优化

deploy/sql/README.md

@@ -231,7 +231,7 @@ SELECT
 
 - 国内固定入口已在海外仓业务 `lastleg-permissions.sql` 权限段之后完整内联 `iam/src/main/resources/db/phase5-delivery-permissions.sql`；测试和部署只执行固定入口，不再单独执行模块脚本。
 - 平台端固定使用排车列表/编辑/取消/转派送、出库列表/创建/取消、派送列表/退回/状态/资料管理、异常订单列表/创建/处理和客户回访列表/编辑十六项权限；列表权限包含详情及只读辅助接口，写操作保持独立授权。
-- 派送七类资料上传、替换、解绑和保存统一使用 `platform:overseas-warehouse:delivery:documents`，读取和下载仍使用 `platform:overseas-warehouse:delivery:list`；默认授予 `PLATFORM_ADMIN`、`PLATFORM_CUSTOM_ADMIN`、`WAREHOUSE_OPERATOR`。
+- 派送三类资料上传、替换、解绑和保存统一使用 `platform:overseas-warehouse:delivery:documents`，读取和下载仍使用 `platform:overseas-warehouse:delivery:list`；默认授予 `PLATFORM_ADMIN`、`PLATFORM_CUSTOM_ADMIN`、`WAREHOUSE_OPERATOR`。
 - 客户端固定使用 `merchant:warehouse:delivery:list` 和 `merchant:warehouse:delivery:create`；客户默认管理员获得两项权限，其他客户角色不自动扩权。
 - `WAREHOUSE_OPERATOR` 获得十六项后台作业权限，`WAREHOUSE_TALLY` 只获得排车、出库、派送、异常订单和客户回访五项列表只读；国内、海外 PDA 岗位不得获得上述后台权限。
 

deploy/sql/头程数据库统一增量-MySQL8.sql

@@ -18120,7 +18120,7 @@ DROP PROCEDURE IF EXISTS assert_wallet_event_schema;
 USE baiyue_firstleg;
 CREATE TABLE IF NOT EXISTS fl_terminal_drayage (
   id BIGINT UNSIGNED NOT NULL COMMENT '目的港码头拖车聚合ID', container_booking_id BIGINT UNSIGNED NOT NULL COMMENT '唯一归属物理货柜ID',
-  fleet_supplier_id BIGINT UNSIGNED NOT NULL COMMENT 'Warehouse ACTIVE/TRUCKING供应商ID快照', fleet_supplier_name VARCHAR(128) NOT NULL COMMENT 'Warehouse供应商名称快照',
+  fleet_supplier_id BIGINT UNSIGNED NULL COMMENT 'Warehouse ACTIVE/TRUCKING供应商ID快照', fleet_supplier_name VARCHAR(128) NULL COMMENT 'Warehouse供应商名称快照',
   pickup_appointment_at DATETIME(3) NULL COMMENT '预约提柜时间', actual_pickup_at DATETIME(3) NULL COMMENT '实际提柜时间',
   estimated_empty_return_at DATETIME(3) NULL COMMENT '服务端按卸柜完成时间加72小时计算的预计还柜时间', actual_empty_return_at DATETIME(3) NULL COMMENT '实际还空柜时间',
   version INT UNSIGNED NOT NULL DEFAULT 1 COMMENT '乐观锁版本号', created_by BIGINT UNSIGNED NOT NULL COMMENT '创建人ID',
@@ -18160,8 +18160,8 @@ CREATE TABLE IF NOT EXISTS fl_terminal_drayage_operation (
 ALTER TABLE fl_terminal_drayage
   MODIFY COLUMN id BIGINT UNSIGNED NOT NULL COMMENT '目的港码头拖车聚合ID',
   MODIFY COLUMN container_booking_id BIGINT UNSIGNED NOT NULL COMMENT '唯一归属物理货柜ID',
-  MODIFY COLUMN fleet_supplier_id BIGINT UNSIGNED NOT NULL COMMENT 'Warehouse ACTIVE/TRUCKING供应商ID快照',
-  MODIFY COLUMN fleet_supplier_name VARCHAR(128) NOT NULL COMMENT 'Warehouse供应商名称快照',
+  MODIFY COLUMN fleet_supplier_id BIGINT UNSIGNED NULL COMMENT 'Warehouse ACTIVE/TRUCKING供应商ID快照',
+  MODIFY COLUMN fleet_supplier_name VARCHAR(128) NULL COMMENT 'Warehouse供应商名称快照',
   MODIFY COLUMN pickup_appointment_at DATETIME(3) NULL COMMENT '预约提柜时间',
   MODIFY COLUMN actual_pickup_at DATETIME(3) NULL COMMENT '实际提柜时间',
   MODIFY COLUMN estimated_empty_return_at DATETIME(3) NULL COMMENT '服务端按卸柜完成时间加72小时计算的预计还柜时间',

firstleg/src/main/java/com/baiyue/firstleg/terminaldrayage/service/TerminalDrayageService.java

@@ -164,12 +164,11 @@ public class TerminalDrayageService {
         WorkContext context = requiredLockedContext(containerBookingId);
         View replay = replay(context, action, key, request);
         if (replay != null) return replay;
-        TerminalDrayageEntity value = requiredAggregate(containerBookingId);
+        TerminalDrayageEntity value = mapper.lock(containerBookingId);
         requireVersion(value, request.expectedVersion());
         LocalDateTime pickupAt = actualPickupAt(context, value);
-        if (pickupAt == null) throw conflict("实际提柜后才能确认还柜");
         if (context.base().unloadingCompletedAt() == null) throw conflict("海外卸柜收货完成后才能确认还柜");
-        LocalDateTime earliest = pickupAt.isAfter(context.base().unloadingCompletedAt())
+        LocalDateTime earliest = pickupAt != null && pickupAt.isAfter(context.base().unloadingCompletedAt())
             ? pickupAt : context.base().unloadingCompletedAt();
         if (request.actualAt().isBefore(earliest)) throw badRequest("实际还柜时间不能早于提柜或卸柜完成时间");
         if (actualEmptyReturnAt(context, value) != null) throw conflict("实际还柜时间已确认");
@@ -177,6 +176,7 @@ public class TerminalDrayageService {
             request.remark(), operatorId, operatorName);
         int fromVersion = version(value);
         String fromStatus = status(context, value);
+        if (value == null) value = create(containerBookingId, operatorId, operatorName);
         applyAuthoritativeDeadline(context, value);
         value.setActualEmptyReturnAt(request.actualAt());
         persist(value, fromVersion, operatorId, operatorName);
@@ -277,14 +277,14 @@ public class TerminalDrayageService {
         if (current != null && current.sequence() >= CarrierScheduleNode.PICKUP_READY.sequence()
             && value != null && value.getFleetSupplierId() != null && value.getPickupAppointmentAt() != null
             && actualPickupAt(context, value) == null) result.add("RECORD_PICKUP");
-        if (value != null && context.base().unloadingCompletedAt() != null && actualPickupAt(context, value) != null
+        if (context.base().unloadingCompletedAt() != null
             && actualEmptyReturnAt(context, value) == null) result.add("RECORD_EMPTY_RETURN");
         return List.copyOf(result);
     }
 
     private String status(WorkContext context, TerminalDrayageEntity value) {
         if (actualEmptyReturnAt(context, value) != null) return "EMPTY_RETURNED";
-        if (context.base().unloadingCompletedAt() != null && actualPickupAt(context, value) != null) return "UNLOADED";
+        if (context.base().unloadingCompletedAt() != null) return "UNLOADED";
         if (actualPickupAt(context, value) != null) return "PICKED_UP";
         if (value != null && value.getPickupAppointmentAt() != null) return "PICKUP_SCHEDULED";
         CarrierScheduleNode current = node(context.facts().latestActualNode());

firstleg/src/main/resources/db/phase3-terminal-drayage-schema.sql

@@ -4,8 +4,8 @@ USE baiyue_firstleg;
 CREATE TABLE IF NOT EXISTS fl_terminal_drayage (
   id BIGINT UNSIGNED NOT NULL COMMENT '目的港码头拖车聚合ID',
   container_booking_id BIGINT UNSIGNED NOT NULL COMMENT '唯一归属物理货柜ID',
-  fleet_supplier_id BIGINT UNSIGNED NOT NULL COMMENT 'Warehouse ACTIVE/TRUCKING供应商ID快照',
-  fleet_supplier_name VARCHAR(128) NOT NULL COMMENT 'Warehouse供应商名称快照',
+  fleet_supplier_id BIGINT UNSIGNED NULL COMMENT 'Warehouse ACTIVE/TRUCKING供应商ID快照',
+  fleet_supplier_name VARCHAR(128) NULL COMMENT 'Warehouse供应商名称快照',
   pickup_appointment_at DATETIME(3) NULL COMMENT '预约提柜时间',
   actual_pickup_at DATETIME(3) NULL COMMENT '实际提柜时间',
   estimated_empty_return_at DATETIME(3) NULL COMMENT '服务端按卸柜完成时间加72小时计算的预计还柜时间',

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

@@ -47,6 +47,7 @@ paths:
   /api/platform/v1/terminal-drayages/{containerBookingId}/empty-return:
     post:
       summary: 海外卸柜收货完成后确认实际还柜并推进EMPTY_RETURNED节点
+      description: 以海外卸柜完成事实开放还柜；无需已有车队、预约或实际提柜记录。无拖车记录时提交 expectedVersion=0，由命令创建记录，不补造提柜时间。实际还柜时间不得早于卸柜完成时间及已有实际提柜时间。
       x-permission: platform:firstleg:terminal-drayage:empty-return:confirm
       parameters: [{$ref: '#/components/parameters/ContainerBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ActualTimeRequest'}}}}

firstleg/src/test/java/com/baiyue/firstleg/terminaldrayage/mapper/TerminalDrayageSqlContractTest.java

@@ -15,6 +15,8 @@ class TerminalDrayageSqlContractTest {
             "src/main/java/com/baiyue/firstleg/terminaldrayage/mapper/TerminalDrayageMapper.java"));
         assertThat(sql).contains(
             "CREATE TABLE IF NOT EXISTS fl_terminal_drayage (",
+            "fleet_supplier_id BIGINT UNSIGNED NULL",
+            "fleet_supplier_name VARCHAR(128) NULL",
             "UNIQUE KEY uk_terminal_drayage_container(container_booking_id)",
             "CREATE TABLE IF NOT EXISTS fl_terminal_drayage_history (",
             "CREATE TABLE IF NOT EXISTS fl_terminal_drayage_operation (",

firstleg/src/test/java/com/baiyue/firstleg/terminaldrayage/service/ContainerWorkbenchServiceTest.java

@@ -95,7 +95,7 @@ class ContainerWorkbenchServiceTest {
     }
 
     @Test
-    void unloadedListWithoutDrayageAggregateDoesNotOfferUnexecutableReturn() throws Exception {
+    void unloadedListWithoutDrayageAggregateOffersEmptyReturn() throws Exception {
         verifyRealEmptyReturnProjection(true, false);
     }
 
@@ -129,7 +129,7 @@ class ContainerWorkbenchServiceTest {
         var page = service.overseasPage(query(WorkbenchScope.ACTIVE), permissions);
         var listed = page.records().get(0);
         var detail = service.overseasDetail(11L, permissions);
-        List<String> expected = hasPermission && hasAggregate ? List.of("RECORD_EMPTY_RETURN") : List.of();
+        List<String> expected = hasPermission ? List.of("RECORD_EMPTY_RETURN") : List.of();
         assertThat(listed.workbenchStage()).isEqualTo("UNLOADED");
         assertThat(listed.terminalDrayage().status()).isEqualTo("UNLOADED");
         assertThat(listed.allowedActions()).isEqualTo(expected);
@@ -143,6 +143,46 @@ class ContainerWorkbenchServiceTest {
         verify(mapper).contexts(List.of(11L));
     }
 
+    @Test
+    void unloadedWorkbenchWithoutPickupOffersEmptyReturn() {
+        var mapper = mock(com.baiyue.firstleg.terminaldrayage.mapper.TerminalDrayageMapper.class);
+        var realDrayages = new TerminalDrayageService(mapper,
+            mock(com.baiyue.firstleg.service.WarehouseSupplierSnapshotService.class), carrierSchedules,
+            new com.fasterxml.jackson.databind.ObjectMapper().findAndRegisterModules());
+        ReflectionTestUtils.setField(service, "terminalDrayages", realDrayages);
+        ContainerBookingEntity container = container();
+        LocalDateTime unloadedAt = LocalDateTime.of(2026, 9, 5, 8, 0);
+        container.setUnloadingCompletedAt(unloadedAt);
+        var context = new com.baiyue.firstleg.terminaldrayage.mapper.TerminalDrayageMapper.Context(
+            11L, container.getContainerNo(), 21L, "ACTIVE", unloadedAt);
+        LocalDateTime readyAt = unloadedAt.minusDays(1);
+        var actualFacts = new ContainerActualFacts(11L, 41L, 8, "READY", "PICKUP_READY", readyAt,
+            readyAt.minusDays(5), readyAt.minusDays(4), readyAt.minusDays(1), readyAt, null, null);
+        when(repository.page(eq("OVERSEAS"), any())).thenReturn(new PageResult<>(List.of(container), 1, 20, 1, 1));
+        when(repository.find(11L)).thenReturn(container);
+        when(repository.departed(11L)).thenReturn(true);
+        when(mapper.contexts(List.of(11L))).thenReturn(List.of(context));
+        when(mapper.context(11L)).thenReturn(context);
+        when(mapper.findAll(List.of(11L))).thenReturn(List.of());
+        when(mapper.find(11L)).thenReturn(null);
+        when(carrierSchedules.containerActualFacts(List.of(11L))).thenReturn(List.of(actualFacts));
+        Set<String> permissions = Set.of("platform:firstleg:terminal-drayage:fleet:edit",
+            "platform:firstleg:terminal-drayage:empty-return:confirm");
+
+        var listed = service.overseasPage(query(WorkbenchScope.ACTIVE), permissions).records().get(0);
+        var detail = service.overseasDetail(11L, permissions);
+
+        for (var result : List.of(listed, detail)) {
+            assertThat(result.workbenchStage()).isEqualTo("UNLOADED");
+            assertThat(result.terminalDrayage().status()).isEqualTo("UNLOADED");
+            assertThat(result.terminalDrayage().version()).isZero();
+            assertThat(result.terminalDrayage().actualPickupAt()).isNull();
+            assertThat(result.allowedActions()).containsExactly("SELECT_FLEET", "RECORD_EMPTY_RETURN");
+            assertThat(result.terminalDrayage().allowedActions()).containsExactly("SELECT_FLEET", "RECORD_EMPTY_RETURN");
+        }
+        verify(mapper, never()).insert(any(com.baiyue.firstleg.terminaldrayage.entity.TerminalDrayageEntity.class));
+    }
+
     @Test
     void domesticHistoryDetailKeepsTheDepartedContainerAndItsUniqueLoadingPlan() {
         ContainerBookingEntity container = container();

firstleg/src/test/java/com/baiyue/firstleg/terminaldrayage/service/TerminalDrayageServiceTest.java

@@ -165,16 +165,61 @@ class TerminalDrayageServiceTest {
     }
 
     @Test
-    void doesNotOfferEmptyReturnWithoutExecutableDrayageAggregate() {
+    void offersEmptyReturnAfterUnloadWithoutDrayageAggregateOrPickupFact() {
         LocalDateTime unloadedAt = LocalDateTime.of(2026, 9, 3, 0, 0);
-        Context context = context("PICKED_UP", unloadedAt);
+        Context context = context("ARRIVED_DESTINATION_PORT", unloadedAt);
         when(mapper.context(11L)).thenReturn(context);
         when(mapper.find(11L)).thenReturn(null);
 
         var result = service.detail(11L);
 
         assertThat(result.status()).isEqualTo("UNLOADED");
+        assertThat(result.allowedActions()).contains("RECORD_EMPTY_RETURN");
+        assertThat(result.actualPickupAt()).isNull();
+        assertThat(result.version()).isZero();
+    }
+
+    @Test
+    void createsReturnAggregateWithoutInventingPickupAndReplaysWithoutWritingAgain() {
+        Context context = context("ARRIVED_DESTINATION_PORT", LocalDateTime.of(2026, 9, 3, 0, 0));
+        when(mapper.lockContext(11L)).thenReturn(context);
+        when(mapper.context(11L)).thenReturn(context);
+        AtomicReference<TerminalDrayageEntity> stored = new AtomicReference<>();
+        AtomicReference<Operation> operation = new AtomicReference<>();
+        when(mapper.lock(11L)).thenAnswer(ignored -> stored.get());
+        when(mapper.find(11L)).thenAnswer(ignored -> stored.get());
+        when(mapper.insert(any(TerminalDrayageEntity.class))).thenAnswer(invocation -> {
+            stored.set(invocation.getArgument(0));
+            return 1;
+        });
+        when(mapper.operation(11L, "return-new")).thenAnswer(ignored -> operation.get());
+        when(mapper.insertOperation(anyLong(), anyLong(), anyString(), anyString(), anyString(), anyInt(), anyLong()))
+            .thenAnswer(invocation -> {
+                operation.set(new Operation(invocation.getArgument(2), invocation.getArgument(4), invocation.getArgument(5)));
+                return 1;
+            });
+        ActualTimeRequest request = new ActualTimeRequest(0, LocalDateTime.of(2026, 9, 4, 9, 0), "手动还柜");
+
+        var result = service.recordEmptyReturn(11L, 7L, "admin", "return-new", request);
+        assertThat(result.status()).isEqualTo("EMPTY_RETURNED");
+        assertThat(result.emptyReturnWarning().status()).isEqualTo("RESOLVED");
+        assertThat(result.actualPickupAt()).isNull();
+        assertThat(result.fleetSupplierId()).isNull();
+        assertThat(result.version()).isEqualTo(1);
         assertThat(result.allowedActions()).doesNotContain("RECORD_EMPTY_RETURN");
+        assertThat(service.recordEmptyReturn(11L, 7L, "admin", "return-new", request)).isEqualTo(result);
+        verify(mapper, times(1)).insert(any(TerminalDrayageEntity.class));
+        verify(carrierSchedules, times(1)).addManualNode(anyLong(), anyLong(), anyString(), anyString(), any());
+    }
+
+    @Test
+    void rejectsReturnBeforeUnloadWithoutAggregateOrPickup() {
+        when(mapper.lockContext(11L)).thenReturn(context("ARRIVED_DESTINATION_PORT", LocalDateTime.of(2026, 9, 3, 0, 0)));
+        assertThatThrownBy(() -> service.recordEmptyReturn(11L, 7L, "admin", "return-early",
+            new ActualTimeRequest(0, LocalDateTime.of(2026, 9, 2, 23, 0), null)))
+            .isInstanceOf(BizException.class).hasMessage("实际还柜时间不能早于提柜或卸柜完成时间");
+        verify(mapper, never()).insert(any(TerminalDrayageEntity.class));
+        verify(carrierSchedules, never()).addManualNode(anyLong(), anyLong(), anyString(), anyString(), any());
     }
 
     @Test

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

@@ -124,7 +124,7 @@ paths:
     get:
       tags: [IAM Resources / IAM 资源]
       summary: 查询当前用户有效权限
-      description: 返回当前有效平台成员权限编码；只要求有效 PLATFORM JWT，不依赖 `platform:role:list`。入库单扣货与解除扣货返回独立写权限 `platform:firstleg:inbound:hold`，不会由 `platform:firstleg:inbound:list` 查看权限自动获得。资金账户充值审核与手工调账分别返回 `platform:finance:recharge:review`、`platform:finance:customer-account:adjust`，并与 `platform:finance:customer-account:list` 只读权限分离。海外仓返回 `platform:overseas-warehouse:dispatch:list`、`platform:overseas-warehouse:dispatch:edit`、`platform:overseas-warehouse:dispatch:cancel`、`platform:overseas-warehouse:dispatch:transfer-delivery`、`platform:overseas-warehouse:outbound:list`、`platform:overseas-warehouse:outbound:create`、`platform:overseas-warehouse:outbound:cancel`、`platform:overseas-warehouse:delivery:list`、`platform:overseas-warehouse:delivery:return`、`platform:overseas-warehouse:delivery:status`、`platform:overseas-warehouse:delivery:documents`、`platform:overseas-warehouse:exception-order:list`、`platform:overseas-warehouse:exception-order:create`、`platform:overseas-warehouse:exception-order:process`、`platform:overseas-warehouse:customer-visit:list`、`platform:overseas-warehouse:customer-visit:edit`；海外 PDA 盘点、移库、换标和现场查询统一返回 `lastleg:pda:operate`，且仅限 `OVERSEAS_WAREHOUSE_PDA_OPERATOR`。货柜双工作台以 `platform:firstleg:container:list/create/edit` 维护国内送柜报关，国外清关提柜独立返回 `platform:firstleg:terminal-drayage:list`、`platform:firstleg:terminal-drayage:document:edit`、`platform:firstleg:terminal-drayage:fleet:edit`、`platform:firstleg:terminal-drayage:pickup-appointment:edit`、`platform:firstleg:terminal-drayage:pickup:confirm`、`platform:firstleg:terminal-drayage:empty-return:confirm`，不以 `container:list/edit` 兼容放行国外操作。派送七类资料管理使用独立写权限 `platform:overseas-warehouse:delivery:documents`；读取和下载仍使用 `platform:overseas-warehouse:delivery:list`。列表权限包含详情和只读辅助接口，写操作独立授权。
+      description: 返回当前有效平台成员权限编码；只要求有效 PLATFORM JWT，不依赖 `platform:role:list`。入库单扣货与解除扣货返回独立写权限 `platform:firstleg:inbound:hold`，不会由 `platform:firstleg:inbound:list` 查看权限自动获得。资金账户充值审核与手工调账分别返回 `platform:finance:recharge:review`、`platform:finance:customer-account:adjust`，并与 `platform:finance:customer-account:list` 只读权限分离。海外仓返回 `platform:overseas-warehouse:dispatch:list`、`platform:overseas-warehouse:dispatch:edit`、`platform:overseas-warehouse:dispatch:cancel`、`platform:overseas-warehouse:dispatch:transfer-delivery`、`platform:overseas-warehouse:outbound:list`、`platform:overseas-warehouse:outbound:create`、`platform:overseas-warehouse:outbound:cancel`、`platform:overseas-warehouse:delivery:list`、`platform:overseas-warehouse:delivery:return`、`platform:overseas-warehouse:delivery:status`、`platform:overseas-warehouse:delivery:documents`、`platform:overseas-warehouse:exception-order:list`、`platform:overseas-warehouse:exception-order:create`、`platform:overseas-warehouse:exception-order:process`、`platform:overseas-warehouse:customer-visit:list`、`platform:overseas-warehouse:customer-visit:edit`；海外 PDA 盘点、移库、换标和现场查询统一返回 `lastleg:pda:operate`，且仅限 `OVERSEAS_WAREHOUSE_PDA_OPERATOR`。货柜双工作台以 `platform:firstleg:container:list/create/edit` 维护国内送柜报关，国外清关提柜独立返回 `platform:firstleg:terminal-drayage:list`、`platform:firstleg:terminal-drayage:document:edit`、`platform:firstleg:terminal-drayage:fleet:edit`、`platform:firstleg:terminal-drayage:pickup-appointment:edit`、`platform:firstleg:terminal-drayage:pickup:confirm`、`platform:firstleg:terminal-drayage:empty-return:confirm`，不以 `container:list/edit` 兼容放行国外操作。派送三类资料管理使用独立写权限 `platform:overseas-warehouse:delivery:documents`；读取和下载仍使用 `platform:overseas-warehouse:delivery:list`。列表权限包含详情和只读辅助接口，写操作独立授权。
       responses:
         '200':
           description: 当前平台成员权限查询成功

scripts/admin-test-env-modules/phase5-terminal-drayage-contract.test.mjs

@@ -3,9 +3,74 @@ import { readFile } from 'node:fs/promises'
 import test from 'node:test'
 import { fileURLToPath } from 'node:url'
 import { normalizeModuleOrder } from '../admin-test-env-acceptance.mjs'
+import { run } from './phase5-terminal-drayage.mjs'
 
 const source = await readFile(fileURLToPath(new URL('./phase5-terminal-drayage.mjs', import.meta.url)), 'utf8')
 
+test('four real command payloads mutate contract fields and preserve remarks and state on conflict', async () => {
+  const marker = 'offline-terminal'
+  const containerBookingId = '9223372036854775806'
+  const containerNo = 'TEST0000001'
+  const actions = ['SELECT_FLEET', 'SCHEDULE_PICKUP', 'RECORD_PICKUP', 'RECORD_EMPTY_RETURN']
+  const paths = ['fleet', 'pickup-appointment', 'pickup', 'empty-return']
+  let state = { containerBookingId, containerNo, version: 0, allowedActions: ['SELECT_FLEET'] }
+  const history = []
+  const commands = new Map()
+  let conflicts = 0
+  let replays = 0
+  const response = (data, code = '200') => ({ http: 200, body: { code, data }, requestId: 'offline-request', traceId: 'offline-trace' })
+  const context = {
+    marker, token: 'offline-only',
+    createdResources: {
+      phase4InboundProducerFixtures: { marker, containers: [{ containerBookingId, containerNo,
+        shippingReady: true, carrierScheduleQueryId: '9223372036854775805', carrierLatestActualAt: '2026-09-09T01:00:00' }] },
+      phase4OverseasPda: { marker, finalStatus: 'COMPLETED', completedContainerFacts: [{ containerBookingId, containerNo }] },
+    },
+    apiSuccess(_module, name, result) { assert.equal(result.body.code, '200', name); return result.body.data },
+    assert(_module, name, _response, passed) { assert.ok(passed, name) },
+    addStep(_module, name, _response, passed) { assert.ok(passed, name) },
+    addCoverageGap() { assert.fail('unexpected missing fixture') },
+    async request(method, path, body, _token, headers) {
+      if (path.includes('/suppliers?')) return response({ records: [{ id: '9223372036854775804', name: 'Offline fleet', status: 'ACTIVE' }] })
+      if (method === 'GET') {
+        if (path.endsWith('/history')) return response(history)
+        if (path.includes('?containerBookingIds=')) return response([state])
+        return response(state)
+      }
+      const actionPath = path.split('/').at(-1)
+      const index = paths.indexOf(actionPath)
+      assert.ok(index >= 0)
+      const field = index < 2 ? 'reason' : 'remark'
+      const forbidden = index < 2 ? 'remark' : 'reason'
+      assert.equal(Object.hasOwn(body, forbidden), false, `${actionPath} must not send ${forbidden}`)
+      const key = headers['Idempotency-Key']
+      const saved = commands.get(key)
+      if (saved) {
+        if (JSON.stringify(saved.body) === JSON.stringify(body)) { replays++; return response(saved.state) }
+        assert.deepEqual(body, { ...saved.body, [field]: `${marker}-DIFFERENT` })
+        conflicts++
+        return response(null, 'A0409')
+      }
+      assert.equal(body[field], marker)
+      assert.equal(body.expectedVersion, state.version)
+      state = { ...state, version: state.version + 1 }
+      if (index === 0) Object.assign(state, { fleetSupplierId: body.fleetSupplierId, fleetSupplierName: body.fleetSupplierName, allowedActions: ['SCHEDULE_PICKUP'] })
+      if (index === 1) state.pickupAppointmentAt = body.pickupAppointmentAt
+      if (index === 2) Object.assign(state, { status: 'UNLOADED', actualPickupAt: body.actualAt, unloadingCompletedAt: '2026-09-09T04:00:00', allowedActions: ['RECORD_EMPTY_RETURN'] })
+      if (index === 3) Object.assign(state, { status: 'EMPTY_RETURNED', actualEmptyReturnAt: body.actualAt, allowedActions: [], emptyReturnWarning: { status: 'RESOLVED' } })
+      history.push({ action: actions[index], fromVersion: index, toVersion: index + 1, reason: body[field] })
+      commands.set(key, { body: structuredClone(body), state: structuredClone(state) })
+      return response(state)
+    },
+  }
+  await run(context)
+  assert.equal(commands.size, 4)
+  assert.equal(replays, 4)
+  assert.equal(conflicts, 4)
+  assert.equal(state.version, 4)
+  assert.equal(context.createdResources.phase5TerminalDrayage.finalStatus, 'EMPTY_RETURNED')
+})
+
 test('terminal drayage runs after pickup-ready and overseas unloading but before final carrier validation', () => {
   const modules = normalizeModuleOrder(['phase4-carrier-nodes'])
   const pickup = modules.indexOf('phase4-carrier-pickup-ready')

scripts/admin-test-env-modules/phase5-terminal-drayage.mjs

@@ -46,12 +46,15 @@ async function command(context, target, action, path, body) {
     `${BASE}/${target.containerBookingId}/${path}`, body, { 'Idempotency-Key': key })
   context.assert(MODULE, `${action}重放状态和版本零漂移`, replay.response,
     JSON.stringify(replay.data) === JSON.stringify(first.data), trace(replay.response), OPTIONS)
-  const changed = path === 'fleet' ? { ...body, reason: `${body.reason}-DIFFERENT` }
+  const changed = ['pickup', 'empty-return'].includes(path) ? { ...body, remark: `${body.remark}-DIFFERENT` }
     : { ...body, reason: `${body.reason}-DIFFERENT` }
   const hashConflict = await context.request('POST', `${BASE}/${target.containerBookingId}/${path}`,
     changed, context.token, { 'Idempotency-Key': key })
   context.addStep(MODULE, `${action}同键异载荷返回A0409`, hashConflict,
     conflict(hashConflict), trace(hashConflict), OPTIONS)
+  const afterConflict = await api(context, 'GET', `${action}冲突后回读聚合`, `${BASE}/${target.containerBookingId}`)
+  context.assert(MODULE, `${action}冲突后聚合零漂移`, afterConflict.response,
+    JSON.stringify(afterConflict.data) === JSON.stringify(first.data), trace(afterConflict.response), OPTIONS)
   return first
 }
 
@@ -104,7 +107,7 @@ export async function run(context) {
 
   const pickupAt = localIso(new Date(Date.parse(`${appointmentAt}Z`) + 60 * 60_000))
   const picked = await command(context, target, '确认实际提柜', 'pickup', {
-    expectedVersion: Number(scheduled.data.version), actualAt: pickupAt, reason: context.marker,
+    expectedVersion: Number(scheduled.data.version), actualAt: pickupAt, remark: context.marker,
   })
   context.assert(MODULE, '实际提柜同步PICKED_UP事实并在已卸柜聚合开放还柜', picked.response,
     picked.data?.status === 'UNLOADED' && picked.data?.actualPickupAt === pickupAt
@@ -115,7 +118,7 @@ export async function run(context) {
   const returnBase = Math.max(Date.parse(`${pickupAt}Z`), Number.isNaN(unloadingAt) ? 0 : unloadingAt)
   const returnedAt = localIso(new Date(returnBase + 60 * 60_000))
   const returned = await command(context, target, '确认实际还柜', 'empty-return', {
-    expectedVersion: Number(picked.data.version), actualAt: returnedAt, reason: context.marker,
+    expectedVersion: Number(picked.data.version), actualAt: returnedAt, remark: context.marker,
   })
   context.assert(MODULE, '实际还柜同步EMPTY_RETURNED并关闭全部动作', returned.response,
     returned.data?.status === 'EMPTY_RETURNED' && returned.data?.actualEmptyReturnAt === returnedAt
@@ -135,6 +138,10 @@ export async function run(context) {
     ['SELECT_FLEET', 'SCHEDULE_PICKUP', 'RECORD_PICKUP', 'RECORD_EMPTY_RETURN'].every((action) => actions.has(action))
       && history.data.every((item) => Number(item?.toVersion) === Number(item?.fromVersion) + 1),
     `actions=${[...actions].join(',')}; ${trace(history.response)}`, OPTIONS)
+  context.assert(MODULE, '提柜和还柜备注写入不可变历史', history.response,
+    ['RECORD_PICKUP', 'RECORD_EMPTY_RETURN'].every((action) =>
+      history.data?.some((item) => item.action === action && item.reason === context.marker)),
+    trace(history.response), OPTIONS)
   context.createdResources.phase5TerminalDrayage = {
     ...context.createdResources.phase5TerminalDrayage,
     containerBookingId: target.containerBookingId, containerNo: target.completed.containerNo,