baiyue-firstleg/AGENTS.md

# 头程与海外仓后端项目指引

## 适用范围与定位

- 本文件适用于 `baiyue-firstleg/` Maven 多模块仓库，包含国内头程与海外区域服务；进入具体服务后继续读取该服务的 `AGENTS.md`。
- 本层只负责：服务边界、跨服务契约、数据库部署总入口、阶段路由和通用验证。Controller、Service、DTO、SQL 细节以模块级指引为准。
- 普通任务先读本文件和目标模块指引；聚合构建/架构问题再读 `README.md`、`pom.xml`、`docs/头程项目目录结构与服务说明.md`。
- 平台/客户层级与权限公共语义见 `../docs/平台客户层级与权限契约.md`；国内/海外 Token、双区域 API 和跨区事件公共契约见 `../docs/跨区域认证与服务通信契约.md`。本文件只保留后端执行所需摘要。

## 不可突破的产品与数据边界

- 当前产品只有“平台—客户”两级。`tenant_id=0` 是平台技术作用域；`tenant_id>0` 是客户隔离键，不得新增租户切换、租户选择或租户级 RBAC。
- 公共仓库、往来单位、快递、托盘、库位统一归属 `tenant_id=0`；订单、文件、费用等客户数据按客户 `tenant_id>0` 隔离。不得跨库 Join 或信任客户端客户 ID。
- 国内订单交易状态归 `order`，头程履约/入库状态归 `firstleg`，财务账期、账单、收款、成本与核销归 `finance`；全部仓库 ID、类型、状态、地址和能力主档归国内 `warehouse`，海外 `warehouse-overseas-service` 只维护引用同一国内 warehouseId 的库位、托盘和资源锁。海外尾程订单、入仓计划、库存业务与海外本土业务归 `lastleg-service`，海外公网入口归 `gateway-overseas`。文件对象归 `file`，第三方适配归 `integration-service`；跨服务通过内部客户端、DTO、事件和服务令牌协作。
- 普通业务成功/失败使用 HTTP 200 + body `code`（成功为字符串 `"200"`）；认证、基础设施和网关拒绝可使用真实 401/403/503。

## 服务路由（按关键词定位）

