fix(dropship): generate pallet numbers atomically and extend full regressions

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

@@ -1,45 +1,371 @@
 openapi: 3.0.3
-info: { title: Firstleg Container Fee Allocation API, version: 1.0.0 }
+info:
+  title: Firstleg Container Fee API
+  version: 1.0.0
+  description: |
+    本契约只生产国内段费用来源（订舱、国内拖车、出口报关、海运等）。
+    loadingPlanId 由服务端解析到同一真实 containerBookingId；海外段费用由 Lastleg 的 OVERSEAS_CONTAINER_FEE 独立维护。
+    审核通过后发布不可变来源版本到 Finance，不复制海外费用或财务状态。
+    应付必须选择有效供应商；DIRECT_PAID 是已付快照，不再进入待结算。
+    当前币种仅支持 CNY，不进行跨币种加总。公共费用按柜内真实客户与订单分摊，
+    各行按 HALF_UP 保留两位后必须大于零，落库金额合计必须等于两位小数的总额。
+    成功和业务错误均使用 HTTP 200 包装，业务冲突 code 为 A0409。
+security: [{bearerAuth: []}]
 paths:
+  /api/platform/v1/loading-plans/{loadingPlanId}/fee-details:
+    get:
+      operationId: listContainerFees
+      summary: 查询当前客户的国内段柜级费用
+      x-permission: firstleg:inbound:fee-detail:view
+      parameters:
+        - {$ref: '#/components/parameters/LoadingPlanId'}
+        - {$ref: '#/components/parameters/AccountId'}
+      responses:
+        '200':
+          description: 通过 code 区分成功与业务失败；分摊组不可经单行入口修改。
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/FeeListResponse'}
+    post:
+      operationId: createContainerFee
+      summary: 创建单一业务归属的国内段柜级费用
+      x-permission: firstleg:inbound:fee-detail:edit
+      parameters:
+        - {$ref: '#/components/parameters/LoadingPlanId'}
+        - {$ref: '#/components/parameters/AccountId'}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/SaveRequest'}
+      responses:
+        '200':
+          description: 通过 code 区分成功与业务失败；分摊组不可经单行入口修改。
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/FeeResponse'}
   /api/platform/v1/loading-plans/{loadingPlanId}/fee-details/allocation-groups:
     post:
-      summary: 原子创建柜级公共费用分摊组
-      description: 客户、订单必填；入仓ID与入仓码同时填写或同时留空。各分摊金额必须大于0且合计等于费用总额。
-      security: [{ bearerAuth: [] }]
-      parameters: [{ $ref: '#/components/parameters/LoadingPlanId' }]
-      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/AllocationGroupRequest' } } } }
-      responses: { '200': { description: 按客户和业务归属生成的待审核费用行 }, '409': { description: 分摊合计或柜内真实归属不一致 } }
-  /api/platform/v1/loading-plans/{loadingPlanId}/fee-details/allocation-groups/{groupId}/{action}:
-    post:
-      summary: 整组审核、驳回、调整或作废柜级分摊费用
-      description: action 仅为 approve、reject、adjust、void；单行接口拒绝处理分摊组，避免部分成功。
-      security: [{ bearerAuth: [] }]
+      operationId: createContainerFeeAllocationGroup
+      summary: 原子创建国内段柜级公共费用分摊组
+      x-permission: firstleg:inbound:fee-detail:edit
       parameters:
-        - { $ref: '#/components/parameters/LoadingPlanId' }
-        - { in: path, name: groupId, required: true, schema: { type: string, pattern: '^[1-9][0-9]{0,19}$' } }
-        - { in: path, name: action, required: true, schema: { type: string, enum: [approve, reject, adjust, void] } }
-      responses: { '200': { description: 整组处理成功 }, '409': { description: 版本、状态或完整性冲突 } }
+        - {$ref: '#/components/parameters/LoadingPlanId'}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/AllocationGroupRequest'}
+      responses:
+        '200':
+          description: 通过 code 区分成功与业务失败；分摊组不可经单行入口修改。
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/FeeListResponse'}
+  /api/platform/v1/loading-plans/{loadingPlanId}/fee-details/allocation-groups/{groupId}/approve:
+    post:
+      operationId: approveContainerFeeAllocationGroup
+      summary: 整组审核国内段柜级费用
+      x-permission: firstleg:inbound:fee-detail:review
+      parameters:
+        - {$ref: '#/components/parameters/LoadingPlanId'}
+        - {$ref: '#/components/parameters/GroupId'}
+      responses:
+        '200':
+          description: 通过 code 区分成功与业务失败；分摊组不可经单行入口修改。
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/FeeListResponse'}
+  /api/platform/v1/loading-plans/{loadingPlanId}/fee-details/allocation-groups/{groupId}/reject:
+    post:
+      operationId: rejectContainerFeeAllocationGroup
+      summary: 整组驳回国内段柜级费用
+      x-permission: firstleg:inbound:fee-detail:review
+      parameters:
+        - {$ref: '#/components/parameters/LoadingPlanId'}
+        - {$ref: '#/components/parameters/GroupId'}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/RejectRequest'}
+      responses:
+        '200':
+          description: 通过 code 区分成功与业务失败；分摊组不可经单行入口修改。
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/FeeListResponse'}
+  /api/platform/v1/loading-plans/{loadingPlanId}/fee-details/allocation-groups/{groupId}/adjust:
+    post:
+      operationId: adjustContainerFeeAllocationGroup
+      summary: 整组调整国内段柜级费用
+      x-permission: firstleg:inbound:fee-detail:edit
+      parameters:
+        - {$ref: '#/components/parameters/LoadingPlanId'}
+        - {$ref: '#/components/parameters/GroupId'}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/AllocationGroupAdjustRequest'}
+      responses:
+        '200':
+          description: 通过 code 区分成功与业务失败；分摊组不可经单行入口修改。
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/FeeListResponse'}
+  /api/platform/v1/loading-plans/{loadingPlanId}/fee-details/allocation-groups/{groupId}/void:
+    post:
+      operationId: voidContainerFeeAllocationGroup
+      summary: 整组作废国内段柜级费用
+      x-permission: firstleg:inbound:fee-detail:review
+      parameters:
+        - {$ref: '#/components/parameters/LoadingPlanId'}
+        - {$ref: '#/components/parameters/GroupId'}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/VersionRequest'}
+      responses:
+        '200':
+          description: 通过 code 区分成功与业务失败；分摊组不可经单行入口修改。
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/EmptyResponse'}
+  /api/platform/v1/loading-plans/{loadingPlanId}/fee-details/{feeId}/approve:
+    post:
+      operationId: approveContainerFee
+      summary: 审核单行国内段柜级费用
+      x-permission: firstleg:inbound:fee-detail:review
+      parameters:
+        - {$ref: '#/components/parameters/LoadingPlanId'}
+        - {$ref: '#/components/parameters/AccountId'}
+        - {$ref: '#/components/parameters/FeeId'}
+      responses:
+        '200':
+          description: 通过 code 区分成功与业务失败；分摊组不可经单行入口修改。
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/EmptyResponse'}
+  /api/platform/v1/loading-plans/{loadingPlanId}/fee-details/{feeId}/reject:
+    post:
+      operationId: rejectContainerFee
+      summary: 驳回单行国内段柜级费用
+      x-permission: firstleg:inbound:fee-detail:review
+      parameters:
+        - {$ref: '#/components/parameters/LoadingPlanId'}
+        - {$ref: '#/components/parameters/AccountId'}
+        - {$ref: '#/components/parameters/FeeId'}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/RejectRequest'}
+      responses:
+        '200':
+          description: 通过 code 区分成功与业务失败；分摊组不可经单行入口修改。
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/EmptyResponse'}
+  /api/platform/v1/loading-plans/{loadingPlanId}/fee-details/{feeId}/adjust:
+    post:
+      operationId: adjustContainerFee
+      summary: 调整单行国内段柜级费用
+      x-permission: firstleg:inbound:fee-detail:edit
+      parameters:
+        - {$ref: '#/components/parameters/LoadingPlanId'}
+        - {$ref: '#/components/parameters/AccountId'}
+        - {$ref: '#/components/parameters/FeeId'}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/AdjustRequest'}
+      responses:
+        '200':
+          description: 通过 code 区分成功与业务失败；分摊组不可经单行入口修改。
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/FeeResponse'}
+  /api/platform/v1/loading-plans/{loadingPlanId}/fee-details/{feeId}/void:
+    post:
+      operationId: voidContainerFee
+      summary: 作废单行国内段柜级费用
+      x-permission: firstleg:inbound:fee-detail:review
+      parameters:
+        - {$ref: '#/components/parameters/LoadingPlanId'}
+        - {$ref: '#/components/parameters/AccountId'}
+        - {$ref: '#/components/parameters/FeeId'}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/VersionRequest'}
+      responses:
+        '200':
+          description: 通过 code 区分成功与业务失败；分摊组不可经单行入口修改。
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/EmptyResponse'}
 components:
+  securitySchemes:
+    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
   parameters:
-    LoadingPlanId: { in: path, name: loadingPlanId, required: true, schema: { type: string, pattern: '^[1-9][0-9]{0,19}$' } }
+    LoadingPlanId: {in: path, name: loadingPlanId, required: true, schema: {$ref: '#/components/schemas/Id'}}
+    GroupId: {in: path, name: groupId, required: true, schema: {$ref: '#/components/schemas/Id'}}
+    FeeId: {in: path, name: feeId, required: true, schema: {$ref: '#/components/schemas/Id'}}
+    AccountId: {in: query, name: accountId, required: true, schema: {type: integer, format: int64, minimum: 1}, description: 平台选择的客户，服务端校验柜内归属}
   schemas:
+    Id: {type: string, pattern: '^[1-9][0-9]{0,19}$'}
+    Amount: {type: number, format: decimal, minimum: 0, description: HALF_UP 保留两位小数}
+    SaveRequest:
+      type: object
+      required: [feeItemId, direction, businessDate, amount, currency]
+      properties:
+        feeItemId: {$ref: '#/components/schemas/Id'}
+        direction: {type: string, enum: [RECEIVABLE, PAYABLE]}
+        businessDate: {type: string, format: date}
+        amount: {$ref: '#/components/schemas/Amount'}
+        currency: {type: string, enum: [CNY]}
+        supplierId: {type: string, nullable: true, description: PAYABLE 必填，必须为启用供应商}
+        settlementMode: {type: string, enum: [ON_ACCOUNT, DIRECT_PAID], nullable: true, description: 仅 PAYABLE 必填}
+        paidAt: {type: string, format: date-time, nullable: true}
+        paymentMethod: {type: string, enum: [ONLINE, BANK_TRANSFER, CASH, OTHER], nullable: true}
+        paymentReferenceNo: {type: string, maxLength: 128, nullable: true}
+        paymentVoucherFileIds:
+          type: array
+          maxItems: 20
+          nullable: true
+          items: {$ref: '#/components/schemas/Id'}
+        remark: {type: string, maxLength: 500, nullable: true}
+      description: DIRECT_PAID 必须填写付款时间、方式及流水号或当前客户凭证；RECEIVABLE 和 ON_ACCOUNT 不允许残留付款字段。
+    Allocation:
+      type: object
+      required: [customerId, orderId, orderNo, amount]
+      properties:
+        customerId: {$ref: '#/components/schemas/Id'}
+        orderId: {$ref: '#/components/schemas/Id'}
+        orderNo: {type: string, minLength: 1, maxLength: 64}
+        inboundId: {type: string, nullable: true}
+        inboundCode: {type: string, maxLength: 64, nullable: true}
+        amount: {type: number, format: decimal, minimum: 0, exclusiveMinimum: true}
+      description: 客户和订单必须属于当前柜；入仓ID与入仓码同时填写或同时留空。
     AllocationGroupRequest:
       type: object
       required: [fee, allocations]
       properties:
-        fee: { type: object, description: 公共费用字段；amount为原始柜级总额 }
+        fee: {$ref: '#/components/schemas/SaveRequest'}
         allocations:
           type: array
           minItems: 1
           maxItems: 200
