242 lines
17 KiB
Markdown
242 lines
17 KiB
Markdown
# 虫虫出海国内货柜履约闭环审计报告
|
||
|
||
> 审计日期：2026-08-08
|
||
> 审计范围：入库测量与计费终点→智能排柜→订舱→拖车→PDA 拣货→装柜/柜封证据→`LOADED`/装柜完成
|
||
> 审计对象：Admin、Client、PDA、`baiyue-firstleg` 后端、OpenAPI/SQL、自动化测试与现有测试环境报告
|
||
> 结论：**NO-GO，当前不能按“国内货柜履约业务闭环”验收**
|
||
|
||
## 1. 执行摘要
|
||
|
||
当前已实现多个真实持久化的国内货柜履约子能力，不是纯页面原型：智能装柜/预装、订舱、拖车、PDA 拣货接口、装柜证据元数据和装柜清单均已有后端实现，订舱和拖车 API 也已在测试环境完成独立生命周期验证。
|
||
|
||
用户已于 2026-08-08 确认：**国内货柜履约不新建独立出仓单，现有订单列表就是主流程承载面；国内国内货柜履约以 `LOADED`/装柜完成为终点**。`DELIVERED`/派送完成只能在货物到达海外仓后由海外仓可信回传推进，不属于国内国内货柜履约操作和验收范围。因此“没有出仓单”不再是缺口；真正的缺口是现有订单与柜次、订舱、拖车、拣货、装柜证据和报关子流程尚未统一编排，服务端也没有为进入 `LOADED` 提供组合门禁。
|
||
|
||
最重要的判断是：
|
||
|
||
- **已经做出了“排柜到装柜清单”的技术子链路。**
|
||
- **订舱和拖车是可独立运行的业务模块，但尚未与出仓主链强绑定。**
|
||
- **报关资料/补件/代理提交/回执/客户下载基本未建模。**
|
||
- **现有订单进入 `LOADED` 的统一门禁和冲正尚未闭合；平台手工推进 `DELIVERED` 的现有接口与最新业务边界冲突。**
|
||
- **Client 没有国内货柜履约协同入口，PDA 仍是演示数据与真实接口混合，尚未完成真实身份、任务领取、文件上传和真机验收。**
|
||
|
||
## 2. 闭环判定口径
|
||
|
||
本次不以“有页面”、“有 Controller”或“单模块测试全绿”作为闭环标准。国内货柜履约只有同时满足以下条件才算闭环：
|
||
|
||
1. 同一个真实客户订单能从入库测量与计费终点 `WAIT_SPLIT + APPROVED + CONFIRMED` 进入国内货柜履约。
|
||
2. 同一订单可追溯所属柜次、排柜方案、订舱、拖车、拣货、装柜证据、报关文件与回执。
|
||
3. 服务端独立校验所有强制前置，不能靠页面按钮顺序保证。
|
||
4. 弱网、重复提交、并发、越权、证据缺失和冲正均有明确行为和审计记录。
|
||
5. Admin、Client、PDA 都能用真实身份和真实数据完成各自职责。
|
||
6. 订单能在服务端门禁通过后进入 `LOADED`/装柜完成；国内端不能手工推进 `DELIVERED`。
|
||
7. 有一条测试环境证据，让同一业务对象贯穿全流程，并完成负向门禁验证。
|
||
|
||
## 3. 国内货柜履约业务矩阵
|
||
|
||
| 环节 | 当前能力 | 审计结论 | 主要缺口 | 优先级 |
|
||
|---|---|---|---|---|
|
||
| 入库测量与计费入口 | 统一订单已有 `WAIT_SPLIT` 投影 | 部分具备 | 没有一条验收数据从入库测量与计费贯穿到国内货柜履约终点 | P0 |
|
||
| 订单国内货柜履约主编排 | 订单列表已承载待分柜、装柜中、装柜完成等状态 | 部分具备 | 无订单级统一门禁、子流程关联和整体时间线；不需新建出仓单 | P0 |
|
||
| 智能排柜 | 有容量型推荐、预装和持久化 | 部分具备 | 无业务硬约束/软偏好规则版本、冲突解释、独立方案确认和版本对比 | P0 |
|
||
| 订舱/船期 | 后端生命周期可用，测试环境 API 已通过 | 部分具备 | Admin 创建/版本/返回 DTO 存在契约错配；未与订单/柜次强关联；无数据来源和时效语义 | P0 |
|
||
| 拖车预约 | 后端和 Admin 正式模块已存在，API 生命周期已验证 | 部分具备 | 与订单国内货柜履约编排未汇聚；前端需手填多个关联 ID；附件上传未接入；幂等重放不完整 | P0 |
|
||
| PDA 拣货 | 有柜次级拣货服务和入库单级汇总接口 | 部分具备 | 两套语义可互相绕过；无领取/分配/复核/异常挂起/撤销闭环；未校验实时处理单元与库位量 | P0 |
|
||
| 装柜/柜封证据 | 有证据元数据和 File 归属校验 | 部分具备 | 已确认空仓、半仓、满仓、锁仓、带锁码照共 5 张必传，锁码文本必填；当前 Admin/PDA 真实文件上传和服务端硬门禁未实现 | P0 |
|
||
| 客户上传报关资料 | Client 无正式入口 | **未具备** | 无清单版本、上传、补件、进度和客户隔离契约 | P0 |
|
||
| 平台报关协同 | 仅有历史文档类型占位 | **未具备** | 无审核退回、补件、代理提交批次、文件版本冻结 | P0 |
|
||
| 回执上传/客户下载 | 无业务模型和页面 | **未具备** | 无回执类型、版本、可见范围、下载授权和门禁关联 | P0 |
|
||
| 出仓后港务/船节点查询 | 订舱实体有 ETD/ETA、船名航次等字段 | 已重新归入海外仓业务 | 本历史审计发现的来源、更新时间、过期标识和客户查询端缺口由海外仓业务承接，不再作为国内货柜履约闭环缺口 | 海外仓业务 |
|
||
| 装柜完成门禁 | 有 `LOADING -> LOADED`，但当前可无证据完成 | **未具备** | 未强制校验 PDA 拣货、5 张真实图片和锁码文本；无冲正 | P0 |
|
||
| 海外仓回传边界 | 有平台手工 `DELIVERED` 动作 | **契约冲突** | 国内端可手工推进派送完成；缺海外仓可信来源、签名、防重放、幂等和审计契约 | P0/跨业务域 |
|
||
| 客户国内货柜履约可见性 | 订单详情有拣货/装柜少量只读摘要 | 严重不足 | 无柜次、报关、回执、船期变更时间线 | P0 |
|
||
|
||
## 4. 核心阻断项
|
||
|
||
### P0-1：现有订单缺少国内货柜履约统一编排和服务端门禁
|
||
|
||
产品已确认不新建独立出仓单，因此应复用现有订单作为国内货柜履约主对象，柜次作为多订单共享的执行对象。当前问题不是少一张单，而是订单状态与各子流程尚未由统一编排器计算。
|
||
|
||
当前实际是四条彼此独立的状态链：
|
||
|
||
```text
|
||
装柜计划：EDITING -> LOADING -> COMPLETED
|
||
订单国内国内货柜履约：WAIT_SPLIT -> LOADING -> LOADED
|
||
海外仓后续回传：LOADED -> DELIVERED
|
||
订舱：DRAFT -> SUBMITTED -> CONFIRMED -> RELEASED
|
||
拖车：DRAFT -> ... -> DEPARTED -> COMPLETED
|
||
```
|
||
|
||
订单上没有一个汇聚节点计算“是否可进入下一状态”，因此即使四条链各自通过，也不等于国内货柜履约闭环。应在现有订单/入库履约聚合上增加统一编排，不应新建重复的出仓单业务对象。
|
||
|
||
### P0-2：装柜完成可绕过拣货和柜封证据
|
||
|
||
`LoadingDeliveryService` 在类注释中明确声明“不检查证据完整度，不阻断业务流转”。`completeLoading` 只校验当前状态为 `LOADING`，没有校验：
|
||
|
||
- 柜次级拣货是否全部复核完成；
|
||
- 入库单级汇总拣货是否与柜次明细一致；
|
||
- 空仓、半仓、满仓、锁仓、带锁码照 5 张必传图片及锁码文本是否齐全；
|
||
- 铅封号是否重复；
|
||
- 订舱、拖车和报关是否属于进入 `LOADED` 的硬门禁（P3-Q11/P3-Q12 尚待确认）。
|
||
|
||
现有单元测试 `completesLoadingWithoutEvidenceGate` 还把“无证据也可完成”固化成预期，与国内货柜履约规划直接冲突。
|
||
|
||
### P0-3：国内端可手工推进海外仓状态
|
||
|
||
当前存在平台手工完成派送的 `POST /delivery/complete` 能力，但最新业务确认是：只有货物到达海外仓后，才能由海外仓可信回传推进 `DELIVERED`。因此该操作必须从国内 Admin/PDA 的国内货柜履约入口移除或禁用；后续海外仓回传接口需单独定义来源认证、签名/时间窗、防重放、幂等和审计。该接口整改是状态边界修复，但海外仓业务本身不纳入国内货柜履约验收。
|
||
|
||
### P0-4：报关协同和回执链路未实现
|
||
|
||
当前未找到以下业务对象和契约：
|
||
|
||
- 按国家/渠道/货物类型选择的报关资料清单及版本；
|
||
- 客户上传、替换、补件和进度；
|
||
- 平台完整性审核、退回原因和截止时间；
|
||
- 提交报关代理批次及文件版本冻结；
|
||
- 接收/申报/退单/查验/放行等回执类型；
|
||
- 客户可见范围和授权下载；
|
||
- 回执或海关放行与装柜完成门禁的关系。
|
||
|
||
数据库中的 `CUSTOMS_CLEARANCE` 文档类型只是占位，不构成业务闭环。
|
||
|
||
### P0-5：Admin 的后半程组件未装配，订舱 UI 与后端契约错配
|
||
|
||
- `UnifiedOrderWorkflowPanel.vue` 已有排柜、拣货、证据和完成装柜交互，但对应作业页未注册到正式路由，统一订单详情也未引用该组件。
|
||
- Admin 现有订单详情没有正式的报关、回执和后程门禁操作面板。
|
||
- 订舱新建页把 `expectedVersion` 初始化为 `null`，而后端创建请求要求非空且大于等于 0。
|
||
- 后端创建订舱返回 Detail 对象，前端 API 按字符串解包并直接用作路由 ID。
|
||
- 订舱状态操作在前端统一用 edit 权限，后端对 submit/confirm/release/change/cancel 使用独立权限和特定 DTO。
|
||
|
||
测试环境订舱 API 23/23 通过，证明后端模块可用；上述问题说明浏览器端真实操作仍需独立验收。
|
||
|
||
### P0-6：Client 和 PDA 没有形成真实角色闭环
|
||
|
||
Client 只在头程订单详情中显示“拣货进度”和“装柜资料”摘要，没有报关上传/补件、回执下载、船期变更和柜次时间线。
|
||
|
||
PDA 已有调用拣货/证据/装柜接口的适配代码，但当前仍存在：
|
||
|
||
- 登录使用演示账号，Token、客户和 API Base 由本地选项注入，不是真实仓库作业身份；
|
||
- 任务列表和页面仍保留演示数据与本地成功分支；
|
||
- 拍照后把本地临时路径放进 `fileName`，未先上传 File 服务获得 `fileId`；
|
||
- 无任务领取/作业员分配/后台复核闭环；
|
||
- 无可验证的 Android/HBuilderX 构建命令，未做真机连续扫码、断网重连、前后台切换和重复提交验收。
|
||
|
||
## 5. 已实现且可保留的能力
|
||
|
||
本次 NO-GO 不代表国内货柜履约必须重做。以下能力已有明确复用价值：
|
||
|
||
- 柜次、智能装柜、预装和装柜清单的持久化模型。
|
||
- 订舱 `DRAFT -> SUBMITTED -> CONFIRMED -> RELEASED` 生命周期、历史和幂等。
|
||
- 拖车从草稿到完成的状态、历史和附件后端能力。
|
||
- 柜次级 PDA 明细拣货、部分拣货和跳过与防重操作。
|
||
- 装柜证据文件归属校验、业务历史、乐观锁和部分幂等基础。
|
||
- Admin 订舱和拖车页面壳、统一订单后半程组件。
|
||
- Client 对统一订单国内货柜履约只读摘要的兼容映射。
|
||
|
||
## 6. 需求确认项重新定性
|
||
|
||
`P3-Q6`、`P3-Q13` 和“不新建独立出仓单”已经确认，其余事项仍需按影响范围继续确认。结合现代码，可重新定性为：
|
||
|
||
| 编号 | 当前代码事实 | 审计定性 |
|
||
|---|---|---|
|
||
| P3-Q1 排柜规则 | 仅基础容量贪心推荐 | 仍为 P0 产品/业务阻断 |
|
||
| P3-Q2 拼柜/一单多柜/拆批 | 已确认不新建出仓单；拼柜和拆批应由订单-柜次关系表达 | 仍需确认具体可开放场景 |
|
||
| P3-Q3 “拖车”用词 | 代码已统一使用拖车 | 可直接确认，非阻断 |
|
||
| P3-Q4 PDA 设备 | 有广播适配，无目标设备和真机验收 | 仍为上线阻断 |
|
||
| P3-Q5 实时库存/库位 | `locationIds` 未进入服务业务校验 | 仍为 P0 流程阻断 |
|
||
| P3-Q6 柜封照片 | 已确认 5 张必传：空仓、半仓、满仓、锁仓、带锁码照；锁码文本必填 | 需实现文件上传与服务端硬门禁 |
|
||
| P3-Q7/Q8/Q12 报关 | 业务模型未实现 | 仍为 P0 范围和契约阻断 |
|
||
| P3-Q9 港务 | 仅有订舱船期字段 | 仍为 P1，但必须在客户展示前确认 |
|
||
| P3-Q10 冲正 | 无 reverse 动作 | 仍为 P0 高风险状态阻断 |
|
||
| P3-Q11 强制前置/并行 | 子模块彼此独立 | 仍为 P0 统一门禁阻断 |
|
||
| P3-Q13 国内货柜履约终点 | 已确认国内终点为 `LOADED`；`DELIVERED` 由海外仓回传 | 已解除范围阻断；需整改国内手工派送接口 |
|
||
|
||
## 7. 自动化和环境证据
|
||
|
||
### 7.1 本次实际执行
|
||
|
||
| 项目 | 命令 | 结果 |
|
||
|---|---|---|
|
||
| Admin | `pnpm test` | 80 个测试文件，418 项通过 |
|
||
| Admin | `pnpm build` | 通过，包含 TypeScript 检查 |
|
||
| Client | `pnpm test` | 176 项通过 |
|
||
| Client | `pnpm build` | 通过，包含 TypeScript 检查 |
|
||
| PDA | `node --test tests/*.test.mjs` | 32 项通过 |
|
||
| Backend | `.\scripts\backend-full-regression.ps1` | Reactor 成功；最终 firstleg 报告 391 项、0 失败、0 错误、2 跳过 |
|
||
|
||
### 7.2 已有测试环境证据
|
||
|
||
`reports/admin-test-env-acceptance-all-green-20260808.json` 记录 Gateway `http://8.163.30.128:9000` 的 549/549 项通过，其中订舱 23 项、拖车 43 项、service-center-flow 10 项。这证明已部署子模块的 API 生命周期可用。
|
||
|
||
`docs/入库测量与计费及国内货柜履约业务功能测试回归报告.md` 在 2026-08-07 将“国内货柜履约结果”写为通过，但其明确的国内货柜履约测试范围只有：虚拟柜、智能装柜、预装、PDA 拣货和最终装柜清单。该结论应改名为“国内货柜履约装柜子链路通过”，不应作为整期闭环证据。
|
||
|
||
### 7.3 测试缺口
|
||
|
||
当前缺少以下验收证据：
|
||
|
||
- 同一订单从入库测量与计费 `WAIT_SPLIT` 贯穿到国内货柜履约终点。
|
||
- 订舱、拖车、柜次、拣货、证据和报关关联到同一批订单/柜次。
|
||
- 未完成 PDA 拣货、缺任意一张必传照片或缺锁码文本时，进入 `LOADED` 必须失败。
|
||
- 若 P3-Q11/P3-Q12 将订舱、拖车或报关确认为硬门禁，对应前置未满足时进入 `LOADED` 必须失败。
|
||
- 两个并发装柜完成请求只产生一次状态迁移和一条有效审计事件。
|
||
- 装柜完成后冲正不直接篡改旧状态，且有反向审计记录。
|
||
- 国内 Admin/PDA 无法手工进入 `DELIVERED`；伪造、重放或重复的海外仓回传不能重复推进状态。
|
||
- 客户 A 无法查看、上传或下载客户 B 的报关文件与回执。
|
||
- PDA 真实设备弱网、连续扫描、重复扫码、前后台切换和重复提交。
|
||
|
||
## 8. 建议修复顺序
|
||
|
||
### 里程碑 A：锁定业务契约（P0）
|
||
|
||
1. 由产品/业务对尚未确认的 P3-Q1/Q2/Q5/Q7/Q8/Q10/Q11/Q12 给出最终结论。
|
||
2. 按已确认结论固定国内货柜履约终点为 `LOADED`/装柜完成，并将 `DELIVERED` 移出国内国内货柜履约状态操作。
|
||
3. 定义订舱、拖车和报关中哪些是进入 `LOADED` 的强制前置，哪些允许并行。
|
||
|
||
### 里程碑 B：在现有订单上建立国内货柜履约统一编排与门禁（P0）
|
||
|
||
1. 复用现有订单主状态，补齐订单-柜次关联、整体时间线、版本和审计投影，不新建出仓单。
|
||
2. 将排柜、订舱、拖车、拣货、证据和报关子流程绑定到订单/柜次。
|
||
3. 服务端实现装柜完成 `check gate`、`LOADED` 状态推进、冲正和并发/幂等。
|
||
4. 禁止入库单汇总拣货绕过柜次明细拣货与复核。
|
||
|
||
### 里程碑 C：补齐报关与文件闭环（P0）
|
||
|
||
1. 建立资料清单版本、客户文件版本、补件、代理提交批次、回执和可见范围。
|
||
2. Client 实现上传/补件/回执下载，Admin 实现审核/退回/提交/回执上传。
|
||
3. Admin/PDA 证据上传必须先经 File 服务获得 `fileId`，不得使用文件名或本地路径代替。
|
||
|
||
### 里程碑 D：接通三端（P0）
|
||
|
||
1. 修复 Admin 订舱 DTO/版本/动作权限，将后半程作业页挂到正式路由。
|
||
2. 拖车从可选资源中关联订单、订舱和柜次，不让用户手填 ID。
|
||
3. Client 增加出仓进度、柜次、报关、回执和船期变更。
|
||
4. PDA 接真实仓库身份、任务领取、服务端详情和文件上传，删除正式业务中的演示成功分支。
|
||
|
||
### 里程碑 E：端到端验收（P0）
|
||
|
||
1. 使用一个独立测试客户和一组可追溯订单完成全链路。
|
||
2. 按本报告 7.3 节逐项做负向、权限、并发、幂等和冲正验收。
|
||
3. 在目标 PDA 真机上完成弱网与扫码验收。
|
||
4. 输出包含订单 ID、柜次 ID、订舱 ID、拖车 ID、证据 ID、报关批次 ID、`LOADED` 状态和审计事件的验收报告。
|
||
|
||
## 9. GO 准入标准
|
||
|
||
以下条件全部满足后，才建议将国内货柜履约从 NO-GO 改为 GO：
|
||
|
||
- [ ] P3-Q1至P3-Q13 已有明确结论，文档与代码口径一致。
|
||
- [ ] 现有订单可通过柜次追溯全部国内货柜履约子流程。
|
||
- [ ] 装柜完成门禁在服务端生效，缺 PDA 拣货、任一必传照片或锁码文本时不能进入 `LOADED`。
|
||
- [ ] 报关资料、补件、代理提交、回执和客户下载闭环。
|
||
- [ ] Admin 所有国内货柜履约正式入口可达，前后端 DTO 和权限一致。
|
||
- [ ] Client 只能访问当前客户的国内货柜履约数据和文件。
|
||
- [ ] PDA 真实鉴权、任务、扫码、文件上传、弱网和重试已真机通过。
|
||
- [ ] 装柜完成后进入 `LOADED` 并支持授权冲正，国内端不能手工推进 `DELIVERED`。
|
||
- [ ] 同一测试订单完成全链路正向与负向验收，证据可重放。
|
||
|
||
## 10. 最终结论
|
||
|
||
当前国内货柜履约建议对外口径为：
|
||
|
||
> **国内货柜履约已确认复用现有订单列表承载全部主状态，不新建出仓单，国内终点为 `LOADED`/装柜完成；已完成排柜/预装/PDA 拣货/装柜清单子链路，订舱和拖车 API 可用。但订单国内货柜履约统一编排、五张装柜照片与锁码文本硬门禁、报关协同、冲正、Client 协同和 PDA 真机仍未闭环，且国内手工推进 `DELIVERED` 的现有能力必须整改，当前不具备整期验收条件。**
|
||
|
||
因此，现阶段不应标记“国内货柜履约完成”，应标记为“**子能力已实现，闭环整改中**”。
|