| 任务关键词 | 首选服务 | 先看入口 |
|---|---|---|
| 登录、Token、密码、注册与顶层授权快照 | `auth/` | `auth/AGENTS.md`；海外 Token 只携带稳定身份与版本，角色、权限和冻结海外仓从登录/刷新响应顶层快照读取，海外 Gateway 再按 IAM 安全投影失败关闭校验 |
| 客户档案、成员、审核、RBAC、授权快照 | `iam/` | `iam/AGENTS.md` |
| 客户建档默认尺寸初始化与补偿 | `iam/`、`firstleg/` | IAM `CustomerDimensionRuleInitializationService` 持久化意图、`CustomerDimensionInitializationRelay` 后台投递；Firstleg 内部入口 `/internal/firstleg/v1/customer-dimension-configs/defaults`，未 `READY` 不得审核通过 |
| 消息中心、站内通知、消息模板、收件箱 | `iam/` | `iam/AGENTS.md`，再按 `src/main/java/com/baiyue/iam/notification/` 定位；业务事件生产者回到所属服务 |
| 订单、货物、快照、状态、幂等、Outbox | `order/` | `order/AGENTS.md`；统一列表由 `UnifiedOrderQueryService` 组合交易与履约投影，仍固定显示 `PENDING_REVIEW` 并提供审核动作：Order 为 `SUBMITTED` 时必须优先返回 `PENDING_REVIEW/APPROVE_ORDER`，不得被 Firstleg 准备中状态覆盖 |
| 客户头程订单中文批量导入 | `order/` | `MerchantBatchImportService.java`、`MerchantWarehouseCatalogClient.java`、`MerchantPricingCatalogClient.java`、`order-v1.yaml`；模板和导入都按当前客户读取动态地址、全部有效仓库与渠道，最多 50 行，只创建草稿，支持 `PARTIAL/ATOMIC` |
| 平台修改客户原始申报、履约渠道变更与跨服务同步 | `order/`、`firstleg/` | Order `OrderDeclarationUpdateService.java`、`OrderInboundOutboxPublisher.java`、`order-v1.yaml`；Firstleg `OrderDeclarationSyncService.java`、`OrderDeclarationSyncMapper.java`、`firstleg-v1.yaml`。只更新申报快照；渠道变化先失败关闭校验履约可逆性与重新计价，成功后由版本化 `ORDER_DECLARATION_UPDATED_V1` 幂等同步，不覆盖实测、箱码或已确认费用 |
| 平台订单批量审核预览 | `order/` | `PlatformFirstLegOrderController.java` 的 `/batch-review-preview`、`BatchOrderReviewPreviewService.java`、`BatchOrderReviewPreviewResponse.java`、`order-v1.yaml`；一次请求固定用订单与货物两次批量查询返回同序快照，不允许前端逐票请求详情，逐项资格以 `canApprove/blockReason` 为准 |
| 履约分配、入库、测量、箱规算法、审核、FBA 计费 | `firstleg/` | `firstleg/AGENTS.md`；客户四档箱规与 `ADD/MULTIPLY` 默认算法从 `CustomerDimensionConfigService` 进入，单箱测量和最终计价分别由 `CustomerDimensionWeightingService`、`FbaPricingService` 保存并消费服务端快照 |
| 入库单扣货、解除、凭证与履约门禁 | `firstleg/`、`file/` | Firstleg `InboundHoldService`、`InboundHoldGuard`、`InboundHoldEvidenceService`；平台接口 `/api/platform/inbounds/{inboundId}/hold`、`/release`、`/evidence`。扣货不改变 Order 主状态，命令使用入库聚合版本和幂等键；凭证只按客户、入库单及 `INBOUND_HOLD_EVIDENCE` 精确归属，所有装柜、PDA 拣货和国内出仓写入口统一复用门禁并失败关闭 |
| 称重确认、整票库位块与 PDA 资源结算 | `firstleg/`、`warehouse/` | Firstleg `MeasurementLocationOccupationService.java`、`InboundMeasurementService.java`、`MeasurementSubmissionService.java`、`WarehousePalletLocationClient.java`；Warehouse `LocationBlockService.java` 与 `location-block-v1.yaml`。称重确认尽力建块、提交时再次补齐，库位指引失败不阻断测量主流程；部分拣货整段转移给余量子单，整票拣完才整块释放，A0 共享资源按 `reservationId` 区分 |
| 客户专属价格簿、柜级阶梯运费与受控调价 | `firstleg/` | `PlatformPriceBookService.java`、`ActivePriceBookEstimator.java`、`FbaPricingService.java`、`pricing/ContainerTierAmountAllocator.java`、`InboundFeeDetailService.java`、`fba-pricing-v1.yaml`。`customerId=0` 为公共报价，正数为客户专属版本；计价优先专属 ACTIVE、缺失才回退公共 ACTIVE。同柜区域重量阶梯按实际成员计费量聚合命中并守恒分摊，装柜变化只重算未锁定客户费用；人工计费量调整限基准上下 10%，私人仓尾程派送费只绑定 `PRIVATE` 入库单；一件代发 `WAIT_PALLETIZE` 允许在预装确认前试算，写费用时必须保留托盘化状态 |
| Firstleg 内部模块化与依赖基线 | `firstleg/` | `firstleg/docs/firstleg-internal-modularization-baseline.md`、`firstleg/scripts/analyze-firstleg-dependencies.mjs`；价格簿查询和客户统计按端口/适配器切片，不改变服务与数据库边界 |
| Mapper 新增、移动、Bean 缺失与扫描遗漏 | 目标持久化服务 | 所有 Mapper 显式 `@Mapper`，启动类按服务根包注解过滤扫描；先运行 `node scripts/mapper-scan-contract.mjs`，再按目标模块执行 `test-compile/test`，不得等部署启动发现 |
| 脚本管理、全量验证、测试造数与诊断 | 仓库根 `scripts/`；服务专属脚本留在 `<service>/scripts/` | 先读 `scripts/AGENTS.md` 和 `scripts/README.md`；Admin HTTP 内部模块继续读 `scripts/admin-test-env-modules/README.md`。新增入口必须登记用途、目标环境、数据副作用和报告位置，并通过 `scripts/script-documentation-contract.test.mjs` |
| 分柜、柜次、智能排柜、预装/装柜清单、真实柜号后补、PDA | `firstleg/` | `firstleg/AGENTS.md`，再按 `split/`、`loading/`、`outbound/` 定位；创建柜次时原子生成唯一预装计划，加入入仓码时同步建立关联，不设推送步骤；预装/正式详情由 `/loading-plans/{planId}/lifecycle` 解析。真实集装箱号不阻塞订舱关联、计划确认或 PDA task 创建，可在 `EDITING/LOADING` 首次补录，但必须在 PDA 最终完成前存在。上传以幂等键绑定包含文件内容的请求哈希，完全重放不得再次调用 File |
| 合柜报关 / 同柜不可拆组、跨客户合柜、整组分配/移除 | `firstleg/` | `loading/coload/controller/PlatformColoadGroupController.java`、`service/ColoadGroupService.java`、`persistence/ColoadGroupMapper.java`、`src/main/resources/openapi/coload-groups-v1.yaml`；按订单建组并冻结全部可用入仓片段，仅要求同国内仓、同渠道 |
| 全局智能装柜候选、柜次、占位与移除 | `firstleg/`、`order/` | Firstleg `controller/PlatformSmartLoadingController.java` 的 `/inbound-candidates`、`/containers`、`/plans/{planId}/inbound-assignments`、`/pending-review-assignments`、`/group-assignments`、`/unpicked-items`，业务编排 `service/SmartLoadingService.java`；待审核事实由 `client/PendingReviewOrderClient.java` 经内部令牌查询 Order `/internal/order/v1/pending-review-orders` 与 `PendingReviewOrderQueryService.java` 的权威 `SUBMITTED/PENDING_REVIEW` 行。候选四态只用于筛选展示，资格以 `canAssign` 为准；待审核或待测量可先占位，确认预装和启动 PDA 前仍须进入 `WAIT_SPLIT`；计划明细总量/余量由 Order 原始申报或最新已审核测量补齐，调整时重验权威数量；人工加入允许跨渠道，智能推荐仍按柜次渠道；同柜组整组分页、分配和移除 |
| 客户入库结果与头程费用确认 | `firstleg/` | `controller/MerchantInboundBillingController.java`、`service/MerchantInboundBillingService.java`、`FbaPricingService.java`，接口 `/api/merchant/v1/first-leg/orders/{orderId}/inbound-billing` 与 `/confirm`；客户按登录态范围读取并以费用版本和幂等键确认当前 `SENT` 费用，确认后锁定 |
| 订舱资料/打印、船期、订舱级拖车、报关 | `firstleg/` | `oceanbooking/`、`portschedule/`、`TruckAppointmentService.java`、`outbound/dispatch/`、`customs/`；拖车只绑定 `RELEASED` 订舱，不携带客户、柜次、装柜计划或真实柜号，每订舱最多一张非终态预约，订舱文件联查 `file/AGENTS.md` |
| 目的港码头拖车与还空预警 | `firstleg/` | `terminaldrayage/controller/PlatformTerminalDrayageController.java`、`service/TerminalDrayageService.java`、`src/main/resources/openapi/terminal-drayage-v1.yaml`；按 `containerBookingId` 聚合并与订舱级拖车分离，引用 Warehouse `ACTIVE + TRUCKING` 供应商，提柜/还柜复用船节点，服务端按海外卸柜完成时间加 72 小时计算还空预警 |
| 客户账期、费用池、账单、入仓码联查、收款、成本、核销 | `finance/` | `finance/AGENTS.md`；客户账单行 `inboundCode` 由 `FinanceQueryService` 从费用来源快照提供，Client 复用头程入仓关系详情；费用来源和柜次成本快照再联查 `firstleg/AGENTS.md`，凭证再联查 `file/AGENTS.md` |
| 客户资金账户、充值、授信、冻结、结算与跨区资金指令 | `finance/`、`lastleg-service/`、`common-event-contract/`、`event-bridge-service/` | 国内 `FinanceWalletService.java` 持有唯一 CNY 主账和不可变流水；平台、客户、内部入口见 `PlatformFinanceWalletController.java`、`ClientFinanceWalletController.java`、`InternalFinanceWalletController.java` 与 `finance-wallet-v1.yaml`。海外采购和换标由 Lastleg `wallet/` 发布 `WALLET_COMMAND_REQUESTED`，Finance 冻结、结算或释放后发布 `WALLET_COMMAND_COMPLETED` 回传，不跨区域同步调用钱包 |
| 柜级公共费用跨客户分摊 | `firstleg/`、`finance/` | Firstleg `PlatformContainerFeeDetailController.java`、`ContainerFeeDetailService.java`、`container-fees-v1.yaml` 按柜内真实客户与订单原子创建 `allocation-groups`；金额合计必须等于总额，分组审核、驳回、调整、作废均整组处理，Finance 只消费各客户不可变来源快照 |
| 海外业务费用来源跨区入池 | `lastleg-service/`、`common-event-contract/`、`event-bridge-service/`、`finance/` | Lastleg `financefee/` 审核五类海外费用并发布 `BUSINESS_FEE_SOURCE_CHANGED` 完整快照；Event Bridge 对 `targetRegion=CN` 定向投递 Finance `/internal/finance/v1/business-fee-source-events`；Finance 按事件 ID、Payload 哈希、来源系统/费用 ID/版本幂等入池，`PAYABLE + DIRECT_PAID` 单独形成已确认成本且不进入 AP 待结算 |
| 入库/柜次应付、直接已付、付款流水与凭证 | `firstleg/`、`finance/`、`file/` | 业务费用与付款快照见 `firstleg/AGENTS.md` 的 `FeePaymentSnapshotValidator`；`/api/platform/finance/v1/vouchers` 上传凭证，File 按 `FINANCE_VOUCHER` 和客户范围校验 |
| 仓库、往来单位、快递、托盘、库位 | `warehouse/` | `warehouse/AGENTS.md` |
| 供应商、国内整柜库存与出入库 | `warehouse/` | `warehouse/AGENTS.md`；OpenAPI `warehouse/src/main/resources/openapi/supplier-v1.yaml`、`domestic-container-v1.yaml` |
| 客户运营统计、在途柜量 | `firstleg/` | `firstleg/AGENTS.md`；OpenAPI `firstleg/src/main/resources/openapi/customer-statistics-v1.yaml` |
| 平台操作日志与审计查询 | `audit-service/` | `audit-service/AGENTS.md`；平台查询接口 `/api/platform/v1/audit/logs` |
| 资质、导出、导出退避重试、测量图片、文件下载 | `file/` | `file/AGENTS.md`；法人身份证选填，可在已有营业执照后单独补传或替换；`PENDING` 且已有失败尝试的退避任务可人工立即到期并复用当前投递，不创建并发任务 |
| 路由、CORS、JWT 入口、访问域 | `gateway/` | `gateway/AGENTS.md` |
| 百度/Amazon/OCR/第三方适配 | `integration-service/` | `integration-service/AGENTS.md` |
| 海外 API 路由、海外 Token、Audience/JWKS | `gateway-overseas/` | `gateway-overseas/AGENTS.md` |
| 海外 IAM 状态与权限版本投影 | `lastleg-service/security/` | `lastleg-service/AGENTS.md`；内部入口 `/internal/lastleg/security/v1/events`、`/validate`；消费三类 IAM 安全事件并为海外 Gateway 提供 fail-closed 校验，投影表归 `baiyue_lastleg` |
| 尾程订单、海外入仓计划、换标、库存、采购、本土卡车 | `lastleg-service/` | `lastleg-service/AGENTS.md`，尾程订单控制从 `LastlegOrderController.java`、`LastlegOrderCommandService.java` 进入，再按 `inboundplan/`、`relabel/`、`inventory/`、`procurement/`、`trucking/` 定位 |
| 尾程订单控制、柜级预览与入仓计划转换 | `lastleg-service/`、`warehouse-overseas-service/` | `orders/container-summaries` 按 `sourceContainerBookingId` 跨客户聚合并分页返回全部稳定来源柜，已完成计划转换的柜仍用于接柜仓查询与修改，生成资格由 `allPlansReady/pendingPlanCount` 表达，详情返回全柜数据。`inbound-plans/container-preview` 由 `InboundPlanService.java` 返回服务端分组、托数、阻断项及快照版本/哈希；`ContainerInboundPlanConversionCoordinator.java` 校验同一快照并以唯一 Saga 先向 `WarehousePalletBatchService.java` 批量预留真实托盘，再本地原子生成剩余独立计划并确认资源，失败只补偿未确认资源，同柜重放不得新建第二批。暂扣/解除和固定八行人工节点进入 `LastlegOrderCommandService.java`；命令按订单版本、客户范围和幂等键执行，暂扣中的订单不得进入排车或出库 |
| 海外入仓分页、FBA 预约、PDA 柜号签收与入仓 | `lastleg-service/` | 平台入口 `inboundplan/controller/InboundPlanController.java`、`InboundPlanQueryMapper.java`、`InboundFbaAppointmentService.java`；PDA 公网入口 `inboundplan/pda/controller/ReceivingContainerController.java`、`ReceivingContainerService.java`，旧 planNo/allocationId Controller 已移除 |
| 海外仓排车查询、候选与智能预排 | `lastleg-service/` | `dispatch/controller/DispatchQueryController.java`、`SmartDispatchController.java`；草稿柜、托盘锁和预排归 `dispatch/`，只读排车和预排创建独立开关，不自动开放编辑、取消、发车、PDA 出库或派送 |
| 海外排车执行、PDA 出库、派送与一件代发 | `lastleg-service/` | `dispatch/controller/DispatchController.java`、`dispatch/pda/controller/DispatchPdaController.java`、`delivery/controller/DeliveryTransferController.java`、`OutboundPdaController.java`、`MerchantDeliveryController.java`，一件代发库存归 `dropship/`；统一经 `gateway-overseas/`，设备端正式入口继续查 `../apps/pda-overseas-uniapp/AGENTS.md` |
| 海外异常退回、库存恢复与客户回访 | `lastleg-service/`、`file/` | `exceptionorder/`、`inventory/command/`、`customervisit/`；异常按版本和幂等键执行 `PENDING → PROCESSING → COMPLETED`，完成证据固定归 `OVERSEAS_EXCEPTION_EVIDENCE`。派送退回明细只能来自原出库拣货事实，退回海外仓时校验真实目标托盘/库位并以 `RETURN_STOCK_IN` 恢复库存后，原子完成异常单与派送 `RETURNED`；回访仍以 Lastleg 客户范围和派送状态为准 |
| 一件代发 SKU/箱唛与暂扣跨区协同 | `order/`、`firstleg/`、`common-event-contract/`、`lastleg-service/` | Order `InternalOrderCargoController` 提供强制 SKU 与每箱数量；Firstleg `InboundCartonLabelService` 冻结箱唛 SKU，`DropshipPalletizationService` 完成清点、组托和封托，智能排柜只按 `SEALED` 整托分配，并消费 `OverseasInboundOrderDetainedChangedV1`；Lastleg `dropship/` 建立库存并发布暂扣变更 |
| 客户海外仓贴标、转运、废弃与退货换标 | `lastleg-service/` | `relabel/`、`relabel/pda/`、`transfer/`、`discard/` 的 Merchant/PDA Controller 和 Service；换标下单按历史入仓库存选择，每个我方箱唛只形成一条箱任务，支持箱唛、SKU 和组合换标，SKU 子项不重复冻结。涉及箱唛换标时冻结派送方式，PDA 逐箱作业并上传完工照片，仓库复核后必须由客户查看证据确认，之后卡车进入预排车，自提/快递进入换标出库待创建；不伪造已入库单。Client 消费端 `../html/client-web/src/modules/overseas-warehouse/`，统一经 `gateway-overseas/` |
| 海外仓 PDA 盘点、移库、托盘、换标与查询 | `lastleg-service/`、`warehouse-overseas-service/` | Lastleg `pda/stocktake/`、`pda/move/`、`pda/warehouse/`、`palletops/`、`relabel/pda/`；托盘作业保留托盘-入仓单组成明细，合托通过入仓计划托盘分配和合托记录留痕；`pallet-operations/relabel-disassemble` 按换标单箱唛快照解析原库存仓位，在一个幂等事务内移动对应冻结箱数并绑定已扫码目标托盘，同时更新换标明细和未开始拣货的出库托盘/箱唛快照；出库可扫描托盘但后台按托盘下各入仓单箱数核平；契约 `lastleg-service/src/main/resources/openapi/overseas-pda-operations-v1.yaml`；物理托盘流转与补偿进入 Warehouse `InternalPdaPalletTransitionController`，设备端入口是否开放以 `../apps/pda-overseas-uniapp/AGENTS.md` 为准 |
| 国内船节点向海外接柜门禁事件 | `firstleg/`、`common-event-contract/`、`lastleg-service/` | Firstleg `portschedule/service/CarrierScheduleNodeOutboxService.java` 发布 `FirstLegContainerShippingNodeRecordedV1`；Lastleg `shipping/service/ContainerShippingNodeConsumer.java` 单调消费，只有实际 `PICKUP_READY` 及以后节点允许海外 PDA 候选进入可收货 |
| 海外仓库目录、海外库位、海外托盘、资源锁 | 国内仓库目录归 `warehouse/`，海外资源归 `warehouse-overseas-service/` | `warehouse/AGENTS.md`、`warehouse-overseas-service/AGENTS.md`；海外库只保存国内 warehouseId 引用 |
| Lastleg 内部模块化与依赖基线 | `lastleg-service/` | `lastleg-service/docs/lastleg-internal-modularization-baseline.md`、`lastleg-service/scripts/analyze-lastleg-dependencies.mjs`；只用于约束服务内部依赖，不改变服务和数据库边界 |
| PDF 标签、审计、跨区双向事件 | `print/`、`audit-service/`、`event-bridge-service/` | 事件模型先读 `common-event-contract/AGENTS.md`；国内真实生产验收 `firstleg/.../TaillegRealProducerAcceptanceTest.java`、海外真实消费验收 `lastleg-service/.../TaillegRealConsumerAcceptanceTest.java`；可靠投递与 CN/OVERSEAS 目标路由读 `event-bridge-service/AGENTS.md` |

