2026-09-28 16:01:16 +08:00
3 changed files with 659 additions and 9 deletions
@@ -8,6 +8,10 @@
 - “尾程订单”属于本期已确认的订单管理范围，但不得据此把海外仓出库、派送履约或 `海外派送` 原型模块整体纳入四期。
 - 历史文档中把高级 BI、开放平台、移动端或性能优化称为“四期”的内容不再作为当前四期范围依据。

+## 人工验收入口
+
+- 国内装柜完成后的三期尾端至四期完整人工验收，统一使用[《三期装柜完成后至四期人工验收手册》](三期装柜完成后至四期人工验收手册.md)。手册从 `LOADED` 柜次开始，覆盖国内出仓、船节点、跨区建单、海外 PDA 入仓、库存/库内结果、海外主数据和海外业务，并明确区分当前可操作页面与仅后端自动化已通过的能力。
+
 ## 功能快速路由

 | 业务域 | 本期范围 | 原型入口 |
@@ -0,0 +1,652 @@
+# 三期装柜完成后至四期人工验收手册
+
+> 适用环境：开发环境
+> 国内 API：`http://dev-api-cn.buggoglobal.com`
+> 海外 API：`http://dev-api-global.buggoglobal.com`
+> 验收起点：国内装柜已完成，入库单和装柜计划已经进入 `LOADED` / `COMPLETED`
+> 验收终点：海外仓完成签收、实收和库存落账；四期独立主数据与海外业务完成各自生命周期核对
+
+## 1. 本手册不重复的内容
+
+以下属于装柜完成前流程，本手册不再重复：
+
+- 客户建档、资质审核和账号创建；
+- 客户下单、入库单生成、测量、称重和计费；
+- 分柜、智能排柜、预装清单和真实柜号关联；
+- 订舱放舱、国内 PDA 拣货、装柜照片和铅封证据；
+- 报关资料、补件、代理提交和放行回执；
+- 将入库单推进至 `LOADED` 的装柜完成操作。
+
+本手册从已有 `LOADED` 柜次开始。若开发库没有可用柜次，可先运行第 15 节的自动化脚本生成隔离数据，但人工页面验收仍从 `LOADED` 柜次开始记录。
+
+## 2. 当前验收边界
+
+### 2.1 本轮必须验收
+
+1. 国内出仓确认与撤销边界；
+2. 出仓后自动创建船节点查询任务；
+3. 十个标准船节点、预计/实际时间、异常和停止条件；
+4. 国内装柜完成事件跨区生成尾程订单和入仓计划；
+5. `PICKUP_READY` 对海外 PDA 待收柜的门禁；
+6. 海外 PDA 柜号签收、三类照片、FBA 按箱数收货、OVERSEAS 逐箱收货和整柜完成；
+7. 海外库存余额、位置、流水、托盘和换标结果查询；
+8. 海外仓合作仓、报价、汇率和车辆主数据；
+9. 海外采购、本土卡车和本土散板；
+10. 海外账号、权限、双 Token、撤权即时失效和跨区事件回写。
+
+### 2.2 明确不验收
+
+- 海外仓出库、退货出库和海外派送；
+- 箱号管理和产品库正式页面；
+- PDA 出库拣货或派送；
+- 车辆派送履约历史；
+- 通过数据库手工修改业务状态；
+- 使用历史柜、伪造节点或直接调用内部接口代替正式流程。
+
+### 2.3 页面与接口验收层级
+
+
+| 能力                                                 | 当前人工验收方式                       | 说明                                                                |
+| ---------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------- |
+| 国内出仓、船节点、尾程订单、入仓单、库存、托盘、换标 | Admin 页面                             | 必须截图并核对状态                                                  |
+| 海外 PDA 柜号签收与入仓                              | 海外 PDA 真机                          | 当前设备端真实开放能力                                              |
+| PDA 盘点、移库、组托/拆托/换托/解绑、换标现场作业    | 自动化 HTTP + Admin 结果查询           | 后端已全链通过；海外 PDA 工作台入口当前仍禁用，不能冒充页面人工验收 |
+| 采购创建                                             | 自动化 HTTP 或具备客户入口时由客户创建 | Admin 当前主要承载列表、详情、编辑和审核结果查看                    |
+| 本土卡车、本土散板                                   | Admin 页面                             | 可创建、编辑并核对状态                                              |
+| 海外主数据                                           | Admin 页面                             | 报价、汇率、车辆支持创建和状态维护                                  |
+
+## 3. 验收人员和账号准备
+
+至少准备以下身份：
+
+
+| 身份             | 用途                       | 必须满足                                                                                 |
+| ---------------- | -------------------------- | ---------------------------------------------------------------------------------------- |
+| 平台管理员       | Admin 全部页面验收         | 使用开发环境验收账号；具备三、四期 canonical 权限                                        |
+| 海外仓操作员     | 海外 PDA 真机验收          | 角色为`WAREHOUSE_PICKER`；权限含 `lastleg:pda:operate`；绑定且只能绑定一个实际海外收货仓 |
+| 第二海外仓操作员 | 抢柜和账号隔离验证         | 与第一操作员绑定同一实际海外仓                                                           |
+| 客户账号         | 客户侧采购或海外仓服务验证 | 客户状态为`ACTIVE`，国内/海外 Token 属于同一客户主体                                     |
+
+禁止把 `platform_admin` 当作 PDA 操作员。平台管理员进入 `/api/pda/**` 应被拒绝。
+
+## 4. 验收数据登记表
+
+开始前复制下表到验收记录中。所有 ID 按字符串保存，不要用 Excel 数值格式截断长 ID。
+
+
+| 数据                    | 验收值          |
+| ----------------------- | --------------- |
+| 验收日期/人员           | 欧阳            |
+| 国内装柜清单号          |                 |
+| 客户名称/客户 ID        |                 |
+| 订单号/订单 ID          |                 |
+| 入仓码/入库单 ID        |                 |
+| 装柜计划 ID             | CAB-260825-0215 |
+| 订舱 ID                 |                 |
+| 柜次 ID                 |                 |
+| 真实柜号                |                 |
+| 船公司/船名航次         |                 |
+| 国内收货仓              |                 |
+| 海外实际收货仓          |                 |
+| FBA 目的仓或海外目的仓  |                 |
+| 尾程订单号/ID           |                 |
+| 海外入仓计划号          |                 |
+| CarrierScheduleQuery ID |                 |
+| PDA 操作员              |                 |
+| 实物托盘码              |                 |
+
+## 5. 起点数据检查：确认柜次可以进入出仓
+
+### 5.1 页面入口
+
+Admin → **货柜管理 → 装柜清单**，打开待验收柜次详情。
+
+### 5.2 必须满足
+
+- 装柜清单状态为 `COMPLETED`；
+- 来源入库单状态为 `LOADED`；
+- 柜号、柜次 ID、装柜计划 ID 均非空；
+- 订舱状态为 `RELEASED`；
+- 国内 PDA 任务已完成；
+- 五类有效装柜证据齐全：`PHOTO_STEP_1`～`PHOTO_STEP_4`、`SEAL`；
+- 铅封号存在；
+- 报关状态为 `CLEARANCE_COMPLETED`；
+- 有效船期未过期。
+
+### 5.3 证据
+
+截图装柜清单详情顶部、明细、证据区域和状态历史。截图文件建议命名：
+
+`01-装柜完成起点-柜号.png`
+
+## 6. 国内出仓确认
+
+### 6.1 页面入口
+
+Admin 直接访问 `/outbound-dispatches`，页面标题为 **国内出仓**。
+
+### 6.2 操作
+
+1. 按订单号、入仓码或柜号定位第 5 节柜次；
+2. 打开详情或门禁面板；
+3. 核对以下门禁全部通过：
+   - `INBOUND_LOADED`
+   - `LOADING_PLAN_COMPLETED`
+   - `PDA_PICK_COMPLETED`
+   - `OCEAN_BOOKING_RELEASED`
+   - `TRUCK_DEPARTED`
+   - `LOADING_EVIDENCE_COMPLETE`
+   - `CUSTOMS_CLEARANCE`
+   - `SAILING_SCHEDULE`
+4. 点击 **确认国内出仓**；
+5. 刷新页面。
+
+### 6.3 预期结果
+
+- 国内出仓状态变为 `WAITING_FOR_LOADING`；
+- 来源入库单仍为 `LOADED`，不能被改成其他状态；
+- 写入一条确认出仓历史；
+- 系统自动创建该柜的船节点查询任务；
+- 自动生成第一条实际节点 `DEPARTED_WAREHOUSE`；
+- 再次用相同操作重放不应重复写历史；
+- 已产生实际 `DEPARTED_WAREHOUSE` 后，撤销国内出仓必须返回 `A0409`，状态不能回退。
+
+### 6.4 证据
+
+- `02-国内出仓门禁全部通过.png`
+- `03-国内出仓确认终态.png`
+- `04-出仓后禁止撤销.png`
+
+## 7. 船节点查询任务与十节点流转
+
+### 7.1 数据怎么创建
+
+船节点任务不能人工新建。第 6 节确认国内出仓后，Firstleg 按真实订舱、柜次和跟踪号自动创建唯一 `CarrierScheduleQuery`。
+
+### 7.2 页面入口
+
+从以下任一真实入口查看：
+
+- Admin → **货柜管理 → 订舱列表** → 对应订舱详情；
+- Admin → **船期信息**；
+- 货柜详情中的船节点面板。
+
+### 7.3 首次核对
+
+- 任务来源为 `OUTBOUND_CONFIRM`；
+- 任务绑定本轮客户、订舱、柜次和柜号；
+- 状态为 `READY` 或供应商明确要求的 `MANUAL_REQUIRED`；
+- 第一条实际节点为 `DEPARTED_WAREHOUSE`；
+- `providerCode=FIRSTLEG`；
+- 节点有 `actualAt`、`observedAt`、来源引用和不可变历史；
+- 同一客户、订舱、柜次只能有一个任务。
+
+### 7.4 标准节点顺序
+
+人工补录或第三方查询必须按下列顺序推进。预计时间只增加预计事实，不得推进“最新实际节点”。
+
+
+| 顺序 | 标准节点                   | 中文含义     | 对任务状态的影响        |
+| ---: | -------------------------- | ------------ | ----------------------- |
+|   10 | `DEPARTED_WAREHOUSE`       | 已离开国内仓 | 自动创建任务时产生      |
+|   20 | `AT_ORIGIN_PORT`           | 已到起运港   | 保持`READY`             |
+|   30 | `LOADED_ON_VESSEL`         | 已装船       | 保持`READY`             |
+|   40 | `DEPARTED_ORIGIN_PORT`     | 已离开起运港 | 保持`READY`             |
+|   50 | `IN_TRANSIT`               | 海运在途     | 保持`READY`             |
+|   60 | `ARRIVED_DESTINATION_PORT` | 已到目的港   | 保持`READY`             |
+|   70 | `DISCHARGED_FROM_VESSEL`   | 已卸船       | 保持`READY`             |
+|   80 | `PICKUP_READY`             | 可提柜       | 开放海外 PDA 待收柜门禁 |
+|   90 | `PICKED_UP`                | 已提柜       | 保持业务跟踪            |
+|  100 | `EMPTY_RETURNED`           | 已还空柜     | 任务变为`STOPPED`       |
+
+### 7.5 人工补录检查
+
+1. 打开对应任务的人工补录弹窗；
+2. 选择标准节点；
+3. 填写 `observedAt`；
+4. 预计节点填写 `estimatedAt`，实际节点填写 `actualAt`；两者至少一个非空；
+5. 填写位置和原因；
+6. 提交后刷新详情。
+
+预期：
+
+- 每次成功后任务版本递增；
+- 预计事实不改变 `latestActualNode/latestActualAt`；
+- 实际事实单调推进，不允许用较早节点覆盖最新事实；
+- 重复提交同一幂等请求不增加节点；
+- 旧版本提交返回 `A0409`；
+- 异常事实独立显示，不参与最新实际节点计算；
+- 只有实际 `EMPTY_RETURNED` 才进入 `STOPPED`，停止原因显示“已还柜”。
+
+### 7.6 PDA 门禁反证
+
+- 在 `PICKUP_READY` 前登录海外 PDA，本柜不能出现在待卸货候选；
+- 补录实际 `PICKUP_READY` 后等待跨区事件收敛并刷新，本柜必须出现；
+- 不得为了让柜号出现而直改 Lastleg 数据库或调用内部接口。
+
+## 8. 跨区生成尾程订单与入仓计划
+
+### 8.1 数据来源
+
+国内装柜完成时，Firstleg 发布 `FIRST_LEG_LOADING_PLAN_COMPLETED` V2。Event Bridge 将事件投递到海外 Lastleg。Lastleg 按最终实装数据生成：
+
+- 尾程订单；
+- 尾程订单货物冻结快照；
+- 独立入仓单/入仓计划；
+- FBA 的 SKU 实收依据；
+- OVERSEAS 的逐箱冻结箱唛；
+- 对应状态历史。
+
+该过程是异步的。页面暂未出现时先等待 30～120 秒并刷新，不手工补数据。
+
+### 8.2 页面核对
+
+Admin → **海外仓 → 尾程订单**：
+
+- 按柜号找到本轮尾程订单；
+- 柜号、客户、来源订单、来源入仓码和目的类型一致；
+- 长 ID 无科学计数法或截断；
+- 详情不出现海外出库、派送或内部事件字段。
+
+Admin → **海外仓 → 入库单**：
+
+- 按柜号或入仓码找到计划；
+- `destinationType` 为 `FBA` 或 `OVERSEAS`；
+- 实际收货仓、目的仓、总箱数、已收箱数和待收箱数正确；
+- FBA 显示 FBA 仓；OVERSEAS 显示海外目的仓；
+- `sourceOrderId` 按字符串显示。
+
+### 8.3 失败判定
+
+- 国内装柜完成后 2 分钟仍没有尾程订单；
+- 同一来源入仓单重复生成多个尾程订单；
+- FBA 和 OVERSEAS 目的类型混淆；
+- OVERSEAS 实装箱唛数量与最终实装箱数不一致；
+- 页面需要浏览器跨区调用国内 internal 接口才能获得数据。
+
+## 9. 海外实际收货仓、托盘与操作员准备
+
+### 9.1 实际收货仓
+
+使用 `warehouse-overseas-service` 的平台公共实际海外仓，必须满足：
+
+- `customer_id=0`；
+- 类型为 `OVERSEAS`；
+- 状态为 `ACTIVE`；
+- 启用 `RECEIVING` 能力；
+- 至少有一个可用库位；
+- 至少有两个可用实物托盘，以便验证托盘兼容与后续库内操作。
+
+实际收货仓不是国内来源仓，也不是 FBA/海外目的仓。
+
+### 9.2 创建 PDA 操作员
+
+Admin → **系统管理 → 用户管理**：
+
+1. 新增平台内部用户；
+2. 角色选择 `WAREHOUSE_PICKER`；
+3. 选择唯一实际海外收货仓；
+4. 保存并设置为 `ACTIVE`；
+5. 使用该账号登录海外 PDA。
+
+预期：其他角色不能提交海外仓绑定；`WAREHOUSE_PICKER` 不绑定仓库时不能保存或登录作业。
+
+## 10. 海外 PDA 真机：柜号签收
+
+### 10.1 登录检查
+
+- 登录成功后同时取得国内和海外会话；
+- 首页只开放 **入仓作业 → 拆柜收货**；
+- 库存盘点、商品移库、托盘管理、换标和现场查询入口当前应显示未开放；
+- 平台管理员或普通客户账号不得进入拆柜收货。
+
+### 10.2 选择柜号
+
+1. 进入 **拆柜收货**；
+2. 在待卸货列表找到已到 `PICKUP_READY` 的柜号；
+3. 点击查看详情；
+4. 核对所有入仓码、目的仓、托数、总箱数和待收箱数；
+5. 点击 **选择此柜并开始拍照**。
+
+预期：
+
+- 当前账号锁定该柜；
+- 完成前不能切换另一柜；
+- 第二操作员抢同一柜返回冲突；
+- 退出并重新登录后自动恢复当前柜，不要求重新选柜。
+
+### 10.3 三类照片
+
+依次拍摄并上传：
+
+1. 车牌照片 `LICENSE_PLATE`；
+2. 集装箱封签 `CONTAINER_SEAL`；
+3. 开柜现场 `DOOR_OPEN`。
+
+验收要求：
+
+- 必须调用真机摄像头，至少一张执行“重拍”；
+- 三个槽位各一张后才可点击 **确认签收并开始收货**；
+- 网络失败时保留当前页面和已上传照片，不重复生成成功记录；
+- 成功后状态由 `WAIT_SIGN` 进入 `SIGNED/RECEIVING`。
+
+## 11. 海外 PDA 真机：两种收货模式
+
+### 11.1 FBA 按 SKU 箱数收货
+
+1. 选择 `destinationType=FBA` 的入仓码；
+2. 扫描该入仓码冻结的 SKU；
+3. 核对页面带出的目的仓、计划箱数和待收箱数；
+4. 扫描实物托盘码；
+5. 确认页面提示“目的仓匹配，可收货”；
+6. 输入本次放入托盘的箱数；
+7. 点击 **确认按箱数收货**；
+8. 分多次重复，直到该入仓码待收箱数为 0。
+
+必须验证：
+
+- 箱数必须为正整数且不超过待收数量；
+- 超收返回 `A0409`，库存不变化；
+- FBA 模式不能走逐箱收货；
+- 同一次提交因超时重试不能重复增加库存。
+
+### 11.2 OVERSEAS 逐箱扫码收货
+
+1. 选择 `destinationType=OVERSEAS` 的入仓码；
+2. 扫描一个最终实装冻结箱唛；
+3. 页面自动切换并显示该箱所属入仓码；
+4. 扫描实物托盘码；
+5. 点击 **确认本箱收货**；
+6. 每一箱重复上述动作，不能直接输入箱数批量收货。
+
+必须验证：
+
+- 非本柜、未实装或不存在的箱唛返回 `A0404`；
+- 已收箱使用新请求再次扫描返回 `A0409`；
+- 托盘与当前入仓码目的模式不匹配时不能提交；
+- OVERSEAS 模式不能走 FBA 批量收货；
+- 每成功一箱，柜级和入仓码级 `received/pending` 同时更新。
+
+### 11.3 完成整柜
+
+只有所有入仓码 `pendingPackages=0` 时，按钮才变为 **每个入仓码已核平，完成整柜入库**。
+
+点击完成后预期：
+
+- PDA 显示当前柜已完成入库；
+- 状态为 `COMPLETED`；
+- current 再查询为空；
+- 库存余额、库存位置和库存流水同事务生成；
+- 尾程主流程推进至 `INBOUND_COMPLETED`；
+- 生成海外卸柜完成 Outbox，异步回写国内柜次事实。
+
+## 12. 入库完成后的 Admin 核对
+
+### 12.1 尾程订单和入库单
+
+Admin → **海外仓 → 尾程订单/入库单**：
+
+- 状态已完成入仓；
+- 总箱数、实收箱数、入仓码和柜号一致；
+- 历史包含创建、签收、实收和完成事实；
+- 不出现出库或派送状态。
+
+### 12.2 库存
+
+Admin → **海外仓 → 库存管理**：
+
+- 按客户、实际海外仓、目的仓和入仓码找到余额；
+- SKU、中文/英文品名快照按实际单 SKU 或 `MIXED` 规则显示；
+- 可用箱数等于 PDA 实收箱数；
+- 详情位置包含实物托盘和库位；
+- 进销存流水包含入库事实；
+- 导出 CSV 可下载，长 ID 不丢失；
+- summary、balances export、ledger export 不传分页也不能返回 `A0422`。
+
+### 12.3 托盘
+
+Admin → **海外仓 → 托盘管理**：
+
+- 托盘属于实际海外收货仓；
+- 公共托盘请求不依赖客户筛选；
+- 托盘位置、状态和绑定库存箱数与 PDA 一致。
+
+### 12.4 国内柜次回写
+
+回到国内货柜详情，等待跨区事件收敛后核对：
+
+- `unloadingCompletedAt` 已写入；
+- `unloadingPhotoUploadedAt` 已写入；
+- `estimatedEmptyReportedAt` 按签收照片时间加两天生成；
+- 实际报空/卸柜事实没有重复写入；
+- 相同海外卸柜完成事件重放不产生第二条事实。
+
+## 13. PDA P2～P5 后端验收与当前前端边界
+
+以下后端能力已经纳入真实 HTTP 自动化：
+
+- P2：盘点创建、计数、提交、分页、幂等和旧版本冲突；
+- P3：同仓整托移库、实物托盘与库存位置同步、重放和版本冲突；
+- P4：换托、拆托、合托、解绑、物理状态补偿和幂等；
+- P5：换标认领、正常处理、跳过、异常、返工、复核和完成。
+
+当前海外 PDA 工作台这些入口仍为 `available: false`。因此人工验收规则是：
+
+1. 不要求验收人员在真机点击不存在的页面；
+2. 使用第 15 节自动化报告证明写链；
+3. 在 Admin 的库存、托盘和换标页面人工核对自动化产生的最终事实；
+4. 等 PDA 页面按最终原型接入后，再追加真机操作、扫码焦点、弱网恢复和视觉验收；
+5. 在此之前不能把“后端 HTTP 已通”写成“PDA 页面已验收”。
+
+## 14. 四期独立业务验收
+
+这些业务与柜号主链共享账号、权限和海外 Gateway，但不依赖同一柜次才能创建。
+
+### 14.1 海外合作仓和报价
+
+1. Admin → **通用 → 仓库管理**；
+2. 新建仓库，类型选择“海外合作仓”；
+3. 保存后在列表按类型筛选并确认可查；
+4. Admin → **通用 → 海外仓报价**；
+5. 点击新增，确认合作仓候选由海外服务内部读取，浏览器不调用国内 internal；
+6. 创建报价，核对版本、状态、详情和列表；
+7. 编辑后 `recordVersion` 递增；
+8. 旧版本修改应返回 `A0409`；
+9. 执行状态变更和 CSV 导出；
+10. 当前无 DELETE，页面不得推断删除功能。
+
+### 14.2 月度汇率
+
+1. Admin → **通用 → 汇率管理**；
+2. 新建月份、币种和汇率；
+3. 查询列表和详情；
+4. 编辑并确认版本递增；
+5. 旧 `recordVersion` 返回 `A0409`；
+6. 修改状态并导出 CSV。
+
+### 14.3 车辆
+
+1. Admin → **通用 → 车辆列表**；
+2. 新建车辆档案；
+3. 查询列表和详情；
+4. 编辑并确认版本递增；
+5. 旧版本返回 `A0409`；
+6. 修改状态并导出；
+7. 详情不应拼装派送履约或更换历史。
+
+### 14.4 海外采购
+
+数据来源为客户提交的采购单。没有客户创建页面时，使用第 15 节自动化生成本轮隔离采购单，再由 Admin 验收。
+
+Admin → **海外业务 → 采购订单**：
+
+- 客户候选只包含有效客户；
+- 采购仓只允许选择正式候选 ID，名称由后端冻结；
+- 可空字段支持“不传不改、null 清空、空串清空”；
+- 编辑写入 `UPDATE` 流水；
+- 审核写入 `REVIEW` 流水；
+- 状态为 `PENDING_REVIEW → APPROVED/REJECTED`；
+- 终态逆向操作返回冲突；
+- 不存在采购出库数量、采购出库记录或 `/outbounds`。
+
+### 14.5 本土卡车
+
+Admin → **海外业务 → 本土卡车**：
+
+1. 显式选择 `ACTIVE` 客户；
+2. 新建卡车单；
+3. 相同请求重放只返回同一资源；
+4. 仅 `PENDING_REVIEW` 允许普通编辑；
+5. 编辑携带当前版本；
+6. 旧版本返回 `A0409`；
+7. 列表、详情和操作流水一致；
+8. 不验收 receive-pallets、PDA 出库或派送。
+
+### 14.6 本土散板
+
+Admin → **海外业务 → 本土散板**：
+
+1. 显式选择客户并新建；
+2. 仅 `PENDING_ACCEPTANCE` 可普通编辑；
+3. 状态顺序为 `PENDING_ACCEPTANCE → DISPATCHED → IN_TRANSIT → COMPLETED`；
+4. 规则允许时可进入 `CANCELLED`；
+5. 旧版本返回 `A0409`；
+6. 终态不能逆向推进；
+7. 不复用本土卡车状态或接口。
+
+### 14.7 排车查询与智能预排
+
+Admin → **海外仓 → 排车列表**：
+
+- 可跨客户查看列表和详情；
+- 候选来自真实入仓计划或已收托盘；
+- 草稿加入托盘后立即锁定；
+- 从草稿移除或关闭时释放锁；
+- 预排创建后锁转换为正式排车锁；
+- 本期只验收查询和预排，不验收编辑、取消、发车、PDA 出库或派送。
+
+## 15. 自动化复核：数据怎么自动创建和清理
+
+### 15.1 运行方式
+
+在 `baiyue-firstleg` 目录执行。密码只通过本机未提交环境变量传入，不写在命令、文档或报告中。
+
+```powershell
+$env:ADMIN_TEST_GATEWAY='http://dev-api-cn.buggoglobal.com'
+$env:ADMIN_OVERSEAS_GATEWAY='http://dev-api-global.buggoglobal.com'
+$env:ADMIN_TEST_USERNAME='platform_admin'
+$env:ADMIN_TEST_PASSWORD='<从本机安全配置读取>'
+
+node scripts/admin-test-env-acceptance.mjs `
+  --modules phase4-overseas-warehouse,phase4-overseas-pda,phase4-overseas-pda-operations,phase4-overseas-inbound-operations,phase4-overseas-client-services,phase4-overseas-dispatch,phase4-cross-region-events,phase4-overseas-business,phase4-overseas-master-data,phase4-carrier-nodes
+```
+
+### 15.2 自动数据流
+
+脚本会自动：
+
+1. 创建本轮 marker 客户和订单前置；
+2. 生成互相隔离的 FBA、OVERSEAS、Dropship 和第二柜；
+3. 完成国内装柜、出仓和每柜独立船节点任务；
+4. 等待跨区建单和安全投影收敛；
+5. 创建实际海外收货仓、库位、托盘和两名临时操作员；
+6. 完成 FBA/OVERSEAS 入仓；
+7. 执行 P2～P5；
+8. 执行海外业务和主数据生命周期；
+9. 停用临时操作员和可停用测试资源；
+10. 生成 `reports/admin-test-env-acceptance-*.json`。
+
+### 15.3 自动化通过标准
+
+- `RESULT=PASS`；
+- `failed=0`；
+- `skippedModules=0`；
+- `deploymentBlockers=0`；
+- 报告敏感信息扫描通过；
+- 不出现非预期 `S0500`、`A0422`、HTTP 0 或 5xx；
+- `A0403/A0404/A0409` 只允许出现在明确的权限、空态、未命中和并发反证步骤。
+
+最近一次开发环境 PDA 主链基准为：`4008/4008 PASS`、2907 个唯一请求。
+
+## 16. 异常、权限和弱网人工反证
+
+至少执行以下反证并截图：
+
+
+| 场景                            | 预期                                             |
+| ------------------------------- | ------------------------------------------------ |
+| 平台管理员访问海外 PDA          | `A0403`，不能进入业务                            |
+| 操作员未绑定海外仓              | 登录或作业 fail-closed                           |
+| 第二操作员抢同一柜              | `A0409`，原操作员会话不变                        |
+| 当前操作员尝试切柜              | 返回当前柜，不建立第二会话                       |
+| `PICKUP_READY` 前查询柜候选     | 本柜不可见                                       |
+| 非本柜箱唛                      | `A0404`                                          |
+| FBA 尝试逐箱                    | `A0409`                                          |
+| OVERSEAS 尝试批量箱数           | `A0409`                                          |
+| 重复收同一箱                    | `A0409`，库存不重复增加                          |
+| 旧版本编辑主数据/业务单         | `A0409`，页面保留输入                            |
+| 海外请求返回 401                | 前端只触发一次国内 refresh，并最多重放原请求一次 |
+| 停用 PDA 用户后继续使用旧 Token | 立即失败；重新进入需重新登录                     |
+| Auth/安全投影校验不可用         | Gateway 拒绝，不默认放行                         |
+| 上传照片时断网                  | 保留当前柜和已成功槽位，恢复后可继续             |
+| 收货提交超时                    | 使用同一幂等请求重试，不重复入账                 |
+
+每个错误证据必须保存：业务码、message、requestId、traceId 和页面上下文。
+
+## 17. 最终完结判定
+
+### 17.1 主链完成
+
+同时满足才可勾选：
+
+- [ ]  国内装柜清单 `COMPLETED`，来源入库单 `LOADED`
+- [ ]  国内出仓 `WAITING_FOR_LOADING`
+- [ ]  CarrierScheduleQuery 自动创建并绑定正确柜次
+- [ ]  实际节点到 `PICKUP_READY` 后 PDA 才可见柜号
+- [ ]  尾程订单和入仓计划由跨区事件生成
+- [ ]  三类卸柜照片齐全
+- [ ]  FBA 按箱数、OVERSEAS 逐箱规则正确
+- [ ]  所有入仓码待收箱数为 0
+- [ ]  当前柜 `COMPLETED`
+- [ ]  尾程状态 `INBOUND_COMPLETED`
+- [ ]  库存余额、位置、流水和托盘事实一致
+- [ ]  国内柜次收到海外卸柜完成回写
+- [ ]  `EMPTY_RETURNED` 后船节点任务 `STOPPED`
+
+### 17.2 独立业务完成
+
+- [ ]  海外合作仓可创建和筛选
+- [ ]  报价、汇率、车辆完成创建/编辑/状态/导出
+- [ ]  采购完成创建事实、编辑三态、审核和流水核对
+- [ ]  本土卡车完成创建、编辑和版本冲突核对
+- [ ]  本土散板完成创建、编辑、状态流转和终态核对
+- [ ]  排车查询与智能预排没有扩大到出库和派送
+
+### 17.3 验收结论分级
+
+
+| 结论       | 条件                                                                                             |
+| ---------- | ------------------------------------------------------------------------------------------------ |
+| 通过       | 所有必验项通过，无 S0500/5xx/数据串仓；自动化报告全绿；页面/真机证据齐全                         |
+| 有条件通过 | 后端和业务状态全通，仅剩已明确的 PDA P2～P5 页面尚未按原型接入，已记录负责人和补验时间           |
+| 不通过     | 主链断裂、状态可绕过、权限越权、重复入账、跨客户/跨仓串数据、非预期 S0500/5xx 或关键页面不可操作 |
+
+## 18. 验收证据目录建议
+
+```text
+三四期人工验收-YYYYMMDD/
+  01-装柜完成起点/
+  02-国内出仓/
+  03-船节点/
+  04-跨区尾程与入仓/
+  05-海外PDA签收照片/
+  06-FBA收货/
+  07-OVERSEAS逐箱收货/
+  08-库存托盘换标/
+  09-海外主数据/
+  10-采购卡车散板/
+  11-权限弱网反证/
+  12-自动化报告/
+```
+
+每张截图保留浏览器地址、柜号/业务单号、状态和时间；不得把密码、完整 Token、身份证件原图或其他敏感信息放入验收包。
@@ -4,8 +4,8 @@

 ## 当前状态

- 当前已启用财务改造、四期前端页面、四期后端缺口和 Java 架构改善四个平级总控；只按下方登记的稳定 `task_id` 协作。
- 财务总控下登记五个长期专项，四期前端总控下登记五个长期专项，四期后端总控下登记五个长期专项，Java 架构改善总控下登记六个长期专项；各总控继续统一集成共享契约与跨专项回归。
+- 当前已启用财务改造、四期前端页面和四期后端缺口三个平级总控；只按下方登记的稳定 `task_id` 协作。
+- 财务总控下登记五个长期专项，四期前端总控下登记六个长期专项，四期后端总控下登记五个长期专项；各总控继续统一集成共享契约与跨专项回归。
 - 其他普通工作仍采用“一个任务、一个对话、逐项修复”的方式，不根据历史名称或旧职责向未登记对话下发。
 - 侧栏其他旧任务不属于本轮已登记协作，是否归档由用户人工决定，Codex 不自动归档、解档或恢复。

@@ -26,7 +26,6 @@
 | `01a01490-08e6-7b11-b16f-0085e232d04c` | 财务改造总控 | 冻结财务共享产品契约、状态机、OpenAPI、权限与数据库边界；协调五个财务专项并统一集成共享导航、权限 SQL、跨任务回归和验收结论 |
 | `01a018cb-a435-7c61-91ca-4f3e484dca75` | 四期前端页面总控 | 负责四期 Admin 前端页面的统一规划、实现与集成：国内出仓后船节点查询、海外仓尾程订单/入库/换标/托盘/箱号/产品/库存、海外采购/本土卡车/本土散板、海外仓合作仓类型、海外仓报价/汇率/车辆；统一维护四期前端路由、导航、权限、原型还原和回归，不承接海外仓出库业务或后端实现 |
 | `01a0194a-259c-7171-8967-074731a27618` | 四期后端缺口总控 | 负责四期后端缺口的统一盘点、契约收口、实现集成与回归：海外区域 Gateway、尾程与海外仓服务，海外接柜入仓、库存与库内操作，海外采购/本土卡车/本土散板，合作仓与报价/汇率/车辆主数据，国内出仓后船节点定时查询，以及所需 IAM、海外 Token、OpenAPI、初始化 SQL 和跨区域事件契约；向四期前端总控提供稳定 API，涉及 Finance 口径时交由财务总控冻结；不承接海外仓出库、海外派送、前端页面或财务状态机 |
-| `01a036f9-1d1c-77a0-a4d4-a99bb0d2532a` | Java架构改善总控 | 负责 Java 后端共享架构治理、改善路线和统一门禁：Firstleg/Lastleg 内部模块化、同步依赖治理、Event Bridge 传输与可靠性口径、数据库版本化演进、OpenAPI/ArchUnit/覆盖率/静态质量、GitLab/Jenkins 服务清单一致性、Trace/事件堆积/业务 SLO 可观测性及架构文档同步；协调后续架构专项并统一集成结论，不替代财务、四期前端或四期后端业务总控，不自行部署、执行 SQL 或修改环境数据 |

 长期独立任务：

@@ -42,14 +41,9 @@
 | `01a018d1-7437-7432-867d-abf33b2d66aa` | `01a018cb-a435-7c61-91ca-4f3e484dca75` | 四期专项三：通用资料与合作仓 | 负责 Admin 四期海外仓合作仓类型、海外仓报价、汇率管理和车辆列表/详情正式页面及模块内契约与测试；仓库类型只扩展现有仓库主数据，不把海外库存写入国内 Warehouse 领域，不修改共享导航、根路由或全局权限装配 |
 | `01a018d1-75cc-78a2-b026-27c69bdcc7ca` | `01a018cb-a435-7c61-91ca-4f3e484dca75` | 四期专项四：船节点前端承载 | 负责 Admin 现有订舱、船期和货柜详情中“确认国内出仓后至还柜”的 CarrierScheduleQuery 标准节点、异常、预计/实际时间、历史、失败态和人工补录前端承载及测试；不新建重复轮询任务、不归入海外派送，不修改共享导航、根路由或全局权限装配 |
 | `01a03382-e812-7ea2-a992-cea04650efaf` | `01a018cb-a435-7c61-91ca-4f3e484dca75` | 四期专项五：海外 PDA | 负责独立海外 PDA 应用 `apps/pda-overseas-uniapp/` 的四期入库签收、拆柜收货、入库打托、换标、库存与库内操作页面、真实海外 API 适配、扫码设备交互、路由、状态恢复及前端测试构建；不承接海外仓出库、退货出库、海外派送、后端实现或 Admin 共享代码 |
+| `01a038c1-c317-76f3-bcec-b220edf597f3` | `01a018cb-a435-7c61-91ca-4f3e484dca75` | 前端专项六：货柜与装柜 | 负责 Admin `apps/admin-web/src/modules/container-loading/` 的货柜列表、模拟柜、排柜与装柜入口、订舱关联候选、运输信息表单、公开前端契约和测试；按后端稳定接口消除候选 N+1 并维护并发安全，不修改后端、共享根路由/导航、IAM 或 SQL，不扩大海外出库与派送范围 |
 | `01a01e56-ba99-71e0-8076-b4f40f4b96f0` | `01a0194a-259c-7171-8967-074731a27618` | 四期后端专项一：海外基础设施与权限 | 负责海外 Gateway、三项海外服务与双区域 Event Bridge 的 Jenkins、Compose、service-map、Nacos 部署契约，海外 Token Claims/Audience、统一权限矩阵、IAM/统一 SQL、跨区域事件可靠性及相关 OpenAPI 与测试；不承接具体业务域实现，不部署或执行 SQL |
 | `01a01e56-bc99-7170-a180-7b6e9f25fc9a` | `01a0194a-259c-7171-8967-074731a27618` | 四期后端专项二：海外通用主数据 | 负责 Lastleg 海外仓报价、月度汇率、车辆主数据的表、Controller、DTO、状态、权限、OpenAPI、导出和测试，以及报价创建时服务端读取国内合作仓并缓存；不承接箱号、产品、出库或派送履约 |
 | `01a01e56-bed3-75f3-ba02-cc28479cd8ee` | `01a0194a-259c-7171-8967-074731a27618` | 四期后端专项三：海外入仓与库存 | 负责 Lastleg 与 Warehouse Overseas 的尾程订单、接柜、入仓计划、卸货入库、换标、平台公共托盘、SKU 库存和库内操作后端；排除箱号平台、产品库、海外出库、退货出库、海外派送，不向 Admin 暴露 PDA 或内部事件端点 |
 | `01a01e56-c0f2-71f1-9c74-02f6709233f1` | `01a0194a-259c-7171-8967-074731a27618` | 四期后端专项四：海外本土业务 | 负责 Lastleg 海外采购订单、本土卡车、本土散板完整后端，以及客户/仓库候选、字段清空语义、流水、平台写接口、权限、OpenAPI、SQL 和测试；排除采购出库、海外仓出库、退货出库与海外派送 |
 | `01a01e56-c30b-7513-be9e-03262a387696` | `01a0194a-259c-7171-8967-074731a27618` | 四期后端专项五：船节点自动查询 | 负责国内确认出仓后至还柜的 CarrierScheduleQuery 自动任务、租约、幂等、退避、十个标准节点、异常事实、预计/实际时间、人工补录、还柜停止条件、Integration 供应商适配、查询尝试与历史、货柜 DTO 及跨区衔接；不新建重复轮询体系，不承接海外派送、PDA 或前端页面 |
-| `01a03702-e35b-7202-a395-62643ab77ec2` | `01a036f9-1d1c-77a0-a4d4-a99bb0d2532a` | Java架构专项一：拓扑与质量门禁 | 负责当前 22 Maven 模块、15 个可运行服务的拓扑合同，POM、service-map、GitLab 制品、Jenkins、Compose、Nacos 清单一致性，以及 Maven、OpenAPI、JaCoCo、静态分析和 ArchUnit 共享质量门禁；不修改业务状态机、不部署，海外基础设施内容与四期后端基础设施专项协调 |
-| `01a03702-e52e-7503-8c4e-b24ebf6aa925` | `01a036f9-1d1c-77a0-a4d4-a99bb0d2532a` | Java架构专项二：同步依赖与失败传播 | 负责 Java 后端 Feign/HTTP 同步调用图，双向依赖、调用链深度、超时、重试、熔断、幂等、错误映射和失败传播治理；不擅自改变财务或四期业务状态机，不以默认成功、空数据或静默降级掩盖远端失败 |
-| `01a03702-e749-7ce1-9c50-25961c7dfc83` | `01a036f9-1d1c-77a0-a4d4-a99bb0d2532a` | Java架构专项三：Event Bridge可靠传输 | 负责当前 HTTP+DB 跨区事件链路的 common-event-contract、Event Bridge、Firstleg、Lastleg 和 IAM Outbox/Inbox、租约、退避、投递记录、死信、人工补投、幂等冲突、文档口径和链路测试；不定义财务或四期业务语义，不承接部署基础设施 |
-| `01a03702-e92c-7b12-815d-5e02f1e1adf0` | `01a036f9-1d1c-77a0-a4d4-a99bb0d2532a` | Java架构专项四：Firstleg内部模块化 | 负责 Firstleg 同一部署单元内入库、测量计价、分柜装柜、订舱报关拖车、出仓、船节点、客户统计和财务集成切片的应用 Port、依赖方向与 ArchUnit 治理；不拆新微服务、不扩大业务范围、不替代财务总控 |
-| `01a03702-ebbd-74d0-a109-54bbd7628050` | `01a036f9-1d1c-77a0-a4d4-a99bb0d2532a` | Java架构专项五：Lastleg内部模块化 | 负责 Lastleg 同一部署单元内尾程交接、入仓/PDA、库存、排车/派车、换标、转运、废弃、一件代发、采购/卡车/散板和海外主数据切片的应用 Port、依赖方向与 ArchUnit 治理；不拆新微服务，不扩大海外出库、退货出库或海外派送范围 |
-| `01a03702-edaa-79b1-bed0-bbe85d6aeac5` | `01a036f9-1d1c-77a0-a4d4-a99bb0d2532a` | Java架构专项六：Trace指标与业务SLO | 负责统一 Trace、X-Request-Id/X-Trace-Id 与 traceparent 传播、Feign/HTTP/事件上下文、通用指标、事件积压与死信指标，以及跨区关键业务链 SLI/SLO 和告警合同；只维护代码、测试、配置模板和文档，不搭建或部署监控环境 |