feat: complete overseas customer and PDA workflows

2026-09-04 12:59:37 +08:00
parent a274d029bb
commit 54cb9ceade
60 changed files with 1598 additions and 277 deletions
@@ -19,7 +19,7 @@
 5. 平台身份只检查 `app_code=PLATFORM`，部分 Gateway/模块守卫没有再次断言登录主体 `tenant_id=0`；客户身份也应断言 `tenant_id>0`。
 6. 平台代客业务审计当前可能记录平台主体 `tenant_id=0`，导致按目标客户查询审计日志漏记；应同时保留操作者作用域和目标客户归属。
 7. Integration 内部令牌存在可预测默认值，必须改为环境显式注入并保持启动失败保护。
-8. 模块级 `AGENTS.md`、README、分期文档和 OpenAPI 仍把兼容 `tenant_id` 描述成真实上级租户，三期存在重新按三级租户开发的返工风险。
+8. 模块级 `AGENTS.md`、README、分期文档和 OpenAPI 仍把兼容 `tenant_id` 描述成真实上级租户，国内货柜履约存在重新按三级租户开发的返工风险。

 ## P2 最小加固

@@ -63,6 +63,6 @@
 - 订单履约：`order/`、`firstleg/` 的生产代码与测试，不修改 SQL、OpenAPI、README、AGENTS。
 - 公共审计事件：`common-audit/`、`audit-service/`、`integration-service/`、`event-bridge-service/`、`common-openapi/` 的生产代码与测试。
 - Warehouse/File/迁移：`warehouse/`、`file/` 生产代码与测试，以及各模块数据库脚本、`deploy/sql/`、`config/nacos/`；平台公共资源（含往来单位、快递公司）作用域迁移为 `0`，客户私有资源保持客户 ID。
- 文档契约：模块 `AGENTS.md`、README、OpenAPI 和一期/二期/三期指导性文档；不修改 Java 或 SQL。
+- 文档契约：模块 `AGENTS.md`、README、OpenAPI 和订单与客户/入库测量与计费/国内货柜履约指导性文档；不修改 Java 或 SQL。

 跨模块新接口、公共 DTO、事件结构和公共仓库作用域变更由主对话统一裁决，单个修改对话不得自行扩展范围。
@@ -54,7 +54,7 @@

 重点检查商户下单、平台代客、列表详情、状态流转、货物/参与方/历史/备注、幂等、Outbox、IAM 资格查询和 Warehouse 主数据调用。必须区分当前隔离键 `tenant_id` 与往来单位语义的 `customer_id`。

-### 对话 C：Firstleg 履约与二期入库
+### 对话 C：Firstleg 履约与入库

 负责目录：`firstleg/`。

@@ -78,11 +78,11 @@

 重点检查表、索引、唯一键、增量迁移、种子数据和环境配置中的客户隔离维度；盘点 `tenant_id = 0`、`10001` 等保留值的真实用途；提出上线前只读数据核验 SQL，不执行写操作。

-### 对话 G：测试、OpenAPI、文档与三期防返工
+### 对话 G：测试、OpenAPI、文档与国内货柜履约防返工

 只负责 `src/test/`、各模块 `src/main/resources/openapi/`、`docs/` 和模块 `README` / `AGENTS.md`，不修改生产代码。

-检查测试是否覆盖跨客户拒绝、平台跨客户、内部调用归属和端域隔离；检查契约及文档是否仍把当前 `tenant_id` 描述成真实上级租户；定向核对三期文档，列出可能诱导后续按三级租户开发的内容。
+检查测试是否覆盖跨客户拒绝、平台跨客户、内部调用归属和端域隔离；检查契约及文档是否仍把当前 `tenant_id` 描述成真实上级租户；定向核对国内货柜履约文档，列出可能诱导后续按三级租户开发的内容。

 ## 五、每个审计对话的统一输出格式

@@ -1,21 +1,21 @@
-# 二期、三期业务功能回归报告
+# 入库测量与计费、国内货柜履约业务功能回归报告

 测试时间：2026-08-07

 ## 测试范围

