feat(reconciliation): 新增对账文件查询及下载接口

- 新增POST方式的对账文件查询接口，支持按会计日期和文件接口名查询文件列表 - 新增POST方式的对账文件下载接口，支持通过文件ID、接口名和密码下载指定对账文件 - 规范对账文件的命名及格式说明，采用CSV UTF-8-BOM编码 - 增加接口参数及返回字段定义，增强错误场景提示，提升接口安全性及易用性 - 更新相关文档，补充详细接口使用说明、业务规则及测试用例 - 调整旧有对账单下载接口为文件查询和文件下载分离设计，提高接口职责明确度
2026-03-13 17:49:37 +08:00 · 2026-03-13 17:49:37 +08:00 · bd7c955654
parent d96a8b2a13
commit bd7c955654
2 changed files with 285 additions and 60 deletions
--- 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'
--- 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 批量补推接口

 **功能描述**：手动批量触发服务完成通知，用于处理蓝色兄弟已核销但邮储银行未收到服务完成通知的订单