优化

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

@@ -295,7 +295,7 @@ components:
         nextProcessStatus: {type: string, nullable: true, description: 费用动作后的入库主流程状态；审核完成后保持 WAIT_SPLIT}
     InboundFeeDetailSaveRequest:
       type: object
-      required: [feeItemId, direction, businessDate, unitPrice, currency, amount, settlementIncluded]
+      required: [feeItemId, direction, businessDate, unitPrice, currency, amount]
       properties:
         feeItemId: {type: string, pattern: '^[1-9][0-9]*$'}
         direction: {type: string, enum: [RECEIVABLE, PAYABLE]}
@@ -303,9 +303,9 @@ components:
         unitPrice: {type: number, minimum: 0}
         currency: {type: string, pattern: '^[A-Z]{3}$'}
         amount: {type: number, minimum: 0}
-        settlementIncluded: {type: boolean}
-        partnerId: {type: string, nullable: true}
-        partnerName: {type: string, maxLength: 200, nullable: true}
+        supplierId: {type: string, nullable: true}
+        supplierName: {type: string, maxLength: 200, nullable: true, readOnly: true}
+        supplierCategory: {type: string, enum: [BOOKING, CUSTOMS, TRUCKING, CERTIFICATE], nullable: true}
         remark: {type: string, maxLength: 500, nullable: true}
     InboundFeeDetailVersionRequest:
       type: object
@@ -318,7 +318,7 @@ components:
     InboundFeeDetailResource:
       type: object
       description: 入仓费用展示记录。sourceType=FBA_PRICING 时是只读派生；sourceType=MANUAL 时按 sourceFeeId/sourceFeeVersion 独立版本化。
-      required: [id, tenantId, inboundId, feeItemId, sourceType, sourceFeeVersion, direction, businessDate, unitPrice, currency, amount, reviewStatus, publicationStatus, settlementIncluded]
+      required: [id, tenantId, inboundId, feeItemId, sourceType, sourceFeeVersion, direction, businessDate, unitPrice, currency, amount, reviewStatus, publicationStatus]
       properties:
         id: {type: string, pattern: '^[1-9][0-9]*$'}
         tenantId: {type: string, pattern: '^[1-9][0-9]*$'}
@@ -330,8 +330,9 @@ components:
         sourceFeeNo: {type: string, nullable: true}
         inboundCode: {type: string, nullable: true}
         direction: {type: string, enum: [RECEIVABLE, PAYABLE]}
-        partnerId: {type: string, nullable: true}
-        partnerName: {type: string, nullable: true}
+        supplierId: {type: string, nullable: true}
+        supplierName: {type: string, nullable: true, readOnly: true}
+        supplierCategory: {type: string, enum: [BOOKING, CUSTOMS, TRUCKING, CERTIFICATE], nullable: true}
         businessDate: {type: string, format: date}
         customerId: {type: string, nullable: true}
         customerName: {type: string, nullable: true}
@@ -365,7 +366,6 @@ components:
         publishedByName: {type: string, nullable: true}
         publishedAt: {type: string, format: date-time, nullable: true}
         inboundedAt: {type: string, format: date-time, nullable: true}
-        settlementIncluded: {type: boolean}
         createdBy: {type: string, nullable: true}
         createdAt: {type: string, format: date-time, nullable: true}
         updatedBy: {type: string, nullable: true}

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

@@ -100,6 +100,7 @@ components:
         category: {type: string, maxLength: 64}
         tradeScope: {type: string, enum: [DOMESTIC, INTERNATIONAL]}
         feeCode: {type: string, maxLength: 50, pattern: '^[A-Za-z0-9_-]+$'}
+        supplierCategory: {type: string, enum: [BOOKING, CUSTOMS, TRUCKING, CERTIFICATE], nullable: true, description: pickupPayable或warehousePayable为true时必填}
         feeTypeName: {type: string, maxLength: 128}
         pickupPayable: {type: boolean}
         pickupReceivable: {type: boolean}