- 二期：企业资质、平台审核、公共主数据、客户计费规则、头程下单、入库测量、称重、计费与入库。
- 三期：虚拟柜、智能装柜、预装、PDA 拣货和最终装柜清单。
+- 入库测量与计费：企业资质、平台审核、公共主数据、客户计费规则、头程下单、入库测量、称重、计费与入库。
+- 国内货柜履约：虚拟柜、智能装柜、预装、PDA 拣货和最终装柜清单。
 - 测试环境：本机 MySQL、Redis、Nacos；隔离服务端口 `19300` 到 `19306`。未停止、未占用用户的 `192xx` 服务端口。
 - 测试结束后已停止本次启动的 Gateway 和全部 `193xx` 隔离服务；未停止 MySQL、Redis、Nacos 或用户服务。

 ## 项目索引结论

- 二期主状态和测量、计费、入库编排在 `firstleg`；订单货物在 `order`；仓库、托盘、库位、往来单位在 `warehouse`；文件在 `file`。
- 三期智能装柜、预装、PDA 拣货、装柜清单均在 `firstleg`。
+- 入库测量与计费主状态和测量、计费、入库编排在 `firstleg`；订单货物在 `order`；仓库、托盘、库位、往来单位在 `warehouse`；文件在 `file`。
+- 国内货柜履约智能装柜、预装、PDA 拣货、装柜清单均在 `firstleg`。
 - 当前 `tenant_id` 在业务上代表客户归属；公共主数据应使用 `tenant_id=0`，订单服务仅可读取公共仓库和公共往来单位。

-## 二期结果
+## 入库测量与计费结果

 结果：未通过，主链路在创建头程订单草稿前被阻断。

@@ -29,9 +29,9 @@
 2. 当前平台往来单位 API 对 `tenantId=0` 返回 `A0422`，校验信息为“最小不能小于 1”；公共主数据无法经 API 创建或查询。
 3. 旧订单请求仍强制 `carrierId`、`carrierName`。本次不传时返回 `A0422`。根据最新业务确认，头程业务不存在“承运商”概念，这一历史字段、校验、分配接口和费率依赖应移除或改为船司领域模型，不能继续作为下单前置条件。

-结论：在修复公共主数据 `tenantId=0` API 契约，并移除订单承运商强制校验前，二期无法从下单继续验证测量、称重、计费和入库。
+结论：在修复公共主数据 `tenantId=0` API 契约，并移除订单承运商强制校验前，入库测量与计费无法从下单继续验证测量、称重、计费和入库。

-## 三期结果
+## 国内货柜履约结果

 结果：通过。

@@ -59,13 +59,13 @@
 ## 构建与脚本观察

 - 离线全量模块测试执行到 `firstleg`：211 项中 1 项失败。失败项是 `InboundParentChildSqlContractTest`，原因是统一 SQL 已使用最终索引命名，但测试仍断言旧索引名 `uk_inbound_parent_sequence`；属于 SQL 契约断言滞后，不是 Java 业务断言失败。
- 二期验收脚本需要 PowerShell 7 的 `SkipHttpErrorCheck`，而本机只有 Windows PowerShell 5；测试时使用了临时 UTF-8 BOM 兼容副本。
+- 入库测量与计费验收脚本需要 PowerShell 7 的 `SkipHttpErrorCheck`，而本机只有 Windows PowerShell 5；测试时使用了临时 UTF-8 BOM 兼容副本。
 - 原脚本引用的 `c7.png`、`c8.png` 示例图片未随项目提供；测试目录使用最小 PNG 仅验证上传协议。
 - 初始 File 隔离 JAR 未包含当前资质包上传端点，使用当前编译类启动后接口通过。发布前应重新打包 File 服务，避免运行包与源码不一致。

 ## 建议处理顺序

-1. 移除头程订单及二期计费中的承运商强制字段、校验和分配逻辑；如需要船司，改为独立船司主数据，不复用往来单位承运商。
+1. 移除头程订单及入库测量与计费计费中的承运商强制字段、校验和分配逻辑；如需要船司，改为独立船司主数据，不复用往来单位承运商。
 2. 修复平台公共主数据 API：允许且仅允许平台身份使用 `tenantId=0` 创建、查询公共仓库和往来单位。
 3. 为订单下单提供可选的公共发货单位选择，或明确订单客户快照不再依赖 `SHIPPER` 往来单位。
