docs/三期/三期闭环审计报告-2026-08-08.md

# 虫虫出海三期闭环审计报告

> 审计日期：2026-08-08  
> 审计范围：二期终点→智能排柜→订舱→拖车→PDA 拣货→装柜/柜封证据→报关协同→国内出仓→等待装船  
> 审计对象：Admin、Client、PDA、`baiyue-firstleg` 后端、OpenAPI/SQL、自动化测试与现有测试环境报告  
> 结论：**NO-GO，当前不能按“三期业务闭环”验收**

## 1. 执行摘要

当前已实现多个真实持久化的三期子能力，不是纯页面原型：智能装柜/预装、订舱、拖车、PDA 拣货接口、装柜证据元数据和装柜清单均已有后端实现，订舱和拖车 API 也已在测试环境完成独立生命周期验证。

用户已于 2026-08-08 确认：**三期不新建独立出仓单，现有订单列表就是主流程承载面**，当前页面使用“待分柜→装柜中→装柜完成→派送完成”状态。因此“没有出仓单”不再是缺口；真正的缺口是现有订单与柜次、订舱、拖车、拣货、装柜证据和报关子流程尚未统一编排，服务端也没有为订单终态提供组合门禁。

最重要的判断是：

- **已经做出了“排柜到装柜清单”的技术子链路。**
- **订舱和拖车是可独立运行的业务模块，但尚未与出仓主链强绑定。**
- **报关资料/补件/代理提交/回执/客户下载基本未建模。**
- **现有订单的统一后程门禁、冲正和终态业务含义尚未闭合。**
- **Client 没有三期协同入口，PDA 仍是演示数据与真实接口混合，尚未完成真实身份、任务领取、文件上传和真机验收。**

## 2. 闭环判定口径

本次不以“有页面”、“有 Controller”或“单模块测试全绿”作为闭环标准。三期只有同时满足以下条件才算闭环：

1. 同一个真实客户订单能从二期终点 `WAIT_SPLIT + APPROVED + CONFIRMED` 进入三期。
2. 同一订单可追溯所属柜次、排柜方案、订舱、拖车、拣货、装柜证据、报关文件与回执。
3. 服务端独立校验所有强制前置，不能靠页面按钮顺序保证。
4. 弱网、重复提交、并发、越权、证据缺失和冲正均有明确行为和审计记录。
5. Admin、Client、PDA 都能用真实身份和真实数据完成各自职责。
6. 订单终态及“派送完成”的触发动作、业务含义和必备门禁已明确。
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、船名航次等字段 | 部分具备 | 无来源、更新时间和过期标识；无独立客户查询端 | P1 |
| 国内出仓门禁 | 有 `LOADING -> LOADED -> DELIVERED` | **未具备** | 无统一门禁、无确认出仓、无冲正、无 `WAITING_FOR_LOADING` | P0 |
| 客户三期可见性 | 订单详情有拣货/装柜少量只读摘要 | 严重不足 | 无柜次、报关、回执、船期变更时间线 | P0 |

## 4. 核心阻断项

### P0-1：现有订单缺少三期统一编排和服务端门禁

产品已确认不新建独立出仓单，因此应复用现有订单作为三期主对象，柜次作为多订单共享的执行对象。当前问题不是少一张单，而是订单状态与各子流程尚未由统一编排器计算。

当前实际是四条彼此独立的状态链：

```text
装柜计划：EDITING -> LOADING -> COMPLETED
入库单后程：LOADING -> LOADED -> DELIVERED
订舱：DRAFT -> SUBMITTED -> CONFIRMED -> RELEASED
拖车：DRAFT -> ... -> DEPARTED -> COMPLETED
```

订单上没有一个汇聚节点计算“是否可进入下一状态”，因此即使四条链各自通过，也不等于三期闭环。应在现有订单/入库履约聚合上增加统一编排，不应新建重复的出仓单业务对象。

### P0-2：装柜完成可绕过拣货和柜封证据

`LoadingDeliveryService` 在类注释中明确声明“不检查证据完整度，不阻断业务流转”。`completeLoading` 只校验当前状态为 `LOADING`，没有校验：

- 柜次级拣货是否全部复核完成；
- 入库单级汇总拣货是否与柜次明细一致；
- 空仓、半仓、满仓、锁仓、带锁码照 5 张必传图片及锁码文本是否齐全；
- 铅封号是否重复；
- 拖车是否已离仓；
- 报关与船期门禁是否满足。

现有单元测试 `completesLoadingWithoutEvidenceGate` 还把“无证据也可完成”固化成预期，与三期规划直接冲突。

### P0-3：报关协同和回执链路未实现

当前未找到以下业务对象和契约：

- 按国家/渠道/货物类型选择的报关资料清单及版本；
- 客户上传、替换、补件和进度；
- 平台完整性审核、退回原因和截止时间；
- 提交报关代理批次及文件版本冻结；
- 接收/申报/退单/查验/放行等回执类型；
- 客户可见范围和授权下载；
- 回执或海关放行与出仓门禁的关系。

数据库中的 `CUSTOMS_CLEARANCE` 文档类型只是占位，不构成业务闭环。