-          items:
-            type: object
-            required: [customerId, orderId, orderNo, amount]
-            properties:
-              customerId: { type: string }
-              orderId: { type: string }
-              orderNo: { type: string, maxLength: 64 }
-              inboundId: { type: string, nullable: true }
-              inboundCode: { type: string, maxLength: 64, nullable: true }
-              amount: { type: number, format: decimal, exclusiveMinimum: 0 }
-  securitySchemes: { bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT } }
+          items: {$ref: '#/components/schemas/Allocation'}
+    AdjustRequest:
+      type: object
+      required: [expectedSourceVersion, businessDate, amount]
+      properties:
+        expectedSourceVersion: {type: integer, minimum: 1}
+        businessDate: {type: string, format: date}
+        amount: {$ref: '#/components/schemas/Amount'}
+      description: 只允许调整当前已审核有效版本，成功递增来源版本并重新待审核。
+    AllocationAmount:
+      type: object
+      required: [feeId, amount]
+      properties:
+        feeId: {$ref: '#/components/schemas/Id'}
+        amount: {type: number, format: decimal, minimum: 0, exclusiveMinimum: true}
+    AllocationGroupAdjustRequest:
+      type: object
+      required: [expectedSourceVersion, businessDate, totalAmount, allocations]
+      properties:
+        expectedSourceVersion: {type: integer, minimum: 1}
+        businessDate: {type: string, format: date}
+        totalAmount: {type: number, format: decimal, minimum: 0, exclusiveMinimum: true}
+        allocations:
+          type: array
+          minItems: 1
+          maxItems: 200
+          items: {$ref: '#/components/schemas/AllocationAmount'}
+      description: 必须包含整组全部费用行，逐行取两位后的合计与总额一致；成功后整组重新待审核。
+    VersionRequest:
+      type: object
+      required: [expectedSourceVersion]
+      properties:
+        expectedSourceVersion: {type: integer, minimum: 1}
+    RejectRequest:
+      type: object
+      required: [reason]
+      properties:
+        reason: {type: string, minLength: 1, maxLength: 500}
+    FeeDetail:
+      type: object
+      properties:
+        id: {type: string, nullable: true}
+        tenantId: {type: string, nullable: true}
+        allocationGroupId: {type: string, nullable: true}
+        allocationOrderId: {type: string, nullable: true}
+        allocationInboundId: {type: string, nullable: true}
+        loadingPlanId: {type: string, nullable: true}
+        containerBookingId: {type: string, nullable: true}
+        feeItemId: {type: string, nullable: true}
+        supplierId: {type: string, nullable: true}
+        reviewerId: {type: string, nullable: true}
+        createdBy: {type: string, nullable: true}
+        updatedBy: {type: string, nullable: true}
+        allocationOrderNo: {type: string, nullable: true}
+        allocationInboundCode: {type: string, nullable: true}
+        containerNo: {type: string, nullable: true}
+        feeItemCodeSnapshot: {type: string, nullable: true}
+        feeItemNameSnapshot: {type: string, nullable: true}
+        supplierName: {type: string, nullable: true}
+        supplierCategory: {type: string, nullable: true}
+        remark: {type: string, nullable: true}
+        reviewerName: {type: string, nullable: true}
+        reviewReason: {type: string, nullable: true}
+        paymentReferenceNo: {type: string, nullable: true}
+        paidAt: {type: string, format: date-time, nullable: true}
+        reviewedAt: {type: string, format: date-time, nullable: true}
+        createdAt: {type: string, format: date-time, nullable: true}
+        updatedAt: {type: string, format: date-time, nullable: true}
+        amount: {$ref: '#/components/schemas/Amount'}
+        allocationGroupAmount: {$ref: '#/components/schemas/Amount'}
+        businessDate: {type: string, format: date}
+        currency: {type: string, enum: [CNY]}
+        direction: {type: string, enum: [RECEIVABLE, PAYABLE]}
+        reviewStatus: {type: string, enum: [PENDING, APPROVED, REJECTED]}
+        sourceStatus: {type: string, enum: [ACTIVE, VOIDED]}
+        sourceVersion: {type: integer, minimum: 1}
+        settlementMode: {type: string, enum: [ON_ACCOUNT, DIRECT_PAID], nullable: true}
+        paymentMethod: {type: string, enum: [ONLINE, BANK_TRANSFER, CASH, OTHER], nullable: true}
+        paymentVoucherFileIds: {type: array, nullable: true, items: {$ref: '#/components/schemas/Id'}}
+    FeeResponse:
+      type: object
+      required: [code, message]
+      properties:
+        code: {type: string, description: 成功为200，业务冲突为A0409}
+        message: {type: string}
+        requestId: {type: string, nullable: true}
+        traceId: {type: string, nullable: true}
+        data: {$ref: '#/components/schemas/FeeDetail'}
+        timestamp: {type: string, format: date-time}
+    FeeListResponse:
+      type: object
+      required: [code, message]
+      properties:
+        code: {type: string, description: 成功为200，业务冲突为A0409}
+        message: {type: string}
+        requestId: {type: string, nullable: true}
+        traceId: {type: string, nullable: true}
+        data: {type: array, items: {$ref: '#/components/schemas/FeeDetail'}}
+        timestamp: {type: string, format: date-time}
+    EmptyResponse:
+      type: object
+      required: [code, message]
+      properties:
+        code: {type: string, description: 成功为200，业务冲突为A0409}
+        message: {type: string}
+        requestId: {type: string, nullable: true}
+        traceId: {type: string, nullable: true}
+        data: {type: object, nullable: true}
+        timestamp: {type: string, format: date-time}

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