-4. 完成以上两项后，重新执行二期全链路：下单、审核、入仓单、测量、OCR 称重、费用试算、费用确认、入库完成。
+4. 完成以上两项后，重新执行入库测量与计费全链路：下单、审核、入仓单、测量、OCR 称重、费用试算、费用确认、入库完成。
@@ -7,7 +7,7 @@
 - `file-service` 统一承载任务、可靠调度、通用 XLSX、存储、过期清理、下载鉴权和指标。
 - File 不跨库读取 IAM、Order、Warehouse 等业务数据；业务服务只实现标准只读 Provider。
 - MQ 只传任务标识，不传筛选条件、业务行、Token 或文件。
- 一期存储是 `FILE_STORAGE_ROOT` 目录且按单节点部署；多实例前必须使用跨主机共享卷或对象存储。
+- 订单与客户存储是 `FILE_STORAGE_ROOT` 目录且按单节点部署；多实例前必须使用跨主机共享卷或对象存储。
 - 当前首个类型为 `CUSTOMER_LIST`，由 IAM 提供数据。

 ## 2. 执行链路
@@ -54,7 +54,7 @@
 - 下载中心继续使用统一任务表，不依赖 MQ 查询状态。
 - 新业务服务只实现公共 Provider 契约并注册导出类型，不写任务、Excel、存储、下载代码。
 - File Service 统一负责 XLSX、存储、下载鉴权、过期清理、可观测性。
- 代码层面支持 File Service 多实例（租约、条件抢占、`lease_owner` 齐备）；**部署层面一期按单节点运行**，因为存储是宿主机目录（§11.1）。滚动发布期间的短暂双实例由租约保证安全。
+- 代码层面支持 File Service 多实例（租约、条件抢占、`lease_owner` 齐备）；**部署层面订单与客户按单节点运行**，因为存储是宿主机目录（§11.1）。滚动发布期间的短暂双实例由租约保证安全。

 ### 2.2 非目标

@@ -65,8 +65,8 @@
 - 不以 Redis 作为任务、重试或幂等的事实来源。
 - 不实现用户自定义列编排器。
 - 不实现导出断点续传：每次执行从零重写整个文件（见 §9.5）。
- 一期不引入 MinIO/OSS（见 §21 决策 6），但存储访问必须走接口抽象。
- 一期不引入 Testcontainers（见 §21 决策 8）。
+- 订单与客户不引入 MinIO/OSS（见 §21 决策 6），但存储访问必须走接口抽象。
+- 订单与客户不引入 Testcontainers（见 §21 决策 8）。

 ## 3. 核心原则

@@ -821,7 +821,7 @@ Provider 可将 Token 实现为签名后的最大 ID、截止时间或数据库
 | 截止时间戳 + 按 `updated_at` 过滤 | ✅ | ⚠️ 取决于是否有历史版本 | ❌ |
 | 数据库快照（如 MySQL 一致性读快照、或导出前落临时表） | ✅ | ✅ | ✅ |

-**一期 `CUSTOMER_LIST` 采用"签名后的最大 ID"，即只保证不混入新增数据，不保证修改与删除的一致性。** 这对客户列表导出是可接受的——导出期间恰好有客户资料被改动的概率极低，且影响仅是个别字段取值偏新。
+**订单与客户 `CUSTOMER_LIST` 采用"签名后的最大 ID"，即只保证不混入新增数据，不保证修改与删除的一致性。** 这对客户列表导出是可接受的——导出期间恰好有客户资料被改动的概率极低，且影响仅是个别字段取值偏新。

 因此对外表述应为“**不会混入导出开始后新增的数据**”，而非笼统的“数据快照一致”。若某个导出类型确实需要完整快照（如财务对账），该 Provider 需自行实现临时表或一致性读方案，本契约不阻止，但也不代为实现。

@@ -916,15 +916,15 @@ baiyue:

 将现有 `LocalExportStorage` 提取为接口 `ExportStorage`（`create` / `size` / `load` / `delete`），实现类 `SharedDirectoryExportStorage` 保持当前行为与对象键格式 `exports/{taskId}/{uuid}.xlsx`。Consumer、API、Reconciler 只依赖接口。

