优化

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、分柜、装柜或完整财务应收应付提前实现到客户工作台。

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`。阶段文档优先级高于历史进度表和原型。

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/)
+})