@@ -46,6 +46,14 @@ paths:
       parameters: [{$ref: '#/components/parameters/TaskId'}]
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/BindPendingRequest'}}}}
       responses: {'200': {description: OK}}
+  /api/platform/v1/first-leg/pda-dropship/tasks/{taskId}/pallets/create-and-bind:
+    post:
+      summary: 系统生成 DP 托盘码并原子绑定全部待绑箱
+      description: 仅当前仓库本人已领取的待组托任务可执行。没有待绑箱时不发码、不建空托。operationId 在同任务和仓库重放不重复创建；不同任务使用同幂等号拒绝。返回当前 Task。
+      x-required-authority: platform:firstleg:pda:work
+      parameters: [{$ref: '#/components/parameters/TaskId'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateAndBindRequest'}}}}
+      responses: {'200': {description: Task}}
   /api/platform/v1/first-leg/pda-dropship/tasks/{taskId}/cartons/{cartonId}/move:
     post:
       summary: 换托，targetPalletNo 为空时退回待绑区
@@ -150,4 +158,10 @@ components:
         expectedVersion: {type: integer, minimum: 1}
         operationId: {type: string, maxLength: 128}
     PalletNo: {type: string, pattern: '^DP-[0-9]{6}-[0-9]{4}$'}
+    CreateAndBindRequest:
+      type: object
+      required: [warehouseId, operationId]
+      properties:
+        warehouseId: {type: integer, format: int64, minimum: 1}
+        operationId: {type: string, minLength: 1, maxLength: 128}
     NullablePalletNo: {type: string, pattern: '^DP-[0-9]{6}-[0-9]{4}$', nullable: true}

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

@@ -32,7 +32,7 @@ paths:
   /api/platform/v1/ocean-bookings/{oceanBookingId}/release:
     post:
       summary: Validate and permanently release a DRAFT
-      description: Release validates the persisted aggregate plus at least one active booking-owned BOOKING_CONFIRMATION or BILL_OF_LADING file. It never requires or creates a real container number.
+      description: Release validates the persisted aggregate plus at least one active booking-owned BOOKING_CONFIRMATION or BILL_OF_LADING file. The customer is optional; a supplied customer must remain ACTIVE. Null denotes no single customer snapshot, never public access. It never requires or creates a real container number.
       parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ReleaseRequest'}}}}
       responses: {'200': {description: RELEASED detail}}
@@ -45,7 +45,7 @@ paths:
         '200': {description: Booking document history, content: {application/json: {schema: {$ref: '#/components/schemas/DocumentListResponse'}}}}
     post:
       summary: Reference an existing File object in a DRAFT booking
-      description: File scope must be customerId + OCEAN_BOOKING_DOCUMENT + oceanBookingId. The booking version is incremented atomically.
+      description: File scope must be platform tenantId=0 + OCEAN_BOOKING_DOCUMENT + oceanBookingId, independent of the optional customer snapshot. The booking version is incremented atomically.
       x-permission: platform:firstleg:ocean-booking:edit
       parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/DocumentRequest'}}}}
@@ -162,8 +162,8 @@ components:
       type: object
       description: Fields may be incomplete in DRAFT. RELEASE validates the complete persisted aggregate.
       properties:
-        customerId: {type: integer, format: int64, nullable: true}
-        customerName: {type: string, nullable: true}
+        customerId: {type: integer, format: int64, minimum: 1, nullable: true, description: 可选启用客户ID；多客户订舱留空，空值不是公开访问授权}
+        customerName: {type: string, nullable: true, description: 可选名称提示；有客户ID时由服务端校验并保存客户主数据名称，清空客户时同时置null}
         channelCode: {type: string, nullable: true}
         warehouseId: {type: integer, format: int64, nullable: true}
         billOfLadingNo: {type: string, nullable: true}
@@ -279,7 +279,7 @@ components:
         requiredQuantity: {type: integer, minimum: 1}
         allocatedQuantity: {type: integer, format: int64, minimum: 0}
         remainingQuantity: {type: integer, format: int64, minimum: 1}
-        customerName: {type: string}
+        customerName: {type: string, nullable: true}
         warehouseName: {type: string}
         channelName: {type: string}
     LinkCandidatePage:

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

@@ -77,7 +77,7 @@ components:
       properties:
         expectedVersion: {type: integer, minimum: 0}
         actualAt: {type: string, format: date-time}
-        reason: {type: string, maxLength: 500, nullable: true}
+        remark: {type: string, maxLength: 500, nullable: true}
     Warning:
       type: object
       required: [status, overdueHours, overdueDays]