-一期不引入对象存储（§21 决策 6），但接口就位后未来替换为 MinIO/OSS 不需要改动调用方。**对象键始终由 File Service 生成与校验，业务服务不得提供。**
+订单与客户不引入对象存储（§21 决策 6），但接口就位后未来替换为 MinIO/OSS 不需要改动调用方。**对象键始终由 File Service 生成与校验，业务服务不得提供。**

 **普通宿主机目录挂载不构成"共享存储"，它只在同一宿主机的容器之间共享。** 这是第一版的一处不实表述：部署已有的 `FILE_UPLOADS_HOST_DIR:/data/files` 是宿主机 bind mount，若 File Service 的两个实例被调度到**不同物理机**，各自看到的是各自宿主机上的独立目录——A 实例生成的文件，B 实例既读不到也删不掉，表现为：下载随机 404（请求打到没有该文件的实例）、过期清理留下永久孤儿文件。

-因此一期存储的明确边界，**二选一，必须在部署前确认**：
+因此订单与客户存储的明确边界，**二选一，必须在部署前确认**：

 | 方案 | 约束 | 适用 |
 |---|---|---|
-| **A. 单节点部署**（一期默认） | File Service 只允许 1 个实例；若用编排系统需固定节点亲和，禁止自动扩容 | 1000 用户量级，导出低频，单实例足够 |
+| **A. 单节点部署**（订单与客户默认） | File Service 只允许 1 个实例；若用编排系统需固定节点亲和，禁止自动扩容 | 1000 用户量级，导出低频，单实例足够 |
 | **B. 跨主机共享卷** | 挂载 NFS / CephFS / 云盘共享卷到同一路径 | 需要多实例时 |

 选 A 时必须注意：**代码不得因此引入任何单实例假设**——租约、`lease_owner`、条件更新全部保留，因为滚动发布期间会短暂存在两个实例，且方案 B 随时可能启用。单实例是部署约束，不是设计约束。
@@ -1020,7 +1020,7 @@ spring:
 - 文件删除成功或确认不存在后，任务才能标记 `EXPIRED`；删除失败保持原状并重试 + 告警（沿用现有实现）。
 - `file_export_outbox` 的 `SENT` 行保留 7 天后**物理删除**（每日一次，每次 ≤5000 行分批删除）。清理必须限定 `status = 'SENT'`，绝不能删除 `PENDING` / `CLAIMED` 行——它们是尚未送达的命令。
 - `file_export_task` 终态行长期保留（下载中心需要历史），当前量级无需归档。
- 存储：一期按 §11.1 方案 A（单节点）或方案 B（跨主机共享卷）二选一，部署前必须确认。宿主机 bind mount 只在同一主机内共享，**不足以支撑跨主机多实例**。
+- 存储：订单与客户按 §11.1 方案 A（单节点）或方案 B（跨主机共享卷）二选一，部署前必须确认。宿主机 bind mount 只在同一主机内共享，**不足以支撑跨主机多实例**。
 - 对象键由 File Service 生成和校验，业务服务不得提供。

 ## 16. 基础设施落地
@@ -1333,7 +1333,7 @@ RocketMQ NameServer/Broker 就绪
 - 存储的多实例边界已明确（§11.1），不把宿主机 bind mount 当作跨主机共享存储。
 - MQ 不承担延迟与业务重排；Reconciler 是唯一重派通道；DLQ 只承载损坏消息。
 - Outbox 与任务均有租约，无“领取后崩溃即永久卡死”的路径。
- 至少一次投递、幂等、租约、Outbox、Reconciler、DLQ、指标与告警全部纳入一期实现。
+- 至少一次投递、幂等、租约、Outbox、Reconciler、DLQ、指标与告警全部纳入订单与客户实现。
 - 新业务类型能通过 Provider 契约 + 受控注册接入，不复制客户导出代码。

 ## 21. 已定型决策
@@ -1342,12 +1342,12 @@ RocketMQ NameServer/Broker 就绪

 | # | 决策 | 取值 | 理由 |
 |---|---|---|---|
