Merge branch 'test' of http://git.buggoglobal.com/java-project/baiyue-firstleg into dev

firstleg/src/main/resources/db/phase3-truck-appointment-schema.sql

@@ -33,8 +33,7 @@ CREATE TABLE IF NOT EXISTS fl_truck_appointment (
  actual_departed_at DATETIME(3) NULL COMMENT '车辆实际离仓时间；DEPARTED后供LOADED门禁使用',
  transit_minutes INT UNSIGNED NULL COMMENT '从到仓到离仓的运输作业耗时，单位分钟',
  payable_amount DECIMAL(18,2) NULL COMMENT '应付拖车服务商金额；币种由currency指定',
- receivable_amount DECIMAL(18,2) NULL COMMENT '拖车业务应收金额；币种由currency指定',
- currency VARCHAR(8) NOT NULL DEFAULT 'RMB' COMMENT '金额币种；首期默认RMB',
+ currency VARCHAR(8) NOT NULL DEFAULT 'RMB' COMMENT '应付金额币种；仅RMB或USD',
  status VARCHAR(32) NOT NULL DEFAULT 'DRAFT' COMMENT '拖车预约状态：DRAFT草稿、PENDING_DISPATCH待派车、DISPATCHED已派车、PICKUP_IN_PROGRESS提货中、ARRIVED_WAREHOUSE已到仓、LOADING装柜中、DEPARTED已离仓、COMPLETED已完成、RESCHEDULED已改约、EXCEPTION异常、CANCELLED已取消',
  active_container_booking_id BIGINT UNSIGNED GENERATED ALWAYS AS (CASE WHEN status NOT IN ('COMPLETED','CANCELLED','EXCEPTION') THEN container_booking_id ELSE NULL END) STORED COMMENT '非终态预约的柜次唯一键',
  revision INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '拖车预约业务修订号；每次状态或改约递增',
@@ -44,7 +43,8 @@ CREATE TABLE IF NOT EXISTS fl_truck_appointment (
  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '拖车预约最后更新时间',
  PRIMARY KEY(id), UNIQUE KEY uk_truck_appointment_no(appointment_no), UNIQUE KEY uk_truck_active_container(active_container_booking_id),
  KEY idx_truck_appointment_status(status,updated_at), KEY idx_truck_appointment_container(container_booking_id),
- CONSTRAINT chk_truck_appointment_status CHECK(status IN ('DRAFT','PENDING_DISPATCH','DISPATCHED','PICKUP_IN_PROGRESS','ARRIVED_WAREHOUSE','LOADING','DEPARTED','COMPLETED','RESCHEDULED','EXCEPTION','CANCELLED'))
+ CONSTRAINT chk_truck_appointment_status CHECK(status IN ('DRAFT','PENDING_DISPATCH','DISPATCHED','PICKUP_IN_PROGRESS','ARRIVED_WAREHOUSE','LOADING','DEPARTED','COMPLETED','RESCHEDULED','EXCEPTION','CANCELLED')),
+ CONSTRAINT chk_truck_appointment_currency CHECK(currency IN ('RMB','USD'))
 ) ENGINE=InnoDB COMMENT='三期拖车预约派车聚合';
 CREATE TABLE IF NOT EXISTS fl_truck_appointment_history (
  id BIGINT UNSIGNED NOT NULL COMMENT '拖车预约历史ID', appointment_id BIGINT UNSIGNED NOT NULL COMMENT '所属拖车预约ID', revision INT UNSIGNED NOT NULL COMMENT '该预约业务修订号', action VARCHAR(32) NOT NULL COMMENT '触发状态或改约的业务动作',

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

@@ -1328,10 +1328,10 @@ components:
           type: array
           maxItems: 100
           items: {$ref: '#/components/schemas/WeightPalletSnapshot'}
-        page: {type: integer, format: int64, minimum: 1}
-        size: {type: integer, format: int64, minimum: 1, maximum: 100}
-        total: {type: integer, format: int64, minimum: 0}
-        pages: {type: integer, format: int64, minimum: 0}
+        page: {oneOf: [{type: integer, format: int64, minimum: 1}, {type: string, pattern: '^[1-9][0-9]*$'}]}
+        size: {oneOf: [{type: integer, format: int64, minimum: 1, maximum: 100}, {type: string, pattern: '^(?:[1-9]|[1-9][0-9]|100)$'}]}
+        total: {oneOf: [{type: integer, format: int64, minimum: 0}, {type: string, pattern: '^(?:0|[1-9][0-9]*)$'}]}
+        pages: {oneOf: [{type: integer, format: int64, minimum: 0}, {type: string, pattern: '^(?:0|[1-9][0-9]*)$'}]}
     CreateWeightResultRequest:
       type: object
       required: [fileId, palletId]

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

@@ -21,6 +21,7 @@ paths:
                       records: {type: array, items: {$ref: '#/components/schemas/DetailStableReferences'}}
     post:
       summary: Create a truck appointment for a released booking and its allocated real container
+      description: If the real container already has a non-terminal appointment, the server returns A0409 with the existing appointment number and instructs the operator to continue editing. This duplicate guard runs before booking-document validation; the database unique key provides the same response for concurrent creates.
       requestBody:
         required: true
         content:
@@ -28,6 +29,7 @@ paths:
             schema: {$ref: '#/components/schemas/SaveRequest'}
       responses:
         '200': {description: 'Created appointment', content: {application/json: {schema: {$ref: '#/components/schemas/DetailEnvelope'}}}}
+        '409': {description: 'A0409 - this container already has a non-terminal appointment; message includes its appointment number and asks the operator to continue editing'}
   /api/platform/v1/truck-appointments/{id}:
     parameters: [{$ref: '#/components/parameters/AppointmentId'}]
     get:
@@ -187,6 +189,8 @@ components:
         carrierName: {type: string, maxLength: 128, nullable: true, description: Optional consistency hint only; the persisted snapshot comes from Warehouse supplier master data.}
         billOfLadingNo: {type: string, maxLength: 128, nullable: true, description: Optional consistency hint; the persisted snapshot is always frozen from the selected RELEASED booking.}
         plannedLoadingAt: {type: string, format: date-time}
+        payableAmount: {type: number, format: double, minimum: 0, nullable: true, description: Amount payable to the trucking supplier.}
+        currency: {type: string, enum: [RMB, USD], default: RMB, description: Payable amount currency.}
         expectedVersion: {type: integer, minimum: 0, description: Must be 0 on create; current version on edit.}
     DetailStableReferences:
       type: object
@@ -209,4 +213,6 @@ components:
         carrierId: {type: integer, format: int64}
         carrierName: {type: string}
         billOfLadingNo: {type: string, maxLength: 128, nullable: true, description: Frozen bill of lading snapshot used by dispatch readiness.}
+        payableAmount: {type: number, format: double, minimum: 0, nullable: true}
+        currency: {type: string, enum: [RMB, USD]}
         attachmentCount: {type: integer, format: int64, minimum: 0, description: Number of attachment references owned by this appointment}