## 公共模块快速索引

| 关键词 | 模块与入口 |
|---|---|
| 公共依赖版本 | `platform-bom/pom.xml`；统一管理公共组件版本，不放业务实现 |
| 通用响应、分页、异常、基础实体与导出契约 | `common-core/`；从 `ApiResponse.java`、`PageResult.java`、`BizException.java`、`ExportContracts.java` 定位 |
| Web 异常、请求关联/Trace、同步出站传播、Long ID 序列化 | `common-web/`；从 `GlobalExceptionHandler.java`、`CorrelationIdFilter.java`、`TraceParent.java`、`FeignTraceRequestInterceptor.java`、`RestClientTraceInterceptor.java`、`LongIdJacksonConfiguration.java` 定位 |
| JWT、JWKS、会话校验与认证用户 | `common-security/`；从 `JwtAuthenticationFilter.java`、`JwtClaimsMapper.java`、`AccessTokenSessionValidator.java` 定位 |
| Springdoc/OpenAPI 自动配置 | `common-openapi/`；从 `BaiyueOpenApiAutoConfiguration.java`、`OpenApiProperties.java` 定位 |
| 业务审计注解、脱敏、Outbox 与投递 | `common-audit/`；从 `BusinessAudit.java`、`BusinessAuditAspect.java`、`SensitiveDataSanitizer.java`、`AuditOutboxPublisher.java` 定位 |
| 跨区域事件信封、Payload 与哈希 | `common-event-contract/`；继续读该目录 `AGENTS.md` |