-| 1 | 一期是否含 MQ | 含 | 业务方已定。可靠性由数据库承担，MQ 引入不降低稳定性 |
+| 1 | 订单与客户是否含 MQ | 含 | 业务方已定。可靠性由数据库承担，MQ 引入不降低稳定性 |
 | 2 | MQ 客户端 | `rocketmq-spring-boot-starter` 2.3.3，Remoting 协议 | 需要显式控制消费返回语义；不引入 Proxy 少一个可失效组件；同时删除 `firstleg` 的 Stream 死依赖。Boot 3.2.9 兼容性与 `rocketmq-client 5.3.1` 传递版本已实证核验，见 §6.1 |
-| 3 | Outbox 是否抽公共模块 | 一期不抽，`file_export_outbox` 独立建表并作为全仓基线 | 一期只有一个真实使用者，过早抽象会把接口定错。`order` 的 Outbox 目前**根本没有发布器**，是独立待修问题；后续收敛时以本表结构为准（含 `lease_owner`/`lease_until`/`next_retry_at`），命名统一为 `<模块>_outbox` |
+| 3 | Outbox 是否抽公共模块 | 订单与客户不抽，`file_export_outbox` 独立建表并作为全仓基线 | 订单与客户只有一个真实使用者，过早抽象会把接口定错。`order` 的 Outbox 目前**根本没有发布器**，是独立待修问题；后续收敛时以本表结构为准（含 `lease_owner`/`lease_until`/`next_retry_at`），命名统一为 `<模块>_outbox` |
 | 4 | 契约放哪 | 放入 `common-core` 的 `com.baiyue.common.core.export` 包，**不新建模块**，模块总数仍为 18 | 契约是 file 与 iam 双方共用的 HTTP 结构。放 `file` 内会迫使 iam 依赖 `file-service`（拖入 POI/MyBatis/任务表实体，且业务服务反向依赖 file）；新建模块则多一个模块。放 `common-core` 两全：双方已通过 `common-web` 传递依赖到它，pom 都不用改。与 `common-event-contract` 不合并——后者是跨区域事件信封（含 `sourceRegion`/`payloadHash` 等无关字段），强行复用会互相牵制 |
-| 5 | Prometheus | 一期补 `micrometer-registry-prometheus`；服务端由运维落地 | 无 registry 则 §13 全部指标无处可采，等于没有可观测性 |
-| 6 | 文件存储 | 一期共享目录挂载 + `ExportStorage` 接口抽象 | 1000 用户、7 天保留、单文件 ≤50MB，总量在 GB 级，共享目录足够。引入 MinIO 多一个有状态组件与备份负担。接口就位后替换不改调用方 |
+| 5 | Prometheus | 订单与客户补 `micrometer-registry-prometheus`；服务端由运维落地 | 无 registry 则 §13 全部指标无处可采，等于没有可观测性 |
+| 6 | 文件存储 | 订单与客户共享目录挂载 + `ExportStorage` 接口抽象 | 1000 用户、7 天保留、单文件 ≤50MB，总量在 GB 级，共享目录足够。引入 MinIO 多一个有状态组件与备份负担。接口就位后替换不改调用方 |
 | 7 | 导出类型注册 | Nacos 受控配置 + 代码内置服务白名单 + 启动强校验 | 纯 Nacos 有 SSRF 面；纯代码注册每加类型都要发版。两者结合：配置只能从白名单里选 |
 | 8 | Testcontainers | 不引入，集成测试连测试环境 Broker | 全仓无 Testcontainers 先例，RocketMQ 容器需同时起 NameServer+Broker 并处理 `brokerIP1`，投入产出比低于直接用测试环境 |
 | 9 | 新旧双轨 | 不双轨，阶段 3 直接停用旧 Worker | 旧 `claim()` 不识别 `next_retry_at` 与 `dispatch_version`，双轨会提前执行退避中的任务。回滚靠配置开关，不靠双轨 |
