优化

firstleg/src/main/resources/db/finance-fee-source-migration.sql

@@ -71,12 +71,12 @@ CREATE TABLE IF NOT EXISTS fl_container_fee_detail (
   fee_item_code_snapshot VARCHAR(50) NOT NULL COMMENT '费用项目稳定编码快照',
   fee_item_name_snapshot VARCHAR(128) NOT NULL COMMENT '费用项目名称快照',
   direction VARCHAR(16) NOT NULL COMMENT '费用方向：RECEIVABLE应收、PAYABLE应付',
-  partner_id BIGINT UNSIGNED NULL COMMENT '应付往来单位ID快照；应收为空',
-  partner_name VARCHAR(200) NULL COMMENT '应付往来单位名称快照；应收为空',
+  supplier_id BIGINT UNSIGNED NULL COMMENT '应付Warehouse供应商ID快照；应收为空',
+  supplier_name VARCHAR(200) NULL COMMENT '应付Warehouse供应商名称快照；应收为空',
+  supplier_category VARCHAR(16) NULL COMMENT '费用项目供应商类别快照；应收为空',
   business_date DATE NOT NULL COMMENT '费用业务日期',
   amount DECIMAL(18,2) NOT NULL COMMENT 'CNY费用金额',
   currency CHAR(3) NOT NULL DEFAULT 'CNY' COMMENT '币种，首期固定CNY',
-  settlement_included TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否参与财务结算来源池',
   review_status VARCHAR(16) NOT NULL DEFAULT 'PENDING' COMMENT '审核状态：PENDING待审核、APPROVED通过、REJECTED驳回',
   source_status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE' COMMENT '来源状态：ACTIVE有效、VOIDED作废',
   source_version INT UNSIGNED NOT NULL DEFAULT 1 COMMENT '费用来源版本；调整递增，作废携带当前版本',
@@ -91,22 +91,46 @@ CREATE TABLE IF NOT EXISTS fl_container_fee_detail (
   updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '最后更新时间',
   PRIMARY KEY (id),
   KEY idx_container_fee_customer_plan (tenant_id, loading_plan_id, source_status),
-  KEY idx_container_fee_settlement (tenant_id, review_status, settlement_included, source_status),
+  KEY idx_container_fee_review (tenant_id, review_status, source_status),
   CONSTRAINT chk_container_fee_direction CHECK (direction IN ('RECEIVABLE', 'PAYABLE')),
   CONSTRAINT chk_container_fee_currency CHECK (currency = 'CNY'),
   CONSTRAINT chk_container_fee_amount CHECK (amount >= 0),
   CONSTRAINT chk_container_fee_review CHECK (review_status IN ('PENDING', 'APPROVED', 'REJECTED')),
   CONSTRAINT chk_container_fee_source CHECK (source_status IN ('ACTIVE', 'VOIDED'))
-) ENGINE=InnoDB COMMENT='柜次级人工应收应付费用来源；审核通过且参与结算后同步Finance';
+) ENGINE=InnoDB COMMENT='柜次级人工应收应付费用来源；审核通过后自动同步Finance';
 
-CALL firstleg_finance_add_column('fl_container_fee_detail', 'partner_id',
-  "BIGINT UNSIGNED NULL COMMENT '应付往来单位ID快照；应收为空' AFTER direction");
-CALL firstleg_finance_add_column('fl_container_fee_detail', 'partner_name',
-  "VARCHAR(200) NULL COMMENT '应付往来单位名称快照；应收为空' AFTER partner_id");
-CALL firstleg_finance_add_column('fl_inbound_fee_detail', 'partner_id',
-  "BIGINT UNSIGNED NULL COMMENT '应付往来单位ID快照；应收为空' AFTER direction");
-CALL firstleg_finance_add_column('fl_inbound_fee_detail', 'partner_name',
-  "VARCHAR(200) NULL COMMENT '应付往来单位名称快照；应收为空' AFTER partner_id");
+CREATE TABLE IF NOT EXISTS fl_container_fee_source_snapshot (
+  id BIGINT UNSIGNED NOT NULL,
+  source_fee_id BIGINT UNSIGNED NOT NULL,
+  source_version INT UNSIGNED NOT NULL,
+  tenant_id BIGINT UNSIGNED NOT NULL,
+  loading_plan_id BIGINT UNSIGNED NOT NULL,
+  container_booking_id BIGINT UNSIGNED NULL,
+  container_no VARCHAR(64) NULL,
+  fee_item_id BIGINT UNSIGNED NOT NULL,
+  fee_item_code VARCHAR(50) NOT NULL,
+  fee_item_name VARCHAR(128) NOT NULL,
+  direction VARCHAR(16) NOT NULL,
+  supplier_id BIGINT UNSIGNED NULL,
+  supplier_name VARCHAR(200) NULL,
+  supplier_category VARCHAR(16) NULL,
+  business_date DATE NOT NULL,
+  amount DECIMAL(18,2) NOT NULL,
+  currency CHAR(3) NOT NULL DEFAULT 'CNY',
+  review_status VARCHAR(16) NOT NULL,
+  reviewed_at DATETIME(3) NULL,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_container_fee_source_version (loading_plan_id, source_fee_id, source_version),
+  KEY idx_container_fee_snapshot_tenant (tenant_id, loading_plan_id)
+) ENGINE=InnoDB COMMENT='柜次费用不可变版本快照';
+
+CALL firstleg_finance_add_column('fl_container_fee_detail', 'supplier_id', "BIGINT UNSIGNED NULL COMMENT '应付Warehouse供应商ID快照；应收为空' AFTER direction");
+CALL firstleg_finance_add_column('fl_container_fee_detail', 'supplier_name', "VARCHAR(200) NULL COMMENT '应付Warehouse供应商名称快照；应收为空' AFTER supplier_id");
+CALL firstleg_finance_add_column('fl_container_fee_detail', 'supplier_category', "VARCHAR(16) NULL COMMENT '费用项目供应商类别快照；应收为空' AFTER supplier_name");
+CALL firstleg_finance_add_column('fl_inbound_fee_detail', 'supplier_id', "BIGINT UNSIGNED NULL COMMENT '应付Warehouse供应商ID快照；应收为空' AFTER direction");
+CALL firstleg_finance_add_column('fl_inbound_fee_detail', 'supplier_name', "VARCHAR(200) NULL COMMENT '应付Warehouse供应商名称快照；应收为空' AFTER supplier_id");
+CALL firstleg_finance_add_column('fl_inbound_fee_detail', 'supplier_category', "VARCHAR(16) NULL COMMENT '费用项目供应商类别快照；应收为空' AFTER supplier_name");
 DROP PROCEDURE IF EXISTS firstleg_finance_add_column;
 
 DROP PROCEDURE IF EXISTS firstleg_finance_assert_schema;
@@ -125,13 +149,13 @@ BEGIN
   END IF;
   IF (SELECT COUNT(*) FROM information_schema.columns
        WHERE table_schema = DATABASE() AND table_name = 'fl_container_fee_detail'
-         AND column_name IN ('partner_id', 'partner_name')) <> 2 THEN
-    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'Firstleg Finance迁移失败：柜次费用往来单位快照字段不完整';
+         AND column_name IN ('supplier_id', 'supplier_name', 'supplier_category')) <> 3 THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'Firstleg Finance迁移失败：柜次费用供应商快照字段不完整';
   END IF;
   IF (SELECT COUNT(*) FROM information_schema.columns
        WHERE table_schema = DATABASE() AND table_name = 'fl_inbound_fee_detail'
-         AND column_name IN ('partner_id', 'partner_name')) <> 2 THEN
-    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'Firstleg Finance迁移失败：入库费用往来单位快照字段不完整';
+         AND column_name IN ('supplier_id', 'supplier_name', 'supplier_category')) <> 3 THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'Firstleg Finance迁移失败：入库费用供应商快照字段不完整';
   END IF;
 END$$
 DELIMITER ;

firstleg/src/main/resources/db/phase2-fee-item-and-inbound-detail.sql

@@ -7,6 +7,7 @@ CREATE TABLE IF NOT EXISTS fl_fee_item (
   category VARCHAR(64) NOT NULL COMMENT '费用分类',
   trade_scope VARCHAR(20) NOT NULL COMMENT 'DOMESTIC国内、INTERNATIONAL国际',
   fee_code VARCHAR(50) NOT NULL COMMENT '稳定费用编码；平台公共主数据固定编码',
+  supplier_category VARCHAR(16) NULL COMMENT 'PAYABLE供应商类别；未配置则失败关闭',
   fee_type_name VARCHAR(128) NOT NULL COMMENT '费用类型名称',
   pickup_payable TINYINT(1) NOT NULL DEFAULT 0 COMMENT '提柜应付是否参与',
   pickup_receivable TINYINT(1) NOT NULL DEFAULT 0 COMMENT '提柜应收是否参与',
@@ -36,8 +37,9 @@ CREATE TABLE IF NOT EXISTS fl_inbound_fee_detail (
   fee_item_id BIGINT UNSIGNED NOT NULL COMMENT '绑定费用项目ID',
   inbound_code VARCHAR(40) NOT NULL COMMENT '入仓码快照',
   direction VARCHAR(16) NOT NULL COMMENT 'RECEIVABLE应收、PAYABLE应付',
-  partner_id BIGINT UNSIGNED NULL COMMENT '应付往来单位ID快照；应收为空',
-  partner_name VARCHAR(200) NULL COMMENT '应付往来单位名称快照；应收为空',
+  supplier_id BIGINT UNSIGNED NULL COMMENT '应付Warehouse供应商ID快照；应收为空',
+  supplier_name VARCHAR(200) NULL COMMENT '应付Warehouse供应商名称快照；应收为空',
+  supplier_category VARCHAR(16) NULL COMMENT '费用项目供应商类别快照；应收为空',
   business_date DATE NOT NULL COMMENT '业务发生日',
   fee_category_snapshot VARCHAR(64) NOT NULL COMMENT '费用分类快照',
   trade_scope_snapshot VARCHAR(20) NOT NULL COMMENT '国内国际快照',

firstleg/src/main/resources/db/phase2-published-freight-detail-migration.sql

@@ -22,6 +22,8 @@ DELIMITER ;
 
 CALL phase2_publish_add_column('fl_fee_item', 'fee_code',
   "VARCHAR(50) NULL COMMENT '稳定费用编码；系统费用使用固定编码' AFTER trade_scope");
+CALL phase2_publish_add_column('fl_fee_item', 'supplier_category',
+  "VARCHAR(16) NULL COMMENT 'PAYABLE供应商类别；未配置则失败关闭' AFTER fee_code");
 ALTER TABLE fl_fee_item
   MODIFY COLUMN tenant_id BIGINT UNSIGNED NOT NULL COMMENT '平台公共费用项目作用域，固定为0；物理字段名沿用 tenant_id',
   COMMENT = '平台公共费用项目主数据';
@@ -431,9 +433,6 @@ CALL phase2_publish_add_column('fl_inbound_fee_detail', 'published_at',
   "DATETIME(3) NULL COMMENT '发布时间' AFTER published_by_name");
 CALL phase2_publish_add_column('fl_inbound_fee_detail', 'inbounded_at',
   "DATETIME(3) NULL COMMENT '入库完成时间快照' AFTER published_at");
-CALL phase2_publish_add_column('fl_inbound_fee_detail', 'settlement_included',
-  "TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否参与结算' AFTER inbounded_at");
-
 DROP PROCEDURE IF EXISTS phase2_publish_add_column;
 
 DROP PROCEDURE IF EXISTS phase2_publish_add_index;

firstleg/src/main/resources/db/phase3-smart-loading-schema.sql

@@ -26,6 +26,13 @@ DELIMITER ;
 CALL phase3_add_allocation_picked_count();
 DROP PROCEDURE phase3_add_allocation_picked_count;
 
+CREATE TABLE IF NOT EXISTS fl_document_sequence (
+  sequence_key VARCHAR(32) NOT NULL COMMENT '单据类型与北京时间日期组合键，例如CAB:20260818',
+  current_value INT UNSIGNED NOT NULL COMMENT '该类型当日已分配的最大序号',
+  PRIMARY KEY (sequence_key),
+  CONSTRAINT chk_fl_document_sequence_value CHECK (current_value > 0)
+) ENGINE=InnoDB COMMENT='头程履约业务单号日序列；生成YYMMDD加四位当日序号';
+
 CREATE TABLE IF NOT EXISTS fl_container_booking (
   id BIGINT UNSIGNED NOT NULL COMMENT '货柜预订ID（雪花ID）',
   booking_no VARCHAR(40) NOT NULL COMMENT '平台唯一货柜预订单号',

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}