@@ -115,6 +116,7 @@ components:
         category: {type: string}
         tradeScope: {type: string, enum: [DOMESTIC, INTERNATIONAL]}
         feeCode: {type: string}
+        supplierCategory: {type: string, enum: [BOOKING, CUSTOMS, TRUCKING, CERTIFICATE], nullable: true}
         feeTypeName: {type: string}
         pickupPayable: {type: boolean}
         pickupReceivable: {type: boolean}

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

@@ -838,7 +838,7 @@ paths:
       summary: 调整已审核柜次费用的日期和金额
       description: >-
         仅 ACTIVE、APPROVED 且 sourceVersion 匹配的费用可调整。成功后 sourceVersion 加一并重新进入
-        PENDING；费用方向、费用项目、往来单位、币种、参与结算和备注保持原快照。身份或结算字段需要变化时，
+        PENDING；费用方向、费用项目、供应商、币种和备注保持原快照。业务字段需要变化时，
         必须作废原费用并新增。同一 expectedSourceVersion、businessDate、amount 的原样重试只读返回已生成的
         PENDING 版本；旧版本异参、已作废或非已审核状态返回 A0409 且零写入。
       parameters:
@@ -1446,10 +1446,10 @@ components:
       properties:
         id: {type: string, pattern: '^[1-9][0-9]*$'}
         planId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true, description: 关联智能装柜计划ID；未创建计划时为空}
-        planNo: {type: string, nullable: true, description: 装柜清单号；未创建计划时为空}
-        bookingNo: {type: string, maxLength: 40}
+        planNo: {type: string, nullable: true, pattern: '^LP-[0-9]{6}-[0-9]{4}$', example: LP-260818-0001, description: 预装与确认装柜清单共用的稳定编号；未创建计划时为空}
+        bookingNo: {type: string, pattern: '^CB-[0-9]{6}-[0-9]{4}$', example: CB-260818-0001, description: 平台内部货柜登记号}
         containerNo: {type: string, maxLength: 64, nullable: true}
-        cabinetNo: {type: string, maxLength: 64}
+        cabinetNo: {type: string, pattern: '^CAB-[0-9]{6}-[0-9]{4}$', example: CAB-260818-0001, description: 平台稳定柜次号}
         sourceType: {type: string, enum: [SIMULATION, OCEAN_BOOKING], description: SIMULATION 为内部模拟柜；OCEAN_BOOKING 为订舱登记直接生成的真实柜}
         recordStatus: {type: string, enum: [ACTIVE, MERGED], description: 正常列表和详情仅返回 ACTIVE；真实订舱柜被模拟柜消费后变为 MERGED 且不再作为可操作柜返回}
         mergedIntoContainerBookingId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true, description: MERGED 源真实柜指向保留的模拟柜稳定 containerBookingId；ACTIVE 时为空}
@@ -1580,7 +1580,7 @@ components:
       required: [id, planNo, status, bookingId, version, canAssign, canEdit, finalCompletionStatus, items]
       properties:
         id: {type: string}
-        planNo: {type: string}
+        planNo: {type: string, pattern: '^LP-[0-9]{6}-[0-9]{4}$', example: LP-260818-0001, description: 预装与确认装柜清单共用的稳定编号}
         status: {type: string, enum: [EDITING, LOADING, COMPLETED]}
         bookingId: {type: string}
         containerNo: {type: string, nullable: true}
@@ -1692,7 +1692,6 @@ components:
         publicationStatus: {type: string, enum: [PUBLISHED]}
         publishedAt: {type: string, format: date-time}
         inboundedAt: {type: string, format: date-time, nullable: true}
-        settlementIncluded: {type: boolean, example: true}
     InboundOrderPageEnvelope:
       type: object
       properties:

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

@@ -294,9 +294,9 @@ components:
       properties:
         planId: {$ref: '#/components/schemas/LongId'}
         containerBookingId: {$ref: '#/components/schemas/LongId'}