## 全量验收路由

- 当前订单与客户、入库测量与计费、国内货柜履约、海外仓业务及财务统一进入全量验收；按本次链路读取对应业务域/专题文档，不以历史规划终点阻断跨服务联调或回归。
- `auth`、`iam`、`warehouse`、`order`、`firstleg`、`file`、`finance`、`integration-service` 及出仓相关能力按各自模块契约协作；状态、权限、数据库和 OpenAPI 以当前实现及已确认契约为准。

## 国内头程与海外仓协同

- 国内头程 Auth 是唯一用户账号和 Token 签发方；Admin/Client 共用一套前端和用户体系，海外仓不得另建登录或权限模型。
- 统一使用 RS256/JWKS。国内登录/刷新时由 Auth 同时签发国内 Token 和短时海外 Token；前端统一认证层按国内/海外 API Base 自动选择。国内服务叠加 Redis 会话校验；海外 Token 只携带稳定身份、客户/仓库范围和版本声明，不携带角色或权限集。海外 Gateway 本地验签后必须通过 Lastleg 安全投影取得当前角色/权限并失败关闭，再清除外部伪造头、写入受内部服务令牌保护的可信身份上下文；海外服务不得访问国内 Redis，海外业务请求不得经国内 Gateway 中转。
- 头程装柜完成向海外建尾程单、海外 PDA 卸柜完成向国内回写货柜报空事实，以及后续费用来源和财务回传，统一走 MQ Outbox/Inbox 事件链；事件不携带用户 JWT，服务身份由 MQ TLS/ACL 或内部服务令牌负责。跨区事件契约、幂等和死信分别查 `common-event-contract/`、`event-bridge-service/` 与目标消费者。
- 海外浏览器请求只进入 `gateway-overseas/`，由其路由到 `lastleg-service/`、`warehouse-overseas-service/` 及海外部署的公共服务；不得经国内 `gateway/` 中转。`lastleg-service` 不读取头程数据库，`warehouse-overseas-service` 不读取尾程订单库。

