677 lines
30 KiB
Markdown
677 lines
30 KiB
Markdown
# 虫虫出海全流程人工验收手册
|
||
|
||
> 适用环境：开发环境
|
||
> 国内 API：`http://dev-api-cn.buggoglobal.com`
|
||
> 海外 API：`http://dev-api-global.buggoglobal.com`
|
||
> 验收起点：客户与账号有效，客户订单具备可履约货物
|
||
> 验收终点：海外仓完成入仓、库内服务、出库和派送；异常退回、一件代发及国内外回写均可核对
|
||
|
||
## 1. 全流程范围
|
||
|
||
本手册统一覆盖：
|
||
|
||
- 客户建档、资质审核、账号、角色和权限；
|
||
- 客户下单、入库单、测量称重、尺寸策略、计价和费用；
|
||
- 分柜、同柜、智能排柜、订舱、拖车、国内 PDA 拣货、装柜、报关和国内出仓；
|
||
- 船节点、跨区建单、海外接柜、卸货入仓、库存、托盘、换标、转运、废弃和退货换标；
|
||
- 排车、海外 PDA 拣货与出库、发车、转派送、派送完成、异常退回和客户回访；
|
||
- 一件代发、海外采购、本土卡车、本土散板、海外费用来源及国内外事件回写。
|
||
|
||
可按业务域分段复核，但最终结论必须以端到端状态、库存、费用、权限和事件一致为准。开发库没有可用数据时，可使用第 15 节自动化脚本生成隔离数据。
|
||
|
||
## 2. 当前验收边界
|
||
|
||
### 2.1 必须验收
|
||
|
||
1. 国内出仓确认与撤销边界；
|
||
2. 出仓后自动创建船节点查询任务；
|
||
3. 十个标准船节点、预计/实际时间、异常和停止条件；
|
||
4. 国内装柜完成事件跨区生成待分配尾程订单和冻结快照，平台人工转换后才生成入仓计划；
|
||
5. `PICKUP_READY` 对海外 PDA 待收柜的门禁；
|
||
6. 海外 PDA 柜号签收、三类照片、FBA 按箱数收货、OVERSEAS 逐箱收货和整柜完成；
|
||
7. 海外库存余额、位置、流水、托盘和换标结果查询；
|
||
8. 海外仓合作仓、报价、汇率和车辆主数据；
|
||
9. 海外采购、本土卡车和本土散板；
|
||
10. 海外账号、权限、双 Token、撤权即时失效和跨区事件回写。
|
||
11. 客户换标、仓储转运、货物废弃和退货换标；
|
||
12. 排车编辑/取消、海外 PDA 拣货、出库、发车和转派送；
|
||
13. 客户派送单、派送状态、派送完成和签收附件；
|
||
14. 异常订单、派送退回入仓和客户回访；
|
||
15. 一件代发 SKU/箱唛库存与出库。
|
||
|
||
### 2.2 验收方式边界
|
||
|
||
- 箱号管理和产品库正式页面；
|
||
- 车辆派送履约历史；
|
||
- 通过数据库手工修改业务状态；
|
||
- 使用历史柜、伪造节点或直接调用内部接口代替正式流程。
|
||
- 派送由 Admin/Client 验收，不要求在海外 PDA 提供派送页面。
|
||
- PDA 工作台未注册的库内操作通过真实 HTTP、Admin/Client 页面和最终库存事实联合验收，不把终端入口与业务能力混为一谈。
|
||
|
||
### 2.3 页面与接口验收层级
|
||
|
||
|
||
| 能力 | 当前人工验收方式 | 说明 |
|
||
| ---------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------- |
|
||
| 国内出仓、船节点、尾程订单、入仓单、库存、托盘、换标 | Admin 页面 | 必须截图并核对状态 |
|
||
| 海外 PDA 柜号签收与入仓 | 海外 PDA 真机 | 当前设备端真实开放能力 |
|
||
| PDA 盘点、移库、组托/拆托/换托/解绑、换标现场作业 | 自动化 HTTP + Admin 结果查询 | 后端已全链通过；海外 PDA 工作台入口当前仍禁用，不能冒充页面人工验收 |
|
||
| 采购创建 | 自动化 HTTP 或具备客户入口时由客户创建 | Admin 当前主要承载列表、详情、编辑和审核结果查看 |
|
||
| 本土卡车、本土散板 | Admin 页面 | 可创建、编辑并核对状态 |
|
||
| 海外主数据 | Admin 页面 | 报价、汇率、车辆支持创建和状态维护 |
|
||
| 排车、出库和发车 | Admin + 海外 PDA | 核对拣货、出库数量、发车门禁与状态历史 |
|
||
| 派送、异常退回和客户回访 | Admin + Client | 核对客户范围、派送状态、退回入仓和附件 |
|
||
| 一件代发 | Client/Admin + 海外 PDA | 核对 SKU/箱唛快照、库存扣减、幂等和出库结果 |
|
||
|
||
## 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 登录检查
|
||
|
||
- 登录成功后同时取得国内和海外会话；
|
||
- 首页开放已注册的拆柜收货、库存盘点、商品移库、托盘管理、换标收货/执行/复核、库存/库位/托盘查询、排车拣货和出库作业；
|
||
- 库内、换标和现场查询需在 PDA 页面验收扫码/人工输入、错误恢复，并与真实 HTTP 及 Admin/Client 最终事实交叉核对；
|
||
- 平台管理员或普通客户账号不得进入拆柜收货。
|
||
|
||
### 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 库内能力与终端边界
|
||
|
||
以下后端能力已经纳入真实 HTTP 自动化：
|
||
|
||
- P2：盘点创建、计数、提交、分页、幂等和旧版本冲突；
|
||
- P3：同仓整托移库、实物托盘与库存位置同步、重放和版本冲突；
|
||
- P4：换托、拆托、合托、解绑、物理状态补偿和幂等；
|
||
- P5：换标认领、正常处理、跳过、异常、返工、复核和完成。
|
||
|
||
当前海外 PDA 工作台已开放库存盘点、商品移库、托盘管理、换标收货/执行/复核和库存/库位/托盘查询，按以下规则验收：
|
||
|
||
1. 在 H5 使用人工输入完成基础流程与错误态检查，在 PDA 真机补充广播扫码、拍照和设备返回行为；
|
||
2. 使用第 15 节自动化报告证明写链、幂等、旧版本冲突和资源隔离；
|
||
3. 在 Admin 的库存、托盘和换标页面核对 PDA 作业产生的最终事实；
|
||
4. 网络失败后保留任务和稳定幂等键，恢复时以服务端当前状态为准，不得重复提交；
|
||
5. 排车拣货、出库和发车同样必须补充真机扫码、弱网恢复和视觉证据。
|
||
|
||
## 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 海外采购
|
||
|
||
数据来源为客户提交的采购单。客户从企业工作台 **出海下单 → 海外采购** 新建，Admin 再完成审核与履约维护；自动化只用于需要隔离数据的补充验收。
|
||
|
||
Admin → **海外业务 → 采购订单**：
|
||
|
||
- 客户候选只包含有效客户；
|
||
- 采购仓只允许选择正式候选 ID，名称由后端冻结；
|
||
- 可空字段支持“不传不改、null 清空、空串清空”；
|
||
- 编辑写入 `UPDATE` 流水；
|
||
- 审核写入 `REVIEW` 流水；
|
||
- 状态为 `PENDING_REVIEW → APPROVED/REJECTED`；
|
||
- 审核通过后可维护入库量、采购物流与多条出库明细，出库总量不得超过入库量；
|
||
- 入库量大于零时，状态按出库汇总派生为 `PENDING_OUTBOUND → PARTIALLY_OUTBOUND → OUTBOUNDED`；
|
||
- 采购出库仅记录采购单履约，不生成或冒充海外仓可用库存；海外仓可用库存仍只由海外 PDA 实际收货产生；
|
||
- 终态逆向操作返回冲突；
|
||
- 不提供独立 `/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 拣货、出库、发车和转派送均需验收；
|
||
- 转派送必须发生在发车前，并生成待出库单；
|
||
- PDA 只按服务端 `canDepart` 与 `departBlockReason` 开放发车；
|
||
- 派送完成、异常退回入仓和客户回访必须保留状态及附件证据。
|
||
|
||
## 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,phase5-overseas-fulfillment,phase4-cross-region-events,phase4-overseas-business,phase4-overseas-master-data,phase4-carrier-nodes
|
||
```
|
||
|
||
### 15.2 自动数据流
|
||
|
||
脚本会自动：
|
||
|
||
1. 创建本轮 marker 客户和订单前置；
|
||
2. 生成互相隔离的 FBA、OVERSEAS、Dropship 和第二柜；
|
||
3. 将装柜清单推进为 `COMPLETED`、来源入库单推进为 `LOADED`，并通过公开平台接口上传/完成同柜 `DESTINATION_CLEARANCE`、`CUSTOMS_DECLARATION`、`DELIVERY_ORDER`、`PICKUP_ORDER` 四类资料；
|
||
4. 确认国内出仓，核对自动创建的每柜独立船节点任务并人工补录至实际 `PICKUP_READY`；
|
||
5. 等待跨区建单、安全投影和海外 PDA 候选门禁收敛；
|
||
6. 创建实际海外收货仓、库位、托盘和两名临时操作员；
|
||
7. 完成 FBA/OVERSEAS 入仓；
|
||
8. 执行 P2～P5；
|
||
9. 执行海外业务和主数据生命周期；
|
||
10. 停用临时操作员和可停用测试资源；
|
||
11. 生成 `reports/admin-test-env-acceptance-*.json`。
|
||
|
||
只复核“装柜完成至海外 PDA 候选可见”当前节点时，可定向执行 `--modules phase4-overseas-pda`；总入口会自动展开上述国内、跨区和海外安全前置。该命令会真实写开发环境，仍须当前对话明确授权后执行。本轮仅做离线检查时，只运行 `node --test scripts/admin-test-env-modules/phase3-container-documents-contract.test.mjs scripts/admin-test-env-modules/phase4-carrier-nodes-contract.test.mjs scripts/admin-test-env-modules/phase4-overseas-pda-contract.test.mjs`。
|
||
|
||
### 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 海外仓与派送完成
|
||
|
||
- [ ] 海外合作仓可创建和筛选
|
||
- [ ] 报价、汇率、车辆完成创建/编辑/状态/导出
|
||
- [ ] 采购完成创建事实、编辑三态、审核和流水核对
|
||
- [ ] 本土卡车完成创建、编辑和版本冲突核对
|
||
- [ ] 本土散板完成创建、编辑、状态流转和终态核对
|
||
- [ ] 换标、转运、废弃和退货换标完成并可核对库存流水
|
||
- [ ] 排车完成预排、编辑、PDA 拣货、出库、发车和状态核对
|
||
- [ ] 转派送、派送完成、异常退回和客户回访完成
|
||
- [ ] 一件代发 SKU/箱唛库存与出库数量核平
|
||
|
||
### 17.3 验收结论分级
|
||
|
||
|
||
| 结论 | 条件 |
|
||
| ---------- | ------------------------------------------------------------------------------------------------ |
|
||
| 通过 | 所有必验项通过，无 S0500/5xx/数据串仓；自动化报告全绿；页面/真机证据齐全 |
|
||
| 有条件通过 | 业务状态全通，但存在已明确不由当前终端承载的页面；替代验收证据齐全且不影响端到端业务结果 |
|
||
| 不通过 | 主链断裂、状态可绕过、权限越权、重复入账、跨客户/跨仓串数据、非预期 S0500/5xx 或关键页面不可操作 |
|
||
|
||
## 18. 验收证据目录建议
|
||
|
||
```text
|
||
虫虫出海全流程人工验收-YYYYMMDD/
|
||
01-装柜完成起点/
|
||
02-国内出仓/
|
||
03-船节点/
|
||
04-跨区尾程与入仓/
|
||
05-海外PDA签收照片/
|
||
06-FBA收货/
|
||
07-OVERSEAS逐箱收货/
|
||
08-库存托盘换标/
|
||
09-海外主数据/
|
||
10-采购卡车散板/
|
||
11-权限弱网反证/
|
||
12-自动化报告/
|
||
13-换标转运退货/
|
||
14-排车出库派送/
|
||
15-异常回访一件代发/
|
||
```
|
||
|
||
每张截图保留浏览器地址、柜号/业务单号、状态和时间；不得把密码、完整 Token、身份证件原图或其他敏感信息放入验收包。
|