diff --git a/AI工程执行与协作约束.md b/AI工程执行与协作约束.md index 47d0c82..b8df966 100644 --- a/AI工程执行与协作约束.md +++ b/AI工程执行与协作约束.md @@ -23,14 +23,14 @@ - 收敛范围包括源码结构、接口与 DTO、字段、状态机、权限、配置键、OpenAPI、数据库结构与初始化 SQL、事件、路由、页面、前端消费者、Mock/Fixture、测试和脚本；旧实现冲突时同步修改全部生产者与消费者并直接删除旧实现。 - 禁止为旧代码、旧调用或开发环境存量保留旧接口/旧字段别名、兼容分支、双协议、双写、灰度、回滚版本、降级解析、旧行为回退、临时适配层、迁移脚本、回填脚本、清理补偿或新旧版本并行；不得以“稳妥”“兼容历史数据”或“先保留以后删除”为由延迟收敛。 - 开发环境数据库记录、上传文件、缓存、会话、消息、搜索索引和其他运行状态均可丢弃；正常验证方式是更新最新初始化基线、重新造数或上传，并直接运行受影响回归，不模拟生产迁移。已有历史 SQL 只用于开发追溯，不构成兼容依据。 -- 后端位于独立 Git 仓库 `../baiyue-firstleg/`，执行 Git 命令前确认当前工作目录。“无需兼容、直接修复”不授权自动重置数据库、删除数据/文件、执行 SQL、部署或修改环境。测试环境授权只读 `独立任务协作登记.md`，开发五期授权只读 `开发环境独立任务协作登记.md`；未登记任务和生产环境仍需用户在当前轮明确授权。 +- 后端位于独立 Git 仓库 `../baiyue-firstleg/`，执行 Git 命令前确认当前工作目录。“无需兼容、直接修复”不授权自动重置数据库、删除数据/文件、执行 SQL、部署或修改环境。测试环境授权只读 `独立任务协作登记.md`，开发全流程授权只读 `开发环境独立任务协作登记.md`；未登记任务和生产环境仍需用户在当前轮明确授权。 ## 联调、部署与数据库 -- 默认只准备代码、验证结果和人工部署步骤，不触发 Jenkins、不启动本地 Java/Nacos/数据库。开发五期总控可按 `开发环境独立任务协作登记.md` 的授权操作开发数据库、部署开发环境并执行开发环境真实 HTTP；登记专项可按 `独立任务协作登记.md` 的持续授权查询和修改用户指定的测试数据库。两类授权不得跨环境复用，也不得自动扩大到 Jenkins 或生产环境。 +- 默认只准备代码、验证结果和人工部署步骤，不触发 Jenkins、不启动本地 Java/Nacos/数据库。开发全流程总控可按 `开发环境独立任务协作登记.md` 的授权操作开发数据库、部署开发环境并执行开发环境真实 HTTP；登记专项可按 `独立任务协作登记.md` 的持续授权查询和修改用户指定的测试数据库。两类授权不得跨环境复用，也不得自动扩大到 Jenkins 或生产环境。 - 只有用户在当前轮明确授权指定环境、服务和提交时，才可部署或执行 HTTP 验收；测试数据库的读写例外仅适用于登记表中已持续授权的总控与专项，并遵守其中的职责和破坏性操作门禁。 - 环境地址、凭据和 Token 不写入源码或 `AGENTS.md`。接口不可用或契约不一致时记录路径、状态、错误码、`requestId`/`traceId` 和阻断原因，不回退到模拟成功。 -- 测试环境联调、部署和验收命令读取 `测试环境Jenkins部署指南.md`；开发五期只按 `开发环境独立任务协作登记.md` 的授权与目标项目指引执行，不把测试 Jenkins 流程当作开发部署入口。 +- 测试环境联调、部署和验收命令读取 `测试环境Jenkins部署指南.md`；开发全流程只按 `开发环境独立任务协作登记.md` 的授权与目标项目指引执行，不把测试 Jenkins 流程当作开发部署入口。 ## 通用工程与质量门禁 @@ -48,9 +48,9 @@ ## 独立任务与多任务协作 - 跨环境调度必须先核对保存项目 projectId、任务 cwd 与环境登记表三项一致；任一不一致不得下发或执行。禁止把测试环境任务通过绝对路径提示临时改作开发环境任务，反向同样禁止。 -- 开发环境五期任务只使用 `开发环境独立任务协作登记.md`；测试环境任务只使用 `独立任务协作登记.md`。两套任务不互相复用，不在两个目录之间复制未提交文件、生成补丁、自动合并或 cherry-pick。 +- 开发环境全流程任务只使用 `开发环境独立任务协作登记.md`；测试环境任务只使用 `独立任务协作登记.md`。两套任务不互相复用，不在两个目录之间复制未提交文件、生成补丁、自动合并或 cherry-pick。 -- 普通任务不读取协作登记。只有用户明确指定当前对话为总控，或要求检索历史任务、独立任务或跨对话通信时，才按当前保存项目与 cwd 读取唯一匹配的登记表：开发五期读 `开发环境独立任务协作登记.md`，测试环境读 `独立任务协作登记.md`；不得同时加载两表后混合选取任务。 +- 普通任务不读取协作登记。只有用户明确指定当前对话为总控，或要求检索历史任务、独立任务或跨对话通信时，才按当前保存项目与 cwd 读取唯一匹配的登记表：开发全流程读 `开发环境独立任务协作登记.md`，测试环境读 `独立任务协作登记.md`；不得同时加载两表后混合选取任务。 - 总控在接收任务时必须先做时长评估；预计单一执行链超过 15 分钟时，不得继续由一个任务从定位包办到验收，必须立即拆成可并行的“根因/契约核对、实现修复、回归验收”等独立工作包，并明确每包文件写权限和交付物。优先复用登记表中的长期专项；一次性工作使用内部子代理。该规则不自动授权创建新的用户可见任务。 - 实际执行超过 15 分钟仍未形成可验证交付时，总控必须主动重新拆分或缩小范围，向用户报告当前阻断与并行安排，不得静默等待、继续扩展设计或把非必要兼容、迁移、补偿工作并入主修复链。 - 用户按业务流程逐节点进行人工验收时，总控必须以“当前验收节点”为调度和完成单位，而不是以代码模块或单个 Bug 为单位。收到该节点首个问题后，应立即并行检查前端交互、后端状态与契约、数据/权限前置和自动化验收覆盖；同一节点后续问题统一并入该批次，不得连续串行追加给一个长期专项。 diff --git a/README.md b/README.md index 5a00418..9581044 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,44 @@ # 虫虫出海文档索引 -项目交付文档按阶段归档，跨阶段原型、调研和过程设计保留在原专题目录。 +项目交付文档按业务域组织。当前开发环境以端到端全流程为统一范围；历史规划、确认和验收记录保留在对应业务域目录，仅用于追溯决策，不构成功能边界。 -## 阶段文档 +## 业务域文档 -- [一期文档](一期/README.md)：一期范围、开发进度和头程订单最小闭环。 -- [二期文档](二期/README.md)：预约取货、到仓收货、实测差异和指定库位闭环。 -- [三期文档](三期/README.md)：智能排柜、订舱、拖车、PDA 拣货、报关协同和国内出仓闭环。 -- [四期文档](四期/README.md)：国内出仓后的船节点定时查询、海外接柜、合作仓卸货入库、库存与库内操作，以及海外采购、本土卡车和本土散板；不包含海外仓出库业务。 - - [船节点标准化契约](四期/船节点标准化契约.md)：统一船司原始状态、十个标准节点、预计/实际时间、异常事实、还柜停止规则和新增船司接入门禁。 -- [测试环境独立任务协作登记](独立任务协作登记.md)：只维护测试环境系统总控与长期专项的稳定 `task_id`、父子关系、职责和测试数据库授权。 -- [开发环境独立任务协作登记](开发环境独立任务协作登记.md)：只维护开发环境五期总控与专项的稳定 `task_id`、projectId、职责及开发数据库/部署/HTTP 授权。 +- [订单与客户](订单与客户/README.md)：登录认证、客户与企业、权限、头程订单和客户工作台。 +- [入库测量与计费](入库测量与计费/README.md)：预约取货、到仓收货、箱码与箱唛、测量、尺寸策略、计价和入库费用。 +- [国内货柜履约](国内货柜履约/README.md)：分柜与同柜、智能排柜、订舱、拖车、PDA 拣货、装柜、报关和国内出仓。 +- [海外仓业务](海外仓业务/README.md)：船节点、海外接柜、入仓、库存、托盘、换标、转运、废弃、退货、排车、PDA 出库、派送、异常退回、客户回访、一件代发及海外本土业务。 + - [船节点标准化契约](海外仓业务/船节点标准化契约.md)：统一船司原始状态、标准节点、预计/实际时间、异常事实、还柜停止规则和新增船司接入门禁。 +- [财务管理](财务管理/README.md)：应收、应付、费用池、账单、收款、成本、核销、凭证以及国内外业务费用来源。 -## 跨阶段参考 +## 全流程公共契约 - [跨区域认证与服务通信契约](跨区域认证与服务通信契约.md)：统一账号、国内/海外 Token、双区域 API、JWKS、Outbox/Inbox 与服务身份边界。 - [双区域部署与 Nacos 规划](双区域部署与Nacos规划.md)：开发/测试同机共置、生产国内/海外独立控制面、Nacos、数据库及 Event Bridge 部署边界。 -- [阿里云生产环境选型、压测与上线手册](阿里云生产环境选型压测与上线手册.md)：面向新手运维的 ECS/ALB、RDS MySQL、Tair/Redis、OSS、MSE Nacos、RocketMQ 选型，压测步骤、高可用演练、监控、备份与上线清单。 - [平台、客户层级与权限契约](平台客户层级与权限契约.md)：平台/客户两级产品语义、列表包含详情的只读权限和跨层同步要求。 -- [AI 工程执行与协作约束](AI工程执行与协作约束.md)：临时目录、依赖复用、当前开发阶段、部署数据库授权、质量门禁和独立任务协作规则。 -- [财务管理闭环盘点与范围建议](财务管理/README.md)：基于当前入库计费、财务原型和现有代码盘点财务闭环、缺口及建议的首期应收边界。 -- [墨家设备测量上传接口说明 V3](墨家设备测量上传接口说明-V3.md)：墨家测量设备经 Gateway 上传箱码、尺寸、重量和图片的开放接口契约。 -- [统一订单主状态与操作契约](统一订单主状态与操作契约.md)：统一订单七状态、操作编码、内部状态兼容映射，以及与三期一致的 `LOADED` 硬门禁和 `DELIVERED` 可信回传边界。 -- [首页数据看板真实化与统计策略规划](首页数据看板真实化与统计策略规划.md)：记录首页看板当前数据能力、实时/缓存边界、指标口径和后续实施顺序。 -- [Admin/Client 前端原型还原验收规则](Admin-Client前端原型还原验收规则.md)：已确认原型页面的逐操作承载方式、视觉还原、响应式检查和验收证据要求。 +- [统一订单主状态与操作契约](统一订单主状态与操作契约.md)：统一订单状态、操作编码、内部状态映射和可信履约回传边界。 +- [Admin/Client 前端原型还原验收规则](Admin-Client前端原型还原验收规则.md)：页面操作承载方式、视觉还原、响应式检查和验收证据要求。 +- [AI 工程执行与协作约束](AI工程执行与协作约束.md)：工作区、依赖、Git、部署、数据库、质量门禁和独立任务协作规则。 - [数据库中文注释维护规范](数据库注释维护规范.md)：数据库注释口径、职责、迁移流程、自动门禁与实值验收要求。 -- [测试环境 Jenkins 部署指南](测试环境Jenkins部署指南.md)：测试环境持续部署授权、Job 参数、执行边界、健康检查与失败处理。 -- `悦/`：产品原型、流程图、历史架构资料和调研数据，仅作为需求参考，不直接等同于已确认范围。 -- `superpowers/`：具体功能的设计与实施记录，按日期和主题维护。 +- [测试环境 Jenkins 部署指南](测试环境Jenkins部署指南.md)：测试环境持续部署授权、Job 参数、健康检查与失败处理。 +- [阿里云生产环境选型、压测与上线手册](阿里云生产环境选型压测与上线手册.md)：ECS/ALB、RDS MySQL、Redis、OSS、Nacos、RocketMQ、压测、高可用、监控、备份与上线清单。 +- [首页数据看板真实化与统计策略规划](首页数据看板真实化与统计策略规划.md)：首页指标、实时与缓存边界、统计口径和实施顺序。 +- [墨家设备测量上传接口说明 V3](墨家设备测量上传接口说明-V3.md)：测量设备经 Gateway 上传箱码、尺寸、重量和图片的接口契约。 + +## 环境协作 + +- [开发环境独立任务协作登记](开发环境独立任务协作登记.md)：开发环境全流程总控与长期专项的稳定任务、职责及开发数据库/部署/HTTP 授权。 +- [测试环境独立任务协作登记](独立任务协作登记.md)：测试环境系统总控与长期专项的稳定任务、职责和测试数据库授权。 + +## 参考资料 + +- `悦/`：产品原型、流程图、历史架构资料和调研数据，只作为需求参考，不直接定义当前范围。 +- `superpowers/`：按日期和主题保留的具体功能设计与实施记录。 ## 维护规则 -- 只影响单个阶段的范围、进度和验收文档放入对应阶段目录。 -- 公共架构、跨阶段契约和长期产品资料保留在 `docs/` 根目录或独立专题目录。 -- 阶段范围变化时同步更新该阶段的规划、进度表及受影响的公共契约。 -- 原型中出现的功能不自动进入开发范围，必须在阶段规划中明确优先级、依赖和验收标准。 +- 新文档按业务域归档，不新增以开发批次编号命名的目录、文件、标题、任务或范围标签。 +- 当前交付范围始终按端到端全流程理解；业务域目录只用于检索和职责归属，不用于排除上下游流程。 +- 范围、字段或流程冲突时，按“当前对话确认 > 正式契约与确认记录 > 项目指引与代码 > 原型 > 历史记录”判断。 +- 新增或修改业务能力时，同步更新业务域 README、跨端契约、接口、权限、SQL、测试和验收入口。 +- 原型中出现的功能不自动成为有效实现；必须由正式契约、代码和验收证据共同确认。 diff --git a/superpowers/specs/2026-07-28-admin-static-rbac-preview-design.md b/superpowers/specs/2026-07-28-admin-static-rbac-preview-design.md index 2604b0b..7b098cc 100644 --- a/superpowers/specs/2026-07-28-admin-static-rbac-preview-design.md +++ b/superpowers/specs/2026-07-28-admin-static-rbac-preview-design.md @@ -59,7 +59,7 @@ - 退出操作先调用权限预览 Store 的重置动作，清除内存状态与持久化演示角色 ID，再调用 `auth.logout()`；认证 Store 不承担预览状态职责。 - 登录成功后由登录流程调用权限预览 Store 的初始化动作，默认选择启用的超级管理员；超级管理员不可用时选择第一个启用角色。未登录阶段不自动初始化或重新持久化默认角色。 - 顶栏固定区分两个来源：`登录身份：{auth.user.name}（{auth.user.account}）` 与 `权限预览：{previewRole.name}`。认证角色 `auth.user.roles` 不作为无标签副标题展示，也不被预览状态读取或改写。 -- `localStorage` 在同源标签页之间共享，但本期不监听 `storage` 事件做实时跨标签同步；其他标签页刷新后读取最新持久化角色。 +- `localStorage` 在同源标签页之间共享，但当前不监听 `storage` 事件做实时跨标签同步；其他标签页刷新后读取最新持久化角色。 ### 权限数据流 diff --git a/一期/虫虫出海一期开发进度表.xlsx b/一期/虫虫出海一期开发进度表.xlsx deleted file mode 100644 index 76d3244..0000000 Binary files a/一期/虫虫出海一期开发进度表.xlsx and /dev/null differ diff --git a/三期/README.md b/三期/README.md deleted file mode 100644 index 3050d5e..0000000 --- a/三期/README.md +++ /dev/null @@ -1,51 +0,0 @@ -# 三期文档 - -三期以国内头程后程作业为范围，完成从排柜、订舱、拖车和仓内拣货，到装柜证据齐全并进入 `LOADED`/装柜完成的业务闭环。`DELIVERED`/派送完成由到达海外仓后的可信回传推进，不属于国内三期操作范围。 - -> 范围更正：三期只维护订舱和出仓前所需的船名航次、港口、ETD/ETA 等资料。柜子确认离开国内仓库后的 `CarrierScheduleQuery`、六家船公司查询、每 3 天/最多 3 次、来源/过期标识和后续定时船节点查询整体归四期，见 `../四期/README.md`。三期不再建设或验收这套查询。 - -## 当前主体模型与开工禁令 - -- 三期继续按业务单租户、“平台—客户”两级开发，客户之间严格隔离。Java 与接口中的业务 `tenant_id > 0` / `tenantId` 当前表示客户 ID；`tenant_id=0` 是平台身份、平台 RBAC 和平台公共仓库、快递公司、托盘、库位等公共资源技术作用域。客户往来单位、订单、文件和费用仍归属客户 `tenant_id>0`。 -- 三期不得新增租户主表、租户选择器、客户所属租户配置、租户切换、租户级 RBAC 或租户级配置，也不得把当前 `tenant_id` 从客户 ID 改义为上级租户 ID。 -- `tenant`、`Tenant*`、`merchant`、接口路径和字段属于历史兼容命名，继续保留；真实租户能力必须等未来独立需求、数据迁移和跨服务契约方案确认后再实施。 - -## 文档 - -- [三期闭环审计报告（2026-08-08）](三期闭环审计报告-2026-08-08.md)：基于当前代码、接口、自动化和测试环境证据的闭环审计，列出阻断项、优先级和 GO 准入标准。 -- [三期装柜闭环产品确认表（2026-08-08）](三期装柜闭环产品确认表-2026-08-08.md)：提供给产品直接填写的纯业务确认表，不包含技术实现细节。 -- [三期装柜闭环开发前确认单（2026-08-08）](三期装柜闭环开发前确认单-2026-08-08.md)：用于产品确认直接开发前的状态、门禁、PDA 取证、冲正和验收细节。 -- [三期开发规划：国内出仓](三期开发规划.md) -- [三期开发进度表](三期开发进度表.md)：参考一期采用“大任务 → 详细任务 → 里程碑 → 未确认事项 → 开工准入 → 验收”结构维护。 -- [虫虫出海三期开发进度表（Excel）](虫虫出海三期开发进度表.xlsx)：可筛选、可下拉维护并使用公式汇总的项目进度工作簿。 -- [三期需求确认表](三期需求确认表.md)：集中跟踪 P3-Q1～P3-Q13、负责人和最终结论。 -- [三期开工门禁](三期开工门禁.md)：维护已确认范围、跨端硬边界和局部阻断项；模块指引引用本文件，不重复维护阶段状态。 -- [三期页面与原型清单](三期页面与原型清单.md)：按管理后台、企业客户端和 PDA 维护页面范围及原型状态。 -- [三期验收任务拆分与待确认清单](三期验收任务拆分与待确认清单.md)：真实 HTTP/真机验收覆盖、coverageGap 解除条件和并行任务入口。 -- `参考资料/出仓流程.png`：本期 9 个核心动作及业务终点的原始参考图。 - -## 当前状态 - -三期已进入分模块部署联调。已确认不新建独立出仓单，现有订单列表/详情承载主状态；支持一单多柜、一个柜拼多个订单，并采用“父订单→子订单→柜次”关系，已装载数量形成子订单，未装载数量自动生成后续子订单。进入 `LOADED`/装柜完成前，订舱完成、拖车完成、报关放行回执、PDA 拣货完成及五类证据完整均为服务端硬门禁；`LOADED` 后错误统一线下人工处理，国内 Admin/PDA 不提供在线冲正或手工推进 `DELIVERED`。当前不能因子链路已通过而宣告整期完成，最终结论以真实 HTTP 全链路验收为准。 - -柜子出仓后的船公司/船节点查询已重新归入四期。三期报关首版不做系统对接，全部由人工整理、线下提交和人工上传回执。仓库初始化角色包括操作员、拣货员、理货员，具体权限矩阵由 IAM 契约任务落表。 - -P3-Q1～P3-Q13 均已确认；P3-Q4 采用 uni-app 开发并支持在线更新，Android 广播扫描已接入。P3-Q5 复用二期实时库存、当前位置和可用量接口，不扩展完整 WMS。 - -### PDA 当前确认口径（2026-08-10） - -- Android 扫描广播方式已接入；PDA 采用 uni-app 开发并支持在线更新，按既定发布安排完成真机验收。 -- 正式作业仅支持在线：进入任务即标记“拣货中”，扫描保存在绑定作业员+任务+柜次的设备持久化草稿，点击提交时批量写后端。 -- 允许部分拣货或跳拣，但每个未完成项必须填写异常原因；存在未解决异常时不能完成或进入 `LOADED`。 -- 重复提交返回原结果，版本冲突提示员工刷新重试。 -- PDA 只能现场拍照，Admin 可人工上传；五类证据各至少 1 张有效照片，可同类型多张追加，错图只作废不硬删除。 -- 单柜次只允许一名作业员作业，不做多人并行和任务接管；进入任务即标记“拣货中”，扫描草稿按作业员+任务+柜次隔离，点击提交时批量写入后端。 -- 后台操作员、理货员可按权限人工上传证据；拣货员只负责 PDA 现场拍照，不开放后台人工上传。照片无限期保留，客户不可见照片和锁码。 - -### 发布与真实验收状态（2026-08-10） - -- Admin 已部署 `b593d72`：智能装柜、预装清单、装柜清单均可访问真实接口；预装/装柜清单不再要求选择仓库，详情仍使用列表行返回的真实仓库归属。 -- Firstleg 已部署 `3bfc11a`：修复 PDA 拣货时库位分配状态提前变更的问题；真实复跑仍发现 PDA `pick` 第二处 `S0500`，当前仍阻断 PDA 复核、装柜完成、报关 LOADED 关联和最终门禁，不能标记三期闭环完成。 -- 验收 fixture 顺序已核实为 `orders → inbound-measurement → phase3-container-loading → phase3-loading → phase3-customs → phase3-port-schedules → phase3-loading-finalize`；脚本保留真实失败，不以 mock、历史资源或 coverage gap 伪装通过。 -- PDA“点击提交时批量写入后端”的原子 batch 契约尚未实现；当前页面仍不能证明整批事务、批次幂等、服务端库存快照和失败整批回滚已具备。 -- ZIM hCaptcha、COSCO 动态页继续按产品确认的人工兜底保留为 `MANUAL_REQUIRED`，不作为自动查询 PASS。 diff --git a/三期/虫虫出海三期开发进度表.xlsx b/三期/虫虫出海三期开发进度表.xlsx deleted file mode 100644 index a63981d..0000000 Binary files a/三期/虫虫出海三期开发进度表.xlsx and /dev/null differ diff --git a/二期/README.md b/二期/README.md deleted file mode 100644 index 196707b..0000000 --- a/二期/README.md +++ /dev/null @@ -1,86 +0,0 @@ -# 二期文档 - -二期当前范围止于头程下单、商户提交、平台审核、到仓测量与称重、费用试算和费用确认。测量审核后主状态停在 `WAIT_SPLIT`，费用可独立维护且不得回退主流程状态；分柜、托盘/库位、预装、PDA 拣货、装柜和派送统一归入三期。二期不建设应收应付、对账、收付款、核销、发票和利润模块。 - -## 当前主体模型 - -- 二期继续按“平台—客户”两级开发。`tenant_id > 0` / `tenantId` 当前表示客户 ID，用于客户隔离；`tenant_id=0` 是平台技术作用域。 -- 不新增真实租户、租户选择器或租户级 RBAC，也不把兼容字段重定义为上级租户。历史路径、字段与配置名继续保留。 -- 平台公共仓库、快递公司、托盘、库位和费用项目统一归属平台技术作用域 `tenant_id=0`，不绑定客户；客户往来单位、订单、文件和费用明细仍按所属客户 `tenant_id>0` 严格隔离，费用明细引用公共 `fee_item_id`。`10001` 是客户 ID，不得用于公共资源归属。 - -## 文档 - -- [二期 V2 需求确认清单（当前会议填写）](二期V2需求确认清单.md) -- [二期需求优化版 V2：测量、计费、托盘入库主流程](二期需求优化版-v2-测量计费入库主流程.md) -- [二期需求优化版：原型对照（上一版优化稿）](二期需求优化版-原型对照.md) -- [二期开发规划：头程到仓](二期开发规划.md) -- [二期头程计费模块规划](二期计费财务模块规划.md) -- [二期头程计费需求确认表](二期计费财务需求确认表.md) -- [二期费用项目数据归属决策记录](二期费用项目数据归属决策记录.md) -- [二期头程计费需求确认表（Excel，保留历史文件名）](二期计费财务需求确认表.xlsx) -- [二期产品待确认事项（发产品填写）](二期产品待确认事项.md) -- [二期开发进度表](二期开发进度表.md) -- [二期开发进度表（Excel）](虫虫出海二期开发进度表.xlsx) -- [二期前端页面清单与多对话并行任务表](二期前端页面清单与多对话并行任务表.md) -- [海外仓阶梯费用前端联调说明（2026-08-05）](海外仓阶梯费用前端联调说明-2026-08-05.md) -- [二期需求确认清单：产品与业务确认](二期需求确认清单.md) -- [二期需求确认清单（会议填写 Excel）](二期需求确认清单.xlsx) -- [规划依据：头程物流流程图](参考资料/头程物流流程图.svg) - -## 当前状态 - -截至 2026-08-06，当前阶段边界已重新确认为 `WAIT_SPLIT + APPROVED + CONFIRMED`：`WAIT_SPLIT` 只表示二期已完成、等待未来三期分柜，不代表三期已启动。2026-08-04 的 `INBOUNDED + APPROVED + SENT` 是旧范围下的历史回归结果，不再作为当前二期验收终点。 - -- 订单：`2084549604719718402` -- 入库单：`2084549769916538881` -- 入仓码：`RK-2084549604719718402` -- 测量批次：`2084556854154715137` -- 费用单：`FBAF-2084549769916538881-1` -- 计费结果：实重 `20kg`，体积 `0.24m³`，计费量 `40.08kg`，费用 `440.68 CNY` -- 自动化测试：Firstleg 77 项、Warehouse 68 项、公共仓储技术归属专项（历史测试名含“资源租户”）3 项全部通过 -- 在线验证：7 个隔离服务健康状态均为 `UP` - -本地 OCR 未配置真实供应商凭证，因此本轮验证的是“图片上传成功、OCR 返回失败、人工修正并确认、继续完成计费入库”的可用降级链路。真实 OCR 识别准确率仍需在测试环境使用现场秤图验证。 - -产品确认与技术验收是两类状态。V2 的 C1-C8 产品结论仍由产品/业务负责人填写；已经实现和测试通过的技术能力记录在验收报告及确认清单的技术状态章节中。 - -## 核心文档 - -- [二期前端联调报告（2026-08-04）](二期前端联调报告-2026-08-04.md) -- [第三方入仓测量接口联调说明](第三方入仓测量接口联调说明-2026-08-04.md) -- [二期需求优化版 V2：测量、计费、托盘入库主流程](二期需求优化版-v2-测量计费入库主流程.md) -- [二期 V2 需求确认清单](二期V2需求确认清单.md) - -## 规划与历史文档 - -- [二期需求优化版：原型对照](二期需求优化版-原型对照.md) -- [二期开发规划：头程到仓](二期开发规划.md) -- [二期开发进度表](二期开发进度表.md) -- [二期头程计费模块规划](二期计费财务模块规划.md) -- [二期头程计费需求确认表](二期计费财务需求确认表.md) -- [二期费用项目数据归属决策记录](二期费用项目数据归属决策记录.md) -- [二期产品待确认事项](二期产品待确认事项.md) -- [二期需求确认清单：产品与业务确认](二期需求确认清单.md) - -## 数据库增量 - -可重复执行的测试库增量脚本位于： - -```text -D:\baiyue-firstleg\deploy\sql\头程数据库统一增量-MySQL8.sql -``` - -该文件是头程数据库唯一增量入口，后续数据库变更只追加到此文件。当前已包含一期、二期以及海外仓阶梯费用基础资料所需结构、索引和权限。历史日期脚本不再作为部署入口。 - -其中海外仓阶梯费用新增： - -- `wh_overseas_storage_fee_rule` -- `wh_overseas_storage_fee_tier` -- 5 个查询、唯一性和关联索引 -- 4 项平台端按钮权限及平台系统管理员默认授权 - -原二期回归字段仍包含： - -- `fl_inbound_weight_result.created_by` -- `fl_inbound_weight_result.updated_by` -- `fl_inbound_pallet_allocation.warehouse_resource_tenant_id` diff --git a/二期/二期计费财务需求确认表.xlsx b/二期/二期计费财务需求确认表.xlsx deleted file mode 100644 index 3319248..0000000 Binary files a/二期/二期计费财务需求确认表.xlsx and /dev/null differ diff --git a/二期/二期需求确认清单.xlsx b/二期/二期需求确认清单.xlsx deleted file mode 100644 index ffaf890..0000000 Binary files a/二期/二期需求确认清单.xlsx and /dev/null differ diff --git a/二期/产品回传/2026-07-28-二期需求确认-产品回传.xlsx b/二期/产品回传/2026-07-28-二期需求确认-产品回传.xlsx deleted file mode 100644 index ba38438..0000000 Binary files a/二期/产品回传/2026-07-28-二期需求确认-产品回传.xlsx and /dev/null differ diff --git a/二期/产品回传/2026-07-31-二期需求确认-产品回传-v1.xlsx b/二期/产品回传/2026-07-31-二期需求确认-产品回传-v1.xlsx deleted file mode 100644 index b283441..0000000 Binary files a/二期/产品回传/2026-07-31-二期需求确认-产品回传-v1.xlsx and /dev/null differ diff --git a/二期/版本归档/2026-07-28-覆盖前-二期开发进度表.xlsx b/二期/版本归档/2026-07-28-覆盖前-二期开发进度表.xlsx deleted file mode 100644 index dbfc6b7..0000000 Binary files a/二期/版本归档/2026-07-28-覆盖前-二期开发进度表.xlsx and /dev/null differ diff --git a/二期/虫虫出海二期开发进度表.xlsx b/二期/虫虫出海二期开发进度表.xlsx deleted file mode 100644 index a777d16..0000000 Binary files a/二期/虫虫出海二期开发进度表.xlsx and /dev/null differ diff --git a/入库测量与计费/README.md b/入库测量与计费/README.md new file mode 100644 index 0000000..92c6322 --- /dev/null +++ b/入库测量与计费/README.md @@ -0,0 +1,86 @@ +# 入库测量与计费文档 + +入库测量与计费当前范围止于头程下单、商户提交、平台审核、到仓测量与称重、费用试算和费用确认。测量审核后主状态停在 `WAIT_SPLIT`，费用可独立维护且不得回退主流程状态；分柜、托盘/库位、预装、PDA 拣货、装柜和派送统一归入国内货柜履约。入库测量与计费不建设应收应付、对账、收付款、核销、发票和利润模块。 + +## 当前主体模型 + +- 入库测量与计费继续按“平台—客户”两级开发。`tenant_id > 0` / `tenantId` 当前表示客户 ID，用于客户隔离；`tenant_id=0` 是平台技术作用域。 +- 不新增真实租户、租户选择器或租户级 RBAC，也不把兼容字段重定义为上级租户。历史路径、字段与配置名继续保留。 +- 平台公共仓库、快递公司、托盘、库位和费用项目统一归属平台技术作用域 `tenant_id=0`，不绑定客户；客户往来单位、订单、文件和费用明细仍按所属客户 `tenant_id>0` 严格隔离，费用明细引用公共 `fee_item_id`。`10001` 是客户 ID，不得用于公共资源归属。 + +## 文档 + +- [入库测量与计费 V2 需求确认清单（当前会议填写）](入库测量与计费V2需求确认清单.md) +- [入库测量与计费需求优化版 V2：测量、计费、托盘入库主流程](入库测量与计费需求优化版-v2-测量计费入库主流程.md) +- [入库测量与计费需求优化版：原型对照（上一版优化稿）](入库测量与计费需求优化版-原型对照.md) +- [入库测量与计费开发规划：头程到仓](入库测量与计费开发规划.md) +- [入库测量与计费头程计费模块规划](入库测量与计费计费财务模块规划.md) +- [入库测量与计费头程计费需求确认表](入库测量与计费计费财务需求确认表.md) +- [入库测量与计费费用项目数据归属决策记录](入库测量与计费费用项目数据归属决策记录.md) +- [入库测量与计费头程计费需求确认表（Excel，保留历史文件名）](入库测量与计费计费财务需求确认表.xlsx) +- [入库测量与计费产品待确认事项（发产品填写）](入库测量与计费产品待确认事项.md) +- [入库测量与计费开发进度表](入库测量与计费开发进度表.md) +- [入库测量与计费开发进度表（Excel）](虫虫出海入库测量与计费开发进度表.xlsx) +- [入库测量与计费前端页面清单与多对话并行任务表](入库测量与计费前端页面清单与多对话并行任务表.md) +- [海外仓阶梯费用前端联调说明（2026-08-05）](海外仓阶梯费用前端联调说明-2026-08-05.md) +- [入库测量与计费需求确认清单：产品与业务确认](入库测量与计费需求确认清单.md) +- [入库测量与计费需求确认清单（会议填写 Excel）](入库测量与计费需求确认清单.xlsx) +- [规划依据：头程物流流程图](参考资料/头程物流流程图.svg) + +## 当前状态 + +截至 2026-08-06，当前阶段边界已重新确认为 `WAIT_SPLIT + APPROVED + CONFIRMED`：`WAIT_SPLIT` 只表示入库测量与计费已完成、等待未来国内货柜履约分柜，不代表国内货柜履约已启动。2026-08-04 的 `INBOUNDED + APPROVED + SENT` 是旧范围下的历史回归结果，不再作为当前入库测量与计费验收终点。 + +- 订单：`2084549604719718402` +- 入库单：`2084549769916538881` +- 入仓码：`RK-2084549604719718402` +- 测量批次：`2084556854154715137` +- 费用单：`FBAF-2084549769916538881-1` +- 计费结果：实重 `20kg`，体积 `0.24m³`，计费量 `40.08kg`，费用 `440.68 CNY` +- 自动化测试：Firstleg 77 项、Warehouse 68 项、公共仓储技术归属专项（历史测试名含“资源租户”）3 项全部通过 +- 在线验证：7 个隔离服务健康状态均为 `UP` + +本地 OCR 未配置真实供应商凭证，因此本轮验证的是“图片上传成功、OCR 返回失败、人工修正并确认、继续完成计费入库”的可用降级链路。真实 OCR 识别准确率仍需在测试环境使用现场秤图验证。 + +产品确认与技术验收是两类状态。V2 的 C1-C8 产品结论仍由产品/业务负责人填写；已经实现和测试通过的技术能力记录在验收报告及确认清单的技术状态章节中。 + +## 核心文档 + +- [入库测量与计费前端联调报告（2026-08-04）](入库测量与计费前端联调报告-2026-08-04.md) +- [第三方入仓测量接口联调说明](第三方入仓测量接口联调说明-2026-08-04.md) +- [入库测量与计费需求优化版 V2：测量、计费、托盘入库主流程](入库测量与计费需求优化版-v2-测量计费入库主流程.md) +- [入库测量与计费 V2 需求确认清单](入库测量与计费V2需求确认清单.md) + +## 规划与历史文档 + +- [入库测量与计费需求优化版：原型对照](入库测量与计费需求优化版-原型对照.md) +- [入库测量与计费开发规划：头程到仓](入库测量与计费开发规划.md) +- [入库测量与计费开发进度表](入库测量与计费开发进度表.md) +- [入库测量与计费头程计费模块规划](入库测量与计费计费财务模块规划.md) +- [入库测量与计费头程计费需求确认表](入库测量与计费计费财务需求确认表.md) +- [入库测量与计费费用项目数据归属决策记录](入库测量与计费费用项目数据归属决策记录.md) +- [入库测量与计费产品待确认事项](入库测量与计费产品待确认事项.md) +- [入库测量与计费需求确认清单：产品与业务确认](入库测量与计费需求确认清单.md) + +## 数据库增量 + +可重复执行的测试库增量脚本位于： + +```text +D:\baiyue-firstleg\deploy\sql\头程数据库统一增量-MySQL8.sql +``` + +该文件是头程数据库唯一增量入口，后续数据库变更只追加到此文件。当前已包含订单与客户、入库测量与计费以及海外仓阶梯费用基础资料所需结构、索引和权限。历史日期脚本不再作为部署入口。 + +其中海外仓阶梯费用新增： + +- `wh_overseas_storage_fee_rule` +- `wh_overseas_storage_fee_tier` +- 5 个查询、唯一性和关联索引 +- 4 项平台端按钮权限及平台系统管理员默认授权 + +原入库测量与计费回归字段仍包含： + +- `fl_inbound_weight_result.created_by` +- `fl_inbound_weight_result.updated_by` +- `fl_inbound_pallet_allocation.warehouse_resource_tenant_id` diff --git a/二期/产品回传/2026-07-28-产品确认审核记录.md b/入库测量与计费/产品回传/2026-07-28-产品确认审核记录.md similarity index 69% rename from 二期/产品回传/2026-07-28-产品确认审核记录.md rename to 入库测量与计费/产品回传/2026-07-28-产品确认审核记录.md index 70874f0..d76f812 100644 --- a/二期/产品回传/2026-07-28-产品确认审核记录.md +++ b/入库测量与计费/产品回传/2026-07-28-产品确认审核记录.md @@ -1,11 +1,11 @@ -# 2026-07-28 二期产品确认回传审核记录 +# 2026-07-28 入库测量与计费产品确认回传审核记录 -> 回传原件：[2026-07-28-二期需求确认-产品回传.xlsx](2026-07-28-二期需求确认-产品回传.xlsx) +> 回传原件：[2026-07-28-入库测量与计费需求确认-产品回传.xlsx](2026-07-28-入库测量与计费需求确认-产品回传.xlsx) > 审核结论：暂不直接合并为正式需求基线 ## 一、确认口径 -二期由单一产品负责人统一确认，不要求填写产品跟进人、业务确认人和确认日期。回传文件中状态为“已确认”且已填写最终结论，即视为产品确认结果；状态为“暂缓”的项目需要明确二期临时处理方式。 +入库测量与计费由单一产品负责人统一确认，不要求填写产品跟进人、业务确认人和确认日期。回传文件中状态为“已确认”且已填写最终结论，即视为产品确认结果；状态为“暂缓”的项目需要明确入库测量与计费临时处理方式。 ## 二、需要产品补充澄清 @@ -17,17 +17,17 @@ | P2-Q4 | 重量体积（毛重/363）；总材积重（长×宽×高/6000）×箱数 | 单位、公式中 `/363` 的业务含义、计费重是否取毛重和材积重较大值、精度和舍入规则 | | P2-Q5 | 差异需客户确认 | 是否所有差异都确认；客户拒绝、超时未确认以及确认前货物能否上架/计费 | | P2-Q6 | 没有隔离单独的区域 | 差异未关闭时货物放哪里、系统是否使用“业务暂停”而不使用隔离库位、谁可以解除暂停 | -| P2-Q7 | 当前没有库位容量 | 二期是否完全不做容量校验；库位停用、占用和货物类型不匹配是否仍需拦截 | +| P2-Q7 | 当前没有库位容量 | 入库测量与计费是否完全不做容量校验；库位停用、占用和货物类型不匹配是否仍需拦截 | | P2-Q8 | 称重照片、测量照片上传 | 是否必传、每个箱件还是每个收货批次上传、允许的文件数量/大小和补传规则 | -| P2-Q9 | 暂缓 | 明确二期不接 PDA，并确定使用后台网页或响应式作业页 | +| P2-Q9 | 暂缓 | 明确入库测量与计费不接 PDA，并确定使用后台网页或响应式作业页 | | P2-Q10 | 暂缓 | 暂缓期间无预报货物是否拒收；如允许收货，需要临时认领和超期规则 | -| P2-Q11 | 保存 12 个月 | 从哪个时间点起算、到期删除还是归档、各类照片/联系方式/凭证是否采用同一期限 | +| P2-Q11 | 保存 12 个月 | 从哪个时间点起算、到期删除还是归档、各类照片/联系方式/凭证是否采用同订单与客户限 | ## 三、当前可保留的结论 - `P2-Q12`：标签打印设备为佳博 1324D 热敏标签打印机；标签纸、连接、驱动和指令协议仍需实机核验。 - `P2-Q8` 已明确需要称重照片和测量照片，可作为规则方向保留，必传粒度和附件限制补齐后再锁定。 -- `P2-Q9、P2-Q10` 可以保持“暂缓”，但必须给出二期临时处理规则，否则仍会阻塞对应开发任务。 +- `P2-Q9、P2-Q10` 可以保持“暂缓”，但必须给出入库测量与计费临时处理规则，否则仍会阻塞对应开发任务。 ## 四、下一步 diff --git a/入库测量与计费/产品回传/2026-07-28-入库测量与计费需求确认-产品回传.xlsx b/入库测量与计费/产品回传/2026-07-28-入库测量与计费需求确认-产品回传.xlsx new file mode 100644 index 0000000..70cbd54 Binary files /dev/null and b/入库测量与计费/产品回传/2026-07-28-入库测量与计费需求确认-产品回传.xlsx differ diff --git a/二期/产品回传/2026-07-31-产品确认合并记录.md b/入库测量与计费/产品回传/2026-07-31-产品确认合并记录.md similarity index 70% rename from 二期/产品回传/2026-07-31-产品确认合并记录.md rename to 入库测量与计费/产品回传/2026-07-31-产品确认合并记录.md index a484b19..8aa4b17 100644 --- a/二期/产品回传/2026-07-31-产品确认合并记录.md +++ b/入库测量与计费/产品回传/2026-07-31-产品确认合并记录.md @@ -1,26 +1,26 @@ -# 2026-07-31 二期产品确认合并记录 +# 2026-07-31 入库测量与计费产品确认合并记录 -> 原始回传：[2026-07-31-二期需求确认-产品回传-v1.xlsx](2026-07-31-二期需求确认-产品回传-v1.xlsx) -> 回传来源：WXWork 文件 `二期需求确认清单.xlsx` +> 原始回传：[2026-07-31-入库测量与计费需求确认-产品回传-v1.xlsx](2026-07-31-入库测量与计费需求确认-产品回传-v1.xlsx) +> 回传来源：WXWork 文件 `入库测量与计费需求确认清单.xlsx` > 原始文件 SHA-256：`841F976133F772BD52E085785C57D8BA90687CA07CC57B8009C71138F78C8563` -## 一、已合并到二期到仓基线 +## 一、已合并到入库测量与计费到仓基线 | 编号 | 产品结论 | 合并后的开发口径 | |---|---|---| | P2-Q1 | 以实际货物重量、体积为准 | 收货实测结果作为后续作业和头程计费输入；少货关闭规则按现有临时基线保留 | | P2-Q4 | 小数点三位向上取整 | 测量和计费中间结果保留原始值，展示/业务结果按三位向上取整；公式版本可追溯 | | P2-Q5 | 差异同步给客户，无需客户确认，只做记录 | 差异不再阻塞后续作业，不建设客户确认动作；保留差异记录、通知和审计 | -| P2-Q6 | 不考虑 | 二期不建设独立隔离区和隔离释放流程 | +| P2-Q6 | 不考虑 | 入库测量与计费不建设独立隔离区和隔离释放流程 | | P2-Q8 | 照片必传，大小不限制 | 称重照片、测量照片必传；产品未设置业务大小上限，系统仍保留可配置的技术安全上限和文件类型校验 | -| P2-Q10 | 不考虑，无此场景 | 二期不建设无预报货物认领流程；不预留正式订单绑定和计费入口 | +| P2-Q10 | 不考虑，无此场景 | 入库测量与计费不建设无预报货物认领流程；不预留正式订单绑定和计费入口 | | P2-Q11 | 永久保存 | 业务上不自动删除照片、凭证和测量记录；具体存储成本、合规删除和备份策略由运维另行制定 | ## 二、财务范围合并结论 -产品在本轮确认中明确：二期财务只做“头程计费”，不做后续财务闭环。 +产品在本轮确认中明确：入库测量与计费财务只做“头程计费”，不做后续财务闭环。 -### 二期纳入 +### 入库测量与计费纳入 - 头程费用项目维护。 - 头程计费规则、计费单位、价格版本和生效区间。 @@ -28,7 +28,7 @@ - 费用结果的人工补录、调整、审核、作废和审计留痕。 - 头程费用明细查询、订单关联、计算过程和规则快照。 -### 二期明确不纳入 +### 入库测量与计费明确不纳入 - 应收应付台账。 - 客户或供应商对账单、结算周期和账单确认。 @@ -37,7 +37,7 @@ - 汇率结算、利润、利润率和财务报表。 - 总账、会计凭证、在线支付和银企直连。 -这些模块的原型页面只作为后续阶段参考，不再进入二期开发任务、验收标准或进度统计。 +这些模块的原型页面只作为后续阶段参考，不再进入入库测量与计费开发任务、验收标准或进度统计。 ## 三、未合并内容 @@ -49,7 +49,7 @@ ## 四、合并后处理 -- 更新二期开发规划、计费规划、需求确认清单和开发进度表。 -- 从二期财务任务中移除应收应付、对账、付款、核销、发票和利润任务。 +- 更新入库测量与计费开发规划、计费规划、需求确认清单和开发进度表。 +- 从入库测量与计费财务任务中移除应收应付、对账、付款、核销、发票和利润任务。 - 将 P2-Q13 标记为“已确认：仅头程计费”，P2-Q14 至 P2-Q16 保持待确认。 - 产品原始回传只读归档，不覆盖；后续回传使用新版本文件名。 diff --git a/入库测量与计费/产品回传/2026-07-31-入库测量与计费需求确认-产品回传-v1.xlsx b/入库测量与计费/产品回传/2026-07-31-入库测量与计费需求确认-产品回传-v1.xlsx new file mode 100644 index 0000000..6854a0f Binary files /dev/null and b/入库测量与计费/产品回传/2026-07-31-入库测量与计费需求确认-产品回传-v1.xlsx differ diff --git a/二期/产品回传/README.md b/入库测量与计费/产品回传/README.md similarity index 53% rename from 二期/产品回传/README.md rename to 入库测量与计费/产品回传/README.md index 005346f..aad93c8 100644 --- a/二期/产品回传/README.md +++ b/入库测量与计费/产品回传/README.md @@ -1,11 +1,11 @@ -# 二期产品确认回传管理 +# 入库测量与计费产品确认回传管理 -本目录只保存产品原始回传文件，不直接作为正式开发进度表使用，也不覆盖 `docs/二期/虫虫出海二期开发进度表.xlsx`。 +本目录只保存产品原始回传文件，不直接作为正式开发进度表使用，也不覆盖 `docs/入库测量与计费/虫虫出海入库测量与计费开发进度表.xlsx`。 ## 文件命名 ```text -YYYY-MM-DD-二期需求确认-产品回传-vN.xlsx +YYYY-MM-DD-入库测量与计费需求确认-产品回传-vN.xlsx ``` ## 合并条件 @@ -16,13 +16,13 @@ YYYY-MM-DD-二期需求确认-产品回传-vN.xlsx - 例外情况、暂缓范围和临时处理规则明确。 - 与其他确认项不存在冲突。 -二期由单一产品负责人统一确认，不要求填写确认人、产品跟进人和确认日期。产品将状态设置为“已确认”即代表结论生效。 +入库测量与计费由单一产品负责人统一确认，不要求填写确认人、产品跟进人和确认日期。产品将状态设置为“已确认”即代表结论生效。 ## 合并流程 1. 原样保存产品回传文件，不在原件上二次修改。 2. 对比正式确认清单，形成回传审核记录。 3. 产品补充不完整或冲突的结论，并将状态设置为“已确认”或“暂缓”。 -4. 按 `P2-Qxx` 合并到 `二期需求确认清单.md`。 +4. 按 `P2-Qxx` 合并到 `入库测量与计费需求确认清单.md`。 5. 同步更新开发规划、开发任务、依赖、验收标准和 Excel 进度表。 -6. 合并前后的正式版本分别保存到 `docs/二期/版本归档/`。 +6. 合并前后的正式版本分别保存到 `docs/入库测量与计费/版本归档/`。 diff --git a/二期/二期V2需求确认清单.md b/入库测量与计费/入库测量与计费V2需求确认清单.md similarity index 74% rename from 二期/二期V2需求确认清单.md rename to 入库测量与计费/入库测量与计费V2需求确认清单.md index a2d04c0..56c1c52 100644 --- a/二期/二期V2需求确认清单.md +++ b/入库测量与计费/入库测量与计费V2需求确认清单.md @@ -1,42 +1,42 @@ -# 虫虫出海二期 V2 需求确认清单 +# 虫虫出海入库测量与计费 V2 需求确认清单 -> 创建日期：2026-08-03 -> 当前状态：待产品与业务确认 -> 确认对象：[二期需求优化版 V2：测量、计费、托盘入库闭环](二期需求优化版-v2-测量计费入库主流程.md) +> 创建日期：2026-08-03 +> 当前状态：待产品与业务确认 +> 确认对象：[入库测量与计费需求优化版 V2：测量、计费、托盘入库闭环](入库测量与计费需求优化版-v2-测量计费入库主流程.md) > 适用范围：头程订单审核通过后的测量、计费、托盘分配、库位占用和入库闭环 > 技术状态（2026-08-04）：任务 `019fc6f9-8dcf-74e1-bc68-d42f15d7802a` 已完成核心正常主链路开发和真实 API 回归。以下“产品确认状态”仍由产品/业务负责人填写，技术完成不自动等同于产品确认。 > 订单衔接规则更新（2026-08-07，已确认）：客户草稿不生成入仓码；客户提交进入待审核时立即生成并固定唯一入仓码。平台审核不以选择承运商为前置条件；审核通过后才创建可进入测量流程的正式入库单，并沿用提交时生成的入仓码。承运商可在后续履约或计费前补充。 -> 主体模型：二期只实现“平台—客户”两级；业务数据的 `tenant_id>0` 是客户隔离兼容字段，平台公共仓储资源归属 `tenant_id=0`。下表历史“资源租户”均指公共主数据技术归属，不代表真实租户。 +> 主体模型：入库测量与计费只实现“平台—客户”两级；业务数据的 `tenant_id>0` 是客户隔离兼容字段，平台公共仓储资源归属 `tenant_id=0`。下表历史“资源租户”均指公共主数据技术归属，不代表真实租户。 ## 一、使用说明 -- 本清单是二期 V2 的唯一会议确认入口。 +- 本清单是入库测量与计费 V2 的唯一会议确认入口。 - 产品只有一人，不填写确认人和确认时间，只填写“最终结论”和“状态”。 - 状态统一使用：`待确认`、`已确认`、`暂缓`。 - 认可当前建议时，可将当前建议直接复制为最终结论，并把状态改为“已确认”。 - 修改当前建议时，必须写清可直接转成页面、接口、状态、计算或验收规则的最终结论。 -- 暂时无法确定时，状态改为“暂缓”，同时填写二期临时处理方式。 +- 暂时无法确定时，状态改为“暂缓”，同时填写入库测量与计费临时处理方式。 - C1 至 C8 全部形成可开发结论后，V2 才能替换现有 24 项开发计划。 ## 二、产品与业务必须确认的 8 项 | 编号 | 需要确认的事项 | 当前建议 | 最终结论 | 状态 | |---|---|---|---|---| -| C1 | 是否正式采用 V2 作为二期唯一开发基线 | 采用“测量数据采集 → 测量审核 → 自动试算 → 人工确认 → 发送费用 → 托盘与库位占用 → 入库成功”主流程；确认后旧 24 项计划和第一份优化稿停止作为开发依据 | 待填写 | 待确认 | +| C1 | 是否正式采用 V2 作为入库测量与计费唯一开发基线 | 采用“测量数据采集 → 测量审核 → 自动试算 → 人工确认 → 发送费用 → 托盘与库位占用 → 入库成功”主流程；确认后旧 24 项计划和第一份优化稿停止作为开发依据 | 待填写 | 待确认 | | C2 | 长宽高和重量分别从哪里取得 | 长宽高由第三方测量设备按入仓码回传；重量由称重图片 OCR 识别，允许人工校正并保留 OCR 原值、修正值和修正原因 | 待填写 | 待确认 | | C3 | 测量审核失败是否允许继续计费和入库 | 默认禁止；仅在 Nacos 异常放行开关开启、操作人有专属权限且填写放行原因时允许继续；作废单、缺少费用快照或无可用库位始终禁止放行 | 待填写 | 待确认 | -| C4 | 二期计费结果的业务边界 | 二期只生成发送给客户的头程费用；船司价格只作为计价基础，不生成船司应付、成本、对账、收付款、核销、发票或利润数据 | 待填写 | 待确认 | +| C4 | 入库测量与计费计费结果的业务边界 | 入库测量与计费只生成发送给客户的头程费用；船司价格只作为计价基础，不生成船司应付、成本、对账、收付款、核销、发票或利润数据 | 待填写 | 待确认 | | C5 | KG/CBM 计费公式、换算系数和价格匹配维度 | 包税按 `体积 × 167` 转换为 KG 后与实重取大；不包税按 `重量 ÷ 363` 转换为 CBM 后与实测体积取大；`167`、`363` 按客户规则版本配置，不硬编码；价格按起运仓、渠道/计费类型、船司、FBA 目的仓和有效期唯一匹配 | 待填写 | 待确认 | -| C6 | 二期首批头程费用项目白名单 | 只纳入实际使用的基础运费和明确附加费；每项费用必须确认编码、名称、计费单位、币种、自动/人工、触发条件及是否允许人工调整 | 待填写 | 待确认 | -| C7 | 发送费用、入库成功及复核节点 | “发送费用给客户”作为二期完成节点：锁定费用快照、生成托盘分配、占用库位并将入库单改为已入库；默认不再增加独立接收审核或第二人复核 | 待填写 | 待确认 | -| C8 | 托盘拆分和库位占用规则 | 按实际总体积除以单托盘可用容积向上取整；二期默认一托一库位；托盘只分配体积和箱数汇总，不拆到 SKU；入库后换位作为 P1 独立功能 | 待填写 | 待确认 | +| C6 | 入库测量与计费首批头程费用项目白名单 | 只纳入实际使用的基础运费和明确附加费；每项费用必须确认编码、名称、计费单位、币种、自动/人工、触发条件及是否允许人工调整 | 待填写 | 待确认 | +| C7 | 发送费用、入库成功及复核节点 | “发送费用给客户”作为入库测量与计费完成节点：锁定费用快照、生成托盘分配、占用库位并将入库单改为已入库；默认不再增加独立接收审核或第二人复核 | 待填写 | 待确认 | +| C8 | 托盘拆分和库位占用规则 | 按实际总体积除以单托盘可用容积向上取整；入库测量与计费默认一托一库位；托盘只分配体积和箱数汇总，不拆到 SKU；入库后换位作为 P1 独立功能 | 待填写 | 待确认 | ## 三、C6 首批费用项目填写表 -没有实际业务的费用不要为了匹配原型而纳入二期。白名单之外的费用默认不能自动生成。 +没有实际业务的费用不要为了匹配原型而纳入入库测量与计费。白名单之外的费用默认不能自动生成。 | 费用编码 | 费用名称 | 计费单位 | 默认币种 | 自动/人工 | 单价来源 | 触发条件 | 是否允许调整 | 备注 | |---|---|---|---|---|---|---|---|---| @@ -56,10 +56,10 @@ | T2 | OCR 接入参数 | 确认 OCR 服务商、图片格式、单图技术上限、单批数量、识别时限、置信度阈值、公斤/磅识别、失败重试和人工校正规则；业务服务通过 `fileId` 调用，不传服务器目录 | 待填写 | 待确认 | | T3 | 托盘和库位基础资料 | 确认托盘编码规则、标准可用容积、仓库现有托盘数量、库位编码、可用状态及初始化数据；并发占位由数据库唯一约束或乐观锁保证 | 待填写 | 待确认 | -## 五、确认后形成的二期主流程 +## 五、确认后形成的入库测量与计费主流程 ```text -一期头程订单提交待审核 +订单与客户头程订单提交待审核 → 生成并固定唯一入仓码 → 平台审核通过（承运商不是审核前置条件） → 创建正式入库单并沿用该入仓码 @@ -76,7 +76,7 @@ → 异步发送客户通知 ``` -## 六、明确不纳入二期 +## 六、明确不纳入入库测量与计费 - 船司应付、供应商应付和应付审核。 - 客户或供应商对账单、结算周期和账单争议。 @@ -108,16 +108,16 @@ C1 至 C8 确认后，原 P2-Q14 至 P2-Q16 不再单独维护，避免形成两 ## 八、确认完成后的文档处理 1. 将本文件状态改为“已确认”。 -2. 将 [二期需求优化版 V2](二期需求优化版-v2-测量计费入库主流程.md) 标记为正式开发基线。 -3. 将 [二期需求优化版：原型对照](二期需求优化版-原型对照.md) 标记为历史版本，不再用于开发。 +2. 将 [入库测量与计费需求优化版 V2](入库测量与计费需求优化版-v2-测量计费入库主流程.md) 标记为正式开发基线。 +3. 将 [入库测量与计费需求优化版：原型对照](入库测量与计费需求优化版-原型对照.md) 标记为历史版本，不再用于开发。 4. 用 V2 的 13 项任务替换现有 24 项开发计划，并同步 Markdown 和 Excel 进度表。 5. 将 C1 至 C8 的结论转换为状态、接口、数据表、权限、异常和验收规则。 6. 将 T1 至 T3 分配给技术、仓库和供应商负责人，在对应开发任务开始前补齐。 -7. 后续新增应收应付、对账、收付款、发票或利润时，必须另行立项，不得直接扩入二期。 +7. 后续新增应收应付、对账、收付款、发票或利润时，必须另行立项，不得直接扩入入库测量与计费。 ## 九、进入开发排期的完成标准 -- C1 至 C8 均为“已确认”，或“暂缓”但已写明二期可执行的临时处理方式。 +- C1 至 C8 均为“已确认”，或“暂缓”但已写明入库测量与计费可执行的临时处理方式。 - C6 至少形成一版可初始化的费用项目白名单。 - 计费公式、换算系数、唯一匹配维度和费用发送节点可以转为自动化测试。 - 托盘数量、库位占用和并发冲突规则可以转为数据库约束和接口验收。 @@ -131,7 +131,7 @@ C1 至 C8 确认后，原 P2-Q14 至 P2-Q16 不再单独维护，避免形成两 | C1 主链路 | 已完成正常链路 | 下单、审核、测量、称重、计费、费用发送、托盘库位、入库已通过真实 API | | C2 测量与重量来源 | 已实现 | 第三方/平台箱规明细、图片证据、OCR 失败人工修正与确认已验证 | | C3 审核失败放行 | 已实现配置和权限边界 | Nacos 开关默认关闭；正常审核通过链路已验证 | -| C4 计费边界 | 已按二期范围实现 | 仅生成客户头程费用，不扩展应付、对账、核销、发票和利润 | +| C4 计费边界 | 已按入库测量与计费范围实现 | 仅生成客户头程费用，不扩展应付、对账、核销、发票和利润 | | C5 KG/CBM 规则 | 已实现并验证样本 | 实重 `20kg`、体积重 `40.08kg`，取 `40.08kg` 计费 | | C6 费用项目白名单 | 技术能力已具备，业务内容待确认 | 本轮使用测试价格 `11 CNY/kg`，不能代替正式费用白名单 | | C7 费用发送与入库节点 | 已实现 | 审核通过后自动生成费用 `440.68 CNY`，最终 `SENT + INBOUNDED` | @@ -140,4 +140,4 @@ C1 至 C8 确认后，原 P2-Q14 至 P2-Q16 不再单独维护，避免形成两 | T2 OCR 参数 | 降级链路已验证，真实供应商待接入 | 本地 OCR 未配置，已验证失败后人工修正继续入库 | | T3 托盘库位基础资料 | 已实现并通过 API 创建 | 当前公共主数据技术归属规则为 `tenant_id=0`，分配状态 `CONFIRMED`；`10001` 不再作为公共资源归属 | -完整接口与回归证据见 [二期前端联调报告（2026-08-04）](二期前端联调报告-2026-08-04.md)。 +完整接口与回归证据见 [入库测量与计费前端联调报告（2026-08-04）](入库测量与计费前端联调报告-2026-08-04.md)。 diff --git a/二期/二期产品待确认事项.md b/入库测量与计费/入库测量与计费产品待确认事项.md similarity index 76% rename from 二期/二期产品待确认事项.md rename to 入库测量与计费/入库测量与计费产品待确认事项.md index e845fe2..de11434 100644 --- a/二期/二期产品待确认事项.md +++ b/入库测量与计费/入库测量与计费产品待确认事项.md @@ -1,15 +1,15 @@ -# 虫虫出海二期产品待确认事项 +# 虫虫出海入库测量与计费产品待确认事项 -> 更新日期：2026-07-31 -> 适用范围：头程物流“02 到仓”及头程计费 -> 正式状态以 [二期需求确认清单](二期需求确认清单.md) 为准。 +> 更新日期：2026-07-31 +> 适用范围：头程物流“02 到仓”及头程计费 +> 正式状态以 [入库测量与计费需求确认清单](入库测量与计费需求确认清单.md) 为准。 > 产品只有一人，不需要填写确认人和确认时间；会议只填写最终结论和状态。 ## 一、会议结论摘要 -- 产品已确认到仓作业规则及二期“只做头程计费”的范围。 +- 产品已确认到仓作业规则及入库测量与计费“只做头程计费”的范围。 - 当前只需确认 P2-Q14、P2-Q15、P2-Q16，共 3 项。 -- P2-Q17 至 P2-Q24 对应应收应付、对账、收付款、核销、发票、汇率结算和利润能力，均不纳入二期。 +- P2-Q17 至 P2-Q24 对应应收应付、对账、收付款、核销、发票、汇率结算和利润能力，均不纳入入库测量与计费。 - 产品回传中 Q14 至 Q16 的“63”没有业务含义，本次会议需要重新填写。 ## 二、本次会议需要确认的 3 项 @@ -22,7 +22,7 @@ ## 三、P2-Q14 首批费用项目填写模板 -没有实际业务的费用不要为了匹配原型而纳入二期。 +没有实际业务的费用不要为了匹配原型而纳入入库测量与计费。 | 费用编码 | 费用名称 | 费用性质 | 计费对象 | 计费单位 | 默认币种 | 默认税率 | 自动/人工 | 触发节点 | |---|---|---|---|---|---|---|---|---| @@ -30,7 +30,7 @@ ## 四、已确认，无需再次询问 -| 编号 | 产品结论 | 二期开发口径 | +| 编号 | 产品结论 | 入库测量与计费开发口径 | |---|---|---| | P2-Q1 | 以实际货物重量、体积为准 | 实测结果作为后续作业和头程计费输入 | | P2-Q2 | 不做系统服务商调度 | 线下安排取货，系统记录结果 | @@ -43,14 +43,14 @@ | P2-Q10 | 不考虑无预报货物 | 不建设无预报认领和正式订单绑定流程 | | P2-Q11 | 永久保存 | 业务记录不自动删除；运维补充备份和合规策略 | | P2-Q12 | 使用佳博 1324D 热敏标签打印机 | 开发前核验纸张、连接、驱动和指令协议 | -| P2-Q13 | 二期只做头程计费 | 不生成应收、应付、账单、付款、核销、发票或利润数据 | +| P2-Q13 | 入库测量与计费只做头程计费 | 不生成应收、应付、账单、付款、核销、发票或利润数据 | -P2-Q9 暂缓：二期不接 PDA，使用后台或响应式作业页。 +P2-Q9 暂缓：入库测量与计费不接 PDA，使用后台或响应式作业页。 ## 五、确认后的处理 1. 将 Q14 至 Q16 的最终结论和状态回写正式需求确认清单。 2. 技术审核结论是否足以转为字段、状态、计算、权限、异常和验收规则。 -3. 同步更新二期开发规划、头程计费规划、开发进度表和 Excel。 +3. 同步更新入库测量与计费开发规划、头程计费规划、开发进度表和 Excel。 4. 保留产品原始回传和本次会议版本；后续修改用新版本，不覆盖历史文件。 diff --git a/二期/二期前端联调报告-2026-08-04.md b/入库测量与计费/入库测量与计费前端联调报告-2026-08-04.md similarity index 96% rename from 二期/二期前端联调报告-2026-08-04.md rename to 入库测量与计费/入库测量与计费前端联调报告-2026-08-04.md index 75adb5a..304a6be 100644 --- a/二期/二期前端联调报告-2026-08-04.md +++ b/入库测量与计费/入库测量与计费前端联调报告-2026-08-04.md @@ -1,4 +1,4 @@ -# 二期入库测量、计费与入库前端联调报告 +# 入库测量、计费与入库前端联调报告 > 版本日期：2026-08-04 > 后端仓库：`D:\baiyue-firstleg` @@ -9,7 +9,7 @@ ## 一、联调结论 -二期后端主流程、平台测量、OCR 重量、客服审核、FBA 计费、费用发布、入库完成、库位和托盘维护、客户只读查询、第三方测量回传接口均已形成代码闭环。 +入库测量与计费后端主流程、平台测量、OCR 重量、客服审核、FBA 计费、费用发布、入库完成、库位和托盘维护、客户只读查询、第三方测量回传接口均已形成代码闭环。 最终正常业务流程是： @@ -75,7 +75,7 @@ Swagger 分组： | 7 | `firstleg-service` | 9202 | 入库、测量、审核和计费主流程 | | 8 | `gateway` | 9000 | 前端统一入口和聚合文档 | -若登录或订单前置流程依赖其他一期服务，应在 Firstleg 前启动。前端业务请求统一走网关，不要将各服务端口写死到页面。 +若登录或订单前置流程依赖其他订单与客户服务，应在 Firstleg 前启动。前端业务请求统一走网关，不要将各服务端口写死到页面。 ## 三、全局请求与响应约定 @@ -413,7 +413,7 @@ DELETE /api/platform/v1/fba-pricing/carrier-rates/{id} } ``` -当前平台托盘 DTO 只返回主数据，不暴露内部 `AVAILABLE / RESERVED / OCCUPIED` 状态；也没有单独的托盘启停或状态筛选 API。页面本期只实现查询、新增、编辑、删除。已预占或占用托盘删除会被后端拒绝。这是当前明确的接口边界，不要自行猜测状态路径。 +当前平台托盘 DTO 只返回主数据，不暴露内部 `AVAILABLE / RESERVED / OCCUPIED` 状态；也没有单独的托盘启停或状态筛选 API。页面当前只实现查询、新增、编辑、删除。已预占或占用托盘删除会被后端拒绝。这是当前明确的接口边界，不要自行猜测状态路径。 ## 十一、商户端只读接口 @@ -486,7 +486,7 @@ image：该条箱规唯一对应的 JPG/PNG/BMP 图片，最大 5 MB ## 十三、推荐前端联调顺序 1. 验证平台登录、刷新 Token、退出、过期会话、401 和 403。 -2. 给测试角色同步二期权限，确认按钮显示与后端权限码一致。 +2. 给测试角色同步入库测量与计费权限，确认按钮显示与后端权限码一致。 3. 初始化启用仓库、至少一个托盘、足量可用库位、客户计费规则和船司 FBA 费率。 4. 创建或准备一条已进入待测量状态的真实入库单。 5. 调用入库列表和详情，核对 Long ID 均按字符串处理。 @@ -558,12 +558,12 @@ D:\apache-maven-3.8.8\bin\mvn.cmd clean test -pl order,firstleg,warehouse,file,i 本次回归没有启动服务、没有占用 `9000/9100/920x` 默认端口，也没有连接或修改 MySQL。以下内容必须在测试环境由后端与前端共同验证后，才能判定上线验收通过： -1. 二期 SQL 在真实 MySQL 的建表/迁移执行，以及历史数据与唯一约束冲突检查。 +1. 入库测量与计费 SQL 在真实 MySQL 的建表/迁移执行，以及历史数据与唯一约束冲突检查。 2. Gateway、Nacos、Redis、MySQL、服务间令牌和各微服务的真实 HTTP 联通。 3. OCR 引擎对现场秤图的识别准确率、超时和失败重试。 4. 并发提交、并发抢托盘/库位、A0 多托盘共享在真实数据库事务下的压力验证。 5. 浏览器端完整登录、刷新 Token、权限按钮、403、跨客户拒绝、空态、加载态和重复提交体验。 -6. 当前托盘管理没有独立启停和状态筛选接口；本期页面只做查询、新增、编辑、删除。 +6. 当前托盘管理没有独立启停和状态筛选接口；页面只做查询、新增、编辑、删除。 上述内容是本报告初版时的阶段结论。2026-08-04 已继续完成真实数据库迁移和隔离端口在线 HTTP 回归，最终结论以第十七章为准。 @@ -624,4 +624,4 @@ D:\apache-maven-3.8.8\bin\mvn.cmd clean test -pl order,firstleg,warehouse,file,i - 浏览器端视觉、移动端适配和真实用户操作体验仍由前端按本报告接口完成联调验收。 - 数据库唯一增量入口：`D:\baiyue-firstleg\deploy\sql\头程数据库统一增量-MySQL8.sql`。后续变更只追加到该文件，历史日期脚本不再作为部署入口。 -最终结论：**二期核心正常主链路已经完成真实 MySQL、真实 HTTP 和自动化回归，后端达到前端联调条件；真实 OCR 供应商识别和浏览器端体验属于后续环境验收项。** +最终结论：**入库测量与计费核心正常主链路已经完成真实 MySQL、真实 HTTP 和自动化回归，后端达到前端联调条件；真实 OCR 供应商识别和浏览器端体验属于后续环境验收项。** diff --git a/二期/二期前端页面清单与多对话并行任务表.md b/入库测量与计费/入库测量与计费前端页面清单与多对话并行任务表.md similarity index 95% rename from 二期/二期前端页面清单与多对话并行任务表.md rename to 入库测量与计费/入库测量与计费前端页面清单与多对话并行任务表.md index aebd20c..19b6221 100644 --- a/二期/二期前端页面清单与多对话并行任务表.md +++ b/入库测量与计费/入库测量与计费前端页面清单与多对话并行任务表.md @@ -1,4 +1,4 @@ -# 二期前端页面清单与多对话并行任务表 +# 入库测量与计费前端页面清单与多对话并行任务表 > 盘点日期：2026-08-05 > 适用项目：`apps/admin-web/`、`apps/client-web/` @@ -11,7 +11,7 @@ ## 一、结论 -二期前端应围绕已经落地的“入库测量、OCR、测量审核、FBA 计费、托盘库位、客户只读结果”建设，不继续沿用旧 24 项计划直接开工。 +入库测量与计费前端应围绕已经落地的“入库测量、OCR、测量审核、FBA 计费、托盘库位、客户只读结果”建设，不继续沿用旧 24 项计划直接开工。 - Admin 新增 6 个正式菜单页面：入库单、客户计费规则、船司 FBA 价格、库位管理、托盘管理、海外仓阶梯费用。 - 入库详情承载测量/OCR、审核、费用快照、托盘库位结果和历史，不再新增独立“接收审核”页面。 @@ -25,7 +25,7 @@ 1. 用户本轮要求：只整理和开发前端，不修改后端，可以直接只读后端代码。 2. 后端真实 Controller、DTO、权限 SQL、状态枚举和服务编排。 -3. `二期需求优化版-v2-测量计费入库主流程.md` 的范围边界。 +3. `入库测量与计费需求优化版-v2-测量计费入库主流程.md` 的范围边界。 4. Admin 原型仅用于布局、字段和交互参考，不补造后端没有的业务能力。 已确认的实现差异： @@ -70,10 +70,10 @@ ### 3.3 全局装配变更 -- `src/app/router/index.ts`：装配二期模块路由。 +- `src/app/router/index.ts`：装配入库测量与计费模块路由。 - `src/core/navigation/adminNavigation.ts`：在“国内仓”下增加入库单、库位、托盘；新增“头程计费”分组；在客户或海外仓基础资料分组增加“海外仓阶梯费用”。 - 路由和导航测试同步更新。 -- IAM 权限页面无需业务改造；后端返回二期权限资源后沿用现有展示和授权能力。 +- IAM 权限页面无需业务改造；后端返回入库测量与计费权限资源后沿用现有展示和授权能力。 - 不恢复“接收审核”“费用项目”“完整财务管理”等原型菜单。 ## 四、Client 页面变更清单 @@ -130,8 +130,8 @@ Client 只修改现有 `FirstLegOrdersView.vue` 的订单详情抽屉，新增 - 新增 `P2-ADM-12` 海外仓阶梯费用前端任务：后端接口、权限和 SQL 已完成，前端页面待实现与联调。 - Admin 已通过 `pnpm test`（58 个文件、262 个测试）、`pnpm typecheck` 和 `pnpm build`。 - Client 已通过 `pnpm test`（135 个测试）、`pnpm typecheck` 和 `pnpm build`。 -- Admin 二期新增模块的 Impeccable detector 结果为 `[]`，模块依赖边界测试已通过。 -- Admin 二期页面已再次按平台后台原型校正搜索条件、表格字段、字段顺序和详情分区；视觉组件统一复用现有 `QueryToolbar`、`DataTable`、`AppDrawer` 及状态组件。 +- Admin 入库测量与计费新增模块的 Impeccable detector 结果为 `[]`，模块依赖边界测试已通过。 +- Admin 入库测量与计费页面已再次按平台后台原型校正搜索条件、表格字段、字段顺序和详情分区；视觉组件统一复用现有 `QueryToolbar`、`DataTable`、`AppDrawer` 及状态组件。 - 原型字段只在当前后端 Controller/DTO 支持时落地；未恢复接收审核、客户确认、报关、智能装柜、托盘状态/启停、尺寸/承重及无接口的导入导出。 - Client 入库费用区沿用既有订单详情视觉，补充换算系数、舍入精度和规则/价格版本，保持只读并继续使用“入仓码”业务术语。 - 本轮未修改 `baiyue-firstleg/`；8.1 节的 Client 服务端响应数据暴露风险仍是上线阻断，不影响本轮前端任务完成状态。 diff --git a/二期/二期开发规划.md b/入库测量与计费/入库测量与计费开发规划.md similarity index 88% rename from 二期/二期开发规划.md rename to 入库测量与计费/入库测量与计费开发规划.md index edd1b82..f4b3ccb 100644 --- a/二期/二期开发规划.md +++ b/入库测量与计费/入库测量与计费开发规划.md @@ -1,17 +1,17 @@ -# 虫虫出海二期开发规划：头程到仓与头程计费 +# 虫虫出海入库测量与计费开发规划：头程到仓与头程计费 > 创建日期：2026-07-28 > 更新日期：2026-07-31 > 状态：开发已启动，3 项计费细节确认中 > 流程依据：[头程物流流程图](参考资料/头程物流流程图.svg)中的头程物流“02 到仓” > 产品确认：[2026-07-31 产品确认合并记录](产品回传/2026-07-31-产品确认合并记录.md) -> 前置阶段：[一期文档](../一期/README.md) +> 前置阶段：[订单与客户文档](../订单与客户/README.md) -> 主体模型：二期只实现“平台—客户”两级。`tenant_id > 0` / `tenantId` 是客户 ID 兼容字段，`tenant_id=0` 是平台技术作用域；不得新增真实租户、租户选择器、租户级 RBAC 或重定义现有隔离字段。 +> 主体模型：入库测量与计费只实现“平台—客户”两级。`tenant_id > 0` / `tenantId` 是客户 ID 兼容字段，`tenant_id=0` 是平台技术作用域；不得新增真实租户、租户选择器、租户级 RBAC 或重定义现有隔离字段。 -## 一、二期目标 +## 一、入库测量与计费目标 -二期承接一期“客户下单并选择平台收货仓”的结果，完成货物从待到仓、实际收货、测量、差异记录到指定库位的作业闭环，并在实测数据之上完成头程费用计算。 +入库测量与计费承接订单与客户“客户下单并选择平台收货仓”的结果，完成货物从待到仓、实际收货、测量、差异记录到指定库位的作业闭环，并在实测数据之上完成头程费用计算。 ```text 线下预约 / 送货预报 @@ -27,11 +27,11 @@ 头程费用试算与费用明细确认 ``` -二期不建设应收应付、对账、收付款、核销、发票、利润或总账。完成标准是每票货能够回答：何时到仓、实际收到什么、实测结果是什么、与申报差多少、差异是否已通知、最终放在哪个库位，以及产生了哪些头程费用和计算依据。 +入库测量与计费不建设应收应付、对账、收付款、核销、发票、利润或总账。完成标准是每票货能够回答：何时到仓、实际收到什么、实测结果是什么、与申报差多少、差异是否已通知、最终放在哪个库位，以及产生了哪些头程费用和计算依据。 ## 二、阶段边界 -### 纳入二期 +### 纳入入库测量与计费 - 客户取货或送货预报，以及线下预约结果、改期和取消记录。 - 平台收货仓到仓签到、分批收货、处理单元标签和收货冲正。 @@ -41,7 +41,7 @@ - 头程费用项目、计费规则版本、费用试算、人工费用、调整、确认和费用明细。 - 服务端权限、基于兼容字段 `tenant_id` 的客户隔离、状态、幂等、并发、文件鉴权、审计和历史快照。 -### 明确不纳入二期 +### 明确不纳入入库测量与计费 - 应收应付台账、客户/供应商对账、账单确认和争议。 - 收款、付款、退款、核销、反核销、银行流水和在线支付。 @@ -49,7 +49,7 @@ - 会计科目、会计凭证和总账。 - 流程图头程“03 出仓”：智能排柜、订舱、拖车、PDA 拣货、装柜、报关和港务信息。 - 完整 WMS：可用库存、库存成本、常规移库、盘点、冻结、拣货、复核和出库。 -- PDA 硬件或厂商 SDK；二期使用后台或响应式作业页。 +- PDA 硬件或厂商 SDK；入库测量与计费使用后台或响应式作业页。 - 独立隔离区、差异等待客户确认、无预报货物认领和待认领区。 - 时间窗容量调度、自动服务商分配、地图、GPS 和外部承运商接口。 - FBA/海外目的仓及尾程到港、到仓、出仓和签收流程。 @@ -66,11 +66,11 @@ | P2-Q6 | 不考虑隔离区 | 不建设隔离库位、隔离上架和释放流程 | | P2-Q7 | 不做库位容量校验 | 仅校验库位启停、仓库归属和权限合法性 | | P2-Q8 | 称重、测量照片必传，大小不限制 | 产品不设业务大小上限；系统保留文件类型校验和可配置技术安全上限 | -| P2-Q9 | PDA 暂缓 | 二期使用后台或响应式作业页 | +| P2-Q9 | PDA 暂缓 | 入库测量与计费使用后台或响应式作业页 | | P2-Q10 | 不考虑无预报货物 | 不建设无预报认领和正式订单绑定流程 | | P2-Q11 | 永久保存 | 业务记录不自动删除；访问审计、备份和合规策略由运维补充 | | P2-Q12 | 佳博 1324D 热敏标签打印机 | 开发前实机核验纸张、连接、驱动和指令协议 | -| P2-Q13 | 二期只做头程计费 | 费用结果不自动形成应收、应付、账单或收付款数据 | +| P2-Q13 | 入库测量与计费只做头程计费 | 费用结果不自动形成应收、应付、账单或收付款数据 | ## 四、角色与数据边界 @@ -125,7 +125,7 @@ ### 6. 库位与上架 - 维护仓库、库区、库位编码、名称、状态和权限范围。 -- 二期不做承重、箱数或体积容量校验，也不建设隔离区和待认领区。 +- 入库测量与计费不做承重、箱数或体积容量校验，也不建设隔离区和待认领区。 - 上架任务关联收货批次、目标库位、执行人、状态和完成时间。 - 上架完成后写入处理单元当前位置和历史位置，为后续出仓提供输入。 @@ -136,7 +136,7 @@ - 头程订单、到仓实测或已确认业务事件触发费用试算，重复事件不得重复计费。 - 支持自动费用、人工补录、调整、确认、作废、查询和导出。 - 已确认费用不直接覆盖，变更通过调整记录留痕。 -- 详细规则见 [二期头程计费模块规划](二期计费财务模块规划.md)。 +- 详细规则见 [入库测量与计费头程计费模块规划](入库测量与计费计费财务模块规划.md)。 ## 六、状态模型 @@ -203,7 +203,7 @@ - 创建取货或送货预报。 - 查看预约结果、到仓时间线、实测、公开照片、差异通知和上架结果。 -- 如二期客户端展示头程费用，只显示本企业公开费用，不显示内部备注和其他企业数据。 +- 如入库测量与计费客户端展示头程费用，只显示本企业公开费用，不显示内部备注和其他企业数据。 ### 国内头程后端 `baiyue-firstleg/` @@ -216,7 +216,7 @@ | 里程碑 | 交付目标 | 进入条件 | |---|---|---| -| P2-M0 规则锁定 | 到仓契约、测量口径、头程计费边界和权限基线确认 | 一期订单及基础资料契约稳定 | +| P2-M0 规则锁定 | 到仓契约、测量口径、头程计费边界和权限基线确认 | 客户订单及基础资料契约稳定 | | P2-M1 到仓预报 | 取货/送货预报及线下预约结果可记录 | 收货仓 API 可用 | | P2-M2 到仓收货 | 签到、分批收货、标签、照片和冲正可追溯 | 文件服务和仓库权限可用 | | P2-M3 测量差异 | 原始测量、三位向上取整、差异记录和通知可用 | 测量公式可用 | @@ -228,7 +228,7 @@ | ID | 端 | 模块 | 交付内容 | 优先级 | 依赖 | |---|---|---|---|---|---| -| P2-BASE-01 | 公共 | 到仓契约 | 状态、枚举、权限、事件、错误码和快照模型 | P0 | 一期订单契约 | +| P2-BASE-01 | 公共 | 到仓契约 | 状态、枚举、权限、事件、错误码和快照模型 | P0 | 客户订单契约 | | P2-BASE-02 | 公共 | 数据模型 | 到仓单、批次、处理单元、标签、测量、差异、库位、位置、费用和审计 | P0 | P2-BASE-01 | | P2-ADM-01 | 后台 | 到仓列表 | 查询、筛选、分页、详情、空态和异常态 | P0 | P2-BASE-01 | | P2-ADM-02 | 后台 | 预约结果 | 记录、调整和取消线下预约结果 | P0 | P2-ADM-01 | @@ -253,7 +253,7 @@ | P2-TEST-01 | 公共 | 自动化测试 | 越权、幂等、测量舍入、计费复算、标签、差异、位置、文件和审计 | P0 | 所有 P0 模块 | | P2-REL-01 | 公共 | 发布验收 | 初始化仓库、库位、测量规则、标签和费用基础数据，联调、验收和发布 | P0 | P2-TEST-01 | -二期开发任务共 24 项。应收应付、对账、账单中心、收付款核销、发票和利润六项任务已根据产品确认从二期移除。 +入库测量与计费开发任务共 24 项。应收应付、对账、账单中心、收付款核销、发票和利润六项任务已根据产品确认从入库测量与计费移除。 ## 十一、测试与验收重点 @@ -278,7 +278,7 @@ | P2-Q15 | 计费维度、阶梯价、最低收费、封顶、组合价和优先级 | 先支持客户、往来单位、仓库、服务和生效区间 | | P2-Q16 | 费用试算、生成、确认、调整和作废节点 | 实测完成试算，其他费用按已确认业务事件生成 | -回传中的“63”不作为业务结论。P2-Q13 已确认仅做头程计费；P2-Q17 至 P2-Q24 不纳入二期。 +回传中的“63”不作为业务结论。P2-Q13 已确认仅做头程计费；P2-Q17 至 P2-Q24 不纳入入库测量与计费。 ## 十三、建议实施顺序 diff --git a/二期/二期开发进度表.md b/入库测量与计费/入库测量与计费开发进度表.md similarity index 88% rename from 二期/二期开发进度表.md rename to 入库测量与计费/入库测量与计费开发进度表.md index c3df208..24d7b85 100644 --- a/二期/二期开发进度表.md +++ b/入库测量与计费/入库测量与计费开发进度表.md @@ -1,11 +1,11 @@ -# 虫虫出海二期开发进度表：到仓与头程计费 +# 虫虫出海入库测量与计费开发进度表：到仓与头程计费 > 创建日期：2026-07-28 > 更新日期：2026-07-31 > 当前阶段：开发已启动，需求确认并行 > 总体状态：到仓规则和范围已确认，3 项计费细节待补充；实际开发进度待负责人回填 -二期严格以头程物流“02 到仓”和头程计费为范围。范围依据见 [二期开发规划](二期开发规划.md)，确认结论见 [二期需求确认清单](二期需求确认清单.md)。原型只用于页面、字段和流程参考，不自动扩大二期范围。 +入库测量与计费严格以头程物流“02 到仓”和头程计费为范围。范围依据见 [入库测量与计费开发规划](入库测量与计费开发规划.md)，确认结论见 [入库测量与计费需求确认清单](入库测量与计费需求确认清单.md)。原型只用于页面、字段和流程参考，不自动扩大入库测量与计费范围。 ## 零、2026-08-05 增量状态 @@ -19,16 +19,16 @@ ## 一、进度口径 - 开发任务共 24 项；未收到具体完成量、负责人和日期前，不虚填开发进度。 -- 需求问题共 24 项：已确认 12 项、暂缓 1 项、待确认 3 项、不纳入二期 8 项。 +- 需求问题共 24 项：已确认 12 项、暂缓 1 项、待确认 3 项、不纳入入库测量与计费 8 项。 - 当前会议只需处理 P2-Q14、P2-Q15、P2-Q16。 -- P2-Q9 暂缓，二期不接 PDA；P2-Q17 至 P2-Q24 不纳入二期。 +- P2-Q9 暂缓，入库测量与计费不接 PDA；P2-Q17 至 P2-Q24 不纳入入库测量与计费。 - 应收应付、对账、收付款、核销、发票、汇率结算、利润和总账不进入任务、排期和验收。 ## 二、总体进度 | 工作流 | 范围 | 状态 | 开发进度 | 需求状态 | 负责人 | 备注 | |---|---|---|---:|---|---|---| -| 规则与数据 | 到仓契约、数据模型、权限、文件和审计 | 待开始 | 0% | 到仓规则已确认 | 待分配 | 一期订单及基础资料契约是前置依赖 | +| 规则与数据 | 到仓契约、数据模型、权限、文件和审计 | 待开始 | 0% | 到仓规则已确认 | 待分配 | 客户订单及基础资料契约是前置依赖 | | 到仓预报 | 取货/送货预报和线下预约结果记录 | 待开始 | 0% | Q2、Q3 已确认 | 待分配 | 不做容量调度和系统服务商分配 | | 到仓收货 | 签到、分批收货、标签、照片、异常和冲正 | 待开始 | 0% | Q1、Q8、Q10、Q12 已确认 | 待分配 | 不建设无预报认领流程 | | 测量差异 | 实测、三位向上取整、差异记录和客户通知 | 待开始 | 0% | Q4、Q5、Q6 已确认 | 待分配 | 差异无需客户确认，不阻塞上架或计费 | @@ -40,7 +40,7 @@ | ID | 里程碑 | 端 | 模块 | 功能/交付内容 | 优先级 | 状态 | 进度 | 原型覆盖 | 需求阻塞 | 依赖 | 负责人 | 计划开始 | 计划完成 | 备注 | |---|---|---|---|---|---|---|---:|---|---|---|---|---|---|---| -| P2-BASE-01 | P2-M0 | 公共 | 到仓契约 | 状态、枚举、权限、事件、错误码和快照模型 | P0 | 待开始 | 0% | 部分 | - | 一期订单契约 | 待分配 | 待排期 | 待排期 | 按已确认到仓规则建设 | +| P2-BASE-01 | P2-M0 | 公共 | 到仓契约 | 状态、枚举、权限、事件、错误码和快照模型 | P0 | 待开始 | 0% | 部分 | - | 客户订单契约 | 待分配 | 待排期 | 待排期 | 按已确认到仓规则建设 | | P2-BASE-02 | P2-M0 | 公共 | 数据模型 | 到仓单、批次、处理单元、标签、测量、差异、库位、位置、费用和审计 | P0 | 待开始 | 0% | 部分 | - | P2-BASE-01 | 待分配 | 待排期 | 待排期 | 不包含后续财务对象 | | P2-ADM-01 | P2-M1 | 后台 | 到仓列表 | 查询、筛选、分页、详情、空态和异常态 | P0 | 待开始 | 0% | 较完整 | - | P2-BASE-01 | 待分配 | 待排期 | 待排期 | 后台原型可参考 | | P2-ADM-02 | P2-M1 | 后台 | 预约结果 | 记录、调整和取消线下预约结果 | P0 | 待开始 | 0% | 部分 | - | P2-ADM-01 | 待分配 | 待排期 | 待排期 | 不建设容量调度和自动分配 | @@ -55,7 +55,7 @@ | P2-HOLD-01 | P2-M3 | 公共 | 异常记录 | 非差异类异常、责任人、证据、处理结果和审计 | P1 | 待开始 | 0% | 部分 | - | P2-BASE-02 | 待分配 | 待排期 | 待排期 | 不建设隔离区或差异暂停 | | P2-LOC-01 | P2-M4 | 后台 | 库位维护 | 库区、库位编码、状态和权限范围 | P0 | 待开始 | 0% | 较完整 | - | P2-BASE-02 | 待分配 | 待排期 | 待排期 | 不做容量校验 | | P2-PUT-01 | P2-M4 | 后台 | 上架任务 | 创建、分配、拆分、异常和完成 | P0 | 待开始 | 0% | 较完整 | - | P2-LOC-01、P2-WH-02 | 待分配 | 待排期 | 待排期 | 不做隔离上架 | -| P2-POS-01 | P2-M4 | 公共 | 位置记录 | 处理单元当前位置和进入/移出历史 | P0 | 待开始 | 0% | 部分 | - | P2-PUT-01 | 待分配 | 待排期 | 待排期 | 二期不建设完整库存系统 | +| P2-POS-01 | P2-M4 | 公共 | 位置记录 | 处理单元当前位置和进入/移出历史 | P0 | 待开始 | 0% | 部分 | - | P2-PUT-01 | 待分配 | 待排期 | 待排期 | 入库测量与计费不建设完整库存系统 | | P2-SEC-01 | P2-M0 | 公共 | 文件与保留 | 文件鉴权、类型/安全校验、访问审计、永久保存和备份边界 | P0 | 待开始 | 0% | 无 | - | P2-WH-01 | 待分配 | 待排期 | 待排期 | 产品不设业务大小上限 | | P2-TIME-01 | P2-M6 | 公共 | 时间线通知 | 对客事件、差异通知和失败补偿记录 | P1 | 待开始 | 0% | 部分 | - | 核心流程完成 | 待分配 | 待排期 | 待排期 | 外部通知渠道另行配置 | | P2-FEE-01 | P2-M5 | 后台 | 费用项目 | 头程费用项目、单位、币种、税务属性和启停 | P0 | 需求确认中 | 0% | 较完整 | Q14 | P2-BASE-01 | 待分配 | 待排期 | 待排期 | 仅头程费用白名单 | @@ -69,7 +69,7 @@ | 里程碑 | 交付目标 | 状态 | 开发进度 | 进入条件 | 计划完成 | |---|---|---|---:|---|---| -| P2-M0 规则锁定 | 到仓契约、数据关系、权限和文件基线 | 待开始 | 0% | 一期订单及基础资料契约稳定 | 待排期 | +| P2-M0 规则锁定 | 到仓契约、数据关系、权限和文件基线 | 待开始 | 0% | 客户订单及基础资料契约稳定 | 待排期 | | P2-M1 到仓预报 | 取货/送货预报和线下预约结果可记录 | 待开始 | 0% | 收货仓 API 可用 | 待排期 | | P2-M2 到仓收货 | 签到、分批收货、标签、照片和冲正可追溯 | 待开始 | 0% | 文件服务、仓库权限及标签设备可用 | 待排期 | | P2-M3 测量差异 | 原始测量、三位向上取整、差异记录和通知可用 | 待开始 | 0% | 测量规则可用 | 待排期 | @@ -79,7 +79,7 @@ ## 五、原型映射与范围边界 -| 流程/能力 | 原型覆盖 | 二期任务 | 二期处理 | +| 流程/能力 | 原型覆盖 | 入库测量与计费任务 | 入库测量与计费处理 | |---|---|---|---| | 取货/送货预报 | 部分 | P2-ADM-02、P2-CLI-01 | 记录线下预约结果，不做容量调度 | | 到仓收货 | 部分 | P2-WH-01、P2-REV-01 | 分批收货和冲正；不建设无预报认领 | @@ -88,19 +88,19 @@ | 指定库位 | 较完整 | P2-LOC-01、P2-PUT-01、P2-POS-01 | 不做容量校验和隔离区 | | 标签打印 | 部分 | P2-LABEL-01 | 使用佳博 1324D 实机适配 | | 头程费用 | 部分 | P2-FEE-01、P2-RATE-01、P2-CALC-01、P2-FEE-02 | 只做费用项目、规则、试算、调整和明细 | -| 应收应付、对账、收付款、核销 | 原型存在 | - | 不纳入二期 | -| 发票、汇率结算、利润和财务报表 | 原型存在 | - | 不纳入二期 | -| PDA | 有“03 出仓”原型 | - | Q9 暂缓，二期不接 PDA | -| 完整库存/WMS | 原型存在 | - | 二期只维护处理单元位置记录 | +| 应收应付、对账、收付款、核销 | 原型存在 | - | 不纳入入库测量与计费 | +| 发票、汇率结算、利润和财务报表 | 原型存在 | - | 不纳入入库测量与计费 | +| PDA | 有“03 出仓”原型 | - | Q9 暂缓，入库测量与计费不接 PDA | +| 完整库存/WMS | 原型存在 | - | 入库测量与计费只维护处理单元位置记录 | ## 六、需求确认进度 | 状态 | 数量 | 编号 | 说明 | |---|---:|---|---| | 已确认 | 12 | Q1-Q8、Q10-Q13 | 到仓规则和“仅头程计费”已进入基线 | -| 暂缓 | 1 | Q9 | 二期不接 PDA | +| 暂缓 | 1 | Q9 | 入库测量与计费不接 PDA | | 待确认 | 3 | Q14-Q16 | 费用白名单、计费复杂度、费用生成节点 | -| 不纳入二期 | 8 | Q17-Q24 | 后续财务与结算能力 | +| 不纳入入库测量与计费 | 8 | Q17-Q24 | 后续财务与结算能力 | ## 七、测试与验收重点 @@ -121,4 +121,4 @@ - 原型覆盖统一使用：较完整、部分、无、不适用；原型覆盖不得换算为开发进度。 - 负责人、计划开始和计划完成由排期会议填写；未获得实际数据时保持“待分配/待排期”。 - 开始编码后才能填写大于 0% 的开发进度；开发、测试和验收完成后才能标记“已完成”。 -- 需求结论先回写 [二期需求确认清单](二期需求确认清单.md)，再同步本表、开发规划、任务依赖和验收标准。 +- 需求结论先回写 [入库测量与计费需求确认清单](入库测量与计费需求确认清单.md)，再同步本表、开发规划、任务依赖和验收标准。 diff --git a/二期/二期计费财务模块规划.md b/入库测量与计费/入库测量与计费计费财务模块规划.md similarity index 83% rename from 二期/二期计费财务模块规划.md rename to 入库测量与计费/入库测量与计费计费财务模块规划.md index 4e32237..6ca3e93 100644 --- a/二期/二期计费财务模块规划.md +++ b/入库测量与计费/入库测量与计费计费财务模块规划.md @@ -1,15 +1,15 @@ -# 虫虫出海二期头程计费模块规划 +# 虫虫出海入库测量与计费头程计费模块规划 -> 创建日期：2026-07-28 -> 更新日期：2026-07-31 -> 状态：产品已确认范围，计费规则细节确认中 -> 历史文件名保留：`二期计费财务模块规划.md` -> 关联规划：[二期开发规划](二期开发规划.md) -> 产品确认记录：[2026-07-31 二期产品确认合并记录](产品回传/2026-07-31-产品确认合并记录.md) +> 创建日期：2026-07-28 +> 更新日期：2026-07-31 +> 状态：产品已确认范围，计费规则细节确认中 +> 历史文件名保留：`入库测量与计费计费财务模块规划.md` +> 关联规划：[入库测量与计费开发规划](入库测量与计费开发规划.md) +> 产品确认记录：[2026-07-31 入库测量与计费产品确认合并记录](产品回传/2026-07-31-产品确认合并记录.md) ## 一、产品确认的范围结论 -二期只做头程业务的费用计算，不建设后续财务闭环。计费结果是头程订单的业务费用明细，不自动形成应收、应付、账单、付款、核销、发票或利润数据。 +入库测量与计费只做头程业务的费用计算，不建设后续财务闭环。计费结果是头程订单的业务费用明细，不自动形成应收、应付、账单、付款、核销、发票或利润数据。 ```text 头程订单 / 到仓实测 / 业务事件 @@ -23,7 +23,7 @@ 头程费用明细确认 ``` -## 二、二期纳入范围 +## 二、入库测量与计费纳入范围 ### 1. 头程费用项目 @@ -63,7 +63,7 @@ 费用项目、规则发布、试算、人工补录、调整、确认、作废和导出均需记录审计日志。 -## 三、二期明确不纳入 +## 三、入库测量与计费明确不纳入 - 应收、应付台账及账龄。 - 客户或供应商对账单、结算周期、账单确认和争议处理。 @@ -73,7 +73,7 @@ - 在线支付、银企直连、银行流水自动认领。 - 会计科目、会计凭证、总账和法定财务报表。 -原型中的上述页面仅作为后续阶段参考，不进入二期任务、排期或验收。 +原型中的上述页面仅作为后续阶段参考，不进入入库测量与计费任务、排期或验收。 ## 四、核心数据对象 @@ -104,7 +104,7 @@ | P2-Q15 | 计费规则维度，以及是否支持阶梯价、最低收费、封顶、组合价和冲突优先级 | 回传中的“63”无业务含义，未合并 | | P2-Q16 | 各类费用在哪个节点试算、生成、确认和作废，人工费用何时生效 | 回传中的“63”无业务含义，未合并 | -P2-Q13 已确认：二期只做到头程费用计算。P2-Q17 至 P2-Q24 对应的应收应付、对账、收付款、发票、汇率结算和利润能力不适用于二期。 +P2-Q13 已确认：入库测量与计费只做到头程费用计算。P2-Q17 至 P2-Q24 对应的应收应付、对账、收付款、发票、汇率结算和利润能力不适用于入库测量与计费。 ## 七、验收重点 diff --git a/二期/二期计费财务需求确认表.md b/入库测量与计费/入库测量与计费计费财务需求确认表.md similarity index 54% rename from 二期/二期计费财务需求确认表.md rename to 入库测量与计费/入库测量与计费计费财务需求确认表.md index 2101d4d..14e9eb1 100644 --- a/二期/二期计费财务需求确认表.md +++ b/入库测量与计费/入库测量与计费计费财务需求确认表.md @@ -1,15 +1,15 @@ -# 二期头程计费需求确认表 +# 入库测量与计费头程计费需求确认表 -> 更新日期：2026-07-31 -> 状态：产品已确认二期只做头程计费，当前仅剩 3 项计费细节待确认 -> 历史文件名保留：`二期计费财务需求确认表.md` -> 关联文档：[二期头程计费模块规划](二期计费财务模块规划.md)、[产品确认合并记录](产品回传/2026-07-31-产品确认合并记录.md) +> 更新日期：2026-07-31 +> 状态：产品已确认入库测量与计费只做头程计费，当前仅剩 3 项计费细节待确认 +> 历史文件名保留：`入库测量与计费计费财务需求确认表.md` +> 关联文档：[入库测量与计费头程计费模块规划](入库测量与计费计费财务模块规划.md)、[产品确认合并记录](产品回传/2026-07-31-产品确认合并记录.md) ## 一、已确认的范围 -| 编号 | 产品结论 | 二期开发口径 | 状态 | +| 编号 | 产品结论 | 入库测量与计费开发口径 | 状态 | |---|---|---|---| -| P2-Q13 | 二期只做头程计费 | 建设头程费用项目、计费规则、费用试算、人工补录、调整、确认、作废和费用明细 | 已确认 | +| P2-Q13 | 入库测量与计费只做头程计费 | 建设头程费用项目、计费规则、费用试算、人工补录、调整、确认、作废和费用明细 | 已确认 | 头程费用结果不自动形成应收、应付、对账单、收付款、核销、发票、利润或总账数据。 @@ -29,24 +29,24 @@ |---|---|---|---|---|---|---|---|---| | 待填写 | 待填写 | 待填写 | 待填写 | CNY | 待填写 | 待填写 | 待填写 | 待填写 | -## 三、明确不纳入二期 +## 三、明确不纳入入库测量与计费 -| 编号 | 主题 | 二期处理 | +| 编号 | 主题 | 入库测量与计费处理 | |---|---|---| -| P2-Q17 | 汇率结算和本位币折算 | 不纳入二期 | -| P2-Q18 | 财务税务结算口径 | 不纳入二期；费用项目如需税率字段，按 Q14 配置 | -| P2-Q19 | 财务费用审批、应收应付审批 | 不纳入二期；仅保留头程费用调整审计 | -| P2-Q20 | 客户/供应商对账和结算周期 | 不纳入二期 | -| P2-Q21 | 账单确认、争议和关闭 | 不纳入二期 | -| P2-Q22 | 收付款、核销、反核销和银行流水 | 不纳入二期 | -| P2-Q23 | 发票登记和外部开票平台 | 不纳入二期 | -| P2-Q24 | 利润、利润率和财务报表 | 不纳入二期 | +| P2-Q17 | 汇率结算和本位币折算 | 不纳入入库测量与计费 | +| P2-Q18 | 财务税务结算口径 | 不纳入入库测量与计费；费用项目如需税率字段，按 Q14 配置 | +| P2-Q19 | 财务费用审批、应收应付审批 | 不纳入入库测量与计费；仅保留头程费用调整审计 | +| P2-Q20 | 客户/供应商对账和结算周期 | 不纳入入库测量与计费 | +| P2-Q21 | 账单确认、争议和关闭 | 不纳入入库测量与计费 | +| P2-Q22 | 收付款、核销、反核销和银行流水 | 不纳入入库测量与计费 | +| P2-Q23 | 发票登记和外部开票平台 | 不纳入入库测量与计费 | +| P2-Q24 | 利润、利润率和财务报表 | 不纳入入库测量与计费 | ## 四、会议填写规则 - 认可当前建议：将建议复制到“最终结论”，状态改为“已确认”。 - 修改当前建议：填写会议确定的可开发口径，状态改为“已确认”。 -- 暂时无法确定：状态改为“暂缓”，并写清二期临时处理方式。 +- 暂时无法确定：状态改为“暂缓”，并写清入库测量与计费临时处理方式。 - 不需要填写确认人和确认时间。 - 确认后保留本次会议文件，不覆盖产品原始回传；新一轮确认使用新版本文件名。 diff --git a/入库测量与计费/入库测量与计费计费财务需求确认表.xlsx b/入库测量与计费/入库测量与计费计费财务需求确认表.xlsx new file mode 100644 index 0000000..6b90afb Binary files /dev/null and b/入库测量与计费/入库测量与计费计费财务需求确认表.xlsx differ diff --git a/二期/二期费用项目数据归属决策记录.md b/入库测量与计费/入库测量与计费费用项目数据归属决策记录.md similarity index 95% rename from 二期/二期费用项目数据归属决策记录.md rename to 入库测量与计费/入库测量与计费费用项目数据归属决策记录.md index 4829981..811bc85 100644 --- a/二期/二期费用项目数据归属决策记录.md +++ b/入库测量与计费/入库测量与计费费用项目数据归属决策记录.md @@ -1,9 +1,9 @@ -# 二期费用项目数据归属决策记录 +# 入库测量与计费费用项目数据归属决策记录 > 形成日期：2026-08-10 > 状态：已确认 > 决策范围：`费用类型.xls` 中 110 条费用类型的数据归属、初始化和存量迁移 -> 关联确认项：[二期 V2 需求确认清单](二期V2需求确认清单.md) C6、[二期头程计费需求确认表](二期计费财务需求确认表.md) P2-Q14 +> 关联确认项：[入库测量与计费 V2 需求确认清单](入库测量与计费V2需求确认清单.md) C6、[入库测量与计费头程计费需求确认表](入库测量与计费计费财务需求确认表.md) P2-Q14 ## 一、最终结论 @@ -11,7 +11,7 @@ - 客户费用明细仍是客户隔离数据，`fl_inbound_fee_detail.tenant_id > 0`；其 `fee_item_id` 直接引用 `tenant_id = 0` 的公共费用项目。 - 不再按客户复制费用项目，不建立“客户 ID + 模板版本”的初始化副本，也不允许用客户级费用项目承接公共定义。 - `tenant_id = 0` 只是平台技术作用域，不增加用户可见的租户层级、租户选择器或租户级运营流程。 -- 本结论只确定费用项目主数据归属。计费单位、币种、税率、自动/人工、触发节点、价格规则和结算范围仍按 C6/P2-Q14 单独确认；110 条公共项目处于 `ACTIVE` 不等于 110 条都自动参与二期计费。 +- 本结论只确定费用项目主数据归属。计费单位、币种、税率、自动/人工、触发节点、价格规则和结算范围仍按 C6/P2-Q14 单独确认；110 条公共项目处于 `ACTIVE` 不等于 110 条都自动参与入库测量与计费计费。 ## 二、源文件核对 diff --git a/二期/二期需求优化版-v2-测量计费入库主流程.md b/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md similarity index 89% rename from 二期/二期需求优化版-v2-测量计费入库主流程.md rename to 入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md index 7aaedce..d63d937 100644 --- a/二期/二期需求优化版-v2-测量计费入库主流程.md +++ b/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md @@ -1,22 +1,22 @@ -# 虫虫出海二期需求优化版 V2：测量、计费、托盘入库闭环 +# 虫虫出海入库测量与计费需求优化版 V2：测量、计费、托盘入库闭环 -> 形成日期：2026-08-01 -> 文档状态：待业务审核 -> 依据：二期原型、现有二期需求优化稿及 2026-08-01 新增流程说明 -> 本文只定义二期范围和业务契约，不代表功能已经开发完成。 +> 形成日期：2026-08-01 +> 文档状态：待业务审核 +> 依据：入库测量与计费原型、现有入库测量与计费需求优化稿及 2026-08-01 新增流程说明 +> 本文只定义入库测量与计费范围和业务契约，不代表功能已经开发完成。 -> 主体模型：本文业务数据中的“租户”历史术语与 `tenantId` / `tenant_id` 字段，当前均按客户归属兼容语义理解；产品只有“平台—客户”两级。`tenant_id=0` 是平台身份、RBAC 和平台公共仓储资源技术作用域，客户往来单位、订单、文件和费用使用所属客户 `tenant_id>0`。二期不引入真实租户层。 +> 主体模型：本文业务数据中的“租户”历史术语与 `tenantId` / `tenant_id` 字段，当前均按客户归属兼容语义理解；产品只有“平台—客户”两级。`tenant_id=0` 是平台身份、RBAC 和平台公共仓储资源技术作用域，客户往来单位、订单、文件和费用使用所属客户 `tenant_id>0`。入库测量与计费不引入真实租户层。 -> 技术实现状态更新（2026-08-04）：任务 `019fc6f9-8dcf-74e1-bc68-d42f15d7802a` 已完成核心正常主链路开发，并通过本地测试 MySQL 和隔离端口真实 API 回归。产品/业务待确认项仍以第九章和《二期 V2 需求确认清单》为准。 +> 技术实现状态更新（2026-08-04）：任务 `019fc6f9-8dcf-74e1-bc68-d42f15d7802a` 已完成核心正常主链路开发，并通过本地测试 MySQL 和隔离端口真实 API 回归。产品/业务待确认项仍以第九章和《入库测量与计费 V2 需求确认清单》为准。 > 订单衔接规则更新（2026-08-07，已确认）：草稿不生成入仓码；订单提交进入待审核时立即生成并固定唯一入仓码。平台审核无需先选择承运商；审核通过后才创建正式入库单并沿用该码，承运商可在后续履约或计费前补充。 ## 一、结论 -二期主流程应从原来的“人工测量—测量审核—接收审核—人工计费—填写一个库位”调整为： +入库测量与计费主流程应从原来的“人工测量—测量审核—接收审核—人工计费—填写一个库位”调整为： ```text -一期头程订单提交待审核 +订单与客户头程订单提交待审核 → 生成并固定唯一入仓码 → 平台审核通过（承运商不是审核前置条件） → 创建正式入库单并沿用该入仓码 @@ -32,9 +32,9 @@ → 异步通知客户 ``` -“发送费用给客户”是二期业务完成节点，也是入库成功节点。原方案中的独立“接收审核”不再作为入库前置节点；如页面需要保留，可改名为“入库确认”，其核心动作就是确认费用并完成托盘、库位占用。 +“发送费用给客户”是入库测量与计费业务完成节点，也是入库成功节点。原方案中的独立“接收审核”不再作为入库前置节点；如页面需要保留，可改名为“入库确认”，其核心动作就是确认费用并完成托盘、库位占用。 -二期不新增微服务： +入库测量与计费不新增微服务： - 入库单、测量数据、审核、计费试算和费用快照放在头程服务。 - 托盘基础资料、库位及库位占用放在仓库服务。 @@ -174,7 +174,7 @@ POST /api/platform/inbounds/{inboundId}/weight-results/confirm ### 2.4 FBA 计费范围 -二期只支持 FBA 目的仓计费，不做完整财务、账单、收付款、核销和利润模块。 +入库测量与计费只支持 FBA 目的仓计费，不做完整财务、账单、收付款、核销和利润模块。 计费匹配顺序： @@ -200,7 +200,7 @@ POST /api/platform/inbounds/{inboundId}/weight-results/confirm 基础费用 = 计费体积 × CBM 单价 ``` -其中 `167`、`363` 只是当前业务给出的默认示例，必须配置在客户规则版本中，不得硬编码。金额还可叠加船司价格表中明确配置的附加费；二期头程/FBA 计费不支持阶梯价、组合优惠和复杂表达式。Warehouse 服务中的海外仓客户级天数阶梯仓储费仅为基础资料 CRUD，当前不参与本流程自动计费。 +其中 `167`、`363` 只是当前业务给出的默认示例，必须配置在客户规则版本中，不得硬编码。金额还可叠加船司价格表中明确配置的附加费；入库测量与计费头程/FBA 计费不支持阶梯价、组合优惠和复杂表达式。Warehouse 服务中的海外仓客户级天数阶梯仓储费仅为基础资料 CRUD，当前不参与本流程自动计费。 费用单必须保存以下快照，避免基础资料后续修改影响历史订单： @@ -244,7 +244,7 @@ POST /api/platform/inbounds/{inboundId}/weight-results/confirm 示例：总体积 `20 CBM`，托盘可用容积 `2 CBM`，需要 `10` 个托盘；默认一个托盘绑定一个库位，因此需要占用 `10` 个库位。若总体积为 `20.1 CBM`，则需要 `11` 个托盘，最后一个托盘保存剩余分配体积。 -注意：业务含义应是“10 个托盘分别绑定 10 个库位”，不是“一个托盘同时绑定 10 个库位”。如果实际仓库允许同一库位存多个托盘，后续再增加库位容量模型；二期默认一托一位，以避免占用口径不清。 +注意：业务含义应是“10 个托盘分别绑定 10 个库位”，不是“一个托盘同时绑定 10 个库位”。如果实际仓库允许同一库位存多个托盘，后续再增加库位容量模型；入库测量与计费默认一托一位，以避免占用口径不清。 拆分规则： @@ -280,13 +280,13 @@ POST /api/platform/inbounds/{inboundId}/weight-results/confirm ## 四、服务与数据边界 -| 服务 | 二期职责 | 主要新增数据 | +| 服务 | 入库测量与计费职责 | 主要新增数据 | |---|---|---| | 头程服务 | 入库单、第三方测量接入、OCR 结果业务管理、测量审核、计费匹配、费用快照、入库编排 | 入库单、测量批次/明细、OCR 重量结果、审核记录、客户规则、船司价格、费用快照、托盘分配引用 | | 仓库服务 | 托盘资料、库位资料、可用库位查询、预占/确认/释放 | 托盘、库位、库位占用、预占记录 | | 文件服务 | 称重图片、测量图片和附件 | 文件元数据和对象存储引用 | | 事件桥接服务 | 客户通知的可靠投递 | Outbox 消费记录、通知结果 | -| IAM | 客户归属、企业、仓库范围和按钮权限 | 新增二期权限资源，不新增业务数据 | +| IAM | 客户归属、企业、仓库范围和按钮权限 | 新增入库测量与计费权限资源，不新增业务数据 | 头程与仓库分库，不能依赖跨库事务。采用“仓库库位预占 → 头程确认入库 → 仓库确认占用”的幂等 Saga；补偿只释放仍处于预占状态的库位，已经完成实物入库的记录不得被通知失败反向释放。 @@ -340,7 +340,7 @@ POST /internal/location-reservations/{reservationNo}/release - 测量视频。 - 单票导出。 -## 七、二期开发任务重排 +## 七、入库测量与计费开发任务重排 | ID | 模块 | 交付内容 | 优先级 | |---|---|---|---| @@ -362,7 +362,7 @@ POST /internal/location-reservations/{reservationNo}/release ### 8.1 正常流程 -1. 一期订单提交待审核时生成唯一入仓码，审核通过后创建正式入库单并沿用该码。 +1. 客户订单提交待审核时生成唯一入仓码，审核通过后创建正式入库单并沿用该码。 2. 第三方用入仓码回传多条长宽高，同一事件重复回传不产生重复数据。 3. 操作员上传多张称重图片，OCR 识别后可逐条修正，系统正确累加 KG。 4. 审核员通过测量，系统按客户规则、船司、FBA 目的仓匹配唯一有效价格。 @@ -384,23 +384,23 @@ POST /internal/location-reservations/{reservationNo}/release ## 九、仍需业务最终确认的事项 1. 包税是否固定采用 `CBM × 167` 转 KG，不包税是否固定采用 `KG ÷ 363` 转 CBM；不同客户能否配置不同系数。 -2. “根据客户规则然后根据船司计算”是只生成客户应收费用，还是同时保存船司成本。本文默认二期只向客户发送应收费用，船司价格作为计价基础，不进入应付和利润闭环。 +2. “根据客户规则然后根据船司计算”是只生成客户应收费用，还是同时保存船司成本。本文默认入库测量与计费只向客户发送应收费用，船司价格作为计价基础，不进入应付和利润闭环。 3. 船司价格唯一匹配所需维度是否就是：起运仓、渠道/类型、船司、FBA 目的仓和有效期。 4. 托盘是否始终一托一库位。本文按一托一位设计；若一个库位可放多个托盘，需要补充库位容积、承重和剩余容量规则。 -5. 托盘分配是只按体积平均拆分，还是还要拆到具体 SKU/箱数。本文二期只分配体积和箱数汇总，不做完整 SKU 库存。 +5. 托盘分配是只按体积平均拆分，还是还要拆到具体 SKU/箱数。本文入库测量与计费只分配体积和箱数汇总，不做完整 SKU 库存。 6. 点击发送费用前是否还需要第二人复核。本文默认测量审核完成后由有发送权限的操作员确认，不再增加独立接收审核。 7. OCR 服务商、图片格式、单图大小、识别时限和失败重试次数需要在技术接入前确定。 ## 十、本次相对上一版的变更 -- 第三方长宽高测量从“不纳入”改为二期 P0，并定义按入仓码接入的开放接口。 -- OCR 称重从“不纳入”改为二期 P0，支持多图累加和人工修正。 +- 第三方长宽高测量从“不纳入”改为入库测量与计费 P0，并定义按入仓码接入的开放接口。 +- OCR 称重从“不纳入”改为入库测量与计费 P0，支持多图累加和人工修正。 - 人工简单计费改为客户规则加船司 FBA 目的仓自动试算。 - 新增 KG/CBM 换算取大和费用规则/价格快照。 - 新增 Nacos 审核失败异常放行开关，默认关闭。 - 原“接收审核通过即入库”改为“发送费用给客户即入库成功”。 - 原“只填一个库位”改为按托盘容积向上拆分，并一托一位占用库位。 -- 托盘管理从“不纳入”改为二期必要基础能力，但不扩展为完整 WMS。 +- 托盘管理从“不纳入”改为入库测量与计费必要基础能力，但不扩展为完整 WMS。 ## 十一、实现与验收状态（2026-08-04） diff --git a/二期/二期需求优化版-原型对照.md b/入库测量与计费/入库测量与计费需求优化版-原型对照.md similarity index 84% rename from 二期/二期需求优化版-原型对照.md rename to 入库测量与计费/入库测量与计费需求优化版-原型对照.md index 7ac6f28..cbddd97 100644 --- a/二期/二期需求优化版-原型对照.md +++ b/入库测量与计费/入库测量与计费需求优化版-原型对照.md @@ -1,15 +1,15 @@ -# 虫虫出海二期需求优化版：头程入库测量闭环 +# 虫虫出海入库测量与计费需求优化版：头程入库测量闭环 -> 形成日期：2026-08-01 -> 需求依据：`D:\docs\悦` 原型、WMS 文档、头程物流流程图及现有二期文档 -> 优化原则：以实际原型可见流程为主，优先复用一期订单与现有微服务，不建设当前业务不需要的完整 WMS 和计费平台。 +> 形成日期：2026-08-01 +> 需求依据：`D:\docs\悦` 原型、WMS 文档、头程物流流程图及现有入库测量与计费文档 +> 优化原则：以实际原型可见流程为主，优先复用客户订单与现有微服务，不建设当前业务不需要的完整 WMS 和计费平台。 ## 一、优化结论 -二期主目标收缩为：一期头程订单提交后，后台能够完成入库单查看、实际测量、测量审核、接收审核，并记录简单库位和头程费用。 +入库测量与计费主目标收缩为：订单与客户头程订单提交后，后台能够完成入库单查看、实际测量、测量审核、接收审核，并记录简单库位和头程费用。 ```text -一期头程订单 +订单与客户头程订单 → 入库单列表/详情 → 录入实际测量数据与图片 → 测量审核 @@ -20,11 +20,11 @@ 不再单独建设到仓预约单、分批收货、处理单元、上架任务、位置历史和自动计费引擎。 -## 二、二期纳入范围 +## 二、入库测量与计费纳入范围 ### 1. 入库单列表和详情 -- 直接复用一期头程订单生成或展示入库单，不新增“订单—到仓单 1:N”模型。 +- 直接复用订单与客户头程订单生成或展示入库单，不新增“订单—到仓单 1:N”模型。 - 支持按入仓码、订单状态、测量审核状态、费用审核状态、客户、仓库和预计到达时间查询。 - 详情展示基本信息、货物明细、测量数据、费用信息、状态历史和其他信息。 - 其他信息包括快递公司、快递单号、关联文件、备注和客服内部备注。 @@ -60,7 +60,7 @@ - 差异不再建设独立差异单、客户确认、通知补偿和关闭流程。 - 在测量审核页面直接展示原单与实测箱数、重量、体积和材积差值。 - 差异仅用于审核参考和历史记录，不阻塞审核人员主动通过。 -- 原型中的“待客户确认”页签不纳入二期，应删除或改为“测量待审核”。 +- 原型中的“待客户确认”页签不纳入入库测量与计费，应删除或改为“测量待审核”。 ### 6. 库位 @@ -71,7 +71,7 @@ ### 7. 头程费用 -- 只维护二期实际使用的头程费用项目白名单。 +- 只维护入库测量与计费实际使用的头程费用项目白名单。 - 在入库单详情人工新增费用项目、数量、单价、币种、金额和备注。 - 金额由服务端按“数量 × 单价”计算，也允许固定金额。 - 费用状态：草稿、待审核、审核通过、审核不通过、作废。 @@ -82,7 +82,7 @@ ### 8. 文件、打印和导出 - 测量图片和关联文件使用现有文件服务，下载时校验租户和订单权限。 -- 打印唛头复用现有打印服务；二期只要求按入库单打印，不建设处理单元标签生命周期。 +- 打印唛头复用现有打印服务；入库测量与计费只要求按入库单打印，不建设处理单元标签生命周期。 - 单票入库清单导出列为 P1；FBA 流转单、批量 ZIP 和自定义列暂不纳入。 ## 三、状态模型 @@ -97,7 +97,7 @@ | `RECEIVED` | 接收审核通过，完成入库 | | `VOIDED` | 入库单已作废 | -不使用“待客户确认、差异关闭、上架中、上架完成”等二期无实际操作页面的状态。 +不使用“待客户确认、差异关闭、上架中、上架完成”等入库测量与计费无实际操作页面的状态。 ## 四、角色与按钮权限 @@ -126,12 +126,12 @@ | P2-08 | 费用项目 | 头程费用项目白名单和启停 | P0 | | P2-09 | 入库费用 | 人工录入、计算、提交、审核、驳回和作废 | P0 | | P2-10 | 文件与打印 | 测量图片、关联文件、鉴权下载和打印唛头 | P0 | -| P2-11 | 客户端展示 | 在一期订单详情只读展示实测、入库状态和公开费用 | P1 | +| P2-11 | 客户端展示 | 在客户订单详情只读展示实测、入库状态和公开费用 | P1 | | P2-12 | 测试发布 | 权限、越权、状态、重复提交、金额计算、文件和回归测试 | P0 | 原 24 项任务收缩为 12 项，不新增微服务：入库和审核放在头程服务，库位/快递公司继续使用仓库服务，文件与打印复用现有服务。 -## 六、从原型发现但原二期文档覆盖不足 +## 六、从原型发现但原入库测量与计费文档覆盖不足 | 原型内容 | 当前覆盖情况 | 优化处理 | |---|---|---| @@ -140,13 +140,13 @@ | 客户下单/外箱规/实际测量三组对比 | 未完整描述 | 纳入测量详情和审核页 | | 审核不通过及失败原因 | 未完整描述 | 测量和接收审核均必须支持驳回原因 | | 测量视频 | 原文只写照片 | 改为 P1 可选附件 | -| 快递公司、快递单号 | 有一期字段，但未进入二期入库详情 | 纳入“其他信息” | +| 快递公司、快递单号 | 有订单与客户字段，但未进入入库详情 | 纳入“其他信息” | | 关联文件、备注、客服内部备注 | 覆盖不足 | 纳入详情，内部备注不对客户展示 | | 作废、打印唛头、单票导出 | 覆盖不完整 | 作废和打印 P0，单票导出 P1 | | 费用审核状态 | 计费方案过度复杂 | 改为人工费用提交与审核 | | 状态历史 | 有数据对象但没有明确页面 | 详情页只读展示操作时间线 | -## 七、原型存在但二期不纳入 +## 七、原型存在但入库测量与计费不纳入 - 智能装柜、合关报关、配载、船期和 FIST 推送。 - 到仓预约容量、自动服务商分配和多批次收货。 @@ -159,20 +159,20 @@ ### 7.1 海外仓阶梯费用补充边界（2026-08-05） -Warehouse 服务已提供海外仓客户级天数阶梯仓储费的分页、详情、新增、编辑和删除接口。该功能属于基础资料配置，不代表海外仓 WMS 或自动计费已经纳入二期。当前配置不参与入库/FBA 费用计算、费用发送、账单或结算。 +Warehouse 服务已提供海外仓客户级天数阶梯仓储费的分页、详情、新增、编辑和删除接口。该功能属于基础资料配置，不代表海外仓 WMS 或自动计费已经纳入入库测量与计费。当前配置不参与入库/FBA 费用计算、费用发送、账单或结算。 ## 八、仍需产品确认的最少事项 1. 测量审核和接收审核是否必须由不同账号完成。 2. 接收审核不通过后退回到测量环节，还是直接作废入库单。 -3. 二期首批费用项目清单，以及哪些费用允许人工录入。 +3. 入库测量与计费首批费用项目清单，以及哪些费用允许人工录入。 4. 客户端是否展示费用；如果展示，只展示审核通过的费用。 5. “是否扣货/扣货理由”只作为备注字段，还是需要真实业务状态。 6. 测量视频是否保留；建议非必填并放入 P1。 ## 九、验收主流程 -1. 一期审核通过的头程订单出现在后台入库单列表。 +1. 订单与客户审核通过的头程订单出现在后台入库单列表。 2. 测量员录入箱规、重量和体积，上传测量图片并提交。 3. 审核员查看原单与实测对比，驳回时必须填写原因。 4. 测量通过后进入接收审核，接收通过后状态变为已入库。 diff --git a/二期/二期需求确认清单.md b/入库测量与计费/入库测量与计费需求确认清单.md similarity index 58% rename from 二期/二期需求确认清单.md rename to 入库测量与计费/入库测量与计费需求确认清单.md index 4362ee6..bdeb660 100644 --- a/二期/二期需求确认清单.md +++ b/入库测量与计费/入库测量与计费需求确认清单.md @@ -1,18 +1,18 @@ -# 虫虫出海二期需求确认清单：头程到仓与头程计费 +# 虫虫出海入库测量与计费需求确认清单：头程到仓与头程计费 -> 创建日期：2026-07-28 -> 更新日期：2026-07-31 -> 当前状态：产品已确认二期只做头程计费，3 项计费细节待补充 -> 确认范围：头程物流“02 到仓”及头程费用计算 -> 关联规划：[二期开发规划](二期开发规划.md) -> 原型依据：[头程物流流程图](参考资料/头程物流流程图.svg) +> 创建日期：2026-07-28 +> 更新日期：2026-07-31 +> 当前状态：产品已确认入库测量与计费只做头程计费，3 项计费细节待补充 +> 确认范围：头程物流“02 到仓”及头程费用计算 +> 关联规划：[入库测量与计费开发规划](入库测量与计费开发规划.md) +> 原型依据：[头程物流流程图](参考资料/头程物流流程图.svg) > 产品回传：[2026-07-31 产品确认合并记录](产品回传/2026-07-31-产品确认合并记录.md) ## 一、文档用途 -本清单记录二期产品确认结果和仍需补齐的开发规则。产品已确认的结论直接进入基线；仍待确认的事项不得写成不可变的业务默认值，应保持配置化或可替换。二期由单一产品负责人统一确认，不记录确认人和确认时间；项目负责人组织业务、仓库、计费和技术共同补齐可开发结论。 +本清单记录入库测量与计费产品确认结果和仍需补齐的开发规则。产品已确认的结论直接进入基线；仍待确认的事项不得写成不可变的业务默认值，应保持配置化或可替换。入库测量与计费由单一产品负责人统一确认，不记录确认人和确认时间；项目负责人组织业务、仓库、计费和技术共同补齐可开发结论。 -二期财务边界已经确定：只做头程费用项目、计费规则、费用试算和头程费用明细，不做应收应付、对账、付款、核销、发票、汇率结算、利润或总账。 +入库测量与计费财务边界已经确定：只做头程费用项目、计费规则、费用试算和头程费用明细，不做应收应付、对账、付款、核销、发票、汇率结算、利润或总账。 ## 二、确认参与人 @@ -29,7 +29,7 @@ | 编号 | 原型/回传情况 | 本次需要确定 | 当前建议 | 临时结论 | 状态 | |---|---|---|---|---|---| -| P2-Q14 | 费用白名单位置出现“63”占位值，不能作为业务结论 | “02 到仓”首批费用项目、计费单位、币种、税率/税务属性和触发节点 | 只纳入二期实际使用的头程费用；白名单外允许人工补录但必须留痕 | 待填写 | 待确认 | +| P2-Q14 | 费用白名单位置出现“63”占位值，不能作为业务结论 | “02 到仓”首批费用项目、计费单位、币种、税率/税务属性和触发节点 | 只纳入入库测量与计费实际使用的头程费用；白名单外允许人工补录但必须留痕 | 待填写 | 待确认 | | P2-Q15 | 计费规则复杂度位置出现“63”占位值，不能作为业务结论 | 计费维度，以及是否支持阶梯价、最低收费、封顶、组合价和冲突优先级 | 先支持客户、往来单位、仓库、服务类型和生效区间；复杂结构按业务需要裁剪 | 待填写 | 待确认 | | P2-Q16 | 费用生成节点位置出现“63”占位值，不能作为业务结论 | 实测、差异、上架和人工费用分别在哪个节点试算、生成、确认和作废 | 实测完成生成试算；其他费用按已确认头程业务事件生成；来源键保证幂等 | 待填写 | 待确认 | @@ -41,7 +41,7 @@ ## 四、已确认的到仓作业结论 -| 编号 | 产品结论 | 二期开发口径 | 状态 | +| 编号 | 产品结论 | 入库测量与计费开发口径 | 状态 | |---|---|---|---| | P2-Q1 | 以实际货物重量、体积为准 | 收货实测结果作为后续作业和头程计费输入 | 已确认 | | P2-Q2 | 不走系统服务商调度，取货安排线下完成 | 系统记录到仓结果，不建设服务商调度闭环 | 已确认 | @@ -51,26 +51,26 @@ | P2-Q6 | 不考虑隔离区 | 不建设独立隔离区和隔离释放流程 | 已确认 | | P2-Q7 | 当前不做库位容量校验 | 不做容量强校验，但校验库位停用和状态合法性 | 已确认 | | P2-Q8 | 称重、测量照片必传，大小不限制 | 必传照片；保留可配置技术安全上限、类型校验和访问审计 | 已确认 | -| P2-Q9 | 暂缓 PDA | 二期使用后台或响应式作业页，不接 PDA | 暂缓 | +| P2-Q9 | 暂缓 PDA | 入库测量与计费使用后台或响应式作业页，不接 PDA | 暂缓 | | P2-Q10 | 不考虑无预报货物场景 | 不建设无预报货物认领和正式订单绑定流程 | 已确认 | | P2-Q11 | 永久保存 | 业务记录不自动删除；运维另行制定存储、备份和合规处理策略 | 已确认 | | P2-Q12 | 使用佳博 1324D 热敏标签打印机 | 纸张、连接、驱动和指令协议在开发前实机核验 | 已确认 | ## 五、已确认的头程计费范围 -| 编号 | 产品结论 | 二期处理 | +| 编号 | 产品结论 | 入库测量与计费处理 | |---|---|---| -| P2-Q13 | 二期只做头程计费 | 只建设费用项目、计费规则、费用试算、调整、确认和头程费用明细 | -| P2-Q17 | 不进入二期 | 不建设汇率结算和本位币折算 | -| P2-Q18 | 不进入二期 | 不建设财务税务结算口径；费用项目如需税率字段，按 Q14 配置即可 | -| P2-Q19 | 不进入二期 | 不建设财务费用审核、应收应付审核或会计审计链；保留头程费用调整审计 | -| P2-Q20 | 不进入二期 | 不建设客户/供应商对账和结算周期 | -| P2-Q21 | 不进入二期 | 不建设账单确认、争议和关闭流程 | -| P2-Q22 | 不进入二期 | 不建设收付款、核销、反核销和银行自动认领 | -| P2-Q23 | 不进入二期 | 不建设发票登记和外部开票平台 | -| P2-Q24 | 不进入二期 | 不建设利润、利润率和财务报表 | +| P2-Q13 | 入库测量与计费只做头程计费 | 只建设费用项目、计费规则、费用试算、调整、确认和头程费用明细 | +| P2-Q17 | 不进入入库测量与计费 | 不建设汇率结算和本位币折算 | +| P2-Q18 | 不进入入库测量与计费 | 不建设财务税务结算口径；费用项目如需税率字段，按 Q14 配置即可 | +| P2-Q19 | 不进入入库测量与计费 | 不建设财务费用审核、应收应付审核或会计审计链；保留头程费用调整审计 | +| P2-Q20 | 不进入入库测量与计费 | 不建设客户/供应商对账和结算周期 | +| P2-Q21 | 不进入入库测量与计费 | 不建设账单确认、争议和关闭流程 | +| P2-Q22 | 不进入入库测量与计费 | 不建设收付款、核销、反核销和银行自动认领 | +| P2-Q23 | 不进入入库测量与计费 | 不建设发票登记和外部开票平台 | +| P2-Q24 | 不进入入库测量与计费 | 不建设利润、利润率和财务报表 | -原型中对应的完整财务页面不自动进入二期，后续阶段如需建设，另行立项确认。 +原型中对应的完整财务页面不自动进入入库测量与计费，后续阶段如需建设，另行立项确认。 ## 六、全量状态跟踪 @@ -88,26 +88,26 @@ | P2-Q10 | P0 | 无预报货物 | 已确认 | | P2-Q11 | P0 | 数据保存 | 已确认 | | P2-Q12 | P0 | 标签设备 | 已确认 | -| P2-Q13 | P0 | 二期财务范围 | 已确认 | +| P2-Q13 | P0 | 入库测量与计费财务范围 | 已确认 | | P2-Q14 | P0 | 首批费用项目 | 待确认 | | P2-Q15 | P0 | 计费规则复杂度 | 待确认 | | P2-Q16 | P0 | 费用生成节点 | 待确认 | -| P2-Q17 | P0 | 汇率结算 | 不纳入二期 | -| P2-Q18 | P0 | 财务税务结算 | 不纳入二期 | -| P2-Q19 | P0 | 财务费用审批 | 不纳入二期 | -| P2-Q20 | P0 | 对账周期 | 不纳入二期 | -| P2-Q21 | P0 | 账单确认争议 | 不纳入二期 | -| P2-Q22 | P0 | 收付款核销 | 不纳入二期 | -| P2-Q23 | P1 | 发票管理 | 不纳入二期 | -| P2-Q24 | P1 | 利润报表 | 不纳入二期 | +| P2-Q17 | P0 | 汇率结算 | 不纳入入库测量与计费 | +| P2-Q18 | P0 | 财务税务结算 | 不纳入入库测量与计费 | +| P2-Q19 | P0 | 财务费用审批 | 不纳入入库测量与计费 | +| P2-Q20 | P0 | 对账周期 | 不纳入入库测量与计费 | +| P2-Q21 | P0 | 账单确认争议 | 不纳入入库测量与计费 | +| P2-Q22 | P0 | 收付款核销 | 不纳入入库测量与计费 | +| P2-Q23 | P1 | 发票管理 | 不纳入入库测量与计费 | +| P2-Q24 | P1 | 利润报表 | 不纳入入库测量与计费 | ## 七、确认完成标准 -P2-Q14 至 P2-Q16 形成可开发结论后，头程计费模块可以进入正式任务拆分和开发验收。后续需求变化按变更流程处理，不得将应收应付、对账、付款、核销、发票或利润功能默认带入二期。 +P2-Q14 至 P2-Q16 形成可开发结论后，头程计费模块可以进入正式任务拆分和开发验收。后续需求变化按变更流程处理，不得将应收应付、对账、付款、核销、发票或利润功能默认带入入库测量与计费。 确认完成后需要同步： -- 二期头程计费模块规划。 -- 二期开发规划和开发进度表。 +- 入库测量与计费头程计费模块规划。 +- 入库测量与计费开发规划和开发进度表。 - 头程计费任务依赖、数据对象和验收标准。 -- 二期会议确认 Excel 及产品回传归档记录。 +- 入库测量与计费会议确认 Excel 及产品回传归档记录。 diff --git a/入库测量与计费/入库测量与计费需求确认清单.xlsx b/入库测量与计费/入库测量与计费需求确认清单.xlsx new file mode 100644 index 0000000..c2aa879 Binary files /dev/null and b/入库测量与计费/入库测量与计费需求确认清单.xlsx differ diff --git a/二期/参考资料/头程物流流程图.svg b/入库测量与计费/参考资料/头程物流流程图.svg similarity index 100% rename from 二期/参考资料/头程物流流程图.svg rename to 入库测量与计费/参考资料/头程物流流程图.svg diff --git a/二期/海外仓阶梯费用前端联调说明-2026-08-05.md b/入库测量与计费/海外仓阶梯费用前端联调说明-2026-08-05.md similarity index 100% rename from 二期/海外仓阶梯费用前端联调说明-2026-08-05.md rename to 入库测量与计费/海外仓阶梯费用前端联调说明-2026-08-05.md diff --git a/入库测量与计费/版本归档/2026-07-28-覆盖前-入库测量与计费开发进度表.xlsx b/入库测量与计费/版本归档/2026-07-28-覆盖前-入库测量与计费开发进度表.xlsx new file mode 100644 index 0000000..9fbf83c Binary files /dev/null and b/入库测量与计费/版本归档/2026-07-28-覆盖前-入库测量与计费开发进度表.xlsx differ diff --git a/二期/第三方入仓测量接口联调说明-2026-08-04.md b/入库测量与计费/第三方入仓测量接口联调说明-2026-08-04.md similarity index 97% rename from 二期/第三方入仓测量接口联调说明-2026-08-04.md rename to 入库测量与计费/第三方入仓测量接口联调说明-2026-08-04.md index 10b744b..77950b2 100644 --- a/二期/第三方入仓测量接口联调说明-2026-08-04.md +++ b/入库测量与计费/第三方入仓测量接口联调说明-2026-08-04.md @@ -184,10 +184,10 @@ GET 同样需要 `X-App-Key`、`X-Timestamp`、`X-Nonce` 和 `X-Signature`，不 firstleg/src/main/resources/db/phase2-third-party-single-measurement-migration.sql ``` -或执行已内联该增量的二期统一脚本： +或执行已内联该增量的入库测量与计费统一脚本： ```text -deploy/sql/2026-08-04-二期入库新增表字段-MySQL8一键执行.sql +deploy/sql/2026-08-04-入库新增表字段-MySQL8一键执行.sql ``` 同时确认 Firstleg、Order、File 使用一致的 `INTERNAL_SERVICE_TOKEN`，并配置 `ORDER_SERVICE_URL`、`FILE_SERVICE_URL` 或启用 Nacos 服务发现。 diff --git a/入库测量与计费/虫虫出海入库测量与计费开发进度表.xlsx b/入库测量与计费/虫虫出海入库测量与计费开发进度表.xlsx new file mode 100644 index 0000000..0f74b19 Binary files /dev/null and b/入库测量与计费/虫虫出海入库测量与计费开发进度表.xlsx differ diff --git a/国内货柜履约/README.md b/国内货柜履约/README.md new file mode 100644 index 0000000..7fb868c --- /dev/null +++ b/国内货柜履约/README.md @@ -0,0 +1,51 @@ +# 国内货柜履约文档 + +国内货柜履约以国内头程后程作业为范围，完成从排柜、订舱、拖车和仓内拣货，到装柜证据齐全并进入 `LOADED`/装柜完成的业务闭环。`DELIVERED`/派送完成由到达海外仓后的可信回传推进，不属于国内国内货柜履约操作范围。 + +> 范围更正：国内货柜履约只维护订舱和出仓前所需的船名航次、港口、ETD/ETA 等资料。柜子确认离开国内仓库后的 `CarrierScheduleQuery`、六家船公司查询、每 3 天/最多 3 次、来源/过期标识和后续定时船节点查询整体归海外仓业务，见 `../海外仓业务/README.md`。国内货柜履约不再建设或验收这套查询。 + +## 当前主体模型与开工禁令 + +- 国内货柜履约继续按业务单租户、“平台—客户”两级开发，客户之间严格隔离。Java 与接口中的业务 `tenant_id > 0` / `tenantId` 当前表示客户 ID；`tenant_id=0` 是平台身份、平台 RBAC 和平台公共仓库、快递公司、托盘、库位等公共资源技术作用域。客户往来单位、订单、文件和费用仍归属客户 `tenant_id>0`。 +- 国内货柜履约不得新增租户主表、租户选择器、客户所属租户配置、租户切换、租户级 RBAC 或租户级配置，也不得把当前 `tenant_id` 从客户 ID 改义为上级租户 ID。 +- `tenant`、`Tenant*`、`merchant`、接口路径和字段属于历史兼容命名，继续保留；真实租户能力必须等未来独立需求、数据迁移和跨服务契约方案确认后再实施。 + +## 文档 + +- [国内货柜履约闭环审计报告（2026-08-08）](国内货柜履约闭环审计报告-2026-08-08.md)：基于当前代码、接口、自动化和测试环境证据的闭环审计，列出阻断项、优先级和 GO 准入标准。 +- [国内货柜履约装柜闭环产品确认表（2026-08-08）](国内货柜履约装柜闭环产品确认表-2026-08-08.md)：提供给产品直接填写的纯业务确认表，不包含技术实现细节。 +- [国内货柜履约装柜闭环开发前确认单（2026-08-08）](国内货柜履约装柜闭环开发前确认单-2026-08-08.md)：用于产品确认直接开发前的状态、门禁、PDA 取证、冲正和验收细节。 +- [国内货柜履约开发规划：国内出仓](国内货柜履约开发规划.md) +- [国内货柜履约开发进度表](国内货柜履约开发进度表.md)：参考订单与客户采用“大任务 → 详细任务 → 里程碑 → 未确认事项 → 开工准入 → 验收”结构维护。 +- [虫虫出海国内货柜履约开发进度表（Excel）](虫虫出海国内货柜履约开发进度表.xlsx)：可筛选、可下拉维护并使用公式汇总的项目进度工作簿。 +- [国内货柜履约需求确认表](国内货柜履约需求确认表.md)：集中跟踪 P3-Q1～P3-Q13、负责人和最终结论。 +- [国内货柜履约开工门禁](国内货柜履约开工门禁.md)：维护已确认范围、跨端硬边界和局部阻断项；模块指引引用本文件，不重复维护阶段状态。 +- [国内货柜履约页面与原型清单](国内货柜履约页面与原型清单.md)：按管理后台、企业客户端和 PDA 维护页面范围及原型状态。 +- [国内货柜履约验收任务拆分与待确认清单](国内货柜履约验收任务拆分与待确认清单.md)：真实 HTTP/真机验收覆盖、coverageGap 解除条件和并行任务入口。 +- `参考资料/出仓流程.png`：本期 9 个核心动作及业务终点的原始参考图。 + +## 当前状态 + +国内货柜履约已进入分模块部署联调。已确认不新建独立出仓单，现有订单列表/详情承载主状态；支持一单多柜、一个柜拼多个订单，并采用“父订单→子订单→柜次”关系，已装载数量形成子订单，未装载数量自动生成后续子订单。进入 `LOADED`/装柜完成前，订舱完成、拖车完成、报关放行回执、PDA 拣货完成及五类证据完整均为服务端硬门禁；`LOADED` 后错误统一线下人工处理，国内 Admin/PDA 不提供在线冲正或手工推进 `DELIVERED`。当前不能因子链路已通过而宣告整期完成，最终结论以真实 HTTP 全链路验收为准。 + +柜子出仓后的船公司/船节点查询已重新归入海外仓业务。国内货柜履约报关首版不做系统对接，全部由人工整理、线下提交和人工上传回执。仓库初始化角色包括操作员、拣货员、理货员，具体权限矩阵由 IAM 契约任务落表。 + +P3-Q1～P3-Q13 均已确认；P3-Q4 采用 uni-app 开发并支持在线更新，Android 广播扫描已接入。P3-Q5 复用入库测量与计费实时库存、当前位置和可用量接口，不扩展完整 WMS。 + +### PDA 当前确认口径（2026-08-10） + +- Android 扫描广播方式已接入；PDA 采用 uni-app 开发并支持在线更新，按既定发布安排完成真机验收。 +- 正式作业仅支持在线：进入任务即标记“拣货中”，扫描保存在绑定作业员+任务+柜次的设备持久化草稿，点击提交时批量写后端。 +- 允许部分拣货或跳拣，但每个未完成项必须填写异常原因；存在未解决异常时不能完成或进入 `LOADED`。 +- 重复提交返回原结果，版本冲突提示员工刷新重试。 +- PDA 只能现场拍照，Admin 可人工上传；五类证据各至少 1 张有效照片，可同类型多张追加，错图只作废不硬删除。 +- 单柜次只允许一名作业员作业，不做多人并行和任务接管；进入任务即标记“拣货中”，扫描草稿按作业员+任务+柜次隔离，点击提交时批量写入后端。 +- 后台操作员、理货员可按权限人工上传证据；拣货员只负责 PDA 现场拍照，不开放后台人工上传。照片无限期保留，客户不可见照片和锁码。 + +### 发布与真实验收状态（2026-08-10） + +- Admin 已部署 `b593d72`：智能装柜、预装清单、装柜清单均可访问真实接口；预装/装柜清单不再要求选择仓库，详情仍使用列表行返回的真实仓库归属。 +- Firstleg 已部署 `3bfc11a`：修复 PDA 拣货时库位分配状态提前变更的问题；真实复跑仍发现 PDA `pick` 第二处 `S0500`，当前仍阻断 PDA 复核、装柜完成、报关 LOADED 关联和最终门禁，不能标记国内货柜履约闭环完成。 +- 验收 fixture 顺序已核实为 `orders → inbound-measurement → phase3-container-loading → phase3-loading → phase3-customs → phase3-port-schedules → phase3-loading-finalize`；脚本保留真实失败，不以 mock、历史资源或 coverage gap 伪装通过。 +- PDA“点击提交时批量写入后端”的原子 batch 契约尚未实现；当前页面仍不能证明整批事务、批次幂等、服务端库存快照和失败整批回滚已具备。 +- ZIM hCaptcha、COSCO 动态页继续按产品确认的人工兜底保留为 `MANUAL_REQUIRED`，不作为自动查询 PASS。 diff --git a/三期/参考资料/出仓流程.png b/国内货柜履约/参考资料/出仓流程.png similarity index 100% rename from 三期/参考资料/出仓流程.png rename to 国内货柜履约/参考资料/出仓流程.png diff --git a/三期/三期Wave1开发任务卡-2026-08-09.md b/国内货柜履约/国内货柜履约Wave1开发任务卡-2026-08-09.md similarity index 85% rename from 三期/三期Wave1开发任务卡-2026-08-09.md rename to 国内货柜履约/国内货柜履约Wave1开发任务卡-2026-08-09.md index de0c5c9..df503cd 100644 --- a/三期/三期Wave1开发任务卡-2026-08-09.md +++ b/国内货柜履约/国内货柜履约Wave1开发任务卡-2026-08-09.md @@ -1,4 +1,4 @@ -# 三期 Wave 1 开发任务卡 +# 国内货柜履约 Wave 1 开发任务卡 整理日期：2026-08-09 用途：产品确认后用于研发排期和任务分派。 @@ -7,9 +7,9 @@ ## 一、统一范围口径 - 不新增独立出仓单主对象、列表或详情页面。 -- 现有订单是三期唯一主对象；柜次是执行对象。 +- 现有订单是国内货柜履约唯一主对象；柜次是执行对象。 - 订单与柜次通过履约分片/分配关系表达一单多柜、一柜多单和部分履约。 -- 国内三期终点是 `LOADED`/装柜完成；国内端不能手工推进 `DELIVERED`。 +- 国内国内货柜履约终点是 `LOADED`/装柜完成；国内端不能手工推进 `DELIVERED`。 - 五类装柜照片为：空仓、半仓、满仓、锁仓、带锁码照；锁码文本单独保存。 ## 二、第一批可立即开发 @@ -18,9 +18,9 @@ |---|---|---|---|---|---| | W1-BE-01-R | 后端 | 订单-柜次-履约分片契约设计 | 现有 order/firstleg/loading DTO、关系表和 OpenAPI；不得创建 `fl_outbound_order` | 支持多对多关系、快照、版本和客户隔离；形成评审稿 | 产品确认 Q2/Q11 后冻结实现 | | W1-BE-06 | 后端 | 拖车幂等与实际节点修复 | TruckAppointmentService、Controller、Mapper、测试 | 缺少幂等键时拒绝；同键重放返回原结果；冲突返回 409；到仓/离仓时间可追溯 | 无 | -| W1-BE-08 | 后端 | OpenAPI 盘点与集成测试骨架 | 订舱、拖车、排柜、PDA、文件、门禁接口文档和契约测试 | 文档路径与 Controller 一致；建立二期终点到装柜完成的测试骨架 | 仅依赖现有接口 | +| W1-BE-08 | 后端 | OpenAPI 盘点与集成测试骨架 | 订舱、拖车、排柜、PDA、文件、门禁接口文档和契约测试 | 文档路径与 Controller 一致；建立入库测量与计费终点到装柜完成的测试骨架 | 仅依赖现有接口 | | A-01 | Admin | 订舱 DTO、版本和动作权限对齐 | `apps/admin-web/src/modules/ocean-bookings/` | 创建、编辑、提交、确认、放舱、变更、取消均使用真实字段、版本和权限 | 后端现有契约 | -| A-02 | Admin | 订单详情挂载三期作业组件 | `apps/admin-web/src/modules/unified-orders/` | 从订单详情可进入分柜、预装、拣货、装柜；刷新可恢复；错误和无权限有明确提示 | 订单与入库关联字段确认 | +| A-02 | Admin | 订单详情挂载国内货柜履约作业组件 | `apps/admin-web/src/modules/unified-orders/` | 从订单详情可进入分柜、预装、拣货、装柜；刷新可恢复；错误和无权限有明确提示 | 订单与入库关联字段确认 | | PDA-01 | PDA | 五证据槽位和上传队列基础 | `apps/pda-uniapp/pages/` 及文件上传适配 | 五类槽位固定；临时路径不作为业务证据；失败可重试；重复提交不产生重复有效记录 | File 上传接口 | | CLI-01 | Client | 内部证据字段脱敏 | `apps/client-web/src/modules/first-leg/` | Client 不返回、不展示照片、锁码和 `sealNo`；订单状态仍可正常展示 | 后端响应兼容 | diff --git a/三期/三期开发规划.md b/国内货柜履约/国内货柜履约开发规划.md similarity index 79% rename from 三期/三期开发规划.md rename to 国内货柜履约/国内货柜履约开发规划.md index 0fda4a0..28b930a 100644 --- a/三期/三期开发规划.md +++ b/国内货柜履约/国内货柜履约开发规划.md @@ -1,19 +1,19 @@ -# 虫虫出海三期开发规划：国内出仓 +# 虫虫出海国内货柜履约开发规划：国内出仓 > 创建日期：2026-07-28 > 状态：已进入分模块开发规划 -> 流程依据：[出仓流程](参考资料/出仓流程.png)中的头程物流“03 出仓”；用户已于 2026-08-08 确认国内三期以 `LOADED`/装柜完成为阶段终点 -> 前置阶段：[一期文档](../一期/README.md) · [二期文档](../二期/README.md) +> 流程依据：[出仓流程](参考资料/出仓流程.png)中的头程物流“03 出仓”；用户已于 2026-08-08 确认国内国内货柜履约以 `LOADED`/装柜完成为阶段终点 +> 前置阶段：[订单与客户文档](../订单与客户/README.md) · [入库测量与计费文档](../入库测量与计费/README.md) -> 2026-08-10 产品确认版：三期不新建独立出仓单；支持一单多柜、一个柜拼多个订单，采用“父订单→子订单→柜次”关系，已装载数量形成子订单，未装载数量自动生成后续子订单。`LOADED` 硬门禁为订舱完成、拖车完成、报关放行回执、PDA 拣货完成和五类证据完整；`LOADED` 后错误线下人工处理。五类证据各至少 1 张有效照片，同类型多张追加，PDA 仅现场拍照，后台操作员和理货员可人工上传，照片无限期保留且客户不可见。 +> 2026-08-10 产品确认版：国内货柜履约不新建独立出仓单；支持一单多柜、一个柜拼多个订单，采用“父订单→子订单→柜次”关系，已装载数量形成子订单，未装载数量自动生成后续子订单。`LOADED` 硬门禁为订舱完成、拖车完成、报关放行回执、PDA 拣货完成和五类证据完整；`LOADED` 后错误线下人工处理。五类证据各至少 1 张有效照片，同类型多张追加，PDA 仅现场拍照，后台操作员和理货员可人工上传，照片无限期保留且客户不可见。 -> 当前范围更正：原 `P3-PORT-01`、六家船公司官网查询及 `CarrierScheduleQuery` 是柜子确认离开国内仓库后的业务，整体重新归入四期。三期仅保存订舱与出仓前所需的船名航次、港口和 ETD/ETA 等资料，不建设或验收出仓后的定时节点查询。 +> 当前范围更正：原 `P3-PORT-01`、六家船公司官网查询及 `CarrierScheduleQuery` 是柜子确认离开国内仓库后的业务，整体重新归入海外仓业务。国内货柜履约仅保存订舱与出仓前所需的船名航次、港口和 ETD/ETA 等资料，不建设或验收出仓后的定时节点查询。 -> 主体模型与硬约束：三期只实现“平台—客户”两级，业务 `tenant_id > 0` / `tenantId` 当前表示客户 ID；`tenant_id=0` 是平台身份、平台 RBAC 和平台公共仓储资源技术作用域，客户往来单位、订单、文件和费用归属客户 `tenant_id>0`。禁止新增租户主表、租户选择器、客户所属租户配置、租户切换、租户级 RBAC 或租户级配置，禁止把现有 `tenant_id` 改义为上级租户 ID；历史类名、路径和字段继续兼容。 +> 主体模型与硬约束：国内货柜履约只实现“平台—客户”两级，业务 `tenant_id > 0` / `tenantId` 当前表示客户 ID；`tenant_id=0` 是平台身份、平台 RBAC 和平台公共仓储资源技术作用域，客户往来单位、订单、文件和费用归属客户 `tenant_id>0`。禁止新增租户主表、租户选择器、客户所属租户配置、租户切换、租户级 RBAC 或租户级配置，禁止把现有 `tenant_id` 改义为上级租户 ID；历史类名、路径和字段继续兼容。 -## 一、三期目标 +## 一、国内货柜履约目标 -三期承接二期“货物完成到仓、实测、差异处理和指定库位”的结果，将已受理货物转化为可执行、可追踪、可审计的国内出仓任务。 +国内货柜履约承接入库测量与计费“货物完成到仓、实测、差异处理和指定库位”的结果，将已受理货物转化为可执行、可追踪、可审计的国内出仓任务。 流程覆盖九个动作： @@ -26,10 +26,10 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 ↓ 维护订舱与出仓前所需的船名航次、港口和预计时间 ↓ -国内三期完成：`LOADED`/装柜完成 +国内国内货柜履约完成：`LOADED`/装柜完成 ``` -三期完成标准是同一订单/柜次已完成排柜和 PDA 拣货，空仓、半仓、满仓、锁仓、带锁码照五类证据各至少 1 张有效照片已真实上传，锁码文本已保存，服务端门禁通过并将订单推进为 `LOADED`/装柜完成。`DELIVERED`/派送完成必须等货物到达海外仓后由海外仓可信回传推进，不是国内三期人工操作。 +国内货柜履约完成标准是同一订单/柜次已完成排柜和 PDA 拣货，空仓、半仓、满仓、锁仓、带锁码照五类证据各至少 1 张有效照片已真实上传，锁码文本已保存，服务端门禁通过并将订单推进为 `LOADED`/装柜完成。`DELIVERED`/派送完成必须等货物到达海外仓后由海外仓可信回传推进，不是国内国内货柜履约人工操作。 ### 原型动作覆盖 @@ -43,13 +43,13 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 | 6. 客户上传报关资料 | 报关资料协同 | P3-CUS-01 | 已覆盖 | | 7. 整理给到报关代理报关 | 报关资料协同 | P3-CLEAR-01 | 已覆盖 | | 8. 回执上传到系统供客户下载 | 报关回执与客户下载 | P3-CLEAR-01、P3-CUS-02 | 已覆盖，首版由授权人员人工上传放行回执 | -| 9. 出仓后查询港务/船节点 | 四期船节点定时查询 | 原 P3-PORT-01、P3-CUS-02 对应查询部分 | 已重新归入四期，不是三期动作或验收项 | +| 9. 出仓后查询港务/船节点 | 海外仓业务船节点定时查询 | 原 P3-PORT-01、P3-CUS-02 对应查询部分 | 已重新归入海外仓业务，不是国内货柜履约动作或验收项 | ## 二、阶段边界 -### 纳入三期 +### 纳入国内货柜履约 -- 现有订单三期状态、订单-柜次关联、智能排柜建议、人工调整和版本确认。 +- 现有订单国内货柜履约状态、订单-柜次关联、智能排柜建议、人工调整和版本确认。 - 订舱申请、舱位结果，以及出仓前人工确认或业务录入的船名航次、港口、ETD/ETA 等资料快照。 - 预约拖车、车辆司机、到仓装柜和离仓记录。 - PDA 任务领取、扫码拣货、部分拣货、异常、复核和幂等提交。 @@ -58,14 +58,14 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 - 报关回执上传、版本、客户可见范围和授权下载。 - 装柜完成门禁、确认、时间线和站内通知；`LOADED` 后纠错走线下人工流程。 -### 明确不纳入三期 +### 明确不纳入国内货柜履约 -- 入库、上架、移库、盘点、冻结、补货和完整 WMS；拣货仅复用二期实时库存、当前位置和可用量接口。 +- 入库、上架、移库、盘点、冻结、补货和完整 WMS；拣货仅复用入库测量与计费实时库存、当前位置和可用量接口。 - 港区闸口、车队、船公司、海关单一窗口的正式自动化接口。 - GPS 实时跟车、电子铅封、称重设备、摄像头 OCR 和 IoT 自动采集。 - 自动报关、关税计算、退税、完整清关业务和自动单证识别。 - 海上运输、海外清关、目的港提柜、海外仓入库和末端派送。 -- 柜子确认离开国内仓库后的 `CarrierScheduleQuery`、船公司查询、定时船节点和到港跟踪；整体归四期。 +- 柜子确认离开国内仓库后的 `CarrierScheduleQuery`、船公司查询、定时船节点和到港跟踪；整体归海外仓业务。 - 无人工确认的全自动排柜、自动订舱和不可逆业务操作。 ## 三、参与角色与数据边界 @@ -89,14 +89,14 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 原型以 1 至 9 编号表达动作顺序。产品确认后，订舱、拖车、报关放行、PDA 拣货和证据完整是进入 `LOADED` 的强制前置；智能排柜、订舱、拖车和资料整理可按子流程并行，但服务端不得绕过门禁。PDA 单柜次单作业员，不实现多人并行或任务接管。 -### 1. 现有订单的三期主状态 +### 1. 现有订单的国内货柜履约主状态 | 稳定编码 | 中文名称 | 含义 | |---|---|---| -| `WAIT_SPLIT` | 待分柜 | 二期已完成，等待排柜/预装 | +| `WAIT_SPLIT` | 待分柜 | 入库测量与计费已完成，等待排柜/预装 | | `LOADING` | 装柜中 | 预装已确认，PDA 执行拣货和装柜证据上传 | | `LOADED` | 装柜完成 | 订舱、拖车、报关放行回执、PDA 拣货完成，且五类证据各至少 1 张有效照片和锁码文本已通过服务端门禁 | -| `DELIVERED` | 派送完成 | 货物到达海外仓后由海外仓可信回传推进；属于三期之后的只读状态 | +| `DELIVERED` | 派送完成 | 货物到达海外仓后由海外仓可信回传推进；属于国内货柜履约之后的只读状态 | ### 2. 子流程状态 @@ -104,7 +104,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 - 拖车：待预约、已预约、车辆已到仓、装柜中、已离仓、改约、已取消。 - 拣货：待分配、待拣货、拣货中、待复核、已完成、异常挂起、已取消。 - 报关：资料待上传、资料待审核、待补件、待提交、已提交代理、回执待上传、回执已上传、已退回、已取消；有效放行回执是 `LOADED` 硬门禁，首版由授权人员人工上传。 -- 出仓前船期资料：待维护、已确认、信息变更；出仓后节点和“已开船”等运输事实归四期。 +- 出仓前船期资料：待维护、已确认、信息变更；出仓后节点和“已开船”等运输事实归海外仓业务。 主状态由服务端根据已确认的必要子流程推进。客户端不得通过传任意目标状态跳过拣货复核、装柜证据或已配置的装柜完成门禁。 @@ -112,7 +112,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 ### 1. 现有订单与柜次 -- 不创建独立出仓单，现有订单从 `WAIT_SPLIT` 继续推进三期状态。 +- 不创建独立出仓单，现有订单从 `WAIT_SPLIT` 继续推进国内货柜履约状态。 - 通过“父订单→子订单→柜次”表达一张订单分多柜、多张订单拼柜和拆批；已装载数量形成子订单，未装载数量自动生成后续子订单，子订单必须保留来源订单和数量分摊快照。 - 订单保持用户当前看到的主状态；柜次承载多订单共享的订舱、拖车、装柜证据和船期信息。 - 订单详情展示关联柜次、子流程状态、异常和整体时间线。 @@ -127,11 +127,11 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 ### 3. 订舱与出仓前船期资料 -- 三期只维护订舱和装柜/出仓交接所需的预计开船、到港等静态资料，不执行出仓后的船公司或船节点查询。 +- 国内货柜履约只维护订舱和装柜/出仓交接所需的预计开船、到港等静态资料，不执行出仓后的船公司或船节点查询。 - 船公司/订舱代理、航线、订舱号、船名航次、起运港、目的港、截单、截关、截港、ETD 和 ETA 暂列为候选字段。 - 订舱失败、改船、甩柜、船期延误和取消暂列为候选异常场景，按业务确认结果实现。 -- 六家船公司来源、每 3 天/最多 3 次、最近有效结果和过期标识，以及对应适配层全部移至四期船节点查询维护。 -- 三期页面展示的 ETD/ETA 必须明确为订舱或人工确认快照，不得伪装成出仓后的实时查询结果。 +- 六家船公司来源、每 3 天/最多 3 次、最近有效结果和过期标识，以及对应适配层全部移至海外仓业务船节点查询维护。 +- 国内货柜履约页面展示的 ETD/ETA 必须明确为订舱或人工确认快照，不得伪装成出仓后的实时查询结果。 - 建议关键信息变更保留旧值、新值、原因，并向授权用户发送站内提醒。 ### 4. 预约拖车 @@ -183,14 +183,14 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 - 服务端校验排柜已确认、PDA 拣货已完成、五类证据各至少 1 张有效且未作废的图片已取得真实 `fileId`、锁码文本已保存。 - 门禁通过后仅将订单推进为 `LOADED`/装柜完成，记录柜次、柜号、锁码、操作人、时间和证据版本。 - 该操作必须幂等、乐观锁、完整审计和失败回复，禁止从前端跳过门禁。 -- 装柜完成后发现错误统一线下人工处理；本期不提供在线冲正/回退接口，系统保留原状态、证据和审计记录。 +- 装柜完成后发现错误统一线下人工处理；当前不提供在线冲正/回退接口，系统保留原状态、证据和审计记录。 - `DELIVERED`/派送完成只接受海外仓可信回传，必须有来源身份、签名/防重放、幂等键、请求摘要和审计；国内 Admin/PDA 不提供手工“确认派送完成”操作。 ## 六、核心数据对象 | 数据对象 | 关键内容 | |---|---| -| 现有订单三期投影 | 订单、客户、仓库、三期主状态、关联柜次、子流程摘要和版本 | +| 现有订单国内货柜履约投影 | 订单、客户、仓库、国内货柜履约主状态、关联柜次、子流程摘要和版本 | | 父/子订单关系 | 父订单、子订单、来源柜次、已装载数量、未装载数量和自动生成原因 | | 排柜方案 | 经确认的规则版本、输入快照、柜次、货物分配、规则计算结果和确认记录 | | 柜次 | 柜型、柜号、铅封号、装载顺序、重量、体积和关联订单 | @@ -235,13 +235,13 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 - 最终保证身份、客户归属、仓库数据范围、权限、状态、门禁、幂等、并发和审计。 - 管理出仓、排柜、订舱、拖车、拣货、装柜、报关和时间线的事务边界。 - 文件上传校验类型、大小、内容和权限；使用不可预测标识和授权下载。 -- 三期服务端保存订舱与出仓前船期资料；六家船公司和定时船节点查询由四期负责。车队、海关仍只预留适配层，报关首版全部人工处理，不承诺正式系统对接。 +- 国内货柜履约服务端保存订舱与出仓前船期资料；六家船公司和定时船节点查询由海外仓业务负责。车队、海关仍只预留适配层，报关首版全部人工处理，不承诺正式系统对接。 ## 八、建议里程碑 | 里程碑 | 交付目标 | 进入条件 | |---|---|---| -| P3-M0 规则与设备锁定 | 流程、角色、状态、排柜规则、PDA、文件和验收确认 | 二期到仓契约稳定 | +| P3-M0 规则与设备锁定 | 流程、角色、状态、排柜规则、PDA、文件和验收确认 | 入库测量与计费到仓契约稳定 | | P3-M1 订单与排柜 | 现有订单可进入待分柜，并按确认范围提供柜次建议、人工确认与追溯 | 排柜规则确认 | | P3-M2 订舱与拖车 | 订舱、出仓前船期资料、拖车预约和异常处理可用 | 服务商与权限可用 | | P3-M3 PDA 拣货 | 在线任务、持久化草稿、批量提交、差异、复核和幂等可用 | 服务端任务与库存契约可用 | @@ -254,13 +254,13 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 | ID | 端 | 模块 | 交付内容 | 优先级 | 依赖 | |---|---|---|---|---|---| -| P3-BASE-01 | 公共 | 出仓契约 | 主/子状态、权限、事件、错误码、门禁和快照模型 | P0 | 二期到仓契约 | -| P3-BASE-02 | 公共 | 数据模型 | 现有订单三期投影、订单-柜次、排柜、订舱、拖车、拣货、装柜、报关和时间线 | P0 | P3-BASE-01 | -| P3-DSP-01 | 后台 | 订单三期编排 | 在现有订单列表/详情中接入柜次、子流程、异常、时间线和门禁操作 | P0 | P3-BASE-02 | +| P3-BASE-01 | 公共 | 出仓契约 | 主/子状态、权限、事件、错误码、门禁和快照模型 | P0 | 入库测量与计费到仓契约 | +| 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 | 后台 | 订舱 | 订舱和经确认的船名航次、港口、变更及异常；订舱完成是 `LOADED` 门禁 | P0 | P3-DSP-01 | -| 原 P3-PORT-01 | 后台/服务端 | 出仓后船节点查询 | 已重新归入四期，不作为三期交付或验收项；沿用现有 `CarrierScheduleQuery`，不得重复实现 | 四期 | P3-BOOK-01、确认国内出仓 | +| 原 P3-PORT-01 | 后台/服务端 | 出仓后船节点查询 | 已重新归入海外仓业务，不作为国内货柜履约交付或验收项；沿用现有 `CarrierScheduleQuery`，不得重复实现 | 海外仓业务 | 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 | @@ -269,7 +269,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 | P3-LOAD-02 | PDA/Admin/服务端 | 柜封拍照上传 | PDA 现场拍摄、Admin 人工上传、五类证据多图追加、真实文件上传、预览、失败重试、作废和提交 | P0 | P3-LOAD-01、文件能力可用 | | P3-CUS-01 | 客户端 | 报关资料 | 清单、上传、补件、版本和进度查看 | P0 | 文件能力可用 | | P3-CLEAR-01 | 后台 | 报关协同 | 人工审核、补件、线下提交代理、人工上传放行回执和版本审计 | P0 | P3-CUS-01 | -| P3-CUS-02 | 客户端 | 回执及出仓前船期资料 | 回执下载、订舱预计开船/到港快照和变更时间线；出仓后查询展示归四期 | P0 | P3-BOOK-01、P3-CLEAR-01 | +| P3-CUS-02 | 客户端 | 回执及出仓前船期资料 | 回执下载、订舱预计开船/到港快照和变更时间线；出仓后查询展示归海外仓业务 | P0 | P3-BOOK-01、P3-CLEAR-01 | | 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 | 核心流程完成 | @@ -280,21 +280,21 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 ## 十、测试与验收重点 - 系统排柜符合已确认的业务规则；如启用建议解释、人工调整、版本或原因记录，对应结果可追溯。 -- 多订单拼柜和一单多柜的件数、重量、体积能与二期实测版本对账。 +- 多订单拼柜和一单多柜的件数、重量、体积能与入库测量与计费实测版本对账。 - PDA 重复扫码、超量、错货和重复提交不产生重复扣减或完成事件；断网时禁止正式作业和提交。 - 本地草稿在应用重启后可由同一作业员、任务和柜次恢复，不能被其他账号继承；批量提交成功后清理。 - 柜封照片能够在 PDA 现场拍摄或由 Admin 受权上传；同类型可多张追加，失败重试不重复创建同一记录，错图只作废不硬删除。 - 未完成 PDA 拣货、缺少任意一张必传照片或锁码文本时不能进入 `LOADED`/装柜完成。 - 企业 A 无法查看、上传或下载企业 B 的报关资料和回执。 - 报关资料替换、退回、补件、提交和回执均能追溯到明确版本。 -- 订舱与出仓前船期资料变更保留历史；出仓后船节点查询结果的来源、更新时间和过期验收归四期。 +- 订舱与出仓前船期资料变更保留历史；出仓后船节点查询结果的来源、更新时间和过期验收归海外仓业务。 - 确认装柜完成的并发请求只产生一次状态变化和一次有效审计事件。 - 管理后台覆盖加载、空态、失败、无权限和数据冲突；PDA 覆盖弱网、前后台切换和硬件扫描。 -- 三期验收基线为 `LOADED`/装柜完成；`DELIVERED`/派送完成只由海外仓回传推进，不属于国内三期验收条件。 +- 国内货柜履约验收基线为 `LOADED`/装柜完成；`DELIVERED`/派送完成只由海外仓回传推进，不属于国内国内货柜履约验收条件。 ## 十一、启动前技术澄清事项 -验收任务拆分、真实 HTTP 覆盖和未确认项解除条件统一见[三期验收任务拆分与待确认清单](三期验收任务拆分与待确认清单.md)。当前已确认的 PDA/证据规则已进入 `phase3-container-loading.mjs`、`phase3-loading.mjs`；未确认规则不得标记为三期完成。 +验收任务拆分、真实 HTTP 覆盖和未确认项解除条件统一见[国内货柜履约验收任务拆分与待确认清单](国内货柜履约验收任务拆分与待确认清单.md)。当前已确认的 PDA/证据规则已进入 `phase3-container-loading.mjs`、`phase3-loading.mjs`；未确认规则不得标记为国内货柜履约完成。 | 编号 | 待确认问题 | 当前建议 | |---|---|---| @@ -302,20 +302,20 @@ PDA 拣货 → 装柜并上传货柜/铅封照片 | P3-Q2 | 是否存在拼柜、一单多柜和拆批出仓？ | 已确认：父订单→子订单→柜次；已装载/未装载数量自动形成子订单 | | P3-Q3 | “预约托车”是否统一为“预约拖车”？ | 已确认统一使用“预约拖车” | | P3-Q4 | PDA 开发、扫描与发布方式是什么？ | 已确认采用 uni-app 开发并支持在线更新；Android 广播接入已完成，设备型号不构成门禁 | -| P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 已确认依赖二期实时库存、当前位置和可用量接口；不扩展完整 WMS | +| P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 已确认依赖入库测量与计费实时库存、当前位置和可用量接口；不扩展完整 WMS | | P3-Q6 | 柜封照片有哪些必传角度和留存期限？ | 已确认：五类各至少 1 张、同类型可多张追加、后台操作员/理货员可上传、拣货员仅 PDA 现场采集、错图作废、无限期保留、客户不可见 | | P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 已确认首版人工维护清单和版本，不接自动报关 | | P3-Q8 | 报关代理如何接收资料和返回回执？ | 已确认线下提交，授权人员人工上传回执 | -| P3-Q9 | 原型中的“港务信息”具体指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 当前更正：三期只维护订舱与出仓前船期资料；六家船公司及出仓后节点查询整体归四期 | -| P3-Q10 | 进入装柜完成后发现错误如何处理？ | 已确认线下人工处理，本期不提供在线冲正 | +| P3-Q9 | 原型中的“港务信息”具体指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 当前更正：国内货柜履约只维护订舱与出仓前船期资料；六家船公司及出仓后节点查询整体归海外仓业务 | +| P3-Q10 | 进入装柜完成后发现错误如何处理？ | 已确认线下人工处理，当前不提供在线冲正 | | P3-Q11 | 九个动作中哪些是强制前置，哪些允许并行？ | 已确认订舱、拖车、报关放行、PDA 拣货和五类证据为 `LOADED` 硬门禁；单柜次单作业员 | | P3-Q12 | “报关回执”具体包含哪些类型，海关放行是否为国内出仓硬门禁？ | 已确认有效放行回执为 `LOADED` 硬门禁，首版人工上传 | -| P3-Q13 | 三期终点以什么状态为准？ | 已确认为 `LOADED`/装柜完成；`DELIVERED`/派送完成由海外仓回传，不属于国内三期 | +| P3-Q13 | 国内货柜履约终点以什么状态为准？ | 已确认为 `LOADED`/装柜完成；`DELIVERED`/派送完成由海外仓回传，不属于国内国内货柜履约 | ## 十二、建议实施顺序 1. 固化已确认业务规则，按 uni-app 在线更新安排推进 PDA 开发、发布和真机验收。 -2. 统一订单、柜次、订舱、拖车、拣货、报关和出仓前船期资料的稳定编码与关联契约；出仓后查询按四期衔接。 +2. 统一订单、柜次、订舱、拖车、拣货、报关和出仓前船期资料的稳定编码与关联契约；出仓后查询按海外仓业务衔接。 3. 先实现服务端权限、状态、门禁、幂等、并发和审计，再接各端页面。 4. 完成管理后台的出仓编排，再接 PDA 现场执行和客户资料协同。 5. 使用脱敏数据演练拼柜、一单多柜、未装数量生成子订单、错拣、补件和改船；`LOADED` 后不演练在线冲正。 diff --git a/三期/三期开发进度表.md b/国内货柜履约/国内货柜履约开发进度表.md similarity index 73% rename from 三期/三期开发进度表.md rename to 国内货柜履约/国内货柜履约开发进度表.md index a919a32..4c7093c 100644 --- a/三期/三期开发进度表.md +++ b/国内货柜履约/国内货柜履约开发进度表.md @@ -1,24 +1,24 @@ -# 虫虫出海三期开发进度表 +# 虫虫出海国内货柜履约开发进度表 -> 创建日期：2026-07-28 -> 当前阶段：已确认口径下的分模块部署、联调与缺口收口 -> 总体状态：分模块已部署联调；PDA 主链仍阻断，尚未达到三期闭环验收 -> 规划依据：`三期开发规划.md` -> 维护方式：参考一期进度表，采用“总体大任务 → 详细任务 → 里程碑 → 未确认事项 → 开工准入 → 验收”的结构。 +> 创建日期：2026-07-28 +> 当前阶段：已确认口径下的分模块部署、联调与缺口收口 +> 总体状态：分模块已部署联调；PDA 主链仍阻断，尚未达到国内货柜履约闭环验收 +> 规划依据：`国内货柜履约开发规划.md` +> 维护方式：参考订单与客户进度表，采用“总体大任务 → 详细任务 → 里程碑 → 未确认事项 → 开工准入 → 验收”的结构。 -## 一、三期目标 +## 一、国内货柜履约目标 -三期承接二期到仓、实测、差异处理、处理单元编码和当前位置记录，完成智能排柜、订舱、拖车预约、PDA 拣货、装柜拍照、报关协同、港务信息查询，并将现有订单推进到 `LOADED`/装柜完成。 +国内货柜履约承接入库测量与计费到仓、实测、差异处理、处理单元编码和当前位置记录，完成智能排柜、订舱、拖车预约、PDA 拣货、装柜拍照、报关协同、港务信息查询，并将现有订单推进到 `LOADED`/装柜完成。 -当前验收基线已确认为 `LOADED`/装柜完成。`DELIVERED`/派送完成只能在货物到达海外仓后由海外仓可信回传推进，不属于国内三期操作和验收范围。 +当前验收基线已确认为 `LOADED`/装柜完成。`DELIVERED`/派送完成只能在货物到达海外仓后由海外仓可信回传推进，不属于国内国内货柜履约操作和验收范围。 ## 二、总体进度（大任务） | 大任务 ID | 大任务 | 范围 | 状态 | 进度 | 计划开始 | 计划完成 | 负责人 | 关键依赖/备注 | |---|---|---|---|---:|---|---|---|---| | T01 | 需求确认与原型 | 锁定阶段边界、流程依赖、排柜规则、设备、文件、报关和港务信息；完成页面原型 | 已完成 | 100% | 2026-07-28 | 2026-08-10 | 总控 | 产品确认版已同步；PDA 采用 uni-app、在线更新和 Android 广播扫描 | -| T02 | 公共契约与数据模型 | 主/子状态、权限、事件、错误码、订单三期投影、柜次、任务、证据、报关和审计模型 | 进行中 | 60% | 2026-08-10 | 待排期 | 总控 | 父子单、硬门禁、仓库角色、证据和费用契约已有真实接口；PDA batch 契约未完成 | -| T03 | 订单三期编排与柜次 | 增强现有订单列表/详情，建立父子订单-柜次关系、拆分/拼柜和时间线 | 联调中 | 80% | 2026-08-10 | 待排期 | 总控 | 父子履约树和柜次分片已通过真实验收，最终 LOADED 仍受 PDA 阻断 | +| T02 | 公共契约与数据模型 | 主/子状态、权限、事件、错误码、订单国内货柜履约投影、柜次、任务、证据、报关和审计模型 | 进行中 | 60% | 2026-08-10 | 待排期 | 总控 | 父子单、硬门禁、仓库角色、证据和费用契约已有真实接口；PDA batch 契约未完成 | +| T03 | 订单国内货柜履约编排与柜次 | 增强现有订单列表/详情，建立父子订单-柜次关系、拆分/拼柜和时间线 | 联调中 | 80% | 2026-08-10 | 待排期 | 总控 | 父子履约树和柜次分片已通过真实验收，最终 LOADED 仍受 PDA 阻断 | | T04 | 智能排柜 | 排柜规则、系统建议、冲突、人工确认和追溯 | 联调中 | 80% | 2026-08-10 | 待排期 | Admin/Firstleg | 智能装柜工作台与真实候选、计划、分配、推送接口已部署；最终完成依赖 PDA | | T05 | 订舱与港务信息 | 订舱、变更异常、船公司官网查询、更新时间和过期标识 | 联调中 | 80% | 2026-08-10 | 待排期 | Firstleg/Admin | 订舱、港务船期生命周期已通过；ZIM/COSCO 保留人工兜底 | | T06 | 拖车预约 | 服务商、车辆司机、预约时间窗、到离仓节点和异常 | 联调中 | 80% | 2026-08-10 | 待排期 | Firstleg/Admin | 预约生命周期和服务中心串联已通过，最终 LOADED 门禁待 PDA | @@ -26,7 +26,7 @@ | T08 | 装柜及柜封证据 | 装柜节点、柜号、铅封号、PDA 现场拍照、后台角色上传、多图追加、作废和复核 | 联调中 | 80% | 2026-08-10 | 待排期 | Firstleg/Admin/PDA | 五类证据、多图追加、作废和硬门禁已通过；终态仍依赖 PDA | | T09 | 报关资料与回执 | 人工资料清单、后台审核补件、线下提交代理、人工上传放行回执 | 联调中 | 70% | 2026-08-10 | 待排期 | Firstleg/Admin | 人工清单和资料版本已通过；LOADED 子订单关联受 PDA 失败级联阻断 | | T10 | 装柜完成门禁 | 校验订舱、拖车、报关放行、PDA 拣货、五类证据和锁码文本，推进 `LOADED` | 已阻塞 | 70% | 2026-08-10 | 待排期 | Firstleg | 门禁逐项读取和 fail-closed 已通过，真实推进 `LOADED` 等 PDA 修复 | -| T11 | 客户端三期协同 | 装柜进度、柜次、回执、预计开船/到港和变更时间线 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 客户不查看装柜照片和锁码；依赖 T05、T09、T10 | +| T11 | 客户端国内货柜履约协同 | 装柜进度、柜次、回执、预计开船/到港和变更时间线 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 客户不查看装柜照片和锁码；依赖 T05、T09、T10 | | T12 | 联调测试与发布 | 跨端联调、自动化测试、PDA 真机、安全、弱网、迁移、验收和发布 | 联调中 | 70% | 2026-08-10 | 待排期 | 总控/测试 | Admin、Firstleg 已分模块部署并持续真实 HTTP 验收；PDA S0500、batch 契约和真机验收未收口 | ## 三、详细任务表 @@ -37,7 +37,7 @@ |---|---|---|---|---|---|---|---:|---|---|---| | P3-T01-00 | T01 | 公共 | 需求确认与原型 | 完成需求确认表、页面清单和原型评审，锁定开工阻断项 | P0 | 已完成 | 100% | - | 总控 | 已同步产品确认版；PDA 技术路线已确认 | | P3-T02-00 | T02 | 公共 | 公共契约与数据模型 | 拆状态、权限、数据模型、接口和审计；初始化操作员/拣货员/理货员角色 | P0 | 进行中 | 60% | P3-T01-00 | 总控 | 主体契约已进入真实联调；PDA 原子 batch 仍缺 | -| P3-T03-00 | T03 | 后台/服务端 | 订单三期编排与柜次 | 实现父订单→子订单→柜次、一单多柜、拼柜、未装数量自动子订单和时间线 | P0 | 联调中 | 80% | P3-T02-00 | Order/Firstleg/Admin | 父子履约树、柜次分片与整体时间线已通过真实接口 | +| P3-T03-00 | T03 | 后台/服务端 | 订单国内货柜履约编排与柜次 | 实现父订单→子订单→柜次、一单多柜、拼柜、未装数量自动子订单和时间线 | P0 | 联调中 | 80% | P3-T02-00 | Order/Firstleg/Admin | 父子履约树、柜次分片与整体时间线已通过真实接口 | | P3-T04-00 | T04 | 后台/服务端 | 智能排柜 | 实现 110% 装载率上限、可配置税率排序、人工确认和版本追溯 | P0 | 联调中 | 80% | P3-T03-00 | Firstleg/Admin | 候选、计划、分配、调整与推送已部署；最终完成依赖 PDA | | P3-T05-00 | T05 | 后台/服务端 | 订舱与港务信息 | 订舱状态及六家船公司查询、三日周期、三次上限、过期标识 | P0 | 联调中 | 80% | P3-T03-00 | Firstleg/Admin | 港务生命周期已通过；ZIM/COSCO 为人工兜底，不算自动查询通过 | | P3-T06-00 | T06 | 后台/服务端 | 拖车预约 | 服务商、车辆司机、时间窗、到离仓和异常；完成状态供门禁校验 | P0 | 联调中 | 80% | P3-T03-00 | Firstleg/Admin | 预约、附件、历史及服务中心链路已通过真实接口 | @@ -45,25 +45,25 @@ | P3-T08-00 | T08 | PDA/后台/服务端 | 装柜及柜封证据 | 实现五类多图追加、角色上传、作废和无限期留存，客户不可见 | P0 | 联调中 | 80% | P3-T07-00 | Firstleg/Admin/PDA | 五类证据与安全边界已通过，真机拍照和终态待验收 | | P3-T09-00 | T09 | 客户端/后台/服务端 | 报关资料与回执 | 实现人工清单、补件、线下提交记录、人工放行回执上传 | P0 | 联调中 | 70% | P3-T02-00 | Firstleg/Admin | 人工协同接口已部署，最终子订单关联受 PDA 失败级联阻断 | | P3-T10-00 | T10 | 后台/服务端 | 装柜完成门禁 | 实现订舱/拖车/放行/PDA/证据硬门禁并推进 `LOADED` | P0 | 已阻塞 | 70% | P3-T07-00、P3-T08-00、P3-T09-00 | Firstleg | 门禁读取已通过；推进 LOADED 受 PDA 主链阻断 | -| P3-T11-00 | T11 | 客户端/服务端 | 客户端三期协同 | 展示柜次、装柜进度、客户可见回执和船期；不返回照片与锁码 | P0 | 待开始 | 0% | P3-T05-00、P3-T09-00、P3-T10-00 | 待分配 | - | +| P3-T11-00 | T11 | 客户端/服务端 | 客户端国内货柜履约协同 | 展示柜次、装柜进度、客户可见回执和船期；不返回照片与锁码 | P0 | 待开始 | 0% | P3-T05-00、P3-T09-00、P3-T10-00 | 待分配 | - | | P3-T12-00 | T12 | 公共 | 联调测试与发布 | 维护定向/全量真实 HTTP、PDA 真机、安全和发布回归 | P0 | 联调中 | 70% | P3-T02-00～P3-T11-00 | 总控/测试 | 已进入分模块部署验收；不得用 mock、历史资源或 coverage gap 伪装通过 | -| 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-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 | 待分配 | 按 110% 装载率上限和可配置税率排序实现 | -| P3-T05-PROTO-01 | T05 | 后台 | 订舱与出仓前船期资料原型核验 | 映射订舱列表、新增/详情、放舱、船名航次、港口和 ETD/ATD/ETA/ATA 字段 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 出仓后的六家船公司及节点查询已重新归入四期 | -| P3-T06-PROTO-01 | T06 | 后台 | 拖车原型核验 | 映射拖车列表、新增表单、运输公司、司机、车头号、装箱日期、费用和附件 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 预约时间窗和到离仓节点仍需按三期流程补充 | +| P3-T05-PROTO-01 | T05 | 后台 | 订舱与出仓前船期资料原型核验 | 映射订舱列表、新增/详情、放舱、船名航次、港口和 ETD/ATD/ETA/ATA 字段 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 出仓后的六家船公司及节点查询已重新归入海外仓业务 | +| 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-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-T11-PROTO-01 | T11 | 客户端 | 客户端三期原型 | 新增装柜进度、报关资料上传/补件、回执下载和出仓前船期资料展示 | P0 | 待开始 | 0% | P3-Q7～P3-Q9、P3-Q12 | 待分配 | 出仓后船节点页面归四期 | +| P3-T11-PROTO-01 | T11 | 客户端 | 客户端国内货柜履约原型 | 新增装柜进度、报关资料上传/补件、回执下载和出仓前船期资料展示 | P0 | 待开始 | 0% | P3-Q7～P3-Q9、P3-Q12 | 待分配 | 出仓后船节点页面归海外仓业务 | ## 四、原型对照与开发影响 | 大任务 | `docs/悦` 现有原型 | 覆盖判断 | 开发处理 | |---|---|---|---| -| T03 订单三期编排与柜次 | 现有订单列表/详情、货柜列表、装柜清单 | 部分参考 | 增强现有订单页并建立订单-柜次关联，不新增出仓单页面 | +| T03 订单国内货柜履约编排与柜次 | 现有订单列表/详情、货柜列表、装柜清单 | 部分参考 | 增强现有订单页并建立订单-柜次关联，不新增出仓单页面 | | T04 智能排柜 | 入库单列表中的“智能装柜”弹窗 | 已有参考 | 复用线路、筛选、锁定、分柜和拖放交互，按 P3-Q1 裁剪规则 | | T05 订舱与港务信息 | 订舱列表、新增/详情、放舱、货柜船期字段 | 已有参考 | 复用订舱字段和页面结构，确认港务信息范围及来源后裁剪 | | T06 拖车预约 | 拖车列表、新增拖车 | 已有参考 | 复用车辆司机和费用字段，补预约时间窗、到仓及离仓节点 | @@ -71,9 +71,9 @@ | T08 装柜及柜封证据 | 货柜列表、预装清单、装柜清单 | 部分参考 | 后台页面裁剪复用；PDA 只拍照，Admin 可上传，同类型多张追加，错图作废 | | T09 报关资料与回执 | 报关单列表、单证管理、装柜清单附件 | 部分参考 | 后台裁剪复用；客户上传、补件和回执下载页面新建 | | T10 装柜完成门禁 | 现有订单状态操作和分散证据字段 | 部分参考 | 在订单详情补门禁检查和确认装柜完成；不提供在线冲正或国内确认派送 | -| T11 客户端三期协同 | 头程下单客户端只有船期字段和少量装柜摘要 | 覆盖不足 | 新建三期客户端装柜进度、报关和港务信息页面 | +| T11 客户端国内货柜履约协同 | 头程下单客户端只有船期字段和少量装柜摘要 | 覆盖不足 | 新建国内货柜履约客户端装柜进度、报关和港务信息页面 | -> `货代SaaS平台原型.html` 是全量平台参考原型，其中海外仓、完整 WMS、费用和清关能力不自动纳入三期；所有复用项仍需经过三期范围裁剪。 +> `货代SaaS平台原型.html` 是全量平台参考原型，其中海外仓、完整 WMS、费用和清关能力不自动纳入国内货柜履约；所有复用项仍需经过国内货柜履约范围裁剪。 ## 五、建议拆分模板 @@ -93,26 +93,26 @@ | 里程碑 | 交付目标 | 状态 | 计划完成 | |---|---|---|---| | P3-M0 需求与原型锁定 | 阶段边界、流程、规则、设备、文件和页面原型确认 | 已完成 | 2026-08-10 | -| P3-M1 公共契约 | 二三期输入、状态、权限、数据模型和接口契约稳定 | 进行中 | 待排期 | -| P3-M2 订单三期编排 | 现有订单、柜次、排柜、订舱、港务和拖车可关联追溯 | 联调中 | 待排期 | +| P3-M1 公共契约 | 入库测量与计费及国内货柜履约输入、状态、权限、数据模型和接口契约稳定 | 进行中 | 待排期 | +| P3-M2 订单国内货柜履约编排 | 现有订单、柜次、排柜、订舱、港务和拖车可关联追溯 | 联调中 | 待排期 | | P3-M3 仓内出仓 | PDA 拣货、复核、装柜和柜封证据闭环 | 已阻塞 | 待排期 | | P3-M4 报关协同 | 客户资料、后台审核、提交代理、回执上传下载闭环 | 联调中 | 待排期 | | P3-M5 装柜完成 | 订舱、拖车、放行回执、PDA 和证据门禁满足后进入 `LOADED`；后续错误线下处理 | 已阻塞 | 待排期 | -| P3-M6 三期上线 | 联调、真机、安全、测试、验收和生产发布完成 | 进行中 | 待排期 | +| P3-M6 国内货柜履约上线 | 联调、真机、安全、测试、验收和生产发布完成 | 进行中 | 待排期 | ## 七、未确认事项（需求确认进度） -当前 13 项主确认事项均已有产品最终结论；P3-Q4 已确认采用 uni-app、在线更新与 Android 广播扫描。完整结论统一维护在 [三期需求确认表](三期需求确认表.md)。 +当前 13 项主确认事项均已有产品最终结论；P3-Q4 已确认采用 uni-app、在线更新与 Android 广播扫描。完整结论统一维护在 [国内货柜履约需求确认表](国内货柜履约需求确认表.md)。 -验收拆分已建立：PDA 进入任务、拣货幂等/版本冲突、五类证据真实上传、多图追加和锁码门禁进入自动化；真机在线、设备草稿批量提交、证据作废、设备与权限留存等仍保留 coverageGap，详见[三期验收任务拆分与待确认清单](三期验收任务拆分与待确认清单.md)。 +验收拆分已建立：PDA 进入任务、拣货幂等/版本冲突、五类证据真实上传、多图追加和锁码门禁进入自动化；真机在线、设备草稿批量提交、证据作废、设备与权限留存等仍保留 coverageGap，详见[国内货柜履约验收任务拆分与待确认清单](国内货柜履约验收任务拆分与待确认清单.md)。 | 编号 | 阻断级别 | 待确认事项 | 状态 | 主要影响 | |---|---|---|---|---| | P3-Q1 | 开工阻断 | 智能排柜的硬约束和软偏好 | 已确认 | T04 智能排柜、T07 拣货任务 | -| P3-Q2 | 开工阻断 | 是否支持拼柜、一单多柜和拆批装柜 | 已确认 | T03 订单三期编排与柜次、T04 智能排柜 | +| P3-Q2 | 开工阻断 | 是否支持拼柜、一单多柜和拆批装柜 | 已确认 | T03 订单国内货柜履约编排与柜次、T04 智能排柜 | | P3-Q3 | 非阻断 | “预约托车”是否统一为“预约拖车” | 已确认 | T06 拖车预约、页面与接口文案 | | P3-Q4 | 非阻断 | PDA 开发、扫描与发布方式 | 已确认 | 采用 uni-app 开发并支持在线更新；Android 广播模式已接入，设备型号不构成门禁 | -| P3-Q5 | 开工阻断 | 拣货是否依赖实时库存和库位可用量 | 已确认 | 复用二期实时库存、当前位置和可用量接口；不扩展完整 WMS | +| P3-Q5 | 开工阻断 | 拣货是否依赖实时库存和库位可用量 | 已确认 | 复用入库测量与计费实时库存、当前位置和可用量接口；不扩展完整 WMS | | P3-Q6 | 模块阻断 | 装柜照片和锁码规则 | 已确认 | 五类多图、角色上传、无限期保留、客户不可见 | | P3-Q7 | 模块阻断 | 报关资料清单是否按国家、渠道和货物类型变化 | 已确认 | T09 报关资料、文件版本 | | P3-Q8 | 模块阻断 | 报关代理接收资料和返回回执的方式 | 已确认 | 线下提交、人工上传回执 | @@ -120,22 +120,22 @@ | P3-Q10 | 模块阻断 | 装柜完成后的错误处理和冲正方式 | 已确认 | 线下人工处理，不提供在线冲正 | | P3-Q11 | 开工阻断 | 九个动作的强制前置和并行关系 | 已确认 | 订舱/拖车/放行/PDA/证据为硬门禁；单柜次单人 | | P3-Q12 | 开工阻断 | 报关回执类型及海关放行是否为装柜完成硬门禁 | 已确认 | 有效放行回执为硬门禁，人工上传 | -| P3-Q13 | 开工阻断 | 三期终点 | 已确认 | `LOADED`/装柜完成；`DELIVERED` 由海外仓回传，移出三期验收 | +| P3-Q13 | 开工阻断 | 国内货柜履约终点 | 已确认 | `LOADED`/装柜完成；`DELIVERED` 由海外仓回传，移出国内货柜履约验收 | ## 八、开工准入记录 -三期已进入分模块部署联调。下表保留开工条件及当前补齐状态，用于检查契约、原型和任务拆分是否仍有缺口，不再作为“尚未开始开发”的结论。 +国内货柜履约已进入分模块部署联调。下表保留开工条件及当前补齐状态，用于检查契约、原型和任务拆分是否仍有缺口，不再作为“尚未开始开发”的结论。 | 准入编号 | 准入条件 | 当前状态 | 责任方 | 完成证据 | |---|---|---|---|---| -| P3-GO-01 | P3-Q1～P3-Q13 均形成产品结论 | 已完成 | 产品、业务 | `三期需求确认表.md` 已同步最终结论 | +| P3-GO-01 | P3-Q1～P3-Q13 均形成产品结论 | 已完成 | 产品、业务 | `国内货柜履约需求确认表.md` 已同步最终结论 | | P3-GO-02 | 确认结论已同步开发规划、进度表、页面清单和验收范围 | 已完成 | 产品、项目负责人 | README、进度表、页面清单和验收口径已按确认版同步 | -| P3-GO-03 | 关键缺失原型已补齐并评审，包括订单装柜完成门禁、客户端三期页面和 PDA 五类多图拍照 | 进行中 | 产品、设计、业务 | 页面清单中的关键页面达到已确认状态 | -| P3-GO-04 | T02 公共契约完成，二期输入、状态机、权限、数据模型、接口、错误码和审计口径稳定 | 进行中 | 前后端、架构/技术负责人 | 主体契约已部署；PDA 原子 batch 契约仍缺 | +| P3-GO-03 | 关键缺失原型已补齐并评审，包括订单装柜完成门禁、客户端国内货柜履约页面和 PDA 五类多图拍照 | 进行中 | 产品、设计、业务 | 页面清单中的关键页面达到已确认状态 | +| P3-GO-04 | T02 公共契约完成，入库测量与计费输入、状态机、权限、数据模型、接口、错误码和审计口径稳定 | 进行中 | 前后端、架构/技术负责人 | 主体契约已部署；PDA 原子 batch 契约仍缺 | | P3-GO-05 | T03～T12 已拆成 RULE、DATA、API、ADM/CLI/PDA、TEST、ACCEPT 任务，并填写负责人和计划 | 进行中 | 项目负责人、研发、测试 | 已按独立任务推进；客户端、PDA batch 和真机验收任务仍需收口 | | P3-GO-06 | 产品、业务、研发和测试完成开工评审，确认范围、依赖、风险和首批任务 | 进行中 | 项目负责人 | 产品范围已确认并开工，正式评审证据仍需归档 | -当前口径：未完成的准入项作为收口风险继续跟踪，不回退已经开始的开发和联调；只有契约、真机和真实 HTTP 验收全部完成后，才能标记三期完成。 +当前口径：未完成的准入项作为收口风险继续跟踪，不回退已经开始的开发和联调；只有契约、真机和真实 HTTP 验收全部完成后，才能标记国内货柜履约完成。 ## 九、状态维护规则 @@ -150,5 +150,5 @@ 1. 修复 PDA `pick` 第二处 `S0500`，复跑领取、拣货、复核、报关关联和装柜完成链路。 2. 独立实现 PDA 原子 batch 契约及测试，覆盖整批事务、幂等、服务端库存快照和失败回滚。 3. 完成 PDA 真机广播扫码、在线草稿、五类证据拍照、多图追加和作废验收。 -4. 收口 T11 客户端三期页面及客户可见性、安全边界。 -5. 复跑三期定向和默认全量真实 HTTP 验收，完成发布记录后再评估三期完成状态。 +4. 收口 T11 客户端国内货柜履约页面及客户可见性、安全边界。 +5. 复跑国内货柜履约定向和默认全量真实 HTTP 验收，完成发布记录后再评估国内货柜履约完成状态。 diff --git a/三期/三期开工门禁.md b/国内货柜履约/国内货柜履约开工门禁.md similarity index 73% rename from 三期/三期开工门禁.md rename to 国内货柜履约/国内货柜履约开工门禁.md index d227a9f..2f7d818 100644 --- a/三期/三期开工门禁.md +++ b/国内货柜履约/国内货柜履约开工门禁.md @@ -1,20 +1,20 @@ -# 三期开工门禁 +# 国内货柜履约开工门禁 -> 本文维护三期跨端开发的稳定门禁。实时任务进度见 `三期开发进度表.md`；产品决策以 `三期需求确认表.md` 为准。 +> 本文维护国内货柜履约跨端开发的稳定门禁。实时任务进度见 `国内货柜履约开发进度表.md`；产品决策以 `国内货柜履约需求确认表.md` 为准。 ## 可直接开展的范围 - 已确认规则可进入契约、数据、接口、页面和测试拆分，不需要等待整期所有模块完成。 -- 订单继续承载三期主状态，不新建独立出仓单；支持父订单、子订单与柜次关系，以及一单多柜和多订单拼柜。 +- 订单继续承载国内货柜履约主状态，不新建独立出仓单；支持父订单、子订单与柜次关系，以及一单多柜和多订单拼柜。 - 智能排柜、订舱与船期、拖车预约、PDA 在线拣货、五类装柜证据、人工报关回执和 `LOADED` 服务端门禁按需求确认表执行。 -- 三期国内终点为 `LOADED`；`DELIVERED` 只由海外仓可信回传推进。 +- 国内货柜履约的国内终点为 `LOADED`；`DELIVERED` 只由海外仓可信回传推进。 ## 跨端硬边界 - `LOADED` 前必须由服务端校验订舱完成、拖车完成、有效报关放行回执、PDA 拣货完成和五类有效证据完整；国内 Admin/PDA 不提供在线冲正或手工推进 `DELIVERED`。 - PDA 正式作业仅在线；单柜次只允许一名作业员，不支持多人并行、任务接管或换班释放。进入任务即由服务端标记拣货中，扫描草稿按作业员、任务和柜次隔离，提交时批量写入。 - 每类证据至少一张有效照片，允许同类型追加；错误照片只能作废并保留审计。客户不可见照片与锁码。 -- 前端页面、菜单和路由只能在对应服务端契约、权限和数据模型稳定后发布；原型中的完整 WMS、海外仓及未确认能力不属于三期默认范围。 +- 前端页面、菜单和路由只能在对应服务端契约、权限和数据模型稳定后发布；原型中的完整 WMS、海外仓及未确认能力不属于国内货柜履约默认范围。 ## 局部阻断项 @@ -24,6 +24,6 @@ ## 使用方式 -1. 先读 `README.md`、`三期需求确认表.md` 和本文件，确认任务属于已确认范围。 +1. 先读 `README.md`、`国内货柜履约需求确认表.md` 和本文件，确认任务属于已确认范围。 2. 再进入目标应用或服务的 `AGENTS.md`，按本地模块入口实现。 3. 发现新的产品决策或门禁变化时，先更新确认表与本文，再更新受影响模块指引；不要将短期进度、联调故障或环境地址写回模块规则。 diff --git a/三期/三期装柜闭环产品确认表-2026-08-08.md b/国内货柜履约/国内货柜履约装柜闭环产品确认表-2026-08-08.md similarity index 96% rename from 三期/三期装柜闭环产品确认表-2026-08-08.md rename to 国内货柜履约/国内货柜履约装柜闭环产品确认表-2026-08-08.md index 004772d..b43b294 100644 --- a/三期/三期装柜闭环产品确认表-2026-08-08.md +++ b/国内货柜履约/国内货柜履约装柜闭环产品确认表-2026-08-08.md @@ -1,4 +1,4 @@ -# 三期装柜闭环产品确认表 +# 国内货柜履约装柜闭环产品确认表 > 确认方式：产品只需在“产品确认”一列填写“同意”，或写明修改后的规则。 > 会议目标：本表确认后直接进入开发，不再补完整高保真原型。 @@ -8,7 +8,7 @@ | 事项 | 已确认结论 | |---|---| | 是否新增出仓单 | 不新增，全部状态继续放在现有订单列表和订单详情中 | -| 国内三期做到哪里结束 | 国内做到“装柜完成”即结束 | +| 国内国内货柜履约做到哪里结束 | 国内做到“装柜完成”即结束 | | 海外仓状态由谁更新 | 货物到达海外仓后，由海外仓回传；国内人员不能手工确认 | | 装柜需要哪些照片 | 空仓、半仓、满仓、锁仓、带锁码照片五类；每类至少 1 张有效照片，同类型允许多张 | | 是否填写锁码 | 必填 | @@ -37,7 +37,7 @@ | 13 | 一个订单分到多个柜时，什么时候算订单“装柜完成”？ | 建议该订单关联的所有柜次都完成装柜后，订单才显示“装柜完成” | 待确认 | | 14 | 装柜完成后发现错柜、错照片或错锁码，由谁更正？ | 建议只有平台指定角色可以更正，必须填写原因并保留修改前记录 | 待确认 | | 15 | 现有“派送完成”状态是否改名？ | 建议改为“海外仓已收货”，避免误解为国内派送或末端派送 | 待确认 | -| 16 | 海外仓回传后，国内是否还能更改装柜信息？ | 建议不能直接更改，需走单独异常处理流程，不纳入本次三期开发 | 待确认 | +| 16 | 海外仓回传后，国内是否还能更改装柜信息？ | 建议不能直接更改，需走单独异常处理流程，不纳入本次国内货柜履约开发 | 待确认 | | 17 | 五类照片需要保存多久？ | 请产品、业务或合规给出期限；未确认前不做自动删除 | 待确认 | | 18 | 客户是否可以查看五类装柜照片和锁码？ | 建议客户可查看照片和锁码；如存在内部证据，应明确哪些照片仅平台可见 | 待确认 | | 19 | 同一柜次是否允许多人并行拣货？ | 待产品确认任务拆分、数量合并、重复扫描和责任归属；未确认前按单任务单作业员设计，但不固化为不可扩展模型 | 待确认 | diff --git a/三期/三期装柜闭环开发前确认单-2026-08-08.md b/国内货柜履约/国内货柜履约装柜闭环开发前确认单-2026-08-08.md similarity index 92% rename from 三期/三期装柜闭环开发前确认单-2026-08-08.md rename to 国内货柜履约/国内货柜履约装柜闭环开发前确认单-2026-08-08.md index 1301f99..9f4f622 100644 --- a/三期/三期装柜闭环开发前确认单-2026-08-08.md +++ b/国内货柜履约/国内货柜履约装柜闭环开发前确认单-2026-08-08.md @@ -1,4 +1,4 @@ -# 三期装柜闭环开发前确认单 +# 国内货柜履约装柜闭环开发前确认单 > 整理日期：2026-08-08 > 用途：产品、业务、仓库、研发在直接开发前确认最小闭环细节 @@ -6,8 +6,8 @@ ## 一、已确认，不再重复讨论 -1. 三期不新增独立出仓单，现有订单列表和订单详情承载三期主状态。 -2. 国内三期终点为 `LOADED`/装柜完成。 +1. 国内货柜履约不新增独立出仓单，现有订单列表和订单详情承载国内货柜履约主状态。 +2. 国内国内货柜履约终点为 `LOADED`/装柜完成。 3. `DELIVERED` 只能在货物到达海外仓后由海外仓可信回传推进，国内 Admin/PDA 不提供手工操作。 4. 空仓、半仓、满仓、锁仓、带锁码照五类证据各至少提交 1 张有效真实图片，可同类型多张追加；带锁码照同时填写锁码文本。 5. PDA 只能现场拍照，Admin 可人工上传；错图不硬删除，以作废记录保留原因、操作人和时间。 @@ -75,7 +75,7 @@ DELIVERED / 海外仓已收货 ### 4.3 Admin 订单详情 -- 在现有订单详情增加“三期作业”区域，不新增出仓单详情。 +- 在现有订单详情增加“国内货柜履约作业”区域，不新增出仓单详情。 - 展示柜次、柜号、拣货进度、五类证据、锁码、各子流程摘要和整体时间线。 - 门禁未通过时展示具体阻塞项，例如“半仓照未上传”“拣货差异待复核”。 - `LOADED` 后隐藏普通编辑动作，仅授权角色可发起冲正。 @@ -109,7 +109,7 @@ DELIVERED / 海外仓已收货 - `LOADED` 后：禁止直接覆盖证据或修改数据库状态，必须发起冲正。 - 冲正记录原因、申请人、审核/执行人、前后状态、原证据版本和请求关联 ID。 - 冲正后重新满足门禁才能再次进入 `LOADED`。 -- 已由海外仓回传进入 `DELIVERED` 后，国内冲正是否允许必须单独制定跨阶段处理规则；三期首版不提供该操作。 +- 已由海外仓回传进入 `DELIVERED` 后，国内冲正是否允许必须单独制定跨业务域处理规则；国内货柜履约当前不提供该操作。 ## 七、验收用例 @@ -132,8 +132,8 @@ DELIVERED / 海外仓已收货 ## 八、本次不自动纳入 - 不新增独立出仓单和对应列表/详情。 -- 不把装船、清关、海外仓入库、海外仓出库和末端派送纳入国内三期。 -- 报关、Client 回执和港务信息是否作为三期上线必交付，以产品对 P3-Q7/P3-Q8/P3-Q9/P3-Q12 的结论为准。 +- 不把装船、清关、海外仓入库、海外仓出库和末端派送纳入国内国内货柜履约。 +- 报关、Client 回执和港务信息是否作为国内货柜履约上线必交付，以产品对 P3-Q7/P3-Q8/P3-Q9/P3-Q12 的结论为准。 - 未确认前，不把订舱、拖车和报关默认设置为 `LOADED` 硬门禁。 ## 九、会议输出 @@ -141,6 +141,6 @@ DELIVERED / 海外仓已收货 产品确认后应形成以下结果： 1. C1 至 C12 均填写最终结论；不能确认的事项明确排除范围和临时方案。 -2. 更新 `三期需求确认表.md` 中对应的 P3-Q2/P3-Q4/P3-Q5/P3-Q6/P3-Q10/P3-Q11/P3-Q12。 +2. 更新 `国内货柜履约需求确认表.md` 中对应的 P3-Q2/P3-Q4/P3-Q5/P3-Q6/P3-Q10/P3-Q11/P3-Q12。 3. 明确是否允许按“服务端门禁 -> PDA -> Admin -> 联调验收”的顺序直接开发。 4. 将本清单作为接口、页面和测试验收的共同依据。 diff --git a/三期/三期闭环审计报告-2026-08-08.md b/国内货柜履约/国内货柜履约闭环审计报告-2026-08-08.md similarity index 69% rename from 三期/三期闭环审计报告-2026-08-08.md rename to 国内货柜履约/国内货柜履约闭环审计报告-2026-08-08.md index 18d61de..7313354 100644 --- a/三期/三期闭环审计报告-2026-08-08.md +++ b/国内货柜履约/国内货柜履约闭环审计报告-2026-08-08.md @@ -1,15 +1,15 @@ -# 虫虫出海三期闭环审计报告 +# 虫虫出海国内货柜履约闭环审计报告 -> 审计日期：2026-08-08 -> 审计范围：二期终点→智能排柜→订舱→拖车→PDA 拣货→装柜/柜封证据→`LOADED`/装柜完成 -> 审计对象：Admin、Client、PDA、`baiyue-firstleg` 后端、OpenAPI/SQL、自动化测试与现有测试环境报告 -> 结论：**NO-GO，当前不能按“三期业务闭环”验收** +> 审计日期：2026-08-08 +> 审计范围：入库测量与计费终点→智能排柜→订舱→拖车→PDA 拣货→装柜/柜封证据→`LOADED`/装柜完成 +> 审计对象：Admin、Client、PDA、`baiyue-firstleg` 后端、OpenAPI/SQL、自动化测试与现有测试环境报告 +> 结论：**NO-GO，当前不能按“国内货柜履约业务闭环”验收** ## 1. 执行摘要 -当前已实现多个真实持久化的三期子能力，不是纯页面原型：智能装柜/预装、订舱、拖车、PDA 拣货接口、装柜证据元数据和装柜清单均已有后端实现，订舱和拖车 API 也已在测试环境完成独立生命周期验证。 +当前已实现多个真实持久化的国内货柜履约子能力，不是纯页面原型：智能装柜/预装、订舱、拖车、PDA 拣货接口、装柜证据元数据和装柜清单均已有后端实现，订舱和拖车 API 也已在测试环境完成独立生命周期验证。 -用户已于 2026-08-08 确认：**三期不新建独立出仓单，现有订单列表就是主流程承载面；国内三期以 `LOADED`/装柜完成为终点**。`DELIVERED`/派送完成只能在货物到达海外仓后由海外仓可信回传推进，不属于国内三期操作和验收范围。因此“没有出仓单”不再是缺口；真正的缺口是现有订单与柜次、订舱、拖车、拣货、装柜证据和报关子流程尚未统一编排，服务端也没有为进入 `LOADED` 提供组合门禁。 +用户已于 2026-08-08 确认：**国内货柜履约不新建独立出仓单，现有订单列表就是主流程承载面；国内国内货柜履约以 `LOADED`/装柜完成为终点**。`DELIVERED`/派送完成只能在货物到达海外仓后由海外仓可信回传推进，不属于国内国内货柜履约操作和验收范围。因此“没有出仓单”不再是缺口；真正的缺口是现有订单与柜次、订舱、拖车、拣货、装柜证据和报关子流程尚未统一编排，服务端也没有为进入 `LOADED` 提供组合门禁。 最重要的判断是： @@ -17,13 +17,13 @@ - **订舱和拖车是可独立运行的业务模块，但尚未与出仓主链强绑定。** - **报关资料/补件/代理提交/回执/客户下载基本未建模。** - **现有订单进入 `LOADED` 的统一门禁和冲正尚未闭合；平台手工推进 `DELIVERED` 的现有接口与最新业务边界冲突。** -- **Client 没有三期协同入口，PDA 仍是演示数据与真实接口混合，尚未完成真实身份、任务领取、文件上传和真机验收。** +- **Client 没有国内货柜履约协同入口，PDA 仍是演示数据与真实接口混合，尚未完成真实身份、任务领取、文件上传和真机验收。** ## 2. 闭环判定口径 -本次不以“有页面”、“有 Controller”或“单模块测试全绿”作为闭环标准。三期只有同时满足以下条件才算闭环： +本次不以“有页面”、“有 Controller”或“单模块测试全绿”作为闭环标准。国内货柜履约只有同时满足以下条件才算闭环： -1. 同一个真实客户订单能从二期终点 `WAIT_SPLIT + APPROVED + CONFIRMED` 进入三期。 +1. 同一个真实客户订单能从入库测量与计费终点 `WAIT_SPLIT + APPROVED + CONFIRMED` 进入国内货柜履约。 2. 同一订单可追溯所属柜次、排柜方案、订舱、拖车、拣货、装柜证据、报关文件与回执。 3. 服务端独立校验所有强制前置，不能靠页面按钮顺序保证。 4. 弱网、重复提交、并发、越权、证据缺失和冲正均有明确行为和审计记录。 @@ -31,42 +31,42 @@ 6. 订单能在服务端门禁通过后进入 `LOADED`/装柜完成；国内端不能手工推进 `DELIVERED`。 7. 有一条测试环境证据，让同一业务对象贯穿全流程，并完成负向门禁验证。 -## 3. 三期业务矩阵 +## 3. 国内货柜履约业务矩阵 | 环节 | 当前能力 | 审计结论 | 主要缺口 | 优先级 | |---|---|---|---|---| -| 二期入口 | 统一订单已有 `WAIT_SPLIT` 投影 | 部分具备 | 没有一条验收数据从二期贯穿到三期终点 | P0 | -| 订单三期主编排 | 订单列表已承载待分柜、装柜中、装柜完成等状态 | 部分具备 | 无订单级统一门禁、子流程关联和整体时间线；不需新建出仓单 | P0 | +| 入库测量与计费入口 | 统一订单已有 `WAIT_SPLIT` 投影 | 部分具备 | 没有一条验收数据从入库测量与计费贯穿到国内货柜履约终点 | P0 | +| 订单国内货柜履约主编排 | 订单列表已承载待分柜、装柜中、装柜完成等状态 | 部分具备 | 无订单级统一门禁、子流程关联和整体时间线；不需新建出仓单 | P0 | | 智能排柜 | 有容量型推荐、预装和持久化 | 部分具备 | 无业务硬约束/软偏好规则版本、冲突解释、独立方案确认和版本对比 | P0 | | 订舱/船期 | 后端生命周期可用，测试环境 API 已通过 | 部分具备 | Admin 创建/版本/返回 DTO 存在契约错配；未与订单/柜次强关联；无数据来源和时效语义 | P0 | -| 拖车预约 | 后端和 Admin 正式模块已存在，API 生命周期已验证 | 部分具备 | 与订单三期编排未汇聚；前端需手填多个关联 ID；附件上传未接入；幂等重放不完整 | P0 | +| 拖车预约 | 后端和 Admin 正式模块已存在，API 生命周期已验证 | 部分具备 | 与订单国内货柜履约编排未汇聚；前端需手填多个关联 ID；附件上传未接入；幂等重放不完整 | P0 | | PDA 拣货 | 有柜次级拣货服务和入库单级汇总接口 | 部分具备 | 两套语义可互相绕过；无领取/分配/复核/异常挂起/撤销闭环；未校验实时处理单元与库位量 | P0 | | 装柜/柜封证据 | 有证据元数据和 File 归属校验 | 部分具备 | 已确认空仓、半仓、满仓、锁仓、带锁码照共 5 张必传，锁码文本必填；当前 Admin/PDA 真实文件上传和服务端硬门禁未实现 | P0 | | 客户上传报关资料 | Client 无正式入口 | **未具备** | 无清单版本、上传、补件、进度和客户隔离契约 | P0 | | 平台报关协同 | 仅有历史文档类型占位 | **未具备** | 无审核退回、补件、代理提交批次、文件版本冻结 | P0 | | 回执上传/客户下载 | 无业务模型和页面 | **未具备** | 无回执类型、版本、可见范围、下载授权和门禁关联 | P0 | -| 出仓后港务/船节点查询 | 订舱实体有 ETD/ETA、船名航次等字段 | 已重新归入四期 | 本历史审计发现的来源、更新时间、过期标识和客户查询端缺口由四期承接，不再作为三期闭环缺口 | 四期 | +| 出仓后港务/船节点查询 | 订舱实体有 ETD/ETA、船名航次等字段 | 已重新归入海外仓业务 | 本历史审计发现的来源、更新时间、过期标识和客户查询端缺口由海外仓业务承接，不再作为国内货柜履约闭环缺口 | 海外仓业务 | | 装柜完成门禁 | 有 `LOADING -> LOADED`，但当前可无证据完成 | **未具备** | 未强制校验 PDA 拣货、5 张真实图片和锁码文本；无冲正 | P0 | -| 海外仓回传边界 | 有平台手工 `DELIVERED` 动作 | **契约冲突** | 国内端可手工推进派送完成；缺海外仓可信来源、签名、防重放、幂等和审计契约 | P0/跨阶段 | -| 客户三期可见性 | 订单详情有拣货/装柜少量只读摘要 | 严重不足 | 无柜次、报关、回执、船期变更时间线 | P0 | +| 海外仓回传边界 | 有平台手工 `DELIVERED` 动作 | **契约冲突** | 国内端可手工推进派送完成；缺海外仓可信来源、签名、防重放、幂等和审计契约 | P0/跨业务域 | +| 客户国内货柜履约可见性 | 订单详情有拣货/装柜少量只读摘要 | 严重不足 | 无柜次、报关、回执、船期变更时间线 | P0 | ## 4. 核心阻断项 -### P0-1：现有订单缺少三期统一编排和服务端门禁 +### P0-1：现有订单缺少国内货柜履约统一编排和服务端门禁 -产品已确认不新建独立出仓单，因此应复用现有订单作为三期主对象，柜次作为多订单共享的执行对象。当前问题不是少一张单，而是订单状态与各子流程尚未由统一编排器计算。 +产品已确认不新建独立出仓单，因此应复用现有订单作为国内货柜履约主对象，柜次作为多订单共享的执行对象。当前问题不是少一张单，而是订单状态与各子流程尚未由统一编排器计算。 当前实际是四条彼此独立的状态链： ```text 装柜计划：EDITING -> LOADING -> COMPLETED -订单国内三期：WAIT_SPLIT -> LOADING -> LOADED +订单国内国内货柜履约：WAIT_SPLIT -> LOADING -> LOADED 海外仓后续回传：LOADED -> DELIVERED 订舱：DRAFT -> SUBMITTED -> CONFIRMED -> RELEASED 拖车：DRAFT -> ... -> DEPARTED -> COMPLETED ``` -订单上没有一个汇聚节点计算“是否可进入下一状态”，因此即使四条链各自通过，也不等于三期闭环。应在现有订单/入库履约聚合上增加统一编排，不应新建重复的出仓单业务对象。 +订单上没有一个汇聚节点计算“是否可进入下一状态”，因此即使四条链各自通过，也不等于国内货柜履约闭环。应在现有订单/入库履约聚合上增加统一编排，不应新建重复的出仓单业务对象。 ### P0-2：装柜完成可绕过拣货和柜封证据 @@ -78,11 +78,11 @@ - 铅封号是否重复； - 订舱、拖车和报关是否属于进入 `LOADED` 的硬门禁（P3-Q11/P3-Q12 尚待确认）。 -现有单元测试 `completesLoadingWithoutEvidenceGate` 还把“无证据也可完成”固化成预期，与三期规划直接冲突。 +现有单元测试 `completesLoadingWithoutEvidenceGate` 还把“无证据也可完成”固化成预期，与国内货柜履约规划直接冲突。 ### P0-3：国内端可手工推进海外仓状态 -当前存在平台手工完成派送的 `POST /delivery/complete` 能力，但最新业务确认是：只有货物到达海外仓后，才能由海外仓可信回传推进 `DELIVERED`。因此该操作必须从国内 Admin/PDA 的三期入口移除或禁用；后续海外仓回传接口需单独定义来源认证、签名/时间窗、防重放、幂等和审计。该接口整改是状态边界修复，但海外仓业务本身不纳入三期验收。 +当前存在平台手工完成派送的 `POST /delivery/complete` 能力，但最新业务确认是：只有货物到达海外仓后，才能由海外仓可信回传推进 `DELIVERED`。因此该操作必须从国内 Admin/PDA 的国内货柜履约入口移除或禁用；后续海外仓回传接口需单独定义来源认证、签名/时间窗、防重放、幂等和审计。该接口整改是状态边界修复，但海外仓业务本身不纳入国内货柜履约验收。 ### P0-4：报关协同和回执链路未实现 @@ -122,7 +122,7 @@ PDA 已有调用拣货/证据/装柜接口的适配代码，但当前仍存在 ## 5. 已实现且可保留的能力 -本次 NO-GO 不代表三期必须重做。以下能力已有明确复用价值： +本次 NO-GO 不代表国内货柜履约必须重做。以下能力已有明确复用价值： - 柜次、智能装柜、预装和装柜清单的持久化模型。 - 订舱 `DRAFT -> SUBMITTED -> CONFIRMED -> RELEASED` 生命周期、历史和幂等。 @@ -130,7 +130,7 @@ PDA 已有调用拣货/证据/装柜接口的适配代码，但当前仍存在 - 柜次级 PDA 明细拣货、部分拣货和跳过与防重操作。 - 装柜证据文件归属校验、业务历史、乐观锁和部分幂等基础。 - Admin 订舱和拖车页面壳、统一订单后半程组件。 -- Client 对统一订单三期只读摘要的兼容映射。 +- Client 对统一订单国内货柜履约只读摘要的兼容映射。 ## 6. 需求确认项重新定性 @@ -148,7 +148,7 @@ PDA 已有调用拣货/证据/装柜接口的适配代码，但当前仍存在 | P3-Q9 港务 | 仅有订舱船期字段 | 仍为 P1，但必须在客户展示前确认 | | P3-Q10 冲正 | 无 reverse 动作 | 仍为 P0 高风险状态阻断 | | P3-Q11 强制前置/并行 | 子模块彼此独立 | 仍为 P0 统一门禁阻断 | -| P3-Q13 三期终点 | 已确认国内终点为 `LOADED`；`DELIVERED` 由海外仓回传 | 已解除范围阻断；需整改国内手工派送接口 | +| P3-Q13 国内货柜履约终点 | 已确认国内终点为 `LOADED`；`DELIVERED` 由海外仓回传 | 已解除范围阻断；需整改国内手工派送接口 | ## 7. 自动化和环境证据 @@ -167,13 +167,13 @@ PDA 已有调用拣货/证据/装柜接口的适配代码，但当前仍存在 `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 拣货和最终装柜清单。该结论应改名为“三期装柜子链路通过”，不应作为整期闭环证据。 +`docs/入库测量与计费及国内货柜履约业务功能测试回归报告.md` 在 2026-08-07 将“国内货柜履约结果”写为通过，但其明确的国内货柜履约测试范围只有：虚拟柜、智能装柜、预装、PDA 拣货和最终装柜清单。该结论应改名为“国内货柜履约装柜子链路通过”，不应作为整期闭环证据。 ### 7.3 测试缺口 当前缺少以下验收证据： -- 同一订单从二期 `WAIT_SPLIT` 贯穿到三期终点。 +- 同一订单从入库测量与计费 `WAIT_SPLIT` 贯穿到国内货柜履约终点。 - 订舱、拖车、柜次、拣货、证据和报关关联到同一批订单/柜次。 - 未完成 PDA 拣货、缺任意一张必传照片或缺锁码文本时，进入 `LOADED` 必须失败。 - 若 P3-Q11/P3-Q12 将订舱、拖车或报关确认为硬门禁，对应前置未满足时进入 `LOADED` 必须失败。 @@ -188,10 +188,10 @@ PDA 已有调用拣货/证据/装柜接口的适配代码，但当前仍存在 ### 里程碑 A：锁定业务契约（P0） 1. 由产品/业务对尚未确认的 P3-Q1/Q2/Q5/Q7/Q8/Q10/Q11/Q12 给出最终结论。 -2. 按已确认结论固定三期终点为 `LOADED`/装柜完成，并将 `DELIVERED` 移出国内三期状态操作。 +2. 按已确认结论固定国内货柜履约终点为 `LOADED`/装柜完成，并将 `DELIVERED` 移出国内国内货柜履约状态操作。 3. 定义订舱、拖车和报关中哪些是进入 `LOADED` 的强制前置，哪些允许并行。 -### 里程碑 B：在现有订单上建立三期统一编排与门禁（P0） +### 里程碑 B：在现有订单上建立国内货柜履约统一编排与门禁（P0） 1. 复用现有订单主状态，补齐订单-柜次关联、整体时间线、版本和审计投影，不新建出仓单。 2. 将排柜、订舱、拖车、拣货、证据和报关子流程绑定到订单/柜次。 @@ -220,22 +220,22 @@ PDA 已有调用拣货/证据/装柜接口的适配代码，但当前仍存在 ## 9. GO 准入标准 -以下条件全部满足后，才建议将三期从 NO-GO 改为 GO： +以下条件全部满足后，才建议将国内货柜履约从 NO-GO 改为 GO： - [ ] P3-Q1至P3-Q13 已有明确结论，文档与代码口径一致。 -- [ ] 现有订单可通过柜次追溯全部三期子流程。 +- [ ] 现有订单可通过柜次追溯全部国内货柜履约子流程。 - [ ] 装柜完成门禁在服务端生效，缺 PDA 拣货、任一必传照片或锁码文本时不能进入 `LOADED`。 - [ ] 报关资料、补件、代理提交、回执和客户下载闭环。 -- [ ] Admin 所有三期正式入口可达，前后端 DTO 和权限一致。 -- [ ] Client 只能访问当前客户的三期数据和文件。 +- [ ] Admin 所有国内货柜履约正式入口可达，前后端 DTO 和权限一致。 +- [ ] Client 只能访问当前客户的国内货柜履约数据和文件。 - [ ] PDA 真实鉴权、任务、扫码、文件上传、弱网和重试已真机通过。 - [ ] 装柜完成后进入 `LOADED` 并支持授权冲正，国内端不能手工推进 `DELIVERED`。 - [ ] 同一测试订单完成全链路正向与负向验收，证据可重放。 ## 10. 最终结论 -当前三期建议对外口径为： +当前国内货柜履约建议对外口径为： -> **三期已确认复用现有订单列表承载全部主状态，不新建出仓单，国内终点为 `LOADED`/装柜完成；已完成排柜/预装/PDA 拣货/装柜清单子链路，订舱和拖车 API 可用。但订单三期统一编排、五张装柜照片与锁码文本硬门禁、报关协同、冲正、Client 协同和 PDA 真机仍未闭环，且国内手工推进 `DELIVERED` 的现有能力必须整改，当前不具备整期验收条件。** +> **国内货柜履约已确认复用现有订单列表承载全部主状态，不新建出仓单，国内终点为 `LOADED`/装柜完成；已完成排柜/预装/PDA 拣货/装柜清单子链路，订舱和拖车 API 可用。但订单国内货柜履约统一编排、五张装柜照片与锁码文本硬门禁、报关协同、冲正、Client 协同和 PDA 真机仍未闭环，且国内手工推进 `DELIVERED` 的现有能力必须整改，当前不具备整期验收条件。** -因此，现阶段不应标记“三期完成”，应标记为“**子能力已实现，闭环整改中**”。 +因此，现阶段不应标记“国内货柜履约完成”，应标记为“**子能力已实现，闭环整改中**”。 diff --git a/三期/三期需求确认表.md b/国内货柜履约/国内货柜履约需求确认表.md similarity index 79% rename from 三期/三期需求确认表.md rename to 国内货柜履约/国内货柜履约需求确认表.md index 4d938c0..75d1f41 100644 --- a/三期/三期需求确认表.md +++ b/国内货柜履约/国内货柜履约需求确认表.md @@ -1,14 +1,14 @@ -# 虫虫出海三期需求确认表 +# 虫虫出海国内货柜履约需求确认表 > 创建日期：2026-07-28 > 当前状态：已进入开发规划（已确认结论按本表执行；技术实现项仍需契约评审） -> 用途：记录会影响三期范围、流程、数据模型、页面和验收的产品决策。 +> 用途：记录会影响国内货柜履约范围、流程、数据模型、页面和验收的产品决策。 ## 一、维护规则 - 状态统一使用：待确认、确认中、已确认、已取消。 - 阻断级别统一使用：开工阻断、模块阻断、非阻断。 -- 结论确认后同步更新 `三期开发规划.md`、`三期开发进度表.md` 和受影响的页面原型。 +- 结论确认后同步更新 `国内货柜履约开发规划.md`、`国内货柜履约开发进度表.md` 和受影响的页面原型。 - 未确认事项只能作为候选方案，不能直接写成固定开发或验收承诺。 ## 二、确认事项 @@ -19,15 +19,15 @@ | 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 拣货、在线更新、真机验收 | -| P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 默认使用二期处理单元和当前位置；如需完整库存，单独评估 WMS 范围 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | PDA 拣货必须依赖实时库存和库位可用量；首版复用二期处理单元、当前位置和可用量接口，超量、库存不足和库位不可用由服务端拒绝；不扩展完整 WMS | 二三期契约、拣货、库存边界 | +| 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-19 | 柜子确认离开国内仓库后的船公司/货物跟踪查询、每 3 天最多 3 次、来源、更新时间和过期标识整体归四期；三期不建设或验收该查询 | 三期订舱资料、四期船节点查询 | +| P3-Q9 | “港务信息”指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 国内货柜履约只维护订舱与出仓前船期资料 | 已重新归期 | 已确认 | 产品/业务 | 2026-08-19 | 柜子确认离开国内仓库后的船公司/货物跟踪查询、每 3 天最多 3 次、来源、更新时间和过期标识整体归海外仓业务；国内货柜履约不建设或验收该查询 | 国内货柜履约订舱资料、海外仓业务船节点查询 | | 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`/派送完成只能在到达海外仓后由海外仓可信回传推进，不属于国内三期操作和验收范围 | 阶段边界、状态、里程碑、验收、海外仓回传 | +| P3-Q13 | 国内货柜履约终点以什么状态为准？ | 国内系统以能掌控的最后环节为终点 | 开工阻断 | 已确认 | 用户当前对话确认 | 2026-08-08 | 国内货柜履约终点为 `LOADED`/装柜完成；`DELIVERED`/派送完成只能在到达海外仓后由海外仓可信回传推进，不属于国内国内货柜履约操作和验收范围 | 阶段边界、状态、里程碑、验收、海外仓回传 | | P3-Q14 | 订舱、渠道柜次、放舱与智能排柜的先后关系是什么？ | 线下已订妥的订舱在创建时完整登记五项真实运输快照并直接确认；放舱不覆盖首次快照 | 开工阻断 | 已确认 | 用户当前对话确认 | 2026-08-12 | 订舱创建请求必须携带提单号、船名、航次、预计开船时间、预计到港时间五项真实运输数据，并直接进入 `CONFIRMED`；渠道、箱型和数量同时确定，系统按箱型需求数量生成绑定渠道的稳定内部柜次。未放舱不影响候选查询、智能推荐、人工调整和保存装柜计划；同一柜次只能装同渠道入库单，服务端禁止跨渠道混装。`RELEASED` 仅作为后续放舱/PDA 门禁，不补录、不覆盖首次五项运输快照；真实集装箱号可在放舱时或之后录入 | 订舱、柜次、智能排柜、预装、PDA、运输信息 | ### 2.1 PDA 已确认子决策 @@ -44,23 +44,23 @@ | P3-PDA-D08 | 2026-08-09 | 同类型证据允许多张并采用追加记录；错误/重复照片不硬删除，只作废 | 每条照片独立保存；作废记录原因、操作人和时间，历史可追溯 | | P3-PDA-D09 | 2026-08-09 | 空仓、半仓、满仓、锁仓、带锁码照五类证据各至少 1 张有效且未作废的照片，可多张；带锁码照同时要求锁码文本 | 服务端完整性门禁按“每类至少一张有效记录”校验，不能按单槽位替换模型实现 | -> 验收映射：当前自动化已真实覆盖五类证据上传、同类型多图追加、跨类型/伪造 `fileId` 拒绝、锁码文本门禁和错图作废审计；设备在线、持久化草稿批量提交仍按[验收任务拆分与待确认清单](三期验收任务拆分与待确认清单.md)保留 coverageGap。 +> 验收映射：当前自动化已真实覆盖五类证据上传、同类型多图追加、跨类型/伪造 `fileId` 拒绝、锁码文本门禁和错图作废审计；设备在线、持久化草稿批量提交仍按[验收任务拆分与待确认清单](国内货柜履约验收任务拆分与待确认清单.md)保留 coverageGap。 ## 三、已确认架构决策 | 编号 | 确认日期 | 最终结论 | 影响 | |---|---|---|---| -| P3-D1 | 2026-08-08 | 三期不新建独立出仓单，现有订单列表承载全部主状态；柜次、订舱、拖车、拣货、证据和报关作为订单关联子对象 | 取消出仓单页面和数据模型规划，改为增强现有订单列表/详情及服务端统一编排 | +| P3-D1 | 2026-08-08 | 国内货柜履约不新建独立出仓单，现有订单列表承载全部主状态；柜次、订舱、拖车、拣货、证据和报关作为订单关联子对象 | 取消出仓单页面和数据模型规划，改为增强现有订单列表/详情及服务端统一编排 | | P3-D2 | 2026-08-10 | 订单拆分采用“父订单→子订单→柜次”；已装载数量形成子订单，未装载数量自动生成后续子订单；支持一单多柜和多订单拼柜 | 后端必须保留父子订单、柜次、数量分摊和整体时间线；不得把未装载部分静默丢弃 | | P3-D3 | 2026-08-10 | `LOADED` 的硬门禁包含订舱完成、拖车完成、报关放行回执、PDA 拣货完成和五类证据完整；`LOADED` 后错误线下人工处理 | 统一门禁服务负责校验，国内页面不提供在线冲正或 `DELIVERED` 操作 | -| P3-D4 | 2026-08-10；2026-08-19 更正归期 | 船公司官网查询：每 3 天一次、最多 3 次，保存来源、更新时间和过期标识 | 该能力及首批六家来源整体归四期，三期只保留订舱与出仓前船期资料 | +| P3-D4 | 2026-08-10；2026-08-19 更正归期 | 船公司官网查询：每 3 天一次、最多 3 次，保存来源、更新时间和过期标识 | 该能力及首批六家来源整体归海外仓业务，国内货柜履约只保留订舱与出仓前船期资料 | | P3-D5 | 2026-08-10 | 初始化仓库常用角色：操作员、拣货员、理货员；按最小权限授予拣货、证据上传和查看能力 | 角色初始化由 IAM/统一 SQL 任务实现，具体权限矩阵在技术契约评审中落表 | ## 四、建议确认顺序 1. 已完成 P3-Q1～P3-Q3、P3-Q5～P3-Q14 的产品确认，可直接进入契约和实现拆分。 2. P3-Q4 已确认采用 uni-app、在线更新与 Android 广播扫描；后续按既定发布安排完成常规真机验收。 -3. P3-Q5 已确认复用二期实时库存、当前位置和可用量接口，完整 WMS 不纳入三期。 +3. P3-Q5 已确认复用入库测量与计费实时库存、当前位置和可用量接口，完整 WMS 不纳入国内货柜履约。 ## 五、产品与业务确认会议 @@ -74,15 +74,15 @@ ### 5.2 会议输入 - 本确认表中的 P3-Q1～P3-Q13。 -- `三期开发规划.md` 的流程、状态、里程碑和任务骨架。 -- `三期页面与原型清单.md` 中已有参考原型和待补页面。 -- 二期输出契约、目标 PDA 信息、文件存储能力及报关/港务协作现状。 +- `国内货柜履约开发规划.md` 的流程、状态、里程碑和任务骨架。 +- `国内货柜履约页面与原型清单.md` 中已有参考原型和待补页面。 +- 入库测量与计费输出契约、目标 PDA 信息、文件存储能力及报关/港务协作现状。 ### 5.3 每项确认要求 1. 必须填写负责人、计划确认日期和可执行的最终结论，不能只记录“按建议处理”。 2. 最终结论需明确正常流程、异常/冲正、权限责任和验收口径。 -3. 暂缓事项必须写明本期是否排除、临时方案、影响模块和再次确认日期。 +3. 暂缓事项必须写明当前范围是否排除、临时方案、影响模块和再次确认日期。 4. 开工阻断项未解除时，不得将受影响模块标记为可开发。 5. 会议结束后，将结论同步到开发规划、开发进度表、页面原型和后续验收任务。 @@ -90,6 +90,6 @@ - 14 项确认事项的状态和最终结论已同步；P3-Q4 已确认采用 uni-app、在线更新与 Android 广播扫描。 - 需要新增或调整的原型清单。 -- 三期范围内/范围外清单及跨期依赖。 +- 国内货柜履约范围内/范围外清单及跨期依赖。 - 仍有风险的事项、责任人和完成日期。 - 已允许进入 T02 契约设计与任务拆分；未决技术项只阻断其对应实现，不反向阻断整期已确认范围。 diff --git a/三期/三期页面与原型清单.md b/国内货柜履约/国内货柜履约页面与原型清单.md similarity index 73% rename from 三期/三期页面与原型清单.md rename to 国内货柜履约/国内货柜履约页面与原型清单.md index 7f08845..7bfd6f3 100644 --- a/三期/三期页面与原型清单.md +++ b/国内货柜履约/国内货柜履约页面与原型清单.md @@ -1,9 +1,9 @@ -# 虫虫出海三期页面与原型清单 +# 虫虫出海国内货柜履约页面与原型清单 -> 创建日期：2026-07-28 -> 当前状态：核心 Admin 装柜页面已部署联调；PDA 提交契约和客户端三期页面仍未完成 +> 创建日期：2026-07-28 +> 当前状态：核心 Admin 装柜页面已部署联调；PDA 提交契约和客户端国内货柜履约页面仍未完成 > 原型依据：`参考资料/出仓流程.png`、现有订单列表/详情、现有 PDA 拣货原型 -> 已确认边界：不新增独立出仓单；国内三期终点为 `LOADED`/装柜完成 +> 已确认边界：不新增独立出仓单；国内国内货柜履约终点为 `LOADED`/装柜完成 ## 一、维护规则 @@ -16,11 +16,11 @@ | 页面 ID | 页面/入口 | 主要能力 | 对应大任务 | 原型状态 | 依赖确认项 | 备注 | |---|---|---|---|---|---|---| -| P3-ADM-01 | 现有订单列表三期增强 | 查询、筛选、三期主状态、异常和阻塞摘要 | T03 订单三期编排与柜次 | 待原型 | P3-Q2、P3-Q11 | 复用现有订单列表，不新增出仓单列表和创建入口 | -| P3-ADM-02 | 现有订单详情三期增强 | 柜次、任务、五类装柜照片、锁码、报关和时间线 | T03 订单三期编排与柜次 | 待原型 | P3-Q11 | 组合现有货柜和装柜清单能力，补统一编排区 | +| P3-ADM-01 | 现有订单列表国内货柜履约增强 | 查询、筛选、国内货柜履约主状态、异常和阻塞摘要 | T03 订单国内货柜履约编排与柜次 | 待原型 | P3-Q2、P3-Q11 | 复用现有订单列表，不新增出仓单列表和创建入口 | +| P3-ADM-02 | 现有订单详情国内货柜履约增强 | 柜次、任务、五类装柜照片、锁码、报关和时间线 | T03 订单国内货柜履约编排与柜次 | 待原型 | P3-Q11 | 组合现有货柜和装柜清单能力，补统一编排区 | | P3-ADM-03 | 智能排柜 | 生成建议、冲突、调整和确认 | T04 智能排柜 | 开发中 | P3-Q1、P3-Q2 | Admin `/container-loading/smart-loading` 已部署；真实完成态受 PDA 门禁阻断 | | P3-ADM-04 | 订舱管理 | 订舱申请、结果、变更和异常 | T05 订舱与港务信息 | 已有参考原型 | P3-Q9、P3-Q11 | 已有订舱列表、新增和详情 | -| P3-ADM-05 | 订舱与出仓前船期资料 | 人工维护船名航次、港口及预计时间快照 | T05 订舱资料 | 部分参考原型 | P3-Q9 | 出仓后的来源、更新时间和节点查询页面整体归四期 | +| P3-ADM-05 | 订舱与出仓前船期资料 | 人工维护船名航次、港口及预计时间快照 | T05 订舱资料 | 部分参考原型 | P3-Q9 | 出仓后的来源、更新时间和节点查询页面整体归海外仓业务 | | P3-ADM-06 | 拖车预约 | 服务商、车辆司机、时间窗和节点 | T06 拖车预约 | 已有参考原型 | P3-Q3、P3-Q11 | 已有拖车列表和新增表单，需补预约及到离仓节点 | | P3-ADM-07 | 拣货任务与复核 | 分配、进度、差异、复核和异常 | T07 PDA 拣货与复核 | 已阻塞 | P3-Q5 | 真实任务领取可用；PDA `pick` 仍返回 S0500，批量提交契约未实现 | | P3-ADM-08 | 装柜证据复核 | 柜号、锁码文本、五类多图、Admin 上传、作废和复核 | T08 装柜及柜封证据 | 开发中 | P3-Q6 | 五类多图追加、作废和 Admin 上传已通过真实接口；终态复核受 PDA 阻断 | @@ -31,11 +31,11 @@ | 页面 ID | 页面/入口 | 主要能力 | 对应大任务 | 原型状态 | 依赖确认项 | 备注 | |---|---|---|---|---|---|---| -| P3-CLI-01 | 现有订单列表三期增强 | 查看本企业订单的装柜阶段、柜次和当前节点 | T11 客户端三期协同 | 待原型 | P3-Q11 | 复用现有订单列表，不新增出仓单列表 | -| P3-CLI-02 | 现有订单详情三期增强 | 时间线、柜号、船期和允许公开的证据 | T11 客户端三期协同 | 待原型 | P3-Q6、P3-Q9 | 在现有订单详情补三期区块，不新建重复详情对象 | +| P3-CLI-01 | 现有订单列表国内货柜履约增强 | 查看本企业订单的装柜阶段、柜次和当前节点 | T11 客户端国内货柜履约协同 | 待原型 | P3-Q11 | 复用现有订单列表，不新增出仓单列表 | +| P3-CLI-02 | 现有订单详情国内货柜履约增强 | 时间线、柜号、船期和允许公开的证据 | T11 客户端国内货柜履约协同 | 待原型 | P3-Q6、P3-Q9 | 在现有订单详情补国内货柜履约区块，不新建重复详情对象 | | P3-CLI-03 | 报关资料上传 | 清单、上传、补件、版本和处理进度 | T09 报关资料与回执 | 待原型 | P3-Q7 | 文件规则确认后细化 | | P3-CLI-04 | 报关回执下载 | 回执列表、类型、版本和授权下载 | T09 报关资料与回执 | 待原型 | P3-Q8、P3-Q12 | 区分客户可见回执 | -| P3-CLI-05 | 出仓前船期资料 | 订舱预计开船、到港快照和变更 | T11 客户端三期协同 | 待原型 | P3-Q9 | 出仓后的实时节点、来源、更新时间和过期展示归四期 | +| P3-CLI-05 | 出仓前船期资料 | 订舱预计开船、到港快照和变更 | T11 客户端国内货柜履约协同 | 待原型 | P3-Q9 | 出仓后的实时节点、来源、更新时间和过期展示归海外仓业务 | ## 四、PDA @@ -52,5 +52,5 @@ 1. 先修复 PDA `pick` 第二处 `S0500`，恢复领取、拣货、复核、装柜完成和报关终态真实链路。 2. 单独实现 P3-PDA-04 原子批量提交契约，覆盖整批事务、幂等、版本/库存快照和失败回滚。 3. 完成 P3-PDA-05 真机拍照、多图追加、失败重试与作废验收。 -4. 补齐 P3-ADM-01、P3-ADM-02、P3-ADM-10 和企业客户端三期页面的最终交互验收。 -5. 复跑三期定向和默认全量 HTTP 验收，只有所有硬门禁真实通过后才把页面和整期标记为完成。 +4. 补齐 P3-ADM-01、P3-ADM-02、P3-ADM-10 和企业客户端国内货柜履约页面的最终交互验收。 +5. 复跑国内货柜履约定向和默认全量 HTTP 验收，只有所有硬门禁真实通过后才把页面和整期标记为完成。 diff --git a/三期/三期验收任务拆分与待确认清单.md b/国内货柜履约/国内货柜履约验收任务拆分与待确认清单.md similarity index 90% rename from 三期/三期验收任务拆分与待确认清单.md rename to 国内货柜履约/国内货柜履约验收任务拆分与待确认清单.md index 2f4e896..217e0a6 100644 --- a/三期/三期验收任务拆分与待确认清单.md +++ b/国内货柜履约/国内货柜履约验收任务拆分与待确认清单.md @@ -1,4 +1,4 @@ -# 三期验收任务拆分与待确认清单 +# 国内货柜履约验收任务拆分与待确认清单 > 更新日期：2026-08-10 > 本清单只描述真实 HTTP/设备验收边界，不把原型或 mock 结果视为通过。 @@ -14,7 +14,7 @@ | 锁码门禁 | 缺少锁码照片或锁码文本为空时，完成装柜请求被拒绝 | `phase3-loading.mjs` | | 统一装柜门禁 | 订舱未完成、拖车未完成、报关无有效放行回执、PDA 未完成或五类证据不完整时，真实 `LOADED` 请求均被拒绝 | `service-center-flow.mjs` / `phase3-loading.mjs` | | 订单/柜次聚合 | 一单多柜、一个柜多订单、父子订单数量分摊及未装数量自动生成子订单可追溯 | `phase3-order-aggregate.mjs`（待补） | -| 出仓后船节点查询 | 已重新归入四期，不属于三期验收 | 四期沿用现有 `CarrierScheduleQuery` 设计验收入口，不再补 `phase3-vessel-tracking.mjs` | +| 出仓后船节点查询 | 已重新归入海外仓业务，不属于国内货柜履约验收 | 海外仓业务沿用现有 `CarrierScheduleQuery` 设计验收入口，不再补 `phase3-vessel-tracking.mjs` | | 仓库角色 | 操作员、拣货员、理货员初始化、最小权限和跨客户隔离 | `phase3-role-contract.mjs`（待补） | | 伪造与交叉归属 | 不存在 `fileId`、其他证据类型的 `fileId` 不能绑定 | `phase3-loading.mjs` | diff --git a/国内货柜履约/虫虫出海国内货柜履约开发进度表.xlsx b/国内货柜履约/虫虫出海国内货柜履约开发进度表.xlsx new file mode 100644 index 0000000..b3e9b59 Binary files /dev/null and b/国内货柜履约/虫虫出海国内货柜履约开发进度表.xlsx differ diff --git a/三期/货柜履约原型字段验收矩阵-2026-08-17.md b/国内货柜履约/货柜履约原型字段验收矩阵-2026-08-17.md similarity index 100% rename from 三期/货柜履约原型字段验收矩阵-2026-08-17.md rename to 国内货柜履约/货柜履约原型字段验收矩阵-2026-08-17.md diff --git a/三期/货柜管理全链验收矩阵-2026-08-13.md b/国内货柜履约/货柜管理全链验收矩阵-2026-08-13.md similarity index 97% rename from 三期/货柜管理全链验收矩阵-2026-08-13.md rename to 国内货柜履约/货柜管理全链验收矩阵-2026-08-13.md index 14b5f40..fb6a309 100644 --- a/三期/货柜管理全链验收矩阵-2026-08-13.md +++ b/国内货柜履约/货柜管理全链验收矩阵-2026-08-13.md @@ -8,7 +8,7 @@ ## 验收口径 -- 本矩阵以当前对话、三期产品确认版开发规划和实际冻结契约为准。旧确认单中的待确认项不覆盖后续已冻结结论。 +- 本矩阵以当前对话、国内货柜履约产品确认版开发规划和实际冻结契约为准。旧确认单中的待确认项不覆盖后续已冻结结论。 - 已冻结能力按事实来源落具体路径和断言；尚未冻结能力继续只保留能力级占位，不预设 HTTP 方法、路径、DTO 字段或业务错误码。 - 自动化必须通过业务 API 生成数据；人工验收必须能从 Admin/PDA 可见入口点击到对应状态。不得以数据库直写、mock、原型或前端本地假状态代替。 - 每次真实 HTTP 验收记录请求用途、响应状态、业务码、`requestId`、`traceId`、关键资源 ID 和清理/保留策略；敏感凭据不得写入报告。 @@ -105,19 +105,19 @@ ## P3-Q14 文档同步待总控统一 - 当前冻结验收时序：订舱只登记 `containerRequirements` 并在完整 release 后进入 `RELEASED`；不会生成真实货柜。未订舱时先建 `SIMULATION/ACTIVE` 模拟柜并排货、无号 push，港口取得真实 `containerNo` 后用四字段 link 原地补全模拟柜并创建 allocation。 -- `docs/三期/三期需求确认表.md` 的 P3-Q14 尚未完整描述新的 DRAFT/RELEASED 与港口四字段关联模型。本任务不擅改需求确认表，标记为 `WAIT_CONTROLLER_DOC_SYNC`，由总控统一文档；本矩阵及自动化以当前冻结 DTO/OpenAPI 为准。 +- `docs/国内货柜履约/国内货柜履约需求确认表.md` 的 P3-Q14 尚未完整描述新的 DRAFT/RELEASED 与港口四字段关联模型。本任务不擅改需求确认表，标记为 `WAIT_CONTROLLER_DOC_SYNC`，由总控统一文档；本矩阵及自动化以当前冻结 DTO/OpenAPI 为准。 - 五项运输事实保存在 DRAFT 聚合，release 只校验完整性并冻结持久化快照；RELEASED 不接受编辑或删除。 ## 契约冻结清单 ### 既有冻结基线 -以下能力在本轮新增 overview 契约之前已经由三期产品确认版、既有 OpenAPI/Controller 和专项测试冻结。本轮不重定义其路径或状态机。 +以下能力在本轮新增 overview 契约之前已经由国内货柜履约产品确认版、既有 OpenAPI/Controller 和专项测试冻结。本轮不重定义其路径或状态机。 | 能力标识 | 冻结边界 | 事实来源 | 状态 | |---|---|---|---| | `booking-requirements-and-port-link` | 订舱按 `containerRequirements[]` 保存箱型数量，不生成真实柜；link 在港口取得真实柜号后补全模拟柜并创建 allocation | `PlatformContainerController`、`ContainerService`、`OceanBookingService`、`firstleg-v1.yaml`、`ocean-bookings-v1.yaml` | 本轮目标冻结，待环境验收 | -| `channel-isolation` | 渠道隔离与禁止跨渠道混装 | 三期产品确认版及既有排柜契约 | 既有冻结，待环境验收 | +| `channel-isolation` | 渠道隔离与禁止跨渠道混装 | 国内货柜履约产品确认版及既有排柜契约 | 既有冻结，待环境验收 | | `container-number-lifecycle` | 模拟柜无真实柜号允许排柜及 push；push 本身不开放 PDA；link 从未消费真实柜带入唯一 `containerNo`，内部柜、计划、bridge 身份稳定；作业中换号身份稳定 | `ContainerService`、`SmartLoadingService`、`SplitPreloadService`、`LoadingListService`、相关 OpenAPI 与合同测试 | 新时序已冻结，待环境验收 | | `preload-and-loading-list` | `PENDING -> EDITING -> CONFIRMED`；计划级确认原子确认全部关联票据并唯一建 task；ACTIVE 模拟柜已关联 `RELEASED` 订舱需求、真实柜号和 readiness 全部满足后 `readyForPda=true`，claim 才推进 `LOADING` | `LoadingListService.confirmPreload`、`LoadingPickService`、`POST /loading-plans/{planId}/confirm` 及 Loading List OpenAPI/DTO | 计划级确认已冻结，待环境验收 | | `customs-documents-lock` | 清关/报关专用流程、完成态禁止替换 | 既有 `LoadingListService`、专用 Controller 与专项测试 | 既有冻结，待环境验收 | diff --git a/开发环境独立任务协作登记.md b/开发环境独立任务协作登记.md index af123e4..22d081f 100644 --- a/开发环境独立任务协作登记.md +++ b/开发环境独立任务协作登记.md @@ -4,7 +4,7 @@ ## 环境隔离门禁 -- 开发总控只向本表 task_id 下发五期开发工作；不得向 `C:\Users\BY-OY\Desktop\code\chongchong-global` 的测试环境任务下发，即使提示中另写开发目录也不例外。 +- 开发总控只向本表 task_id 下发当前系统全流程开发工作；不得向 `C:\Users\BY-OY\Desktop\code\chongchong-global` 的测试环境任务下发，即使提示中另写开发目录也不例外。 - 每个任务必须同时满足 projectId、cwd 和登记环境一致；任一项不一致立即停止，不读取、不修改、不运行命令，也不得自行切换目录补救。 - 开发专项日常只执行源码实现、定向测试、类型检查和构建；开发数据库与开发部署只能由开发总控在代码门禁通过后按精确服务、数据库和变更清单单独下发。测试环境、测试数据库、生产环境和 Jenkins 仍禁止。 - 开发与测试目录之间不得复制未提交文件、生成补丁、自动合并或 cherry-pick；需要移交时由用户明确授权具体方向、提交和范围。 @@ -17,7 +17,7 @@ - 数据库操作前必须确认开发库、精确表、业务主键或 SQL 文件和预计影响行；优先使用事务并保留执行结果。仓库已审核的开发增量 SQL、测试造数和职责范围内的数据修正可执行。 - `DROP`、`TRUNCATE`、整库重置、清空表、无明确主键范围的批量删除及其他不可恢复操作不在授权内，仍需用户当轮单独确认。 - 开发部署必须在受影响测试、类型检查或构建通过后进行，并记录精确部署单元、使用的提交或工作区状态、配置来源和部署结果。若唯一部署方式依赖 Jenkins，执行前重新取得用户对 Jenkins 的明确授权。 -- 开发环境真实 HTTP 在部署和数据库变更完成后执行，可包含当前五期职责范围内的读写验收；只使用开发身份和开发数据，记录接口路径、HTTP 状态、业务码、`requestId`/`traceId` 与结果，不输出或持久化 Token、密码和敏感载荷。破坏性批量请求仍需单独确认。 +- 开发环境真实 HTTP 在部署和数据库变更完成后执行，可包含当前全流程职责范围内的读写验收；只使用开发身份和开发数据，记录接口路径、HTTP 状态、业务码、`requestId`/`traceId` 与结果，不输出或持久化 Token、密码和敏感载荷。破坏性批量请求仍需单独确认。 ## 登记表 @@ -25,16 +25,54 @@ | task_id | project_id | 展示名称 | 长期职责 | |---|---|---|---| -| `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发总控】五期开发 | 接收五期开发任务，冻结跨端契约和串行批次，协调本表专项完成实现、定向测试和构建；代码门禁通过后按本表授权操作开发数据库、部署开发环境并执行真实 HTTP 验收；不操作测试/生产环境或 Jenkins。 | +| `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发总控】全流程开发 | 接收当前系统端到端全流程开发任务，冻结跨端契约和串行批次，协调本表专项完成实现、定向测试和构建；代码门禁通过后按本表授权操作开发数据库、部署开发环境并执行真实 HTTP 验收；不操作测试/生产环境或 Jenkins。 | 长期专项： | task_id | parent_task_id | project_id | 展示名称 | 唯一长期职责 | |---|---|---|---|---| -| `01a05b23-bfc6-7121-a6f2-7fc14ee456a3` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发五期前端】Admin | `apps/admin-web/` 五期海外仓排车、出库、派送、异常退回、客户回访页面、路由、API、权限消费、测试与构建；不修改 Client、PDA、后端或 SQL。 | -| `01a05b23-c20f-7f52-8a26-543f1563f0f8` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发五期前端】Client | `apps/client-web/` 五期客户派送页面、详情、创建表单、路由、API、权限消费、测试与构建；不修改 Admin、PDA、后端或 SQL。 | -| `01a05b78-6e28-7460-babf-3a87331f6dd4` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发五期前端】海外PDA | `apps/pda-overseas-uniapp/` 五期排车拣货、一件代发出库、任务完成、发车入口、真实 API、恢复、扫码、幂等、测试与构建；派送不进入 PDA。 | -| `01a05b23-c5ff-77c3-8f77-ceb4f4c40de2` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发五期后端】Lastleg | `baiyue-firstleg/lastleg-service/` 五期 dispatch、delivery、dropship、exceptionorder、customervisit、PDA 出库与发车的接口、业务、OpenAPI、SQL、权限强制和测试。 | -| `01a05b23-c7f8-72e0-bb3c-afbbf1c7f9e7` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发五期后端】IAM权限 | `baiyue-firstleg/iam/` 及必要 common-security 的五期平台/客户权限资源、角色初始化、授权快照、OpenAPI、SQL 和测试；不修改 Lastleg 业务或前端。 | +| `01a05b23-bfc6-7121-a6f2-7fc14ee456a3` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程前端】Admin | `apps/admin-web/` 全部平台管理页面、路由、API、权限消费、测试与构建；不修改 Client、PDA、后端或 SQL。 | +| `01a05b23-c20f-7f52-8a26-543f1563f0f8` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程前端】Client | `apps/client-web/` 全部客户工作台页面、路由、API、权限消费、测试与构建；不修改 Admin、PDA、后端或 SQL。 | +| `01a05b78-6e28-7460-babf-3a87331f6dd4` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程前端】海外PDA | `apps/pda-overseas-uniapp/` 全部海外仓现场作业、真实 API、恢复、扫码、幂等、测试与构建；派送仍由 Admin/Client 承载。 | +| `01a05b23-c5ff-77c3-8f77-ceb4f4c40de2` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程后端】Lastleg | `baiyue-firstleg/lastleg-service/` 海外尾程、入仓、库存、换标、转运、废弃、排车、出库、派送、一件代发、异常、回访及海外业务的接口、OpenAPI、SQL、权限强制和测试。 | +| `01a05b23-c7f8-72e0-bb3c-afbbf1c7f9e7` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程后端】IAM权限 | `baiyue-firstleg/iam/` 及必要 common-security 的平台/客户全流程权限资源、角色初始化、授权快照、OpenAPI、SQL 和测试；不修改 Lastleg 业务或前端。 | 验收与部署任务不常驻登记。只有用户明确要求开始验收、准备部署或执行验收时，才另行决定是否创建；开发任务不得代行。 + +## 当前 P0 全流程补齐批次 + +本批只处理原型盘点确认的 P0，不混入 Admin 经营分析、销售管理、官网、小程序、独立 APP 或全量视觉验收。现有文档业务域改名属于总控在途改动，各专项必须保留，不得暂存、提交、覆盖或回滚。 + +| 工作包 | 执行任务 | 写入范围 | 交付目标 | 依赖与集成边界 | +|---|---|---|---|---| +| `P0-BE-LASTLEG` | 【开发全流程后端】Lastleg | `baiyue-firstleg/lastleg-service/` | 补齐客户海外采购、本土卡、本土散板、海外入库订单所需客户 API；核对并补齐 PDA 盘点、移库、换标、库存/库位/托盘查询专用 API、OpenAPI 与测试 | 先冻结 DTO、权限码和状态机并通知 Client、海外 PDA、IAM；不修改 `iam/`、统一 SQL或前端 | +| `P0-BE-IAM` | 【开发全流程后端】IAM权限 | `baiyue-firstleg/iam/` 及必要 `common-security/` | 补齐并核对客户海外业务、海外入库查询和海外 PDA 现场作业的权限资源、角色初始化、OpenAPI 与模块 SQL | 消费 Lastleg 冻结的权限码；不修改 Lastleg、统一 SQL或前端 | +| `P0-FE-CLIENT` | 【开发全流程前端】Client | `apps/client-web/` | 将海外采购、美国本土卡、美本土散板和海外入库订单从占位收敛为真实页面；修正首页快捷入口；覆盖权限、加载、空态、错误态、幂等与测试 | 只消费客户正式 API，不调用平台/内部接口，不模拟成功；“我的订单”统一查询不在本批 | +| `P0-FE-OVERSEAS-PDA` | 【开发全流程前端】海外PDA | `apps/pda-overseas-uniapp/` | 接通库存盘点、商品移库、换标收货/执行/复核、库存/库位/托盘查询共 8 项现场能力，完成扫码、恢复、并发冲突、幂等、错误态和构建测试 | 只调用 `/api/pda/**` 正式接口；不得通过 `available: true` 掩盖未接通能力，不改后端或其他前端 | + +完成门禁：四包定向测试与构建通过，跨端契约一致，所有 P0 页面或 PDA 入口均不再是 `prototype`、`available: false` 或模拟成功。专项本批不提交、不推送、不部署、不执行数据库和真实 HTTP；总控汇总差异并处理现有文档改动后，再按各仓库最新测试分支同步门禁统一集成。 + +### P0 批次结果（2026-09-04） + +| 工作包 | 状态 | 结果与门禁 | +|---|---|---| +| `P0-BE-LASTLEG` | 已完成 | 客户海外采购、本土卡、本土散板、海外入库列表/详情接口及 PDA 作业 OpenAPI 已补齐；Lastleg 548 项测试通过，2 项跳过 | +| `P0-BE-IAM` | 已完成 | 4 项客户权限已冻结并只授予企业负责人，PDA 继续使用统一 `lastleg:pda:operate`；IAM 全量 284 项测试通过 | +| `P0-FE-CLIENT` | 已完成（总控接管） | 原 Client 任务连续两次网络流中断；总控在同一工作区完成三类跨境订单列表/详情/新增、海外入库列表/详情和首页正确路由；Client 263 项测试、类型检查、生产构建通过 | +| `P0-FE-OVERSEAS-PDA` | 已完成 | 盘点、移库、换标收货/执行/复核、库存/库位/托盘查询 8 项入口已接真实 `/api/pda/**`；64 项测试及 H5/App 资源构建通过 | +| 总控集成 | 已完成 | IAM 模块 SQL 与统一增量 SQL 内容一致；开发/测试登记隔离、页面索引、权限、Gateway、PDA 能力等 832 项索引合同通过；各 Git 仓库 `git diff --check` 通过 | + +总控已在每次提交前重新获取并合并对应测试分支，完成开发分支提交与推送：Backend `54cb9cea`、Auth 修复 `81470359`，Client `6998f81`，Admin `7d29f3d`，国内 PDA `881c273`，海外 PDA `f960b9f`。五个工作区提交后均保持在 `dev` 分支且无未提交业务改动。 + +开发部署已完成：Admin Jenkins `#41`、Client `#42`、IAM `#33`、Lastleg `#65`、Auth `#24` 均成功，其中后端任务显式使用 `ENVIRONMENT=development` 与 `DEPLOY=true`；未触发测试或生产任务。开发数据库只在 `8.163.49.32:3306` 执行统一增量，环境标记为 `dev`，迁移合同结果为 `PASS`，4 项权限及负责人授权、唯一索引和重复绑定清理结果均已核对；未重建或删除数据库。 + +开发环境真实 HTTP 已通过：登录后签发国内及海外 Token，IAM 返回 4 项目标权限；海外采购、本土卡、本土散板和海外入仓计划 4 个客户接口均返回 HTTP 200、业务码 200。Client 已按 `1920×1080`、浏览器缩放 `100%` 验收业务总览、三个出海下单列表、散板新增表单和海外入仓列表，未发现遮挡、溢出、错误日志或“暂无权限”；海外 PDA H5/App 构建已通过，真机广播扫码、拍照等硬件能力仍需设备证据。 + +### 全流程收口检查点（2026-09-04） + +- Backend 已在提交前重新获取并合并 `origin/test`，开发分支提交为 `e477f739`、`b8a649e7`；开发 Jenkins Backend `#165` 及下游 Firstleg `#72` 成功。 +- 最新开发环境真实 HTTP 全流程报告 `baiyue-firstleg/reports/admin-test-env-acceptance-20260904080448.json` 结果为 `PASS`：`8166/8166` 断言通过、`112` 次模块运行、`92` 个唯一模块、`4981` 个唯一请求，`failed=0`、`skippedModules=0`、`deploymentBlockers=0`。17 项覆盖说明均为非阻断项，包含设备能力、外部船司依赖和无公开接口可稳定构造的中间状态。 +- Admin 已合并最新 `origin/release/test`，冲突按当前全流程契约收敛；补齐智能装柜箱数输入提示，`233/233` 个测试文件、`1670/1670` 条测试及生产构建通过，本地提交 `871d0a5`、`bc6629d`。Client 已合并最新 `origin/release/test`，全量测试及生产构建通过，本地提交 `dbd3c61`。国内 PDA `118/118` 条测试通过。海外 PDA `65/65` 条测试及 H5 构建通过，本地提交 `4f314fa`。 +- 海外 PDA 已按 `390×844` 通过 H5 登录、工作台、拆柜收货、托盘、盘点、移库、换标、库存/库位/托盘查询、排车、出库、历史和个人中心的页面路由与横向溢出检查；托盘管理页不再显示“PDA 广播扫码与 H5 人工输入均可使用”。Android 广播扫码、相机与弱网恢复仍只计入设备验收，不以 H5 结果替代。 +- Git 域名入口的写入凭据失效后，使用本机已登记的同一 Git 服务入口 `8.163.30.128:10082` 完成推送，未修改仓库远程配置：Admin `bc6629d`、Client `dbd3c61`、海外 PDA `4f314fa` 已进入远端 `dev`。本检查点无代码、部署或验收阻断。 +- 最新前端提交已部署到开发环境：Admin Jenkins `#42`、Client Jenkins `#43` 均为 `SUCCESS`，`http://dev-admin.buggoglobal.com/healthz` 与 `http://dev-app.buggoglobal.com/healthz` 均返回 HTTP 200。Backend、Admin、Client、国内 PDA、海外 PDA 五个仓库的本地 `HEAD` 与远端 `origin/dev` 一致且工作区干净；AGENTS 索引合同 `872/872` 通过。 diff --git a/四期/README.md b/海外仓业务/README.md similarity index 57% rename from 四期/README.md rename to 海外仓业务/README.md index 7b5ceba..341a85d 100644 --- a/四期/README.md +++ b/海外仓业务/README.md @@ -1,26 +1,28 @@ -# 四期范围与快速索引 +# 海外仓业务范围与快速索引 ## 已确认业务边界 -- 一期、二期、三期覆盖国内头程仓内操作，三期完成装柜及国内出仓交接；柜子确认离开国内仓库后的节点查询不属于三期。 -- 四期从柜子确认国内出仓后开始定时查询船节点，持续跟踪国内出仓、港口、开航、海运在途、到港、卸船、清关、提柜及还柜事实；统一语义和停止规则见[船节点标准化契约](船节点标准化契约.md)。海外仓作业继续覆盖安排车辆提柜、运抵合作海外仓、卸货、入库、形成库存和库内操作。 -- 四期止于海外仓库存和库内作业，不包含海外仓出库单、出库履约、海外派送或其他库存离仓业务。 -- “尾程订单”属于本期已确认的订单管理范围，但不得据此把海外仓出库、派送履约或 `海外派送` 原型模块整体纳入四期。 -- 历史文档中把高级 BI、开放平台、移动端或性能优化称为“四期”的内容不再作为当前四期范围依据。 +- 当前开发环境按端到端全流程交付，不再用开发批次切断上下游。订单与客户、入库测量与计费、国内货柜履约、海外仓业务和财务共同组成一条连续业务链。 +- 海外仓业务从国内装柜完成及确认出仓后的船节点开始，覆盖海运在途、海外接柜、卸货入仓、库存与托盘、换标、转运、废弃、退货、排车、PDA 拣货与出库、发车、转派送、派送完成、异常退回、客户回访和一件代发。 +- 海外采购、本土卡车、本土散板、海外仓报价、汇率和车辆主数据属于同一海外业务域，并统一经 `gateway-overseas/` 访问。 +- 功能是否可用以正式路由、Controller/OpenAPI、权限、数据库结构和验收证据为准；历史规划只用于追溯，不再用于排除已经纳入全流程的能力。 ## 人工验收入口 -- 国内装柜完成后的三期尾端至四期完整人工验收，统一使用[《三期装柜完成后至四期人工验收手册》](三期装柜完成后至四期人工验收手册.md)。手册从 `LOADED` 柜次开始，覆盖国内出仓、船节点、跨区建单、海外 PDA 入仓、库存/库内结果、海外主数据和海外业务，并明确区分当前可操作页面与仅后端自动化已通过的能力。 +- 端到端人工验收统一使用[《虫虫出海全流程人工验收手册》](虫虫出海全流程人工验收手册.md)。手册覆盖客户与订单、国内履约、跨区事件、海外 PDA 入仓、库存与库内服务、排车出库、派送、异常退回、一件代发、海外主数据和海外业务，并区分页面、真机和自动化证据。 ## 功能快速路由 -| 业务域 | 本期范围 | 原型入口 | +| 业务域 | 能力范围 | 原型入口 | |---|---|---| -| 海外仓 | 尾程订单、入库单、换标单、托盘管理、库存管理；箱号管理与产品库当前暂不进入四期正式入口；Admin 入口 `../../apps/admin-web/src/modules/overseas-warehouse/` | 原型 `../悦/货代SAAS平台后台/prototype-src/modules/03-overseas-warehouse.html`；Backend `../../baiyue-firstleg/lastleg-service/`、`../../baiyue-firstleg/warehouse-overseas-service/`，经 `gateway-overseas/` | -| 海外仓排车查询与智能预排 | 平台查看排车列表/详情，按入仓计划或已收托盘筛选候选并创建待出库预排；不开放排车编辑、取消、发车、PDA 出库或派送 | Admin `../../apps/admin-web/src/modules/overseas-warehouse/pages/DispatchesView.vue`、`api/dispatches.ts`；Backend `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/controller/DispatchQueryController.java`、`SmartDispatchController.java` | +| 海外仓 | 尾程订单、入库单、换标单、托盘管理、库存管理；箱号管理与产品库当前暂不进入海外仓业务正式入口；Admin 入口 `../../apps/admin-web/src/modules/overseas-warehouse/` | 原型 `../悦/货代SAAS平台后台/prototype-src/modules/03-overseas-warehouse.html`；Backend `../../baiyue-firstleg/lastleg-service/`、`../../baiyue-firstleg/warehouse-overseas-service/`，经 `gateway-overseas/` | +| 海外仓排车与智能预排 | 平台查看排车列表/详情，按入仓计划或已收托盘创建预排，并完成编辑、取消、拣货、出库、发车和转派送 | Admin `../../apps/admin-web/src/modules/overseas-warehouse/pages/DispatchesView.vue`、`api/dispatches.ts`；Backend `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/` | | 海外仓客户自助服务 | 客户工作台正式开放贴标申请、仓储转运、货物废弃和退货换标；所有查询和写入只使用登录态客户范围 | Client `../../apps/client-web/src/modules/overseas-warehouse/routes.ts`、`views/WarehouseServiceView.vue`、`api/warehouseServices.ts`；Backend `../../baiyue-firstleg/lastleg-service/` 的 `relabel/`、`transfer/`、`discard/`，经 `gateway-overseas/` | | 海外仓 PDA 柜号签收与入仓 | 独立应用 `../../apps/pda-overseas-uniapp/`；当前真实前端只开放拆柜收货，完成柜号认领、三类照片、FBA 按 SKU 箱数/OVERSEAS 逐箱实收与全柜完成 | 前端 `src/api/inbound.js`、`receiving-adapter.js`、`pages/operation/operation.vue`；Backend `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/inboundplan/pda/controller/ReceivingContainerController.java`、`ReceivingContainerService.java`，经 `gateway-overseas/` | -| 海外仓 PDA 库内、托盘、换标与查询 | Lastleg 已提供 PDA 专用盘点、同仓整托移库、托盘组拆换绑、换标与库存/库位/托盘查询后端；海外 PDA 工作台入口仍禁用，前端接入前不得宣称全链路完成 | Backend `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/pda/stocktake/`、`pda/move/`、`pda/warehouse/`、`palletops/`、`relabel/pda/`；契约 `src/main/resources/openapi/overseas-pda-operations-v1.yaml` | +| 海外仓 PDA 库内、托盘、换标与查询 | Lastleg 提供盘点、同仓整托移库、托盘组拆换绑、换标和库存/库位/托盘查询能力；当前终端入口按工作台能力开关启用，未进入 PDA 的操作由 Admin/Client 正式页面承载 | Backend `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/pda/stocktake/`、`pda/move/`、`pda/warehouse/`、`palletops/`、`relabel/pda/`；契约 `src/main/resources/openapi/overseas-pda-operations-v1.yaml` | +| 海外仓出库与派送 | 排车编辑/取消、PDA 排车拣货、出库任务、发车门禁、转派送、客户派送单和派送完成 | Admin `../../apps/admin-web/src/modules/overseas-warehouse/`；Overseas PDA `../../apps/pda-overseas-uniapp/src/pages/dispatch/`、`src/pages/outbound/`；Backend `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/`、`delivery/` | +| 异常退回与客户回访 | 异常建档、派送退回入仓、派送状态、签收/回访附件和客户回访 | Admin `ExceptionOrdersView.vue`、`CustomerVisitsView.vue`；Backend `exceptionorder/`、`customervisit/` | +| 一件代发 | 国内订单强制 SKU 快照、装柜工作托盘、海外 SKU/箱唛库存和一件代发出库 | Backend `order/`、`firstleg/`、`lastleg-service/dropship/`；跨区事件见 `common-event-contract/` | | 海外业务 | 本土散板、采购订单、本土卡车；Admin 入口 `../../apps/admin-web/src/modules/overseas-business/` | 原型 `../悦/货代SAAS平台后台/prototype-src/modules/07-overseas-business.html`；Backend `../../baiyue-firstleg/lastleg-service/` 的 `procurement/`、`trucking/` 及后续本土散板子域 | | 仓库主数据与海外资源 | 仓库 ID、类型、状态、地址、能力统一由国内仓库主数据维护；海外服务只维护库位、托盘和资源锁 | Admin `../../apps/admin-web/src/modules/warehouses/`；国内权威 `../../baiyue-firstleg/warehouse/`；海外资源 `../../baiyue-firstleg/warehouse-overseas-service/` | | 通用资料 | 海外仓报价、汇率管理、车辆列表；Admin 入口 `../../apps/admin-web/src/modules/overseas-master-data/` | `../悦/货代SAAS平台后台/prototype-src/modules/10-general.html` | @@ -45,7 +47,7 @@ - 采购订单：`overseas-purchase`、`overseas-purchase-edit`、`overseas-purchase-detail`。 - 本土卡车：`overseas-truck`、`overseas-truck-add`、`overseas-truck-edit`。 - 本土散板：`overseas-looseboard`、`overseas-looseboard-add`、`overseas-looseboard-edit`。 -- `domestic-*` 和 `legacy-*` 页面不是四期默认入口；只有实际流程明确复用时才联查。 +- `domestic-*` 和 `legacy-*` 页面不是海外仓业务默认入口；只有实际流程明确复用时才联查。 ### 仓库与通用资料 @@ -54,31 +56,31 @@ - 汇率管理：`gen-exchange-rate`。 - 车辆列表与详情：`vehicle`、`vehicle-detail`。 -## 明确排除 +## 终端与模块边界 -- 海外仓出库及退货出库：`overseas-outbound`、`fba-outbound-order`、`fba-outbound-order-detail`、`fba-return-outbound`。 -- `prototype-src/modules/04-overseas-delivery.html` 中的海外派送、出库派车、自提和其他离仓履约页面。 -- 当前暂缓的箱号管理与产品库正式页面、平台查询和维护接口；保留既有源码供后续迭代恢复，不在四期菜单、路由和联调门禁中出现。 -- 未经后续确认的财务扩展、高级 BI、开放平台、移动端、完整海外 WMS 或四期之后的出库业务。 +- 海外仓出库、派送、异常退回和一件代发已经纳入全流程，不再作为海外入仓之后的独立开发批次。 +- 派送业务由 Admin/Client 承载，不进入海外 PDA；海外 PDA 负责现场入仓、托盘、排车拣货和出库等已注册作业。 +- 箱号和产品信息作为入仓、库存、箱唛及 SKU 快照的一部分使用；是否提供独立维护页面由正式路由决定，不影响全流程状态推进。 +- 高级 BI、开放平台和独立移动 APP 属于独立产品能力，不与现有业务全流程完成状态混为一谈。 ## 船节点定时查询边界 - 所有供应商统一节点、时间语义、异常事实、停止规则和新增船司接入门禁以[船节点标准化契约](船节点标准化契约.md)为准；供应商缺失的节点保持缺失，不推测补齐。 -- 现有 `CarrierScheduleQuery` 查询任务及其查询尝试、历史、来源、过期标识和频率约束整体重新归入四期；不再把它列作三期港务/船期查询能力，也不得另建一套重复任务。 +- 现有 `CarrierScheduleQuery` 查询任务及其查询尝试、历史、来源、过期标识和频率约束整体重新归入海外仓业务；不再把它列作国内货柜履约港务/船期查询能力，也不得另建一套重复任务。 - 定时查询对象必须关联真实订舱、柜次以及可用的船司/船名航次或跟踪标识，不建立脱离业务单据的孤立轮询任务。 - Firstleg `portschedule/` 负责任务编排、业务关联、最新节点、节点历史、幂等和停止条件；`integration-service/` 只负责船司或轨迹供应商适配、限流、超时、重试和错误归一化，不保存业务主数据。 - 查询从确认柜子离开国内仓库后开始，贯通目的港到达、卸船、清关、提柜和还柜事实，默认在实际 `EMPTY_RETURNED` 后停止；这只扩展货柜轨迹事实，不纳入海外派送、海外仓出库或库存离仓业务。失败不能伪造成功节点，需保留来源、观测时间、最近成功时间和失败原因。 -- 现有“每 3 天一次、窗口最多 3 次”、六家船公司来源、最近有效结果和过期标识是同一查询能力的既有约束，归四期继续核对；后续若调整自动轮询频率、供应商额度、退避或停止规则，应只修改四期契约和这套任务。 +- 现有“每 3 天一次、窗口最多 3 次”、六家船公司来源、最近有效结果和过期标识是同一查询能力的既有约束，归海外仓业务继续核对；后续若调整自动轮询频率、供应商额度、退避或停止规则，应只修改海外仓业务契约和这套任务。 - 当前原型没有独立的“船节点定时查询”页面；涉及页面展示时从订舱、船期或货柜详情进入，不得为了匹配原型菜单把它归入海外派送。 ## 系统边界与索引维护 - 海外仓合作仓是现有头程仓库主数据的类型扩展，需同步核对 Admin `warehouses`、Warehouse Service 的 DTO/Controller/OpenAPI/SQL 及实际消费者；不得因此把海外库存业务写入国内 Warehouse Service。 - 海外库存、库内作业和海外本土业务已有明确服务入口：`gateway-overseas/` 是海外 API 网关，`lastleg-service/` 拥有尾程订单、入仓计划、换标、库存业务、采购和本土卡车；国内 `warehouse-service` 是仓库主数据唯一权威，`warehouse-overseas-service/` 只拥有库位、托盘及资源锁并引用国内 `warehouseId`。不得把海外库存业务塞入国内 `firstleg/` 或 `warehouse/`。 -- 国内装柜完成事件只在海外生成 `PENDING_ASSIGNMENT` 尾程订单、冻结快照和 `FIRST_LEG` 在途库存，不自动生成入仓计划。平台通过 `GET /api/platform/v1/last-leg/orders/container-summaries` 按稳定 `sourceContainerBookingId` 服务端聚合全柜订单、入仓码和有效计划，在分页前排除全部入仓码均已生成有效独立计划的柜，仅向柜子工作台返回仍有入仓码待生成计划的柜；详情 `/{sourceContainerBookingId}` 返回柜内全部订单与计划且不受订单分页截断。`plannedArrivalAt` 只来自装柜完成事件 `estimatedWarehouseArrivalAt` 冻结到 Lastleg `ll_order.estimated_warehouse_at` 的计划到仓事实，不得使用创建时间、预计到港或当前时间替代，并按该时间升序、空值最后排序。确认后调用 `POST /api/platform/v1/last-leg/inbound-plans/convert-container`；服务端一次锁定整柜、每票独立生成一个计划，整批原子且幂等。转换成功才将尾程订单推进为 `INBOUND_PLANNED`，并把库存余额的来源入仓码展示快照替换为各自 `planNo`。 -- 船节点是头程海运在途事实与四期海外接柜之间的衔接能力，业务聚合继续由 Firstleg 持有；到港/可提柜结果通过明确契约或跨区域事件提供给海外区域，不复制第二套轮询任务。 +- 国内装柜完成事件只在海外生成 `PENDING_ASSIGNMENT` 尾程订单、冻结快照和 `FIRST_LEG` 在途库存，不自动生成入仓计划。平台通过 `GET /api/platform/v1/last-leg/orders/container-summaries` 按稳定 `sourceContainerBookingId` 服务端聚合全柜订单、入仓码、计划数、未操作数和 `allPlansReady`，在分页前排除全部入仓码均已生成有效独立计划的柜，仅返回仍有入仓码待生成计划的柜；详情 `/{sourceContainerBookingId}` 返回柜内全部订单与计划且不受订单分页截断。`plannedArrivalAt` 只来自装柜完成事件 `estimatedWarehouseArrivalAt` 冻结到 Lastleg `ll_order.estimated_warehouse_at` 的计划到仓事实，不得使用创建时间、预计到港或当前时间替代，并按该时间升序、空值最后排序。确认后调用 `POST /api/platform/v1/last-leg/inbound-plans/convert-container`；服务端一次锁定整柜、每票独立生成一个计划，整批原子且幂等。转换成功才将尾程订单推进为 `INBOUND_PLANNED`，并把库存余额的来源入仓码展示快照替换为各自 `planNo`。 +- 船节点是头程海运在途事实与海外接柜之间的衔接能力，业务聚合继续由 Firstleg 持有；到港/可提柜结果通过明确契约或跨区域事件提供给海外区域，不复制第二套轮询任务。 - Admin、Client 仍使用统一账号体系，并按根 `AGENTS.md` 的双区域 API、海外 Token 和跨区域事件约定接入；业务页面不自行实现第二套登录。 -- 海外仓 PDA 使用独立 `apps/pda-overseas-uniapp/` 工程和发布身份，但账号仍由国内 Auth 唯一签发；真实作业请求必须经海外 Gateway 的显式 PDA 路由。当前拆柜收货已接真实 API；库内、托盘、换标和查询仍按工作台禁用状态管理，即使 Lastleg Controller 已存在也不得据此宣称设备端联调完成。 +- 海外仓 PDA 使用独立 `apps/pda-overseas-uniapp/` 工程和发布身份，但账号仍由国内 Auth 唯一签发；真实作业请求必须经海外 Gateway 的显式 PDA 路由。工作台只展示已注册并启用的现场作业，其他业务通过 Admin/Client 完成，不以某个终端是否承载全部操作判断端到端流程是否完成。 - 海外 PDA 的实际收货仓是国内 `warehouse-service` 中 `tenant_id=0`、类型为 `OVERSEAS`、状态 `ACTIVE` 且启用 `RECEIVING` 能力的平台共享物理仓，并由 `WAREHOUSE_PICKER` 的 Token Claim 固定；海外数据库只保存相同 `warehouseId` 引用。PDA 不接收仓库 ID，也不能切换柜号。海外 Gateway 对每个 `/api/pda/**` 请求在本地验签后向 Auth 实时核对账号 `token_version` 与当前仓绑定，换仓或清空绑定后旧 Token 立即失效，Auth 不可用时拒绝请求。待收柜在首次准备时原子认领到该仓，入仓计划、尾程订单和收货会话冻结实际仓 ID/名称；国内装柜事件的仓库仅作为来源仓快照，目的仓/FBA 仓也不得冒充实际收货仓。 - 新增实际代码模块、API、权限、OpenAPI 或数据库入口后，同步更新根 `AGENTS.md`、对应应用/服务 `AGENTS.md` 和本文件；不把排期、完成比例或临时任务状态写入快速索引。 diff --git a/四期/海外仓PDA接柜入库全流程图-20260828.png b/海外仓业务/海外仓PDA接柜入库全流程图-20260828.png similarity index 100% rename from 四期/海外仓PDA接柜入库全流程图-20260828.png rename to 海外仓业务/海外仓PDA接柜入库全流程图-20260828.png diff --git a/四期/四期后端缺口清单.md b/海外仓业务/海外仓业务后端缺口清单.md similarity index 70% rename from 四期/四期后端缺口清单.md rename to 海外仓业务/海外仓业务后端缺口清单.md index d4d31f0..ba140bd 100644 --- a/四期/四期后端缺口清单.md +++ b/海外仓业务/海外仓业务后端缺口清单.md @@ -1,39 +1,39 @@ -# 四期后端缺口清单 +# 海外仓业务后端缺口清单 更新日期：2026-08-19 ## 口径与边界 -- 本清单以当前四期范围、后端代码、静态 OpenAPI、数据库基线、IAM 初始化 SQL 和本地测试为依据。 +- 本清单以当前海外仓业务范围、后端代码、静态 OpenAPI、数据库基线、IAM 初始化 SQL 和本地测试为依据。 - “已实现”表示已有可定位的领域实现、持久化和直接测试，不代表已经部署或完成测试环境 HTTP 验收。 - “部分实现”表示已有主体或单点能力，但缺少安全、契约、状态衔接或页面所需查询中的至少一项，不能作为稳定前端契约交付。 -- 明确排除海外仓出库、退货出库、海外派送及其他库存离仓履约。代码中的 `dispatch/`、`delivery/`、`ll_outbound_*` 不计入四期完成度。 +- 明确排除海外仓出库、退货出库、海外派送及其他库存离仓履约。代码中的 `dispatch/`、`delivery/`、`ll_outbound_*` 不计入海外仓业务完成度。 ## 总览 | 业务域 | 判定 | 当前事实 | 主要缺口或下一闭环 | |---|---|---|---| -| 海外 Token 与 JWKS | 部分实现 | Auth 登录与刷新已同时返回国内 Token 和短时 RS256 海外 Token，海外 Token Claims 已统一为下划线命名；JWKS、海外网关和两个海外业务服务按 `lastleg-api` Audience 验签并使用 Claims 授权，不依赖国内 Redis 会话 | 仍缺 Auth—Gateway—Servlet 服务跨模块契约测试；`POST /auth/overseas/token` 仅保留为过渡兑换能力，不作为四期稳定前端契约 | -| `gateway-overseas` 路由与入口安全 | 部分实现 | 已路由 `/api/*/v1/last-leg/**`、海外仓库、File/Print 等海外部署服务；可校验 Issuer、Audience、必要 Claims 和应用域，并清洗可信身份头 | 网关只做应用域，不做资源权限；静态路由未覆盖尚未实现的四期通用资料 API；可信身份头只传身份、不传权限是合理边界，资源权限必须由下游 JWT Claims 校验 | -| 装柜完成跨区建单 | 已实现 | Firstleg Outbox、版本化装柜完成事件、Event Bridge Inbox/重试/死信式 `DEAD`、Lastleg Inbox 幂等和事务建单均有实现及测试 | 与四期到港/可提柜衔接是另一事件，当前缺失，不能复用装柜完成事件冒充到港 | +| 海外 Token 与 JWKS | 部分实现 | Auth 登录与刷新已同时返回国内 Token 和短时 RS256 海外 Token，海外 Token Claims 已统一为下划线命名；JWKS、海外网关和两个海外业务服务按 `lastleg-api` Audience 验签并使用 Claims 授权，不依赖国内 Redis 会话 | 仍缺 Auth—Gateway—Servlet 服务跨模块契约测试；`POST /auth/overseas/token` 仅保留为过渡兑换能力，不作为海外仓业务稳定前端契约 | +| `gateway-overseas` 路由与入口安全 | 部分实现 | 已路由 `/api/*/v1/last-leg/**`、海外仓库、File/Print 等海外部署服务；可校验 Issuer、Audience、必要 Claims 和应用域，并清洗可信身份头 | 网关只做应用域，不做资源权限；静态路由未覆盖尚未实现的海外仓业务通用资料 API；可信身份头只传身份、不传权限是合理边界，资源权限必须由下游 JWT Claims 校验 | +| 装柜完成跨区建单 | 已实现 | Firstleg Outbox、版本化装柜完成事件、Event Bridge Inbox/重试/死信式 `DEAD`、Lastleg Inbox 幂等和事务建单均有实现及测试 | 与海外仓业务到港/可提柜衔接是另一事件，当前缺失，不能复用装柜完成事件冒充到港 | | 尾程订单 | 部分实现 | 有事件建单、列表、详情、CSV 导出、目的仓单条/批量调整、客户隔离与状态历史 | 平台接口大多仅校验平台应用域，未按 `list/edit/export` 等资源权限闭环；IAM 仍保留独立 `detail` 权限，违反“列表包含详情只读”统一语义；缺静态 OpenAPI | | 海外接柜、卸货与入仓 | 部分实现 | 有入仓计划转换、FBA 预约、托盘分配、PDA 实收/上架/合托/完成以及实收后库存落账 | 缺“国内出仓后到港结果 → 海外可提柜/接柜任务”的事件或内部契约；缺接柜车辆/运抵/卸货节点聚合；入仓单列表和正式详情契约不足，现有 Controller 主要是转换与单号详情；权限资源和静态 OpenAPI 未闭环 | -| 换标 | 部分实现 | 有换标申请、明细、状态历史和库存联动服务及测试 | 仅有平台接口且权限未闭环；状态机与前端四期页面字段尚无静态 OpenAPI；需确认换标完成后库存 SKU/箱唛快照的稳定查询形态 | +| 换标 | 部分实现 | 有换标申请、明细、状态历史和库存联动服务及测试 | 仅有平台接口且权限未闭环；状态机与前端海外仓业务页面字段尚无静态 OpenAPI；需确认换标完成后库存 SKU/箱唛快照的稳定查询形态 | | 海外仓托盘与库位 | 部分实现 | `warehouse-overseas-service` 有仓库、地址、能力、库位、托盘、绑定和资源锁；平台/商户及内部锁定接口均存在 | 平台资源接口要求显式 `customerId`，与“仓储资源可独立查询全部客户和仓库”的产品约定存在冲突；仅校验平台应用域，缺细粒度权限；缺静态 OpenAPI | -| 箱号管理 | 部分实现 | 一件代发领域保存来源箱唛、箱级库存和箱流水，库存查询可返回部分箱/SKU事实 | 没有面向四期 Admin 的箱号列表、详情、筛选及只读权限契约；现有 Dropship 接口是内部接收口，不能直接作为平台箱号管理 API | +| 箱号管理 | 部分实现 | 一件代发领域保存来源箱唛、箱级库存和箱流水，库存查询可返回部分箱/SKU事实 | 没有面向海外仓业务 Admin 的箱号列表、详情、筛选及只读权限契约；现有 Dropship 接口是内部接收口，不能直接作为平台箱号管理 API | | 产品库 | 缺失 | 现有 SKU 仅作为尾程明细、采购明细或一件代发库存快照存在 | 无独立产品主档、平台 CRUD/查询、唯一键/启停规则、静态 OpenAPI、权限和表结构 | -| 库存及库内操作 | 部分实现 | 有余额、仓位、流水、汇总查询；有 hold/release/allocate/unallocate/pick/ship/adjust 命令幂等；PDA 实收后可入可用库存 | 四期排除库存离仓，因此 `pick/ship` 不应作为四期交付；其余平台命令有代码权限常量但 IAM 未初始化；查询接口缺只读权限；跨仓转移包含出仓动作，需把四期可验收部分限定为不离仓库内操作；缺静态 OpenAPI | -| 海外采购订单 | 部分实现 | 商户下单、平台审核/管理、采购单据余量及测试已存在，PDA 实收才进入可用库存的边界已建立 | 页面需要的平台列表/详情/编辑字段需与现有 API 冻结；代码使用的 `lastleg:overseas-procurement:*` 未写入 IAM 种子；手工采购出库属于库存离仓，不纳入四期；缺静态 OpenAPI | -| 本土卡车 | 部分实现 | 平台/商户订单、托盘明细、状态历史和测试存在 | 需确认该子域是四期“本土卡车”而非海外派送；平台只使用单一 `manage` 权限且 IAM 未初始化；缺列表只读/操作拆分和静态 OpenAPI | +| 库存及库内操作 | 部分实现 | 有余额、仓位、流水、汇总查询；有 hold/release/allocate/unallocate/pick/ship/adjust 命令幂等；PDA 实收后可入可用库存 | 海外仓业务排除库存离仓，因此 `pick/ship` 不应作为海外仓业务交付；其余平台命令有代码权限常量但 IAM 未初始化；查询接口缺只读权限；跨仓转移包含出仓动作，需把海外仓业务可验收部分限定为不离仓库内操作；缺静态 OpenAPI | +| 海外采购订单 | 部分实现 | 商户下单、平台审核/管理、采购单据余量及测试已存在，PDA 实收才进入可用库存的边界已建立 | 页面需要的平台列表/详情/编辑字段需与现有 API 冻结；代码使用的 `lastleg:overseas-procurement:*` 未写入 IAM 种子；手工采购出库属于库存离仓，不纳入海外仓业务；缺静态 OpenAPI | +| 本土卡车 | 部分实现 | 平台/商户订单、托盘明细、状态历史和测试存在 | 需确认该子域是海外仓业务“本土卡车”而非海外派送；平台只使用单一 `manage` 权限且 IAM 未初始化；缺列表只读/操作拆分和静态 OpenAPI | | 本土散板 | 缺失 | `lastleg-service` 无稳定子域、Controller、表或测试 | 新建独立领域，不能复用出库/派送表；先冻结状态、字段、权限和与库存的非离仓边界 | | 海外仓合作仓类型 | 已实现 | 国内 Warehouse 已新增正式类型码 `OVERSEAS_PARTNER`，与普通海外仓 `OVERSEAS` 明确区分；保存、查询筛选、列表响应、批量导入、Schema 注释、统一 SQL 和测试已同步；Admin 已完成列表筛选、新增/编辑及保存透传；内部服务令牌接口 `GET /internal/warehouses/overseas-partners` 仅供海外报价服务读取当前启用候选 | 实际环境 SQL 尚未执行；前端不得调用内部合作仓接口，也不跨区域为报价拉取国内候选 | -| 海外仓报价 | 缺失 | 国内 Warehouse 有“海外仓阶梯仓租费”，但没有四期原型所指完整海外仓报价主数据；已冻结合作仓来源方案：海外报价服务仅在创建时通过内部服务身份读取国内 `ACTIVE + OVERSEAS_PARTNER` 列表并缓存 30 分钟 | 需实现报价维度、币种、有效期、服务项、仓库/客户作用域和权限/OpenAPI/SQL；报价保存合作仓 ID、编码、名称快照，缓存未命中时强制刷新一次后再拒绝 | -| 汇率管理 | 缺失 | 四期目标服务中无汇率主档、接口、权限或表 | 汇率仅作为业务换算主数据；财务记账/结算汇率口径必须交财务总控冻结 | +| 海外仓报价 | 缺失 | 国内 Warehouse 有“海外仓阶梯仓租费”，但没有海外仓业务原型所指完整海外仓报价主数据；已冻结合作仓来源方案：海外报价服务仅在创建时通过内部服务身份读取国内 `ACTIVE + OVERSEAS_PARTNER` 列表并缓存 30 分钟 | 需实现报价维度、币种、有效期、服务项、仓库/客户作用域和权限/OpenAPI/SQL；报价保存合作仓 ID、编码、名称快照，缓存未命中时强制刷新一次后再拒绝 | +| 汇率管理 | 缺失 | 海外仓业务目标服务中无汇率主档、接口、权限或表 | 汇率仅作为业务换算主数据；财务记账/结算汇率口径必须交财务总控冻结 | | 车辆列表/详情 | 缺失 | 卡车订单仅保存车辆字段快照，没有车辆主档 | 需独立车辆主数据、启停/证照字段、平台查询与权限；不得把订单快照当车辆主档 | -| 国内出仓后船节点 | 部分实现 | Firstleg 已有 `CarrierScheduleQuery` 任务、尝试、历史、来源、过期、幂等、真实订舱/柜次关联和“3 天窗口最多 3 次”约束；船期及查询任务的列表、详情、历史、船司辅助查询已统一使用 `*:list`，旧 `*:view` 初始化资源已清理 | 当前适配器全部返回 `MANUAL_REQUIRED`，Integration 无船司/轨迹 DTO、内部接口或适配器；没有定时调度、任务租约、退避、失败重试、到港停止条件、最新标准节点事实或到港跨区事件；领域 SQL 文件仍沿用历史三期命名 | -| 四期 IAM 权限 | 缺失 | 仅初始化少量尾程订单权限；代码内有库存、PDA、废弃、转仓、采购、卡车等权限常量 | 建立四期资源矩阵；所有正式列表用 `*:list` 覆盖详情和只读辅助接口，写操作独立；同步 Controller、OpenAPI、IAM 基线、统一 SQL 和契约测试 | -| 四期静态 OpenAPI | 缺失 | 船节点已有静态 YAML；Lastleg、Overseas Warehouse、Auth 海外 Token、到港事件及四期主数据没有完整静态 OpenAPI | 按浏览器公网 API、内部 API、事件三类拆分契约，先于前端正式联调冻结 DTO 与错误码 | -| 海外费用与 Finance | 跨总控依赖 | Lastleg 当前无四期费用事实 Outbox；Finance 口径不属于本总控 | 本总控只定义来源事件候选、业务键、币种/金额/来源快照与幂等字段，提交财务总控冻结入池条件、审核、结算和汇率口径后再实现生产者 | +| 国内出仓后船节点 | 部分实现 | Firstleg 已有 `CarrierScheduleQuery` 任务、尝试、历史、来源、过期、幂等、真实订舱/柜次关联和“3 天窗口最多 3 次”约束；船期及查询任务的列表、详情、历史、船司辅助查询已统一使用 `*:list`，旧 `*:view` 初始化资源已清理 | 当前适配器全部返回 `MANUAL_REQUIRED`，Integration 无船司/轨迹 DTO、内部接口或适配器；没有定时调度、任务租约、退避、失败重试、到港停止条件、最新标准节点事实或到港跨区事件；领域 SQL 文件仍沿用历史国内货柜履约命名 | +| 海外仓业务 IAM 权限 | 缺失 | 仅初始化少量尾程订单权限；代码内有库存、PDA、废弃、转仓、采购、卡车等权限常量 | 建立海外仓业务资源矩阵；所有正式列表用 `*:list` 覆盖详情和只读辅助接口，写操作独立；同步 Controller、OpenAPI、IAM 基线、统一 SQL 和契约测试 | +| 海外仓业务静态 OpenAPI | 缺失 | 船节点已有静态 YAML；Lastleg、Overseas Warehouse、Auth 海外 Token、到港事件及海外仓业务主数据没有完整静态 OpenAPI | 按浏览器公网 API、内部 API、事件三类拆分契约，先于前端正式联调冻结 DTO 与错误码 | +| 海外费用与 Finance | 跨总控依赖 | Lastleg 当前无海外仓业务费用事实 Outbox；Finance 口径不属于本总控 | 本总控只定义来源事件候选、业务键、币种/金额/来源快照与幂等字段，提交财务总控冻结入池条件、审核、结算和汇率口径后再实现生产者 | ## 已确认可复用的实现 @@ -48,7 +48,7 @@ ### 批次 0：认证与契约门禁 1. 收口海外 Token 下划线 Claims、Audience/JWKS 和 Claims 模式权限快照；增加 Auth—Gateway—Servlet 服务跨模块契约测试。 -2. 冻结四期 API 路径、DTO、错误码和权限矩阵；删除尾程/船节点旧独立详情权限，按 `list` 统一只读语义。 +2. 冻结海外仓业务 API 路径、DTO、错误码和权限矩阵；删除尾程/船节点旧独立详情权限，按 `list` 统一只读语义。 3. 为 Lastleg、Overseas Warehouse、海外 Token 增加静态 OpenAPI；补齐 Gateway 路由合同测试。 验收终点：平台/商户海外 Token 能分别访问正确应用域；错误 Audience、缺 Claim、过期/错签、伪造身份头和缺资源权限均稳定拒绝。 @@ -68,7 +68,7 @@ 2. 补齐换标、托盘、箱号、产品、库存查询及不离仓库内操作的权限/OpenAPI。 3. 调整海外仓资源查询，不以客户筛选限制仓库候选；补细粒度资源权限和越权测试。 -验收终点：四期前端所需七类海外仓页面均有稳定的列表、详情和允许操作 API，且不暴露出库/派送能力。 +验收终点：海外仓业务前端所需七类海外仓页面均有稳定的列表、详情和允许操作 API，且不暴露出库/派送能力。 ### 批次 3：海外业务闭环 @@ -83,16 +83,16 @@ 2. 实现海外仓报价、汇率、车辆主数据及权限/OpenAPI/SQL。 3. 将海外费用事件候选契约提交财务总控；只有财务口径冻结后才实现费用 Outbox。 -验收终点：合作仓、报价、汇率、车辆均可作为稳定主数据被四期业务引用；任何财务落账仍以财务总控确认契约为准。 +验收终点：合作仓、报价、汇率、车辆均可作为稳定主数据被海外仓业务业务引用；任何财务落账仍以财务总控确认契约为准。 ## 跨总控依赖 | 接收方 | 需要冻结/确认 | 本总控交付 | |---|---|---| -| 四期前端页面总控 | 合作仓类型码、各页面最小字段/筛选/动作、平台与商户 API 使用范围 | 稳定路径、DTO、枚举、权限码、错误码、分页/幂等约定和 OpenAPI；不修改前端共享导航/根路由 | +| 海外仓业务前端页面总控 | 合作仓类型码、各页面最小字段/筛选/动作、平台与商户 API 使用范围 | 稳定路径、DTO、枚举、权限码、错误码、分页/幂等约定和 OpenAPI；不修改前端共享导航/根路由 | | 财务改造总控 | 海外费用入池条件、审核与结算状态、记账/结算汇率、来源作废/调整规则 | 业务来源事件候选、不可变来源快照、业务键/版本/币种/金额/发生时间/区域和幂等语义；不改 Finance 状态机 | -当前协同状态：四期前端总控已完成双 Token 原子适配，登录/刷新消费 `overseasAccessToken: string | null` 与秒单位 `overseasExpiresIn`；海外请求缺 Token、临近过期或收到 401 时统一触发一次国内刷新并使用响应中的新海外 Token 重放，不再依赖 `POST /auth/overseas/token`。共享认证定向 19 个测试已通过；前端后续全量 typecheck 与 build 也已通过。 +当前协同状态：海外仓业务前端总控已完成双 Token 原子适配，登录/刷新消费 `overseasAccessToken: string | null` 与秒单位 `overseasExpiresIn`；海外请求缺 Token、临近过期或收到 401 时统一触发一次国内刷新并使用响应中的新海外 Token 重放，不再依赖 `POST /auth/overseas/token`。共享认证定向 19 个测试已通过；前端后续全量 typecheck 与 build 也已通过。 合作仓协同状态：Admin 已启用 `OVERSEAS_PARTNER` 的类型、筛选、新增、编辑与保存透传，普通 `OVERSEAS` 保持独立；前端定向 30 个测试、全量 1144 个测试、typecheck 与 build 均通过。前端不调用 `/internal/warehouses/overseas-partners`，该接口只属于未来海外报价服务的服务间契约。 diff --git a/四期/船节点标准化契约.md b/海外仓业务/船节点标准化契约.md similarity index 97% rename from 四期/船节点标准化契约.md rename to 海外仓业务/船节点标准化契约.md index 942bbac..e8f9e93 100644 --- a/四期/船节点标准化契约.md +++ b/海外仓业务/船节点标准化契约.md @@ -1,4 +1,4 @@ -# 四期船节点标准化契约 +# 海外仓业务船节点标准化契约 > 状态：已确认 > @@ -12,7 +12,7 @@ - 每家供应商保留自己的原始节点编码和文案，再映射到本契约的标准节点。 - 供应商没有提供的标准节点保持缺失，不推测、不补造，也不要求所有船司返回相同数量的节点。 -- 四期船节点从国内确认出仓开始，持续记录至已还柜 `EMPTY_RETURNED` 后停止。 +- 海外仓业务船节点从国内确认出仓开始，持续记录至已还柜 `EMPTY_RETURNED` 后停止。 - `PICKED_UP`、`EMPTY_RETURNED` 在本契约中只是货柜轨迹事实，不代表启用海外派送、海外仓出库或库存离仓业务。 - Firstleg 拥有查询任务、标准节点、异常事实和停止条件；Integration Service 只负责供应商访问、解析、标准化和错误归一化。 @@ -162,6 +162,6 @@ - Firstleg 的标准节点枚举、任务状态推进、节点事实、查询历史、停止条件、SQL 约束和 OpenAPI。 - Admin 的 TypeScript 类型、节点中文文案、时间展示、状态标签和页面测试。 - HTTP 验收脚本中的节点枚举、详情和历史断言。 -- 四期 README、相关 `AGENTS.md` 和新增供应商映射证据。 +- 海外仓业务 README、相关 `AGENTS.md` 和新增供应商映射证据。 不得只修改某一家适配器而跳过统一模型，也不得为单一供应商新增含义重复的业务节点。 diff --git a/四期/三期装柜完成后至四期人工验收手册.md b/海外仓业务/虫虫出海全流程人工验收手册.md similarity index 84% rename from 四期/三期装柜完成后至四期人工验收手册.md rename to 海外仓业务/虫虫出海全流程人工验收手册.md index 32507ea..92a54e1 100644 --- a/四期/三期装柜完成后至四期人工验收手册.md +++ b/海外仓业务/虫虫出海全流程人工验收手册.md @@ -1,27 +1,27 @@ -# 三期装柜完成后至四期人工验收手册 +# 虫虫出海全流程人工验收手册 > 适用环境：开发环境 > 国内 API：`http://dev-api-cn.buggoglobal.com` > 海外 API：`http://dev-api-global.buggoglobal.com` -> 验收起点：国内装柜已完成，入库单和装柜计划已经进入 `LOADED` / `COMPLETED` -> 验收终点：海外仓完成签收、实收和库存落账；四期独立主数据与海外业务完成各自生命周期核对 +> 验收起点：客户与账号有效，客户订单具备可履约货物 +> 验收终点：海外仓完成入仓、库内服务、出库和派送；异常退回、一件代发及国内外回写均可核对 -## 1. 本手册不重复的内容 +## 1. 全流程范围 -以下属于装柜完成前流程，本手册不再重复： +本手册统一覆盖： -- 客户建档、资质审核和账号创建； -- 客户下单、入库单生成、测量、称重和计费； -- 分柜、智能排柜、预装清单和真实柜号关联； -- 订舱放舱、国内 PDA 拣货、装柜照片和铅封证据； -- 报关资料、补件、代理提交和放行回执； -- 将入库单推进至 `LOADED` 的装柜完成操作。 +- 客户建档、资质审核、账号、角色和权限； +- 客户下单、入库单、测量称重、尺寸策略、计价和费用； +- 分柜、同柜、智能排柜、订舱、拖车、国内 PDA 拣货、装柜、报关和国内出仓； +- 船节点、跨区建单、海外接柜、卸货入仓、库存、托盘、换标、转运、废弃和退货换标； +- 排车、海外 PDA 拣货与出库、发车、转派送、派送完成、异常退回和客户回访； +- 一件代发、海外采购、本土卡车、本土散板、海外费用来源及国内外事件回写。 -本手册从已有 `LOADED` 柜次开始。若开发库没有可用柜次，可先运行第 15 节的自动化脚本生成隔离数据，但人工页面验收仍从 `LOADED` 柜次开始记录。 +可按业务域分段复核，但最终结论必须以端到端状态、库存、费用、权限和事件一致为准。开发库没有可用数据时，可使用第 15 节自动化脚本生成隔离数据。 ## 2. 当前验收边界 -### 2.1 本轮必须验收 +### 2.1 必须验收 1. 国内出仓确认与撤销边界； 2. 出仓后自动创建船节点查询任务； @@ -33,15 +33,20 @@ 8. 海外仓合作仓、报价、汇率和车辆主数据； 9. 海外采购、本土卡车和本土散板； 10. 海外账号、权限、双 Token、撤权即时失效和跨区事件回写。 +11. 客户换标、仓储转运、货物废弃和退货换标； +12. 排车编辑/取消、海外 PDA 拣货、出库、发车和转派送； +13. 客户派送单、派送状态、派送完成和签收附件； +14. 异常订单、派送退回入仓和客户回访； +15. 一件代发 SKU/箱唛库存与出库。 -### 2.2 明确不验收 +### 2.2 验收方式边界 -- 海外仓出库、退货出库和海外派送； - 箱号管理和产品库正式页面； -- PDA 出库拣货或派送； - 车辆派送履约历史； - 通过数据库手工修改业务状态； - 使用历史柜、伪造节点或直接调用内部接口代替正式流程。 +- 派送由 Admin/Client 验收，不要求在海外 PDA 提供派送页面。 +- PDA 工作台未注册的库内操作通过真实 HTTP、Admin/Client 页面和最终库存事实联合验收，不把终端入口与业务能力混为一谈。 ### 2.3 页面与接口验收层级 @@ -54,6 +59,9 @@ | 采购创建 | 自动化 HTTP 或具备客户入口时由客户创建 | Admin 当前主要承载列表、详情、编辑和审核结果查看 | | 本土卡车、本土散板 | Admin 页面 | 可创建、编辑并核对状态 | | 海外主数据 | Admin 页面 | 报价、汇率、车辆支持创建和状态维护 | +| 排车、出库和发车 | Admin + 海外 PDA | 核对拣货、出库数量、发车门禁与状态历史 | +| 派送、异常退回和客户回访 | Admin + Client | 核对客户范围、派送状态、退回入仓和附件 | +| 一件代发 | Client/Admin + 海外 PDA | 核对 SKU/箱唛快照、库存扣减、幂等和出库结果 | ## 3. 验收人员和账号准备 @@ -62,7 +70,7 @@ | 身份 | 用途 | 必须满足 | | ---------------- | -------------------------- | ---------------------------------------------------------------------------------------- | -| 平台管理员 | Admin 全部页面验收 | 使用开发环境验收账号；具备三、四期 canonical 权限 | +| 平台管理员 | Admin 全部页面验收 | 使用开发环境验收账号；具备三、海外仓业务 canonical 权限 | | 海外仓操作员 | 海外 PDA 真机验收 | 角色为`WAREHOUSE_PICKER`；权限含 `lastleg:pda:operate`；绑定且只能绑定一个实际海外收货仓 | | 第二海外仓操作员 | 抢柜和账号隔离验证 | 与第一操作员绑定同一实际海外仓 | | 客户账号 | 客户侧采购或海外仓服务验证 | 客户状态为`ACTIVE`，国内/海外 Token 属于同一客户主体 | @@ -296,8 +304,8 @@ Admin → **系统管理 → 用户管理**： ### 10.1 登录检查 - 登录成功后同时取得国内和海外会话； -- 首页只开放 **入仓作业 → 拆柜收货**； -- 库存盘点、商品移库、托盘管理、换标和现场查询入口当前应显示未开放； +- 首页开放已注册的拆柜收货、库存盘点、商品移库、托盘管理、换标收货/执行/复核、库存/库位/托盘查询、排车拣货和出库作业； +- 库内、换标和现场查询需在 PDA 页面验收扫码/人工输入、错误恢复，并与真实 HTTP 及 Admin/Client 最终事实交叉核对； - 平台管理员或普通客户账号不得进入拆柜收货。 ### 10.2 选择柜号 @@ -389,7 +397,7 @@ Admin → **海外仓 → 尾程订单/入库单**： - 状态已完成入仓； - 总箱数、实收箱数、入仓码和柜号一致； - 历史包含创建、签收、实收和完成事实； -- 不出现出库或派送状态。 +- 出库、派送和异常状态只来自对应子单及状态历史，不覆盖尾程主流程状态。 ### 12.2 库存 @@ -421,7 +429,7 @@ Admin → **海外仓 → 托盘管理**： - 实际报空/卸柜事实没有重复写入； - 相同海外卸柜完成事件重放不产生第二条事实。 -## 13. PDA P2～P5 后端验收与当前前端边界 +## 13. 海外 PDA 库内能力与终端边界 以下后端能力已经纳入真实 HTTP 自动化： @@ -430,15 +438,15 @@ Admin → **海外仓 → 托盘管理**： - P4：换托、拆托、合托、解绑、物理状态补偿和幂等； - P5：换标认领、正常处理、跳过、异常、返工、复核和完成。 -当前海外 PDA 工作台这些入口仍为 `available: false`。因此人工验收规则是： +当前海外 PDA 工作台已开放库存盘点、商品移库、托盘管理、换标收货/执行/复核和库存/库位/托盘查询，按以下规则验收： -1. 不要求验收人员在真机点击不存在的页面； -2. 使用第 15 节自动化报告证明写链； -3. 在 Admin 的库存、托盘和换标页面人工核对自动化产生的最终事实； -4. 等 PDA 页面按最终原型接入后，再追加真机操作、扫码焦点、弱网恢复和视觉验收； -5. 在此之前不能把“后端 HTTP 已通”写成“PDA 页面已验收”。 +1. 在 H5 使用人工输入完成基础流程与错误态检查，在 PDA 真机补充广播扫码、拍照和设备返回行为； +2. 使用第 15 节自动化报告证明写链、幂等、旧版本冲突和资源隔离； +3. 在 Admin 的库存、托盘和换标页面核对 PDA 作业产生的最终事实； +4. 网络失败后保留任务和稳定幂等键，恢复时以服务端当前状态为准，不得重复提交； +5. 排车拣货、出库和发车同样必须补充真机扫码、弱网恢复和视觉证据。 -## 14. 四期独立业务验收 +## 14. 海外仓业务独立业务验收 这些业务与柜号主链共享账号、权限和海外 Gateway，但不依赖同一柜次才能创建。 @@ -514,7 +522,7 @@ Admin → **海外业务 → 本土散板**： 6. 终态不能逆向推进； 7. 不复用本土卡车状态或接口。 -### 14.7 排车查询与智能预排 +### 14.7 排车、出库与派送 Admin → **海外仓 → 排车列表**： @@ -523,7 +531,10 @@ Admin → **海外仓 → 排车列表**： - 草稿加入托盘后立即锁定； - 从草稿移除或关闭时释放锁； - 预排创建后锁转换为正式排车锁； -- 本期只验收查询和预排，不验收编辑、取消、发车、PDA 出库或派送。 +- 编辑、取消、PDA 拣货、出库、发车和转派送均需验收； +- 转派送必须发生在发车前，并生成待出库单； +- PDA 只按服务端 `canDepart` 与 `departBlockReason` 开放发车； +- 派送完成、异常退回入仓和客户回访必须保留状态及附件证据。 ## 15. 自动化复核：数据怎么自动创建和清理 @@ -538,7 +549,7 @@ $env:ADMIN_TEST_USERNAME='platform_admin' $env:ADMIN_TEST_PASSWORD='<从本机安全配置读取>' node scripts/admin-test-env-acceptance.mjs ` - --modules phase4-overseas-warehouse,phase4-overseas-pda,phase4-overseas-pda-operations,phase4-overseas-inbound-operations,phase4-overseas-client-services,phase4-overseas-dispatch,phase4-cross-region-events,phase4-overseas-business,phase4-overseas-master-data,phase4-carrier-nodes + --modules phase4-overseas-warehouse,phase4-overseas-pda,phase4-overseas-pda-operations,phase4-overseas-inbound-operations,phase4-overseas-client-services,phase4-overseas-dispatch,phase5-overseas-fulfillment,phase4-cross-region-events,phase4-overseas-business,phase4-overseas-master-data,phase4-carrier-nodes ``` ### 15.2 自动数据流 @@ -617,14 +628,17 @@ node scripts/admin-test-env-acceptance.mjs ` - [ ] 国内柜次收到海外卸柜完成回写 - [ ] `EMPTY_RETURNED` 后船节点任务 `STOPPED` -### 17.2 独立业务完成 +### 17.2 海外仓与派送完成 - [ ] 海外合作仓可创建和筛选 - [ ] 报价、汇率、车辆完成创建/编辑/状态/导出 - [ ] 采购完成创建事实、编辑三态、审核和流水核对 - [ ] 本土卡车完成创建、编辑和版本冲突核对 - [ ] 本土散板完成创建、编辑、状态流转和终态核对 -- [ ] 排车查询与智能预排没有扩大到出库和派送 +- [ ] 换标、转运、废弃和退货换标完成并可核对库存流水 +- [ ] 排车完成预排、编辑、PDA 拣货、出库、发车和状态核对 +- [ ] 转派送、派送完成、异常退回和客户回访完成 +- [ ] 一件代发 SKU/箱唛库存与出库数量核平 ### 17.3 验收结论分级 @@ -632,13 +646,13 @@ node scripts/admin-test-env-acceptance.mjs ` | 结论 | 条件 | | ---------- | ------------------------------------------------------------------------------------------------ | | 通过 | 所有必验项通过，无 S0500/5xx/数据串仓；自动化报告全绿；页面/真机证据齐全 | -| 有条件通过 | 后端和业务状态全通，仅剩已明确的 PDA P2～P5 页面尚未按原型接入，已记录负责人和补验时间 | +| 有条件通过 | 业务状态全通，但存在已明确不由当前终端承载的页面；替代验收证据齐全且不影响端到端业务结果 | | 不通过 | 主链断裂、状态可绕过、权限越权、重复入账、跨客户/跨仓串数据、非预期 S0500/5xx 或关键页面不可操作 | ## 18. 验收证据目录建议 ```text -三四期人工验收-YYYYMMDD/ +虫虫出海全流程人工验收-YYYYMMDD/ 01-装柜完成起点/ 02-国内出仓/ 03-船节点/ @@ -651,6 +665,9 @@ node scripts/admin-test-env-acceptance.mjs ` 10-采购卡车散板/ 11-权限弱网反证/ 12-自动化报告/ + 13-换标转运退货/ + 14-排车出库派送/ + 15-异常回访一件代发/ ``` 每张截图保留浏览器地址、柜号/业务单号、状态和时间；不得把密码、完整 Token、身份证件原图或其他敏感信息放入验收包。 diff --git a/统一订单主状态与操作契约.md b/统一订单主状态与操作契约.md index 42288e0..dd075bc 100644 --- a/统一订单主状态与操作契约.md +++ b/统一订单主状态与操作契约.md @@ -37,7 +37,7 @@ ## 三、门禁与修改规则 -- `WAIT_MEASURE -> WAIT_SPLIT` 必须满足二期测量、审核和费用确认契约；客户确认和差异沟通不单独增加主状态，也不替代服务端门禁。 +- `WAIT_MEASURE -> WAIT_SPLIT` 必须满足入库测量与计费测量、审核和费用确认契约；客户确认和差异沟通不单独增加主状态，也不替代服务端门禁。 - `LOADING -> LOADED` 必须由服务端校验订舱完成、拖车完成、有效放行回执、PDA 拣货完成、五类证据各至少一张有效照片及锁码文本；任何一项缺失都不得推进。 - 本版本不新增异常、驳回、阻塞、取消等主状态。异常说明、差异说明和补充资料作为子状态、备注、附件或自定义节点保存。 - `LOADED` 前的业务资料可在权限和状态规则内修改；修改资料不自动回退主状态。`LOADED` 后错误统一线下人工处理，国内系统不提供在线冲正。 @@ -83,7 +83,7 @@ → 智能分柜并确认预装清单 → 完成订舱、拖车、报关放行和 PDA 拣货 → 五类有效照片及锁码文本通过门禁 -→ 装柜完成（LOADED，国内三期终点） +→ 装柜完成（LOADED，国内国内货柜履约终点） ``` -后续由海外仓可信回传把 `LOADED` 推进为 `DELIVERED`，不属于国内三期验收主链。每一段均需验证：满足门禁时可推进、重复操作幂等、操作有留痕、客户未确认不额外阻断，并且 Admin、Client、PDA 显示同一主状态。 +后续由海外仓可信回传把 `LOADED` 推进为 `DELIVERED`，不属于国内国内货柜履约验收主链。每一段均需验证：满足门禁时可推进、重复操作幂等、操作有留痕、客户未确认不额外阻断，并且 Admin、Client、PDA 显示同一主状态。 diff --git a/一期/README.md b/订单与客户/README.md similarity index 58% rename from 一期/README.md rename to 订单与客户/README.md index 3ae0c6f..1ef2db1 100644 --- a/一期/README.md +++ b/订单与客户/README.md @@ -1,29 +1,29 @@ -# 一期文档 +# 订单与客户文档 -一期目标是完成平台后台与企业客户端的真实业务基础，以及头程订单最小闭环。 +订单与客户目标是完成平台后台与企业客户端的真实业务基础，以及头程订单最小闭环。 ## 当前主体模型 -- 一期及后续未单独启用租户能力的阶段统一按“平台—客户”两级开发，当前是业务单租户、平台管理多客户、客户严格隔离。 +- 订单与客户及后续未单独启用租户能力的阶段统一按“平台—客户”两级开发，当前是业务单租户、平台管理多客户、客户严格隔离。 - Java 与接口中的 `tenant_id > 0`、`tenantId` 当前表示客户 ID，是客户隔离兼容字段；`tenant_id=0` 是平台账号和平台 RBAC 的技术作用域，不是可管理租户。 - 历史表名、类名、接口路径和字段保留 `tenant` 命名，但不得据此新增租户主表、租户选择器、租户级权限或把现有字段改义为上级租户。 ## 文档 -- [一期开发进度表](一期开发进度表.md) -- [一期头程订单闭环设计](一期头程订单闭环设计.md) -- `虫虫出海一期开发进度表.xlsx`：面向团队日常维护的 Excel 进度表。 +- [订单与客户开发进度表](订单与客户开发进度表.md) +- [订单与客户头程订单闭环设计](订单与客户头程订单闭环设计.md) +- `虫虫出海订单与客户开发进度表.xlsx`：面向团队日常维护的 Excel 进度表。 ## 原型来源 - 产品原型统一位于 `docs/悦/`。 -- 企业登录与注册分别参考 `docs/悦/合并/login.html`、`docs/悦/合并/register.html`；一期只默认包含中文账号密码登录和基础企业注册闭环。 +- 企业登录与注册分别参考 `docs/悦/合并/login.html`、`docs/悦/合并/register.html`；订单与客户只默认包含中文账号密码登录和基础企业注册闭环。 - 快递公司和往来单位参考 `docs/悦/货代SAAS平台后台/货代SaaS平台原型.html` 中“通用”菜单下的对应页面。 -- 原型用于确认信息架构、字段和视觉方向；是否已进入当前 Vue 应用、是否具备完整交互与数据持久化，以一期开发进度表为准。 +- 原型用于确认信息架构、字段和视觉方向；是否已进入当前 Vue 应用、是否具备完整交互与数据持久化，以订单与客户开发进度表为准。 ## 当前边界 -- 平台后台：内部账号登录、客户及企业资料审核、内部用户、角色权限、平台收货仓、快递公司、往来单位和头程订单；工作台不作为一期交付项。 -- 企业客户端：中文邮箱/手机号加密码登录、免审核企业注册、企业资料、成员角色权限、头程下单、订单列表和详情；企业资料经平台人工审核通过后才允许提交订单，一期不接短信/邮箱验证码及微信、企业微信登录。 +- 平台后台：内部账号登录、客户及企业资料审核、内部用户、角色权限、平台收货仓、快递公司、往来单位和头程订单；工作台不作为订单与客户交付项。 +- 企业客户端：中文邮箱/手机号加密码登录、免审核企业注册、企业资料、成员角色权限、头程下单、订单列表和详情；企业资料经平台人工审核通过后才允许提交订单，订单与客户不接短信/邮箱验证码及微信、企业微信登录。 - 服务端：认证、基于兼容字段 `tenant_id` 的客户隔离、权限、文件、基础资料、订单状态机、幂等和审计。 -- 不包含工作台、部门/组织架构、完整 WMS、FBA/海外目的仓服务、在线报价、财务结算、完整报关清关、外部物流接口、多语言及微信/企业微信登录；快递公司和往来单位一期支持批量导入，不提供导出。 +- 不包含工作台、部门/组织架构、完整 WMS、FBA/海外目的仓服务、在线报价、财务结算、完整报关清关、外部物流接口、多语言及微信/企业微信登录；快递公司和往来单位订单与客户支持批量导入，不提供导出。 diff --git a/订单与客户/虫虫出海订单与客户开发进度表.xlsx b/订单与客户/虫虫出海订单与客户开发进度表.xlsx new file mode 100644 index 0000000..6c49842 Binary files /dev/null and b/订单与客户/虫虫出海订单与客户开发进度表.xlsx differ diff --git a/一期/一期头程订单闭环设计.md b/订单与客户/订单与客户头程订单闭环设计.md similarity index 82% rename from 一期/一期头程订单闭环设计.md rename to 订单与客户/订单与客户头程订单闭环设计.md index e944a21..7268eed 100644 --- a/一期/一期头程订单闭环设计.md +++ b/订单与客户/订单与客户头程订单闭环设计.md @@ -1,14 +1,14 @@ -# 一期头程订单闭环设计 +# 订单与客户头程订单闭环设计 > 状态：产品决策已确认，前端静态闭环实施中 > 创建日期：2026-07-28 > 适用范围：`apps/client-web`、`apps/admin-web`、`baiyue-firstleg` -> 主体模型：本设计按“平台—客户”两级执行。现有 `tenant_id > 0` / `tenantId` 当前表示客户 ID，是客户隔离兼容字段；`tenant_id=0` 是平台技术作用域。历史命名继续兼容，不在一期引入真实租户层。 +> 主体模型：本设计按“平台—客户”两级执行。现有 `tenant_id > 0` / `tenantId` 当前表示客户 ID，是客户隔离兼容字段；`tenant_id=0` 是平台技术作用域。历史命名继续兼容，不在订单与客户引入真实租户层。 ## 一、目标 -一期形成可验收的最小订单闭环： +订单与客户形成可验收的最小订单闭环： 1. 企业注册成功后可直接登录，不经过注册审核。 2. 企业提交资料，由平台人员人工点击审核通过；只有审核通过的企业才可提交头程订单。 @@ -21,20 +21,20 @@ ## 原型依据与迁移原则 -一期原型统一以 `docs/悦/` 为依据。快递公司、往来单位的直接参考页面位于 `docs/悦/货代SAAS平台后台/货代SaaS平台原型.html` 的“通用”菜单： +订单与客户原型统一以 `docs/悦/` 为依据。快递公司、往来单位的直接参考页面位于 `docs/悦/货代SAAS平台后台/货代SaaS平台原型.html` 的“通用”菜单： -| 原型页面 | 已有内容 | 一期迁移说明 | +| 原型页面 | 已有内容 | 订单与客户迁移说明 | |---|---|---| -| 快递公司 | 公司名称、编码、官网、客服电话、合作状态；名称/编码和状态筛选；新增、导入、导出、编辑入口 | 保留核心字段与列表方向；状态统一映射为 `ACTIVE` / `INACTIVE`；一期实现标准模板导入，不实现导出 | -| 往来单位 | 单位名称、类型、联系人、电话、启停状态；名称、类型和状态筛选；新增、导入、导出、编辑、详情入口 | 补充稳定编码、邮箱和完整地址；类型与一期订单的发货方/收货方角色统一；一期实现标准模板导入，不实现导出 | +| 快递公司 | 公司名称、编码、官网、客服电话、合作状态；名称/编码和状态筛选；新增、导入、导出、编辑入口 | 保留核心字段与列表方向；状态统一映射为 `ACTIVE` / `INACTIVE`；订单与客户实现标准模板导入，不实现导出 | +| 往来单位 | 单位名称、类型、联系人、电话、启停状态；名称、类型和状态筛选；新增、导入、导出、编辑、详情入口 | 补充稳定编码、邮箱和完整地址；类型与客户订单的发货方/收货方角色统一；订单与客户实现标准模板导入，不实现导出 | 现有 HTML 原型已完成菜单、静态列表、演示数据和表格渲染，但多数按钮没有完整的数据提交、校验、失败反馈和持久化流程。因此迁移到 `apps/admin-web`、`apps/client-web` 时，必须按当前项目的 Vue、Pinia、RBAC、响应式和测试约定重新实现，不能把原型存在等同于当前工程已经完成。 -原型负责提供信息架构、字段和视觉参考；一期范围、数据隔离、权限和历史快照规则以本设计及开发进度表为准。原型中的 FBA、海外仓、库位、货架、托盘、船期价格和完整 WMS 菜单不因复用同一页面而进入一期。 +原型负责提供信息架构、字段和视觉参考；订单与客户范围、数据隔离、权限和历史快照规则以本设计及开发进度表为准。原型中的 FBA、海外仓、库位、货架、托盘、船期价格和完整 WMS 菜单不因复用同一页面而进入订单与客户。 -## 二、一期边界 +## 二、订单与客户边界 -### 纳入一期 +### 纳入订单与客户 - 客户端：订单列表、组合筛选、创建、编辑草稿、提交、详情、取消。 - 管理后台：企业资料审核通过、订单列表、详情、待审核订单人工修改、受理、负责人分配和状态更新。 @@ -43,9 +43,9 @@ - 平台收货仓：后台维护国内收货仓档案和启停状态；客户端新建订单只选择已启用仓库。 - 快递公司：后台人员统一维护快递公司档案和启停状态；企业客户端不维护，订单详情只读展示履约快递信息。 - 往来单位：后台人员维护发货单位、收货单位、供应商和服务商；企业客户端只读选择当前可用的发货方和收货方。 -- 货物信息：一期至少支持一条货物明细，并允许同一订单包含多条明细。 +- 货物信息：订单与客户至少支持一条货物明细，并允许同一订单包含多条明细。 -### 暂不纳入一期 +### 暂不纳入订单与客户 - 在线询价、自动报价和费率计算。 - 应收应付、对账、结算和利润核算。 @@ -54,9 +54,9 @@ - Excel 批量下单、快速下单和复制订单。 - 客户端批量取消或批量修改。 - FBA/海外目的仓、库存、库位、货架及入出库等 WMS 作业。 -- 将旧架构文档中的 11 个微服务直接作为一期落地方案。 +- 将旧架构文档中的 11 个微服务直接作为订单与客户落地方案。 -原型中的 FBA 批量下单、渠道、商检、退税和复杂货物属性作为后续扩展依据，不进入一期最小闭环的必填字段。 +原型中的 FBA 批量下单、渠道、商检、退税和复杂货物属性作为后续扩展依据，不进入订单与客户最小闭环的必填字段。 ## 三、参与者与数据边界 @@ -71,15 +71,15 @@ 服务端必须从已验证身份中取得客户归属上下文。客户端传入的 `tenantId`、`customerId` 或查询参数不能单独作为授权依据；其中 `tenantId` 是客户 ID 的兼容参数名。 -企业客户端菜单和操作权限由企业管理员为本企业角色分配。一个成员可拥有多个角色，权限取角色权限并集；一期不引入部门或组织架构，成员直接归属企业。企业管理员不能配置平台后台菜单，也不能跨企业授权。 +企业客户端菜单和操作权限由企业管理员为本企业角色分配。一个成员可拥有多个角色，权限取角色权限并集；订单与客户不引入部门或组织架构，成员直接归属企业。企业管理员不能配置平台后台菜单，也不能跨企业授权。 客户读取、更新、提交和取消订单时，服务端必须同时匹配订单 ID、当前客户 ID（兼容字段 `tenant_id`）和删除标记；不允许先按全局 ID 查出订单后再仅依赖前端隐藏。 -平台国内收货仓由后台统一维护，企业客户只读选择。停用仓库不得用于新建或重新提交订单，但不能破坏历史订单已经保存的仓库名称；一期首批覆盖义乌、深圳、青岛、上海、宁波和厦门，不将其与 FBA/海外目的仓混为同一模型。 +平台国内收货仓由后台统一维护，企业客户只读选择。停用仓库不得用于新建或重新提交订单，但不能破坏历史订单已经保存的仓库名称；订单与客户首批覆盖义乌、深圳、青岛、上海、宁波和厦门，不将其与 FBA/海外目的仓混为同一模型。 快递公司和往来单位均由当前平台后台人员维护。企业客户端不提供对应的新增、编辑、启停菜单和写接口：快递公司只通过订单详情展示，往来单位只用于下单时只读查询和选择。服务端必须按后台人员权限和数据范围校验写操作，并按当前企业可见范围过滤客户端往来单位查询，不能依赖前端隐藏按钮实现边界。 -## 四、一期订单状态 +## 四、客户订单状态 ### 已确认的统一状态 @@ -90,10 +90,10 @@ | `ACCEPTED` | 已受理 | 平台审核通过并进入履约准备 | | `BOOKED` | 已订舱 | 已完成舱位或对应运输资源确认 | | `IN_TRANSIT` | 运输中 | 货物已进入运输过程 | -| `COMPLETED` | 已完成 | 一期订单履约结束 | +| `COMPLETED` | 已完成 | 客户订单履约结束 | | `CANCELLED` | 已取消 | 客户或平台按规则取消 | -该方案与当前管理后台实现最接近。两个前端应用内 `shared/` 现有“处理中”以及旧架构文档中的“已确认、已报关、到港待提”不作为一期并存状态；产品确认后分别迁移。 +该方案与当前管理后台实现最接近。两个前端应用内 `shared/` 现有“处理中”以及旧架构文档中的“已确认、已报关、到港待提”不作为订单与客户并存状态；产品确认后分别迁移。 ### 允许的状态转换 @@ -106,12 +106,12 @@ - 草稿可由客户编辑、提交或取消。 - 待审核订单允许获授权的后台人员人工修改；平台无法直接确认的信息由平台联系客户修改。客户和后台修改后订单仍保持待审核，修改前后值、操作者和时间必须写入审计记录。 -- 已受理后取消可能已经产生成本，一期默认仅平台可执行；客户只能联系平台处理。 +- 已受理后取消可能已经产生成本，订单与客户默认仅平台可执行；客户只能联系平台处理。 - 已订舱、运输中和已完成不允许客户取消。 - 已取消和已完成为终态，不允许直接恢复。 - 所有状态变更必须校验当前状态，不能由前端提交任意目标状态。 -## 五、一期数据模型 +## 五、订单与客户数据模型 ### 企业资料审核状态 @@ -134,7 +134,7 @@ | `consigneeSnapshot` | 私人仓时提交必填 | 仅目的仓类型为 `PRIVATE` 时保存私人收件地址快照；FBA 仓、海外仓使用所选公共仓主数据，不重复填写收件资料 | | `deliveryInfo` | 平台维护 | 可选履约信息，包含快递公司 ID/快照和快递单号；企业客户端只读 | | `transportMode` | 提交必填 | FCL、LCL、AIR、ROAD | -| `businessType` | 提交必填 | 一期支持 EXPORT、IMPORT | +| `businessType` | 提交必填 | 订单与客户支持 EXPORT、IMPORT | | `origin` | 提交必填 | 起运地或起运港 | | `destination` | 提交必填 | 目的地或目的港 | | `expectedDepartureDate` | 可选 | 客户期望出发日期，不等同于平台确认 ETD | @@ -147,7 +147,7 @@ | `version` | 服务端维护 | 乐观锁版本，防止覆盖并发修改 | | `createdBy`、`createdAt`、`updatedAt` | 服务端维护 | 审计信息 | -订单金额不由客户创建接口提交。一期若后台继续展示金额，应标记为平台估算字段，并在报价/结算范围确认后单独设计。 +订单金额不由客户创建接口提交。订单与客户若后台继续展示金额，应标记为平台估算字段，并在报价/结算范围确认后单独设计。 ### 平台收货仓 @@ -176,7 +176,7 @@ | `status` | `ACTIVE` 或 `INACTIVE` | | `remark`、`updatedAt` | 后台说明和更新时间 | -快递公司只能由获授权的后台人员维护。停用后不得新增到订单履约信息，但历史订单继续展示保存的快递公司名称和编码。企业客户端不直接查询快递公司主数据，只通过订单详情响应读取后台已保存的履约信息。一期不接快递轨迹订阅和自动回传；一个订单只支持一组快递公司与快递单号，多包裹和多段运输后续扩展。 +快递公司只能由获授权的后台人员维护。停用后不得新增到订单履约信息，但历史订单继续展示保存的快递公司名称和编码。企业客户端不直接查询快递公司主数据，只通过订单详情响应读取后台已保存的履约信息。订单与客户不接快递轨迹订阅和自动回传；一个订单只支持一组快递公司与快递单号，多包裹和多段运输后续扩展。 ### 往来单位 @@ -185,7 +185,7 @@ | `id` | 服务端稳定 ID | | `code` | 所属数据范围内唯一编码 | | `name` | 单位名称 | -| `types` | 可多选的稳定单位类型集合；一期覆盖供应商、客户、承运商、报关行、发货单位和收货单位 | +| `types` | 可多选的稳定单位类型集合；订单与客户覆盖供应商、客户、承运商、报关行、发货单位和收货单位 | | `contactName`、`contactPhone`、`email` | 主要联系人信息 | | `country`、`province`、`city`、`postalCode`、`address` | 主要地址信息 | | `status` | `ACTIVE` 或 `INACTIVE` | @@ -196,9 +196,9 @@ ### 基础资料批量导入 -一期确认支持后台批量导入快递公司和往来单位，企业客户端不提供导入入口。平台提供版本化的 `.xlsx` 标准模板；后台人员上传后，服务端先完成整批校验，存在任一错误时不写入业务表，并返回包含行号、字段和原因的错误报告。 +订单与客户确认支持后台批量导入快递公司和往来单位，企业客户端不提供导入入口。平台提供版本化的 `.xlsx` 标准模板；后台人员上传后，服务端先完成整批校验，存在任一错误时不写入业务表，并返回包含行号、字段和原因的错误报告。 -导入至少校验必填字段、稳定编码、名称、单位类型、联系方式、地址、数据范围和启停值；同一文件内重复、与现有档案重复或越过操作人数据范围的记录必须拒绝，不得静默覆盖已有档案。一期批量导入只新增，不更新或覆盖已有档案；任一记录失败时整批不写入。每次导入记录操作人、原始文件名、总行数、成功/失败数量、失败原因摘要和服务端时间。文件大小和最大行数使用服务端可配置上限；快递公司和往来单位导出不纳入一期。 +导入至少校验必填字段、稳定编码、名称、单位类型、联系方式、地址、数据范围和启停值；同一文件内重复、与现有档案重复或越过操作人数据范围的记录必须拒绝，不得静默覆盖已有档案。订单与客户批量导入只新增，不更新或覆盖已有档案；任一记录失败时整批不写入。每次导入记录操作人、原始文件名、总行数、成功/失败数量、失败原因摘要和服务端时间。文件大小和最大行数使用服务端可配置上限；快递公司和往来单位导出不纳入订单与客户。 ### 货物明细 @@ -268,7 +268,7 @@ | `POST` | `/api/v1/admin/first-leg-orders/{id}/cancel` | `first-leg:status` | 平台取消，原因必填 | | `GET` | `/api/v1/admin/company-verifications` | `company:verification:list` | 查询企业资料审核状态和待审核企业 | | `GET` | `/api/v1/admin/company-verifications/{companyId}` | `company:verification:list` | 查看企业资料与资质详情 | -| `POST` | `/api/v1/admin/company-verifications/{companyId}/approve` | `company:verification:approve` | 人工点击审核通过并开通下单资格；一期无驳回动作 | +| `POST` | `/api/v1/admin/company-verifications/{companyId}/approve` | `company:verification:approve` | 人工点击审核通过并开通下单资格；订单与客户无驳回动作 | | `GET` | `/api/v1/admin/platform-receiving-warehouses` | `warehouse:list` | 分页查询全部平台收货仓 | | `POST` | `/api/v1/admin/platform-receiving-warehouses` | `warehouse:write` | 新增平台收货仓 | | `PUT` | `/api/v1/admin/platform-receiving-warehouses/{id}` | `warehouse:write` | 编辑平台收货仓 | @@ -285,7 +285,7 @@ | `POST` | `/api/v1/admin/counterparties/import` | `counterparty:import` | 在授权数据范围内使用标准模板批量导入往来单位 | | `PUT` | `/api/v1/admin/first-leg-orders/{id}/delivery-info` | `first-leg:update` | 后台维护快递公司和快递单号 | -一期不使用通用的“传任意目标状态”接口替代状态动作。服务端根据当前状态、动作、操作者和权限决定目标状态。 +订单与客户不使用通用的“传任意目标状态”接口替代状态动作。服务端根据当前状态、动作、操作者和权限决定目标状态。 ### 请求一致性 @@ -321,7 +321,7 @@ ### 管理后台 -新增企业资料审核、平台收货仓、快递公司和往来单位管理。企业资料审核只有“审核通过”，资料不正确时由平台联系客户修改；基础资料页面支持列表筛选、新增、编辑和启停，并由 RBAC 与数据范围控制。快递公司、往来单位页面沿用 `docs/悦` 原型的信息层级和主要字段，但使用当前后台视觉体系和交互组件重新实现；一期实现标准模板下载、文件上传、校验结果和错误报告，不提供导出入口。保留当前订单列表和详情方向，将自由状态下拉改为服务端返回的可用动作；补充待审核订单人工修改、受理、分配、订舱、发运、完成、取消和履约快递信息维护动作，不提供驳回入口。 +新增企业资料审核、平台收货仓、快递公司和往来单位管理。企业资料审核只有“审核通过”，资料不正确时由平台联系客户修改；基础资料页面支持列表筛选、新增、编辑和启停，并由 RBAC 与数据范围控制。快递公司、往来单位页面沿用 `docs/悦` 原型的信息层级和主要字段，但使用当前后台视觉体系和交互组件重新实现；订单与客户实现标准模板下载、文件上传、校验结果和错误报告，不提供导出入口。保留当前订单列表和详情方向，将自由状态下拉改为服务端返回的可用动作；补充待审核订单人工修改、受理、分配、订舱、发运、完成、取消和履约快递信息维护动作，不提供驳回入口。 ## 八、测试与验收 @@ -359,20 +359,20 @@ 以下决策于 2026-07-28 至 2026-07-29 确认： -1. 采用“草稿、待审核、已受理、已订舱、运输中、已完成、已取消”七个一期状态，不设置“已驳回”。 +1. 采用“草稿、待审核、已受理、已订舱、运输中、已完成、已取消”七个订单与客户状态，不设置“已驳回”。 2. 待审核订单无驳回操作；信息有误时由后台人工修改，或由平台联系客户修改，订单保持待审核并完整记录修改审计。 -3. 已受理后客户不能直接取消，一期由客户联系平台并由平台执行取消。 +3. 已受理后客户不能直接取消，订单与客户由客户联系平台并由平台执行取消。 4. 保留平台代客户创建订单的能力。 -5. 一期使用本设计的精简必填字段；FBA 批量下单、渠道、商检和退税后续扩展。 +5. 订单与客户使用本设计的精简必填字段；FBA 批量下单、渠道、商检和退税后续扩展。 6. 快递公司和往来单位均由当前平台后台人员维护；企业客户端不提供维护入口和写接口，仅按权限只读使用。 -7. 一期包含快递公司、往来单位标准模板批量导入，不包含对应导出功能。 -8. 一期客户端包含我的信息和公司信息，范围以 `docs/悦/头程下单/柏悦客户端.html` 原型为基准并接入真实权限与接口。 +7. 订单与客户包含快递公司、往来单位标准模板批量导入，不包含对应导出功能。 +8. 订单与客户客户端包含我的信息和公司信息，范围以 `docs/悦/头程下单/柏悦客户端.html` 原型为基准并接入真实权限与接口。 9. 企业注册不需要审核，注册成功即可登录；提交订单前必须提交企业资料并由平台人工点击审核通过。 -10. 一期支持一个用户拥有多个角色，权限取角色权限并集。 -11. 往来单位按所属业务主体隔离并支持一个单位拥有多个稳定编码类型；一期类型覆盖供应商、客户、承运商、报关行、发货单位和收货单位。 -12. 一个订单一期只支持一组快递公司和快递单号。 -13. 快递公司、往来单位批量导入一期只新增，不更新或覆盖已有档案；重复或任一行错误时整批失败。 +10. 订单与客户支持一个用户拥有多个角色，权限取角色权限并集。 +11. 往来单位按所属业务主体隔离并支持一个单位拥有多个稳定编码类型；订单与客户类型覆盖供应商、客户、承运商、报关行、发货单位和收货单位。 +12. 一个订单订单与客户只支持一组快递公司和快递单号。 +13. 快递公司、往来单位批量导入订单与客户只新增，不更新或覆盖已有档案；重复或任一行错误时整批失败。 14. “我的信息”中的用户名只读，不允许修改。 -15. 企业客户端菜单和操作权限由企业管理员为本企业角色分配，一期不做部门/组织架构。 -16. 企业注册一期不接短信或邮箱验证码，只做基础字段、密码和账号重复校验。 -17. 一期仅支持中文账号密码登录，不做多语言、微信和企业微信登录。 +15. 企业客户端菜单和操作权限由企业管理员为本企业角色分配，订单与客户不做部门/组织架构。 +16. 企业注册订单与客户不接短信或邮箱验证码，只做基础字段、密码和账号重复校验。 +17. 订单与客户仅支持中文账号密码登录，不做多语言、微信和企业微信登录。 diff --git a/一期/一期开发进度表.md b/订单与客户/订单与客户开发进度表.md similarity index 87% rename from 一期/一期开发进度表.md rename to 订单与客户/订单与客户开发进度表.md index 54454e0..e594838 100644 --- a/一期/一期开发进度表.md +++ b/订单与客户/订单与客户开发进度表.md @@ -1,37 +1,37 @@ -# 虫虫出海一期开发进度表 +# 虫虫出海订单与客户开发进度表 > 创建日期：2026-07-27 > 更新日期：2026-08-03 -> 当前阶段：一期功能基本完成，进入测试环境部署、业务样本补齐和验收收口。双端核心页面已接真实 API；后端 19 个 Reactor 模块、169 项测试及本地真实接口回归已通过。2026-08-03 最新门禁中，Client 99 项测试和双端生产构建通过，Admin 129 项测试中 122 项通过、7 项失败，需先修正企业审核标识映射及其余页面断言后再做最终验收 -> 总体状态：收口中（暂不标记一期完成） +> 当前阶段：订单与客户功能基本完成，进入测试环境部署、业务样本补齐和验收收口。双端核心页面已接真实 API；后端 19 个 Reactor 模块、169 项测试及本地真实接口回归已通过。2026-08-03 最新门禁中，Client 99 项测试和双端生产构建通过，Admin 129 项测试中 122 项通过、7 项失败，需先修正企业审核标识映射及其余页面断言后再做最终验收 +> 总体状态：收口中（暂不标记订单与客户完成） > 主体模型：当前只实现“平台—客户”两级；`tenant_id > 0` 是客户 ID 兼容字段，`tenant_id=0` 是平台技术作用域。进度项中的历史 `tenant` 命名不得解释为真实租户层。 -头程订单一期闭环范围与接口草案见 `一期头程订单闭环设计.md`。 +头程订单订单与客户闭环范围与接口草案见 `订单与客户头程订单闭环设计.md`。 ## 原型依据与进度口径 -- 一期产品原型统一以 `docs/悦/` 为依据；企业登录、注册页面分别来源于 `docs/悦/合并/login.html`、`docs/悦/合并/register.html`，快递公司、往来单位页面来源为 `docs/悦/货代SAAS平台后台/货代SaaS平台原型.html`。 +- 订单与客户产品原型统一以 `docs/悦/` 为依据；企业登录、注册页面分别来源于 `docs/悦/合并/login.html`、`docs/悦/合并/register.html`，快递公司、往来单位页面来源为 `docs/悦/货代SAAS平台后台/货代SaaS平台原型.html`。 - 登录原型包含邮箱/手机号、密码、记住我、忘记密码提示和其他登录方式占位；注册原型包含企业名称、联系人、邮箱、手机号、8–20 位密码及服务协议/隐私政策确认。 -- 一期只做中文账号密码登录和基础企业注册闭环，不接短信/邮箱验证码、微信/企业微信登录及多语言；独立找回密码和工作台也不纳入一期。 +- 订单与客户只做中文账号密码登录和基础企业注册闭环，不接短信/邮箱验证码、微信/企业微信登录及多语言；独立找回密码和工作台也不纳入订单与客户。 - 原型已经包含“通用 → 快递公司 / 往来单位”菜单、列表、筛选、状态、操作按钮和演示数据，可作为字段、布局和交互方向参考。 - 原型中的新增、编辑、详情、查询、导入和导出多数仅有静态入口或表格渲染，不等同于 `apps/admin-web`、`apps/client-web` 已完成开发。 - 进度表将“原型核对”和“Vue 工程实现”分开统计：原型核对可标记完成，未进入当前 Vue 应用的页面、状态管理、权限和测试仍按待开始或 0% 记录。 -- Client 静态页面完成度与接口联调完成度分开统计：当前一期客户端路由均已落到正式页面，无在用占位页，静态页面完成度为 100%；各任务百分比继续反映真实接口、数据和验收进度。 -- 一期权限与业务边界以本目录文档为准；旧原型中的租户角色、FBA、海外仓和 WMS 菜单不自动纳入一期。 +- Client 静态页面完成度与接口联调完成度分开统计：当前订单与客户客户端路由均已落到正式页面，无在用占位页，静态页面完成度为 100%；各任务百分比继续反映真实接口、数据和验收进度。 +- 订单与客户权限与业务边界以本目录文档为准；旧原型中的租户角色、FBA、海外仓和 WMS 菜单不自动纳入订单与客户。 -## 一、一期目标 +## 一、订单与客户目标 -一期完成两个端的基础业务闭环： +订单与客户完成两个端的基础业务闭环： -- 平台后台：内部账号登录、客户与企业资料审核、内部用户、角色、权限和头程订单管理；工作台不作为一期交付项。 +- 平台后台：内部账号登录、客户与企业资料审核、内部用户、角色、权限和头程订单管理；工作台不作为订单与客户交付项。 - 企业客户端：用户名加密码登录、免审核企业注册、企业资料、企业成员、角色、菜单及权限管理；企业资料审核通过后才可提交订单。 - 头程订单：提供客户端下单和订单查询能力，形成前后台业务闭环。 - 平台收货仓：平台统一维护国内收货仓，客户端下单时选择已启用仓库并保存仓库 ID、编码、名称和地址快照。 - 快递公司：当前平台后台人员统一维护快递公司档案，企业客户端不维护；订单履约时记录快递公司与快递单号。 - 往来单位：当前平台后台人员维护发货单位、收货单位、供应商和服务商，企业客户端只读选择并在头程订单中保存快照。 -一期基础资料范围包括平台收货仓、快递公司和往来单位。仓库能力限定为义乌、深圳、青岛、上海、宁波、厦门等国内收货仓的档案、启停、查询和订单关联，不包含 FBA/海外目的仓、库存、库位、货架、入库、出库、盘点等 WMS 作业；快递能力不包含轨迹订阅和自动回传。 +订单与客户基础资料范围包括平台收货仓、快递公司和往来单位。仓库能力限定为义乌、深圳、青岛、上海、宁波、厦门等国内收货仓的档案、启停、查询和订单关联，不包含 FBA/海外目的仓、库存、库位、货架、入库、出库、盘点等 WMS 作业；快递能力不包含轨迹订阅和自动回传。 权限边界暂按以下模型设计： @@ -64,7 +64,7 @@ | BASE-02 | 公共 | 数据库 | 用户、企业、企业资料审核、成员、角色、菜单、权限、订单、仓库等核心表设计 | P0 | 待开始 | 0% | BASE-01 | 待分配 | 企业资料审核状态与注册账号状态分离；仓库主数据与订单仓库快照分离 | | BASE-03 | 公共 | 认证 | Admin 与企业端登录、退出、Token、密码加密、登录状态和接口鉴权 | P0 | 联调中 | 55% | BASE-02 | 待分配 | Client 已接真实登录/退出、Access/Refresh Token、MERCHANT 身份校验、并发 401 单次刷新；2026-07-30 Gateway/Auth 登录均出现 503，待后端恢复服务发现后验收 | | BASE-04 | 公共 | 通用能力 | 统一响应、错误码、分页、操作日志、文件上传 | P0 | 进行中 | 25% | BASE-01 | 待分配 | Client 已实现 code 字符串响应解包、字段错误模型、常见网络错误和 multipart 营业执照上传；分页与日志待接入 | -| BASE-05 | 公共 | 接口文档 | 输出并维护一期 API 文档 | P0 | 待开始 | 0% | BASE-01 | 待分配 | 建议使用 OpenAPI；同步企业资料审核、下单资格、仓库、快递公司、往来单位与订单快照契约 | +| BASE-05 | 公共 | 接口文档 | 输出并维护订单与客户 API 文档 | P0 | 待开始 | 0% | BASE-01 | 待分配 | 建议使用 OpenAPI；同步企业资料审核、下单资格、仓库、快递公司、往来单位与订单快照契约 | | ADM-AUTH-01 | 后台 | 登录认证 | 平台内部员工账号密码登录、退出、登录回跳、路由守卫和无权限跳转 | P0 | 进行中 | 70% | BASE-03 | 待分配 | 已接 `/api/auth/**` 与 `/api/platform/v1/iam/permissions`，校验 PLATFORM 身份并按 JWT 与启用权限资源交集授权；等待 Gateway/Nacos 路由恢复后完成真实环境验收 | | ADM-CUSTOMER-01 | 后台 | 客户管理 | 客户列表、搜索、分页、详情、新增、编辑和启停 | P0 | 进行中 | 70% | BASE-03 | 待分配 | 前端已完成并通过浏览器验收，等待接口联调 | | ADM-CUSTOMER-02 | 后台 | 客户管理 | 查看企业资料和资质，人工点击审核通过并维护下单资格 | P0 | 联调中 | 82% | ADM-CUSTOMER-01、CLI-PROFILE-02 | 待分配 | 独立审核页已接 IAM 待审列表、按租户资质查询、平台 Token 文件预览、通过与驳回接口；待使用真实待审记录验证完整写操作 | @@ -83,7 +83,7 @@ | ADM-WH-01 | 后台 | 平台收货仓 | 仓库列表、关键词和状态筛选、分页及空态 | P0 | 进行中 | 75% | BASE-03、WH-BASE-01 | 待分配 | 静态页面和权限已完成，等待接口联调 | | ADM-WH-02 | 后台 | 平台收货仓 | 新增、编辑、启用和停用仓库；校验编码唯一性 | P0 | 进行中 | 75% | ADM-WH-01 | 待分配 | 停用仓库不允许新订单选择，不物理删除历史引用 | | WH-BASE-01 | 公共 | 仓库模型 | 定义国内平台收货仓、启停状态及订单仓库关联 | P0 | 进行中 | 65% | BASE-02 | 待分配 | 共享仓库及快照模型已完成，数据库与 API 契约待实现 | -| MD-PROTO-01 | 公共 | 基础资料原型 | 核对 `docs/悦` 中快递公司、往来单位菜单、列表、字段、状态和现有交互，形成一期迁移口径 | P0 | 已完成 | 100% | - | 待分配 | 已确认原型存在；原型资产与当前 Vue 工程实现分开统计 | +| MD-PROTO-01 | 公共 | 基础资料原型 | 核对 `docs/悦` 中快递公司、往来单位菜单、列表、字段、状态和现有交互，形成订单与客户迁移口径 | P0 | 已完成 | 100% | - | 待分配 | 已确认原型存在；原型资产与当前 Vue 工程实现分开统计 | | MD-BASE-01 | 公共 | 基础资料模型 | 统一快递公司、往来单位的稳定编码、启停、审计、数据范围和订单快照规则 | P0 | 进行中 | 10% | BASE-02、BASE-04、MD-PROTO-01 | 待分配 | 设计文档已有字段草案；共享类型、数据库与 API 契约尚未实现 | | ADM-EXP-01 | 后台 | 快递公司 | 快递公司列表、关键词搜索、按状态筛选及详情 | P0 | 进行中 | 80% | BASE-03、MD-BASE-01 | 待分配 | Vue 列表、组合筛选、详情和响应式展示完成；Pinia 静态数据等待新架构业务 API | | ADM-EXP-02 | 后台 | 快递公司 | 后台人员新增、编辑、启用和停用；校验稳定编码与名称唯一性 | P0 | 进行中 | 80% | ADM-EXP-01 | 待分配 | Vue 维护、权限控制、编码/名称不区分大小写唯一校验和历史引用提示完成；服务端校验待接入 | @@ -99,7 +99,7 @@ | CLI-MY-01 | 客户端 | 我的信息 | 查看用户名、姓名、联系电话、邮箱和所属公司，支持进入编辑、保存和取消 | P0 | 联调中 | 90% | CLI-AUTH-01 | 待分配 | 已接个人资料查询/编辑接口；用户名和所属公司只读，电话与邮箱按 OpenAPI 可选约束处理，保存失败保留输入 | | CLI-MY-02 | 客户端 | 我的信息 | 使用当前密码、新密码和确认密码修改登录密码 | P0 | 联调中 | 90% | CLI-MY-01、BASE-03 | 待分配 | 已接 `PUT /api/auth/password`，按 8–64 位且同时包含字母数字校验；成功后清理旧会话并返回登录页 | | CLI-PROFILE-01 | 客户端 | 公司信息 | 企业基本信息、法人信息、联系人、手机、邮箱、微信和地址查看与维护 | P0 | 进行中 | 65% | CLI-REG-01 | 待分配 | 原型按“企业基本信息/联系信息”分页签展示；当前静态编辑交互已完成，等待接口和真实权限控制 | -| CLI-PROFILE-02 | 客户端 | 公司信息 | 一期营业执照状态、查看和上传 | P1 | 联调中 | 90% | BASE-04 | 待分配 | 已接资料编辑、资质查询、营业执照上传及携带 Token 的图片预览；按后端限制为单张 JPG/PNG、最大 5MB，待稳定环境完成浏览器验收 | +| CLI-PROFILE-02 | 客户端 | 公司信息 | 订单与客户营业执照状态、查看和上传 | P1 | 联调中 | 90% | BASE-04 | 待分配 | 已接资料编辑、资质查询、营业执照上传及携带 Token 的图片预览；按后端限制为单张 JPG/PNG、最大 5MB，待稳定环境完成浏览器验收 | | CLI-MEMBER-01 | 客户端 | 企业成员 | 成员列表、新增、编辑、启停和重置密码 | P0 | 联调中 | 92% | CLI-REG-01 | 待分配 | 姓名、联系方式、memberNo 和 roleIds 已真实回显；新增、编辑、启停、重置密码均接精确 membershipId 路径，所有者保护由服务端最终校验 | | CLI-ROLE-01 | 客户端 | 角色 | 企业角色新增、编辑、删除、启停 | P0 | 测试中 | 90% | CLI-MEMBER-01 | 待分配 | 已从后端只读源码确认并接入编辑、状态和删除真实接口；浏览器真实读取正常，当前只有内置角色，需自定义角色样本复测操作入口且暂不执行写入 | | CLI-ROLE-02 | 客户端 | 角色 | 为成员分配一个或多个角色 | P0 | 联调中 | 92% | CLI-ROLE-01 | 待分配 | 成员 roleIds 已回显，新增/编辑成员通过精确 membershipId 全量保存角色；待浏览器执行一次真实写入验收 | @@ -112,14 +112,14 @@ | CLI-ORDER-02 | 客户端 | 头程订单 | 我的订单列表和详情 | P0 | 测试中 | 95% | CLI-ORDER-01 | 待分配 | 浏览器真实读取 1 条草稿及详情，货物、双方快照和状态历史正常回显；编辑前强制加载完整详情，修复列表简要数据导致空货物和响应式复制异常 | | CLI-ORDER-03 | 客户端 | 头程订单 | 下单选择平台收货仓；提交时保存仓库 ID 和展示快照 | P0 | 测试中 | 90% | CLI-WH-01、CLI-ORDER-01 | 待分配 | 新订单真实仓库选择和详情回显已验证；当前旧草稿引用已不存在的仓库 `2001`，客户端清空失效选择并提示重新选择，服务端样本关联待修复 | | CLI-ORDER-04 | 客户端 | 头程订单 | 从已启用往来单位选择发货方/收货方并带入联系人和地址，提交时保存快照 | P0 | 测试中 | 94% | CLI-CP-01、CLI-ORDER-01 | 待分配 | 真实候选接口和订单双方快照已接；创建/编辑请求已用发货方 ID 填充后端必填 `customerId`。当前无启用收货仓，创建入口被禁用，候选下拉待准备仓库样本后复测 | -| ADM-ORDER-05 | 后台 | 头程订单 | 维护履约快递公司、快递单号并在订单详情展示 | P1 | 进行中 | 80% | ADM-EXP-02、ADM-ORDER-02 | 待分配 | Vue 列表/详情/维护弹窗、单组限制、停用历史回显和审计记录完成；一期不接轨迹订阅，业务 API 待新架构确认 | +| ADM-ORDER-05 | 后台 | 头程订单 | 维护履约快递公司、快递单号并在订单详情展示 | P1 | 进行中 | 80% | ADM-EXP-02、ADM-ORDER-02 | 待分配 | Vue 列表/详情/维护弹窗、单组限制、停用历史回显和审计记录完成；订单与客户不接轨迹订阅，业务 API 待新架构确认 | | CLI-ORDER-05 | 客户端 | 头程订单 | 订单详情只读展示后台维护的快递公司和快递单号 | P1 | 测试中 | 75% | ADM-ORDER-05、CLI-ORDER-02 | 待分配 | 真实订单详情已验证“平台尚未维护快递信息”空态，客户侧无编辑入口；仍需后台准备含快递公司和单号的样本复测有值回显 | | TEST-01 | 公共 | 测试 | 用户、角色、权限和越权访问测试 | P0 | 进行中 | 40% | 权限模块完成 | 待分配 | 客户端已覆盖权限过滤、403、首个可访问页面、按钮权限和会话恢复；跨企业越权及接口拒绝必须待服务端测试 | | TEST-02 | 公共 | 测试 | Admin 登录、企业端免审核注册、企业资料审核、下单资格和头程订单业务流程测试 | P0 | 进行中 | 45% | 业务模块完成 | 待分配 | 客户端已覆盖免审核注册、资料待审核可存草稿、提交阻断和资料引导；仍需接口失败、审核通过提交及服务端越权测试 | | TEST-03 | 公共 | 测试 | 编码唯一、启停控制、客户端只读选择及订单仓库关联测试 | P0 | 进行中 | 65% | ADM-WH-02、CLI-ORDER-03 | 待分配 | 前端自动化已覆盖停用限制和主数据变更后的历史快照；服务端测试待补 | | TEST-04 | 公共 | 测试 | 快递公司和往来单位编码唯一、数据范围、启停控制、批量导入、只读查询、订单带入及快照测试 | P0 | 进行中 | 25% | ADM-EXP-03、ADM-CP-04、CLI-ORDER-05 | 待分配 | 补充模板版本、必填/格式/重复校验、整批失败、错误报告、导入权限和审计测试 | | REL-01 | 公共 | 发布 | 测试环境部署、初始化账号、基础菜单权限和首批基础资料 | P0 | 待开始 | 0% | BASE-01、ADM-WH-02、ADM-EXP-02、ADM-CP-03 | 待分配 | 首批收货仓、快递公司、往来单位数据需业务验收；禁止使用通用弱密码 | -| REL-02 | 公共 | 验收 | 一期验收、问题修复和生产发布 | P0 | 待开始 | 0% | TEST-01、TEST-02、TEST-03、TEST-04 | 待分配 | 形成验收清单 | +| REL-02 | 公共 | 验收 | 订单与客户验收、问题修复和生产发布 | P0 | 待开始 | 0% | TEST-01、TEST-02、TEST-03、TEST-04 | 待分配 | 形成验收清单 | ## 四、建议里程碑 @@ -131,7 +131,7 @@ | M4 企业权限 | 客户端角色、菜单和权限完整可用 | 进行中 | 待排期 | | M5 基础资料主数据 | 后台可维护平台收货仓、快递公司、往来单位；客户端只读查询并受数据范围控制 | 进行中 | 待排期 | | M6 订单闭环 | 客户选择收货仓和往来单位提交订单，后台维护履约信息，历史展示稳定 | 进行中 | 待排期 | -| M7 一期上线 | 联调、测试、验收和生产发布完成 | 待排期 | 待排期 | +| M7 订单与客户上线 | 联调、测试、验收和生产发布完成 | 待排期 | 待排期 | ## 五、产品决策与待确认事项 @@ -139,26 +139,26 @@ | 编号 | 决策 | 结论 | |---|---|---| -| Q1 | 客户端一期是否包含头程下单、订单列表和详情？ | 包含，作为一期前后台订单闭环的必要范围 | +| Q1 | 客户端订单与客户是否包含头程下单、订单列表和详情？ | 包含，作为订单与客户前后台订单闭环的必要范围 | | Q2 | 企业注册与企业资料审核关系 | 注册无需审核，成功后即可登录；提交订单前必须提交企业资料并由平台人工点击审核通过 | | Q3 | 客户端“菜单分配”的操作人 | 企业管理员为本企业角色分配菜单和操作权限，不能管理其他企业或平台后台菜单 | -| Q4 | 一个用户能否拥有多个角色？ | 一期支持多角色，服务端按角色权限并集授权 | -| Q5 | 企业注册是否使用短信或邮箱验证码？ | 一期不接验证码，仅做必填、格式、密码强度和账号重复校验 | -| Q6 | 头程订单一期状态 | 草稿、待审核、已受理、已订舱、运输中、已完成、已取消；不设置已驳回状态 | -| Q7 | 是否需要部门/组织架构？ | 一期不纳入，成员直接关联企业并通过角色授权 | -| Q8 | 一期仓库范围与维护方 | 平台后台统一维护国内收货仓，客户端只读选择启用仓库；FBA/海外目的仓不纳入本次 | +| Q4 | 一个用户能否拥有多个角色？ | 订单与客户支持多角色，服务端按角色权限并集授权 | +| Q5 | 企业注册是否使用短信或邮箱验证码？ | 订单与客户不接验证码，仅做必填、格式、密码强度和账号重复校验 | +| Q6 | 头程订单订单与客户状态 | 草稿、待审核、已受理、已订舱、运输中、已完成、已取消；不设置已驳回状态 | +| Q7 | 是否需要部门/组织架构？ | 订单与客户不纳入，成员直接关联企业并通过角色授权 | +| Q8 | 订单与客户仓库范围与维护方 | 平台后台统一维护国内收货仓，客户端只读选择启用仓库；FBA/海外目的仓不纳入本次 | | Q9 | 仓库停用后的订单处理 | 禁止新单选择；历史订单继续展示下单时仓库编码、名称和地址快照 | | Q10 | 快递公司和往来单位维护方 | 均由当前平台后台人员维护；企业客户端无维护入口和写接口，仅可按权限查询、选择和查看 | | Q11 | 往来单位的数据范围 | 按所属业务主体隔离，平台人员仅在授权数据范围内维护和查看 | -| Q12 | 往来单位一期类型 | 使用稳定编码并支持一个单位多选类型；一期覆盖供应商、客户、承运商、报关行、发货单位和收货单位 | -| Q13 | 一个订单支持几组快递公司和快递单号？ | 一期只支持一组履约快递信息；多包裹、多段运输后续扩展 | -| Q15 | Admin 工作台是否纳入一期？ | 不纳入一期交付与验收；一期先完成简单登录、企业资料审核、权限、基础资料和订单闭环 | -| Q14 | 快递公司、往来单位批量导入是否纳入一期？ | 已确认纳入一期，均由获授权的后台人员使用标准模板导入 | -| Q16 | 多语言、微信和企业微信登录是否纳入一期？ | 不纳入；一期仅交付中文账号密码登录，第三方登录后续单独排期 | -| Q17 | 快递公司、往来单位导出是否纳入一期？ | 不纳入；一期仅实现标准模板批量导入 | -| Q18 | 一期客户端是否包含我的信息和公司信息？ | 已确认包含；按现有客户端原型覆盖个人资料编辑、修改密码、企业基本/联系信息和资质文件查看维护 | -| Q19 | 待审核订单信息不正确时如何处理？ | 一期无驳回操作；后台可人工修改，不能直接确认时联系客户修改，订单保持待审核并记录修改审计 | -| Q20 | 批量导入是否更新已有档案？ | 一期仅新增；重复编码或唯一键冲突时整批失败，不覆盖已有档案 | +| Q12 | 往来单位订单与客户类型 | 使用稳定编码并支持一个单位多选类型；订单与客户覆盖供应商、客户、承运商、报关行、发货单位和收货单位 | +| Q13 | 一个订单支持几组快递公司和快递单号？ | 订单与客户只支持一组履约快递信息；多包裹、多段运输后续扩展 | +| Q15 | Admin 工作台是否纳入订单与客户？ | 不纳入订单与客户交付与验收；订单与客户先完成简单登录、企业资料审核、权限、基础资料和订单闭环 | +| Q14 | 快递公司、往来单位批量导入是否纳入订单与客户？ | 已确认纳入订单与客户，均由获授权的后台人员使用标准模板导入 | +| Q16 | 多语言、微信和企业微信登录是否纳入订单与客户？ | 不纳入；订单与客户仅交付中文账号密码登录，第三方登录后续单独排期 | +| Q17 | 快递公司、往来单位导出是否纳入订单与客户？ | 不纳入；订单与客户仅实现标准模板批量导入 | +| Q18 | 订单与客户客户端是否包含我的信息和公司信息？ | 已确认包含；按现有客户端原型覆盖个人资料编辑、修改密码、企业基本/联系信息和资质文件查看维护 | +| Q19 | 待审核订单信息不正确时如何处理？ | 订单与客户无驳回操作；后台可人工修改，不能直接确认时联系客户修改，订单保持待审核并记录修改审计 | +| Q20 | 批量导入是否更新已有档案？ | 订单与客户仅新增；重复编码或唯一键冲突时整批失败，不覆盖已有档案 | | Q21 | “我的信息”中的用户名能否修改？ | 用户名只读，不允许修改 | ### 待确认事项 @@ -181,7 +181,7 @@ | 验收项 | 结果 | 证据/说明 | |---|---|---| | 客户管理 | 通过（静态，待调整） | 列表、筛选、分页、新增/编辑、详情和启停已完成；原注册审核交互需改为企业资料审核通过 | -| Admin 登录 | 通过（静态） | 登录必填/失败反馈、退出确认、安全回跳、403 路由及按角色首个业务页落地已完成；一期工作台入口已移除，真实 Token 与会话失效处理待接入 | +| Admin 登录 | 通过（静态） | 登录必填/失败反馈、退出确认、安全回跳、403 路由及按角色首个业务页落地已完成；订单与客户工作台入口已移除，真实 Token 与会话失效处理待接入 | | 内部用户 | 通过 | 列表、筛选、新增/编辑、多角色、重置密码、启停及管理员保护 | | 角色管理 | 通过 | 新增/编辑/删除/启停、权限树、数据范围及内置角色保护 | | 权限管理 | 通过 | 目录/菜单/按钮/接口资源树、上下级维护、状态与唯一编码校验 | @@ -192,7 +192,7 @@ | 生产构建 | 通过 | `pnpm build`，输出至 `apps/admin-web/dist`；产物扫描确认不包含平台联调账号、密码和开发提示 | | impeccable 样式检测 | 通过（已修复告警） | 修复字体栈以及 width/margin 布局动画；保留既有后台视觉体系 | -> 客户档案、内部用户和基础资料仍使用 Pinia 模拟数据；企业审核、平台角色、菜单及按钮权限资源已切换到真实 IAM 接口。后台前端阶段完成不等于一期业务完成，仍需后端数据、真实 RBAC 鉴权、联调和测试后才能标记“已完成”。 +> 客户档案、内部用户和基础资料仍使用 Pinia 模拟数据；企业审核、平台角色、菜单及按钮权限资源已切换到真实 IAM 接口。后台前端阶段完成不等于订单与客户业务完成，仍需后端数据、真实 RBAC 鉴权、联调和测试后才能标记“已完成”。 ### Admin 认证联调记录（2026-07-29） @@ -220,8 +220,8 @@ | 企业角色 | 通过（静态） | 新增/编辑/删除/启停、成员和权限数量、内置角色保护及权限入口已完成 | | 菜单权限 | 通过（静态） | 角色选择、分组菜单与操作权限、全选/半选、保存/重置和只读保护已完成 | | 我的信息与修改密码 | 通过（静态） | 原型字段、查看/编辑/保存/取消、只读账号与企业、当前密码错误、密码强度和静态会话/审计结果已完成 | -| 头程订单与仓库 | 通过（静态） | 下单、草稿、提交、列表、详情、启用仓库选择、历史仓库快照及后端必填字段已完成；取消不纳入本轮一期客户端验收 | -| 静态页面完整性与响应式 | 通过（100%） | 一期客户端导航和路由均落到正式页面，无在用占位页；桌面、720px 和 390px 布局、移动导航、44px 主要操作及无横向溢出已验证 | +| 头程订单与仓库 | 通过（静态） | 下单、草稿、提交、列表、详情、启用仓库选择、历史仓库快照及后端必填字段已完成；取消不纳入本轮订单与客户客户端验收 | +| 静态页面完整性与响应式 | 通过（100%） | 订单与客户客户端导航和路由均落到正式页面，无在用占位页；桌面、720px 和 390px 布局、移动导航、44px 主要操作及无横向溢出已验证 | | 自动化测试 | 通过 | `apps/client-web` 执行 `pnpm test`，94 项通过，覆盖认证、个人资料、成员、角色权限、超大整数响应、业务总览真实加载、往来单位历史快照、仓库详情、头程订单完整详情编辑、幂等、快递字段、失败恢复、未保存保护、响应式和关键源码契约 | | TypeScript 类型检查 | 通过 | `apps/client-web` 执行 `pnpm typecheck` | | 生产构建 | 通过 | `apps/client-web` 执行 `pnpm build`；产物扫描确认不包含商户联调账号和开发提示 | @@ -232,7 +232,7 @@ | 快递信息 | 通过（静态） | 订单详情只读展示平台维护的快递公司和单号，并提供未维护空态；客户侧无写入口 | | 服务端与数据安全 | 联调中 | 认证、权限资源、企业资料、营业执照、个人资料、成员完整维护、角色完整维护、仓库详情、往来单位、头程订单及快递只读字段已接真实 API；订单 `customerId` 与 `CUSTOMER / SUPPLIER / BOTH` 契约已按后端源码和回归脚本复核 | -> 客户端静态页面阶段通过不等于一期业务完成。菜单隐藏和页面只读只用于前端体验，服务端仍必须按当前用户、`tenant_id` 和权限编码执行授权校验。 +> 客户端静态页面阶段通过不等于订单与客户业务完成。菜单隐藏和页面只读只用于前端体验，服务端仍必须按当前用户、`tenant_id` 和权限编码执行授权校验。 ### Client 认证与企业资料联调记录（2026-07-29） @@ -263,7 +263,7 @@ - 新版联调文档和 Gateway Swagger 已确认可用；实测商户登录、企业资料、资质、权限、角色、成员、仓库分页、订单分页与订单详情均返回 `code=0`，订单详情不返回平台内部备注。 - 已接企业资料 `PUT`、资质图片鉴权下载、仓库分页、订单分页/详情、创建/编辑草稿和提交；`SUBMITTED/PROCESSING`、`transportMode/containerMode` 均通过适配层映射，未把 FCL/LCL 错当运输方式。 - 页面新增渠道、提货方式、报关模式、目的仓类型、包装类型等后端必填字段；订单和仓库请求失败不回退模拟数据，仓库为空时禁用创建。 -- Swagger 虽存在订单取消接口，但新版任务文档明确取消不纳入本轮本地一期验收，因此客户端不暴露取消写操作。 +- Swagger 虽存在订单取消接口，但新版任务文档明确取消不纳入本轮本地订单与客户验收，因此客户端不暴露取消写操作。 - 远端环境在浏览器验收阶段再次无响应；`http://127.0.0.1:5190` 登录页正常加载并发起真实登录，但 Gateway 健康检查与登录请求均超时，未进入工作台。 - 代码已再次通过 81 项自动化测试和 TypeScript 检查；本轮生产构建与浏览器验收结果见交付记录，真实草稿写入、资质预览与空仓禁建仍需在稳定 Gateway 和有效仓库数据下继续验收。 @@ -271,7 +271,7 @@ - 最新文档再次确认浏览器只通过 Gateway `9000` 和同源 `/api` 访问，禁止直连 `9100/9201/9204/9205/9206` 等服务端口；后端文档记录 8 个应用健康检查均为 `UP`，平台账号也已由人工登录进入 Admin。 - 本轮真实接入范围为商户企业资料/资质、商户仓库和头程订单 CRUD/提交，以及平台待审列表、指定租户资质、鉴权文件查看和审核动作。平台订单审核、受理、履约、完成、取消及 Admin 快递公司/往来单位业务接口未纳入最新本地联调契约，前端继续保留静态实现，不猜测接口。 -- 后端任务文档写有“`DRAFT`、`REJECTED` 可编辑”，与已确认的一期订单七状态规则冲突。产品确认优先：订单不恢复“已驳回”状态；兼容旧接口返回的订单 `REJECTED` 时映射为待审核且不开放客户编辑。企业资料和资质审核的 `REJECTED` 仍正常保留，这是独立业务状态。 +- 后端任务文档写有“`DRAFT`、`REJECTED` 可编辑”，与已确认的客户订单七状态规则冲突。产品确认优先：订单不恢复“已驳回”状态；兼容旧接口返回的订单 `REJECTED` 时映射为待审核且不开放客户编辑。企业资料和资质审核的 `REJECTED` 仍正常保留，这是独立业务状态。 - 平台企业审核详情改为按租户查询资质，文件通过平台 Token 请求二进制后临时预览，不再直接打开商户文件 URL；覆盖加载、空数据、失败重试和对象地址释放。 - 商户订单创建与提交请求增加 `Idempotency-Key`，并将 `merchant:order:create/edit/submit` 映射为三个独立前端操作权限；商户详情仍不读取或渲染 `internalNotes`。 - 交付门禁通过：Admin `21` 个测试文件、`147` 项测试，Client `81` 项测试；两端 `pnpm typecheck` 与 `pnpm build` 均通过。已使用真实平台账号进入 `http://localhost:5173/customers/reviews`，待审列表真实返回空数据且无控制台错误；桌面和 390px 窄屏无页面级横向溢出。由于当前无待审记录，资质抽屉的真实文件预览仍待准备样本后人工验收。 @@ -327,4 +327,4 @@ - 从后端 `iam/RbacController.java` 与 `RbacDtos.java` 确认平台角色已提供详情、编辑、启停、删除和权限全量替换接口，前端不再受旧联调文档缺口限制。 - Admin 角色页现同时读取角色 `permissionIds` 与权限资源，真实回显菜单和按钮授权；编辑使用 `PUT /api/platform/v1/iam/roles/{roleId}`，启停使用 `PUT /api/platform/v1/iam/roles/{roleId}/status`，删除使用 `DELETE /api/platform/v1/iam/roles/{roleId}`，授权使用 `PUT /api/platform/v1/iam/roles/permissions`。 - 19 位角色和权限 ID 延续字符串处理，避免 JavaScript 数值精度丢失；保存、启停和删除均有重复提交防护与真实失败反馈，不回退本地成功。 -- 后端订单 Controller 仍包含订单驳回接口，与当前一期“不设置已驳回状态”的确认结论冲突，本轮明确不接入该接口；企业资料审核驳回不受此订单规则影响。 +- 后端订单 Controller 仍包含订单驳回接口，与当前订单与客户“不设置已驳回状态”的确认结论冲突，本轮明确不接入该接口；企业资料审核驳回不受此订单规则影响。 diff --git a/财务管理/F1人工财务契约审查与门禁.md b/财务管理/F1人工财务契约审查与门禁.md index 2a185c1..cd4709d 100644 --- a/财务管理/F1人工财务契约审查与门禁.md +++ b/财务管理/F1人工财务契约审查与门禁.md @@ -4,7 +4,7 @@ > 审查范围：Finance Java、Finance 建库 SQL、统一增量 SQL、Admin/Client Finance API、File Java/测试、`openapi/finance-f1-manual-v1.yaml` > 结论：F0/F1 基础代码已经实现，当前处于专项修复与契约收敛阶段；不是整体未开发。修复项完成前尚未达到完整联调验收/测试放行。 -> 范围重定：领导验收改为《财务一期五页产品与接口验收契约》中的 5 页。本文 D1-D11 继续作为既有人工接口专项门禁，并新增来源链路和五页门禁。 +> 范围重定：领导验收改为《财务核心五页产品与接口验收契约》中的 5 页。本文 D1-D11 继续作为既有人工接口专项门禁，并新增来源链路和五页门禁。 ## 1. 已确认且已对齐 @@ -92,7 +92,7 @@ | D11 | 客户状态可见性 | **后端完成。** 客户账单只见 `ISSUED/PARTIALLY_PAID/PAID`；客户收款只见 `CONFIRMED`，使用 `ClientReceipt` 专用 DTO 并去除凭证、操作人和内部字段；脱敏测试通过 | 后端门禁关闭；保留跨客户与序列化回归 | | D12 | Finance 费用来源写入 | **后端完成。** 内部事件入口、令牌鉴权、Inbox 幂等、Firstleg 快照回查、来源写入/替代/作废均已实现；非作废事件必须 `PUBLISHED`，未发布返回 `FIN-EVT-015`；金额必须 `>0`，零/负返回 `FIN-EVT-010`；专项 10/10、Finance 全量 35/35 通过 | 后端门禁关闭；保留真实跨服务 HTTP 冒烟 | | D13 | 柜子费用来源 | **后端完成并验证。** Firstleg 已有柜子费用模型、审核/参与结算/作废、事件、Relay 和内部快照；Firstleg 相关 17/17、Finance 柜子来源消费测试通过 | 后端门禁关闭；测试环境补真实跨服务事件冒烟 | -| D14 | 一期 5 页 | **FAIL / 一期 P0 未关闭。** 11 个目标 operation 契约已冻结；实现状态不再写入 OpenAPI 或主契约，G1-G4 证据矩阵当前均未放行 | G1-G4 分别完成组内全部后端直接行为测试和 Admin 真实接入，证据矩阵更新为 `PASS` 后再完成五页端到端验收 | +| D14 | 订单与客户 5 页 | **FAIL / 订单与客户 P0 未关闭。** 11 个目标 operation 契约已冻结；实现状态不再写入 OpenAPI 或主契约，G1-G4 证据矩阵当前均未放行 | G1-G4 分别完成组内全部后端直接行为测试和 Admin 真实接入，证据矩阵更新为 `PASS` 后再完成五页端到端验收 | ## 4. 非阻断但需锁定的契约说明 @@ -107,7 +107,7 @@ 进入前后端联调前至少满足： -1. D1-D8、D10-D13 已具备后端直接证据；D14 当前 FAIL，G1-G4 任一组未同时通过后端行为测试与 Admin 真实接入，均不得通过一期完整联调验收。 +1. D1-D8、D10-D13 已具备后端直接证据；D14 当前 FAIL，G1-G4 任一组未同时通过后端行为测试与 Admin 真实接入，均不得通过订单与客户完整联调验收。 2. D2 已固定为首期非分页数组；后续若改服务端分页须另行升级契约。 3. 幂等门禁已关闭；后续写 operation 继续复用同参重放、异参冲突和恢复语义。 4. Finance 集成测试覆盖：默认 30 天、CNY 拒绝、出账冻结、300 分 3 单、超额/跨客户/草稿拒绝、部分收款到收清、调整修订、已收不可作废。 diff --git a/财务管理/F1人工账单收款成本接口契约.md b/财务管理/F1人工账单收款成本接口契约.md index accff49..f26b341 100644 --- a/财务管理/F1人工账单收款成本接口契约.md +++ b/财务管理/F1人工账单收款成本接口契约.md @@ -5,7 +5,7 @@ > 状态：目标契约；以《F1人工财务契约审查与门禁》为开发/联调准入依据 > OpenAPI：`openapi/finance-f1-manual-v1.yaml` -> 一期 5 页产品与新增接口以《财务一期五页产品与接口验收契约》和 `openapi/finance-phase1-five-pages-v1.yaml` 为准；本文保留现有人工账单、收款和成本能力的细化契约。 +> 订单与客户 5 页产品与新增接口以《财务核心五页产品与接口验收契约》和 `openapi/finance-core-five-pages-v1.yaml` 为准；本文保留现有人工账单、收款和成本能力的细化契约。 ## 1. 首期边界 diff --git a/财务管理/Firstleg-Finance跨服务契约.md b/财务管理/Firstleg-Finance跨服务契约.md index 8907716..9db2f23 100644 --- a/财务管理/Firstleg-Finance跨服务契约.md +++ b/财务管理/Firstleg-Finance跨服务契约.md @@ -2,9 +2,9 @@ > 版本：V0.4（费用作废命令与事件回流对齐） > 日期：2026-08-20 -> 状态：技术边界和一期产品口径已确认；Firstleg 事件/Relay/快照、Finance Inbox/来源写入及 Finance 发起的业务作废闭环均已实现。 +> 状态：技术边界和订单与客户产品口径已确认；Firstleg 事件/Relay/快照、Finance Inbox/来源写入及 Finance 发起的业务作废闭环均已实现。 -本文是 `firstleg-service` 与已落地 `finance-service` 之间的费用来源技术契约。产品范围以《财务一期五页产品与接口验收契约》为准。 +本文是 `firstleg-service` 与已落地 `finance-service` 之间的费用来源技术契约。产品范围以《财务核心五页产品与接口验收契约》为准。 ## 1. 事实依据与当前实现差异 diff --git a/财务管理/README.md b/财务管理/README.md index cf56485..8303e15 100644 --- a/财务管理/README.md +++ b/财务管理/README.md @@ -1,8 +1,8 @@ # 财务管理闭环盘点与范围建议 -> 盘点日期：2026-08-10 -> 当前状态：F0/F1 已有 Finance 服务、数据库、权限、Admin/Client 页面和基础接口；一期 11 个 P0 operation 的目标契约已冻结，本地实现验收按独立 G1-G4 证据矩阵均为 `PASS`；真实 MySQL、测试环境 HTTP 冒烟和领导页面验收仍需单独执行 -> 盘点范围：二期入库计费现状、平台后台财务原型、Admin/Client/Firstleg 当前实现 +> 盘点日期：2026-08-10 +> 当前状态：F0/F1 已有 Finance 服务、数据库、权限、Admin/Client 页面和基础接口；订单与客户 11 个 P0 operation 的目标契约已冻结，本地实现验收按独立 G1-G4 证据矩阵均为 `PASS`；真实 MySQL、测试环境 HTTP 冒烟和领导页面验收仍需单独执行 +> 盘点范围：入库计费现状、平台后台财务原型、Admin/Client/Firstleg 当前实现 > 结论口径：本文区分“代码已实现”“原型展示”和“建议范围”；原型功能不自动成为开发范围。 ## 费用来源扩展确认（2026-09-02） @@ -35,21 +35,21 @@ Finance 全链路测试环境实跑报告为 `baiyue-firstleg/reports/finance-fu 开发前总控门禁与 F0/F1 任务清单：[财务开工门禁与F0-F1任务清单](财务开工门禁与F0-F1任务清单.md)。 -一期领导验收唯一范围入口：[财务一期五页产品与接口验收契约](财务一期五页产品与接口验收契约.md)。 +订单与客户领导验收唯一范围入口：[财务核心五页产品与接口验收契约](财务核心五页产品与接口验收契约.md)。 -一期 11 个 P0 操作、状态机与验收用例：[财务一期 P0 操作契约与验收用例](财务一期P0操作契约与验收用例.md)。 +订单与客户 11 个 P0 操作、状态机与验收用例：[财务核心 P0 操作契约与验收用例](财务核心P0操作契约与验收用例.md)。 -一期实现与 Admin 接入证据（不反向修改目标契约）：[财务一期 P0 实现证据矩阵](财务一期P0实现证据矩阵.md)。 +订单与客户实现与 Admin 接入证据（不反向修改目标契约）：[财务核心 P0 实现证据矩阵](财务核心P0实现证据矩阵.md)。 -文档优先级：五页验收契约和本轮产品确认 > 五页目标 OpenAPI > 既有人工 F1 契约/门禁 > 领域模型、历史全量规划和迁移文档。旧文档用于追溯，不得据此把钱包、充值、发票、费用分析或利润表重新纳入一期。 +文档优先级：五页验收契约和本轮产品确认 > 五页目标 OpenAPI > 既有人工 F1 契约/门禁 > 领域模型、历史全量规划和迁移文档。旧文档用于追溯，不得据此把钱包、充值、发票、费用分析或利润表重新纳入订单与客户。 旧文档降级规则： -| 文档/章节 | 当前用途 | 一期实施约束 | +| 文档/章节 | 当前用途 | 订单与客户实施约束 | |---|---|---| | 本文第六节起的“历史全量规划” | 保存早期盘点和演进背景 | 与五页契约冲突时全部失效，不作为菜单、路由、字段或接口依据 | | `财务领域模型与跨服务契约.md` | 历史合并稿 | 已被数据字典和跨服务契约替代 | -| `财务服务边界设计.md`、`财务领域模型与数据字典.md` | 服务边界和长期模型参考 | 其中钱包、充值、发票、费用分析、利润模型不属于一期 | +| `财务服务边界设计.md`、`财务领域模型与数据字典.md` | 服务边界和长期模型参考 | 其中钱包、充值、发票、费用分析、利润模型不属于订单与客户 | | `财务历史迁移与上线验收方案.md`、`财务F0实施任务拆分.md` | 历史迁移、底座任务追溯 | 不得覆盖五页范围和当前实现状态 | 详细设计材料： @@ -61,10 +61,10 @@ Finance 全链路测试环境实跑报告为 `baiyue-firstleg/reports/finance-fu - [Firstleg-Finance跨服务契约](Firstleg-Finance跨服务契约.md) - [F1 人工账单、收款、成本接口契约](F1人工账单收款成本接口契约.md) - [F1 人工财务契约审查与门禁](F1人工财务契约审查与门禁.md) -- [财务一期五页产品与接口验收契约](财务一期五页产品与接口验收契约.md) -- [财务一期五页 OpenAPI](openapi/finance-phase1-five-pages-v1.yaml) -- [财务一期 P0 操作契约与验收用例](财务一期P0操作契约与验收用例.md) -- [财务一期 P0 实现证据矩阵](财务一期P0实现证据矩阵.md) +- [财务核心五页产品与接口验收契约](财务核心五页产品与接口验收契约.md) +- [财务核心五页 OpenAPI](openapi/finance-core-five-pages-v1.yaml) +- [财务核心 P0 操作契约与验收用例](财务核心P0操作契约与验收用例.md) +- [财务核心 P0 实现证据矩阵](财务核心P0实现证据矩阵.md) - [财务历史迁移与上线验收方案](财务历史迁移与上线验收方案.md) - [财务F0实施任务拆分](财务F0实施任务拆分.md) @@ -101,21 +101,21 @@ Finance 全链路测试环境实跑报告为 `baiyue-firstleg/reports/finance-fu 此前基础链路已完成 Firstleg 真实柜次体积快照、客户归属、成本凭证校验、revision、双权限上传、费用来源事件/Relay/快照、Finance `fin_fee_source` 消费写入和完整幂等。在此基础上，固定五页所需的 11 个目标 operation、Admin 页面动作与 IAM 权限目录现已闭环，G1-G4 本地门禁均为 `PASS`；最终直接证据包括 Finance 聚合 82/82、G3 16/16、G4 18/18、收款及 AR 同步 12/12、IAM 168/168、Admin 财务专项 60/60、Admin 全量 654/654 及 Admin 构建通过。真实 MySQL 执行、测试环境 HTTP 冒烟和领导页面验收仍需单独完成，未经当前对话明确授权不触发 Jenkins。 -一期范围已重新冻结为原型 5 页：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付。费用分析、利润表、发票和钱包不做，也不保留菜单、路由或假按钮。客户账户改为账单、收款和应收应付来源派生的财务往来总览，不做充值/预收。 +订单与客户范围已重新冻结为原型 5 页：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付。费用分析、利润表、发票和钱包不做，也不保留菜单、路由或假按钮。客户账户改为账单、收款和应收应付来源派生的财务往来总览，不做充值/预收。 ## 二、事实来源与边界 本次按以下资料核对： -1. 二期需求文档明确二期只做头程计费，不自动形成应收、应付、对账单、收付款、核销、发票、利润或总账。 +1. 入库测量与计费需求文档明确入库测量与计费只做头程计费，不自动形成应收、应付、对账单、收付款、核销、发票、利润或总账。 2. 平台后台原型提供财务管理全量参考，但其中数据和交互主要由单页 HTML 内的静态数据及前端脚本驱动。 3. 当前代码用于证明“已经实现什么”，不反向扩大产品范围。 主要依据： -- `docs/二期/二期计费财务需求确认表.md` -- `docs/二期/二期V2需求确认清单.md` -- `docs/二期/二期需求优化版-v2-测量计费入库主流程.md` +- `docs/入库测量与计费/入库测量与计费计费财务需求确认表.md` +- `docs/入库测量与计费/入库测量与计费V2需求确认清单.md` +- `docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md` - `docs/悦/货代SAAS平台后台/货代SaaS平台原型.html` - `apps/admin-web/src/modules/inbounds/` - `apps/admin-web/src/modules/fee-items/` @@ -163,13 +163,13 @@ Firstleg 已有 `fl_inbound_fee_detail`，包含： | 原型模块 | 原型展示的主要能力 | 当前代码状态 | 是否能直接纳入首期 | |---|---|---|---| -| 客户账户 | 原型为余额、冻结、可用余额和充值流水 | 未实现 | 一期保留汇总/详情/流水结构，但改为未收、待出账、本期已收等派生指标；删除充值/钱包能力 | +| 客户账户 | 原型为余额、冻结、可用余额和充值流水 | 未实现 | 订单与客户保留汇总/详情/流水结构，但改为未收、待出账、本期已收等派生指标；删除充值/钱包能力 | | 客户应收应付 | 费用明细、编辑审核、按截止时间或勾选生成账单 | 已接入真实费用来源和编辑审核闭环 | 作为应收应付费用池 | | 客户对账单 | 账期、汇率、应收、已收、结清、明细和支付历史 | 未实现 | 可作为应收闭环核心，但汇率和开票先暂缓 | | 结算单应收 | 应收、已收、余额、到期日、审批、部分收款 | 未实现 | 可合并进账单/应收单，避免首期重复建模 | -| 结算单应付 | 供应商应付、已付、余额、审批、部分付款、利润 | 未实现；上游成本来源不完整 | 一期纳入，但删除利润字段/按钮；必须先补真实供应商应付来源和付款凭证链路 | -| 费用分析 | 内外部费用对比、趋势和明细 | 未实现 | 一期明确不做，不进菜单/路由 | -| 利润表 | 按客户、货柜、单票、月份统计收入、成本、利润率 | 未实现 | 一期明确不做，不进菜单/路由 | +| 结算单应付 | 供应商应付、已付、余额、审批、部分付款、利润 | 未实现；上游成本来源不完整 | 订单与客户纳入，但删除利润字段/按钮；必须先补真实供应商应付来源和付款凭证链路 | +| 费用分析 | 内外部费用对比、趋势和明细 | 未实现 | 订单与客户明确不做，不进菜单/路由 | +| 利润表 | 按客户、货柜、单票、月份统计收入、成本、利润率 | 未实现 | 订单与客户明确不做，不进菜单/路由 | 原型还出现了发票抬头、开票日期、汇率、支付方式、收付款凭证号等字段。它们只说明未来可能需要，不代表当前产品已经确认税务、外币折算、资金或发票边界。 @@ -190,13 +190,13 @@ Firstleg 已有 `fl_inbound_fee_detail`，包含： ## 六、全量财务规划与交付顺序 -### 6.1 历史全量规划（不作为一期范围） +### 6.1 历史全量规划（不作为订单与客户范围） -以下内容只保留为历史分析。若与《财务一期五页产品与接口验收契约》冲突，以五页契约为准。 +以下内容只保留为历史分析。若与《财务核心五页产品与接口验收契约》冲突，以五页契约为准。 | 目标域 | 业务结果 | 主要来源 | 不能提前假定的口径 | |---|---|---|---| -| 客户账户 | 客户财务往来派生汇总、详情和流水 | 账单、收款和应收应付来源 | 一期不建设钱包、充值、预收或自动扣款 | +| 客户账户 | 客户财务往来派生汇总、详情和流水 | 账单、收款和应收应付来源 | 订单与客户不建设钱包、充值、预收或自动扣款 | | 客户应收 | 客户欠款、到期、逾期、结清 | 已发布对客费用、补差/冲销 | 收入确认节点和账期规则 | | 客户应付 | 客户代垫或返还类应付款（如确有业务） | 业务费用或人工单据 | 产品是否真的存在“平台向客户付款”的场景 | | 客户对账单 | 期间内费用汇总、明细、平台出账和客户确认 | 应收/应付费用池 | 一张账单是否允许混合方向、混合币种 | @@ -204,7 +204,7 @@ Firstleg 已有 `fl_inbound_fee_detail`，包含： | 结算单应付 | 供应商成本、付款、余额和结清 | 供应商费用、运力/仓储/报关成本 | 成本确认、供应商账期、审批和付款方式 | | 收付款与核销 | 到账/付款凭证，部分结算、反核销 | 银行流水或人工登记 | 是否首期接银行流水，是否允许一笔多单核销 | | 发票 | 开票申请、开具、红冲、作废和关联 | 已确认应收/收款 | 税率、含税/未税、开票主体、外部平台 | -| 费用分析 | 历史规划，一期不做 | 应收应付台账 | 不进入一期菜单、路由和验收 | +| 费用分析 | 历史规划，订单与客户不做 | 应收应付台账 | 不进入订单与客户菜单、路由和验收 | | 利润 | 客户/单票/柜次/月度收入、成本、利润率 | 应收收入 + 应付成本 + 分摊 | 汇率、成本分摊、收入成本确认时间 | ### 6.2 分阶段交付顺序 @@ -216,8 +216,8 @@ Firstleg 已有 `fl_inbound_fee_detail`，包含： | F0 财务底座 | 独立 Finance 服务/数据库、财务主体、客户/供应商往来单位、币种、费用科目、期间、权限、审计、幂等、金额精度 | 所有后续对象使用同一基础口径 | 服务边界已技术确认；产品确认主体、币种、权限和编码 | | F1 应收与客户对账 | 应收费用池、平台出账、客户确认、结算单应收、收款登记、核销、反核销 | 费用 → 账单 → 客户确认 → 应收 → 收款 → 结清 | 当前已发布对客费用来源 | | F2 应付与供应商结算 | 成本费用池、供应商账单、结算单应付、付款登记、付款核销、应付调整 | 成本 → 供应商账单 → 应付 → 付款 → 结清 | 供应商主数据和真实成本来源 | -| F3 客户账户与发票 | 一期只做派生客户账户总览；发票暂缓 | 账户只读聚合，不维护资金余额 | 发票不属于一期 | -| F4 分析与利润 | 一期不做 | 不建设菜单、路由或假入口 | 后续重新立项 | +| F3 客户账户与发票 | 订单与客户只做派生客户账户总览；发票暂缓 | 账户只读聚合，不维护资金余额 | 发票不属于订单与客户 | +| F4 分析与利润 | 订单与客户不做 | 不建设菜单、路由或假入口 | 后续重新立项 | 阶段之间可以并行做页面原型和契约设计，但生产数据链路必须按 F0 → F1/F2 → F3 → F4 验收。F4 不能用原型静态数字先行替代真实台账。 @@ -246,9 +246,9 @@ F1 建议页面： 4. 核销记录：每笔收款对应哪些应收、核销金额、剩余余额、反核销历史。 5. 客户侧账单：查看明细、收款与未结余额，并在线确认本人已出账账单；不做在线争议。 -以下历史排除清单已被 2026-08-11 的五页范围取代。结算单应付现在属于一期；其余未确认能力继续排除： +以下历史排除清单已被 2026-08-11 的五页范围取代。结算单应付现在属于订单与客户；其余未确认能力继续排除： -- 供应商在线确认和自动付款（应付结算单与人工付款属于一期）； +- 供应商在线确认和自动付款（应付结算单与人工付款属于订单与客户）； - 客户预充值、余额冻结和自动扣款； - 发票申请、开票和税务接口； - 多币种折算与汇兑损益； @@ -273,7 +273,7 @@ F1 建议页面： | 编号 | 待确认问题 | 建议默认值 | |---|---|---| -| F1 | 一期领导验收范围 | 固定为客户账户、客户应收应付、客户对账单、结算单应收、结算单应付；费用分析和利润表不做 | +| F1 | 订单与客户领导验收范围 | 固定为客户账户、客户应收应付、客户对账单、结算单应收、结算单应付；费用分析和利润表不做 | | F2 | 账单生成维度 | 客户 + 币种 + 账期；不同币种不合并 | | F3 | 哪些费用可以进入账单 | `APPROVED + PUBLISHED + AVAILABLE + CNY + amount>0` 且未出账；无人工结算开关 | | F4 | 当前已发布头程费用是否自动进入待对账池 | 是，但仍由财务选择并生成账单 | diff --git a/财务管理/openapi/finance-phase1-five-pages-v1.yaml b/财务管理/openapi/finance-core-five-pages-v1.yaml similarity index 99% rename from 财务管理/openapi/finance-phase1-five-pages-v1.yaml rename to 财务管理/openapi/finance-core-five-pages-v1.yaml index 8b1b904..3cb6158 100644 --- a/财务管理/openapi/finance-phase1-five-pages-v1.yaml +++ b/财务管理/openapi/finance-core-five-pages-v1.yaml @@ -3,10 +3,10 @@ info: title: Finance Phase 1 Five-page Acceptance API version: 1.0.0-draft description: >- - 一期领导验收 5 页目标契约：客户账户、客户应收应付、客户对账单、结算单应收、 + 订单与客户领导验收 5 页目标契约：客户账户、客户应收应付、客户对账单、结算单应收、 结算单应付。只支持 CNY。费用分析、利润表、钱包、预收和充值不属于本契约。 - 本文件冻结一期目标契约及后续确认的费用编辑审核、客户确认和应收统计扩展。实现与 - Admin 接入证据单独维护在财务一期P0实现证据矩阵.md，不得因代码文件出现反复修改本契约。 + 本文件冻结订单与客户目标契约及后续确认的费用编辑审核、客户确认和应收统计扩展。实现与 + Admin 接入证据单独维护在财务核心P0实现证据矩阵.md，不得因代码文件出现反复修改本契约。 servers: - url: /api x-product-scope: @@ -46,8 +46,8 @@ x-customer-account-ui-contract: x-phase1-p0-contract: status: FROZEN rule: 所有已列 operation 均为当前目标契约；实现状态不得写入本文件。 - contract: ../财务一期P0操作契约与验收用例.md - evidenceMatrix: ../财务一期P0实现证据矩阵.md + contract: ../财务核心P0操作契约与验收用例.md + evidenceMatrix: ../财务核心P0实现证据矩阵.md x-idempotency-contract: scope: method + normalizedPath + resolvedCustomerId + completeQueryAndBody sameKeySameRequest: replay original result diff --git a/财务管理/财务历史迁移与上线验收方案.md b/财务管理/财务历史迁移与上线验收方案.md index 3b31f1e..de0e365 100644 --- a/财务管理/财务历史迁移与上线验收方案.md +++ b/财务管理/财务历史迁移与上线验收方案.md @@ -12,7 +12,7 @@ 本方案用于把 Finance 上线前已经存在于 Firstleg 的历史对客费用，安全地接入独立 `finance-service` 和 `baiyue_finance`，并定义 F0/F1 从测试、灰度到正式启用的验收门禁。 -本方案不把“费用已发送/已发布”推断为“客户尚欠款”，也不把二期计费状态推断为财务结算状态。历史迁移分成三个明确步骤： +本方案不把“费用已发送/已发布”推断为“客户尚欠款”，也不把入库测量与计费计费状态推断为财务结算状态。历史迁移分成三个明确步骤： ```text Firstleg 历史费用候选集 @@ -71,7 +71,7 @@ Firstleg 历史费用候选集 ### 3.1 候选来源 -首批只处理能够追溯到 Firstleg 已发布对客费用版本的 `RECEIVABLE` 数据。当前二期费用用于证明业务计费结果，不直接证明应收、收款或核销事实。 +首批只处理能够追溯到 Firstleg 已发布对客费用版本的 `RECEIVABLE` 数据。当前入库测量与计费费用用于证明业务计费结果，不直接证明应收、收款或核销事实。 每条候选记录至少应能提供： diff --git a/财务管理/财务开工门禁与F0-F1任务清单.md b/财务管理/财务开工门禁与F0-F1任务清单.md index 6861fa3..fdf41d6 100644 --- a/财务管理/财务开工门禁与F0-F1任务清单.md +++ b/财务管理/财务开工门禁与F0-F1任务清单.md @@ -9,7 +9,7 @@ Finance 的服务拆分、独立数据库、基础表、权限、人工账单/收款/成本接口及 Admin/Client 基础页面已经落地。后端真实体积快照、归属、成本凭证、revision、双权限上传、费用来源事件/Relay/快照、固定 DTO、完整幂等、File fail-closed、客户收款 DTO 和稳定错误码已经完成并通过专项测试；当前继续收口 Admin 最终契约适配和五页剩余 operation。 -F0 的平台主体、首期仅 RMB/CNY、自定义账期、编号、费用冻结、无历史迁移、客户角色和首期简化审批已经确认。一期领导验收固定为 5 页；客户账户为派生财务往来总览，不做钱包/充值，费用分析和利润表不做。详见[财务一期五页产品与接口验收契约](财务一期五页产品与接口验收契约.md)。 +F0 的平台主体、首期仅 RMB/CNY、自定义账期、编号、费用冻结、无历史迁移、客户角色和首期简化审批已经确认。订单与客户领导验收固定为 5 页；客户账户为派生财务往来总览，不做钱包/充值，费用分析和利润表不做。详见[财务核心五页产品与接口验收契约](财务核心五页产品与接口验收契约.md)。 ## 二、文档交付状态 @@ -48,7 +48,7 @@ G0 允许：完善 API/OpenAPI、数据库迁移草案、契约测试样例、 当前按以下冻结口径修复和补测： -- `财务一期P0操作契约与验收用例.md` 中的 11 个 operation 全部为一期 P0；目标契约不跟随开发中间态修改，G1-G4 证据矩阵任一组未同时通过后端行为测试和 Admin 真实接入时均不得关闭； +- `财务核心P0操作契约与验收用例.md` 中的 11 个 operation 全部为订单与客户 P0；目标契约不跟随开发中间态修改，G1-G4 证据矩阵任一组未同时通过后端行为测试和 Admin 真实接入时均不得关闭； - 账单聚合维度（首期固定 RMB/CNY）和账期计算规则冻结； - 平台出账、关闭、重开和线下异议录入状态冻结；客户首期只读； @@ -56,9 +56,9 @@ G0 允许：完善 API/OpenAPI、数据库迁移草案、契约测试样例、 - 预收、多收、手续费、退款、反核销的处理方式冻结； - 至少准备一组真实或脱敏费用来源样本，能够完成费用→账单→应收→收款→核销回归。 -### G3/G4：一期应付与排除项门禁 +### G3/G4：订单与客户应付与排除项门禁 -结算单应付纳入一期，但必须有供应商和真实 PAYABLE 来源。客户账户只做派生查询。发票、费用分析、利润、汇率和月结不属于一期，禁止保留假入口。 +结算单应付纳入订单与客户，但必须有供应商和真实 PAYABLE 来源。客户账户只做派生查询。发票、费用分析、利润、汇率和月结不属于订单与客户，禁止保留假入口。 ## 四、F0/F1 任务清单 @@ -89,7 +89,7 @@ G0 允许：完善 API/OpenAPI、数据库迁移草案、契约测试样例、 ### 本轮不再等待产品确认 -- 一期只支持 CNY，验收 5 页及其真实费用来源、对账、应收/应付和人工收付款链路。 +- 订单与客户只支持 CNY，验收 5 页及其真实费用来源、对账、应收/应付和人工收付款链路。 - 客户账户是派生总览；发票、费用分析、利润、汇率、月结不属于本轮。 - 首发不迁移历史，不阻塞 F1 修复。 diff --git a/财务管理/财务服务边界设计.md b/财务管理/财务服务边界设计.md index b8ff9fa..af7cc34 100644 --- a/财务管理/财务服务边界设计.md +++ b/财务管理/财务服务边界设计.md @@ -1,6 +1,6 @@ # 财务服务边界设计 -> **范围说明**：本文只作为 Finance 独立服务/独立数据库的技术边界依据。文中的钱包、充值、发票、费用分析和利润属于长期模型，不属于一期；一期唯一产品范围以《财务一期五页产品与接口验收契约》为准。 +> **范围说明**：本文只作为 Finance 独立服务/独立数据库的技术边界依据。文中的钱包、充值、发票、费用分析和利润属于长期模型，不属于订单与客户；订单与客户唯一产品范围以《财务核心五页产品与接口验收契约》为准。 > 决策日期：2026-08-10 > 决策状态：技术已确认 diff --git a/财务管理/财务一期P0实现证据矩阵.md b/财务管理/财务核心P0实现证据矩阵.md similarity index 96% rename from 财务管理/财务一期P0实现证据矩阵.md rename to 财务管理/财务核心P0实现证据矩阵.md index a25a6f3..fe5eb34 100644 --- a/财务管理/财务一期P0实现证据矩阵.md +++ b/财务管理/财务核心P0实现证据矩阵.md @@ -1,7 +1,7 @@ -# 财务一期 P0 实现证据矩阵 +# 财务核心 P0 实现证据矩阵 -> 日期：2026-08-11 -> 目标契约：`openapi/finance-phase1-five-pages-v1.yaml`、`财务一期P0操作契约与验收用例.md` +> 日期：2026-08-11 +> 目标契约：`openapi/finance-core-five-pages-v1.yaml`、`财务核心P0操作契约与验收用例.md` > 使用规则：本文件只记录验收证据，不反向修改目标契约；Controller 文件、编译成功或开发中间态均不能单独关闭门禁 ## 1. 状态更新规则 @@ -15,7 +15,7 @@ ## 2. G1-G4 稳定验收表 -| 分组 | 一期 P0 operation | 后端行为测试放行条件 | Admin 真实接入放行条件 | 当前可复核证据 | 结论 | +| 分组 | 订单与客户 P0 operation | 后端行为测试放行条件 | Admin 真实接入放行条件 | 当前可复核证据 | 结论 | |---|---|---|---|---|---| | G1 客户账户 | `listDerivedCustomerAccounts`、`listDerivedCustomerAccountLedger` | 派生金额、分页筛选、日期边界、停用客户历史、跨客户隔离、固定 DTO/追踪字段测试全部通过 | 客户账户列表、筛选、详情入口、流水筛选均调用真实接口；无钱包、充值、预收或余额写入口 | 后端 G1 专项 4/4、Admin G1 专项 15/15、Finance 专项 21/21、Admin typecheck、IAM 166/166、IAM 权限契约 3/3、Finance 权限契约 2/2 通过；统一 SQL 已同步权限目录且未默认授予角色 | `PASS` | | G2 费用来源 | `getFinanceFeeSource`、`reviewFinanceFeeSource`、`updateFeeSourceSettlementInclusion` | 详情、PENDING 审核、非法状态、expectedVersion、占用冻结、完整幂等、跨客户隐藏和 CNY 条件全部通过 | 客户应收应付页详情、审核、参与/禁止结算使用真实接口；权限和服务端错误态可见，不存在假成功 | 后端 G2 专项 9/9、Admin G2 专项 21/21、Admin typecheck/build、IAM 166/166、IAM 权限契约 3/3、Finance 权限契约 2/2 通过；统一 SQL 已同步权限目录且未默认授予角色 | `PASS` | diff --git a/财务管理/财务一期P0操作契约与验收用例.md b/财务管理/财务核心P0操作契约与验收用例.md similarity index 92% rename from 财务管理/财务一期P0操作契约与验收用例.md rename to 财务管理/财务核心P0操作契约与验收用例.md index 52f5f4c..9799635 100644 --- a/财务管理/财务一期P0操作契约与验收用例.md +++ b/财务管理/财务核心P0操作契约与验收用例.md @@ -1,9 +1,9 @@ -# 财务一期 P0 操作契约与验收用例 +# 财务核心 P0 操作契约与验收用例 -> 日期：2026-08-11 -> 适用范围：一期财务闭环及后续确认的费用编辑审核、客户确认操作 -> 状态口径：以下 11 项全部是一期 P0，目标契约已冻结；实现和 Admin 接入证据只维护在 `财务一期P0实现证据矩阵.md` -> 机器契约：`openapi/finance-phase1-five-pages-v1.yaml` +> 日期：2026-08-11 +> 适用范围：订单与客户财务闭环及后续确认的费用编辑审核、客户确认操作 +> 状态口径：以下 11 项全部是订单与客户 P0，目标契约已冻结；实现和 Admin 接入证据只维护在 `财务核心P0实现证据矩阵.md` +> 机器契约：`openapi/finance-core-five-pages-v1.yaml` ## 1. 统一冻结规则 @@ -32,11 +32,11 @@ | P0-10 | `getSettlement` | `SettlementIdPath` | `SettlementDetailEnvelope` | AR/AP view 二选一并与单据方向匹配 | 返回结算单、来源快照、revision 和收付款记录；没有对应方向权限时 HTTP 403。验收 AC-22、AC-23 | | P0-11 | `createSettlementPayment` | `CreateSettlementPaymentRequest` | `SettlementDetailEnvelope` | `platform:finance:payment:create` | 只允许 PAYABLE 的 ISSUED/PARTIALLY_PAID；金额不得超过余额，凭证 File fail-closed；更新为 PARTIALLY_PAID/PAID。验收 AC-24 至 AC-26 | -`createReceiptWithAllocations` 已实现，不计入上述 11 项，但仍属于一期 P0 回归门禁：一笔 300 元收款可人工分配到同一客户 3 张各 100 元应收结算单并共用凭证；跨客户、草稿、超额、非 CNY、无有效凭证必须拒绝。 +`createReceiptWithAllocations` 已实现，不计入上述 11 项，但仍属于订单与客户 P0 回归门禁：一笔 300 元收款可人工分配到同一客户 3 张各 100 元应收结算单并共用凭证；跨客户、草稿、超额、非 CNY、无有效凭证必须拒绝。 ### 2.1 契约与证据分离 -本文件不记录 Controller、编译和测试中间态，也不使用 `NOT_IMPLEMENTED/IN_PROGRESS/IMPLEMENTED` 标记。G1-G4 后端行为测试和 Admin 真实接入证据统一见 `财务一期P0实现证据矩阵.md`；开发过程不得反向修改本文件冻结的路径、DTO、状态机和验收标准。 +本文件不记录 Controller、编译和测试中间态，也不使用 `NOT_IMPLEMENTED/IN_PROGRESS/IMPLEMENTED` 标记。G1-G4 后端行为测试和 Admin 真实接入证据统一见 `财务核心P0实现证据矩阵.md`；开发过程不得反向修改本文件冻结的路径、DTO、状态机和验收标准。 ## 3. 状态机 @@ -80,7 +80,7 @@ ISSUED --VOID--> VOIDED（已收付金额=0） VOIDED --REOPEN--> ISSUED（新 revision） ``` -一期不处理预收、多收、退款、手续费、自动银行对账或汇率折算。人工收付款只能分配到同客户、同方向、CNY 且已出账的结算单。 +订单与客户不处理预收、多收、退款、手续费、自动银行对账或汇率折算。人工收付款只能分配到同客户、同方向、CNY 且已出账的结算单。 ## 4. 请求字段条件 diff --git a/财务管理/财务一期五页产品与接口验收契约.md b/财务管理/财务核心五页产品与接口验收契约.md similarity index 92% rename from 财务管理/财务一期五页产品与接口验收契约.md rename to 财务管理/财务核心五页产品与接口验收契约.md index e3fe813..abde133 100644 --- a/财务管理/财务一期五页产品与接口验收契约.md +++ b/财务管理/财务核心五页产品与接口验收契约.md @@ -1,16 +1,16 @@ -# 财务一期五页产品与接口验收契约 +# 财务核心五页产品与接口验收契约 -> 日期：2026-08-11 -> 状态：产品范围已确认；一期 11 个 P0 operation 的目标契约已冻结；实现与 Admin 接入只按独立 G1-G4 证据矩阵验收，当前未放行 -> 领导验收范围：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付 +> 日期：2026-08-11 +> 状态：产品范围已确认；订单与客户 11 个 P0 operation 的目标契约已冻结；实现与 Admin 接入只按独立 G1-G4 证据矩阵验收，当前未放行 +> 领导验收范围：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付 > 原型依据：`docs/悦/货代SAAS平台后台/货代SaaS平台原型.html` -> 目标 OpenAPI：`openapi/finance-phase1-five-pages-v1.yaml`；当前人工接口继续参考 `openapi/finance-f1-manual-v1.yaml`。 -> 11 个 P0 操作的 DTO、状态机、权限、幂等、错误码、隔离和验收用例以 `财务一期P0操作契约与验收用例.md` 为准；实现证据只维护在 `财务一期P0实现证据矩阵.md`。 +> 目标 OpenAPI：`openapi/finance-core-five-pages-v1.yaml`；当前人工接口继续参考 `openapi/finance-f1-manual-v1.yaml`。 +> 11 个 P0 操作的 DTO、状态机、权限、幂等、错误码、隔离和验收用例以 `财务核心P0操作契约与验收用例.md` 为准；实现证据只维护在 `财务核心P0实现证据矩阵.md`。 -## 1. 一期范围结论 +## 1. 订单与客户范围结论 -一期只交付原型中的以下 5 页，并实现页面结构、字段、筛选、详情和状态： +订单与客户只交付原型中的以下 5 页，并实现页面结构、字段、筛选、详情和状态： 1. 客户账户。 2. 客户应收应付。 @@ -20,7 +20,7 @@ 明确不做：费用分析、利润表、钱包、预收、手动充值、自动扣款余额、汇率、外币、发票、月结、银行自动对账。未实现能力不得保留按钮、菜单、路由或模拟成功入口。 -所有金额只使用 CNY。原型中的 USD、汇率、开票日期、利润审批、利润金额仅为历史原型字段，一期删除。 +所有金额只使用 CNY。原型中的 USD、汇率、开票日期、利润审批、利润金额仅为历史原型字段，订单与客户删除。 客户对账单、应收结算单、应付结算单统一使用短业务编号：`REC-YYMMDD-NNNN`、`AR-YYMMDD-NNNN`、`AP-YYMMDD-NNNN`。日期按北京时间的单据创建日计算，各单据类型分别按日从 `0001` 递增；编号生成后不可修改，作废也不回收。 @@ -45,7 +45,7 @@ ## 3. 五页验收矩阵 -| 页面 | 原型结构和筛选 | 一期字段 | 一期操作 | 状态与验收 | +| 页面 | 原型结构和筛选 | 订单与客户字段 | 订单与客户操作 | 状态与验收 | |---|---|---|---|---| | 客户账户 | 汇总卡、客户列表、账户详情、流水详情；客户名称/编号、账户状态、余额条件、流水类型和日期 | 客户基本信息、客户编号、联系人、电话、未收余额、待出账金额、本期已收金额、总成本、已付成本、待付金额、账户状态、最后变动时间；流水号、时间、业务类型、关联单据、应收/应付变动、变动后未收余额、操作人、备注 | 详情、查询、重置、导出；**无充值、扣款或余额调整** | 运营资金只认三类：待收客户款=正式 AR outstanding，不叠加待出账；待付供应商款=AP outstanding+未制单有效 ON_ACCOUNT 来源并按来源去重；已线下支付供应商款=AP paid+有效 DIRECT_PAID，明细区分账期付款和现场已付。不存在客户线下支付分类，也不新增已收客户款卡片 | | 客户应收应付 | 工具栏、组合查询、选中汇总、费用列表、费用详情、审核进度、关联业务、操作记录 | 客户、费用单号、是否已生成对账单、审核状态、应收/应付、结算方式、已付时间/方式/凭证、入仓码/柜次号、业务状态、费用类型、金额、业务发生日、来源类型、来源版本 | 详情、编辑草稿/驳回项、提交审核、审核通过/拒绝、调整、作废、按截止时间或勾选生成；不提供“是否结算”开关 | PAYABLE 必须区分 ON_ACCOUNT/DIRECT_PAID；前者可进入 AP，后者只计成本且排除 AP；同一来源版本只能识别一次成本 | @@ -57,7 +57,7 @@ ### 3.1 五页现状/目标差异 -| 页面 | 当前仓库事实 | 一期目标 | 差异等级 | +| 页面 | 当前仓库事实 | 订单与客户目标 | 差异等级 | |---|---|---|---| | 客户账户 | 后端已新增 `/customer-accounts/{customerId}` 和固定读 DTO；无列表接口 | 派生财务往来汇总、详情和流水，无任何充值/余额写入口 | IMPLEMENTED（单客户查询）；列表/筛选仍缺，Finance DTO 测试通过 | | 客户应收应付 | `/fee-sources` 固定 DTO、Firstleg 事件/快照和 `fin_fee_source` 写入均已实现 | 真实入库/柜子费用来源池，支持编辑、提交、审核、调整、作废、详情和生成对账单 | 审核通过自动成为结算候选，不提供人工结算开关 | @@ -96,7 +96,7 @@ flowchart LR 当前柜子费用来源表/实体、Controller、审核/调整/作废服务、自动发布事件、Relay 和内部快照已经实现。Firstleg 的真实柜次体积快照同时服务 Finance 整柜成本分摊，但仍不能由 Admin 手工提交的订单归属或体积替代。 -一期至少需要业务侧模型： +订单与客户至少需要业务侧模型： - `containerFeeId/version`、`containerId/containerNo`、费用方向、费用项目、业务日、CNY 金额。 - 应付来源必须有供应商；应收来源必须有客户分摊结果。 @@ -151,11 +151,11 @@ Finance 必须通过 Inbox 幂等消费来源版本，或通过受保护的快 ## 7. 专项优先级 -### P0：一期验收硬阻断 +### P0：订单与客户验收硬阻断 1. 财务 operation 全部通过直接行为测试：账户列表/流水；费用来源详情及编辑审核闭环；对账单生成、审核、出账、客户确认、调整/作废；应收/应付结算单生成与详情；人工收付款登记。人工收款继续覆盖 300 元分配 3 张 100 元应收单等回归。 2. 对账单、应收/应付结算单、付款和 revision 所需数据模型与唯一约束同步落地，不能只做空 Controller。 -3. 详细冻结契约见 `财务一期P0操作契约与验收用例.md`；不得把其中任何一项标为 P1、后续优化或假入口。 +3. 详细冻结契约见 `财务核心P0操作契约与验收用例.md`；不得把其中任何一项标为 P1、后续优化或假入口。 ### P1：领导验收前必须完成 diff --git a/财务管理/财务管理产品确认版差异与剩余待确认.md b/财务管理/财务管理产品确认版差异与剩余待确认.md index 4e18fd8..67cb72d 100644 --- a/财务管理/财务管理产品确认版差异与剩余待确认.md +++ b/财务管理/财务管理产品确认版差异与剩余待确认.md @@ -4,7 +4,7 @@ > 复核日期：2026-08-10 > 用途：把产品回填内容转成可开发口径；不替代产品原始回传表。 -> **降级说明（2026-08-11）**：本文保留首次回填复核过程，不再作为一期范围入口。当前范围和冲突处理以《财务一期五页产品与接口验收契约》为准；原文中的“仍待确认”“F3 整体暂缓”“成本/利润统计”均不得覆盖已确认的五页范围。 +> **降级说明（2026-08-11）**：本文保留首次回填复核过程，不再作为订单与客户范围入口。当前范围和冲突处理以《财务核心五页产品与接口验收契约》为准；原文中的“仍待确认”“F3 整体暂缓”“成本/利润统计”均不得覆盖已确认的五页范围。 ## 一、回传表复核结论 @@ -12,7 +12,7 @@ 其中，以下内容可直接纳入正式文档： -- 一期页面固定为客户账户、客户应收应付、客户对账单、结算单应收、结算单应付；客户账户只是派生财务往来总览，不做钱包/预收；发票和外部接口不做。 +- 订单与客户页面固定为客户账户、客户应收应付、客户对账单、结算单应收、结算单应付；客户账户只是派生财务往来总览，不做钱包/预收；发票和外部接口不做。 - 供应商付款为线下付款并上传凭证；单票成本直接归属单票，整柜清关、拖车等公共成本按柜内体积分摊。 - 首期账单只支持 RMB/CNY；每个客户维护自己的账期配置，默认 30 天。 - 收款全部由财务人工填写表单并上传收款图片；一笔 300 元可由财务分别填入 3 张 100 元账单，关联同一张凭证。 @@ -36,17 +36,17 @@ | 事项 | 暂缓口径 | |---|---| -| F2-01、F2-03、F2-04 | 供应商在线确认、自动付款等能力暂缓；一期仍须交付结算单应付页、真实 PAYABLE 来源和人工付款凭证链路 | -| F3-01 至 F3-04 | 一期建设客户账户派生总览页，但不建设钱包余额、充值、冻结、自动扣款或退款对象 | +| F2-01、F2-03、F2-04 | 供应商在线确认、自动付款等能力暂缓；订单与客户仍须交付结算单应付页、真实 PAYABLE 来源和人工付款凭证链路 | +| F3-01 至 F3-04 | 订单与客户建设客户账户派生总览页，但不建设钱包余额、充值、冻结、自动扣款或退款对象 | | F3-05 至 F3-07 | 发票和外部开票/银行接口首期线下处理；只保留未来扩展位 | -| F4-04 | 费用分析和利润表一期不进菜单/路由；后续重新立项时再定义权限 | +| F4-04 | 费用分析和利润表订单与客户不进菜单/路由；后续重新立项时再定义权限 | ## 四、当前放行判断 - F0 技术方案和客户主体/成员边界已经冻结，可以继续做 Finance 服务骨架、数据库迁移草案、事件契约和权限矩阵设计。 - F1 客户应收的核心产品口径已补齐；账期日期算法、账单单据粒度和收款字段可按本文默认值直接写入契约。 - F2/F4 的产品口径已补齐；开发前只需把人工成本/收款表单字段、凭证关联和体积分摊公式写入接口与验收契约。 -- F3 钱包/充值/发票能力可暂缓；客户账户派生总览属于一期五页，不得整体暂缓。 +- F3 钱包/充值/发票能力可暂缓；客户账户派生总览属于订单与客户五页，不得整体暂缓。 因此，本轮已没有新的核心产品问题；剩余工作是把确认版 XLSX 的状态归一化，并在接口/验收契约中补充账期日期算法、收款表单字段、收款凭证与账单分配关系、成本来源字段和体积分摊公式。 diff --git a/财务管理/财务管理产品确认表.md b/财务管理/财务管理产品确认表.md index b6e4f9f..fa6685c 100644 --- a/财务管理/财务管理产品确认表.md +++ b/财务管理/财务管理产品确认表.md @@ -1,15 +1,15 @@ # 财务管理产品确认表 -> 版本：V1.1 -> 创建日期：2026-08-10 -> 状态：一期 5 页范围已确认 +> 版本：V1.1 +> 创建日期：2026-08-10 +> 状态：订单与客户 5 页范围已确认 > 适用范围：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付 > 技术方案说明：服务边界、跨服务访问、事件幂等、金额存储、状态留痕和正式模块发布方式已按当前仓库架构直接确认，不再要求产品确认；以 XLSX 的“技术结论”工作表为准。 正式技术决策见：[财务服务边界设计](财务服务边界设计.md)。 -一期领导验收及接口事实以[财务一期五页产品与接口验收契约](财务一期五页产品与接口验收契约.md)为准；本文后续 F2-F4 历史问题不自动进入一期。 +订单与客户领导验收及接口事实以[财务核心五页产品与接口验收契约](财务核心五页产品与接口验收契约.md)为准；本文后续 F2-F4 历史问题不自动进入订单与客户。 产品回传版 XLSX 的逐项复核和剩余确认门禁见：[财务管理产品确认版差异与剩余待确认](财务管理产品确认版差异与剩余待确认.md)。 @@ -44,7 +44,7 @@ | 实施复杂度 | 首期全部由平台财务人工填写账单、收款和成本表单并上传凭证；不建设自动银行对账、自动核销、复杂审批、钱包、发票或总账 | | 审批复杂度 | 首期不做强制双人复核和金额分级审批；保留独立权限、操作原因和完整审计 | | 成员停用 | 客户子用户停用只撤销访问权限；客户账单、应收、余额等仍归客户企业，不触发财务单据转交；历史保留操作人快照 | -| 一期页面 | 只做客户账户、客户应收应付、客户对账单、结算单应收、结算单应付；费用分析和利润表不进菜单/路由 | +| 订单与客户页面 | 只做客户账户、客户应收应付、客户对账单、结算单应收、结算单应付；费用分析和利润表不进菜单/路由 | | 客户账户性质 | 财务往来派生总览，不是钱包；删除手动充值、预收、可消费余额和自动扣款入口 | | 费用来源链路 | 入库单费用和柜子费用审核通过后自动发布到 Finance 来源池并成为结算候选；不保留人工“是否结算”标记 | @@ -53,13 +53,13 @@ | 编号 | 范围 | 建议结论 | 最终结论 | 状态 | |---|---|---|---|---| | S1 | 客户账户 | 做预充值、冻结、解冻、扣款、退款和账户流水；账户余额与应收核销分开，任何抵扣都产生核销记录 | 只做账单、收款和应收应付来源派生的财务往来总览；不做钱包、预收、充值和自动扣款 | 已确认 | -| S2 | 客户应收 | 做客户费用池、对账单、应收单、到期/逾期、收款、部分核销、结清、反核销 | 纳入一期 5 页；平台财务操作，客户只读 | 已确认 | +| S2 | 客户应收 | 做客户费用池、对账单、应收单、到期/逾期、收款、部分核销、结清、反核销 | 纳入订单与客户 5 页；平台财务操作，客户只读 | 已确认 | | S3 | 客户应付 | 仅在确有平台向客户付款的业务场景时启用；否则不开放菜单和数据方向 | 客户应收应付页按来源方向展示；没有真实 PAYABLE 来源时为空，不造模拟数据 | 已确认 | | S4 | 客户对账单 | 按客户 + 币种 + 账期生成，支持平台内部复核、发送、关闭和财务重开；客户只读查看 | 平台财务出账，客户只读，异议线下反馈 | 已确认 | -| S5 | 供应商应付 | 做供应商成本池、供应商对账、应付单、付款、付款核销和反核销 | 结算单应付纳入一期；只使用具有供应商和真实来源的 CNY 应付费用，付款人工登记 | 已确认 | -| S6 | 发票 | 做发票申请、开票登记、票号/文件关联、红冲和作废；不直接假定外部开票平台 | 一期不做，不设计菜单、路由或按钮 | 已确认 | -| S7 | 费用分析 | 按费用项目、客户、供应商、期间统计发生额、已结算额和余额，支持钻取来源单据 | 一期不做，不进菜单/路由 | 已确认 | -| S8 | 利润 | 支持客户、货柜、单票、月份维度；收入、成本、分摊、汇率和利润率必须可追溯 | 一期不做，不进菜单/路由；应付页删除利润字段和利润审批 | 已确认 | +| S5 | 供应商应付 | 做供应商成本池、供应商对账、应付单、付款、付款核销和反核销 | 结算单应付纳入订单与客户；只使用具有供应商和真实来源的 CNY 应付费用，付款人工登记 | 已确认 | +| S6 | 发票 | 做发票申请、开票登记、票号/文件关联、红冲和作废；不直接假定外部开票平台 | 订单与客户不做，不设计菜单、路由或按钮 | 已确认 | +| S7 | 费用分析 | 按费用项目、客户、供应商、期间统计发生额、已结算额和余额，支持钻取来源单据 | 订单与客户不做，不进菜单/路由 | 已确认 | +| S8 | 利润 | 支持客户、货柜、单票、月份维度；收入、成本、分摊、汇率和利润率必须可追溯 | 订单与客户不做，不进菜单/路由；应付页删除利润字段和利润审批 | 已确认 | ## 三、F0 财务底座确认 @@ -104,7 +104,7 @@ | F1-07 | 核销关系 | 支持一笔收款核销多张应收、一张应收被多笔收款核销；禁止跨币种和超额 | 一笔客户付款可分配到多张账单；财务分别填写各账单对应金额并关联同一收款凭证；首期不处理预收、多收、手续费、退款 | 已确认 | | F1-08 | 反核销/作废 | 独立高风险权限，填写原因并保留原记录；不物理删除 | 首期不做复杂反核销；未收单据可作废，已出账调整/作废重开必须留原因、版本和原记录 | 已确认 | | F1-09 | 出账后调整 | 已出账冻结；平台财务通过调整/作废重开形成新版本，保留原金额和原因 | 仅平台财务手工调整，不允许客户修改 | 已确认 | -| F1-10 | 预收/多收/手续费/退款 | 单独建模为预收、其他应付款或退款，不直接冲减应收金额 | 一期全部不做；不设计钱包或预收入口 | 已确认 | +| F1-10 | 预收/多收/手续费/退款 | 单独建模为预收、其他应付款或退款，不直接冲减应收金额 | 订单与客户全部不做；不设计钱包或预收入口 | 已确认 | | F1-11 | 应收款统计表 | 按结算单生成自然月和客户汇总 CNY 正式应收 | 展示应收总额、已收合计、余额未收，支持打印和异步 Excel；不做 FBA 渠道拆分、USD、编辑或零头减免 | 已确认 | ## 五、F2 供应商应付与结算确认 @@ -113,11 +113,11 @@ |---|---|---|---|---| | F2-01 | 成本来源 | 只有具备 Warehouse 供应商、真实业务来源、审核和 CNY 正金额的 PAYABLE 来源才能进入应付池 | 供应商必须为 `ACTIVE`，名称只取 Warehouse 快照；费用项目 `supplierCategory` 为空时允许任意启用供应商，非空时严格匹配类别 | 已确认 | | F2-02 | 成本确认节点 | 费用审核通过后自动发布并进入 Finance 结算候选，确认后冻结成本快照 | 不保留“参与结算”开关；来源版本冻结 | 已确认 | -| F2-03 | 供应商账单 | DRAFT → INTERNAL_REVIEW → SENT → CONFIRMED → CLOSED；差异走争议/补差/冲销 | 一期不单独做供应商对账页，直接在结算单应付中生成、审核和付款 | 已确认 | +| F2-03 | 供应商账单 | DRAFT → INTERNAL_REVIEW → SENT → CONFIRMED → CLOSED；差异走争议/补差/冲销 | 订单与客户不单独做供应商对账页，直接在结算单应付中生成、审核和付款 | 已确认 | | F2-04 | 应付状态 | OPEN → PARTIALLY_PAID → PAID；到期增加 OVERDUE 标记 | DRAFT → PENDING_REVIEW → ISSUED → PARTIALLY_PAID → PAID；可拒绝/作废并留痕 | 已确认 | | F2-05 | 付款与核销 | 付款单独登记，支持多对多付款核销；禁止跨币种和超额 | 平台财务人工登记付款表单和凭证；不得跨供应商或超额 | 已确认 | -| F2-06 | 审批 | 应付确认和付款前复核使用独立权限；是否需要金额分级审批待确认 | 使用独立审核权限；一期不做金额分级或强制双人 | 已确认 | -| F2-07 | 预付/押金/代付/退款 | 不混入普通应付余额，单独建模并保留关联单据 | 一期不做 | 已确认 | +| F2-06 | 审批 | 应付确认和付款前复核使用独立权限；是否需要金额分级审批待确认 | 使用独立审核权限；订单与客户不做金额分级或强制双人 | 已确认 | +| F2-07 | 预付/押金/代付/退款 | 不混入普通应付余额，单独建模并保留关联单据 | 订单与客户不做 | 已确认 | | F2-08 | 当前人工 PAYABLE 明细 | 仅作为待补充来源，不得直接视为供应商应付闭环 | 没有供应商、审核和发布事实的明细不得进入结算单应付 | 已确认 | | F2-09 | 账期应付与已付成本 | 费用方向只表示收付对象，支付时点另建字段 | `direction` 保持 `RECEIVABLE/PAYABLE`；PAYABLE 必填 `settlementMode=ON_ACCOUNT/DIRECT_PAID`。ON_ACCOUNT 进入 AP，DIRECT_PAID 只计成本且永不进入 AP 或待付金额 | 已确认 | | F2-10 | 已付成本凭证 | 已付事实必须具备时间、方式和可追溯证据 | DIRECT_PAID 必填 `paidAt`、`paymentMethod`；方式限 `ONLINE/BANK_TRANSFER/CASH/OTHER`，`paymentReferenceNo` 与付款凭证至少一项 | 已确认 | @@ -131,7 +131,7 @@ | F3-01 | 账户余额性质 | 明确是客户预付款余额还是平台内部授信；充值必须有到账凭证，余额变更原子落流水 | 不是资金余额；客户账户页只展示账单、收款和费用来源派生指标 | 已确认 | | F3-02 | 账户与应收关系 | 账户扣款可以核销应收，但不得直接修改应收原金额；余额、扣款、核销三条记录均保留 | 不做账户扣款；收款只通过结算单分配更新未收余额 | 已确认 | | F3-03 | 冻结与解冻 | 明确冻结触发、解冻人、原因、部分冻结和失败补偿 | 不做钱包冻结/解冻；待出账金额由合格未出账来源派生 | 已确认 | -| F3-04 | 退款 | 退款必须关联原充值/收款，记录审批、到账方式、退款凭证和余额恢复规则 | 一期不做充值和退款 | 已确认 | +| F3-04 | 退款 | 退款必须关联原充值/收款，记录审批、到账方式、退款凭证和余额恢复规则 | 订单与客户不做充值和退款 | 已确认 | | F3-05 | 发票主体 | 明确开票主体、税率、含税/未税、发票类型和客户抬头校验 | 待填写 | 待确认 | | F3-06 | 开票流程 | 申请 → 审核 → 开票登记 → 票据/文件关联；红冲、作废不可删除原票 | 待填写 | 待确认 | | F3-07 | 外部平台 | 首版可人工登记，外部开票平台和银行流水接口另定接入契约 | 待填写 | 待确认 | @@ -140,13 +140,13 @@ | 编号 | 需要确认的事项 | 建议结论 | 最终结论 | 状态 | |---|---|---|---|---| -| F4-01 | 收入口径 | 按已确认/已发布应收还是已收款确认收入，二者报表分开显示 | 费用分析/利润表一期不做 | 已确认 | -| F4-02 | 成本口径 | 按已确认应付还是已付款确认成本，二者报表分开显示 | 费用分析/利润表一期不做；来源成本仍用于应付结算 | 已确认 | -| F4-03 | 分摊维度 | 支持客户、订单、单票、柜次、费用项目；明确公共成本分摊算法 | 一期只为来源和结算保留真实分摊，不开发利润分析页面 | 已确认 | -| F4-04 | 汇率 | 明确交易日、账单日或月末汇率，以及本位币和汇兑损益 | 一期只支持 CNY，不做汇率 | 已确认 | -| F4-05 | 期间锁定 | 月结后报表冻结；调整通过新期间补差/冲销反映 | 一期不做月结 | 已确认 | -| F4-06 | 利润维度 | 客户、货柜、单票、月份均支持；每个结果可钻取到收入、成本、分摊和原始单据 | 一期不做利润表 | 已确认 | -| F4-07 | 导出与权限 | 导出按财务数据权限控制，客户不可见供应商成本和内部利润 | 一期无利润菜单、路由或权限 | 已确认 | +| F4-01 | 收入口径 | 按已确认/已发布应收还是已收款确认收入，二者报表分开显示 | 费用分析/利润表订单与客户不做 | 已确认 | +| F4-02 | 成本口径 | 按已确认应付还是已付款确认成本，二者报表分开显示 | 费用分析/利润表订单与客户不做；来源成本仍用于应付结算 | 已确认 | +| F4-03 | 分摊维度 | 支持客户、订单、单票、柜次、费用项目；明确公共成本分摊算法 | 订单与客户只为来源和结算保留真实分摊，不开发利润分析页面 | 已确认 | +| F4-04 | 汇率 | 明确交易日、账单日或月末汇率，以及本位币和汇兑损益 | 订单与客户只支持 CNY，不做汇率 | 已确认 | +| F4-05 | 期间锁定 | 月结后报表冻结；调整通过新期间补差/冲销反映 | 订单与客户不做月结 | 已确认 | +| F4-06 | 利润维度 | 客户、货柜、单票、月份均支持；每个结果可钻取到收入、成本、分摊和原始单据 | 订单与客户不做利润表 | 已确认 | +| F4-07 | 导出与权限 | 导出按财务数据权限控制，客户不可见供应商成本和内部利润 | 订单与客户无利润菜单、路由或权限 | 已确认 | ## 八、全量验收主链路 diff --git a/财务管理/财务领域模型与数据字典.md b/财务管理/财务领域模型与数据字典.md index 9233ba7..350000e 100644 --- a/财务管理/财务领域模型与数据字典.md +++ b/财务管理/财务领域模型与数据字典.md @@ -1,11 +1,11 @@ # 财务领域模型与数据字典（F0/F1 首版） -> **范围说明**：本文包含长期数据模型候选。钱包、充值、发票、费用分析和利润表不属于一期，不得据此建菜单、路由或接口；一期数据模型以《财务一期五页产品与接口验收契约》为准。 +> **范围说明**：本文包含长期数据模型候选。钱包、充值、发票、费用分析和利润表不属于订单与客户，不得据此建菜单、路由或接口；订单与客户数据模型以《财务核心五页产品与接口验收契约》为准。 > 版本：V0.1（开发前设计稿） > 日期：2026-08-10 > 范围：F0 财务底座、F1 客户应收与对账；F2-F4 预留 -> 关联：[财务服务边界设计](财务服务边界设计.md)、[财务管理产品确认表](财务管理产品确认表.md)、[二期费用项目数据归属决策记录](../二期/二期费用项目数据归属决策记录.md) +> 关联：[财务服务边界设计](财务服务边界设计.md)、[财务管理产品确认表](财务管理产品确认表.md)、[入库测量与计费费用项目数据归属决策记录](../入库测量与计费/入库测量与计费费用项目数据归属决策记录.md) ## 1. 阅读和决策标记 diff --git a/财务管理/财务领域模型与跨服务契约.md b/财务管理/财务领域模型与跨服务契约.md index 74ee769..8000e14 100644 --- a/财务管理/财务领域模型与跨服务契约.md +++ b/财务管理/财务领域模型与跨服务契约.md @@ -1,6 +1,6 @@ # 财务领域模型与跨服务契约（历史合并稿） -> **历史文档，非一期实施依据**：本合并稿已被《财务领域模型与数据字典》《Firstleg-Finance 跨服务契约》和《财务一期五页产品与接口验收契约》替代。钱包、充值、发票、费用分析和利润模型不属于一期。 +> **历史文档，非订单与客户实施依据**：本合并稿已被《财务领域模型与数据字典》《Firstleg-Finance 跨服务契约》和《财务核心五页产品与接口验收契约》替代。钱包、充值、发票、费用分析和利润模型不属于订单与客户。 > 文档状态：已被拆分替代，仅保留历史设计过程，不作为后续实施依据 > 替代文档：[财务领域模型与数据字典](财务领域模型与数据字典.md)、[Firstleg-Finance 跨服务契约](Firstleg-Finance跨服务契约.md)