提交

2026-08-06 15:48:21 +08:00
parent 4df8b8c355
commit c3a978b497
71 changed files with 6268 additions and 13 deletions
@@ -0,0 +1,340 @@
+openapi: 3.0.3
+info:
+  title: 头程装柜与完成装柜清单接口
+  version: 1.0.0
+  description: 装柜计划仅允许 EDITING 到 LOADING 再到 COMPLETED 单向推进；EDITING 和 LOADING 均可维护未拣货明细，COMPLETED 后计划、明细与货柜运输信息永久只读，不提供回退或撤回接口。
+paths:
+  /api/platform/v1/first-leg/loading-plans:
+    get:
+      summary: 分页查询预装清单
+      description: 仅返回预装柜中或预装柜完成的计划，计划为平台作业数据，客户账号仅作为明细筛选条件。
+      x-permission: platform:firstleg:preload:list
+      parameters:
+        - {$ref: '#/components/parameters/Page'}
+        - {$ref: '#/components/parameters/Size'}
+        - {$ref: '#/components/parameters/Keyword'}
+        - name: status
+          in: query
+          description: 预装状态
+          schema: {type: string, enum: [LOADING]}
+        - {$ref: '#/components/parameters/AccountId'}
+        - {$ref: '#/components/parameters/WarehouseId'}
+        - {$ref: '#/components/parameters/CreatedFrom'}
+        - {$ref: '#/components/parameters/CreatedTo'}
+      responses:
+        '200': {$ref: '#/components/responses/PreloadPageResponse'}
+  /api/platform/v1/first-leg/loading-plans/{planId}:
+    get:
+      summary: 查询预装清单详情
+      description: 返回同一装柜计划的汇总、冻结明细和完整操作历史。
+      x-permission: platform:firstleg:preload:view
+      parameters: [{$ref: '#/components/parameters/PlanId'}]
+      responses:
+        '200': {$ref: '#/components/responses/PreloadDetailResponse'}
+  /api/platform/v1/first-leg/loading-plans/{planId}/transport:
+    patch:
+      summary: 修改预装运输信息
+      description: 仅 LOADING 状态允许修改集装箱号与航次；装柜中可以维护未拣货明细。
+      x-permission: platform:firstleg:preload:edit
+      parameters:
+        - {$ref: '#/components/parameters/PlanId'}
+        - {$ref: '#/components/parameters/IdempotencyKey'}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/TransportUpdateRequest'}
+      responses:
+        '200': {$ref: '#/components/responses/PreloadDetailResponse'}
+  /api/platform/v1/first-leg/loading-plans/{planId}/complete:
+    post:
+      summary: 完成预装
+      description: 仅允许将 LOADING 单向推进为 COMPLETED；完成前必须完成全部 PDA 拣货。
+      x-permission: platform:firstleg:preload:complete
+      parameters:
+        - {$ref: '#/components/parameters/PlanId'}
+        - {$ref: '#/components/parameters/IdempotencyKey'}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/AdvanceRequest'}
+      responses:
+        '200': {$ref: '#/components/responses/PreloadDetailResponse'}
+  /api/platform/v1/first-leg/loading-lists:
+    get:
+      summary: 分页查询装柜清单
+      description: 读取同一个装柜计划聚合，仅返回 COMPLETED 状态记录。
+      x-permission: platform:firstleg:loading-list:list
+      parameters:
+        - {$ref: '#/components/parameters/Page'}
+        - {$ref: '#/components/parameters/Size'}
+        - {$ref: '#/components/parameters/Keyword'}
+        - {$ref: '#/components/parameters/AccountId'}
+        - {$ref: '#/components/parameters/WarehouseId'}
+        - {$ref: '#/components/parameters/CreatedFrom'}
+        - {$ref: '#/components/parameters/CreatedTo'}
+      responses:
+        '200': {$ref: '#/components/responses/ConfirmedPageResponse'}
+  /api/platform/v1/first-leg/loading-lists/{planId}:
+    get:
+      summary: 查询装柜清单详情
+      description: 返回已确认计划的汇总、冻结明细和操作历史，全部只读。
+      x-permission: platform:firstleg:loading-list:view
+      parameters: [{$ref: '#/components/parameters/PlanId'}]
+      responses:
+        '200': {$ref: '#/components/responses/ConfirmedDetailResponse'}
+components:
+  parameters:
+    PlanId:
+      name: planId
+      in: path
+      required: true
+      description: 装柜计划 ID
+      schema: {$ref: '#/components/schemas/LongId'}
+    IdempotencyKey:
+      name: Idempotency-Key
+      in: header
+      required: true
+      description: 写操作幂等键，同一业务操作重试时必须保持不变
+      schema: {type: string, minLength: 1, maxLength: 128}
+    Page:
+      name: page
+      in: query
+      description: 页码，从 1 开始
+      schema: {type: integer, format: int64, minimum: 1, default: 1}
+    Size:
+      name: size
+      in: query
+      description: 每页条数
+      schema: {type: integer, format: int64, minimum: 1, maximum: 200, default: 20}
+    Keyword:
+      name: keyword
+      in: query
+      description: 按预装单号、集装箱号或柜号模糊查询
+      schema: {type: string, maxLength: 128}
+    AccountId:
+      name: accountId
+      in: query
+      description: 客户账号 ID 筛选条件，计划本身仍属于平台作业数据
+      schema: {$ref: '#/components/schemas/LongId'}
+    WarehouseId:
+      name: warehouseId
+      in: query
+      description: 仓库 ID
+      schema: {$ref: '#/components/schemas/LongId'}
+    CreatedFrom:
+      name: createdFrom
+      in: query
+      description: 创建时间起点，包含该时间
+      schema: {type: string, format: date-time}
+    CreatedTo:
+      name: createdTo
+      in: query
+      description: 创建时间终点，包含该时间
+      schema: {type: string, format: date-time}
+  responses:
+    PreloadPageResponse:
+      description: 预装清单分页查询成功或业务失败，按响应体 code 判断
+      content: {application/json: {schema: {$ref: '#/components/schemas/PreloadPageEnvelope'}}}
+    PreloadDetailResponse:
+      description: 预装清单详情查询或操作成功，也可能返回业务失败
+      content: {application/json: {schema: {$ref: '#/components/schemas/PreloadDetailEnvelope'}}}
+    ConfirmedPageResponse:
+      description: 装柜清单分页查询成功或业务失败，按响应体 code 判断
+      content: {application/json: {schema: {$ref: '#/components/schemas/ConfirmedPageEnvelope'}}}
+    ConfirmedDetailResponse:
+      description: 装柜清单详情查询或确认成功，也可能返回业务失败
+      content: {application/json: {schema: {$ref: '#/components/schemas/ConfirmedDetailEnvelope'}}}
+  schemas:
+    LongId:
+      type: string
+      pattern: '^[1-9][0-9]*$'
+      example: '1900000000000000001'
+      description: 长整型 ID，JSON 中使用字符串避免前端精度丢失
+    NullableLongId:
+      allOf: [{$ref: '#/components/schemas/LongId'}]
+      nullable: true
+    ApiEnvelope:
+      type: object
+      required: [code, message, timestamp]
+      properties:
+        code: {type: string, description: 业务结果码，仅字符串 200 表示成功, example: '200'}
+        message: {type: string, description: 结果说明}
+        requestId: {type: string, nullable: true, description: 请求标识}
+        traceId: {type: string, nullable: true, description: 链路标识}
+        timestamp: {type: string, format: date-time, description: 服务端响应时间}
+    PreloadPageEnvelope:
+      allOf:
+        - {$ref: '#/components/schemas/ApiEnvelope'}
+        - type: object
+          properties:
+            data:
+              allOf: [{$ref: '#/components/schemas/PreloadPage'}]
+              nullable: true
+    PreloadDetailEnvelope:
+      allOf:
+        - {$ref: '#/components/schemas/ApiEnvelope'}
+        - type: object
+          properties:
+            data:
+              allOf: [{$ref: '#/components/schemas/PreloadDetail'}]
+              nullable: true
+    ConfirmedPageEnvelope:
+      allOf:
+        - {$ref: '#/components/schemas/ApiEnvelope'}
+        - type: object
+          properties:
+            data:
+              allOf: [{$ref: '#/components/schemas/ConfirmedPage'}]
+              nullable: true
+    ConfirmedDetailEnvelope:
+      allOf:
+        - {$ref: '#/components/schemas/ApiEnvelope'}
+        - type: object
+          properties:
+            data:
+              allOf: [{$ref: '#/components/schemas/ConfirmedDetail'}]
+              nullable: true
+    PreloadPage:
+      type: object
+      required: [records, page, size, total, pages]
+      properties:
+        records: {type: array, items: {$ref: '#/components/schemas/PreloadSummary'}}
+        page: {type: string, pattern: '^[1-9][0-9]*$', description: 当前页码}
+        size: {type: string, pattern: '^[1-9][0-9]*$', description: 每页条数}
+        total: {type: string, pattern: '^[0-9]+$', description: 总记录数}
+        pages: {type: string, pattern: '^[0-9]+$', description: 总页数}
+    ConfirmedPage:
+      type: object
+      required: [records, page, size, total, pages]
+      properties:
+        records: {type: array, items: {$ref: '#/components/schemas/ConfirmedSummary'}}
+        page: {type: string, pattern: '^[1-9][0-9]*$', description: 当前页码}
+        size: {type: string, pattern: '^[1-9][0-9]*$', description: 每页条数}
+        total: {type: string, pattern: '^[0-9]+$', description: 总记录数}
+        pages: {type: string, pattern: '^[0-9]+$', description: 总页数}
+    Customer:
+      type: object
+      required: [accountId, customerName]
+      properties:
+        accountId: {$ref: '#/components/schemas/LongId'}
+        customerName: {type: string, nullable: true, description: 客户名称}
+    PreloadSummary:
+      type: object
+      required: [planId, preloadNo, customers, status, skuCount, totalPackageCount, totalVolumeCbm, totalGrossWeightKg, createdAt, version]
+      properties:
+        planId: {$ref: '#/components/schemas/LongId'}
+        preloadNo: {type: string, description: 预装单号}
+        containerNo: {type: string, nullable: true, description: 集装箱号}
+        internalContainerNo: {type: string, nullable: true, description: 内部柜号}
+        customers: {type: array, description: 计划包含的客户, items: {$ref: '#/components/schemas/Customer'}}
+        warehouseId: {$ref: '#/components/schemas/NullableLongId'}
+        warehouseName: {type: string, nullable: true, description: 仓库名称}
+        vesselName: {type: string, nullable: true, description: 船名}
+        voyageNo: {type: string, nullable: true, description: 航次}
+        containerType: {type: string, nullable: true, description: 货柜类型}
+        status: {type: string, enum: [LOADING], description: 装柜状态}
+        skuCount: {type: string, pattern: '^[0-9]+$', description: SKU 种类数}
+        totalPackageCount: {type: string, pattern: '^[0-9]+$', description: 总箱数}
+        totalVolumeCbm: {type: number, description: 总体积，单位立方米}
+        totalGrossWeightKg: {type: number, description: 总毛重，单位千克}
+        createdAt: {type: string, format: date-time, description: 创建时间}
+        version: {type: integer, format: int32, minimum: 0, description: 乐观锁版本}
+    ConfirmedSummary:
+      type: object
+      required: [planId, loadingListNo, status, totalPackageCount, totalGrossWeightKg, totalNetWeightKg, totalVolumeCbm, totalQuantity, createdAt, version]
+      properties:
+        planId: {$ref: '#/components/schemas/LongId'}
+        loadingListNo: {type: string, description: 装柜清单号}
+        warehouseId: {$ref: '#/components/schemas/NullableLongId'}
+        warehouseName: {type: string, nullable: true, description: 仓库名称}
+        containerNo: {type: string, nullable: true, description: 集装箱号}
+        internalContainerNo: {type: string, nullable: true, description: 内部柜号}
+        status: {type: string, enum: [COMPLETED], description: 装柜清单状态}
+        totalPackageCount: {type: string, pattern: '^[0-9]+$', description: 总箱数}
+        totalGrossWeightKg: {type: number, description: 总毛重，单位千克}
+        totalNetWeightKg: {type: number, description: 总净重，单位千克}
+        totalVolumeCbm: {type: number, description: 总体积，单位立方米}
+        totalQuantity: {type: string, pattern: '^[0-9]+$', description: 产品总数量}
+        remark: {type: string, nullable: true, description: 备注}
+        createdBy: {$ref: '#/components/schemas/NullableLongId'}
+        createdByName: {type: string, nullable: true, description: 创建人姓名}
+        createdAt: {type: string, format: date-time, description: 创建时间}
+        version: {type: integer, format: int32, minimum: 0, description: 乐观锁版本}
+    LoadingItem:
+      type: object
+      required: [itemId, accountId, inboundId, inboundDetailId, packageCount, palletCount, grossWeightKg, netWeightKg, volumeCbm, dimensionalWeightKg, productQuantity, unitsPerPackage, loadSequence]
+      properties:
+        itemId: {$ref: '#/components/schemas/LongId'}
+        accountId: {$ref: '#/components/schemas/LongId'}
+        customerName: {type: string, nullable: true, description: 客户名称快照}
+        inboundId: {$ref: '#/components/schemas/LongId'}
+        inboundDetailId: {$ref: '#/components/schemas/LongId'}
+        inboundCode: {type: string, nullable: true, description: 入仓码}
+        skuCode: {type: string, nullable: true, description: SKU 编码快照}
+        destinationWarehouse: {type: string, nullable: true, description: 目的仓名称快照}
+        chineseName: {type: string, nullable: true, description: 中文品名快照}
+        englishName: {type: string, nullable: true, description: 英文品名快照}
+        goodsImageUrl: {type: string, nullable: true, description: 产品图片地址快照}
+        packageCount: {type: integer, format: int32, minimum: 0, description: 箱数}
+        palletCount: {type: integer, format: int32, minimum: 0, description: 托盘数}
+        grossWeightKg: {type: number, description: 毛重，单位千克}
+        netWeightKg: {type: number, description: 净重，单位千克}
+        volumeCbm: {type: number, description: 体积，单位立方米}
+        dimensionalWeightKg: {type: number, description: 材积重，单位千克}
+        productQuantity: {type: string, pattern: '^[0-9]+$', description: 产品数量}
+        unitsPerPackage: {type: integer, format: int32, minimum: 0, description: 每箱数量}
+        fbaTrackingNo: {type: string, nullable: true, description: FBA 跟踪编号}
+        shipmentNo: {type: string, nullable: true, description: 货件号}
+        shippingMark: {type: string, nullable: true, description: 唛头}
+        internalRemark: {type: string, nullable: true, description: 内部备注}
+        customerRemark: {type: string, nullable: true, description: 客户备注}
+        warehouseRemark: {type: string, nullable: true, description: 仓库备注}
+        loadSequence: {type: integer, format: int32, minimum: 0, description: 装柜顺序}
+        frozenAt: {type: string, format: date-time, nullable: true, description: 明细冻结时间}
+    OperationHistory:
+      type: object
+      required: [historyId, actionType, operatorId, occurredAt]
+      properties:
+        historyId: {$ref: '#/components/schemas/LongId'}
+        itemId: {$ref: '#/components/schemas/NullableLongId'}
+        actionType: {type: string, description: 操作类型}
+        fromStatus: {type: string, nullable: true, description: 操作前状态}
+        toStatus: {type: string, nullable: true, description: 操作后状态}
+        beforeSnapshot: {type: string, nullable: true, description: 操作前快照}
+        afterSnapshot: {type: string, nullable: true, description: 操作后快照}
+        operatorId: {$ref: '#/components/schemas/LongId'}
+        operatorName: {type: string, nullable: true, description: 操作人姓名}
+        operationReason: {type: string, nullable: true, description: 操作原因}
+        occurredAt: {type: string, format: date-time, description: 操作时间}
+    PreloadDetail:
+      type: object
+      required: [summary, items, histories]
+      properties:
+        summary: {$ref: '#/components/schemas/PreloadSummary'}
+        items: {type: array, description: 装柜中明细，可维护未拣货项, items: {$ref: '#/components/schemas/LoadingItem'}}
+        histories: {type: array, description: 计划操作历史, items: {$ref: '#/components/schemas/OperationHistory'}}
+    ConfirmedDetail:
+      type: object
+      required: [summary, items, histories]
+      properties:
+        summary: {$ref: '#/components/schemas/ConfirmedSummary'}
+        items: {type: array, description: 已完成且永久只读的装柜明细, items: {$ref: '#/components/schemas/LoadingItem'}}
+        histories: {type: array, description: 计划操作历史, items: {$ref: '#/components/schemas/OperationHistory'}}
+    TransportUpdateRequest:
+      type: object
+      required: [expectedVersion]
+      additionalProperties: false
+      properties:
+        containerNo: {type: string, maxLength: 64, nullable: true, description: 集装箱号}
+        voyageNo: {type: string, maxLength: 64, nullable: true, description: 航次}
+        expectedVersion: {type: integer, format: int32, minimum: 0, description: 当前乐观锁版本}
+        operationReason: {type: string, maxLength: 500, nullable: true, description: 操作原因}
+    AdvanceRequest:
+      type: object
+      required: [expectedVersion]
+      additionalProperties: false
+      properties:
+        expectedVersion: {type: integer, format: int32, minimum: 0, description: 当前乐观锁版本}
+        operationReason: {type: string, maxLength: 500, nullable: true, description: 操作原因}