From b058ccb374fe31e16c37b014883d4dd18556b874 Mon Sep 17 00:00:00 2001 From: ouyangxq <775153912@qq.com> Date: Sat, 8 Aug 2026 11:33:06 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 12 ++++++++++++ shared/AGENTS.md | 8 ++++++++ 2 files changed, 20 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 6ba59ca..5a7b2cc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,3 +60,15 @@ pnpm build - 日常变更至少运行 `pnpm typecheck`；交付前运行 `pnpm build`。 - 当前测试使用 Node.js 内置测试运行器，执行 `pnpm test`；项目仍未声明 lint 脚本，不得声称 lint 已通过。 - 不手工修改 `dist/` 或 `node_modules/`；依赖变更必须同步当前项目依赖清单和锁文件。 + +## 一期/二期/三期快速索引 + +按阶段开展客户工作台任务时，先核对对应阶段文档，再进入模块；阶段范围以用户确认、需求确认表和设计文档为准，原型只用于视觉与交互补充。 + +| 阶段 | 当前状态与边界 | Client 代码入口 | 开始前核对 | +|---|---|---|---| +| 一期：客户与头程订单闭环 | 登录/注册、企业资料与资质、成员/角色权限、工作台和头程订单已接入一期后端；当前重点为测试 Gateway 验收，仓库查询与草稿创建仍受后端 `S0500` 阻断。订单停在已确认的七状态，不对客户开放取消写操作。 | `src/modules/auth/`、`tenant-management/`、`account/`、`system/`、`dashboard/`、`first-leg/`、`order-management/`；路由由各模块 `routes.ts` 通过 `src/modules/registry.ts` 组装。 | `../../docs/一期/README.md`、`../../docs/一期/一期开发进度表.md`、`../../docs/一期/一期头程订单闭环设计.md`；核对资格门禁、幂等键、状态机、仓库主数据及真实接口错误处理。 | +| 二期：到仓与头程计费 | 客户侧以一期订单为承接面，展示入库/测量/费用结果；技术闭环终点为 `WAIT_SPLIT + APPROVED + CONFIRMED`，`WAIT_SPLIT` 等待三期分柜。不得在 Client 暴露 Admin 内部备注、文件或测量原始数据之外的敏感运营字段。 | `src/modules/first-leg/`（订单详情中的到仓、测量、费用只读区）；费用与入库 API、类型和状态映射应与后端 `firstleg/` Controller/OpenAPI 对齐。 | `../../docs/二期/README.md`、`../../docs/二期/二期需求优化版-v2-测量计费入库主流程.md`、`../../docs/二期/二期前端联调报告-2026-08-04.md`、`../../docs/二期/第三方入仓测量接口联调说明-2026-08-04.md`；`二期开发进度表.md` 为旧口径，使用前核对日期与验收终点。 | +| 三期：国内出仓 | 当前 NO-GO、需求确认未完成；Client 暂不新增正式业务入口。阶段终点是国内出仓完成、等待装船，涉及分柜/订舱/拖车/PDA 拣货/装柜证据等能力，必须先解除 P3-Q1/Q2/Q5/Q9/Q11/Q12/Q13 阻断。 | 规划复用 `src/modules/first-leg/`、`order-management/` 的订单承接与状态展示；新增模块、路由或 `release: 'active'` 页面前须完成契约和权限确认。 | `../../docs/三期/README.md`、`../../docs/三期/三期开发规划.md`、`../../docs/三期/三期需求确认表.md`、`../../docs/三期/三期页面与原型清单.md`；不得把原型中的完整 WMS、报关或海运流程自动纳入 Client 三期范围。 | + +阶段边界：一期负责客户入驻与下单，二期负责到仓和计费并停在等待三期分柜，三期才进入国内出仓；不要把 PDA、分柜、装柜或完整财务应收应付提前实现到客户工作台。 diff --git a/shared/AGENTS.md b/shared/AGENTS.md index 5efe933..576bff1 100644 --- a/shared/AGENTS.md +++ b/shared/AGENTS.md @@ -18,3 +18,11 @@ - 修改导出名称、字段类型、枚举值或常量语义前，搜索当前应用内全部消费者。 - 优先采用兼容性新增；破坏性修改必须同步更新当前应用消费者。 - 本包没有独立质量脚本；变更后运行父应用声明的类型检查、测试或构建命令。 + +## 一期/二期/三期契约索引 + +- 一期共享模型主要服务客户认证、企业资料/成员权限和头程订单：修改订单状态、仓库摘要、资质或权限枚举前，核对 `../../../docs/一期/一期头程订单闭环设计.md` 及后端 Controller/DTO/OpenAPI，并搜索 `src/modules/` 全部消费者。 +- 二期只在客户侧承接到仓与计费结果的展示契约。`WAIT_SPLIT + APPROVED + CONFIRMED` 是当前技术闭环终点，内部测量明细、备注和文件权限不可通过共享类型绕过；费用字段必须与后端 `firstleg/` 契约兼容。 +- 三期当前 NO-GO。不得为了预留分柜、装柜、PDA 或报关字段而提前扩展公共枚举；待 `../../../docs/三期/三期需求确认表.md` 中 P3-Q1/Q2/Q5/Q9/Q11/Q12/Q13 解除后，再以兼容新增方式定义模型，并同步所有 Client 消费者。 + +阶段文档入口（路径相对本文件所在目录）：一期 `../../../docs/一期/README.md`；二期 `../../../docs/二期/README.md` 与 `../../../docs/二期/二期需求优化版-v2-测量计费入库主流程.md`；三期 `../../../docs/三期/README.md`、`../../../docs/三期/三期开发规划.md` 和 `../../../docs/三期/三期需求确认表.md`。阶段文档优先级高于历史进度表和原型。