@@ -1359,8 +1359,8 @@ RocketMQ NameServer/Broker 就绪
 | 15 | Outbox 失败终态 | 取消 `DEAD`，发送无限退避重试 + 告警 | 设终态会让 Broker 长期故障时任务静默停滞，违背 §2.1 的“提交成功的任务最终一定被调度”。靠告警驱动人工介入，Broker 恢复后自动追平 |
 | 16 | 续租方式 | 独立 watchdog 线程按 60 秒周期，覆盖全执行期 | 挂在批次循环里会漏掉最终 `write()`/压缩/落盘阶段，慢磁盘下大文件会在临成功时被误判失联并反复重跑 |
 | 17 | 时间基准 | 全部走数据库 `CURRENT_TIMESTAMP(3)` | 实例时钟偏差会导致提前抢占（两实例同写一任务）或延迟恢复 |
-| 18 | 多实例部署 | 代码支持，**一期部署按单节点**；需多实例时先上跨主机共享卷 | 宿主机 bind mount 只在同主机内共享，跨主机会导致下载随机 404 与永久孤儿文件（§11.1） |
-| 19 | 快照强度 | 一期只保证“不混入导出开始后新增的数据”，不冻结修改与删除 | 最大 ID 游标的固有限制。对客户列表可接受；需要完整快照的类型由该 Provider 自行实现临时表或一致性读（§10.2） |
+| 18 | 多实例部署 | 代码支持，**订单与客户部署按单节点**；需多实例时先上跨主机共享卷 | 宿主机 bind mount 只在同主机内共享，跨主机会导致下载随机 404 与永久孤儿文件（§11.1） |
+| 19 | 快照强度 | 订单与客户只保证“不混入导出开始后新增的数据”，不冻结修改与删除 | 最大 ID 游标的固有限制。对客户列表可接受；需要完整快照的类型由该 Provider 自行实现临时表或一致性读（§10.2） |
 | 20 | 权限取值时点 | 创建与人工重试时校验，执行阶段不校验；不存权限快照 | 执行在后台无用户会话，无法重新鉴权。已受理即视为已授权，代价与已知缺口写明于 §10.4 |
 | 21 | 毒消息处置 | 独立 DLQ Handler 自动将匹配的 Outbox 置 `QUARANTINED`、任务置 `FAILED` | 人工隔离无法保证在 Reconciler 10 分钟补投窗口内完成；定位字段放 User Properties，避免依赖损坏 payload |

@@ -2,7 +2,7 @@

 ## 目的与口径

-本基线覆盖当前官方 22 个 Maven 模块、15 个可执行服务之间的 OpenFeign、`RestClient`、`WebClient` 与 JDK `HttpClient` 调用。海外安全 Inbox/投影属于 Lastleg 内部子域，不再作为独立服务节点。基线用于识别同步依赖方向、在线请求深度、后台中继、超时、重试、熔断、幂等、错误映射和失败传播，不改变 Finance 或四期业务状态机。
+本基线覆盖当前官方 22 个 Maven 模块、15 个可执行服务之间的 OpenFeign、`RestClient`、`WebClient` 与 JDK `HttpClient` 调用。海外安全 Inbox/投影属于 Lastleg 内部子域，不再作为独立服务节点。基线用于识别同步依赖方向、在线请求深度、后台中继、超时、重试、熔断、幂等、错误映射和失败传播，不改变 Finance 或海外仓业务业务状态机。

 “存在双向服务边”不等于“一次在线请求会递归调用”。每条边必须继续区分：

@@ -106,7 +106,7 @@ File 的五个导出 Provider、Order→Firstleg 入库 Outbox、该入库消费

 ### 已完成的第一个 REQUEST 边退出

