docs/三期

三期文档

三期以国内头程后程作业为范围，完成从排柜、订舱、拖车和仓内拣货，到装柜证据齐全并进入 LOADED/装柜完成的业务闭环。DELIVERED/派送完成由到达海外仓后的可信回传推进，不属于国内三期操作范围。

当前主体模型与开工禁令

• 三期继续按业务单租户、“平台—客户”两级开发，客户之间严格隔离。Java 与接口中的业务 tenant_id > 0 / tenantId 当前表示客户 ID；tenant_id=0 是平台身份、平台 RBAC 和平台公共仓库、快递公司、托盘、库位等公共资源技术作用域。客户往来单位、订单、文件和费用仍归属客户 tenant_id>0。
• 三期不得新增租户主表、租户选择器、客户所属租户配置、租户切换、租户级 RBAC 或租户级配置，也不得把当前 tenant_id 从客户 ID 改义为上级租户 ID。
• tenant、Tenant*、merchant、接口路径和字段属于历史兼容命名，继续保留；真实租户能力必须等未来独立需求、数据迁移和跨服务契约方案确认后再实施。

文档

• 三期闭环审计报告（2026-08-08）：基于当前代码、接口、自动化和测试环境证据的闭环审计，列出阻断项、优先级和 GO 准入标准。
• 三期装柜闭环产品确认表（2026-08-08）：提供给产品直接填写的纯业务确认表，不包含技术实现细节。
• 三期装柜闭环开发前确认单（2026-08-08）：用于产品确认直接开发前的状态、门禁、PDA 取证、冲正和验收细节。
• 三期开发规划：国内出仓
• 三期开发进度表：参考一期采用“大任务 → 详细任务 → 里程碑 → 未确认事项 → 开工准入 → 验收”结构维护。
• 虫虫出海三期开发进度表（Excel）：可筛选、可下拉维护并使用公式汇总的项目进度工作簿。
• 三期需求确认表：集中跟踪 P3-Q1～P3-Q13、负责人和最终结论。
• 三期页面与原型清单：按管理后台、企业客户端和 PDA 维护页面范围及原型状态。
• 三期验收任务拆分与待确认清单：真实 HTTP/真机验收覆盖、coverageGap 解除条件和并行任务入口。
• 参考资料/出仓流程.png：本期 9 个核心动作及业务终点的原始参考图。

当前状态

三期已从“等待产品确认”转入分模块开发规划。已确认不新建独立出仓单，现有订单列表/详情承载主状态；支持一单多柜、一个柜拼多个订单，并采用“父订单→子订单→柜次”关系，已装载数量形成子订单，未装载数量自动生成后续子订单。进入 LOADED/装柜完成前，订舱完成、拖车完成、报关放行回执、PDA 拣货完成及五类证据完整均为服务端硬门禁；LOADED 后错误统一线下人工处理，国内 Admin/PDA 不提供在线冲正或手工推进 DELIVERED。

船期首版按船公司官网查询，每 3 天一次、最多 3 次，记录来源、查询/更新时间和过期标识。首批来源为美森、SML、ZIM、COSCO、EMC、合德；外部页面不可用时保留最近结果并标记过期。报关首版不做系统对接，全部由人工整理、线下提交和人工上传回执。仓库初始化角色包括操作员、拣货员、理货员，具体权限矩阵由 IAM 契约任务落表。

当前仅 P3-Q4 的设备型号/Android/打包真机口径、P3-Q5 的实时库存与库位数据源仍需技术澄清；这些问题只阻断对应实现，不影响已确认模块进入契约设计和并行开发。

PDA 当前确认口径（2026-08-10）

• Android 扫描广播方式已接入；具体设备型号、系统版本、打包发布和真机验收仍待确认。
• 正式作业仅支持在线：进入任务即标记“拣货中”，扫描保存在绑定作业员+任务+柜次的设备持久化草稿，点击提交时批量写后端。
• 允许部分拣货或跳拣，但每个未完成项必须填写异常原因；存在未解决异常时不能完成或进入 LOADED。
• 重复提交返回原结果，版本冲突提示员工刷新重试。
• PDA 只能现场拍照，Admin 可人工上传；五类证据各至少 1 张有效照片，可同类型多张追加，错图只作废不硬删除。
• 单柜次只允许一名作业员作业，不做多人并行和任务接管；进入任务即标记“拣货中”，扫描草稿按作业员+任务+柜次隔离，点击提交时批量写入后端。
• 后台操作员、拣货员、理货员可按权限人工上传证据；照片无限期保留，客户不可见照片和锁码。