### P0-4：Admin 的后半程组件未装配，订舱 UI 与后端契约错配

- `UnifiedOrderWorkflowPanel.vue` 已有排柜、拣货、证据和完成装柜交互，但对应作业页未注册到正式路由，统一订单详情也未引用该组件。
- Admin 现有订单详情没有正式的报关、回执和后程门禁操作面板。
- 订舱新建页把 `expectedVersion` 初始化为 `null`，而后端创建请求要求非空且大于等于 0。
- 后端创建订舱返回 Detail 对象，前端 API 按字符串解包并直接用作路由 ID。
- 订舱状态操作在前端统一用 edit 权限，后端对 submit/confirm/release/change/cancel 使用独立权限和特定 DTO。

测试环境订舱 API 23/23 通过，证明后端模块可用；上述问题说明浏览器端真实操作仍需独立验收。

### P0-5：Client 和 PDA 没有形成真实角色闭环

Client 只在头程订单详情中显示“拣货进度”和“装柜资料”摘要，没有报关上传/补件、回执下载、船期变更和柜次时间线。

PDA 已有调用拣货/证据/装柜接口的适配代码，但当前仍存在：

- 登录使用演示账号，Token、客户和 API Base 由本地选项注入，不是真实仓库作业身份；
- 任务列表和页面仍保留演示数据与本地成功分支；
- 拍照后把本地临时路径放进 `fileName`，未先上传 File 服务获得 `fileId`；
- 无任务领取/作业员分配/后台复核闭环；
- 无可验证的 Android/HBuilderX 构建命令，未做真机连续扫码、断网重连、前后台切换和重复提交验收。

## 5. 已实现且可保留的能力

本次 NO-GO 不代表三期必须重做。以下能力已有明确复用价值：

- 柜次、智能装柜、预装和装柜清单的持久化模型。
- 订舱 `DRAFT -> SUBMITTED -> CONFIRMED -> RELEASED` 生命周期、历史和幂等。
- 拖车从草稿到完成的状态、历史和附件后端能力。
- 柜次级 PDA 明细拣货、部分拣货和跳过与防重操作。
- 装柜证据文件归属校验、业务历史、乐观锁和部分幂等基础。
- Admin 订舱和拖车页面壳、统一订单后半程组件。
- Client 对统一订单三期只读摘要的兼容映射。

## 6. 需求确认项重新定性

`P3-Q1` 至 `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 三期终点 | 实际终态与规划不一致 | 必须在统一状态机前确认 |

## 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` 贯穿到三期终点。
- 订舱、拖车、柜次、拣货、证据和报关关联到同一批订单/柜次。
- 缺拣货复核、缺照片、缺铅封、拖车未离仓或报关未满足时，确认出仓必须失败。
- 两个并发确认出仓请求只产生一次状态迁移和一条有效审计事件。
- 出仓后冲正不直接篡改旧状态，且有反向审计记录。
- 客户 A 无法查看、上传或下载客户 B 的报关文件与回执。
- PDA 真实设备弱网、连续扫描、重复扫码、前后台切换和重复提交。

## 8. 建议修复顺序

### 里程碑 A：锁定业务契约（P0）

1. 由产品/业务对 P3-Q1/Q2/Q5/Q6/Q7/Q8/Q10/Q11/Q12/Q13 给出最终结论。
2. 固定三期终点为“国内出仓完成，等待装船”，或明确替代终点。
3. 定义哪些前置必须完成，哪些子流程允许并行。

### 里程碑 B：在现有订单上建立三期统一编排与门禁（P0）

1. 复用现有订单主状态，补齐订单-柜次关联、整体时间线、版本和审计投影，不新建出仓单。
2. 将排柜、订舱、拖车、拣货、证据和报关子流程绑定到订单/柜次。
3. 服务端实现 `check gate`、最终状态推进、冲正和并发/幂等。
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、终态和审计事件的验收报告。

## 9. GO 准入标准

以下条件全部满足后，才建议将三期从 NO-GO 改为 GO：

- [ ] P3-Q1至P3-Q13 已有明确结论，文档与代码口径一致。
- [ ] 现有订单可通过柜次追溯全部三期子流程。
- [ ] 统一出仓门禁在服务端生效，负向场景全部阻断。
- [ ] 报关资料、补件、代理提交、回执和客户下载闭环。
- [ ] Admin 所有三期正式入口可达，前后端 DTO 和权限一致。
- [ ] Client 只能访问当前客户的三期数据和文件。
- [ ] PDA 真实鉴权、任务、扫码、文件上传、弱网和重试已真机通过。
- [ ] 确认出仓后进入已确认的三期终态，并支持授权冲正。
- [ ] 同一测试订单完成全链路正向与负向验收，证据可重放。

## 10. 最终结论

当前三期建议对外口径为：

> **三期已确认复用现有订单列表承载全部状态，不新建出仓单；已完成排柜/预装/PDA 拣货/装柜清单子链路，订舱和拖车 API 可用。但订单三期统一编排、五张装柜照片硬门禁、报关协同、冲正、Client 协同和 PDA 真机仍未闭环，当前不具备整期验收条件。**

因此，现阶段不应标记“三期完成”，应标记为“**子能力已实现，闭环整改中**”。