## 契约、数据库与验证入口

- 跨服务修改先检查调用方 `client/`、被调用方 Controller/DTO、`src/main/resources/openapi/` 和双方契约测试；禁止共享领域 Entity。
- 修改 Java 方法、构造器、Controller、Client、DTO 或 Mapper 参数签名时，先用 `rg` 定向查找符号及旧参数形态，并同步更新 `src/main/`、`src/test/`、Mock、Fixture、契约测试和脚本中的全部调用点。新增可选参数也必须补齐旧测试调用，不能因生产调用已更新就视为完成。
- 所有生产 MyBatis Mapper 接口必须显式标记 `@Mapper`；每个持久化服务只允许在启动类使用一次服务根包 `@MapperScan(..., annotationClass = Mapper.class)`，不得新增子域包白名单或分散的 `*MapperConfiguration`。新增或移动 Mapper 后先运行 `node scripts/mapper-scan-contract.mjs`，全量后端回归也会在 Maven 前执行该门禁。
- 平台后台存在正式列表页时，`*:list` 同时授权列表、详情及只读辅助接口；`create`、`edit`、`delete`、`status`、`approve`、`review`、`export`、`upload`、`complete` 等操作保持独立。当前未上线，不兼容旧独立 `*:view`，Controller 不得使用 `hasAnyAuthority(list, view)`，OpenAPI 和角色初始化只保留 `*:list`。
- 供应商查询接口固定只使用 `platform:supplier:list`；IAM 中 `platform:supplier:list` 是正式菜单资源，`platform:supplier:view` 必须停用/移除，不得重新提升或兼容。
- 权限语义变更必须同步 Controller `@PreAuthorize`、OpenAPI、模块权限 SQL、IAM 菜单资源、统一增量脚本和契约测试。并行模块任务不得覆盖菜单与权限总控已写入共享 SQL 或权限契约的改动。
- 数据库只访问所属服务库。模块表结构位于 `<module>/src/main/resources/db/`；当前开发阶段直接更新最新模块基线和 `deploy/sql/头程数据库统一增量-MySQL8.sql`，不为历史开发数据新增兼容迁移。已有名称含 `migration` 的脚本仅作现有结构来源和开发追溯，部署说明见 `deploy/sql/README.md`。
- 后端同样遵守根指引中的“开发数据和上传文件可丢弃”边界：不得为现有开发库孤儿文件、旧文件归属或历史部分失败新增删除补偿接口、兼容复用、回填或清理链路；只修复当前正式上传与持久化路径，既有开发文件由人工重新上传。
- 通用配置在 `config/nacos/{local,cn}/`；服务日志、上传文件、`target/`、`reports/` 不属于源码。
- Java 签名变更的最低编译门禁是 `mvn -pl <module> -am test-compile`，它必须在部署前完成并覆盖测试源码；有行为变化时继续运行 `mvn -pl <module> -am test`。`-DskipTests` 可跳过测试执行但仍须保留测试编译，`-Dmaven.test.skip=true` 会跳过测试编译，不得作为签名变更的交付验证。全量验证仍使用 `mvn -DskipTests validate`、`mvn test`；不要在本地启动 Java/Nacos/数据库，除非用户明确要求。
- `AGENTS.md` 索引维护完成后运行 `./scripts/agents-index-contract.ps1`；脚本只读源码目录和指定指引，验证根快速表唯一性、部署单元、Client active 路由、海外仓业务范围漂移、仓库主档唯一权威、订舱关联候选与柜量语义、整柜出仓与船节点单调性、海外 Gateway 覆盖、PDA 运行配置/独立更新/语言预留、人工分段验收链、Lastleg 海外安全投影、同步 Trace、模块覆盖、关键入口与排除目录，不访问 HTTP、数据库或部署环境。
- Mapper 注册静态合同为 `scripts/mapper-scan-contract.mjs`、`mapper-scan-contract.test.mjs`：自动发现聚合模块、生产 `*Mapper` 接口、服务启动类和分散扫描配置，不启动 Spring、不连接数据库；遗漏注解、扫描根漂移或重新引入子域扫描时直接失败并输出类与文件路径。
- 单服务镜像构建/部署从 `Jenkinsfile.service`、`deploy/docker/Dockerfile`、`deploy/scripts/deploy-built-service.sh` 进入；新镜像启动失败或健康检查失败时只允许回滚到同服务先前镜像，并保持任务失败，离线合同见 `scripts/deploy-built-service-rollback.test.mjs`。实际部署仍须当前对话明确授权。