-        preloadNo: {type: string, description: 预装单号}
+        preloadNo: {type: string, pattern: '^LP-[0-9]{6}-[0-9]{4}$', example: LP-260818-0001, description: 预装单号；按北京时间创建日逐日编号，确认后继续作为同一装柜清单号使用}
         containerNo: {type: string, nullable: true, description: 集装箱号}
-        cabinetNo: {type: string, nullable: true, description: 稳定柜次号；不得与真实集装箱号混用}
+        cabinetNo: {type: string, nullable: true, pattern: '^CAB-[0-9]{6}-[0-9]{4}$', example: CAB-260818-0001, description: 稳定柜次号；不得与真实集装箱号混用}
         customers: {type: array, description: 计划包含的客户, items: {$ref: '#/components/schemas/Customer'}}
         warehouseId: {$ref: '#/components/schemas/NullableLongId'}
         warehouseName: {type: string, nullable: true, description: 仓库名称}
@@ -351,11 +351,11 @@ components:
       properties:
         planId: {$ref: '#/components/schemas/LongId'}
         containerBookingId: {$ref: '#/components/schemas/LongId'}
-        loadingListNo: {type: string, description: 装柜清单号}
+        loadingListNo: {type: string, pattern: '^LP-[0-9]{6}-[0-9]{4}$', example: LP-260818-0001, description: 装柜清单号；沿用预装阶段生成的同一编号}
         warehouseId: {$ref: '#/components/schemas/NullableLongId'}
         warehouseName: {type: string, nullable: true, description: 仓库名称}
         containerNo: {type: string, nullable: true, description: 集装箱号}
-        cabinetNo: {type: string, nullable: true, description: 稳定柜次号}
+        cabinetNo: {type: string, nullable: true, pattern: '^CAB-[0-9]{6}-[0-9]{4}$', example: CAB-260818-0001, description: 稳定柜次号}
         status: {type: string, enum: [COMPLETED], description: 装柜清单状态}
         totalPackageCount: {type: string, pattern: '^[0-9]+$', description: 总箱数}
         totalGrossWeightKg: {type: number, description: 总毛重，单位千克}

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

@@ -94,4 +94,15 @@ components:
         channelName: {type: string}
         priceModel: {type: string}
         pricingTaxModes: {type: array, items: {type: string}}
-    Detail: {type: object, required: [oceanBooking, parties, containerRequirements, containers, histories], properties: {oceanBooking: {type: object}, parties: {type: array}, containerRequirements: {type: array}, containers: {type: array, description: Existing containers allocated after port pickup linking}, histories: {type: array}}}
+    Detail:
+      type: object
+      required: [oceanBooking, parties, containerRequirements, containers, histories]
+      properties:
+        oceanBooking:
+          type: object
+          properties:
+            bookingNo: {type: string, pattern: '^OB-[0-9]{6}-[0-9]{4}$', example: OB-260818-0001, description: 平台订舱号；按北京时间创建日逐日编号}
+        parties: {type: array}
+        containerRequirements: {type: array}
+        containers: {type: array, description: Existing containers allocated after port pickup linking}
+        histories: {type: array}

firstleg/src/main/resources/openapi/phase3-container-overview-v1.yaml

@@ -55,7 +55,7 @@ components:
         exception: {$ref: '#/components/schemas/ExceptionState'}
         exceptionHistory: {type: array, items: {$ref: '#/components/schemas/ExceptionHistory'}}
         timeline: {type: array, items: {$ref: '#/components/schemas/TimelineEntry'}}
-    Container: {type: object, properties: {id: {type: integer, format: int64}, bookingNo: {type: string}, cabinetNo: {type: string}, containerNo: {type: string}, status: {type: string}, warehouseId: {type: integer, format: int64}, warehouseName: {type: string}, voyageNo: {type: string}, vesselName: {type: string}, version: {type: integer, minimum: 0}}}
+    Container: {type: object, properties: {id: {type: integer, format: int64}, bookingNo: {type: string, pattern: '^CB-[0-9]{6}-[0-9]{4}$', example: CB-260818-0001}, cabinetNo: {type: string, pattern: '^CAB-[0-9]{6}-[0-9]{4}$', example: CAB-260818-0001}, containerNo: {type: string}, status: {type: string}, warehouseId: {type: integer, format: int64}, warehouseName: {type: string}, voyageNo: {type: string}, vesselName: {type: string}, version: {type: integer, minimum: 0}}}
     PdaSummary: {type: object, properties: {taskId: {type: integer, format: int64}, loadingPlanId: {type: integer, format: int64}, containerBookingId: {type: integer, format: int64}, taskStatus: {type: string, description: '持久化任务态：LOADING/COMPLETED'}, workflowStatus: {type: string, enum: [IN_PROGRESS, AWAITING_REVIEW, COMPLETED], description: 'PDA作业展示态'}, taskVersion: {type: integer}, itemCount: {type: integer}, completedItemCount: {type: integer}, unresolvedItemCount: {type: integer}, photoCounts: {type: array, items: {$ref: '#/components/schemas/PhotoCount'}}, photos: {type: array, items: {$ref: '#/components/schemas/Photo'}}, exceptionReasons: {type: array, items: {type: string}}}}
     PhotoCount: {type: object, properties: {evidenceType: {type: string}, count: {type: integer}}}
     Photo: {type: object, properties: {evidenceId: {type: integer, format: int64}, tenantId: {type: integer, format: int64}, inboundId: {type: integer, format: int64}, evidenceType: {type: string}, fileId: {type: integer, format: int64}, fileName: {type: string}, status: {type: string, enum: [ACTIVE, VOID]}, downloadPath: {type: string, nullable: true, description: '仅 ACTIVE 照片提供鉴权下载路径；VOID 历史照片为空'}, uploadedAt: {type: string, format: date-time}}}

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

@@ -29,7 +29,7 @@ paths:
           application/json:
             schema: {$ref: '#/components/schemas/SaveRequest'}
       responses:
-        '200': {description: Created appointment}
+        '200': {description: Created appointment, content: {application/json: {schema: {$ref: '#/components/schemas/DetailStableReferences'}}}}
   /api/platform/v1/truck-appointments/{id}:
     parameters: [{$ref: '#/components/parameters/AppointmentId'}]
     get:
@@ -182,13 +182,14 @@ components:
         expectedVersion: {type: integer, minimum: 0, description: Must be 0 on create; current version on edit.}
     DetailStableReferences:
       type: object
-      required: [customerId, customerName, carrierId, carrierName, attachmentCount]
+      required: [appointmentNo, customerId, customerName, carrierId, carrierName, attachmentCount]
       description: Stable IDs plus server-resolved saved resource names returned by appointment detail. Fulfillment associations remain null for an independently created appointment.
       properties:
+        appointmentNo: {type: string, pattern: '^TA-[0-9]{6}-[0-9]{4}$', example: TA-260818-0001, description: 派车单号；按北京时间创建日逐日编号}
         oceanBookingId: {type: integer, format: int64, nullable: true}
-        oceanBookingNo: {type: string, nullable: true}
+        oceanBookingNo: {type: string, nullable: true, pattern: '^OB-[0-9]{6}-[0-9]{4}$', example: OB-260818-0001}
         containerBookingId: {type: integer, format: int64, nullable: true}
-        cabinetNo: {type: string, nullable: true}
+        cabinetNo: {type: string, nullable: true, pattern: '^CAB-[0-9]{6}-[0-9]{4}$', example: CAB-260818-0001}
         containerNo: {type: string, nullable: true}
         loadingPlanId: {type: integer, format: int64, nullable: true}
         warehouseId: {type: integer, format: int64, nullable: true}