From 4712b21ace5c808adf273ca0db1569f7191df78e Mon Sep 17 00:00:00 2001 From: ouyangxq <775153912@qq.com> Date: Sat, 8 Aug 2026 21:14:43 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 1 + 三期/README.md | 3 +- 三期/三期开发规划.md | 62 ++++---- 三期/三期闭环审计报告-2026-08-08.md | 234 ++++++++++++++++++++++++++++ 三期/三期需求确认表.md | 22 ++- 测试环境Jenkins部署指南.md | 167 ++++++++++++++++++++ 6 files changed, 448 insertions(+), 41 deletions(-) create mode 100644 三期/三期闭环审计报告-2026-08-08.md create mode 100644 测试环境Jenkins部署指南.md diff --git a/README.md b/README.md index ad3a621..b9a8f26 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ ## 跨阶段参考 +- [测试环境 Jenkins 部署指南](测试环境Jenkins部署指南.md)：测试环境持续部署授权、Job 参数、执行边界、健康检查与失败处理。 - `悦/`：产品原型、流程图、历史架构资料和调研数据，仅作为需求参考，不直接等同于已确认范围。 - `superpowers/`：具体功能的设计与实施记录，按日期和主题维护。 diff --git a/三期/README.md b/三期/README.md index 4b4c145..c328c2d 100644 --- a/三期/README.md +++ b/三期/README.md @@ -10,6 +10,7 @@ ## 文档 +- [三期闭环审计报告（2026-08-08）](三期闭环审计报告-2026-08-08.md)：基于当前代码、接口、自动化和测试环境证据的闭环审计，列出阻断项、优先级和 GO 准入标准。 - [三期开发规划：国内出仓](三期开发规划.md) - [三期开发进度表](三期开发进度表.md)：参考一期采用“大任务 → 详细任务 → 里程碑 → 未确认事项 → 开工准入 → 验收”结构维护。 - [虫虫出海三期开发进度表（Excel）](虫虫出海三期开发进度表.xlsx)：可筛选、可下拉维护并使用公式汇总的项目进度工作簿。 @@ -19,4 +20,4 @@ ## 当前状态 -三期处于范围规划阶段，当前开工结论为 `NO-GO`。当前以原型图片中的“完成国内出仓，等待装船”为阶段终点。动作依赖与并行关系、排柜规则、PDA 设备、拖车协作、柜封照片清单、报关回执及放行门禁、港务/船期信息范围和来源仍需在启动前确认。产品和业务完成确认后先进入契约与任务准备，六项开工准入全部通过后再进入全面功能开发；通过准入也不授权引入真实租户层。 +三期已有排柜/预装/PDA 拣货/装柜清单子链路，订舱和拖车子模块 API 也已实现并完成独立环境验证；但 2026-08-08 闭环审计结论仍为 `NO-GO`。已确认不新建出仓单，现有订单列表承载待分柜、装柜中、装柜完成和派送完成等主状态。当前缺少订单三期统一编排、五张装柜照片真实上传与硬门禁、报关协同、冲正、Client 三期协同及 PDA 真实身份/真机验收，暂不具备整期验收条件。详细缺口和 GO 标准以最新闭环审计报告为准。 diff --git a/三期/三期开发规划.md b/三期/三期开发规划.md index 50cf6f6..10678c2 100644 --- a/三期/三期开发规划.md +++ b/三期/三期开发规划.md @@ -5,6 +5,8 @@ > 流程依据：[出仓流程](参考资料/出仓流程.png)中的头程物流“03 出仓”；当前以图片中的“完成国内出仓，等待装船”为阶段终点 > 前置阶段：[一期文档](../一期/README.md) · [二期文档](../二期/README.md) +> 2026-08-08 已确认调整：三期不新建独立出仓单，现有订单列表承载全部主状态，柜次、订舱、拖车、拣货、证据和报关作为订单关联子对象。PDA 拣货后必传空仓、半仓、满仓、锁仓、带锁码照共 5 张图片，并必填锁码文本；全部真实上传成功后 PDA 装柜任务才能完结。 + > 主体模型与硬约束：三期只实现“平台—客户”两级，业务 `tenant_id > 0` / `tenantId` 当前表示客户 ID；`tenant_id=0` 是平台身份、平台 RBAC 和平台公共仓储资源技术作用域，客户往来单位、订单、文件和费用归属客户 `tenant_id>0`。禁止新增租户主表、租户选择器、客户所属租户配置、租户切换、租户级 RBAC 或租户级配置，禁止把现有 `tenant_id` 改义为上级租户 ID；历史类名、路径和字段继续兼容。 ## 一、三期目标 @@ -35,7 +37,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 | 2. 订舱 | 订舱与港务/船期信息 | P3-BOOK-01 | 已覆盖 | | 3. 预约托车 | 预约拖车 | P3-TRUCK-01 | 已覆盖，用词待 P3-Q3 确认 | | 4. PDA 拣货 | PDA 拣货与复核 | P3-PICK-01、P3-PDA-01、P3-PDA-02 | 已覆盖 | -| 5. 拍货柜及铅封照上传 | 装柜及柜封证据 | P3-LOAD-01、P3-LOAD-02 | 已补充现场拍照上传任务，清单待 P3-Q6 确认 | +| 5. 拍货柜及铅封照上传 | 装柜及柜封证据 | P3-LOAD-01、P3-LOAD-02 | 已确认空仓、半仓、满仓、锁仓、带锁码照共 5 张必传，锁码文本必填 | | 6. 客户上传报关资料 | 报关资料协同 | P3-CUS-01 | 已覆盖 | | 7. 整理给到报关代理报关 | 报关资料协同 | P3-CLEAR-01 | 已覆盖 | | 8. 回执上传到系统供客户下载 | 报关回执与客户下载 | P3-CLEAR-01、P3-CUS-02 | 已覆盖，回执类型待 P3-Q12 确认 | @@ -45,7 +47,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 ### 纳入三期 -- 出仓单、柜次、智能排柜建议、人工调整和版本确认。 +- 现有订单三期状态、订单-柜次关联、智能排柜建议、人工调整和版本确认。 - 订舱申请、舱位结果，以及原型所述预计开船、到港等港务/船期信息；具体字段和数据源待确认。 - 预约拖车、车辆司机、到仓装柜和离仓记录。 - PDA 任务领取、扫码拣货、部分拣货、异常、复核和幂等提交。 @@ -67,32 +69,28 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 | 角色 | 数据范围 | 主要操作 | |---|---|---| -| 企业订单操作员 | 当前企业订单与出仓单 | 上传/补充报关资料、查看出仓和港务/船期进度、下载回执 | -| 平台运营 | 授权客户、订单和出仓单 | 创建出仓单、确认排柜、订舱、维护港务/船期信息和协调异常 | +| 企业订单操作员 | 当前企业订单及关联柜次 | 上传/补充报关资料、查看订单后程和港务/船期进度、下载回执 | +| 平台运营 | 授权客户、订单和柜次 | 确认排柜、订舱、维护港务/船期信息和协调异常 | | 仓库主管 | 被授权的平台收货仓 | 分配拣货任务、复核差异、确认装柜和出仓条件 | | 仓库作业员 | 分配给本人或本仓的任务 | PDA 扫码、数量确认、异常上报和任务提交 | -| 拖车调度员 | 授权出仓单与车辆范围 | 预约车辆、维护司机/车牌、到仓和离仓节点 | +| 拖车调度员 | 授权订单/柜次与车辆范围 | 预约车辆、维护司机/车牌、到仓和离仓节点 | | 报关专员 | 授权客户、订单和报关批次 | 审核、退回、整理、提交资料并上传回执 | | 平台管理员 | 平台授权范围 | 维护权限、规则、服务商和高风险冲正 | -服务端必须依据登录身份确定企业、仓库、客户和数据范围。前端传入的订单 ID、出仓单 ID、仓库 ID、客户 ID、作业员 ID 或报关批次 ID 不能单独作为授权依据。 +服务端必须依据登录身份确定企业、仓库、客户和数据范围。前端传入的订单 ID、柜次 ID、仓库 ID、客户 ID、作业员 ID 或报关批次 ID 不能单独作为授权依据。 ## 四、流程与状态设计 原型以 1 至 9 编号表达动作顺序，但尚未说明哪些是强制前置、哪些允许并行。当前按原型顺序规划业务节点，同时使用主状态和子流程状态保留后续调整空间；在 P3-Q11 确认前，不把并行关系写成固定业务规则。 -### 1. 出仓单主状态 +### 1. 现有订单的三期主状态 | 稳定编码 | 中文名称 | 含义 | |---|---|---| -| `DRAFT` | 草稿 | 出仓单已创建，排柜方案尚未确认 | -| `PLANNING` | 排柜中 | 系统生成建议或人工调整方案 | -| `PREPARING` | 出仓准备中 | 按已确认的依赖关系处理订舱、拖车、拣货和报关 | -| `READY_TO_DISPATCH` | 待出仓 | 必要子流程和证据已满足 | -| `DISPATCHED` | 已出仓 | 货柜已离开国内仓库 | -| `WAITING_FOR_LOADING` | 等待装船 | 国内出仓已完成，等待对应船班装船 | -| `CANCELLED` | 已取消 | 按规则取消并保留原因与历史 | -| `BLOCKED` | 已阻塞 | 存在必须人工解除的关键异常 | +| `WAIT_SPLIT` | 待分柜 | 二期已完成，等待排柜/预装 | +| `LOADING` | 装柜中 | 预装已确认，PDA 执行拣货和装柜证据上传 | +| `LOADED` | 装柜完成 | 拣货已完成，5 张必传照片和锁码文本已通过服务端门禁 | +| `DELIVERED` | 派送完成 | 当前订单列表终态；具体触发动作和与三期终点的关系待 P3-Q13 确认 | ### 2. 子流程状态 @@ -106,13 +104,13 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 ## 五、业务模块 -### 1. 出仓单 +### 1. 现有订单与柜次 -- 从已上架且允许出仓的头程订单创建一张或多张出仓单。 -- 支持一张订单分多个柜次，也支持多个订单拼柜，具体开放范围由产品确认。 -- 保存订单、客户、仓库、货物、往来单位和计量数据快照。 -- 维护计划出仓时间、优先级、负责人、异常和整体时间线。 -- 重复创建和确认使用幂等键，并通过版本字段防止并发覆盖。 +- 不创建独立出仓单，现有订单从 `WAIT_SPLIT` 继续推进三期状态。 +- 通过订单-柜次关系表达一张订单分多柜、多张订单拼柜和拆批，具体开放范围由 P3-Q2 确认。 +- 订单保持用户当前看到的主状态；柜次承载多订单共享的订舱、拖车、装柜证据和船期信息。 +- 订单详情展示关联柜次、子流程状态、异常和整体时间线。 +- 所有主状态推进使用服务端门禁、幂等键和版本字段防止绕过与并发覆盖。 ### 2. 智能排柜 @@ -151,7 +149,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 ### 6. 装柜及柜封证据 - 维护柜号、铅封号、装柜开始/完成时间、操作人和异常说明。 -- 支持按可配置清单上传货柜及铅封照片；柜体、开门空柜、装柜过程、满柜、关门和铅封照仅为候选类型，必传类型、角度和数量以 P3-Q6 为准。 +- 必须上传空仓、半仓、满仓、锁仓、带锁码照共 5 张图片，并必填锁码文本。 - 现场执行端支持直接拍照或从相册选择后上传，上传前显示柜次、柜号、铅封号和照片类型，防止证据关联错误。 - 支持上传进度、失败重试、重复照片提示和提交前预览；弱网下不得因重复点击产生多份有效证据。 - 照片记录文件哈希、上传人、上传时间、关联柜次和客户可见范围。 @@ -186,7 +184,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 | 数据对象 | 关键内容 | |---|---| -| 出仓单 | 订单、企业、仓库、计划/实际时间、主状态、负责人和版本 | +| 现有订单三期投影 | 订单、客户、仓库、三期主状态、关联柜次、子流程摘要和版本 | | 排柜方案 | 经确认的规则版本、输入快照、柜次、货物分配、规则计算结果和确认记录 | | 柜次 | 柜型、柜号、铅封号、装载顺序、重量、体积和关联订单 | | 订舱记录 | 船公司/代理、订舱号、船名航次、港口、舱位和异常 | @@ -203,7 +201,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 ### 管理后台 `apps/admin-web` -- 出仓单列表、筛选、详情、异常和状态操作。 +- 增强现有订单列表/详情，展示柜次、各子流程、异常和状态操作。 - 按已确认的排柜规则提供建议、冲突展示、人工调整、版本对比和确认。 - 订舱、船期、拖车预约、装柜、柜号、铅封和照片。 - 报关资料审核、补件、提交批次、回执上传和客户可见控制。 @@ -211,7 +209,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 ### 企业客户端 `apps/client-web` -- 查看本企业出仓单、柜次和允许公开的进度时间线。 +- 在现有订单中查看关联柜次和允许公开的进度时间线。 - 上传、补充和查看报关资料及处理结果。 - 下载客户可见的报关回执。 - 查看预计开船、到港和船期变更，不暴露内部成本、供应商敏感信息和内部备注。 @@ -236,7 +234,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 | 里程碑 | 交付目标 | 进入条件 | |---|---|---| | P3-M0 规则与设备锁定 | 流程、角色、状态、排柜规则、PDA、文件和验收确认 | 二期到仓契约稳定 | -| P3-M1 出仓单与排柜 | 出仓单可创建，并按确认范围提供排柜建议、人工确认与追溯 | 排柜规则确认 | +| P3-M1 订单与排柜 | 现有订单可进入待分柜，并按确认范围提供柜次建议、人工确认与追溯 | 排柜规则确认 | | P3-M2 订舱与拖车 | 订舱、船期、拖车预约和异常处理可用 | 服务商与权限可用 | | P3-M3 PDA 拣货 | 任务生成、扫码、差异、复核和幂等提交可用 | 目标设备与仓库流程确认 | | P3-M4 装柜封柜 | 柜号、铅封和照片证据完整，门禁生效 | 文件能力与必传清单确认 | @@ -249,8 +247,8 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 | ID | 端 | 模块 | 交付内容 | 优先级 | 依赖 | |---|---|---|---|---|---| | P3-BASE-01 | 公共 | 出仓契约 | 主/子状态、权限、事件、错误码、门禁和快照模型 | P0 | 二期到仓契约 | -| P3-BASE-02 | 公共 | 数据模型 | 出仓单、排柜、柜次、订舱、拖车、拣货、装柜、报关和时间线 | P0 | P3-BASE-01 | -| P3-DSP-01 | 后台 | 出仓单 | 列表、筛选、创建、详情、异常和取消 | P0 | P3-BASE-02 | +| P3-BASE-02 | 公共 | 数据模型 | 现有订单三期投影、订单-柜次、排柜、订舱、拖车、拣货、装柜、报关和时间线 | P0 | P3-BASE-01 | +| P3-DSP-01 | 后台 | 订单三期编排 | 在现有订单列表/详情中接入柜次、子流程、异常、时间线和门禁操作 | P0 | P3-BASE-02 | | P3-PLAN-01 | 公共 | 排柜规则 | 按已确认规则实现输入、约束、偏好和冲突判断 | P0 | P3-BASE-02、P3-Q1 | | P3-PLAN-02 | 后台 | 智能排柜 | 按已确认范围实现建议、人工确认和追溯 | P0 | P3-PLAN-01 | | P3-BOOK-01 | 后台 | 订舱 | 订舱和经确认的船名航次、港口、变更及异常 | P0 | P3-DSP-01、P3-Q9 | @@ -259,8 +257,8 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 | P3-PICK-01 | 公共 | 拣货任务 | 按排柜方案生成任务、明细、差异和复核规则 | P0 | P3-PLAN-02 | | P3-PDA-01 | PDA | 扫码拣货 | 领取、扫描、部分拣货、跳拣、撤销和异常 | P0 | P3-PICK-01 | | P3-PDA-02 | PDA/服务端 | 弱网幂等 | 重试、去重、冲突、换班和设备缓存清理 | P0 | P3-PDA-01 | -| P3-LOAD-01 | 后台 | 装柜封柜 | 柜号、铅封号、装柜节点、可配置照片清单和复核 | P0 | P3-PICK-01、P3-Q6 | -| P3-LOAD-02 | PDA/服务端 | 柜封拍照上传 | 现场拍照/相册选择、关联确认、进度、预览、失败重试、去重和提交 | P0 | P3-LOAD-01、文件能力可用 | +| P3-LOAD-01 | 后台 | 装柜封柜 | 柜号、锁码文本、装柜节点、5 张必传照片和门禁复核 | P0 | P3-PICK-01 | +| P3-LOAD-02 | PDA/服务端 | 柜封拍照上传 | 空仓、半仓、满仓、锁仓、带锁码照的拍摄/相册选择、真实文件上传、预览、失败重试、去重和提交 | P0 | P3-LOAD-01、文件能力可用 | | P3-CUS-01 | 客户端 | 报关资料 | 清单、上传、补件、版本和进度查看 | P0 | 文件能力可用 | | P3-CLEAR-01 | 后台 | 报关协同 | 审核、退回、提交代理、批次、回执和可见范围 | P0 | P3-CUS-01 | | P3-CUS-02 | 客户端 | 回执及港务信息 | 回执下载、预计开船/到港信息、数据来源、更新时间和变更时间线 | P0 | P3-PORT-01、P3-CLEAR-01 | @@ -293,7 +291,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 | P3-Q3 | “预约托车”是否统一为“预约拖车”？ | 建议统一使用行业常用的“拖车”，并确认业务实际含义 | | P3-Q4 | 目标 PDA 型号、系统和扫描头接入方式是什么？ | 设备确认前保持适配层，不绑定厂商 SDK | | P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 若需要，完整 WMS 前置范围会显著扩大，必须单独评估 | -| P3-Q6 | 柜封照片有哪些必传角度和留存期限？ | 启动前由仓库、业务和合规共同锁定 | +| P3-Q6 | 柜封照片有哪些必传角度和留存期限？ | 已确认空仓、半仓、满仓、锁仓、带锁码照共 5 张必传，锁码文本必填；留存期限尚待确认 | | P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 建议配置化，并保留下单使用的清单版本 | | P3-Q8 | 报关代理如何接收资料和返回回执？ | 首版系统内整理加线下提交，正式接口后续评估 | | P3-Q9 | 原型中的“港务信息”具体指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 先确认业务词义和字段；首版建议平台人工维护并审计，外部接口仅预留适配层 | @@ -305,7 +303,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 ## 十二、建议实施顺序 1. 锁定待确认事项、业务规则、目标设备和协作责任人。 -2. 统一出仓单、柜次、订舱、拖车、拣货、报关和港务/船期信息的稳定编码。 +2. 统一订单、柜次、订舱、拖车、拣货、报关和港务/船期信息的稳定编码与关联契约。 3. 先实现服务端权限、状态、门禁、幂等、并发和审计，再接各端页面。 4. 完成管理后台的出仓编排，再接 PDA 现场执行和客户资料协同。 5. 使用脱敏数据演练拼柜、一单多柜、错拣、补件、改船和冲正。 diff --git a/三期/三期闭环审计报告-2026-08-08.md b/三期/三期闭环审计报告-2026-08-08.md new file mode 100644 index 0000000..d7b1340 --- /dev/null +++ b/三期/三期闭环审计报告-2026-08-08.md @@ -0,0 +1,234 @@ +# 虫虫出海三期闭环审计报告 + +> 审计日期：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 真机仍未闭环，当前不具备整期验收条件。** + +因此，现阶段不应标记“三期完成”，应标记为“**子能力已实现，闭环整改中**”。 diff --git a/三期/三期需求确认表.md b/三期/三期需求确认表.md index 1ac4b11..20b4a99 100644 --- a/三期/三期需求确认表.md +++ b/三期/三期需求确认表.md @@ -16,11 +16,11 @@ | 编号 | 决策/问题 | 当前建议 | 阻断级别 | 状态 | 负责人 | 计划确认 | 最终结论 | 影响模块 | |---|---|---|---|---|---|---|---|---| | P3-Q1 | 智能排柜需考虑哪些硬约束和软偏好？ | 业务提供可执行规则表，建议可解释并由人工确认 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 智能排柜、拣货任务 | -| P3-Q2 | 是否存在拼柜、一单多柜和拆批出仓？ | 数据模型预留能力，页面按高频场景逐步开放 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 出仓单、柜次、排柜、拣货 | +| P3-Q2 | 是否存在拼柜、一单多柜和拆批出仓？ | 通过订单-柜次关系预留能力，页面按高频场景逐步开放 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 订单、柜次、排柜、拣货 | | P3-Q3 | 原型“预约托车”是否统一为“预约拖车”？ | 建议使用行业常用的“拖车”，同时确认业务实际含义 | 非阻断 | 待确认 | 待分配 | 待排期 | - | 页面文案、接口字段说明 | | P3-Q4 | 目标 PDA 型号、系统和扫描头接入方式是什么？ | 确认前保持设备适配层，不绑定厂商 SDK | 模块阻断 | 待确认 | 待分配 | 待排期 | - | PDA 拣货、真机验收 | | P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 默认使用二期处理单元和当前位置；如需完整库存，单独评估 WMS 范围 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 二三期契约、拣货、库存边界 | -| P3-Q6 | 柜封照片有哪些必传类型、角度、数量和留存期限？ | 使用可配置清单，由仓库、业务和合规共同确认 | 模块阻断 | 待确认 | 待分配 | 待排期 | - | 装柜、PDA 拍照、文件存储、出仓门禁 | +| P3-Q6 | 柜封照片有哪些必传类型、角度、数量和留存期限？ | 使用可配置清单，由仓库、业务和合规共同确认 | 模块阻断 | 已确认 | 用户当前对话确认 | 2026-08-08 | PDA 拣货后必须上传空仓、半仓、满仓、锁仓、带锁码照共 5 张图片，并必填锁码文本；5 张全部真实上传成功后 PDA 装柜任务才能完结 | 装柜、PDA 拍照、文件存储、订单后程门禁 | | P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 清单配置化，并保存业务使用的清单版本 | 模块阻断 | 待确认 | 待分配 | 待排期 | - | 客户资料、报关审核、文件版本 | | P3-Q8 | 报关代理如何接收资料并返回回执？ | 首版系统内整理、线下提交，正式接口后续评估 | 模块阻断 | 待确认 | 待分配 | 待排期 | - | 报关协同、回执上传 | | P3-Q9 | “港务信息”指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 先确认词义和字段；首版平台人工维护并审计 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 订舱、港务查询、客户展示 | @@ -29,30 +29,36 @@ | P3-Q12 | 报关回执包含哪些类型，海关放行是否为国内出仓硬门禁？ | 当前不默认以放行为门禁，业务明确各类回执含义 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 报关状态、出仓门禁、客户回执 | | P3-Q13 | 三期终点以“等待装船”还是“装船发运”为准？ | 当前以“完成国内出仓，等待装船”为基线 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 阶段边界、状态、里程碑、验收 | -## 三、建议确认顺序 +## 三、已确认架构决策 + +| 编号 | 确认日期 | 最终结论 | 影响 | +|---|---|---|---| +| P3-D1 | 2026-08-08 | 三期不新建独立出仓单，现有订单列表承载全部主状态；柜次、订舱、拖车、拣货、证据和报关作为订单关联子对象 | 取消出仓单页面和数据模型规划，改为增强现有订单列表/详情及服务端统一编排 | + +## 四、建议确认顺序 1. 先确认 P3-Q13、P3-Q11，锁定阶段终点和流程依赖。 2. 再确认 P3-Q1、P3-Q2、P3-Q5，锁定排柜、柜次和拣货输入。 3. 然后确认 P3-Q12、P3-Q7、P3-Q8，锁定报关和出仓门禁。 4. 最后确认设备、照片、港务信息、冲正和文案事项。 -## 四、产品与业务确认会议 +## 五、产品与业务确认会议 -### 4.1 参会角色 +### 5.1 参会角色 - 产品负责人：逐项说明问题、候选方案和影响范围，维护最终结论。 - 业务负责人：确认流程、规则、例外、责任边界和客户可见范围。 - 仓库/运营代表：确认现场作业、PDA、照片、拖车、装柜和冲正可执行性。 - 研发与测试代表：识别数据、接口、设备、权限和验收风险，不代替业务作决定。 -### 4.2 会议输入 +### 5.2 会议输入 - 本确认表中的 P3-Q1～P3-Q13。 - `三期开发规划.md` 的流程、状态、里程碑和任务骨架。 - `三期页面与原型清单.md` 中已有参考原型和待补页面。 - 二期输出契约、目标 PDA 信息、文件存储能力及报关/港务协作现状。 -### 4.3 每项确认要求 +### 5.3 每项确认要求 1. 必须填写负责人、计划确认日期和可执行的最终结论，不能只记录“按建议处理”。 2. 最终结论需明确正常流程、异常/冲正、权限责任和验收口径。 @@ -60,7 +66,7 @@ 4. 开工阻断项未解除时，不得将受影响模块标记为可开发。 5. 会议结束后，将结论同步到开发规划、开发进度表、页面原型和后续验收任务。 -### 4.4 会议输出 +### 5.4 会议输出 - 13 项确认事项的状态和最终结论。 - 需要新增或调整的原型清单。 diff --git a/测试环境Jenkins部署指南.md b/测试环境Jenkins部署指南.md new file mode 100644 index 0000000..f4cd9e3 --- /dev/null +++ b/测试环境Jenkins部署指南.md @@ -0,0 +1,167 @@ +# 测试环境 Jenkins 部署指南 + +> 最后核对：2026-08-08 +> +> 本文供 Codex 对话和项目维护人员部署虫虫出海测试环境使用。只适用于测试环境，不适用于预发布或生产。 + +## 1. 持续授权与执行边界 + +用户已明确授权：当前任务确实需要把已完成的变更部署到测试环境时，Codex 可以直接触发与变更范围对应的 Jenkins 测试 Job，不必再次等待“是否部署”的确认。 + +出现以下任一情况，可以直接部署： + +- 用户明确要求部署、发布测试环境或验证测试环境。 +- 当前任务的完成标准包含远端联调、测试环境回归或浏览器验收。 +- 已修复测试环境问题，必须部署后才能验证修复结果。 + +此授权不包含以下操作；遇到时必须单独取得用户明确确认： + +- 部署 `staging` 或 `production`。 +- 勾选 `INITIALIZE_TEST_DATABASE`，或执行任何数据库写入、迁移、初始化和测试数据修改。 +- 勾选 `SKIP_TESTS`。 +- 无法明确影响范围时执行后端 `ALL` 全量部署。 +- 修改 Jenkins Job、Credentials、节点、插件、权限或系统配置。 +- 删除构建、停止他人正在执行的构建、回滚环境或清理容器/数据。 + +普通本地代码任务不因为存在 Jenkins 就自动部署。只有部署是用户要求或当前任务验收所必需时，才使用本授权。 + +## 2. 环境与认证 + +| 项目 | 地址或标识 | +|---|---| +| Jenkins | `http://8.163.30.128:14808/` | +| Jenkins 用户 | `admin` | +| 测试 Gateway | `http://8.163.30.128:9000` | +| Admin Web | `http://8.163.30.128:9001` | +| Client Web | `http://8.163.30.128:9002` | +| 后端 Git 分支 | `test` | +| Admin/Client Git 分支 | `release/test` | + +本文不保存 Jenkins 密码、API Token 或 Cookie。优先复用已登录的受控浏览器会话；没有登录会话时，从用户明确提供的安全来源获取凭据。不得把凭据写入仓库、命令行历史、脚本、日志或交付说明。 + +Jenkins 页面会显示“系统管理”“新建任务”“配置”“删除 Pipeline”等管理入口。即使当前账号具有管理权限，也只能执行本任务所需的构建和只读检查。 + +## 3. Job 与部署单元 + +| 部署单元 | Jenkins Job | 源码目录 | 流水线行为 | +|---|---|---|---| +| Admin Web | `admin-web-test` | `apps/admin-web/` | 拉取 `release/test`，构建镜像，重建容器，执行容器内 `/healthz` | +| Client Web | `client-web-test` | `apps/client-web/` | 拉取 `release/test`，构建镜像，重建容器，执行容器内 `/healthz` | +| 后端总控 | `backend-java` | `baiyue-firstleg/` | 选择变更服务并行调度下游 Job；测试环境使用 Jenkins 节点本机镜像 | + +后端下游 Job： + +- `baiyue-firstleg-gateway` +- `baiyue-firstleg-auth` +- `baiyue-firstleg-iam` +- `baiyue-firstleg-firstleg` +- `baiyue-firstleg-order` +- `baiyue-firstleg-warehouse` +- `baiyue-firstleg-file` +- `baiyue-firstleg-print` +- `baiyue-firstleg-integration-service` +- `baiyue-firstleg-event-bridge-service` +- `baiyue-firstleg-audit-service` + +正常部署后端时从 `backend-java` 总控 Job 发起。下游 Job 主要由总控调度；只有重跑同一提交的单个失败服务且已核对全部参数时，才直接操作下游 Job。 + +## 4. 部署前强制检查 + +1. 阅读目标项目及目标模块的 `AGENTS.md`，确认任务允许修改和部署该单元。 +2. 检查工作区状态，区分当前任务变更与用户已有变更。不得擅自提交或部署无关改动。 +3. 运行目标项目声明的测试和构建门禁： + - Admin：至少运行受影响测试、`pnpm typecheck` 和 `pnpm build`；交付部署前优先运行 `pnpm test`。 + - Client：至少运行 `pnpm typecheck`、受影响测试和 `pnpm build`；交付部署前优先运行 `pnpm test`。 + - Backend：优先运行 `mvn -pl -am test`；公共模块或跨服务变更按影响范围扩大验证。 +4. 确认待部署代码已经提交并推送到 Jenkins 实际拉取的远端分支。Jenkins 无法部署本地未提交或未推送的文件。 +5. 记录准备部署的仓库、分支、完整 commit SHA、Job 和后端服务列表。 +6. 在触发前通过 commentary 告知用户即将部署的 Job、commit 和范围。该通知不是等待确认；符合第 1 节授权时可继续执行。 +7. 检查 Jenkins 构建队列和执行器。不得覆盖或中断他人构建；同一 Job 正在构建时等待其结束，再重新核对远端提交。 + +如果当前工作区包含其他人的未提交改动，只有在能够证明远端目标 commit 仅包含本任务变更时才可部署。无法隔离时停止并说明阻断。 + +## 5. 前端部署 + +Admin 和 Client Job 无部署参数，触发后会直接构建并重建对应测试容器。因此触发前必须确认远端 `release/test` HEAD 就是目标提交。 + +### Admin + +1. 打开 `admin-web-test`。 +2. 核对最近构建、当前队列和远端 `release/test` 目标提交。 +3. 触发“立即构建”。 +4. 等待构建进入终态，不得只看到进入队列就结束任务。 +5. 成功后检查 `http://8.163.30.128:9001/healthz` 返回 HTTP 200 和 `ok`。 + +### Client + +1. 打开 `client-web-test`。 +2. 核对最近构建、当前队列和远端 `release/test` 目标提交。 +3. 触发“立即构建”。 +4. 等待构建进入终态。 +5. 成功后检查 `http://8.163.30.128:9002/healthz` 返回 HTTP 200 和 `ok`。 + +前端 `/healthz` 只证明容器和 Nginx 正常。任务涉及登录、接口或业务页面时，还必须按当前任务执行对应 Gateway 请求或浏览器业务验收。 + +## 6. 后端部署 + +打开 `backend-java`，选择 “Build with Parameters”。测试环境常规部署使用以下参数： + +| 参数 | 常规值 | 说明 | +|---|---|---| +| `BUILD_MODE` | `SELECT` 或已核对后的 `AUTO` | 优先显式选择受影响服务；确认提交差异完整时可用 `AUTO` | +| `SERVICE_*` | 仅勾选受影响服务 | `SELECT` 模式至少选择一个 | +| `ENVIRONMENT` | `test` | 本文禁止改为其他环境 | +| `DEPLOY` | `true` | 否则只构建镜像，不更新测试容器 | +| `INITIALIZE_TEST_DATABASE` | `false` | 修改数据库，未经单独确认不得开启 | +| `SKIP_TESTS` | `false` | 未经单独确认不得跳过测试 | +| `IMAGE_REPOSITORY` | 保持测试默认值 | `test` 会解析为 `baiyue-firstleg-test` | +| `DOCKER_BASE_IMAGE` | 保持 Job 默认值 | 除非任务明确要求变更基础镜像 | +| `DOWNSTREAM_JOB_PREFIX` | `baiyue-firstleg-` | 与现有 11 个下游 Job 对应 | + +选择规则： + +- 单服务业务代码：选择该服务，并检查内部客户端或契约消费者是否也需要部署。 +- `common-*`、父 `pom.xml`、`platform-bom/`、`Jenkinsfile*` 或 `deploy/` 变化：`AUTO` 会选择全部 11 个服务；全量部署前仍需按第 1 节取得确认。 +- Gateway 路由、CORS 或访问域变化：选择 `gateway`，并检查受影响业务服务。 +- 跨服务 DTO/OpenAPI/内部客户端变化：同时选择生产者和消费者。 +- 数据库结构变化：不能仅部署服务。先按数据库变更规则取得明确授权并完成迁移，再部署依赖该结构的服务。 +- File 服务部署依赖 Jenkins 文件凭据 `firstleg-test-env` 中有效的 `ROCKETMQ_NAME_SERVER`，且 `MQ_TOPIC_PREFIX` 必须为 `test-`。 + +总控 Job 成功不应只看主任务颜色。必须核对描述或日志中的每个下游结果均为 `SUCCESS`。出现任一 `FAILURE` 时，总控可能显示 `UNSTABLE`；这种情况视为部署失败。 + +## 7. 部署后验证 + +每次部署至少完成以下检查： + +1. Jenkins Job 已进入终态，记录构建号、结果、commit 和耗时。 +2. 后端总控部署记录全部下游 Job 名称、构建号和结果。 +3. 前端健康检查： + - `GET http://8.163.30.128:9001/healthz` + - `GET http://8.163.30.128:9002/healthz` +4. 后端入口检查：`GET http://8.163.30.128:9000/actuator/health` 返回 HTTP 200。 +5. 执行与变更直接相关的真实 API 或浏览器流程。健康检查不能代替业务验收。 +6. 失败响应记录 HTTP 状态、业务错误码、`requestId`、`traceId` 和阻断原因。 + +不得因为 Jenkins 成功就宣称业务验收通过，也不得让测试失败回退为模拟成功。 + +## 8. 失败处理 + +- 构建失败：读取失败阶段和控制台日志，定位第一个有效错误；修复并完成本地验证后，用新 commit 重新部署。 +- 下游服务失败：记录失败的服务 Job 和构建号，检查 Maven 测试、镜像构建、环境凭据及 Docker Compose 输出。 +- 部署成功但健康检查失败：检查对应 Job 的容器状态和末尾日志，不切换为本地后端。 +- 健康检查成功但业务失败：记录请求证据，核对数据库迁移、Nacos 配置、服务注册和真实接口契约。 +- 不得在未确认影响的情况下通过跳过测试、初始化数据库、清理工作区外数据或全量重启来“试一下”。 + +失败后不要自动回滚、删除容器或修改测试数据。需要这些动作时先向用户说明具体目标、影响和恢复方案并取得确认。 + +## 9. 交付记录 + +部署完成后，最终回复至少包含： + +- 部署的环境、Job 和服务范围。 +- 分支与 commit SHA。 +- Jenkins 构建号及最终结果。 +- 健康检查和直接业务验证结果。 +- 任何失败、跳过项、残余风险及 `requestId`/`traceId`。 + +不要在回复中输出密码、Token、Cookie、Jenkins Credential 内容或环境文件内容。