Merge branch 'test' into dev

firstleg/src/main/resources/openapi/firstleg-v1.yaml

@@ -94,6 +94,25 @@ paths:
         - {name: sourceVersion, in: query, required: true, schema: {type: integer, minimum: 1}}
       responses:
         '200': {description: 成功时 data 为 FinanceFeeSourceSnapshot；不存在精确版本时返回业务错误}
+  /internal/firstleg/v1/fee-sources/commands/void:
+    post:
+      summary: Finance 发起 Firstleg 业务费用作废
+      description: >-
+        Finance 只发起命令，不修改或伪造业务费用状态。Firstleg 按 sourceType、sourceFeeId、sourceVersion、
+        customerId 和所属入库单/柜次精确校验，原子作废业务费用并写入 FIRSTLEG_FEE_VOIDED Outbox；
+        Finance 后续仅消费该事件同步本地费用池。相同幂等键与请求哈希安全重放，异参重放返回冲突。
+      security:
+        - internalServiceToken: []
+      parameters:
+        - {name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
+        - {name: X-Request-Hash, in: header, required: true, schema: {type: string, pattern: '^[0-9a-f]{64}$'}}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/FinanceFeeSourceVoidCommand'}
+      responses:
+        '200': {description: 成功时 data 为 FinanceFeeSourceCommandResult；业务失败仍按统一响应 code 返回}
   /api/platform/v1/first-leg/customer-dimension-config:
     get:
       summary: 查询客户固定四箱规尺寸配置
@@ -1879,3 +1898,26 @@ components:
         actualVolumeCbm: {type: number, nullable: true}
         sourceHash: {type: string}
         snapshotVersion: {type: integer, minimum: 1}
+    FinanceFeeSourceVoidCommand:
+      type: object
+      additionalProperties: false
+      required: [sourceType, sourceFeeId, sourceVersion, customerId, operatorId, operatorName, reason]
+      properties:
+        sourceType: {type: string, enum: [INBOUND_FEE, CONTAINER_FEE]}
+        sourceFeeId: {type: integer, format: int64, minimum: 1}
+        sourceVersion: {type: integer, minimum: 1}
+        customerId: {type: integer, format: int64, minimum: 1}
+        inboundId: {type: integer, format: int64, minimum: 1, nullable: true, description: INBOUND_FEE必填且containerId必须为空}
+        containerId: {type: integer, format: int64, minimum: 1, nullable: true, description: CONTAINER_FEE必填且inboundId必须为空}
+        operatorId: {type: integer, format: int64, minimum: 1}
+        operatorName: {type: string, minLength: 1, maxLength: 64}
+        reason: {type: string, minLength: 1, maxLength: 500}
+    FinanceFeeSourceCommandResult:
+      type: object
+      required: [sourceType, sourceFeeId, sourceVersion, status, replayed]
+      properties:
+        sourceType: {type: string, enum: [INBOUND_FEE, CONTAINER_FEE]}
+        sourceFeeId: {type: integer, format: int64}
+        sourceVersion: {type: integer}
+        status: {type: string, enum: [VOIDED]}
+        replayed: {type: boolean}