-`IAM → Firstleg` 的 `CustomerDimensionRuleClient` 默认尺寸初始化已经从 REQUEST WRITE 改为可靠后台编排。IAM 与客户主档同事务持久化稳定 `initializationKey` 的任务，显式维护 `PENDING/READY/FAILED`，由租约调度重试并提供诊断查询和人工重试；审批通过与下单资格在未 READY 时失败关闭。此边现在仅属于 BACKGROUND，在线五服务强连通分量实际拆为 Auth↔IAM 与 Order↔Firstleg 两个子环，未触碰财务、Event Bridge 或四期业务状态机。
+`IAM → Firstleg` 的 `CustomerDimensionRuleClient` 默认尺寸初始化已经从 REQUEST WRITE 改为可靠后台编排。IAM 与客户主档同事务持久化稳定 `initializationKey` 的任务，显式维护 `PENDING/READY/FAILED`，由租约调度重试并提供诊断查询和人工重试；审批通过与下单资格在未 READY 时失败关闭。此边现在仅属于 BACKGROUND，在线五服务强连通分量实际拆为 Auth↔IAM 与 Order↔Firstleg 两个子环，未触碰财务、Event Bridge 或海外仓业务业务状态机。

 ### Order↔Firstleg 第二阶段结论

@@ -143,7 +143,7 @@ File 的五个导出 Provider、Order→Firstleg 入库 Outbox、该入库消费
 | IAM/Firstleg | `mvn -pl iam,firstleg -am test` |
 | Firstleg/Finance | `mvn -pl firstleg,finance -am test`；业务口径先由财务总控确认 |
 | Firstleg/File 或 File/Finance | `mvn -pl firstleg,file,finance -am test`，按实际消费者缩小模块集 |
-| Lastleg 原始 HTTP | `mvn -pl lastleg-service,warehouse-overseas-service,file -am test`；不改变四期状态机 |
+| Lastleg 原始 HTTP | `mvn -pl lastleg-service,warehouse-overseas-service,file -am test`；不改变海外仓业务状态机 |
 | 全部治理阶段收口 | `mvn -DskipTests validate` 后执行 `mvn test` |

 以上均为本地离线验证；未经明确授权不启动 Java/Nacos/数据库，不执行 SQL、部署或测试环境 HTTP 验收。
@@ -43,7 +43,7 @@ baiyue-firstleg/
 ├─ auth/                         # 统一登录与账号凭据
 ├─ iam/                          # 租户、成员、角色、权限、企业审核
 ├─ order/                        # 头程订单中心
-├─ firstleg/                     # 履约任务、二期入库、测量与计费
+├─ firstleg/                     # 履约任务、入库、测量与计费
 ├─ warehouse/                    # 仓库主数据、托盘与库位资源
 ├─ finance/                      # 财务账期、账单、收付款与核销
 ├─ lastleg-service/              # 海外尾程、入仓、库存与本土业务
@@ -93,9 +93,9 @@ baiyue-firstleg/
 | `gateway-overseas` | `gateway-overseas` | 9300 | 无 | 海外区域 API 入口、海外 Audience/JWKS 校验及海外服务路由 |
 | `auth` | `auth-service` | 9100 | `baiyue_auth` | 登录、刷新 Token、退出、商户注册、账号密码和账号内部管理 |
 | `iam` | `iam-service` | 9201 | `baiyue_iam` | 租户、企业资料、企业审核、成员、角色、权限、按钮权限、个人资料和授权快照 |
-| `firstleg` | `firstleg-service` | 9202 | `baiyue_firstleg` | 履约任务与分配；二期入库单、测量审核、FBA 计费、费用发布和完成入库编排；不是订单主数据服务 |
+| `firstleg` | `firstleg-service` | 9202 | `baiyue_firstleg` | 履约任务与分配；入库单、测量审核、FBA 计费、费用发布和完成入库编排；不是订单主数据服务 |
 | `order` | `order-service` | 9204 | `baiyue_order` | 订单草稿、编辑、提交、详情、状态历史、货物、往来单位快照、内部备注和 Outbox |
-| `warehouse` | `warehouse-service` | 9205 | `baiyue_warehouse` | 仓库、地址、服务能力、往来单位、快递公司，以及二期托盘、库位、预占和占用；往来单位不单独拆服务 |
+| `warehouse` | `warehouse-service` | 9205 | `baiyue_warehouse` | 仓库、地址、服务能力、往来单位、快递公司，以及入库测量与计费托盘、库位、预占和占用；往来单位不单独拆服务 |
 | `file` | `file-service` | 9206 | `baiyue_file` | 企业资质文件、公共异步导出下载、入库测量图片及重量 OCR 调用协作 |
 | `print` | `print-service` | 9207 | 无 | 无状态 PDF 渲染服务；调用方传入完整标签数据，服务在内存中生成一次性多页 PDF |
 | `integration-service` | `integration-service` | 9210 | 无 | 百度 OCR、Amazon SP-API 等第三方适配器和启停状态；默认关闭外部调用 |
