From c1f2411c6cddf685620285726108a078f6c506b1 Mon Sep 17 00:00:00 2001 From: ouyangxq <775153912@qq.com> Date: Sat, 8 Aug 2026 12:01:54 +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 | 6 +++--- shared/AGENTS.md | 8 +++++--- src/modules/first-leg/api/unifiedOrders.test.mjs | 11 +++++++++++ 3 files changed, 19 insertions(+), 6 deletions(-) create mode 100644 src/modules/first-leg/api/unifiedOrders.test.mjs diff --git a/AGENTS.md b/AGENTS.md index 5a7b2cc..5597f38 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -63,12 +63,12 @@ pnpm build ## 一期/二期/三期快速索引 -按阶段开展客户工作台任务时，先核对对应阶段文档，再进入模块；阶段范围以用户确认、需求确认表和设计文档为准，原型只用于视觉与交互补充。 +按阶段开展客户工作台任务时，先核对对应阶段文档，再按“模块 `routes.ts` → 页面/组件 → `api`、store、contracts”定位；阶段范围以用户确认、需求确认表和设计文档为准，原型只用于视觉与交互补充。本表只描述 Client 页面与客户可见契约，服务端实现详见后端模块指引。 | 阶段 | 当前状态与边界 | 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 三期范围。 | +| 二期：到仓与头程计费 | 客户侧以一期订单为承接面，展示已授权的入库、测量和费用结果；页面终点为 `WAIT_SPLIT + APPROVED + CONFIRMED`，不暴露 Admin 内部备注、文件或未授权原始证据。 | `src/modules/first-leg/`（订单详情中的到仓、测量、费用只读区）；同步维护本模块 `api`、store、类型和状态映射。 | `../../docs/二期/README.md`、`../../docs/二期/二期需求优化版-v2-测量计费入库主流程.md`、相关联调报告；`二期开发进度表.md` 为旧口径，使用前核对日期与验收终点。 | +| 三期：国内出仓 | 当前 NO-GO、需求确认未完成；Client 暂不新增正式业务入口。 | 规划复用 `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 576bff1..11361cf 100644 --- a/shared/AGENTS.md +++ b/shared/AGENTS.md @@ -21,8 +21,10 @@ ## 一期/二期/三期契约索引 -- 一期共享模型主要服务客户认证、企业资料/成员权限和头程订单：修改订单状态、仓库摘要、资质或权限枚举前，核对 `../../../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 消费者。 +- 一期共享模型服务客户认证、企业资料/成员权限和头程订单；修改订单状态、仓库摘要、资质或权限枚举前，先核对阶段契约并搜索 `src/modules/` 全部消费者。 +- 二期仅承接客户可见的到仓与计费结果。`WAIT_SPLIT + APPROVED + CONFIRMED` 为当前终点；内部测量明细、备注和文件权限不得通过共享类型绕过。 +- 三期当前 NO-GO；不得预留分柜、装柜、PDA 或报关字段，待需求阻断解除并冻结契约后再兼容新增。 + +定位规则：从 `src/index.ts` 的导出开始，反查模块 `api`、store 和 `contracts.ts` 消费者；字段含义不明确时回到服务端 DTO/OpenAPI，不在 shared 中扩展业务语义。 阶段文档入口（路径相对本文件所在目录）：一期 `../../../docs/一期/README.md`；二期 `../../../docs/二期/README.md` 与 `../../../docs/二期/二期需求优化版-v2-测量计费入库主流程.md`；三期 `../../../docs/三期/README.md`、`../../../docs/三期/三期开发规划.md` 和 `../../../docs/三期/三期需求确认表.md`。阶段文档优先级高于历史进度表和原型。 diff --git a/src/modules/first-leg/api/unifiedOrders.test.mjs b/src/modules/first-leg/api/unifiedOrders.test.mjs new file mode 100644 index 0000000..ca874ef --- /dev/null +++ b/src/modules/first-leg/api/unifiedOrders.test.mjs @@ -0,0 +1,11 @@ +import assert from 'node:assert/strict' +import { readFileSync } from 'node:fs' +import test from 'node:test' + +const source = readFileSync(new URL('./unifiedOrders.ts', import.meta.url), 'utf8') + +test('keeps the merchant unified-order boundary and phase-two WAIT_SPLIT status', () => { + assert.match(source, /const unifiedOrderBaseUrl = '\/merchant\/v1\/orders'/) + assert.match(source, /ApiUnifiedOrderMainStatus[\s\S]*?'WAIT_SPLIT'/) + assert.match(source, /mainStatus\?: ApiUnifiedOrderMainStatus/) +})