From bd7c955654aa1f3ec456a1358dfebb8c10c16382 Mon Sep 17 00:00:00 2001 From: zhouyonggao <1971162852@qq.com> Date: Fri, 13 Mar 2026 17:49:37 +0800 Subject: [PATCH] =?UTF-8?q?feat(reconciliation):=20=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E5=AF=B9=E8=B4=A6=E6=96=87=E4=BB=B6=E6=9F=A5=E8=AF=A2=E5=8F=8A?= =?UTF-8?q?=E4=B8=8B=E8=BD=BD=E6=8E=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增POST方式的对账文件查询接口，支持按会计日期和文件接口名查询文件列表 - 新增POST方式的对账文件下载接口，支持通过文件ID、接口名和密码下载指定对账文件 - 规范对账文件的命名及格式说明，采用CSV UTF-8-BOM编码 - 增加接口参数及返回字段定义，增强错误场景提示，提升接口安全性及易用性 - 更新相关文档，补充详细接口使用说明、业务规则及测试用例 - 调整旧有对账单下载接口为文件查询和文件下载分离设计，提高接口职责明确度 --- docs/接口文档/openapi.yaml | 256 +++++++++++++++++++++++++++++++------ docs/需求文档-PRD.md | 89 ++++++++++--- 2 files changed, 285 insertions(+), 60 deletions(-) diff --git a/docs/接口文档/openapi.yaml b/docs/接口文档/openapi.yaml index a9ec936..f7e04c1 100644 --- a/docs/接口文档/openapi.yaml +++ b/docs/接口文档/openapi.yaml @@ -9,7 +9,8 @@ info: - 服务取消接口：接收取消请求，作废券码 - 订单过期积分查询接口：查询过期幸福点信息 - 服务详情查询接口：获取券码链接展示服务详情 - - 对账单下载接口：GET方式直接下载对账文件 + - 对账文件查询接口：查询可用的对账文件列表 + - 对账文件下载接口：根据文件ID下载对账文件 - 批量补推接口：手动批量触发服务完成通知 ## 公共响应结构 @@ -412,20 +413,112 @@ paths: msg: "系统异常" traceId: "26031314253001000019" - /api/v1/reconciliation/download: - get: + /api/v1/reconciliation/files: + post: tags: - 对账管理 - summary: 对账单下载接口 + summary: 对账文件查询接口 description: | - 提供GET方式直接下载对账文件，用于管理员或运营人员获取本地处理后的对账数据。 + 查询可用的对账文件列表，用于管理员或运营人员获取本地处理后的对账文件信息。 ## 业务规则 1. 每月3号生成上月服务状态为「服务已完成(300)」的权益订单对账文件 2. 对账月份规则：服务完成时间所在月份为对账月份 - 3. 对账文件名称格式：RIGHTS_SERVICE_CHK_{providerCode}_{reconMonth}.csv - 4. 支持按对账月份查询和下载 - 5. 文件格式为CSV，编码UTF-8-BOM（兼容Excel中文显示） + 3. 对账文件名称格式：RIGHTS_SERVICE_CHK_{providerCode} + 4. 返回文件ID、文件名称等信息 + operationId: queryReconciliationFiles + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ReconciliationFilesRequest' + examples: + normal: + summary: 正常查询请求 + value: + accountingDate: "20251201" + fileIntfcName: "RIGHTS_SERVICE_CHK_A101" + responses: + '200': + description: 查询成功 + content: + application/json: + schema: + $ref: '#/components/schemas/ReconciliationFilesResponse' + examples: + success: + summary: 查询成功 + value: + code: 0 + msg: "成功" + traceId: "26031314253001000020" + data: + fileList: + - fileId: "FILE202512A101001" + fileName: "RIGHTS_SERVICE_CHK_A101_202512.csv" + fileSize: 12560 + createTime: "20260103100000" + emptyResult: + summary: 无对账数据 + value: + code: 0 + msg: "成功" + traceId: "26031314253001000021" + data: + fileList: [] + '400': + description: 参数错误 + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + paramError: + summary: 参数错误 + value: + code: 2 + msg: "参数错误" + traceId: "26031314253001000022" + monthExceed: + summary: 对账月份超过当前月 + value: + code: 4 + msg: "对账月份不能超过上月" + traceId: "26031314253001000023" + fileIntfcNameNotFound: + summary: 文件接口名不存在 + value: + code: 4 + msg: "文件接口名不存在" + traceId: "26031314253001000024" + '500': + description: 系统异常 + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + systemError: + summary: 系统异常 + value: + code: 1 + msg: "系统异常" + traceId: "26031314253001000024" + + /api/v1/reconciliation/download: + post: + tags: + - 对账管理 + summary: 对账文件下载接口 + description: | + 根据文件ID和文件接口名下载对账文件，用于管理员或运营人员获取具体的对账文件内容。 + + ## 业务规则 + 1. 根据文件ID和文件接口名查询对账文件 + 2. 验证下载密码，密码错误拒绝下载 + 3. 文件格式为CSV，编码UTF-8-BOM（兼容Excel中文显示） + 4. 直接返回文件流 ## 对账文件内容字段 | 序号 | 字段名 | 说明 | @@ -441,24 +534,20 @@ paths: | 9 | 权益兑换码 | code字段 | | 10 | 订单号 | order_no | | 11 | 券码状态 | 1-正常，2-已核销，3-已作废，4-已过期 | - operationId: downloadReconciliation - parameters: - - name: reconMonth - in: query - required: true - description: 对账月份，格式：YYYYMM，例如：202512 - schema: - type: string - pattern: '^\d{6}$' - example: "202512" - - name: providerCode - in: query - required: false - description: 服务厂商编号，默认为当前服务商编号，例如：A101 - schema: - type: string - example: "A101" - maxLength: 4 + operationId: downloadReconciliationFile + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ReconciliationDownloadRequest' + examples: + normal: + summary: 正常下载请求 + value: + fileId: "FILE202512A101001" + fileIntfcName: "RIGHTS_SERVICE_CHK_A101" + password: "your_password" responses: '200': description: 下载成功 @@ -474,7 +563,7 @@ paths: type: string example: 'attachment; filename="RIGHTS_SERVICE_CHK_A101_202512.csv"' '400': - description: 参数错误 + description: 参数错误或文件不存在 content: application/json: schema: @@ -485,19 +574,19 @@ paths: value: code: 2 msg: "参数错误" - traceId: "26031314253001000020" - monthExceed: - summary: 对账月份超过当前月 + traceId: "26031314253001000025" + passwordError: + summary: 密码错误 + value: + code: 3 + msg: "密码错误" + traceId: "26031314253001000028" + fileNotFound: + summary: 文件不存在 value: code: 4 - msg: "对账月份不能超过上月" - traceId: "26031314253001000021" - noData: - summary: 无对账数据 - value: - code: 4 - msg: "暂无对账数据" - traceId: "26031314253001000022" + msg: "文件不存在" + traceId: "26031314253001000026" '500': description: 系统异常 content: @@ -510,7 +599,7 @@ paths: value: code: 1 msg: "系统异常" - traceId: "26031314253001000023" + traceId: "26031314253001000027" /api/v1/reconciliation/batch-repush: post: @@ -761,6 +850,49 @@ components: default: false example: false + ReconciliationFilesRequest: + type: object + description: 对账文件查询请求参数 + required: + - accountingDate + - fileIntfcName + properties: + accountingDate: + type: string + description: 会计日期，格式：YYYYMMDD + pattern: '^\d{8}$' + maxLength: 8 + example: "20251201" + fileIntfcName: + type: string + description: 文件接口名，固定值，如：RIGHTS_SERVICE_CHK_A101 + maxLength: 64 + example: "RIGHTS_SERVICE_CHK_A101" + + ReconciliationDownloadRequest: + type: object + description: 对账文件下载请求参数 + required: + - fileId + - fileIntfcName + - password + properties: + fileId: + type: string + description: 文件唯一标识，从查询接口获取 + maxLength: 32 + example: "FILE202512A101001" + fileIntfcName: + type: string + description: 文件接口名，固定值，如：RIGHTS_SERVICE_CHK_A101 + maxLength: 64 + example: "RIGHTS_SERVICE_CHK_A101" + password: + type: string + description: 下载密码，用于验证下载权限 + maxLength: 32 + example: "your_password" + # ============ 响应参数 ============ BaseResponse: type: object @@ -907,6 +1039,52 @@ components: - $ref: '#/components/schemas/BaseResponse' description: 错误响应 + ReconciliationFilesResponse: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + data: + type: object + description: 业务数据 + required: + - fileList + properties: + fileList: + type: array + description: 对账文件列表 + items: + $ref: '#/components/schemas/ReconciliationFileItem' + + ReconciliationFileItem: + type: object + description: 对账文件信息 + required: + - fileId + - fileName + - fileSize + - createTime + properties: + fileId: + type: string + description: 文件唯一标识，用于下载接口 + example: "FILE202512A101001" + maxLength: 32 + fileName: + type: string + description: 文件名称 + example: "RIGHTS_SERVICE_CHK_A101_202512.csv" + maxLength: 64 + fileSize: + type: integer + format: int64 + description: 文件大小（字节） + example: 12560 + createTime: + type: string + description: 文件创建时间 yyyyMMddHHmmss + example: "20260103100000" + BatchRepushResponse: allOf: - $ref: '#/components/schemas/BaseResponse' diff --git a/docs/需求文档-PRD.md b/docs/需求文档-PRD.md index 782e710..0c73c75 100644 --- a/docs/需求文档-PRD.md +++ b/docs/需求文档-PRD.md @@ -733,28 +733,76 @@ --- -#### 3.4.3 对账单下载接口 +#### 3.4.3 对账文件查询接口 -**功能描述**：提供GET方式直接下载对账文件，用于管理员或运营人员获取本地处理后的对账数据 +**功能描述**：查询可用的对账文件列表，用于管理员或运营人员获取本地处理后的对账文件信息 **接口信息**： -- 请求方式：GET -- 接口路径：/api/v1/reconciliation/download +- 请求方式：POST +- 接口路径：/api/v1/reconciliation/files **业务规则**： 1. 每月3号生成上月服务状态为「服务已完成(300)」的权益订单对账文件 2. 对账月份规则：服务完成时间所在月份为对账月份 - 例如：服务完成时间 202512210000，对账月份为 2025年12月，对账文件在 2026年1月3日生成 -3. 对账文件名称格式：`RIGHTS_SERVICE_CHK_{providerCode}_{reconMonth}.csv` - - 例如：`RIGHTS_SERVICE_CHK_A101_202512.csv` -4. 支持按对账月份查询和下载 -5. 文件格式为CSV，内容与邮储对账文件格式一致 +3. 对账文件名称格式：`RIGHTS_SERVICE_CHK_{providerCode}` + - 例如：`RIGHTS_SERVICE_CHK_A101` +4. 返回文件ID、文件名称等信息 **输入**： +| 字段 | 类型 | 长度 | 必填 | 说明 | +|-----|------|-----|-----|------| +| accountingDate | String | 8 | M | 会计日期，格式：YYYYMMDD，例如：20251201 | +| fileIntfcName | String | 64 | M | 文件接口名，固定值，如：RIGHTS_SERVICE_CHK_A101 | + +**输出**（data字段内容）： | 字段 | 类型 | 必填 | 说明 | |-----|------|-----|------| -| reconMonth | String | M | 对账月份，格式：YYYYMM，例如：202512 | -| providerCode | String | C | 服务厂商编号，默认为当前服务商编号，例如：A101 | +| fileList | Object[] | M | 对账文件列表 | +| fileList[].fileId | String | M | 文件唯一标识，用于下载接口 | +| fileList[].fileName | String | M | 文件名称 | +| fileList[].fileSize | long | M | 文件大小（字节） | +| fileList[].createTime | String | M | 文件创建时间 yyyyMMddHHmmss | + +**验收标准**： +- [ ] POST请求能正确查询对账文件列表 +- [ ] accountingDate参数校验：格式必须为YYYYMMDD +- [ ] fileIntfcName参数校验：必须为有效的文件接口名 +- [ ] 返回文件ID、文件名称等完整信息 +- [ ] 对账月份不存在数据时返回空列表 + +**测试用例**： + +| 用例编号 | 测试场景 | 前置条件 | 输入数据 | 预期结果 | +|---------|---------|---------|---------|----------| +| TC-3.4.3-001 | 正常查询对账文件 | 2025年12月有已完成订单 | accountingDate=20251201, fileIntfcName=RIGHTS_SERVICE_CHK_A101 | code=0, 返回文件列表 | +| TC-3.4.3-002 | 会计日期格式错误 | - | accountingDate=2025-12-01 | code=2, msg="参数错误" | +| TC-3.4.3-003 | 文件接口名不存在 | - | fileIntfcName=INVALID_NAME | code=4, msg="文件接口名不存在" | +| TC-3.4.3-004 | 对账月份无数据 | 2025年11月无已完成订单 | accountingDate=20251101 | code=0, fileList=[] | +| TC-3.4.3-005 | 缺少必填参数 | - | 不传accountingDate | code=2, msg="参数错误" | + +--- + +#### 3.4.4 对账文件下载接口 + +**功能描述**：根据文件ID下载对账文件，用于管理员或运营人员获取具体的对账文件内容 + +**接口信息**： +- 请求方式：POST +- 接口路径：/api/v1/reconciliation/download + +**业务规则**： +1. 根据文件ID和文件接口名查询对账文件 +2. 验证下载密码，密码错误拒绝下载 +3. 文件格式为CSV，编码UTF-8-BOM（兼容Excel中文显示） +4. 直接返回文件流 + +**输入**： +| 字段 | 类型 | 长度 | 必填 | 说明 | +|-----|------|-----|-----|------| +| fileId | String | 32 | M | 文件唯一标识，从查询接口获取 | +| fileIntfcName | String | 64 | M | 文件接口名，固定值，如：RIGHTS_SERVICE_CHK_A101 | +| password | String | 32 | M | 下载密码，用于验证下载权限 | **输出**： 直接返回文件流，Content-Type: text/csv，Content-Disposition: attachment; filename="RIGHTS_SERVICE_CHK_A101_202512.csv" @@ -775,27 +823,26 @@ | 11 | 券码状态 | key_status：1-正常，2-已核销，3-已作废，4-已过期 | **验收标准**： -- [ ] GET请求能正确下载对账文件 -- [ ] 对账月份参数校验：格式必须为YYYYMM，且不能超过当前月份 -- [ ] 对账文件只包含status=300(服务已完成)的订单 -- [ ] 对账文件按服务完成时间所在月份归档 +- [ ] POST请求能正确下载对账文件 +- [ ] fileId、fileIntfcName、password都为必填参数 +- [ ] 密码验证失败时返回错误提示 +- [ ] 文件ID不存在时返回错误提示 - [ ] 文件名格式正确：RIGHTS_SERVICE_CHK_{providerCode}_{reconMonth}.csv -- [ ] 对账月份不存在数据时返回空文件或提示"暂无对账数据" - [ ] 文件内容编码为UTF-8-BOM（兼容Excel中文显示） **测试用例**： | 用例编号 | 测试场景 | 前置条件 | 输入数据 | 预期结果 | |---------|---------|---------|---------|----------| -| TC-3.4.3-001 | 正常下载对账文件 | 2025年12月有已完成订单 | reconMonth=202512 | 返回CSV文件流，文件名正确 | -| TC-3.4.3-002 | 对账月份格式错误 | - | reconMonth=2025-12 | code=2, msg="参数错误" | -| TC-3.4.3-003 | 对账月份超过当前月 | 当前为2026年1月 | reconMonth=202602 | code=4, msg="对账月份不能超过上月" | -| TC-3.4.3-004 | 对账月份无数据 | 2025年11月无已完成订单 | reconMonth=202511 | code=4, msg="暂无对账数据" | -| TC-3.4.3-005 | 指定服务商编号 | A101有数据，B101无数据 | reconMonth=202512, providerCode=B101 | code=4, msg="暂无对账数据" | +| TC-3.4.4-001 | 正常下载对账文件 | 文件存在，密码正确 | fileId=有效ID, fileIntfcName=RIGHTS_SERVICE_CHK_A101, password=正确密码 | 返回CSV文件流，文件名正确 | +| TC-3.4.4-002 | 密码错误 | 文件存在 | fileId=有效ID, password=错误密码 | code=3, msg="密码错误" | +| TC-3.4.4-003 | 文件ID不存在 | - | fileId=无效ID | code=4, msg="文件不存在" | +| TC-3.4.4-004 | 文件ID为空 | - | fileId= | code=2, msg="参数错误" | +| TC-3.4.4-005 | 缺少password参数 | - | 不传password | code=2, msg="参数错误" | --- -#### 3.4.4 批量补推接口 +#### 3.4.5 批量补推接口 **功能描述**：手动批量触发服务完成通知，用于处理蓝色兄弟已核销但邮储银行未收到服务完成通知的订单