优化

2026-08-11 13:55:19 +08:00
parent a5b49293ab
commit 863f9ca395
6 changed files with 114 additions and 252 deletions
@@ -1,10 +1,11 @@
 openapi: 3.0.3
 info:
  title: Finance F1 Manual AR API
-  version: 1.1.0
+  version: 1.2.0
  description: >-
    F1 人工账单、收款和成本目标契约。仅 CNY；平台财务可写；客户只读且仅可见
-    ISSUED、PARTIALLY_PAID、PAID 账单。所有响应使用固定 DTO 和统一追踪字段。
+    ISSUED、PARTIALLY_PAID、PAID 账单。固定 DTO、完整追踪字段、真实体积快照和
+    File fail-closed 校验属于放行目标；当前实现差异见契约门禁文档。
 servers:
  - url: /api
 paths:
@@ -203,8 +204,9 @@ paths:
    post:
      summary: 人工登记单票或整柜成本
      description: >-
-        SINGLE_ORDER 直接归属同客户订单；CONTAINER_SHARED 默认按柜内同客户有效票体积分摊，
-        只有总体积为零时才接受 MANUAL_ZERO_VOLUME。
+        SINGLE_ORDER 直接归属经服务端验证的同客户订单；CONTAINER_SHARED 当前请求包含
+        containerOrders 过渡字段，但放行前必须改由服务端从 Firstleg 取得不可篡改体积快照。
+        总体积为零时拒绝，首期不支持人工分摊。
      x-permission: platform:finance:cost:create
      security:
        - platformFinance: []
@@ -221,17 +223,20 @@ paths:
          $ref: '#/components/responses/CostResponse'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
-  /platform/v1/files/finance-vouchers:
+  /platform/finance/v1/vouchers:
    post:
-      summary: 上传财务凭证临时文件
+      summary: 上传财务凭证图片
      description: >-
-        File 服务目标接口。文件上传后为 TEMPORARY，Finance 成功创建收款或成本后通过内部接口幂等关联。
-        临时文件不得直接向客户开放下载。
-      x-permissions:
+        当前 Finance Controller 的真实入口，query 参数为 customerId，multipart 字段为 file。
+        当前 File 仅校验图片 MIME，尚无用途区分和关联状态；收款/成本落库前的 fail-closed
+        校验仍是门禁阻断。
+      x-permission-any-of:
        - platform:finance:receipt:create
        - platform:finance:cost:create
      security:
        - platformFinance: []
+      parameters:
+        - $ref: '#/components/parameters/RequiredCustomerId'
      requestBody:
        required: true
        content:
@@ -279,46 +284,6 @@ paths:
          $ref: '#/components/responses/ClientReceiptListResponse'
        '403':
          $ref: '#/components/responses/BusinessError'
-  /internal/file/v1/finance-vouchers/validate:
-    post:
-      servers:
-        - url: /
-      summary: Finance 批量校验财务凭证
-      description: Finance 落单前同步调用；任一文件不合规则整批失败，Finance 不落业务数据。
-      security:
-        - internalService: []
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/VoucherValidationRequest'
-      responses:
-        '200':
-          $ref: '#/components/responses/VoucherValidationResponse'
-  /internal/file/v1/finance-vouchers/associate:
-    post:
-      servers:
-        - url: /
-      summary: Finance 幂等关联财务凭证
-      description: >-
-        Finance 落单成功后以业务幂等键调用。相同文件、资源类型和资源 ID 重放返回原关联结果；
-        已关联到其他资源时拒绝。调用失败进入 Finance Outbox 重试，不重复创建财务单据。
-      security:
-        - internalService: []
-      parameters:
-        - $ref: '#/components/parameters/IdempotencyKey'
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/VoucherAssociationRequest'
-      responses:
-        '200':
-          $ref: '#/components/responses/VoucherAssociationResponse'
-        '409':
-          $ref: '#/components/responses/IdempotencyConflict'
 components:
  securitySchemes:
    platformFinance:
@@ -327,10 +292,6 @@ components:
    customerFinanceRead:
      type: http
      scheme: bearer
-    internalService:
-      type: apiKey
-      in: header
-      name: X-Internal-Service-Token
  parameters:
    BillId:
      name: billId