## 全量 HTTP 验收脚本路由

- 脚本管理的唯一总索引是 `scripts/README.md`，最近执行规则是 `scripts/AGENTS.md`。仓库级脚本、Admin 内部模块、服务局部合同和部署脚本的目录归属以这两个文件为准，不再通过无范围搜索猜测入口。
- 全量验收唯一指向测试环境 HTTP：平台端执行 `scripts/admin-test-env-acceptance.mjs`，客户端执行 `scripts/client-test-env-acceptance.mjs`；入库测量与计费专项场景才单独执行 `scripts/client-phase2-test-env-acceptance.mjs`，不替代客户端全量入口。
- Client 快速下单定向验收使用 `scripts/client-quick-order-test-env-acceptance.mjs`，只验证批量草稿接口、逐行隔离和幂等行为，不提交、不审核，也不替代 Client 全量入口。
- 固定客户待审核订单使用 `scripts/create-pending-review-orders.mjs`；固定“IT测试”与“义乌仓”、随机真实线路并推进至 `WAIT_SPLIT` 使用 `scripts/it-test-wait-split-bulk.mjs`。二者都是造数入口，不属于全量验证；会写目标环境且不自动清理成功数据。
- Admin 总入口默认按模块列表覆盖平台全链路；需要定位单个业务时使用 `--modules <name>`，模块名称和静态合同先查 `scripts/admin-test-env-modules/README.md`。
- 订舱与拖车跨服务完整状态链由 Admin 注册模块 `service-center-flow` 验证，必须复用本轮已放舱订舱并由总入口展开依赖，不得直接执行模块文件或借历史数据。
- 尾程公网控制由 `phase4-tail-order-controls` 在海外 PDA 前验证整柜接柜仓变更与恢复、单/批目的仓变更、单/批合托标记、CSV 导出、订单费用、暂扣/解除、八个人工节点和逐票人工计划；目的港码头拖车由 `phase5-terminal-drayage` 在卸柜后验证选车队、预约提柜、实际提柜和实际还柜，`phase4-carrier-nodes` 只读核验最终船节点终态。
- 这些脚本会创建、更新或最终停用测试数据，必须在当前对话明确授权测试环境验收后执行，并保存 JSON 报告；未授权不得请求 Gateway。
- 后端 Maven、前端 `pnpm test/typecheck`、PDA `node --test` 和数据库 Dry-run 都是本地质量检查，不属于全量 HTTP 验收。
- Java 模块、OpenAPI 覆盖、JaCoCo 与 SpotBugs 聚合摘要使用 `node scripts/java-quality-summary.mjs`；默认仅报告存量缺口，是否阻断由显式 `--require-*` 参数决定，输出位于 `target/` 时不得作为业务事实或提交物。
- HTTP 全量通过后，才进入 Admin/Client 真实页面调用、浏览器样式和 PDA 页面/设备验收；自动化 HTTP 通过不代表视觉验收完成。
- 修改脚本目录、入口或说明后，至少运行 `node --test scripts/script-documentation-contract.test.mjs`；修改 `AGENTS.md` 后继续运行 `./scripts/agents-index-contract.ps1`。两者均为离线只读合同，不能代替真实 HTTP 验收。

