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

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

审计日期：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、船名航次等字段	部分具备	无来源、更新时间和过期标识；无独立客户查询端	P1
装柜完成门禁	有 LOADING -> LOADED，但当前可无证据完成	未具备	未强制校验 PDA 拣货、5 张真实图片和锁码文本；无冲正	P0
海外仓回传边界	有平台手工 DELIVERED 动作	契约冲突	国内端可手工推进派送完成；缺海外仓可信来源、签名、防重放、幂等和审计契约	P0/跨阶段
客户三期可见性	订单详情有拣货/装柜少量只读摘要	严重不足	无柜次、报关、回执、船期变更时间线	P0

4. 核心阻断项

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

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

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

装柜计划：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 的现有能力必须整改，当前不具备整期验收条件。

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