@@ -361,6 +322,9 @@ components:
      name: Idempotency-Key
      in: header
      required: true
+      description: >-
+        服务端以 HTTP method、规范化 path、客户范围和完整规范化 JSON body 计算请求哈希。
+        同键同参重放原结果；同键异参冲突；PROCESSING 返回 409 和 Retry-After。
      schema:
        type: string
        minLength: 1
@@ -373,6 +337,10 @@ components:
      type: string
      pattern: '^(0|[1-9][0-9]*)(\.[0-9]{1,6})?$'
      example: '300.000000'
+    SignedMoney:
+      type: string
+      pattern: '^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$'
+      example: '-0.000001'
    ResponseMeta:
      type: object
      required:
@@ -624,7 +592,7 @@ components:
          required:
            - costType
            - containerId
-            - allocationMode
+            - containerOrders
          properties:
            costType:
              type: string
@@ -632,94 +600,38 @@ components:
                - CONTAINER_SHARED
            containerId:
              $ref: '#/components/schemas/Id'
-            allocationMode:
-              type: string
-              enum:
-                - AUTO_VOLUME
-                - MANUAL_ZERO_VOLUME
-              default: AUTO_VOLUME
-            manualAllocations:
+            containerOrders:
              type: array
              minItems: 1
              items:
-                $ref: '#/components/schemas/ManualCostAllocationInput'
-              description: 仅柜内有效票总体积为零且 allocationMode=MANUAL_ZERO_VOLUME 时允许。
-    ManualCostAllocationInput:
+                $ref: '#/components/schemas/ContainerOrderVolumeInput'
+              description: >-
+                当前 Java 过渡请求字段。调用方不得把人工填写体积视为可信快照；放行前应由
+                Finance 根据 containerId 从 Firstleg 获取并校验，届时公开请求应移除此字段。
+    ContainerOrderVolumeInput:
      type: object
      required:
        - orderId
-        - amount
+        - inboundId
+        - containerId
+        - volumeCbm
      properties:
        orderId:
          $ref: '#/components/schemas/Id'
-        amount:
+        inboundId:
+          $ref: '#/components/schemas/Id'
+        containerId:
+          $ref: '#/components/schemas/Id'
+        volumeCbm:
          $ref: '#/components/schemas/Money'
    FinanceVoucherUploadRequest:
      type: object
      required:
-        - customerId
-        - purpose
        - file
      properties:
-        customerId:
-          $ref: '#/components/schemas/Id'
-        purpose:
-          type: string
-          enum:
-            - RECEIPT
-            - COST
        file:
          type: string
          format: binary
-    VoucherValidationRequest:
-      type: object
-      required:
-        - customerId
-        - purpose
-        - fileIds
-      properties:
-        customerId:
-          $ref: '#/components/schemas/Id'
-        purpose:
-          type: string
-          enum:
-            - RECEIPT
-            - COST
-        fileIds:
-          type: array
-          minItems: 1
-          uniqueItems: true
-          items:
-            $ref: '#/components/schemas/Id'
-    VoucherAssociationRequest:
-      type: object
-      required:
-        - customerId
-        - purpose
-        - resourceType
-        - resourceId
-        - fileIds
-      properties:
-        customerId:
-          $ref: '#/components/schemas/Id'
-        purpose:
-          type: string
-          enum:
-            - RECEIPT
-            - COST
-        resourceType:
-          type: string
-          enum:
-            - FINANCE_RECEIPT
-            - FINANCE_COST
-        resourceId:
-          $ref: '#/components/schemas/Id'
-        fileIds:
-          type: array
-          minItems: 1
-          uniqueItems: true
-          items:
-            $ref: '#/components/schemas/Id'
    BillStatus:
      type: string
      enum:
@@ -929,6 +841,7 @@ components:
        - ratio
        - allocatedAmount
        - roundingAdjustment
+        - roundingDelta
      properties:
        orderId:
          $ref: '#/components/schemas/Id'
@@ -942,7 +855,10 @@ components:
        allocatedAmount:
          $ref: '#/components/schemas/Money'
        roundingAdjustment:
-          $ref: '#/components/schemas/Money'
+          type: boolean
+          description: 仅实际尾差非零时为 true。
+        roundingDelta:
+          $ref: '#/components/schemas/SignedMoney'
    Cost:
      type: object
      required:
@@ -977,7 +893,6 @@ components:
          enum:
            - DIRECT
            - AUTO_VOLUME
-            - MANUAL_ZERO_VOLUME
        expenseName:
          type: string
        amount:
@@ -1025,22 +940,14 @@ components:
      required:
        - fileId
        - customerId
-        - purpose
        - fileName
        - contentType
        - sizeBytes
-        - sha256
-        - status
      properties:
        fileId:
          $ref: '#/components/schemas/Id'
        customerId:
          $ref: '#/components/schemas/Id'
-        purpose:
-          type: string
-          enum:
-            - RECEIPT
-            - COST
        fileName:
          type: string
        contentType:
@@ -1049,54 +956,11 @@ components:
            - image/jpeg
            - image/png
            - image/webp
-            - application/pdf
        sizeBytes:
          type: integer
          format: int64
          minimum: 1
          maximum: 10485760
-        sha256:
-          type: string
-          pattern: '^[a-f0-9]{64}$'
-        status:
-          type: string
-          enum:
-            - TEMPORARY
-            - ASSOCIATED
-        resourceType:
-          type: string
-        resourceId:
-          $ref: '#/components/schemas/Id'
-    VoucherValidationResult:
-      type: object
-      required:
-        - valid
-        - files
-      properties:
-        valid:
-          type: boolean
-        files:
-          type: array
-          items:
-            $ref: '#/components/schemas/VoucherFile'
-    VoucherAssociationResult:
-      type: object
-      required:
-        - resourceType
-        - resourceId
-        - files
-      properties:
-        resourceType:
-          type: string
-          enum:
-            - FINANCE_RECEIPT
-            - FINANCE_COST
-        resourceId:
-          $ref: '#/components/schemas/Id'
-        files:
-          type: array
-          items:
-            $ref: '#/components/schemas/VoucherFile'
    ErrorDetail:
      type: object
      required:
@@ -1119,6 +983,12 @@ components:
        code:
          type: string
          example: FIN-AR-002
+          description: >-
+            稳定业务码。体积快照/归属使用 FIN-COST-VOLUME-SNAPSHOT-REQUIRED、
+            FIN-COST-VOLUME-SNAPSHOT-INVALID、FIN-COST-CUSTOMER-MISMATCH、
+            FIN-COST-ORDER-NOT-IN-CONTAINER；凭证使用 FIN-FILE-VALIDATION-UNAVAILABLE、
+            FIN-FILE-CUSTOMER-MISMATCH、FIN-FILE-TYPE-INVALID；幂等使用
+            FIN-IDEMPOTENCY-CONFLICT、FIN-IDEMPOTENCY-PROCESSING。
        message:
          type: string
        details:
@@ -1241,24 +1111,6 @@ components:
            code: {type: string, example: '200'}
            message: {type: string}
            data: {$ref: '#/components/schemas/VoucherFile'}
-    VoucherValidationEnvelope:
-      allOf:
-        - $ref: '#/components/schemas/ResponseMeta'
-        - type: object
-          required: [code, message, data]
-          properties:
-            code: {type: string, example: '200'}
-            message: {type: string}
-            data: {$ref: '#/components/schemas/VoucherValidationResult'}
-    VoucherAssociationEnvelope:
-      allOf:
-        - $ref: '#/components/schemas/ResponseMeta'
-        - type: object
-          required: [code, message, data]
-          properties:
-            code: {type: string, example: '200'}
-            message: {type: string}
-            data: {$ref: '#/components/schemas/VoucherAssociationResult'}
  responses:
    BillListResponse:
      description: 平台账单列表。
@@ -1315,16 +1167,6 @@ components:
      content:
        application/json:
          schema: {$ref: '#/components/schemas/VoucherUploadEnvelope'}
-    VoucherValidationResponse:
-      description: 财务凭证批量校验结果。
-      content:
-        application/json:
-          schema: {$ref: '#/components/schemas/VoucherValidationEnvelope'}
-    VoucherAssociationResponse:
-      description: 财务凭证关联结果。
-      content:
-        application/json:
-          schema: {$ref: '#/components/schemas/VoucherAssociationEnvelope'}
    BusinessError:
      description: 业务错误。
      content: