优化

AGENTS.md

@@ -29,7 +29,7 @@
 | 分柜、柜次、智能排柜、预装/装柜清单、PDA | `firstleg/` | `firstleg/AGENTS.md`，再按 `split/`、`loading/`、`outbound/` 定位；预装/正式装柜详情阶段由 `/loading-plans/{planId}/lifecycle` 按稳定 planId 解析，不从 404 或文案推断 |
 | 合柜报关 / 同柜不可拆组、跨客户合柜、整组分配/移除 | `firstleg/` | `loading/coload/controller/PlatformColoadGroupController.java`、`service/ColoadGroupService.java`、`persistence/ColoadGroupMapper.java`、`src/main/resources/openapi/coload-groups-v1.yaml`；按订单建组并冻结全部可用入仓片段，仅要求同国内仓、同渠道 |
 | 智能装柜入仓码候选与箱数分配 | `firstleg/` | `controller/PlatformSmartLoadingController.java` 的 `/inbound-candidates`、`/plans/{planId}/inbound-assignments`，业务编排 `service/SmartLoadingService.java` |
-| 订舱、船期、拖车、报关 | `firstleg/` | `oceanbooking/`、`portschedule/`、`outbound/dispatch/`、`customs/` |
+| 订舱资料/打印、船期、订舱拥有的拖车、报关 | `firstleg/` | `oceanbooking/`、`portschedule/`、`TruckAppointmentService.java`、`outbound/dispatch/`、`customs/`；拖车不带客户归属，必须绑定 `RELEASED` 订舱及其真实柜，订舱文件联查 `file/AGENTS.md` |
 | 客户账期、费用池、账单、收款、成本、核销 | `finance/` | `finance/AGENTS.md`；费用来源和柜次成本快照再联查 `firstleg/AGENTS.md`，凭证再联查 `file/AGENTS.md` |
 | 入库/柜次应付、直接已付、付款流水与凭证 | `firstleg/`、`finance/`、`file/` | 业务费用与付款快照见 `firstleg/AGENTS.md` 的 `FeePaymentSnapshotValidator`；`/api/platform/finance/v1/vouchers` 上传凭证，File 按 `FINANCE_VOUCHER` 和客户范围校验 |
 | 仓库、往来单位、快递、托盘、库位 | `warehouse/` | `warehouse/AGENTS.md` |

file/AGENTS.md

@@ -18,6 +18,7 @@
 | 财务付款凭证、海外卸柜照片 | 通用业务文件入口 `InternalBusinessFileController.java`、`InternalBusinessFileService.java`；业务类型分别为 `FINANCE_VOUCHER`、`OVERSEAS_UNLOAD_PHOTO`，必须按客户与业务 ID 精确校验 |
 | 报关源文件、完成文件与买单明细导出 | `src/main/resources/openapi/customs-file-and-export-v1.yaml`；文件类别 `LOADING_LIST_CUSTOMS_SOURCE`、`LOADING_LIST_CUSTOMS_RESULT` 均为客户作用域且最多 50MB，异步导出类型 `LOADING_LIST_BUY_DECLARATION_ITEMS` 由 Firstleg Provider 按固定十三列供数 |
 | 订舱文件 | 通用内部业务文件入口，契约 `src/main/resources/openapi/ocean-booking-file-v1.yaml`；类型固定 `OCEAN_BOOKING_DOCUMENT`、`tenantId=订舱customerId`、`businessId=oceanBookingId`，任意格式且最多 50MiB，不得绑定拖车；`BOOKING_CONFIRMATION/BILL_OF_LADING` 文档类型及有效状态由 Firstleg 保存 |
+| 拖车预约附件 | 通用内部业务文件入口；固定 `tenantId=0`、`businessType=TRUCK_APPOINTMENT_ATTACHMENT`、`businessId=appointmentId`，只允许派车单、司机/车辆资料和其他平台附件；提单文件归订舱 `OCEAN_BOOKING_DOCUMENT`，不得复制为拖车附件 |
 | 存储与实体 | `service/LocalQualificationStorage.java`、`MeasurementImageStorage.java`、`entity/FileObjectEntity.java` |
 | 下游 OCR | `client/WeightOcrClient.java` |
 | SQL/配置 | `src/main/resources/db/file.sql`、`application.yml` |

firstleg/AGENTS.md

@@ -35,11 +35,11 @@
 | PDA 拣货与装柜 | `controller/PlatformLoadingPdaController.java`、`loading/controller/PlatformLoadingDeliveryController.java` |
 | 装柜完成跨区事件 | `service/LoadingCompletedOutboxService.java`、`LoadingCompletedOutboxRelay.java`、`repository/LoadingCompletedOutboxRepository.java`、`mapper/LoadingCartonManifestMapper.java`、`client/EventBridgeClient.java`；从 `fl_inbound_order.destination_type` 冻结 V2 `orders[].destinationType=FBA|OVERSEAS`，OVERSEAS 按最终实装与稳定箱码冻结，FBA 可仅冻结箱数；真实生产验收 `src/test/java/com/baiyue/firstleg/service/TaillegRealProducerAcceptanceTest.java`；事件模型见 `../common-event-contract/AGENTS.md` |
 | 海外卸柜完成事件回写 | 内部入口 `controller/InternalOverseasContainerEventController.java`、消费者 `service/OverseasContainerEventConsumer.java`、Inbox `entity/ContainerEventInboxEntity.java` 与 `mapper/ContainerEventInboxMapper.java`；事件模型见 `../common-event-contract/AGENTS.md` |
-| 三期海运订舱、关联候选与出仓前船期资料 | `oceanbooking/controller/PlatformOceanBookingController.java`、`oceanbooking/service/OceanBookingService.java`、`oceanbooking/mapper/OceanBookingMapper.java`、`portschedule/controller/PlatformPortScheduleController.java`；关联候选入口 `/api/platform/v1/ocean-bookings/link-candidates`，订舱契约见 `src/main/resources/openapi/ocean-bookings-v1.yaml`，表结构见 `src/main/resources/db/phase3-ocean-booking-schema.sql` |
+| 三期海运订舱、资料/打印、关联候选与出仓前船期资料 | `oceanbooking/controller/PlatformOceanBookingController.java`、`oceanbooking/service/OceanBookingService.java`、`OceanBookingDocumentService.java`、`OceanBookingPrintService.java`、`oceanbooking/mapper/OceanBookingMapper.java`、`portschedule/controller/PlatformPortScheduleController.java`；文件经 `client/OceanBookingFileClient.java` 进入 File，关联候选 `/api/platform/v1/ocean-bookings/link-candidates`，契约 `src/main/resources/openapi/ocean-bookings-v1.yaml` |
 | 四期国内出仓后船节点定时查询 | `outbound/dispatch/service/OutboundDispatchService.java` 在确认出仓事务内幂等创建现有 `CarrierScheduleQuery`；编排与租约 `portschedule/service/CarrierScheduleQueryScheduler.java`，任务/十节点事实/异常事实/不可变 attempt `CarrierScheduleQueryService.java`，平台查询与人工补录入口 `PlatformCarrierScheduleQueryController.java` 的 `/{queryId}/manual-nodes`；停止只由实际 `EMPTY_RETURNED` 节点触发，不提供无节点停止入口；外部船司/轨迹调用经 `integration-service/`；标准见 `../../docs/四期/船节点标准化契约.md` |
 | 船节点跨区交接事件 | `portschedule/service/CarrierScheduleNodeOutboxService.java`；实际节点落库后发布 `FIRST_LEG_CONTAINER_SHIPPING_NODE_RECORDED` V1，复用 `LoadingCompletedOutboxRepository`/Relay 投 Event Bridge；海外消费见 `../lastleg-service/src/main/java/com/baiyue/lastleg/shipping/service/ContainerShippingNodeConsumer.java` |
 | Firstleg 业务单据编号 | `service/FirstlegDocumentNumberGenerator.java`；当前支持 `OB`、`TA`、`CB`、`CAB`、`LP` 前缀，按北京时间每日独立编号；具体业务归属以各调用服务为准 |
-| 拖车与整柜出仓调度 | `controller/PlatformTruckAppointmentController.java`、`outbound/dispatch/controller/PlatformOutboundDispatchController.java`；按真实 `containerBookingId` 查询聚合和 `gate`、确认离仓，契约 `src/main/resources/openapi/phase3-outbound-dispatch-v1.yaml` |
+| 订舱拥有的拖车与整柜出仓调度 | `controller/PlatformTruckAppointmentController.java`、`service/TruckAppointmentService.java`、`repository/TruckAppointmentRepository.java`、`outbound/dispatch/controller/PlatformOutboundDispatchController.java`；拖车契约 `src/main/resources/openapi/truck-appointments-v1.yaml`，出仓契约 `phase3-outbound-dispatch-v1.yaml`。预约无客户字段，必须绑定 `RELEASED` 订舱及其已分配真实 ISO 柜，同柜最多一条有效预约；提单号和仓库取订舱/柜次权威事实，附件固定平台作用域 |
 | 整柜出口报关 | `customs/container/controller/PlatformContainerCustomsController.java`、`customs/container/controller/MerchantContainerCustomsController.java`、`customs/container/service/ContainerCustomsService.java`、`customs/container/mapper/ContainerCustomsMapper.java`；装柜完成后按柜收集退税资料，多对多覆盖入仓码，开始报关冻结，完成文件逐资料一对一回传，全买单柜由平台确认并通过导出中心取明细；契约 `src/main/resources/openapi/customs-v1.yaml`，基线 `src/main/resources/db/phase3-container-customs-schema.sql`；消费者为 Admin `../../apps/admin-web/src/modules/container-loading/components/ContainerCustomsPanel.vue` 和 Client `../../apps/client-web/src/modules/first-leg/components/CustomsDocumentsDialog.vue` |
 | 买单订单明细导出 Provider | `customs/container/controller/LoadingListBuyDeclarationExportController.java`、`service/LoadingListBuyDeclarationExportService.java`；只为 File 导出中心提供 `LOADING_LIST_BUY_DECLARATION_ITEMS` 的已完成装柜实际买单行，不在 Firstleg 生成文件 |
 | 跨模型桥接 | `loading/bridge/controller/PlatformLoadingModelBridgeController.java` |
@@ -61,9 +61,10 @@
 - 订舱柜型需求至少一项、最多 20 项，数量必须为正整数，容量和限重必须匹配平台柜型规格。起运仓必须是启用的国内中转仓；物流渠道必须来自该仓当前 ACTIVE 价格版本，服务端保存渠道名称快照，渠道失效时失败关闭。
 - 订舱号统一使用 `OB-yyMMdd-####`，按北京时间创建日每日独立递增且单日最多 9999；不得以实体 ID 拼接生成。放舱不要求真实柜号，也不得为满足放舱校验伪造柜号。
 - 订舱列表 `containerCount` 固定为该订舱全部柜型需求 `quantity` 之和，与真实柜关联/解除无关；关联候选只返回 `RELEASED`、剩余数量大于 0 且 `warehouseId + channelCode + containerType` 精确匹配的需求，由服务端集合查询 ACTIVE 分配量。前端不得扇出详情计算或用已关联柜数覆盖该字段，最终关联命令仍须重验目标货柜可修改性。
+- 拖车预约是平台级订舱履约资源，不是客户资源：请求、实体、查询和附件不得恢复 `customerId/customerName`。创建或编辑必须选择 `RELEASED` 订舱及其已分配、有效且带真实 ISO 6346 柜号的柜次，订舱还须有有效提单号和至少一份 ACTIVE `BOOKING_CONFIRMATION` 或 `BILL_OF_LADING`；同一真实柜通过查询锁与唯一约束最多保留一条非取消预约。拖车附件使用 `tenantId=0 + TRUCK_APPOINTMENT_ATTACHMENT + appointmentId`，提单文件继续归订舱，不复制到拖车附件。
 - 四期船节点任务从确认柜子离开国内仓库后启用，必须绑定真实订舱和柜次；十个标准节点、预计/实际时间、异常事实、供应商缺失节点和还柜停止规则统一以 `../../docs/四期/船节点标准化契约.md` 为准。`CarrierScheduleQuery` 的正常业务查询槽位固定为 `Asia/Shanghai` 每日 09:00、12:30、16:00；每分钟任务只扫描已到期 `next_allowed_at`，不是每分钟请求船司。成功、无变化、需人工或永久失败进入下一固定槽位；仅技术性 `RETRYABLE_FAILURE` 在当前槽内按15/30分钟退避，含首次最多3次且不得跨下一槽，实际 `EMPTY_RETURNED` 后停止。错过的正常槽位直接顺延，不在服务恢复时补跑；单轮按受控批次持续领取并受最大任务数保护。租约、调度尝试和内部停止入口不得暴露为平台页面 API，外部失败不得推进业务节点，不得在三期另建查询任务。
 - 国内出口报关在装柜完成后启用，不再阻塞 `LOADED`。整柜 `fl_customs_container.status=COMPLETED` 才通过离仓报关门禁；完成后以系统身份、确定性幂等键立即尝试确认国内离仓，其他门禁未齐时由受控定时补偿重试，禁止部分入仓成功或重复创建离仓/船司查询事实。
-- 国内出仓确认以真实 `containerBookingId` 聚合全部入仓绑定并锁定校验；装柜证据按物理货柜只计算一次，拖车状态和独立船期只作参考。全部门禁在同一事务通过后推进所有技术行、记录一条可见历史并幂等创建 `CarrierScheduleQuery/DEPARTED_WAREHOUSE`，不允许单入仓局部成功。
+- 国内出仓确认以真实 `containerBookingId` 聚合全部入仓绑定并锁定校验；装柜证据按物理货柜只计算一次，PDA `taskId` 仅用于来源审计和任务授权，File 所有权仍固定 `tenantId=0 + containerBookingId`；拖车状态和独立船期只作参考。全部门禁在同一事务通过后推进所有技术行、记录一条可见历史并幂等创建 `CarrierScheduleQuery/DEPARTED_WAREHOUSE`，不允许单入仓局部成功。
 - 手工船节点的预计时间只追加事实，不推进 `latestStandardNode`；携带 `actualAt` 时标准节点序号必须严格大于最新实际节点，重复、相同或回退节点返回冲突。已审核实际时间修正只能更新同一事实的时间/证据，不得制造第二条同节点实际事实或绕过单调推进。
 - 海外卸柜完成事件只接受 `OVERSEAS -> CN` 的 `OVERSEAS_CONTAINER_UNLOADED` V1，并通过内部服务令牌进入。消费者必须校验信封、Payload 哈希、来源货柜和时间顺序，以 event ID + Payload 哈希幂等，使用事件聚合版本阻止乱序覆盖；预计报空时间固定按卸柜照片上传时间加两天计算，实际报空时间可为空。
 - Firstleg 只拥有业务费用及履约事实；Finance 拥有费用入池、账期、账单、收款、成本分摊结果和财务状态。修改费用来源版本、发布条件、柜次归属或体积快照时同步检查 `../finance/src/main/java/com/baiyue/finance/client/FirstlegFeeSourceClient.java`、同目录 `FirstlegCostSnapshotClient.java` 及双方契约测试，不在 Firstleg 复制财务状态机。

scripts/agents-index-contract.ps1

@@ -125,6 +125,22 @@ $orderAgents = Read-RequiredText (Join-Path $backendRoot 'order/AGENTS.md')
 Assert-Contains $orderAgents '`channelCode` 直接来自 Order/Firstleg 权威快照' 'Order 稳定渠道编码'
 Assert-Contains $orderAgents 'InboundCodeAssociationService.java' 'Order 入仓码业务关系入口'
 Assert-Contains $firstlegAgents '/loading-plans/{planId}/lifecycle' 'Firstleg 装柜生命周期入口'
+$fileAgents = Read-RequiredText (Join-Path $backendRoot 'file/AGENTS.md')
+$truckOpenApi = Read-RequiredText (Join-Path $backendRoot 'firstleg/src/main/resources/openapi/truck-appointments-v1.yaml')
+$pdaLoadingApi = Read-RequiredText (Join-Path $workspaceRoot 'apps/pda-uniapp/api/pda-loading.js')
+Assert-Contains $rootAgents '拖车预约由已放舱订舱拥有，不按客户归属' '根订舱拥有拖车语义'
+Assert-Contains $rootAgents '证据以 `taskId + warehouseId` 进入任务专用 API' '根柜级证据入口'
+Assert-Contains $adminAgents '订舱拥有的拖车预约' 'Admin 拖车快速入口'
+Assert-Contains $adminAgents '不选择或提交客户' 'Admin 拖车无客户语义'
+Assert-Contains $backendAgents '订舱拥有的拖车' '后端拖车快速入口'
+Assert-Contains $firstlegAgents '请求、实体、查询和附件不得恢复 `customerId/customerName`' 'Firstleg 拖车无客户边界'
+Assert-Contains $firstlegAgents '同一真实柜通过查询锁与唯一约束最多保留一条非取消预约' 'Firstleg 拖车唯一有效预约'
+Assert-Contains $fileAgents '`businessType=TRUCK_APPOINTMENT_ATTACHMENT`' 'File 拖车平台附件入口'
+Assert-Contains $truckOpenApi 'required: [oceanBookingId, containerBookingId, carrierId, plannedLoadingAt, expectedVersion]' '拖车请求无客户字段'
+Assert-NotContains $truckOpenApi 'customerId:' '拖车 OpenAPI 客户字段'
+Assert-Contains $pdaAgents '当前 `taskId + warehouseId` 走任务专用 API' '国内 PDA 柜级证据入口'
+Assert-Contains $pdaLoadingApi '/first-leg/pda-loading/tasks/${encodeURIComponent(taskId)}/evidence?warehouseId=' '国内 PDA 证据查询 API'
+Assert-NotContains $pdaLoadingApi '/inbounds/${encodeURIComponent(inboundId)}/loading/evidence' '国内 PDA 旧入仓证据 API'
 $mapperModuleAgents = @(
     @{ Module = 'audit-service'; Application = 'BaiyueAuditApplication.java' },
     @{ Module = 'auth'; Application = 'BaiyueAuthApplication.java' },
@@ -431,6 +447,10 @@ $criticalPaths = @(
     'apps/admin-web/src/modules/unified-orders/pages/UnifiedOrdersView.vue',
     'apps/admin-web/src/modules/ocean-bookings/api/platformOceanBookings.ts',
     'apps/admin-web/src/modules/ocean-bookings/pages/OceanBookingsView.vue',
+    'apps/admin-web/src/modules/ocean-bookings/components/OceanBookingDocumentsPanel.vue',
+    'apps/admin-web/src/modules/ocean-bookings/components/OceanBookingPrintDialog.vue',
+    'apps/admin-web/src/modules/trucking/components/TruckAppointmentForm.vue',
+    'apps/admin-web/src/modules/trucking/api/platformTrucking.ts',
     'apps/admin-web/src/core/routing/navigationRecovery.ts',
     'apps/admin-web/src/core/routing/navigationRecovery.test.ts',
     'apps/admin-web/src/modules/overseas-warehouse/api/outbounds.ts',
@@ -513,6 +533,10 @@ $criticalPaths = @(
     'baiyue-firstleg/firstleg/src/main/resources/openapi/loading-lists-v1.yaml',
     'baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/loading/coload/controller/PlatformColoadGroupController.java',
     'baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/loading/coload/service/ColoadGroupService.java',
+    'baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/service/OceanBookingDocumentService.java',
+    'baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/service/OceanBookingPrintService.java',
+    'baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/TruckAppointmentService.java',
+    'baiyue-firstleg/firstleg/src/main/resources/openapi/truck-appointments-v1.yaml',
     'baiyue-firstleg/file/src/main/resources/openapi/customs-file-and-export-v1.yaml',
     'baiyue-firstleg/order/src/main/java/com/baiyue/order/service/InboundCodeAssociationService.java',
     'baiyue-firstleg/order/src/main/java/com/baiyue/order/service/UnifiedOrderQueryService.java',
@@ -693,5 +717,5 @@ if ($failures.Count -gt 0) {
     exit 1
 }
 
-Write-Host "AGENTS 索引合同通过：$checked 项检查，覆盖快速表唯一性、部署单元、前端模块、Client active 路由、业务编号与内部 ID 隔离、装柜清单生命周期、四期范围漂移、仓库主档唯一权威、订舱候选与柜量语义、整柜出仓与船节点单调性、Gateway 覆盖、PDA 页面/运行配置/独立更新/语言预留/能力开关、人工分段验收链、Maven 模块、Lastleg 海外安全投影、同步 Trace、关键入口和排除目录。" -ForegroundColor Green
+Write-Host "AGENTS 索引合同通过：$checked 项检查，覆盖快速表唯一性、部署单元、前端模块、Client active 路由、业务编号与内部 ID 隔离、装柜清单生命周期、订舱拥有拖车与柜级证据、四期范围漂移、仓库主档唯一权威、订舱候选与柜量语义、整柜出仓与船节点单调性、Gateway 覆盖、PDA 页面/运行配置/独立更新/语言预留/能力开关、人工分段验收链、Maven 模块、Lastleg 海外安全投影、同步 Trace、关键入口和排除目录。" -ForegroundColor Green
 exit 0