## 业务域文档入口

- 订单与客户：`../docs/订单与客户/README.md`、`../docs/订单与客户/订单与客户头程订单闭环设计.md`
- 入库测量与计费：`../docs/入库测量与计费/README.md`、`../docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`、需求确认清单及联调报告
- 国内货柜履约：`../docs/国内货柜履约/README.md`、`../docs/国内货柜履约/国内货柜履约开工门禁.md`、`../docs/国内货柜履约/国内货柜履约开发规划.md`、`../docs/国内货柜履约/国内货柜履约需求确认表.md`、页面与原型清单
- 海外仓业务：`../docs/海外仓业务/README.md`；海外入口 `gateway-overseas/`，尾程与入仓库存 `lastleg-service/`，海外仓储资源 `warehouse-overseas-service/`
- 海外仓全流程：以正式 Controller、前端路由、权限、SQL 与跨区事件契约为范围依据；海外接柜、入仓、库存、库内服务、排车、出库、派送、一件代发、异常退回和客户回访进入 `lastleg-service/`，国内 SKU/箱唛及暂扣协同进入 `order/`、`firstleg/`、`common-event-contract/`
- 财务：`../docs/财务管理/README.md` 中已确认的范围、对象、状态和接口约束

全量验收任务再读取对应阶段进度表、验收报告和证据矩阵；普通代码定位只读取当前链路涉及的范围、契约、模块指引和代码。