@@ -128,13 +128,13 @@ Order 负责订单草稿、提交、平台处理状态、货物、参与方和

 ### 5.5 `firstleg/`：头程履约中心

-Firstleg 承担订单提交后的履约任务、操作分配与历史，以及二期入库单查询、测量回传、人工测量、审核、异常放行、FBA 计费、费用发布和完成入库状态编排。
+Firstleg 承担订单提交后的履约任务、操作分配与历史，以及入库单查询、测量回传、人工测量、审核、异常放行、FBA 计费、费用发布和完成入库状态编排。

 订单主单和货物主数据仍属于 Order；托盘和库位资源属于 Warehouse；图片对象属于 File；OCR 供应商协议属于 Integration。Firstleg 只保存自身业务状态、快照和逻辑引用，通过内部 DTO 调用其他服务，不复制对方领域模型。

 ### 5.6 `warehouse/`：仓库与仓储资源

-Warehouse 负责仓库、地址、服务能力、往来单位、快递公司，以及二期托盘、库位、预占和占用资源。往来单位只是 Warehouse 下的主数据配置，保存在 `baiyue_warehouse.wh_partner`，不创建独立服务和数据库。
+Warehouse 负责仓库、地址、服务能力、往来单位、快递公司，以及入库测量与计费托盘、库位、预占和占用资源。往来单位只是 Warehouse 下的主数据配置，保存在 `baiyue_warehouse.wh_partner`，不创建独立服务和数据库。

 Firstleg 通过内部接口发起托盘库位预占、确认和释放，只保存逻辑引用与入库快照。容量、共享溢出、预占和占用一致性由 Warehouse 的数据库事务和条件更新最终保证。

@@ -156,7 +156,7 @@ Print 是无数据库的无状态 PDF 渲染服务。业务归属服务完成权

 ### 5.10 `integration-service/`：第三方集成中心

-Integration 负责百度 OCR、重量识别和 Amazon Logistics/SP-API 等第三方协议适配及能力状态。二期重量 OCR 由 File 调用，业务图片和入库状态不归 Integration；服务不使用业务数据库，真实外部调用默认关闭，密钥必须通过 Jenkins Credentials、环境变量或 Nacos 密文注入。
+Integration 负责百度 OCR、重量识别和 Amazon Logistics/SP-API 等第三方协议适配及能力状态。入库测量与计费重量 OCR 由 File 调用，业务图片和入库状态不归 Integration；服务不使用业务数据库，真实外部调用默认关闭，密钥必须通过 Jenkins Credentials、环境变量或 Nacos 密文注入。

 ### 5.11 `event-bridge-service/`：跨区域事件桥

@@ -194,7 +194,7 @@ deploy/

 - `local-env.ps1`：本地服务环境变量
 - `publish-local-nacos-config.ps1`：发布本地 Nacos 配置
- `phase1-acceptance.ps1`：一期验收入口
+- `phase1-acceptance.ps1`：订单与客户验收入口
 - `phase1-business-maturity-regression.ps1`：业务成熟度回归
 - `phase1-onboarding-order-e2e.ps1`：企业入驻到订单端到端验证
 - `order-warehouse-real-api-regression.ps1`：订单、仓库、往来单位真实 API 回归
@@ -76,7 +76,7 @@
 | 库位占用记录 | `OCCUPIED` | 正在占用。 |
 | 库位占用记录 | `RELEASED` | 已释放。 |

-## 二期入库
+## 入库

 ### 入库单主流程状态

@@ -130,7 +130,7 @@
 | 入库与计费幂等记录 | `PROCESSING` | 请求正在执行。 |
 | 入库与计费幂等记录 | `COMPLETED` | 请求已成功完成，可返回幂等结果。 |

-## 三期智能装柜和 PDA
+## 国内货柜履约智能装柜和 PDA

 | 字段 | 状态值 | 中文含义 |
 | --- | --- | --- |