From 82c3ef841395ecf9f08197eeba0baf956b024f39 Mon Sep 17 00:00:00 2001 From: ouyangxq <775153912@qq.com> Date: Mon, 10 Aug 2026 11:29:00 +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 | 12 +++- 三期/三期开发规划.md | 72 ++++++++++++------------ 三期/三期开发进度表.md | 82 ++++++++++++++-------------- 三期/三期需求确认表.md | 45 ++++++++------- 三期/三期验收任务拆分与待确认清单.md | 37 +++++++++++++ 5 files changed, 151 insertions(+), 97 deletions(-) create mode 100644 三期/三期验收任务拆分与待确认清单.md diff --git a/三期/README.md b/三期/README.md index 5581131..ed38d88 100644 --- a/三期/README.md +++ b/三期/README.md @@ -18,17 +18,23 @@ - [虫虫出海三期开发进度表（Excel）](虫虫出海三期开发进度表.xlsx)：可筛选、可下拉维护并使用公式汇总的项目进度工作簿。 - [三期需求确认表](三期需求确认表.md)：集中跟踪 P3-Q1～P3-Q13、负责人和最终结论。 - [三期页面与原型清单](三期页面与原型清单.md)：按管理后台、企业客户端和 PDA 维护页面范围及原型状态。 +- [三期验收任务拆分与待确认清单](三期验收任务拆分与待确认清单.md)：真实 HTTP/真机验收覆盖、coverageGap 解除条件和并行任务入口。 - `参考资料/出仓流程.png`：本期 9 个核心动作及业务终点的原始参考图。 ## 当前状态 -三期已有排柜/预装/PDA 拣货/装柜清单子链路，订舱和拖车子模块 API 也已实现并完成独立环境验证；但 2026-08-08 闭环审计结论仍为 `NO-GO`。已确认不新建出仓单，现有订单列表承载待分柜、装柜中和装柜完成等国内三期主状态。当前缺少订单三期统一编排、五类装柜照片多图追加/作废与真实门禁、报关协同、冲正、Client 三期协同及 PDA 真实身份/真机验收，暂不具备整期验收条件。现有平台手工“确认派送完成”接口与已确认边界不一致，应改为海外仓可信回传或从国内三期入口移除。 +三期已从“等待产品确认”转入分模块开发规划。已确认不新建独立出仓单，现有订单列表/详情承载主状态；支持一单多柜、一个柜拼多个订单，并采用“父订单→子订单→柜次”关系，已装载数量形成子订单，未装载数量自动生成后续子订单。进入 `LOADED`/装柜完成前，订舱完成、拖车完成、报关放行回执、PDA 拣货完成及五类证据完整均为服务端硬门禁；`LOADED` 后错误统一线下人工处理，国内 Admin/PDA 不提供在线冲正或手工推进 `DELIVERED`。 -### PDA 当前确认口径（2026-08-09） +船期首版按船公司官网查询，每 3 天一次、最多 3 次，记录来源、查询/更新时间和过期标识。首批来源为美森、SML、ZIM、COSCO、EMC、合德；外部页面不可用时保留最近结果并标记过期。报关首版不做系统对接，全部由人工整理、线下提交和人工上传回执。仓库初始化角色包括操作员、拣货员、理货员，具体权限矩阵由 IAM 契约任务落表。 + +当前仅 P3-Q4 的设备型号/Android/打包真机口径、P3-Q5 的实时库存与库位数据源仍需技术澄清；这些问题只阻断对应实现，不影响已确认模块进入契约设计和并行开发。 + +### PDA 当前确认口径（2026-08-10） - Android 扫描广播方式已接入；具体设备型号、系统版本、打包发布和真机验收仍待确认。 - 正式作业仅支持在线：进入任务即标记“拣货中”，扫描保存在绑定作业员+任务+柜次的设备持久化草稿，点击提交时批量写后端。 - 允许部分拣货或跳拣，但每个未完成项必须填写异常原因；存在未解决异常时不能完成或进入 `LOADED`。 - 重复提交返回原结果，版本冲突提示员工刷新重试。 - PDA 只能现场拍照，Admin 可人工上传；五类证据各至少 1 张有效照片，可同类型多张追加，错图只作废不硬删除。 -- 一柜多人并行、退出/换班释放、最终 `LOADED` 触发人、Admin 上传角色、照片可见范围和留存期限仍待产品确认。 +- 单柜次只允许一名作业员作业，不做多人并行和任务接管；进入任务即标记“拣货中”，扫描草稿按作业员+任务+柜次隔离，点击提交时批量写入后端。 +- 后台操作员、拣货员、理货员可按权限人工上传证据；照片无限期保留，客户不可见照片和锁码。 diff --git a/三期/三期开发规划.md b/三期/三期开发规划.md index 05f9bf3..167afdc 100644 --- a/三期/三期开发规划.md +++ b/三期/三期开发规划.md @@ -1,11 +1,11 @@ # 虫虫出海三期开发规划：国内出仓 > 创建日期：2026-07-28 -> 状态：范围规划中 +> 状态：已进入分模块开发规划 > 流程依据：[出仓流程](参考资料/出仓流程.png)中的头程物流“03 出仓”；用户已于 2026-08-08 确认国内三期以 `LOADED`/装柜完成为阶段终点 > 前置阶段：[一期文档](../一期/README.md) · [二期文档](../二期/README.md) -> 2026-08-09 已确认调整：三期不新建独立出仓单，现有订单列表承载全部主状态，柜次、订舱、拖车、拣货、证据和报关作为订单关联子对象。空仓、半仓、满仓、锁仓、带锁码照五类证据各至少 1 张有效照片，可同类型多张追加；带锁码照必须同时保存锁码文本。PDA 只能现场拍照，Admin 可人工上传，错图只作废不硬删除。 +> 2026-08-10 产品确认版：三期不新建独立出仓单；支持一单多柜、一个柜拼多个订单，采用“父订单→子订单→柜次”关系，已装载数量形成子订单，未装载数量自动生成后续子订单。`LOADED` 硬门禁为订舱完成、拖车完成、报关放行回执、PDA 拣货完成和五类证据完整；`LOADED` 后错误线下人工处理。五类证据各至少 1 张有效照片，同类型多张追加，PDA 仅现场拍照，后台操作员和理货员可人工上传，照片无限期保留且客户不可见。 > 主体模型与硬约束：三期只实现“平台—客户”两级，业务 `tenant_id > 0` / `tenantId` 当前表示客户 ID；`tenant_id=0` 是平台身份、平台 RBAC 和平台公共仓储资源技术作用域，客户往来单位、订单、文件和费用归属客户 `tenant_id>0`。禁止新增租户主表、租户选择器、客户所属租户配置、租户切换、租户级 RBAC 或租户级配置，禁止把现有 `tenant_id` 改义为上级租户 ID；历史类名、路径和字段继续兼容。 @@ -73,15 +73,18 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 | 平台运营 | 授权客户、订单和柜次 | 确认排柜、订舱、维护港务/船期信息和协调异常 | | 仓库主管 | 被授权的平台收货仓 | 分配拣货任务、复核差异、确认装柜和出仓条件 | | 仓库作业员 | 分配给本人或本仓的任务 | PDA 扫码、数量确认、异常上报和任务提交 | +| 操作员 | 授权仓库/订单/柜次 | 查看作业进度、人工上传装柜证据、协助处理异常 | +| 拣货员 | 分配给本人的单柜次任务 | PDA 扫码、数量确认、异常上报和批量提交；不开放后台人工证据上传 | +| 理货员 | 授权仓库/柜次 | 人工上传/补充/作废装柜证据、核对柜号和锁码、记录异常 | | 拖车调度员 | 授权订单/柜次与车辆范围 | 预约车辆、维护司机/车牌、到仓和离仓节点 | | 报关专员 | 授权客户、订单和报关批次 | 审核、退回、整理、提交资料并上传回执 | -| 平台管理员 | 平台授权范围 | 维护权限、规则、服务商和高风险冲正 | +| 平台管理员 | 平台授权范围 | 维护权限、规则和服务商；`LOADED` 后问题按线下流程处理，不提供在线冲正 | 服务端必须依据登录身份确定企业、仓库、客户和数据范围。前端传入的订单 ID、柜次 ID、仓库 ID、客户 ID、作业员 ID 或报关批次 ID 不能单独作为授权依据。 ## 四、流程与状态设计 -原型以 1 至 9 编号表达动作顺序，但尚未说明哪些是强制前置、哪些允许并行。当前按原型顺序规划业务节点，同时使用主状态和子流程状态保留后续调整空间；在 P3-Q11 确认前，不把并行关系写成固定业务规则。 +原型以 1 至 9 编号表达动作顺序。产品确认后，订舱、拖车、报关放行、PDA 拣货和证据完整是进入 `LOADED` 的强制前置；智能排柜、订舱、拖车和资料整理可按子流程并行，但服务端不得绕过门禁。PDA 单柜次单作业员，不实现多人并行或任务接管。 ### 1. 现有订单的三期主状态 @@ -89,7 +92,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 |---|---|---| | `WAIT_SPLIT` | 待分柜 | 二期已完成，等待排柜/预装 | | `LOADING` | 装柜中 | 预装已确认，PDA 执行拣货和装柜证据上传 | -| `LOADED` | 装柜完成 | 拣货已完成，五类证据各至少 1 张有效照片和锁码文本已通过服务端门禁 | +| `LOADED` | 装柜完成 | 订舱、拖车、报关放行回执、PDA 拣货完成，且五类证据各至少 1 张有效照片和锁码文本已通过服务端门禁 | | `DELIVERED` | 派送完成 | 货物到达海外仓后由海外仓可信回传推进；属于三期之后的只读状态 | ### 2. 子流程状态 @@ -97,7 +100,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 - 订舱：待订舱、订舱中、已订舱、订舱失败、已取消。 - 拖车：待预约、已预约、车辆已到仓、装柜中、已离仓、改约、已取消。 - 拣货：待分配、待拣货、拣货中、待复核、已完成、异常挂起、已取消。 -- 报关：资料待上传、资料待审核、待补件、待提交、已提交代理、回执待上传、回执已上传、已退回、已取消。海关放行如需管理，作为待确认的回执类型或后续状态，不默认作为三期装柜完成门禁。 +- 报关：资料待上传、资料待审核、待补件、待提交、已提交代理、回执待上传、回执已上传、已退回、已取消；有效放行回执是 `LOADED` 硬门禁，首版由授权人员人工上传。 - 港务/船期：待维护、已确认、信息变更、已开船；“已开船”属于三期之后的运输阶段，不是当前三期完成条件。 主状态由服务端根据已确认的必要子流程推进。客户端不得通过传任意目标状态跳过拣货复核、装柜证据或已配置的装柜完成门禁。 @@ -107,27 +110,26 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 ### 1. 现有订单与柜次 - 不创建独立出仓单，现有订单从 `WAIT_SPLIT` 继续推进三期状态。 -- 通过订单-柜次关系表达一张订单分多柜、多张订单拼柜和拆批，具体开放范围由 P3-Q2 确认。 +- 通过“父订单→子订单→柜次”表达一张订单分多柜、多张订单拼柜和拆批；已装载数量形成子订单，未装载数量自动生成后续子订单，子订单必须保留来源订单和数量分摊快照。 - 订单保持用户当前看到的主状态；柜次承载多订单共享的订舱、拖车、装柜证据和船期信息。 - 订单详情展示关联柜次、子流程状态、异常和整体时间线。 - 所有主状态推进使用服务端门禁、幂等键和版本字段防止绕过与并发覆盖。 ### 2. 智能排柜 -- 原型仅明确“智能排柜”，具体硬约束、软偏好、输入数据和输出结果以 P3-Q1 的业务规则表为准。 -- 柜型容量、重量、体积、箱数、同票/混票、不可混装、装载顺序和利用率暂列为候选能力，不作为未经确认的固定验收项。 +- 原型仅明确“智能排柜”；已确认装载率上限为 110%，税率高排前仅作为可配置排序规则。柜型容量、重量、体积、箱数、同票/混票、不可混装和装载顺序由规则表配置并保留版本。 - 当前建议首版采用“系统建议、人工确认”；是否允许调整、是否强制填写原因由排柜规则确认。 - 建议排柜方案保留版本、规则版本、输入快照、操作者和前后差异，以支持追溯。 - 未确认方案不得生成正式拣货任务或执行不可逆状态变化。 ### 3. 订舱与港务/船期信息 -- 原型明确需要查询预计开船、到港等港务信息；“港务信息”的准确业务含义、字段范围和归属以 P3-Q9 为准。 +- 原型明确需要查询预计开船、到港等船期信息；首版按船公司官网查询，每 3 天一次、最多 3 次，并记录来源、查询时间、更新时间和过期标识。 - 船公司/订舱代理、航线、订舱号、船名航次、起运港、目的港、截单、截关、截港、ETD 和 ETA 暂列为候选字段。 - 订舱失败、改船、甩柜、船期延误和取消暂列为候选异常场景，按业务确认结果实现。 -- 港务信息查询与人工维护分开设计：三期至少支持查询系统内已维护的信息，并记录查询条件、数据来源和更新时间；如后续确认可靠外部数据源，再通过预留适配边界接入，不在三期默认承诺正式接口。 +- 首批船公司来源配置：美森 `https://www.matson.com/shipment-tracking.html`、SML `https://esvc.smlines.com/smline/CUP_HOM_3301.do?sessLocale=zh`、ZIM `https://www.zimchina.com/tools/track-a-shipment`、COSCO `https://elines.coscoshipping.com/ebusiness/`、EMC `https://www.evergreen-shipping.cn/servlet/TDB1_CargoTracking.do`、合德 `http://elines.hedehk.com/cargoDynamic`。外部查询失败不得覆盖最近有效结果，连续达到 3 次仍失败时标记信息过期。 - 客户查看预计开船、到港等信息时展示数据来源和最近更新时间，避免把过期结果显示为实时信息。 -- 当前建议首版由平台人工维护，外部港务或船期接口只预留适配边界。 +- 港务/船期查询作为独立适配层实现；平台可人工维护修正，并保留来源和变更审计，不承诺船公司正式 API 对接。 - 建议关键信息变更保留旧值、新值、原因，并向授权用户发送站内提醒。 ### 4. 预约拖车 @@ -146,7 +148,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 - 扫描只更新绑定作业员、任务和柜次的设备持久化草稿；员工点击提交时才将全部明细批量写入后端，成功或明确放弃后清理，其他账号不得继承。 - 服务端校验任务归属、状态、重复扫码、超量、错货和批量提交；重复提交返回原结果，版本冲突提示刷新后重试。 - 允许部分拣货和跳拣，但每个未完成项必须填写异常原因；存在未解决差异时任务挂起，不能完成或进入 `LOADED`。 -- 一柜多人并行、退出/换班释放规则、最终完成触发人和是否需要后台复核仍待确认。 +- 单柜次只允许一名作业员；不实现多人并行、退出接管或换班释放。进入任务即标记拣货中，点击确认完成后由服务端批量落库并参与统一门禁，无需后台二次审核。 - 扫描器、声音、震动、网络和缓存通过设备适配层实现，不直接绑定单一厂商 SDK。 ### 6. 装柜及柜封证据 @@ -155,7 +157,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 - 空仓、半仓、满仓、锁仓、带锁码照五类证据各至少上传 1 张有效照片，可同类型多张追加；带锁码照同时要求锁码文本。 - PDA 只能现场拍照；Admin 可通过独立受权入口人工上传。上传前展示柜次、柜号、铅封号和照片类型，防止证据关联错误。 - 每张照片作为独立记录，支持上传进度、失败重试和提交前预览；错误或重复照片不硬删除，标记作废并记录原因、操作人和时间。 -- 照片记录文件哈希、上传人、上传时间、关联柜次、有效/作废状态和客户可见范围；Admin 上传角色、可见范围和留存期限仍待确认。 +- 照片记录文件哈希、上传人、上传时间、关联柜次、有效/作废状态和作废审计；照片无限期保留，客户不可见照片和锁码。后台操作员和理货员按权限人工上传，拣货员仅通过 PDA 现场拍照。 - 锁码重复、已确认的必传照片缺失或复核未通过时禁止确认装柜完成。 - 修改柜号或铅封号需要二次确认、原因和完整审计。 @@ -169,7 +171,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 ### 8. 报关回执与客户下载 -- 上传代理回传的报关回执并关联提交批次；回执类型可区分接收、申报、退单、查验或放行等，实际类型及装柜完成门禁以 P3-Q12 为准。 +- 授权人员人工上传代理回传的报关回执并关联提交批次；有效放行回执是装柜完成硬门禁，回执类型、版本和操作者可追溯。 - 替换文件产生新版本，不覆盖原记录；退单或补件形成明确任务。 - 客户只能下载本企业且标记为客户可见的回执。 - 文件下载使用授权地址并记录审计，不暴露内部存储路径。 @@ -179,7 +181,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 - 服务端校验排柜已确认、PDA 拣货已完成、五类证据各至少 1 张有效且未作废的图片已取得真实 `fileId`、锁码文本已保存。 - 门禁通过后仅将订单推进为 `LOADED`/装柜完成，记录柜次、柜号、锁码、操作人、时间和证据版本。 - 该操作必须幂等、乐观锁、完整审计和失败回复，禁止从前端跳过门禁。 -- 装柜完成后发现错误不得直接回退数据库状态，必须使用授权冲正动作和反向审计事件。 +- 装柜完成后发现错误统一线下人工处理；本期不提供在线冲正/回退接口，系统保留原状态、证据和审计记录。 - `DELIVERED`/派送完成只接受海外仓可信回传，必须有来源身份、签名/防重放、幂等键、请求摘要和审计；国内 Admin/PDA 不提供手工“确认派送完成”操作。 ## 六、核心数据对象 @@ -254,8 +256,8 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 | 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 | -| P3-PORT-01 | 后台/服务端 | 港务信息查询 | 查询系统内预计开船、到港等信息，记录来源和更新时间，并提供授权人工维护兜底 | P0 | P3-BOOK-01、P3-Q9 | +| P3-BOOK-01 | 后台 | 订舱 | 订舱和经确认的船名航次、港口、变更及异常；订舱完成是 `LOADED` 门禁 | P0 | P3-DSP-01 | +| P3-PORT-01 | 后台/服务端 | 船期查询 | 按美森、SML、ZIM、COSCO、EMC、合德官网查询，每 3 天一次最多 3 次，记录来源/更新时间/过期标识并支持人工修正 | P0 | P3-BOOK-01 | | P3-TRUCK-01 | 后台 | 拖车预约 | 服务商、车辆司机、时间窗、到离仓和异常 | P0 | P3-DSP-01 | | P3-PICK-01 | 公共 | 拣货任务 | 按排柜方案生成任务、明细、差异和复核规则 | P0 | P3-PLAN-02 | | P3-PDA-01 | PDA | 在线扫码拣货 | 进入任务标记拣货中、扫描草稿、部分/跳拣异常原因和批量提交 | P0 | P3-PICK-01 | @@ -263,9 +265,9 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 | P3-LOAD-01 | 后台 | 装柜封柜 | 柜号、锁码文本、装柜节点、五类多图证据和门禁复核 | P0 | P3-PICK-01 | | P3-LOAD-02 | PDA/Admin/服务端 | 柜封拍照上传 | PDA 现场拍摄、Admin 人工上传、五类证据多图追加、真实文件上传、预览、失败重试、作废和提交 | P0 | P3-LOAD-01、文件能力可用 | | P3-CUS-01 | 客户端 | 报关资料 | 清单、上传、补件、版本和进度查看 | P0 | 文件能力可用 | -| P3-CLEAR-01 | 后台 | 报关协同 | 审核、退回、提交代理、批次、回执和可见范围 | P0 | P3-CUS-01 | +| P3-CLEAR-01 | 后台 | 报关协同 | 人工审核、补件、线下提交代理、人工上传放行回执和版本审计 | P0 | P3-CUS-01 | | P3-CUS-02 | 客户端 | 回执及港务信息 | 回执下载、预计开船/到港信息、数据来源、更新时间和变更时间线 | P0 | P3-PORT-01、P3-CLEAR-01 | -| P3-GATE-01 | 服务端 | 装柜完成门禁 | 校验 PDA 拣货、五类证据各至少 1 张有效照片和锁码文本，幂等推进 `LOADED` 并支持授权冲正 | P0 | P3-PICK-01、P3-LOAD-01、P3-LOAD-02、P3-Q10 | +| P3-GATE-01 | 服务端 | 装柜完成门禁 | 校验订舱、拖车、报关放行回执、PDA 拣货、五类证据和锁码文本，幂等推进 `LOADED`；`LOADED` 后仅线下人工处理 | P0 | P3-PICK-01、P3-LOAD-01、P3-LOAD-02 | | P3-OVERSEAS-01 | 服务端 | 海外仓派送完成回传 | 只接受海外仓可信回传，校验身份、签名、时间窗、防重放和幂等，推进 `DELIVERED` | P1/后续阶段 | 海外仓契约 | | P3-NOTIFY-01 | 公共 | 通知异常 | 站内通知、阻塞、责任人、时限和失败补偿 | P1 | 核心流程完成 | | P3-TEST-01 | 公共 | 自动化测试 | 权限、排柜、幂等、并发、文件、门禁和状态测试 | P0 | 所有 P0 模块 | @@ -287,29 +289,31 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 - 管理后台覆盖加载、空态、失败、无权限和数据冲突；PDA 覆盖弱网、前后台切换和硬件扫描。 - 三期验收基线为 `LOADED`/装柜完成；`DELIVERED`/派送完成只由海外仓回传推进，不属于国内三期验收条件。 -## 十一、启动前待确认事项 +## 十一、启动前技术澄清事项 + +验收任务拆分、真实 HTTP 覆盖和未确认项解除条件统一见[三期验收任务拆分与待确认清单](三期验收任务拆分与待确认清单.md)。当前已确认的 PDA/证据规则已进入 `phase3-container-loading.mjs`、`phase3-loading.mjs`；未确认规则不得标记为三期完成。 | 编号 | 待确认问题 | 当前建议 | |---|---|---| -| P3-Q1 | 智能排柜需考虑哪些硬约束和软偏好？ | 业务先提供可执行规则表；建议必须可解释且人工确认 | -| P3-Q2 | 是否存在拼柜、一单多柜和拆批出仓？ | 数据模型全部支持，页面按实际高频场景逐步开放 | -| P3-Q3 | “预约托车”是否统一为“预约拖车”？ | 建议统一使用行业常用的“拖车”，并确认业务实际含义 | +| P3-Q1 | 智能排柜需考虑哪些硬约束和软偏好？ | 已确认：装载率上限 110%；税率高排前做可配置排序，规则版本化 | +| P3-Q2 | 是否存在拼柜、一单多柜和拆批出仓？ | 已确认：父订单→子订单→柜次；已装载/未装载数量自动形成子订单 | +| P3-Q3 | “预约托车”是否统一为“预约拖车”？ | 已确认统一使用“预约拖车” | | P3-Q4 | 目标 PDA 型号、系统和扫描头接入方式是什么？ | 广播接入已确认并完成；设备型号、Android 版本、打包发布和真机验收仍待确认 | -| P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 若需要，完整 WMS 前置范围会显著扩大，必须单独评估 | -| P3-Q6 | 柜封照片有哪些必传角度和留存期限？ | 已确认五类各至少 1 张、可多张追加、PDA 仅拍照、Admin 可上传、错图作废；Admin 角色、可见范围和留存期限尚待确认 | -| P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 建议配置化，并保留下单使用的清单版本 | -| P3-Q8 | 报关代理如何接收资料和返回回执？ | 首版系统内整理加线下提交，正式接口后续评估 | -| P3-Q9 | 原型中的“港务信息”具体指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 先确认业务词义和字段；首版建议平台人工维护并审计，外部接口仅预留适配层 | -| P3-Q10 | 进入装柜完成后发现错误如何处理？ | 不直接回退状态，使用授权冲正动作和反向审计事件 | -| P3-Q11 | 九个动作中哪些是强制前置，哪些允许并行？ | PDA 进入任务、批量提交和异常阻断已确认；多人协作、最终完成触发和跨模块门禁仍待确认 | -| P3-Q12 | “报关回执”具体包含哪些类型，海关放行是否为国内出仓硬门禁？ | 当前不默认以放行为门禁；由业务明确接收、申报、退单、查验和放行的含义及门禁 | +| P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 已确认依赖二期库存/库位可用量接口；不扩展完整 WMS | +| P3-Q6 | 柜封照片有哪些必传角度和留存期限？ | 已确认：五类各至少 1 张、同类型可多张追加、后台操作员/理货员可上传、错图作废、无限期保留、客户不可见 | +| P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 已确认首版人工维护清单和版本，不接自动报关 | +| P3-Q8 | 报关代理如何接收资料和返回回执？ | 已确认线下提交，授权人员人工上传回执 | +| P3-Q9 | 原型中的“港务信息”具体指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 已确认首版查询六家船公司官网，每 3 天一次最多 3 次，记录来源/更新时间/过期标识 | +| P3-Q10 | 进入装柜完成后发现错误如何处理？ | 已确认线下人工处理，本期不提供在线冲正 | +| P3-Q11 | 九个动作中哪些是强制前置，哪些允许并行？ | 已确认订舱、拖车、报关放行、PDA 拣货和五类证据为 `LOADED` 硬门禁；单柜次单作业员 | +| P3-Q12 | “报关回执”具体包含哪些类型，海关放行是否为国内出仓硬门禁？ | 已确认有效放行回执为 `LOADED` 硬门禁，首版人工上传 | | P3-Q13 | 三期终点以什么状态为准？ | 已确认为 `LOADED`/装柜完成；`DELIVERED`/派送完成由海外仓回传，不属于国内三期 | ## 十二、建议实施顺序 -1. 锁定待确认事项、业务规则、目标设备和协作责任人。 +1. 固化已确认业务规则，仅对目标设备和实时库存/库位数据源做技术澄清。 2. 统一订单、柜次、订舱、拖车、拣货、报关和港务/船期信息的稳定编码与关联契约。 3. 先实现服务端权限、状态、门禁、幂等、并发和审计，再接各端页面。 4. 完成管理后台的出仓编排，再接 PDA 现场执行和客户资料协同。 -5. 使用脱敏数据演练拼柜、一单多柜、错拣、补件、改船和冲正。 +5. 使用脱敏数据演练拼柜、一单多柜、未装数量生成子订单、错拣、补件和改船；`LOADED` 后不演练在线冲正。 6. 在真实 PDA 和代表性仓库网络环境中完成联调、验收和灰度发布。 diff --git a/三期/三期开发进度表.md b/三期/三期开发进度表.md index 54cecd2..c3c5387 100644 --- a/三期/三期开发进度表.md +++ b/三期/三期开发进度表.md @@ -1,8 +1,8 @@ # 虫虫出海三期开发进度表 > 创建日期：2026-07-28 -> 当前阶段：范围规划与大任务拆分 -> 总体状态：待确认 +> 当前阶段：已确认口径下的分模块开发与契约拆分 +> 总体状态：已进入开发准备 > 规划依据：`三期开发规划.md` > 维护方式：参考一期进度表，采用“总体大任务 → 详细任务 → 里程碑 → 未确认事项 → 开工准入 → 验收”的结构。 @@ -16,16 +16,16 @@ | 大任务 ID | 大任务 | 范围 | 状态 | 进度 | 计划开始 | 计划完成 | 负责人 | 关键依赖/备注 | |---|---|---|---|---:|---|---|---|---| -| T01 | 需求确认与原型 | 锁定阶段边界、流程依赖、排柜规则、设备、文件、报关和港务信息；完成页面原型 | 进行中 | 40% | 2026-07-28 | 待排期 | 待分配 | 已盘点 `docs/悦` 三期相关原型；后台有较完整参考，客户端三期页面和 PDA 柜封拍照仍待补 | -| T02 | 公共契约与数据模型 | 主/子状态、权限、事件、错误码、订单三期投影、柜次、任务、证据、报关和审计模型 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T01、二期输出契约 | -| T03 | 订单三期编排与柜次 | 增强现有订单列表/详情，建立订单-柜次关系、拆分/拼柜和时间线 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T02、P3-Q2、P3-Q11；不新建出仓单 | -| T04 | 智能排柜 | 排柜规则、系统建议、冲突、人工确认和追溯 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T03、P3-Q1、P3-Q2 | -| T05 | 订舱与港务信息 | 订舱、变更异常、预计开船/到港信息、来源和更新时间 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T03、P3-Q9、P3-Q11 | -| T06 | 拖车预约 | 服务商、车辆司机、预约时间窗、到离仓节点和异常 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T03、一期往来单位、P3-Q3 | -| T07 | PDA 拣货与复核 | 在线进入任务、持久化扫描草稿、批量提交、部分拣货、异常、幂等和后台复核 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 在线、草稿、批量提交和异常阻断已确认；依赖 T04、二期处理单元/位置、P3-Q4、P3-Q5，多人协作待确认 | -| T08 | 装柜及柜封证据 | 装柜节点、柜号、铅封号、PDA 现场拍照、Admin 上传、多图追加、作废和复核 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 五类证据规则已确认；Admin 角色、可见范围和留存依赖后续确认 | -| T09 | 报关资料与回执 | 客户上传、后台审核补件、提交代理、回执上传和客户下载 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖文件能力、P3-Q7、P3-Q8、P3-Q12 | -| T10 | 装柜完成门禁 | 校验 PDA 拣货、五类证据各至少 1 张有效照片和锁码文本，推进 `LOADED`，并提供阻塞、冲正和审计 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 最低门禁已确认；其他前置依赖 P3-Q11/P3-Q12 | +| T01 | 需求确认与原型 | 锁定阶段边界、流程依赖、排柜规则、设备、文件、报关和港务信息；完成页面原型 | 已完成 | 100% | 2026-07-28 | 2026-08-10 | 总控 | 产品确认版已同步；仅保留设备与实时库存的技术澄清 | +| T02 | 公共契约与数据模型 | 主/子状态、权限、事件、错误码、订单三期投影、柜次、任务、证据、报关和审计模型 | 进行中 | 10% | 2026-08-10 | 待排期 | 待分配 | 已确认父子订单、硬门禁和仓库角色；依赖二期输出契约 | +| T03 | 订单三期编排与柜次 | 增强现有订单列表/详情，建立父子订单-柜次关系、拆分/拼柜和时间线 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 不新建出仓单；一单多柜、拼柜和未装数量自动生成子订单 | +| T04 | 智能排柜 | 排柜规则、系统建议、冲突、人工确认和追溯 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 装载率上限 110%；税率排序可配置 | +| T05 | 订舱与港务信息 | 订舱、变更异常、船公司官网查询、更新时间和过期标识 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 订舱完成属于 `LOADED` 门禁；船期每 3 天最多查询 3 次 | +| T06 | 拖车预约 | 服务商、车辆司机、预约时间窗、到离仓节点和异常 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 拖车完成属于 `LOADED` 门禁 | +| T07 | PDA 拣货与复核 | 在线进入任务、持久化扫描草稿、批量提交、部分拣货、异常、幂等和单人作业 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 单柜次单作业员；设备型号/实时库存仍需技术澄清 | +| T08 | 装柜及柜封证据 | 装柜节点、柜号、铅封号、PDA 现场拍照、后台角色上传、多图追加、作废和复核 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 操作员/拣货员/理货员可上传；无限期保留、客户不可见 | +| T09 | 报关资料与回执 | 人工资料清单、后台审核补件、线下提交代理、人工上传放行回执 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 放行回执属于 `LOADED` 门禁，不做自动接口 | +| T10 | 装柜完成门禁 | 校验订舱、拖车、报关放行、PDA 拣货、五类证据和锁码文本，推进 `LOADED` | 待开始 | 0% | 待排期 | 待排期 | 待分配 | `LOADED` 后错误线下处理，不提供在线冲正 | | T11 | 客户端三期协同 | 装柜进度、柜次、回执、预计开船/到港和变更时间线 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T05、T09、T10；客户可见范围 | | T12 | 联调测试与发布 | 跨端联调、自动化测试、PDA 真机、安全、弱网、迁移、验收和发布 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T02～T11 完成 | @@ -35,28 +35,28 @@ | ID | 大任务 | 端 | 模块 | 功能/交付内容 | 优先级 | 状态 | 进度 | 依赖 | 负责人 | 备注 | |---|---|---|---|---|---|---|---:|---|---|---| -| P3-T01-00 | T01 | 公共 | 需求确认与原型 | 完成需求确认表、页面清单和原型评审，锁定开工阻断项 | P0 | 进行中 | 40% | - | 待分配 | 已建立文档骨架并完成 `docs/悦` 原型初审，后续逐项确认和裁剪 | -| P3-T02-00 | T02 | 公共 | 公共契约与数据模型 | 待 T01 确认后拆分 | P0 | 待确认 | 0% | P3-T01-00 | 待分配 | 下一层将拆状态、权限、数据模型、接口和审计 | -| P3-T03-00 | T03 | 后台/服务端 | 订单三期编排与柜次 | 待 T02 契约明确后拆分 | P0 | 待确认 | 0% | P3-T02-00 | 待分配 | 复用现有订单，不创建独立出仓单 | -| P3-T04-00 | T04 | 后台/服务端 | 智能排柜 | 待排柜规则确认后拆分 | P0 | 待确认 | 0% | P3-T03-00、P3-Q1 | 待分配 | - | -| P3-T05-00 | T05 | 后台/服务端 | 订舱与港务信息 | 待港务范围和字段确认后拆分 | P0 | 待确认 | 0% | P3-T03-00、P3-Q9 | 待分配 | - | -| P3-T06-00 | T06 | 后台/服务端 | 拖车预约 | 待流程依赖确认后拆分 | P0 | 待确认 | 0% | P3-T03-00、P3-Q11 | 待分配 | - | -| P3-T07-00 | T07 | PDA/后台/服务端 | PDA 拣货与复核 | 按已确认的在线草稿+批量提交规则拆分，补多人协作和最终复核结论 | P0 | 待确认 | 0% | P3-T04-00、P3-Q4、P3-Q5 | 待分配 | 广播模式已接入；持久化草稿和真实批量契约仍需核验 | -| P3-T08-00 | T08 | PDA/后台/服务端 | 装柜及柜封证据 | 实现五类多图追加、PDA 拍照、Admin 上传、作废和完整性门禁 | P0 | 待确认 | 0% | P3-T07-00、P3-Q6 | 待分配 | 当前代码仍需核对是否按追加而非替换实现 | -| P3-T09-00 | T09 | 客户端/后台/服务端 | 报关资料与回执 | 待资料和回执规则确认后拆分 | P0 | 待确认 | 0% | P3-Q7、P3-Q8、P3-Q12 | 待分配 | - | -| P3-T10-00 | T10 | 后台/服务端 | 装柜完成门禁 | 实现最低硬门禁、`LOADED` 推进、阻塞、冲正和审计 | P0 | 待确认 | 0% | P3-T07-00、P3-T08-00、P3-Q10、P3-Q11 | 待分配 | 国内端不得推进 `DELIVERED` | +| P3-T01-00 | T01 | 公共 | 需求确认与原型 | 完成需求确认表、页面清单和原型评审，锁定开工阻断项 | P0 | 已完成 | 100% | - | 总控 | 已同步产品确认版；只剩设备和实时库存技术澄清 | +| P3-T02-00 | T02 | 公共 | 公共契约与数据模型 | 拆状态、权限、数据模型、接口和审计；初始化操作员/拣货员/理货员角色 | P0 | 进行中 | 10% | P3-T01-00 | 待分配 | 统一固化父子订单、柜次、硬门禁和人工报关 | +| P3-T03-00 | T03 | 后台/服务端 | 订单三期编排与柜次 | 实现父订单→子订单→柜次、一单多柜、拼柜、未装数量自动子订单和时间线 | P0 | 待开始 | 0% | P3-T02-00 | 待分配 | 复用现有订单，不创建独立出仓单 | +| P3-T04-00 | T04 | 后台/服务端 | 智能排柜 | 实现 110% 装载率上限、可配置税率排序、人工确认和版本追溯 | P0 | 待开始 | 0% | P3-T03-00 | 待分配 | - | +| P3-T05-00 | T05 | 后台/服务端 | 订舱与港务信息 | 订舱状态及六家船公司查询、三日周期、三次上限、过期标识 | P0 | 待开始 | 0% | P3-T03-00 | 待分配 | - | +| P3-T06-00 | T06 | 后台/服务端 | 拖车预约 | 服务商、车辆司机、时间窗、到离仓和异常；完成状态供门禁校验 | P0 | 待开始 | 0% | P3-T03-00 | 待分配 | - | +| P3-T07-00 | T07 | PDA/后台/服务端 | PDA 拣货与复核 | 按单柜次单作业员实现在线草稿、批量提交、异常和幂等 | P0 | 待开始 | 0% | P3-T04-00 | 待分配 | 设备型号和实时库存数据源单独澄清 | +| P3-T08-00 | T08 | PDA/后台/服务端 | 装柜及柜封证据 | 实现五类多图追加、角色上传、作废和无限期留存，客户不可见 | P0 | 待开始 | 0% | P3-T07-00 | 待分配 | - | +| P3-T09-00 | T09 | 客户端/后台/服务端 | 报关资料与回执 | 实现人工清单、补件、线下提交记录、人工放行回执上传 | P0 | 待开始 | 0% | P3-T02-00 | 待分配 | - | +| P3-T10-00 | T10 | 后台/服务端 | 装柜完成门禁 | 实现订舱/拖车/放行/PDA/证据硬门禁并推进 `LOADED` | P0 | 待开始 | 0% | P3-T07-00、P3-T08-00、P3-T09-00 | 待分配 | `LOADED` 后只线下人工处理 | | P3-T11-00 | T11 | 客户端/服务端 | 客户端三期协同 | 待客户可见字段确认后拆分 | P0 | 待确认 | 0% | P3-T05-00、P3-T09-00、P3-T10-00 | 待分配 | - | | P3-T12-00 | T12 | 公共 | 联调测试与发布 | 待各模块拆分完成后细化测试与发布任务 | P0 | 待开始 | 0% | P3-T02-00～P3-T11-00 | 待分配 | - | | P3-T01-PROTO-01 | T01 | 公共 | 原型盘点 | 盘点流程图、后台、企业客户端和 PDA 中与三期相关的页面及交互 | P0 | 已完成 | 100% | - | 待分配 | 2026-07-28 已完成首次盘点，来源为 `docs/悦` | | P3-T03-PROTO-01 | T03 | 后台 | 订单三期编排原型 | 在现有订单列表/详情中设计柜次、子流程摘要、阻塞原因、时间线和操作入口 | P0 | 进行中 | 50% | P3-T01-PROTO-01、P3-Q11 | 待分配 | 不新建出仓单页面 | -| P3-T04-PROTO-01 | T04 | 后台 | 智能排柜原型核验 | 映射智能装柜的线路页签、筛选、智能锁定、订单分柜、拖放调整和集装箱详情 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 原型叫“智能装柜”，与“智能排柜”的业务边界待 P3-Q1 确认 | -| P3-T05-PROTO-01 | T05 | 后台 | 订舱港务原型核验 | 映射订舱列表、新增/详情、放舱、船名航次、港口和 ETD/ATD/ETA/ATA 字段 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 港务信息是否独立模块仍待 P3-Q9 确认 | +| P3-T04-PROTO-01 | T04 | 后台 | 智能排柜原型核验 | 映射智能装柜的线路页签、筛选、智能锁定、订单分柜、拖放调整和集装箱详情 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 按 110% 装载率上限和可配置税率排序实现 | +| P3-T05-PROTO-01 | T05 | 后台 | 订舱港务原型核验 | 映射订舱列表、新增/详情、放舱、船名航次、港口和 ETD/ATD/ETA/ATA 字段 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 船期查询按六家船公司来源配置，每 3 天最多 3 次 | | P3-T06-PROTO-01 | T06 | 后台 | 拖车原型核验 | 映射拖车列表、新增表单、运输公司、司机、车头号、装箱日期、费用和附件 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 预约时间窗和到离仓节点仍需按三期流程补充 | | P3-T07-PROTO-01 | T07 | 后台/PDA | 拣货原型核验 | 对照通用 WMS 出库拣货和现有 PDA 集装箱拣货，锁定可复用交互与真实接口缺口 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 已确认在线作业、进入即开始、持久化草稿和批量提交；真实任务、鉴权与契约仍需完成 | | P3-T08-PROTO-01 | T08 | 后台 | 装柜证据原型核验 | 映射货柜列表、预装清单、装柜清单、柜号、单证、船期和装柜明细 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 后台参考较完整，但现场拍照上传原型缺失 | | P3-T08-PROTO-02 | T08 | PDA | 装柜拍照原型 | 新增柜次确认、五类证据多图追加、锁码文本、预览、重试、作废和提交页面原型 | P0 | 待开始 | 0% | P3-Q4、P3-Q6 | 待分配 | PDA 仅拍照、Admin 可上传、每类至少一张和错图作废已确认 | | P3-T09-PROTO-01 | T09 | 后台 | 报关单证原型核验 | 映射报关单列表、单证管理、报关/清关/放行资料及装柜清单附件 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 客户上传和回执下载页面仍需新建 | -| P3-T10-PROTO-01 | T10 | 后台 | 装柜完成门禁原型 | 在现有订单详情设计门禁检查、阻塞原因、确认装柜完成和冲正交互 | P0 | 进行中 | 30% | P3-Q10～P3-Q12 | 待分配 | 不需要独立门禁页面，可作为订单详情操作区 | +| P3-T10-PROTO-01 | T10 | 后台 | 装柜完成门禁原型 | 在现有订单详情设计门禁检查、阻塞原因和确认装柜完成交互 | P0 | 进行中 | 30% | P3-Q10～P3-Q12 | 待分配 | 不提供在线冲正，不需要独立门禁页面 | | P3-T11-PROTO-01 | T11 | 客户端 | 客户端三期原型 | 新增装柜进度、报关资料上传/补件、回执下载和港务/船期页面原型 | P0 | 待开始 | 0% | P3-Q7～P3-Q9、P3-Q12 | 待分配 | 现有客户端原型未覆盖三期专用页面 | ## 四、原型对照与开发影响 @@ -92,32 +92,34 @@ | 里程碑 | 交付目标 | 状态 | 计划完成 | |---|---|---|---| -| P3-M0 需求与原型锁定 | 阶段边界、流程、规则、设备、文件和页面原型确认 | 待确认 | 待排期 | +| P3-M0 需求与原型锁定 | 阶段边界、流程、规则、设备、文件和页面原型确认 | 已完成 | 2026-08-10 | | P3-M1 公共契约 | 二三期输入、状态、权限、数据模型和接口契约稳定 | 待排期 | 待排期 | | P3-M2 订单三期编排 | 现有订单、柜次、排柜、订舱、港务和拖车可关联追溯 | 待排期 | 待排期 | | P3-M3 仓内出仓 | PDA 拣货、复核、装柜和柜封证据闭环 | 待排期 | 待排期 | | P3-M4 报关协同 | 客户资料、后台审核、提交代理、回执上传下载闭环 | 待排期 | 待排期 | -| P3-M5 装柜完成 | 最低门禁满足后进入 `LOADED`，支持阻塞提示和授权冲正 | 待排期 | 待排期 | +| P3-M5 装柜完成 | 订舱、拖车、放行回执、PDA 和证据门禁满足后进入 `LOADED`；后续错误线下处理 | 待排期 | 待排期 | | P3-M6 三期上线 | 联调、真机、安全、测试、验收和生产发布完成 | 待排期 | 待排期 | ## 七、未确认事项（需求确认进度） -当前共 13 项主确认事项：P3-Q13 已确认；P3-Q4、P3-Q6、P3-Q11 已取得可直接开发的 PDA 子结论但主项仍在确认中；其余事项待确认。完整结论统一维护在 [三期需求确认表](三期需求确认表.md)，不得因为主项仍有残留问题而忽略其中已经确认的规则。 +当前 13 项主确认事项中，P3-Q1～P3-Q3、P3-Q6～P3-Q13 已有产品最终结论；P3-Q4 仅剩设备/真机技术澄清，P3-Q5 仅剩实时库存与库位数据源技术澄清。完整结论统一维护在 [三期需求确认表](三期需求确认表.md)。 + +验收拆分已建立：PDA 进入任务、拣货幂等/版本冲突、五类证据真实上传、多图追加和锁码门禁进入自动化；真机在线、设备草稿批量提交、证据作废、设备与权限留存等仍保留 coverageGap，详见[三期验收任务拆分与待确认清单](三期验收任务拆分与待确认清单.md)。 | 编号 | 阻断级别 | 待确认事项 | 状态 | 主要影响 | |---|---|---|---|---| -| P3-Q1 | 开工阻断 | 智能排柜的硬约束和软偏好 | 待确认 | T04 智能排柜、T07 拣货任务 | -| P3-Q2 | 开工阻断 | 是否支持拼柜、一单多柜和拆批装柜 | 待确认 | T03 订单三期编排与柜次、T04 智能排柜 | -| P3-Q3 | 非阻断 | “预约托车”是否统一为“预约拖车” | 待确认 | T06 拖车预约、页面与接口文案 | +| P3-Q1 | 开工阻断 | 智能排柜的硬约束和软偏好 | 已确认 | T04 智能排柜、T07 拣货任务 | +| P3-Q2 | 开工阻断 | 是否支持拼柜、一单多柜和拆批装柜 | 已确认 | T03 订单三期编排与柜次、T04 智能排柜 | +| P3-Q3 | 非阻断 | “预约托车”是否统一为“预约拖车” | 已确认 | T06 拖车预约、页面与接口文案 | | P3-Q4 | 模块阻断 | PDA 型号、系统和扫描头接入方式 | 确认中 | 广播模式已接入；设备型号、Android 版本、发布和真机验收待确认 | | P3-Q5 | 开工阻断 | 拣货是否依赖实时库存和库位可用量 | 待确认 | T02 二三期契约、T07 PDA 拣货 | -| P3-Q6 | 模块阻断 | 装柜照片和锁码规则 | 确认中 | 五类最少一张、多图追加、PDA 拍照、Admin 上传和作废已确认；角色、可见范围、留存待确认 | -| P3-Q7 | 模块阻断 | 报关资料清单是否按国家、渠道和货物类型变化 | 待确认 | T09 报关资料、文件版本 | -| P3-Q8 | 模块阻断 | 报关代理接收资料和返回回执的方式 | 待确认 | T09 报关协同、回执上传 | -| P3-Q9 | 开工阻断 | 港务信息的业务含义、字段和维护方 | 待确认 | T05 订舱港务、T11 客户端展示 | -| P3-Q10 | 模块阻断 | 装柜完成后的错误处理和冲正方式 | 待确认 | T10 装柜完成门禁、权限和审计 | -| P3-Q11 | 开工阻断 | 九个动作的强制前置和并行关系 | 确认中 | PDA 进入任务、批量提交、异常阻断已确认；多人协作、最终触发和跨模块门禁待确认 | -| P3-Q12 | 开工阻断 | 报关回执类型及海关放行是否为装柜完成硬门禁 | 待确认 | T09 报关状态、T10 装柜完成门禁 | +| P3-Q6 | 模块阻断 | 装柜照片和锁码规则 | 已确认 | 五类多图、角色上传、无限期保留、客户不可见 | +| P3-Q7 | 模块阻断 | 报关资料清单是否按国家、渠道和货物类型变化 | 已确认 | T09 报关资料、文件版本 | +| P3-Q8 | 模块阻断 | 报关代理接收资料和返回回执的方式 | 已确认 | 线下提交、人工上传回执 | +| P3-Q9 | 开工阻断 | 港务信息的业务含义、字段和维护方 | 已确认 | 六家船公司查询、三日周期、三次上限、过期标识 | +| P3-Q10 | 模块阻断 | 装柜完成后的错误处理和冲正方式 | 已确认 | 线下人工处理，不提供在线冲正 | +| P3-Q11 | 开工阻断 | 九个动作的强制前置和并行关系 | 已确认 | 订舱/拖车/放行/PDA/证据为硬门禁；单柜次单人 | +| P3-Q12 | 开工阻断 | 报关回执类型及海关放行是否为装柜完成硬门禁 | 已确认 | 有效放行回执为硬门禁，人工上传 | | P3-Q13 | 开工阻断 | 三期终点 | 已确认 | `LOADED`/装柜完成；`DELIVERED` 由海外仓回传，移出三期验收 | ## 八、开工准入清单 @@ -126,8 +128,8 @@ | 准入编号 | 准入条件 | 当前状态 | 责任方 | 完成证据 | |---|---|---|---|---| -| P3-GO-01 | P3-Q1～P3-Q13 均形成明确结论，7 项开工阻断全部解除 | 进行中 | 产品、业务 | `三期需求确认表.md` 状态均为已确认并填写最终结论 | -| P3-GO-02 | 确认结论已同步开发规划、进度表、页面清单和验收范围 | 待开始 | 产品、项目负责人 | 四份文档口径一致，无未标注的候选规则 | +| P3-GO-01 | P3-Q1～P3-Q3、P3-Q6～P3-Q13 均形成产品结论；P3-Q4/P3-Q5 仅剩技术澄清 | 已完成 | 产品、业务 | `三期需求确认表.md` 已同步最终结论 | +| P3-GO-02 | 确认结论已同步开发规划、进度表、页面清单和验收范围 | 进行中 | 产品、项目负责人 | 本轮已同步四份文档，后续随契约实现更新 | | P3-GO-03 | 关键缺失原型已补齐并评审，包括订单装柜完成门禁、客户端三期页面和 PDA 五类多图拍照 | 进行中 | 产品、设计、业务 | 页面清单中的关键页面达到已确认状态 | | P3-GO-04 | T02 公共契约完成，二期输入、状态机、权限、数据模型、接口、错误码和审计口径稳定 | 待开始 | 前后端、架构/技术负责人 | 契约评审记录及稳定的数据/API 定义 | | P3-GO-05 | T03～T12 已拆成 RULE、DATA、API、ADM/CLI/PDA、TEST、ACCEPT 任务，并填写负责人和计划 | 待开始 | 项目负责人、研发、测试 | 详细任务可独立开发、联调和验收 | diff --git a/三期/三期需求确认表.md b/三期/三期需求确认表.md index 3e6ea9d..b068963 100644 --- a/三期/三期需求确认表.md +++ b/三期/三期需求确认表.md @@ -1,7 +1,7 @@ # 虫虫出海三期需求确认表 > 创建日期：2026-07-28 -> 当前状态：确认中 +> 当前状态：已进入开发规划（已确认结论按本表执行；技术实现项仍需契约评审） > 用途：记录会影响三期范围、流程、数据模型、页面和验收的产品决策。 ## 一、维护规则 @@ -15,18 +15,18 @@ | 编号 | 决策/问题 | 当前建议 | 阻断级别 | 状态 | 负责人 | 计划确认 | 最终结论 | 影响模块 | |---|---|---|---|---|---|---|---|---| -| P3-Q1 | 智能排柜需考虑哪些硬约束和软偏好？ | 业务提供可执行规则表，建议可解释并由人工确认 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 智能排柜、拣货任务 | -| P3-Q2 | 是否存在拼柜、一单多柜和拆批出仓？ | 通过订单-柜次关系预留能力，页面按高频场景逐步开放 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 订单、柜次、排柜、拣货 | -| P3-Q3 | 原型“预约托车”是否统一为“预约拖车”？ | 建议使用行业常用的“拖车”，同时确认业务实际含义 | 非阻断 | 待确认 | 待分配 | 待排期 | - | 页面文案、接口字段说明 | -| P3-Q4 | 目标 PDA 型号、系统和扫描头接入方式是什么？ | 保持设备适配层，不绑定厂商 SDK | 模块阻断 | 确认中 | 用户当前对话确认 | 2026-08-10 | Android 广播接入方式已确认并已接入：Action=`android.intent.action.SCANRESULT`、字符串 Extra=`value`；具体 PDA 型号、Android 版本、打包发布流程和目标设备真机验收仍待确认 | PDA 拣货、真机验收 | -| P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 默认使用二期处理单元和当前位置；如需完整库存，单独评估 WMS 范围 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 二三期契约、拣货、库存边界 | -| P3-Q6 | 柜封照片有哪些必传类型、数量、采集方式、处理规则和留存期限？ | 已确认规则直接进入契约；权限和留存继续确认 | 模块阻断 | 确认中 | 用户当前对话确认 | 2026-08-10 | 五类证据各至少 1 张有效照片，可同类型多张追加；PDA 只能现场拍照，Admin 可人工上传；错图不硬删除，按原因、操作人、时间作废；带锁码照还必须填写锁码文本。Admin 上传角色、客户可见范围和留存期限仍待确认 | 装柜、PDA 拍照、Admin 上传、文件存储、订单后程门禁 | -| P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 清单配置化，并保存业务使用的清单版本 | 模块阻断 | 待确认 | 待分配 | 待排期 | - | 客户资料、报关审核、文件版本 | -| P3-Q8 | 报关代理如何接收资料并返回回执？ | 首版系统内整理、线下提交，正式接口后续评估 | 模块阻断 | 待确认 | 待分配 | 待排期 | - | 报关协同、回执上传 | -| P3-Q9 | “港务信息”指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 先确认词义和字段；首版平台人工维护并审计 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 订舱、港务查询、客户展示 | -| P3-Q10 | 订单进入“装柜完成”后发现错误如何处理？ | 不直接回退状态，使用授权冲正和反向审计事件 | 模块阻断 | 待确认 | 待分配 | 待排期 | - | 装柜完成门禁、权限、审计 | -| P3-Q11 | 九个动作中哪些是强制前置，哪些允许并行？ | 已确认 PDA 子流程直接进入契约，其余跨模块依赖继续确认 | 开工阻断 | 确认中 | 用户当前对话确认 | 2026-08-10 | PDA 进入任务即标记“拣货中”；扫描先写入绑定人员+任务+柜次的本地草稿，仅点击提交时批量写后端；部分拣货/跳拣允许，但未完成项必须填写异常原因并挂起，不能完成任务或进入 `LOADED`。一柜多人并行、退出/换班释放、批量提交超时/错误交互、最终 `LOADED` 触发人及订舱/拖车/报关硬门禁仍待确认 | 全流程、状态机、PDA、页面进度 | -| P3-Q12 | 报关回执包含哪些类型，海关放行是否为装柜完成硬门禁？ | 当前不默认以放行为门禁，业务明确各类回执含义 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 报关状态、装柜完成门禁、客户回执 | +| P3-Q1 | 智能排柜需考虑哪些硬约束和软偏好？ | 业务提供可执行规则表，建议可解释并由人工确认 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 装载率上限 110%；税率高排前暂作为可配置排序，不作为不可变硬编码；系统给出可解释建议，人工确认后生成任务 | 智能排柜、拣货任务 | +| P3-Q2 | 是否存在拼柜、一单多柜和拆批出仓？ | 通过订单-柜次关系预留能力，页面按高频场景逐步开放 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 支持一单多柜、一个柜拼多个订单；采用“父订单→子订单→柜次”关系。已装载数量形成子订单，未装载数量自动生成待后续处理的子订单；不新建独立出仓单 | 订单、柜次、排柜、拣货 | +| P3-Q3 | 原型“预约托车”是否统一为“预约拖车”？ | 建议使用行业常用的“拖车”，同时确认业务实际含义 | 非阻断 | 已确认 | 产品/业务 | 2026-08-10 | 页面、接口和文档统一使用“预约拖车” | 页面文案、接口字段说明 | +| P3-Q4 | 目标 PDA 型号、系统和扫描头接入方式是什么？ | 保持设备适配层，不绑定厂商 SDK | 模块阻断 | 确认中 | 用户当前对话确认 | 2026-08-10 | 采用 uni-app 开发并支持在线更新；Android 广播方式已确认并已接入：Action=`android.intent.action.SCANRESULT`、字符串 Extra=`value`。具体 PDA 型号、Android 版本、打包发布流程和目标设备真机验收仍待技术确认 | PDA 拣货、真机验收 | +| P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 默认使用二期处理单元和当前位置；如需完整库存，单独评估 WMS 范围 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | PDA 拣货必须依赖实时库存和库位可用量；首版复用二期处理单元、当前位置和可用量接口，超量、库存不足和库位不可用由服务端拒绝；不扩展完整 WMS | 二三期契约、拣货、库存边界 | +| P3-Q6 | 柜封照片有哪些必传类型、数量、采集方式、处理规则和留存期限？ | 已确认规则直接进入契约；权限和留存继续确认 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | 空仓、半仓、满仓、锁仓、带锁码照五类各至少 1 张有效照片，同类型可无限追加；PDA 只能现场拍照；后台操作员和理货员可人工上传；拣货员只负责 PDA 现场采集，不开放后台人工上传；错图不硬删除，按原因、操作人、时间作废；带锁码照必须填写锁码文本；照片无限期保留，客户不可见照片和锁码 | 装柜、PDA 拍照、Admin 上传、文件存储、订单后程门禁 | +| P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 清单配置化，并保存业务使用的清单版本 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | 首版不对接海关或代理系统；按人工维护资料清单、收集/补件并保存版本，具体清单可配置 | 客户资料、报关审核、文件版本 | +| P3-Q8 | 报关代理如何接收资料并返回回执？ | 首版系统内整理、线下提交，正式接口后续评估 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | 全部人工处理：平台整理资料后线下交代理，授权人员人工上传代理回执；系统记录提交批次、回执版本和时间，不建设自动对接 | 报关协同、回执上传 | +| P3-Q9 | “港务信息”指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 先确认词义和字段；首版平台人工维护并审计 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 首版聚焦船公司船期/货物跟踪查询；每 3 天查询一次，最多 3 次，记录查询时间、来源、更新时间和过期标识。首批来源：美森、SML、ZIM、COSCO、EMC、合德官网；失败后标记信息过期并保留最近结果 | 订舱、港务查询、客户展示 | +| P3-Q10 | 订单进入“装柜完成”后发现错误如何处理？ | 不直接回退状态，使用授权冲正动作和反向审计事件 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | `LOADED` 后不提供在线冲正/回退入口，统一线下人工处理；系统保留原状态和审计记录，不由国内 Admin/PDA 推进 `DELIVERED` | 装柜完成门禁、权限、审计 | +| P3-Q11 | 九个动作中哪些是强制前置，哪些允许并行？ | 已确认 PDA 子流程直接进入契约，其余跨模块依赖继续确认 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 订舱完成、拖车完成、报关资料完成且有放行回执、PDA 拣货完成及五类证据完整均为进入 `LOADED` 的强制门禁；PDA 单柜次单人作业，不做多人并行；进入任务即拣货中，提交时批量写入 | 全流程、状态机、PDA、页面进度 | +| P3-Q12 | 报关回执包含哪些类型，海关放行是否为装柜完成硬门禁？ | 当前不默认以放行为门禁，业务明确各类回执含义 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 首版回执由人工上传；必须存在有效放行回执才能通过 `LOADED` 门禁。回执类型和版本可追溯，具体字段按人工业务单据映射 | 报关状态、装柜完成门禁、客户回执 | | P3-Q13 | 三期终点以什么状态为准？ | 国内系统以能掌控的最后环节为终点 | 开工阻断 | 已确认 | 用户当前对话确认 | 2026-08-08 | 三期终点为 `LOADED`/装柜完成；`DELIVERED`/派送完成只能在到达海外仓后由海外仓可信回传推进，不属于国内三期操作和验收范围 | 阶段边界、状态、里程碑、验收、海外仓回传 | ### 2.1 PDA 已确认子决策 @@ -43,18 +43,23 @@ | P3-PDA-D08 | 2026-08-09 | 同类型证据允许多张并采用追加记录；错误/重复照片不硬删除，只作废 | 每条照片独立保存；作废记录原因、操作人和时间，历史可追溯 | | P3-PDA-D09 | 2026-08-09 | 空仓、半仓、满仓、锁仓、带锁码照五类证据各至少 1 张有效且未作废的照片，可多张；带锁码照同时要求锁码文本 | 服务端完整性门禁按“每类至少一张有效记录”校验，不能按单槽位替换模型实现 | +> 验收映射：当前自动化已真实覆盖五类证据上传、同类型多图追加、跨类型/伪造 `fileId` 拒绝、锁码文本门禁和错图作废审计；设备在线、持久化草稿批量提交仍按[验收任务拆分与待确认清单](三期验收任务拆分与待确认清单.md)保留 coverageGap。 + ## 三、已确认架构决策 | 编号 | 确认日期 | 最终结论 | 影响 | |---|---|---|---| | P3-D1 | 2026-08-08 | 三期不新建独立出仓单，现有订单列表承载全部主状态；柜次、订舱、拖车、拣货、证据和报关作为订单关联子对象 | 取消出仓单页面和数据模型规划，改为增强现有订单列表/详情及服务端统一编排 | +| P3-D2 | 2026-08-10 | 订单拆分采用“父订单→子订单→柜次”；已装载数量形成子订单，未装载数量自动生成后续子订单；支持一单多柜和多订单拼柜 | 后端必须保留父子订单、柜次、数量分摊和整体时间线；不得把未装载部分静默丢弃 | +| P3-D3 | 2026-08-10 | `LOADED` 的硬门禁包含订舱完成、拖车完成、报关放行回执、PDA 拣货完成和五类证据完整；`LOADED` 后错误线下人工处理 | 统一门禁服务负责校验，国内页面不提供在线冲正或 `DELIVERED` 操作 | +| P3-D4 | 2026-08-10 | 船期按船公司官网查询：每 3 天一次，最多 3 次，保存来源、更新时间和过期标识 | 首批船公司来源配置为美森、SML、ZIM、COSCO、EMC、合德；失败不覆盖最近有效结果 | +| P3-D5 | 2026-08-10 | 初始化仓库常用角色：操作员、拣货员、理货员；按最小权限授予拣货、证据上传和查看能力 | 角色初始化由 IAM/统一 SQL 任务实现，具体权限矩阵在技术契约评审中落表 | ## 四、建议确认顺序 -1. 先确认 P3-Q13、P3-Q11，锁定阶段终点和流程依赖。 -2. 再确认 P3-Q1、P3-Q2、P3-Q5，锁定排柜、柜次和拣货输入。 -3. 然后确认 P3-Q12、P3-Q7、P3-Q8，锁定报关和装柜完成门禁。 -4. 最后确认设备、照片、港务信息、冲正和文案事项。 +1. 已完成 P3-Q1、P3-Q2、P3-Q3、P3-Q6～P3-Q13 的产品确认，可直接进入契约和实现拆分。 +2. P3-Q4 仅保留设备型号、Android 版本、打包发布和真机验收的技术确认。 +3. P3-Q5 仍需技术确认实时库存/库位接口是否作为拣货数据源，不影响已确认的 PDA 交互规则。 ## 五、产品与业务确认会议 @@ -80,10 +85,10 @@ 4. 开工阻断项未解除时，不得将受影响模块标记为可开发。 5. 会议结束后，将结论同步到开发规划、开发进度表、页面原型和后续验收任务。 -### 5.4 会议输出 +### 5.4 会议输出（确认版） -- 13 项确认事项的状态和最终结论。 +- 13 项确认事项的状态和最终结论已同步；其中 P3-Q4、P3-Q5 仅保留技术/设备澄清，不再阻断已确认模块的契约设计。 - 需要新增或调整的原型清单。 - 三期范围内/范围外清单及跨期依赖。 - 仍有风险的事项、责任人和完成日期。 -- 是否允许进入 T02 契约设计与任务拆分的明确结论。 +- 已允许进入 T02 契约设计与任务拆分；未决技术项只阻断其对应实现，不反向阻断整期已确认范围。 diff --git a/三期/三期验收任务拆分与待确认清单.md b/三期/三期验收任务拆分与待确认清单.md new file mode 100644 index 0000000..a396e07 --- /dev/null +++ b/三期/三期验收任务拆分与待确认清单.md @@ -0,0 +1,37 @@ +# 三期验收任务拆分与待确认清单 + +> 更新日期：2026-08-10 +> 本清单只描述真实 HTTP/设备验收边界，不把原型或 mock 结果视为通过。 + +## 已纳入真实 HTTP 验收 + +| 任务 | 真实断言 | 脚本入口 | +|---|---|---| +| PDA 进入任务 | 领取后服务端任务立即进入 `IN_PROGRESS`，并绑定当前作业员 | `phase3-container-loading.mjs` | +| PDA 拣货提交 | 明细数量、重复扫码、旧版本冲突、`operationId` 幂等及复核完成态 | `phase3-container-loading.mjs` | +| 五类装柜证据 | 空仓、半仓、满仓、锁仓、带锁码照均上传真实文件并按客户/柜次绑定 | `phase3-loading.mjs` | +| 同类型多图 | 同一证据类型追加第二张真实图片，原记录与新增记录同时保持有效 | `phase3-loading.mjs` | +| 锁码门禁 | 缺少锁码照片或锁码文本为空时，完成装柜请求被拒绝 | `phase3-loading.mjs` | +| 统一装柜门禁 | 订舱未完成、拖车未完成、报关无有效放行回执、PDA 未完成或五类证据不完整时，真实 `LOADED` 请求均被拒绝 | `service-center-flow.mjs` / `phase3-loading.mjs` | +| 订单/柜次聚合 | 一单多柜、一个柜多订单、父子订单数量分摊及未装数量自动生成子订单可追溯 | `phase3-order-aggregate.mjs`（待补） | +| 船期查询 | 六家船公司来源、三日查询周期、最多三次、更新时间和过期标识真实可见 | `phase3-vessel-tracking.mjs`（待补） | +| 仓库角色 | 操作员、拣货员、理货员初始化、最小权限和跨客户隔离 | `phase3-role-contract.mjs`（待补） | +| 伪造与交叉归属 | 不存在 `fileId`、其他证据类型的 `fileId` 不能绑定 | `phase3-loading.mjs` | + +## 保留 coverageGap 的确认项 + +| 编号 | 待确认/待环境能力 | 保留原因 | 解除条件 | +|---|---|---|---| +| P3-PDA-D01 | PDA 断网、恢复网络和真机在线限制 | HTTP 验收器无法模拟设备网络与现场相机 | 目标 PDA 型号、Android 版本、网络策略和真机环境确定后执行真机脚本 | +| P3-PDA-D03/D04 | 设备持久化草稿、批量提交、跨账号隔离 | 当前公开服务未提供稳定的设备草稿/批量提交 HTTP 契约 | 固定草稿 DTO、提交端点、幂等键、版本字段和清理语义 | +| P3-Q4 | 真机型号、系统、扫描头、打包发布 | 广播协议已接入，但具体设备和真机发布口径未提供 | 产品/技术补齐设备清单并完成真机验收 | +| P3-Q5 | 拣货实时库存与库位数据源 | 已确认 PDA 交互，不代表实时库存接口已稳定 | 技术确认二期库存/位置契约并纳入真实 HTTP 验收 | + +## 并行任务拆分 + +1. `P3-ACCEPT-PDA-ONLINE`：PDA 真机在线/断网/前后台验收。 +2. `P3-ACCEPT-PDA-DRAFT`：草稿持久化、批量提交、幂等、版本冲突和跨账号隔离验收。 +3. `P3-ACCEPT-EVIDENCE-VOID`：五类证据多图追加、作废、锁码文本和 `LOADED` 门禁验收。 +4. `P3-CONFIRM-Q4-Q5`：技术补齐设备/真机和实时库存/库位契约确认。 + +每个任务完成后，必须把真实请求、响应状态、业务码、`requestId/traceId` 写入报告，并删除对应 coverageGap；不得以 mock 或数据库直写替代接口验收。