docs: organize contracts by business domain

订单与客户/README.md

@@ -0,0 +1,29 @@
+# 订单与客户文档
+
+订单与客户目标是完成平台后台与企业客户端的真实业务基础，以及头程订单最小闭环。
+
+## 当前主体模型
+
+- 订单与客户及后续未单独启用租户能力的阶段统一按“平台—客户”两级开发，当前是业务单租户、平台管理多客户、客户严格隔离。
+- Java 与接口中的 `tenant_id > 0`、`tenantId` 当前表示客户 ID，是客户隔离兼容字段；`tenant_id=0` 是平台账号和平台 RBAC 的技术作用域，不是可管理租户。
+- 历史表名、类名、接口路径和字段保留 `tenant` 命名，但不得据此新增租户主表、租户选择器、租户级权限或把现有字段改义为上级租户。
+
+## 文档
+
+- [订单与客户开发进度表](订单与客户开发进度表.md)
+- [订单与客户头程订单闭环设计](订单与客户头程订单闭环设计.md)
+- `虫虫出海订单与客户开发进度表.xlsx`：面向团队日常维护的 Excel 进度表。
+
+## 原型来源
+
+- 产品原型统一位于 `docs/悦/`。
+- 企业登录与注册分别参考 `docs/悦/合并/login.html`、`docs/悦/合并/register.html`；订单与客户只默认包含中文账号密码登录和基础企业注册闭环。
+- 快递公司和往来单位参考 `docs/悦/货代SAAS平台后台/货代SaaS平台原型.html` 中“通用”菜单下的对应页面。
+- 原型用于确认信息架构、字段和视觉方向；是否已进入当前 Vue 应用、是否具备完整交互与数据持久化，以订单与客户开发进度表为准。
+
+## 当前边界
+
+- 平台后台：内部账号登录、客户及企业资料审核、内部用户、角色权限、平台收货仓、快递公司、往来单位和头程订单；工作台不作为订单与客户交付项。
+- 企业客户端：中文邮箱/手机号加密码登录、免审核企业注册、企业资料、成员角色权限、头程下单、订单列表和详情；企业资料经平台人工审核通过后才允许提交订单，订单与客户不接短信/邮箱验证码及微信、企业微信登录。
+- 服务端：认证、基于兼容字段 `tenant_id` 的客户隔离、权限、文件、基础资料、订单状态机、幂等和审计。
+- 不包含工作台、部门/组织架构、完整 WMS、FBA/海外目的仓服务、在线报价、财务结算、完整报关清关、外部物流接口、多语言及微信/企业微信登录；快递公司和往来单位订单与客户支持批量导入，不提供导出。

订单与客户/订单与客户头程订单闭环设计.md

@@ -0,0 +1,378 @@
+# 订单与客户头程订单闭环设计
+
+> 状态：产品决策已确认，前端静态闭环实施中  
+> 创建日期：2026-07-28  
+> 适用范围：`apps/client-web`、`apps/admin-web`、`baiyue-firstleg`
+
+> 主体模型：本设计按“平台—客户”两级执行。现有 `tenant_id > 0` / `tenantId` 当前表示客户 ID，是客户隔离兼容字段；`tenant_id=0` 是平台技术作用域。历史命名继续兼容，不在订单与客户引入真实租户层。
+
+## 一、目标
+
+订单与客户形成可验收的最小订单闭环：
+
+1. 企业注册成功后可直接登录，不经过注册审核。
+2. 企业提交资料，由平台人员人工点击审核通过；只有审核通过的企业才可提交头程订单。
+3. 企业客户创建头程订单并保存草稿，提交后平台后台收到待审核任务。
+4. 平台人员审核订单；信息有误时由后台人工修改，或联系客户修改，不设置驳回操作。
+5. 平台人员受理、订舱并更新运输状态，企业客户查看订单详情和处理进度。
+6. 企业客户在允许的状态下取消订单。
+
+本设计先统一业务契约，不预先绑定尚未确认的 Java 框架、数据库、中间件或微服务拆分方式。
+
+## 原型依据与迁移原则
+
+订单与客户原型统一以 `docs/悦/` 为依据。快递公司、往来单位的直接参考页面位于 `docs/悦/货代SAAS平台后台/货代SaaS平台原型.html` 的“通用”菜单：
+
+| 原型页面 | 已有内容 | 订单与客户迁移说明 |
+|---|---|---|
+| 快递公司 | 公司名称、编码、官网、客服电话、合作状态；名称/编码和状态筛选；新增、导入、导出、编辑入口 | 保留核心字段与列表方向；状态统一映射为 `ACTIVE` / `INACTIVE`；订单与客户实现标准模板导入，不实现导出 |
+| 往来单位 | 单位名称、类型、联系人、电话、启停状态；名称、类型和状态筛选；新增、导入、导出、编辑、详情入口 | 补充稳定编码、邮箱和完整地址；类型与客户订单的发货方/收货方角色统一；订单与客户实现标准模板导入，不实现导出 |
+
+现有 HTML 原型已完成菜单、静态列表、演示数据和表格渲染，但多数按钮没有完整的数据提交、校验、失败反馈和持久化流程。因此迁移到 `apps/admin-web`、`apps/client-web` 时，必须按当前项目的 Vue、Pinia、RBAC、响应式和测试约定重新实现，不能把原型存在等同于当前工程已经完成。
+
+原型负责提供信息架构、字段和视觉参考；订单与客户范围、数据隔离、权限和历史快照规则以本设计及开发进度表为准。原型中的 FBA、海外仓、库位、货架、托盘、船期价格和完整 WMS 菜单不因复用同一页面而进入订单与客户。
+
+## 二、订单与客户边界
+
+### 纳入订单与客户
+
+- 客户端：订单列表、组合筛选、创建、编辑草稿、提交、详情、取消。
+- 管理后台：企业资料审核通过、订单列表、详情、待审核订单人工修改、受理、负责人分配和状态更新。
+- 服务端：基于兼容字段 `tenant_id` 的客户隔离、权限校验、状态机、幂等提交、并发控制和操作时间线。
+- 公共契约：订单状态、运输方式、优先级、列表摘要和详情模型。
+- 平台收货仓：后台维护国内收货仓档案和启停状态；客户端新建订单只选择已启用仓库。
+- 快递公司：后台人员统一维护快递公司档案和启停状态；企业客户端不维护，订单详情只读展示履约快递信息。
+- 往来单位：后台人员维护发货单位、收货单位、供应商和服务商；企业客户端只读选择当前可用的发货方和收货方。
+- 货物信息：订单与客户至少支持一条货物明细，并允许同一订单包含多条明细。
+
+### 暂不纳入订单与客户
+
+- 在线询价、自动报价和费率计算。
+- 应收应付、对账、结算和利润核算。
+- 报关、清关、保险和完整单证中心。
+- 船期自动同步、承运商接口和实时物流轨迹。
+- Excel 批量下单、快速下单和复制订单。
+- 客户端批量取消或批量修改。
+- FBA/海外目的仓、库存、库位、货架及入出库等 WMS 作业。
+- 将旧架构文档中的 11 个微服务直接作为订单与客户落地方案。
+
+原型中的 FBA 批量下单、渠道、商检、退税和复杂货物属性作为后续扩展依据，不进入订单与客户最小闭环的必填字段。
+
+## 三、参与者与数据边界
+
+| 参与者 | 数据范围 | 主要操作 |
+|---|---|---|
+| 企业成员 | 当前客户订单 | 查看列表与详情 |
+| 企业订单操作员 | 当前客户订单 | 创建、编辑草稿、提交、取消 |
+| 企业管理员 | 当前客户订单 | 拥有企业端全部订单权限 |
+| 平台运营 | 获授权数据范围内订单 | 审核、人工修改、受理、分配负责人 |
+| 平台操作员 | 获授权数据范围内订单 | 订舱、更新运输状态与处理说明 |
+| 平台超级管理员 | 全部订单 | 平台端全部订单操作 |
+
+服务端必须从已验证身份中取得客户归属上下文。客户端传入的 `tenantId`、`customerId` 或查询参数不能单独作为授权依据；其中 `tenantId` 是客户 ID 的兼容参数名。
+
+企业客户端菜单和操作权限由企业管理员为本企业角色分配。一个成员可拥有多个角色，权限取角色权限并集；订单与客户不引入部门或组织架构，成员直接归属企业。企业管理员不能配置平台后台菜单，也不能跨企业授权。
+
+客户读取、更新、提交和取消订单时，服务端必须同时匹配订单 ID、当前客户 ID（兼容字段 `tenant_id`）和删除标记；不允许先按全局 ID 查出订单后再仅依赖前端隐藏。
+
+平台国内收货仓由后台统一维护，企业客户只读选择。停用仓库不得用于新建或重新提交订单，但不能破坏历史订单已经保存的仓库名称；订单与客户首批覆盖义乌、深圳、青岛、上海、宁波和厦门，不将其与 FBA/海外目的仓混为同一模型。
+
+快递公司和往来单位均由当前平台后台人员维护。企业客户端不提供对应的新增、编辑、启停菜单和写接口：快递公司只通过订单详情展示，往来单位只用于下单时只读查询和选择。服务端必须按后台人员权限和数据范围校验写操作，并按当前企业可见范围过滤客户端往来单位查询，不能依赖前端隐藏按钮实现边界。
+
+## 四、客户订单状态
+
+### 已确认的统一状态
+
+| 稳定编码 | 中文名称 | 含义 |
+|---|---|---|
+| `DRAFT` | 草稿 | 客户尚未提交，可继续编辑 |
+| `PENDING_REVIEW` | 待审核 | 客户已提交，等待平台审核 |
+| `ACCEPTED` | 已受理 | 平台审核通过并进入履约准备 |
+| `BOOKED` | 已订舱 | 已完成舱位或对应运输资源确认 |
+| `IN_TRANSIT` | 运输中 | 货物已进入运输过程 |
+| `COMPLETED` | 已完成 | 客户订单履约结束 |
+| `CANCELLED` | 已取消 | 客户或平台按规则取消 |
+
+该方案与当前管理后台实现最接近。两个前端应用内 `shared/` 现有“处理中”以及旧架构文档中的“已确认、已报关、到港待提”不作为订单与客户并存状态；产品确认后分别迁移。
+
+### 允许的状态转换
+
+```text
+草稿 ──客户提交──> 待审核 ──平台受理──> 已受理 ──平台订舱──> 已订舱
+  │                    │                                      │
+  └──客户取消──> 已取消 ├──后台人工修改/联系客户修改──> 待审核 │
+                       └──客户取消申请/平台取消──> 已取消       └──发运──> 运输中 ──完成──> 已完成
+```
+
+- 草稿可由客户编辑、提交或取消。
+- 待审核订单允许获授权的后台人员人工修改；平台无法直接确认的信息由平台联系客户修改。客户和后台修改后订单仍保持待审核，修改前后值、操作者和时间必须写入审计记录。
+- 已受理后取消可能已经产生成本，订单与客户默认仅平台可执行；客户只能联系平台处理。
+- 已订舱、运输中和已完成不允许客户取消。
+- 已取消和已完成为终态，不允许直接恢复。
+- 所有状态变更必须校验当前状态，不能由前端提交任意目标状态。
+
+## 五、订单与客户数据模型
+
+### 企业资料审核状态
+
+企业账号状态与企业资料审核状态分离：注册成功即可创建账号和登录，不能用禁用账号或注册待审核状态代替下单资格。企业资料至少保存 `verificationStatus`（`UNSUBMITTED`、`PENDING`、`APPROVED`）、`submittedAt`、`approvedAt`、`approvedBy` 和资料版本；只有 `APPROVED` 可提交订单。资料提交、修改和审核通过均写入审计记录。
+
+### 订单主信息
+
+| 字段 | 必填阶段 | 说明 |
+|---|---|---|
+| `id` | 服务端生成 | 内部稳定 ID，不承载客户归属信息 |
+| `orderNo` | 提交时生成 | 客户可见业务单号；客户内和平台范围均应唯一 |
+| `tenantId` | 服务端注入 | 当前表示客户 ID；历史兼容字段，不接受客户指定 |
+| `referenceNo` | 可选 | 客户内部参考号；建议客户内非强制唯一 |
+| `receivingWarehouseId` | 提交必填 | 平台国内收货仓 ID；提交时必须存在且处于启用状态 |
+| `receivingWarehouseName` | 服务端保存 | 下单时仓库名称冗余，兼容列表和旧消费者 |
+| `receivingWarehouseSnapshot` | 服务端保存 | 下单时仓库展示快照，至少包含 ID、编码、名称、省、市和详细地址 |
+| `shipperCounterpartyId` | 可选 | 兼容后台往来单位引用；企业客户端下单不强制选择 |
+| `shipperSnapshot` | 我司提货时提交必填 | 仅取货方式为 `PICKUP` 时保存提货公司、联系人、电话和地址快照；自送快递、自送卡车不要求 |
+| `consigneeCounterpartyId` | 可选 | 兼容后台往来单位引用；企业客户端下单不强制选择 |
+| `consigneeSnapshot` | 私人仓时提交必填 | 仅目的仓类型为 `PRIVATE` 时保存私人收件地址快照；FBA 仓、海外仓使用所选公共仓主数据，不重复填写收件资料 |
+| `deliveryInfo` | 平台维护 | 可选履约信息，包含快递公司 ID/快照和快递单号；企业客户端只读 |
+| `transportMode` | 提交必填 | FCL、LCL、AIR、ROAD |
+| `businessType` | 提交必填 | 订单与客户支持 EXPORT、IMPORT |
+| `origin` | 提交必填 | 起运地或起运港 |
+| `destination` | 提交必填 | 目的地或目的港 |
+| `expectedDepartureDate` | 可选 | 客户期望出发日期，不等同于平台确认 ETD |
+| `etd`、`eta` | 平台维护 | 平台受理后的预计节点 |
+| `priority` | 可选 | NORMAL、URGENT、EXPEDITED，默认 NORMAL |
+| `customerRemark` | 可选 | 客户和平台均可见 |
+| `internalRemark` | 可选 | 仅平台可见，不得返回客户接口 |
+| `operatorId` | 平台维护 | 负责人内部用户 ID |
+| `status` | 服务端维护 | 使用稳定英文编码 |
+| `version` | 服务端维护 | 乐观锁版本，防止覆盖并发修改 |
+| `createdBy`、`createdAt`、`updatedAt` | 服务端维护 | 审计信息 |
+
+订单金额不由客户创建接口提交。订单与客户若后台继续展示金额，应标记为平台估算字段，并在报价/结算范围确认后单独设计。
+
+### 平台收货仓
+
+| 字段 | 说明 |
+|---|---|
+| `id` | 服务端稳定 ID |
+| `code` | 平台内唯一仓库编码，统一大写 |
+| `name` | 客户可见仓库名称 |
+| `province`、`city`、`address` | 国内收货地址 |
+| `contactName`、`contactPhone` | 收货联系信息 |
+| `businessHours` | 收货时间说明 |
+| `status` | `ACTIVE` 或 `INACTIVE` |
+| `remark`、`updatedAt` | 运营说明和更新时间 |
+
+订单只持有仓库 ID 与不可编辑的必要展示快照，不复制联系人、电话、营业时间、运营备注等会持续维护的完整仓库档案。快照字段为 `id`、`code`、`name`、`province`、`city`、`address`；订单详情优先读取快照，不能回查当前仓库主数据覆盖历史值。真实服务端接入后，创建和提交均需重新校验仓库可用性，并在同一事务中持久化快照，不能只依赖客户端下拉选项。
+
+### 快递公司
+
+| 字段 | 说明 |
+|---|---|
+| `id` | 服务端稳定 ID |
+| `code` | 平台内唯一稳定编码 |
+| `name` | 快递公司名称 |
+| `customerServicePhone` | 客服电话，可选 |
+| `trackingUrl` | 官方查询网址，可选 |
+| `status` | `ACTIVE` 或 `INACTIVE` |
+| `remark`、`updatedAt` | 后台说明和更新时间 |
+
+快递公司只能由获授权的后台人员维护。停用后不得新增到订单履约信息，但历史订单继续展示保存的快递公司名称和编码。企业客户端不直接查询快递公司主数据，只通过订单详情响应读取后台已保存的履约信息。订单与客户不接快递轨迹订阅和自动回传；一个订单只支持一组快递公司与快递单号，多包裹和多段运输后续扩展。
+
+### 往来单位
+
+| 字段 | 说明 |
+|---|---|
+| `id` | 服务端稳定 ID |
+| `code` | 所属数据范围内唯一编码 |
+| `name` | 单位名称 |
+| `types` | 可多选的稳定单位类型集合；订单与客户覆盖供应商、客户、承运商、报关行、发货单位和收货单位 |
+| `contactName`、`contactPhone`、`email` | 主要联系人信息 |
+| `country`、`province`、`city`、`postalCode`、`address` | 主要地址信息 |
+| `status` | `ACTIVE` 或 `INACTIVE` |
+| `dataScopeId` | 所属业务数据范围，由服务端维护 |
+| `remark`、`updatedAt` | 后台说明和更新时间 |
+
+往来单位只能由获授权的后台人员维护，企业客户端只读查询当前可见且已启用的发货单位和收货单位。单位类型使用稳定编码，同一单位允许拥有供应商、客户、承运商、报关行、发货单位、收货单位中的多个类型。数据按所属业务主体隔离，后台人员只能在授权范围维护和查看。订单提交时服务端重新校验单位类型、启用状态和数据范围，并保存发货方、收货方快照；主数据后续改名、改地址或停用不得覆盖历史订单。订单内允许调整本单快照，但不得反向修改往来单位档案。
+
+### 基础资料批量导入
+
+订单与客户确认支持后台批量导入快递公司和往来单位，企业客户端不提供导入入口。平台提供版本化的 `.xlsx` 标准模板；后台人员上传后，服务端先完成整批校验，存在任一错误时不写入业务表，并返回包含行号、字段和原因的错误报告。
+
+导入至少校验必填字段、稳定编码、名称、单位类型、联系方式、地址、数据范围和启停值；同一文件内重复、与现有档案重复或越过操作人数据范围的记录必须拒绝，不得静默覆盖已有档案。订单与客户批量导入只新增，不更新或覆盖已有档案；任一记录失败时整批不写入。每次导入记录操作人、原始文件名、总行数、成功/失败数量、失败原因摘要和服务端时间。文件大小和最大行数使用服务端可配置上限；快递公司和往来单位导出不纳入订单与客户。
+
+### 货物明细
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `id` | 服务端生成 | 明细 ID |
+| `lineNo` | 是 | 订单内序号 |
+| `sku` | 否 | 客户 SKU |
+| `cargoNameCn` | 是 | 中文品名 |
+| `cargoNameEn` | 否 | 英文品名 |
+| `pieces` | 是 | 件数，正整数 |
+| `packageCount` | 否 | 箱数/包装数，非负整数 |
+| `grossWeightKg` | 是 | 毛重，必须大于 0 |
+| `volumeCbm` | 是 | 体积，必须大于 0 |
+| `containerType` | FCL 时必填 | 20GP、40GP、40HQ 等 |
+| `containerCount` | FCL 时必填 | 柜量，正整数 |
+| `remark` | 否 | 客户可见备注 |
+
+主表中的总件数、总重量、总体积应由服务端根据明细汇总，不接受客户端独立提交两套可能冲突的合计。
+
+### 时间线
+
+每次提交、待审核订单修改、受理、状态变化、取消和负责人变化均写入不可由客户端编辑的时间线：
+
+- 事件类型和事件标题；
+- 变更前后状态；
+- 操作说明、修改摘要或取消原因；
+- 操作者 ID、名称和操作者类型；
+- 服务端发生时间；
+- 请求关联 ID，便于审计和排错。
+
+## 六、接口草案
+
+统一前缀暂用 `/api/v1`。具体服务拆分不影响浏览器端契约。
+
+### 客户端接口
+
+| 方法 | 路径 | 权限编码 | 说明 |
+|---|---|---|---|
+| `GET` | `/api/v1/client/first-leg-orders` | `order:first-leg:list` | 当前客户订单分页列表 |
+| `POST` | `/api/v1/client/first-leg-orders` | `order:first-leg:create` | 创建草稿 |
+| `GET` | `/api/v1/client/first-leg-orders/{id}` | `order:first-leg:view` | 当前客户订单详情 |
+| `PUT` | `/api/v1/client/first-leg-orders/{id}` | `order:first-leg:update` | 编辑草稿；平台联系客户后可修改本企业待审核订单，状态保持待审核并记录审计 |
+| `POST` | `/api/v1/client/first-leg-orders/{id}/submit` | `order:first-leg:submit` | 幂等提交草稿；提交前强制校验企业资料审核已通过 |
+| `POST` | `/api/v1/client/first-leg-orders/{id}/cancel` | `order:first-leg:cancel` | 按状态规则取消 |
+| `GET` | `/api/v1/client/platform-receiving-warehouses` | 登录用户 | 查询客户端可选择的启用收货仓 |
+| `GET` | `/api/v1/client/counterparties` | 登录用户 | 按当前数据范围只读查询已启用的发货单位和收货单位 |
+| `GET` | `/api/v1/client/me` | 登录用户 | 查询当前成员的用户名、姓名、手机、邮箱、微信和所属公司 |
+| `PUT` | `/api/v1/client/me` | 登录用户 | 更新真实姓名、手机、邮箱和微信；用户名与所属公司不可修改 |
+| `POST` | `/api/v1/client/me/password` | 登录用户 | 校验当前密码后修改密码并记录安全审计 |
+| `GET` | `/api/v1/client/company-profile` | `company:profile:view` | 查询当前企业基本信息、法人信息、联系信息和地址 |
+| `PUT` | `/api/v1/client/company-profile` | `company:profile:write` | 按企业权限更新允许维护的公司信息 |
+| `GET` | `/api/v1/client/company-qualifications` | `company:qualification:view` | 查询资质文件类型、状态、有效期和安全访问地址 |
+| `POST` | `/api/v1/client/company-qualifications` | `company:qualification:write` | 上传或更新企业资质文件 |
+
+### 管理后台接口
+
+| 方法 | 路径 | 权限编码 | 说明 |
+|---|---|---|---|
+| `GET` | `/api/v1/admin/first-leg-orders` | `first-leg:list` | 按平台数据范围查询 |
+| `POST` | `/api/v1/admin/first-leg-orders` | `first-leg:create` | 平台代客创建订单 |
+| `GET` | `/api/v1/admin/first-leg-orders/{id}` | `first-leg:list` | 订单完整详情，含内部信息 |
+| `PUT` | `/api/v1/admin/first-leg-orders/{id}` | `first-leg:update` | 按状态规则维护订单 |
+| `POST` | `/api/v1/admin/first-leg-orders/{id}/accept` | `first-leg:status` | 受理并可分配负责人 |
+| `POST` | `/api/v1/admin/first-leg-orders/{id}/assign` | `first-leg:assign` | 分配负责人 |
+| `POST` | `/api/v1/admin/first-leg-orders/{id}/transition` | `first-leg:status` | 执行服务端允许的后续状态转换 |
+| `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` | 人工点击审核通过并开通下单资格；订单与客户无驳回动作 |
+| `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` | 编辑平台收货仓 |
+| `POST` | `/api/v1/admin/platform-receiving-warehouses/{id}/status` | `warehouse:write` | 启用或停用收货仓 |
+| `GET` | `/api/v1/admin/express-companies` | `express-company:list` | 分页查询快递公司 |
+| `POST` | `/api/v1/admin/express-companies` | `express-company:write` | 新增快递公司 |
+| `PUT` | `/api/v1/admin/express-companies/{id}` | `express-company:write` | 编辑快递公司 |
+| `POST` | `/api/v1/admin/express-companies/{id}/status` | `express-company:write` | 启用或停用快递公司 |
+| `POST` | `/api/v1/admin/express-companies/import` | `express-company:import` | 使用标准模板批量导入快递公司，整批校验后提交 |
+| `GET` | `/api/v1/admin/counterparties` | `counterparty:list` | 按授权数据范围分页查询往来单位 |
+| `POST` | `/api/v1/admin/counterparties` | `counterparty:write` | 在授权数据范围内新增往来单位 |
+| `PUT` | `/api/v1/admin/counterparties/{id}` | `counterparty:write` | 编辑往来单位 |
+| `POST` | `/api/v1/admin/counterparties/{id}/status` | `counterparty:write` | 启用或停用往来单位 |
+| `POST` | `/api/v1/admin/counterparties/import` | `counterparty:import` | 在授权数据范围内使用标准模板批量导入往来单位 |
+| `PUT` | `/api/v1/admin/first-leg-orders/{id}/delivery-info` | `first-leg:update` | 后台维护快递公司和快递单号 |
+
+订单与客户不使用通用的“传任意目标状态”接口替代状态动作。服务端根据当前状态、动作、操作者和权限决定目标状态。
+
+### 请求一致性
+
+- 创建和提交接口接受 `Idempotency-Key`，服务端按客户、用户、接口和键去重。
+- 更新请求携带 `version`；版本不一致返回冲突，不静默覆盖。
+- 提交和状态动作在同一事务内更新订单、版本和时间线。
+- 分页参数统一为 `page`、`pageSize`，并设置服务端最大页容量。
+- API 响应继续采用仓库已有 `ApiResponse<T>` 外层结构；错误码需在后端设计时统一补充。
+
+## 七、页面范围
+
+### 我的信息
+
+按客户端原型提供“基本信息”和“修改密码”两个页签。基本信息展示用户名、真实姓名、手机号、邮箱、微信和所属公司，支持进入编辑、保存与取消；用户名和所属公司始终只读，真实姓名、手机号、邮箱和微信允许按权限编辑。修改密码要求当前密码、新密码和确认密码，覆盖强度校验、两次输入不一致、错误反馈、重复提交防护及成功后的会话处理。
+
+### 公司信息
+
+按客户端原型提供“企业基本信息、联系信息、资质文件”三个页签。基本信息覆盖公司名称、统一信用代码、企业类型、注册地、成立日期、注册资本、法人姓名和法人电话；联系信息覆盖联系人、手机、邮箱、微信和地址；资质文件展示文件类型、验证状态、有效期、上传时间，并支持查看、下载及获授权用户更新。企业数据只能读取当前企业，服务端根据企业角色控制可编辑字段和资质操作。注册不审核；企业资料未审核通过时可继续登录、查看和补充资料，但创建页必须显示下单资格提示，提交订单接口必须拒绝并返回可识别错误码。
+
+### 客户工作台
+
+订单列表包含订单号、参考号、运输方式、起运地、目的地、状态、负责人、预计时间和更新时间；支持关键词、状态、运输方式和创建日期筛选。
+
+创建页按以下顺序组织：
+
+1. 运输信息和平台收货仓；
+2. 从后台维护的往来单位中选择发货方和收货方；
+3. 货物明细；
+4. 客户备注；
+5. 保存草稿或提交审核；提交前校验企业资料已经平台人工审核通过。
+
+详情页展示订单摘要、发货方/收货方快照、货物明细、服务端时间线、履约快递公司、快递单号和当前可用操作。内部备注、成本和平台内部操作信息不得进入客户响应；企业客户端不能修改快递信息或往来单位档案。
+
+### 管理后台
+
+新增企业资料审核、平台收货仓、快递公司和往来单位管理。企业资料审核只有“审核通过”，资料不正确时由平台联系客户修改；基础资料页面支持列表筛选、新增、编辑和启停，并由 RBAC 与数据范围控制。快递公司、往来单位页面沿用 `docs/悦` 原型的信息层级和主要字段，但使用当前后台视觉体系和交互组件重新实现；订单与客户实现标准模板下载、文件上传、校验结果和错误报告，不提供导出入口。保留当前订单列表和详情方向，将自由状态下拉改为服务端返回的可用动作；补充待审核订单人工修改、受理、分配、订舱、发运、完成、取消和履约快递信息维护动作，不提供驳回入口。
+
+## 八、测试与验收
+
+- 客户 A 无法读取、更新、提交或取消客户 B 的订单。
+- 草稿可以反复保存，提交请求重复发送只产生一次状态变化。
+- 待审核订单仅允许当前企业获授权成员或获授权平台人员修改核心业务字段，修改后状态保持待审核且必须完整留痕；其他非草稿状态禁止修改。
+- 服务端拒绝非法状态跳转和缺少权限的状态动作。
+- 并发修改返回明确冲突，客户端保留用户输入并支持重新加载。
+- 客户接口永不返回内部备注、成本或不必要的人员信息。
+- 列表覆盖加载、空数据、失败、无权限和分页边界。
+- 创建页覆盖校验错误、提交中、重复点击、失败恢复和离开未保存提示。
+- 管理后台覆盖待审核订单人工修改、联系客户修改后的并发冲突、受理、负责人失效及状态变更失败，并确认无驳回入口和接口。
+- 仓库编码必须唯一；停用仓库不出现在客户新建订单选项中，仓库改名、改地址或停用后，历史订单仍展示下单时的编码、名称和地址快照。
+- 企业客户端无法调用快递公司或往来单位写接口，也不显示维护入口；伪造请求必须由服务端拒绝。
+- 往来单位查询只返回当前企业可见且已启用的发货单位和收货单位；跨数据范围 ID 在保存草稿和提交时均被拒绝。
+- 往来单位改名、改地址或停用后，历史订单继续展示下单时快照；停用单位不能用于新订单提交。
+- 快递公司编码和名称满足唯一规则；停用公司不能新增到履约信息，历史订单继续展示已保存快照。
+- 客户端订单详情只读展示快递公司和快递单号，接口不得接受客户修改履约快递信息。
+- 我的信息只能读取当前登录成员；修改所属公司或其他成员资料的伪造请求必须拒绝，修改密码必须校验当前密码并写入安全审计。
+- 注册成功后无需审核即可登录；公司信息只返回当前企业数据，未通过企业资料审核时服务端拒绝提交订单，审核通过后允许提交。普通成员无写权限时仍可按授权查看，资质文件下载使用受控地址并覆盖过期、缺失、上传失败和无权限状态。
+- 快递公司和往来单位批量导入仅允许具备对应导入权限的后台人员调用；企业客户端和普通写权限不能绕过独立导入权限。
+- 导入文件覆盖模板版本、空文件、超限文件、缺列、类型错误、重复编码、跨数据范围和恶意文件名；任一行失败时业务数据不发生部分写入，并可下载逐行错误报告。
+
+## 九、实施顺序
+
+1. 将已确认的注册、企业资料审核、订单修改和基础资料规则冻结为接口契约。
+2. 以 Java Controller、DTO 和 OpenAPI 为跨端契约来源，在 Admin、Client 各自应用内 `shared/` 和 API 适配层维护前端映射。
+3. 在 `baiyue-firstleg` 定义企业资料审核、订单、收货仓、快递公司和往来单位接口，并以服务端状态机和权限校验作为唯一业务规则来源。
+4. 实现后台基础资料维护、快递公司/往来单位批量导入和企业客户端往来单位只读查询。
+5. 实现客户工作台订单列表、创建和详情页面，静态阶段通过 API 适配层提供可替换数据源。
+6. 将管理后台订单 Pinia 模拟操作迁移到同一 API 契约，并接入履约快递信息。
+7. 增加跨客户拒绝、状态机、幂等、基础资料越权和前端业务流程测试。
+
+## 十、已确认实施决策
+
+以下决策于 2026-07-28 至 2026-07-29 确认：
+
+1. 采用“草稿、待审核、已受理、已订舱、运输中、已完成、已取消”七个订单与客户状态，不设置“已驳回”。
+2. 待审核订单无驳回操作；信息有误时由后台人工修改，或由平台联系客户修改，订单保持待审核并完整记录修改审计。
+3. 已受理后客户不能直接取消，订单与客户由客户联系平台并由平台执行取消。
+4. 保留平台代客户创建订单的能力。
+5. 订单与客户使用本设计的精简必填字段；FBA 批量下单、渠道、商检和退税后续扩展。
+6. 快递公司和往来单位均由当前平台后台人员维护；企业客户端不提供维护入口和写接口，仅按权限只读使用。
+7. 订单与客户包含快递公司、往来单位标准模板批量导入，不包含对应导出功能。
+8. 订单与客户客户端包含我的信息和公司信息，范围以 `docs/悦/头程下单/柏悦客户端.html` 原型为基准并接入真实权限与接口。
+9. 企业注册不需要审核，注册成功即可登录；提交订单前必须提交企业资料并由平台人工点击审核通过。
+10. 订单与客户支持一个用户拥有多个角色，权限取角色权限并集。
+11. 往来单位按所属业务主体隔离并支持一个单位拥有多个稳定编码类型；订单与客户类型覆盖供应商、客户、承运商、报关行、发货单位和收货单位。
+12. 一个订单订单与客户只支持一组快递公司和快递单号。
+13. 快递公司、往来单位批量导入订单与客户只新增，不更新或覆盖已有档案；重复或任一行错误时整批失败。
+14. “我的信息”中的用户名只读，不允许修改。
+15. 企业客户端菜单和操作权限由企业管理员为本企业角色分配，订单与客户不做部门/组织架构。
+16. 企业注册订单与客户不接短信或邮箱验证码，只做基础字段、密码和账号重复校验。
+17. 订单与客户仅支持中文账号密码登录，不做多语言、微信和企业微信登录。

订单与客户/订单与客户开发进度表.md

@@ -0,0 +1,330 @@
+# 虫虫出海订单与客户开发进度表
+
+> 创建日期：2026-07-27
+> 更新日期：2026-08-03
+> 当前阶段：订单与客户功能基本完成，进入测试环境部署、业务样本补齐和验收收口。双端核心页面已接真实 API；后端 19 个 Reactor 模块、169 项测试及本地真实接口回归已通过。2026-08-03 最新门禁中，Client 99 项测试和双端生产构建通过，Admin 129 项测试中 122 项通过、7 项失败，需先修正企业审核标识映射及其余页面断言后再做最终验收
+> 总体状态：收口中（暂不标记订单与客户完成）
+
+> 主体模型：当前只实现“平台—客户”两级；`tenant_id > 0` 是客户 ID 兼容字段，`tenant_id=0` 是平台技术作用域。进度项中的历史 `tenant` 命名不得解释为真实租户层。
+
+头程订单订单与客户闭环范围与接口草案见 `订单与客户头程订单闭环设计.md`。
+
+## 原型依据与进度口径
+
+- 订单与客户产品原型统一以 `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 菜单不自动纳入订单与客户。
+
+## 一、订单与客户目标
+
+订单与客户完成两个端的基础业务闭环：
+
+- 平台后台：内部账号登录、客户与企业资料审核、内部用户、角色、权限和头程订单管理；工作台不作为订单与客户交付项。
+- 企业客户端：用户名加密码登录、免审核企业注册、企业资料、企业成员、角色、菜单及权限管理；企业资料审核通过后才可提交订单。
+- 头程订单：提供客户端下单和订单查询能力，形成前后台业务闭环。
+- 平台收货仓：平台统一维护国内收货仓，客户端下单时选择已启用仓库并保存仓库 ID、编码、名称和地址快照。
+- 快递公司：当前平台后台人员统一维护快递公司档案，企业客户端不维护；订单履约时记录快递公司与快递单号。
+- 往来单位：当前平台后台人员维护发货单位、收货单位、供应商和服务商，企业客户端只读选择并在头程订单中保存快照。
+
+订单与客户基础资料范围包括平台收货仓、快递公司和往来单位。仓库能力限定为义乌、深圳、青岛、上海、宁波、厦门等国内收货仓的档案、启停、查询和订单关联，不包含 FBA/海外目的仓、库存、库位、货架、入库、出库、盘点等 WMS 作业；快递能力不包含轨迹订阅和自动回传。
+
+权限边界暂按以下模型设计：
+
+- 平台后台 RBAC：平台内部员工使用，管理所有企业和订单。
+- 企业客户端 RBAC：企业管理员使用，只管理本企业的成员、角色和权限。
+- 企业之间按 `tenant_id` 隔离，客户端用户不能访问其他企业数据。
+- 快递公司和往来单位的新增、编辑、启停仅开放给获授权的后台人员；企业客户端不提供维护入口和写接口。
+
+## 二、总体进度
+
+| 模块 | 范围 | 状态 | 进度 | 计划开始 | 计划完成 | 负责人 | 备注 |
+|---|---|---|---:|---|---|---|---|
+| 基础工程 | 前后端工程、数据库、环境、接口规范 | 测试中 | 92% | 2026-07-27 | 待排期 | 待分配 | 双端工程、Gateway、认证、统一响应、数据库脚本和 OpenAPI 基础已完成；待测试环境迁移、配置发布和部署核验 |
+| 后台客户管理 | 客户档案、企业资料审核、启停和资料维护 | 测试中 | 88% | 2026-07-27 | 待排期 | 待分配 | 客户档案、资质和审核已接真实 API；当前 Admin 测试暴露审核记录 `reviewId`/租户字段映射风险，修复后需用待审/驳回样本验收 |
+| 后台管理 | 内部用户、角色、权限 | 测试中 | 93% | 2026-07-27 | 待排期 | 待分配 | 内部用户完整生命周期、角色权限回显与保存、权限资源维护均已接真实 API；待受限账号、停用权限即时生效和跨客户 403 验收 |
+| 后台头程订单 | 订单列表、详情、审核、受理、处理、完成、取消及履约信息 | 测试中 | 93% | 2026-07-27 | 待排期 | 待分配 | 订单状态流转、内部备注及快递信息已接真实 API；待准备完整状态与快递有值样本完成浏览器验收 |
+| 平台收货仓 | 平台维护国内收货仓；客户端选择启用仓库 | 测试中 | 92% | 2026-07-28 | 待排期 | 待分配 | 后台增改查和启停、客户端选择、详情及订单快照均已接真实 API；待测试环境初始化启用仓库并验收停用与历史引用 |
+| 快递公司维护 | 平台后台维护快递公司档案、启停及订单履约信息关联 | 测试中 | 90% | 2026-07-28 | 待排期 | 待分配 | 后台分页、详情、新增、编辑、启停和订单履约快递已接真实 API；批量导入后端解析接口尚未形成最终验收证据 |
+| 往来单位维护 | 平台后台维护往来单位档案、启停及订单引用 | 测试中 | 92% | 2026-07-28 | 待排期 | 待分配 | 后台增改查和启停、客户端真实候选及订单快照已接真实 API；批量导入及多类型测试样本仍待最终验收 |
+| 登录注册与客户入驻 | Admin 登录、企业端注册、个人与企业资料及企业审核 | 测试中 | 92% | 2026-07-27 | 待排期 | 待分配 | 登录注册、令牌轮换、个人/企业资料、资质上传与鉴权预览均已接真实 API；待五种企业状态和文件存储部署验收 |
+| 客户端权限体系 | 企业成员、菜单、角色、权限 | 测试中 | 95% | 2026-07-28 | 待排期 | 待分配 | 成员完整维护、角色增改启停删除、权限回显与全量保存均已接真实 API；Client 相关自动化测试通过，待普通成员和越权场景验收 |
+| 客户端头程订单 | 下单、列表、详情、平台收货仓及往来单位选择 | 测试中 | 94% | 2026-07-28 | 待排期 | 待分配 | 草稿、编辑、提交、列表、详情、幂等、仓库与往来单位快照均已接真实 API；待有效主数据和完整状态样本完成浏览器闭环验收 |
+| 联调与上线 | 测试、验收、部署、初始化数据 | 进行中 | 65% | 2026-07-30 | 待排期 | 待分配 | 本地后端真实接口回归、Client 99 项测试和双端构建已通过；Admin 尚有 7 项测试失败，测试环境迁移、部署及业务验收未完成 |
+
+## 三、详细任务表
+
+| ID | 端 | 模块 | 功能/交付内容 | 优先级 | 状态 | 进度 | 依赖 | 负责人 | 备注 |
+|---|---|---|---|---|---|---:|---|---|---|
+| BASE-01 | 公共 | 工程初始化 | 创建后台前端、客户端前端和后端工程，区分开发/测试/生产环境 | P0 | 进行中 | 70% | - | 待分配 | admin/client 已独立安装与构建，API 工程待初始化 |
+| 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；同步企业资料审核、下单资格、仓库、快递公司、往来单位与订单快照契约 |
+| 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 文件预览、通过与驳回接口；待使用真实待审记录验证完整写操作 |
+| ADM-USER-01 | 后台 | 内部用户 | 用户列表、搜索、分页和详情 | P0 | 进行中 | 70% | BASE-03 | 待分配 | 前端列表、筛选和分页已完成 |
+| ADM-USER-02 | 后台 | 内部用户 | 新增、编辑、启停、重置密码 | P0 | 进行中 | 65% | ADM-USER-01 | 待分配 | 前端交互已完成，操作日志与接口待接入 |
+| ADM-USER-03 | 后台 | 内部用户 | 给用户分配一个或多个角色 | P0 | 进行中 | 75% | ADM-ROLE-01 | 待分配 | 多角色选择与回显已完成 |
+| ADM-ROLE-01 | 后台 | 角色 | 角色列表、新增、编辑、删除、启停 | P0 | 联调中 | 92% | BASE-03 | 待分配 | 已按后端 `RbacController` 接入角色查询、新增、编辑、启停、删除、权限回显及全量保存；待准备自定义角色样本完成真实写操作验收 |
+| ADM-ROLE-02 | 后台 | 角色 | 给角色分配菜单和操作权限 | P0 | 已阻塞 | 75% | ADM-PERM-01 | 待分配 | 写接口是全量替换，但缺少角色当前 `permissionIds` 回显；真实会话暂不开放保存，避免清空已有授权 |
+| ADM-PERM-01 | 后台 | 权限 | 菜单树、页面权限、按钮权限和接口权限模型 | P0 | 联调中 | 88% | BASE-02 | 待分配 | `GET/POST /api/platform/v1/iam/permissions` 已接入；真实模式只创建 `MENU/BUTTON`，编辑和启停接口待补 |
+| ADM-PERM-02 | 后台 | 权限 | 登录后返回当前用户菜单和权限集合 | P0 | 联调中 | 80% | ADM-PERM-01 | 待分配 | 已接 `/api/platform/v1/iam/authorization/permissions` 当前用户启用权限快照，并与 JWT 权限取交集；待 Gateway 恢复后复验权限变更后的 Token 刷新 |
+| ADM-PERM-03 | 后台 | 权限 | 未授权页面、按钮隐藏和接口拒绝访问 | P0 | 联调中 | 65% | ADM-PERM-02 | 待分配 | 前端路由、菜单和主要按钮已按稳定权限码控制；后端文档确认方法级按钮权限尚未覆盖所有管理接口 |
+| ADM-ORDER-01 | 后台 | 头程订单 | 订单列表、组合查询、分页和导出 | P0 | 进行中 | 70% | BASE-03 | 待分配 | 前端组合筛选、分页、选择与导出反馈已完成 |
+| ADM-ORDER-02 | 后台 | 头程订单 | 订单详情、货物、收发货和平台收货仓信息 | P0 | 进行中 | 75% | ADM-ORDER-01 | 待分配 | 前端详情按下单时仓库快照展示；API 与数据库持久化待接入 |
+| ADM-ORDER-03 | 后台 | 头程订单 | 订单审核、人工修改、受理、取消和状态流转 | P0 | 进行中 | 80% | ADM-ORDER-02 | 待分配 | Vue 已删除订单驳回状态/动作；后台修改待审核订单后仍保持待审核并自动追加审计记录，联系客户修改不改变状态；等待业务 API |
+| ADM-ORDER-04 | 后台 | 头程订单 | 订单指派、内部备注和操作记录 | P1 | 进行中 | 65% | ADM-ORDER-03 | 待分配 | 负责人、处理说明和时间线前端已完成 |
+| 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-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 维护、权限控制、编码/名称不区分大小写唯一校验和历史引用提示完成；服务端校验待接入 |
+| ADM-EXP-03 | 后台 | 快递公司 | 使用标准模板批量导入快递公司档案 | P1 | 进行中 | 60% | ADM-EXP-02、BASE-04 | 待分配 | 标准 XLSX 下载、文件选择、扩展名和大小检查已完成；工作表解析、模板版本、重复校验、整批事务及错误报告均由后端负责，等待导入 API |
+| ADM-CP-01 | 后台 | 往来单位 | 往来单位列表、关键词搜索、按单位类型/状态筛选及详情 | P0 | 进行中 | 80% | BASE-03、MD-BASE-01 | 待分配 | Vue 列表、关键词/六类角色/状态筛选、详情和空态完成；原型核对与 Vue 实现分别统计 |
+| ADM-CP-02 | 后台 | 往来单位 | 后台人员新增、编辑、启用和停用；维护单位编码、名称和类型 | P0 | 进行中 | 80% | ADM-CP-01 | 待分配 | Vue 新增/编辑/启停、多类型和编码唯一校验完成；企业客户端无维护入口，服务端数据范围待接入 |
+| ADM-CP-03 | 后台 | 往来单位 | 维护联系人、电话、邮箱、国家/地区、州省、城市、邮编和详细地址 | P0 | 进行中 | 80% | ADM-CP-02 | 待分配 | Vue 联系人与完整地址字段、邮箱格式和必填校验完成；订单快照 API 待接入 |
+| ADM-CP-04 | 后台 | 往来单位 | 使用标准模板批量导入往来单位档案 | P1 | 进行中 | 60% | ADM-CP-03、BASE-04 | 待分配 | 标准 XLSX、六类多值说明、文件类型和大小检查已完成；解析、数据范围、整批失败和错误报告由后端返回，等待导入 API |
+| CLI-AUTH-01 | 客户端 | 登录认证 | 按后端契约实现用户名密码登录、记住我、登录反馈及登录/注册互跳 | P0 | 联调中 | 85% | BASE-03 | 待分配 | 已接 `/api/auth/login|refresh|logout`、Token 轮换、MERCHANT JWT 和会话恢复；Gateway 在线但登录转发 503，待路由恢复后验证错误码与过期刷新 |
+| CLI-REG-01 | 客户端 | 注册 | 按后端契约维护用户名、8–72 位密码、企业、联系人、法人、手机、邮箱、国家和地址 | P0 | 联调中 | 85% | BASE-03 | 待分配 | 已按 DTO 补齐全部字段并接 `/api/auth/register`；Gateway/Auth 环境不稳定，待恢复后验证重复用户名与 422 字段错误 |
+| CLI-REG-02 | 客户端 | 注册 | 完成基础格式校验、协议确认、免审核注册成功反馈和登录互跳 | P0 | 联调中 | 90% | CLI-REG-01 | 待分配 | 注册成功跳登录并带入用户名，账号与企业资料审核状态分离；待 Gateway 真实验收 |
+| ADM-CUSTOMER-03 | 后台 | 企业资料审核 | 企业资料待审核列表、详情和人工审核通过操作 | P0 | 联调中 | 85% | ADM-CUSTOMER-02、CLI-PROFILE-02 | 待分配 | 已接待审列表、`/tenants/{tenantId}/qualifications`、平台资质文件二进制接口及真实审核动作；文件不再使用无 Token 直链，待审样本写操作仍待人工验收 |
+| 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-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 全量保存角色；待浏览器执行一次真实写入验收 |
+| CLI-MENU-01 | 客户端 | 菜单分配 | 企业管理员为本企业角色分配客户端菜单和操作权限 | P0 | 进行中 | 60% | CLI-ROLE-01 | 待分配 | 已确认操作人为企业管理员；分组选择交互已完成，动态菜单生成与平台菜单隔离需由服务端契约保证 |
+| CLI-PERM-01 | 客户端 | 权限 | 页面、按钮和接口权限定义及角色授权 | P0 | 联调中 | 90% | CLI-MENU-01 | 待分配 | 角色 permissionIds 与启用权限资源已映射回显；非内置启用角色可全量保存权限，待准备自定义角色完成浏览器写入验收 |
+| CLI-PERM-02 | 客户端 | 权限 | 按当前成员权限生成菜单并执行接口鉴权 | P0 | 进行中 | 55% | CLI-PERM-01 | 待分配 | 已完成演示账号权限集合、动态菜单、路由 403、首个可访问页面、会话恢复和按钮权限预览；服务端仍必须校验 `tenant_id` 与权限 |
+| CLI-CP-01 | 客户端 | 往来单位查询 | 只读查询当前可用的发货单位和收货单位，支持关键词和类型筛选 | P0 | 联调中 | 90% | ADM-CP-03、BASE-03 | 待分配 | 已接 `/api/merchant/v1/partners/candidates`；后端类型修正为 `CUSTOMER / SUPPLIER / BOTH`，一次读取启用候选并同时供订单发货方/收货方选择，无维护入口且不回退演示数据 |
+| CLI-WH-01 | 客户端 | 平台收货仓选择 | 查询已启用仓库，展示名称、地址和收货时间 | P0 | 测试中 | 95% | WH-BASE-01、ADM-WH-02 | 待分配 | 浏览器已读取 1 条真实启用仓库，选择后成功加载深圳地址和每日 16:00 截单时间；历史订单引用失效仓库时要求重新选择，不回退模拟仓库 |
+| CLI-ORDER-01 | 客户端 | 头程订单 | 新建头程订单、保存草稿和提交；提交前校验企业资料审核状态 | P0 | 联调中 | 92% | BASE-03、ADM-CUSTOMER-03 | 待分配 | 企业审核状态改为进入订单页时真实加载；创建/编辑/提交契约、幂等键和权限映射已接。为避免污染联调数据，本轮只读验收未执行保存和提交 |
+| 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 待新架构确认 |
+| 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 | 待分配 | 形成验收清单 |
+
+## 四、建议里程碑
+
+| 里程碑 | 交付目标 | 状态 | 计划完成 |
+|---|---|---|---|
+| M1 基础工程 | 工程、数据库、登录认证、通用能力可用 | 待排期 | 待排期 |
+| M2 后台权限 | 内部用户、角色、权限完整可用 | 进行中 | 待排期 |
+| M3 企业入驻 | 免审核注册、企业资料人工审核、下单资格和企业成员可用 | 进行中 | 待排期 |
+| M4 企业权限 | 客户端角色、菜单和权限完整可用 | 进行中 | 待排期 |
+| M5 基础资料主数据 | 后台可维护平台收货仓、快递公司、往来单位；客户端只读查询并受数据范围控制 | 进行中 | 待排期 |
+| M6 订单闭环 | 客户选择收货仓和往来单位提交订单，后台维护履约信息，历史展示稳定 | 进行中 | 待排期 |
+| M7 订单与客户上线 | 联调、测试、验收和生产发布完成 | 待排期 | 待排期 |
+
+## 五、产品决策与待确认事项
+
+### 已确认决策
+
+| 编号 | 决策 | 结论 |
+|---|---|---|
+| Q1 | 客户端订单与客户是否包含头程下单、订单列表和详情？ | 包含，作为订单与客户前后台订单闭环的必要范围 |
+| Q2 | 企业注册与企业资料审核关系 | 注册无需审核，成功后即可登录；提交订单前必须提交企业资料并由平台人工点击审核通过 |
+| Q3 | 客户端“菜单分配”的操作人 | 企业管理员为本企业角色分配菜单和操作权限，不能管理其他企业或平台后台菜单 |
+| Q4 | 一个用户能否拥有多个角色？ | 订单与客户支持多角色，服务端按角色权限并集授权 |
+| Q5 | 企业注册是否使用短信或邮箱验证码？ | 订单与客户不接验证码，仅做必填、格式、密码强度和账号重复校验 |
+| Q6 | 头程订单订单与客户状态 | 草稿、待审核、已受理、已订舱、运输中、已完成、已取消；不设置已驳回状态 |
+| Q7 | 是否需要部门/组织架构？ | 订单与客户不纳入，成员直接关联企业并通过角色授权 |
+| Q8 | 订单与客户仓库范围与维护方 | 平台后台统一维护国内收货仓，客户端只读选择启用仓库；FBA/海外目的仓不纳入本次 |
+| Q9 | 仓库停用后的订单处理 | 禁止新单选择；历史订单继续展示下单时仓库编码、名称和地址快照 |
+| Q10 | 快递公司和往来单位维护方 | 均由当前平台后台人员维护；企业客户端无维护入口和写接口，仅可按权限查询、选择和查看 |
+| Q11 | 往来单位的数据范围 | 按所属业务主体隔离，平台人员仅在授权数据范围内维护和查看 |
+| Q12 | 往来单位订单与客户类型 | 使用稳定编码并支持一个单位多选类型；订单与客户覆盖供应商、客户、承运商、报关行、发货单位和收货单位 |
+| Q13 | 一个订单支持几组快递公司和快递单号？ | 订单与客户只支持一组履约快递信息；多包裹、多段运输后续扩展 |
+| Q15 | Admin 工作台是否纳入订单与客户？ | 不纳入订单与客户交付与验收；订单与客户先完成简单登录、企业资料审核、权限、基础资料和订单闭环 |
+| Q14 | 快递公司、往来单位批量导入是否纳入订单与客户？ | 已确认纳入订单与客户，均由获授权的后台人员使用标准模板导入 |
+| Q16 | 多语言、微信和企业微信登录是否纳入订单与客户？ | 不纳入；订单与客户仅交付中文账号密码登录，第三方登录后续单独排期 |
+| Q17 | 快递公司、往来单位导出是否纳入订单与客户？ | 不纳入；订单与客户仅实现标准模板批量导入 |
+| Q18 | 订单与客户客户端是否包含我的信息和公司信息？ | 已确认包含；按现有客户端原型覆盖个人资料编辑、修改密码、企业基本/联系信息和资质文件查看维护 |
+| Q19 | 待审核订单信息不正确时如何处理？ | 订单与客户无驳回操作；后台可人工修改，不能直接确认时联系客户修改，订单保持待审核并记录修改审计 |
+| Q20 | 批量导入是否更新已有档案？ | 订单与客户仅新增；重复编码或唯一键冲突时整批失败，不覆盖已有档案 |
+| Q21 | “我的信息”中的用户名能否修改？ | 用户名只读，不允许修改 |
+
+### 待确认事项
+
+| 编号 | 待确认问题 | 当前建议 |
+|---|---|---|
+| Q22 | 企业资料审核通过需要哪些必填资料？ | 待产品给出字段和资质文件清单；在确认前按现有公司信息与营业执照能力保持可配置校验 |
+| Q23 | 审核通过后修改哪些关键资料需要重新审核？ | 建议公司名称、统一信用代码、营业执照等关键资料变更后回到待审核；联系人等普通信息不触发 |
+| Q24 | 企业资料未审核通过时允许进行到哪一步？ | 当前实现允许保存订单草稿但禁止提交；是否连新建订单也禁止仍需产品确认 |
+
+## 六、状态维护规则
+
+- 状态统一使用：待确认、待开始、进行中、联调中、测试中、已完成、已阻塞。
+- 开始开发时填写负责人、计划日期并将状态改为“进行中”。
+- 提交测试时更新为“测试中”，测试通过并验收后才更新为“已完成”。
+- 出现阻塞时在备注中写明阻塞原因、责任人和预计解除时间。
+
+## 七、后台前端阶段验收（2026-07-27）
+
+| 验收项 | 结果 | 证据/说明 |
+|---|---|---|
+| 客户管理 | 通过（静态，待调整） | 列表、筛选、分页、新增/编辑、详情和启停已完成；原注册审核交互需改为企业资料审核通过 |
+| Admin 登录 | 通过（静态） | 登录必填/失败反馈、退出确认、安全回跳、403 路由及按角色首个业务页落地已完成；订单与客户工作台入口已移除，真实 Token 与会话失效处理待接入 |
+| 内部用户 | 通过 | 列表、筛选、新增/编辑、多角色、重置密码、启停及管理员保护 |
+| 角色管理 | 通过 | 新增/编辑/删除/启停、权限树、数据范围及内置角色保护 |
+| 权限管理 | 通过 | 目录/菜单/按钮/接口资源树、上下级维护、状态与唯一编码校验 |
+| 头程订单 | 通过 | 创建/编辑、草稿/提交、详情、时间线、单笔/批量处理、指派与导出反馈 |
+| 响应式与可访问性 | 通过 | 桌面与 390px 手机视口实测；菜单可收起，表格可滚动，关键触控区 44px |
+| 自动化测试 | 通过 | `apps/admin-web` 执行 `pnpm test`，21 个测试文件、148 项通过，覆盖企业审核、租户资质鉴权预览、平台角色/权限 IAM 路径、错误追踪信息、导入边界、真实列表/失败态、登录安全回跳及开发账号环境隔离 |
+| TypeScript 类型检查 | 通过 | `pnpm typecheck` |
+| 生产构建 | 通过 | `pnpm build`，输出至 `apps/admin-web/dist`；产物扫描确认不包含平台联调账号、密码和开发提示 |
+| impeccable 样式检测 | 通过（已修复告警） | 修复字体栈以及 width/margin 布局动画；保留既有后台视觉体系 |
+
+> 客户档案、内部用户和基础资料仍使用 Pinia 模拟数据；企业审核、平台角色、菜单及按钮权限资源已切换到真实 IAM 接口。后台前端阶段完成不等于订单与客户业务完成，仍需后端数据、真实 RBAC 鉴权、联调和测试后才能标记“已完成”。
+
+### Admin 认证联调记录（2026-07-29）
+
+- 前端已统一通过 Gateway 前缀调用 `/api/auth/**` 和 `/api/platform/v1/iam/**`，本地 Vite 使用 `/api` 代理，不拼接 Nacos 服务名或服务直连端口。
+- 已实现 Access/Refresh Token 持久化、PLATFORM 身份域校验、刷新令牌轮换、并发 401 单次刷新、服务端退出调用，以及 JWT 权限与 IAM 启用资源交集。
+- `192.168.110.149:9000` Gateway 的 Auth、IAM、头程订单和仓库路由已恢复并完成基础连通验证；企业审核列表当前返回空数组。
+- 企业审核已新增独立路由 `/customers/reviews`，权限为 `platform:customer:review`，通过/驳回分别校验 `platform:customer:approve` 与 `platform:customer:reject`，提交参数使用审核接口返回的 `reviewId`。
+- `file-service:9206` 当前拒绝连接；IAM Swagger/OpenAPI 当前返回 500，审核 DTO 的可选展示字段仍以真实返回为准。前端不增加服务直连或模拟数据静默回退。
+
+### Admin 平台角色与权限联调记录（2026-07-30）
+
+- 已接入 `GET/POST /api/platform/v1/iam/roles`，真实会话使用 IAM 角色列表，新增角色使用后端返回的真实角色记录。
+- 新增角色按钮严格使用 `platform:role:create`；角色编辑、删除、启停接口未在最新联调文档中提供，真实会话中不展示这些模拟操作。
+- 角色权限写接口是全量替换，但联调文档没有角色当前 `permissionIds` 回显。为避免覆盖已有授权，真实会话暂不开放角色授权保存。
+- 已接入 `GET/POST /api/platform/v1/iam/permissions`；真实会话使用 IAM 权限资源树，并严格把新增类型限制为 `MENU` 和 `BUTTON`。
+- 新增权限使用 `platform:permission:create`，正确提交真实父资源 ID、路由和排序；权限编辑、启停接口未提供，真实会话不展示对应模拟操作。
+- 2026-07-30 验收时 `192.168.110.149:9000` 连接被拒绝，无法执行真实登录和角色读写现场验证；专项自动化测试已覆盖接口路径、真实列表模式和失败恢复。
+
+## 八、客户端前端阶段验收（更新至 2026-07-30）
+
+| 验收项 | 结果 | 证据/说明 |
+|---|---|---|
+| 企业资料 | 通过（静态） | 基本信息、联系信息、资质文件选择与校验、移除、提交防重、元数据详情和移动端卡片已完成 |
+| 企业成员 | 通过（静态） | 列表与移动卡片、筛选、新增/编辑、多角色、重置密码、启停和管理员保护已完成 |
+| 企业角色 | 通过（静态） | 新增/编辑/删除/启停、成员和权限数量、内置角色保护及权限入口已完成 |
+| 菜单权限 | 通过（静态） | 角色选择、分组菜单与操作权限、全选/半选、保存/重置和只读保护已完成 |
+| 我的信息与修改密码 | 通过（静态） | 原型字段、查看/编辑/保存/取消、只读账号与企业、当前密码错误、密码强度和静态会话/审计结果已完成 |
+| 头程订单与仓库 | 通过（静态） | 下单、草稿、提交、列表、详情、启用仓库选择、历史仓库快照及后端必填字段已完成；取消不纳入本轮订单与客户客户端验收 |
+| 静态页面完整性与响应式 | 通过（100%） | 订单与客户客户端导航和路由均落到正式页面，无在用占位页；桌面、720px 和 390px 布局、移动导航、44px 主要操作及无横向溢出已验证 |
+| 自动化测试 | 通过 | `apps/client-web` 执行 `pnpm test`，94 项通过，覆盖认证、个人资料、成员、角色权限、超大整数响应、业务总览真实加载、往来单位历史快照、仓库详情、头程订单完整详情编辑、幂等、快递字段、失败恢复、未保存保护、响应式和关键源码契约 |
+| TypeScript 类型检查 | 通过 | `apps/client-web` 执行 `pnpm typecheck` |
+| 生产构建 | 通过 | `apps/client-web` 执行 `pnpm build`；产物扫描确认不包含商户联调账号和开发提示 |
+| 登录注册 | 代码接入（待环境验收） | 已移除模拟登录成功，接入真实注册、登录、退出、Token 轮换、统一错误与 MERCHANT 身份校验 |
+| 下单资格 | 通过（静态） | 企业资料待审核时可创建、编辑和保存草稿，提交时阻断并引导至企业资料；审核通过状态允许提交 |
+| 客户端权限效果 | 通过（静态） | 按演示账号过滤导航，拒绝无权限路由并显示 403，恢复刷新后的权限身份，控制主要业务按钮和首个可访问页面 |
+| 往来单位与订单快照 | 通过（静态） | 仅选择启用的发货/收货单位，可调整本单联系人和地址；保存后形成独立快照，不反向修改主数据 |
+| 快递信息 | 通过（静态） | 订单详情只读展示平台维护的快递公司和单号，并提供未维护空态；客户侧无写入口 |
+| 服务端与数据安全 | 联调中 | 认证、权限资源、企业资料、营业执照、个人资料、成员完整维护、角色完整维护、仓库详情、往来单位、头程订单及快递只读字段已接真实 API；订单 `customerId` 与 `CUSTOMER / SUPPLIER / BOTH` 契约已按后端源码和回归脚本复核 |
+
+> 客户端静态页面阶段通过不等于订单与客户业务完成。菜单隐藏和页面只读只用于前端体验，服务端仍必须按当前用户、`tenant_id` 和权限编码执行授权校验。
+
+### Client 认证与企业资料联调记录（2026-07-29）
+
+- 已按后端联调文档统一使用 Gateway `/api` 前缀，开发代理目标更新为 `http://127.0.0.1:9000`。
+- 已实现字符串业务码响应解包、422 字段错误载体、401 并发单次刷新、Refresh Token 轮换、退出清理，以及 403 不误跳登录。
+- 客户端只接受 `app_code=MERCHANT`，权限由 JWT 权限与 IAM 启用资源取交集后显式映射到现有页面权限。
+- 企业资料状态已统一为 `PROFILE_REQUIRED / PENDING / ACTIVE / REJECTED / DISABLED`；营业执照按后端限制只接受单张 JPG/PNG、最大 5MB。
+- 本机 `http://127.0.0.1:9000` 当前拒绝连接，真实登录与上传尚未执行；订单、仓库、往来单位接口文档缺少精确请求响应结构，本轮未猜测接入。
+
+### Client IAM 角色与成员联调记录（2026-07-29）
+
+- 已接入 `GET/POST /api/merchant/v1/iam/roles` 和 `GET /api/merchant/v1/iam/members`；新增角色使用后端返回的真实角色记录。
+- 已封装角色权限与成员角色的全量替换接口，请求分别使用 `roleId + permissionIds`、`membershipId + roleIds`，未误用 `userId`。
+- 成员列表接口目前只返回 membershipId、userId、memberType、status、joinedAt，页面不会伪造姓名、联系方式或角色关系。
+- 联调文档没有返回角色当前 permissionIds 和成员当前 roleIds 的查询契约。由于写接口是全量替换，页面暂禁用授权保存，避免覆盖已有权限。
+- 角色编辑、删除、启停、成员新增、资料编辑、启停和密码重置接口未提供；API 模式下相关静态写操作不再开放，也不会在请求失败后回退模拟成功。
+
+### Client 联调环境复测记录（2026-07-30）
+
+- 客户端开发服务 `http://localhost:5176` 返回 200，静态资源和前端运行环境正常。
+- 本机 `127.0.0.1:9000/9100/9201/9206` 均未监听；局域网环境 `192.168.110.149` 的 Gateway、Auth、IAM、File 健康端点曾同时返回 `UP`。
+- 通过 Gateway 请求未登录的商户权限接口返回预期 401，证明 Gateway 可达且鉴权入口生效；使用文档初始化商户账号调用 `/api/auth/login` 返回 503，无法取得 Token，后续企业资料、权限、角色和成员真实读取未能执行。
+- Auth 直连登录同样出现 503，随后端口短暂拒绝连接，表现为服务发现或服务重启不稳定；前端仍坚持只调用 Gateway，未把直连服务地址写入配置。
+- 后端恢复后优先复测：登录、Token 刷新与退出、企业状态、资质列表、权限资源、角色列表和成员列表；授权全量替换继续保持禁用，直到补齐当前 `permissionIds` 与 `roleIds` 回显。
+
+### Client 头程订单新接口接入记录（2026-07-30）
+
+- 新版联调文档和 Gateway Swagger 已确认可用；实测商户登录、企业资料、资质、权限、角色、成员、仓库分页、订单分页与订单详情均返回 `code=0`，订单详情不返回平台内部备注。
+- 已接企业资料 `PUT`、资质图片鉴权下载、仓库分页、订单分页/详情、创建/编辑草稿和提交；`SUBMITTED/PROCESSING`、`transportMode/containerMode` 均通过适配层映射，未把 FCL/LCL 错当运输方式。
+- 页面新增渠道、提货方式、报关模式、目的仓类型、包装类型等后端必填字段；订单和仓库请求失败不回退模拟数据，仓库为空时禁用创建。
+- Swagger 虽存在订单取消接口，但新版任务文档明确取消不纳入本轮本地订单与客户验收，因此客户端不暴露取消写操作。
+- 远端环境在浏览器验收阶段再次无响应；`http://127.0.0.1:5190` 登录页正常加载并发起真实登录，但 Gateway 健康检查与登录请求均超时，未进入工作台。
+- 代码已再次通过 81 项自动化测试和 TypeScript 检查；本轮生产构建与浏览器验收结果见交付记录，真实草稿写入、资质预览与空仓禁建仍需在稳定 Gateway 和有效仓库数据下继续验收。
+
+### 最新本地联调契约收口（2026-07-30）
+
+- 最新文档再次确认浏览器只通过 Gateway `9000` 和同源 `/api` 访问，禁止直连 `9100/9201/9204/9205/9206` 等服务端口；后端文档记录 8 个应用健康检查均为 `UP`，平台账号也已由人工登录进入 Admin。
+- 本轮真实接入范围为商户企业资料/资质、商户仓库和头程订单 CRUD/提交，以及平台待审列表、指定租户资质、鉴权文件查看和审核动作。平台订单审核、受理、履约、完成、取消及 Admin 快递公司/往来单位业务接口未纳入最新本地联调契约，前端继续保留静态实现，不猜测接口。
+- 后端任务文档写有“`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 窄屏无页面级横向溢出。由于当前无待审记录，资质抽屉的真实文件预览仍待准备样本后人工验收。
+
+### Admin 前端质量收口（2026-07-30）
+
+- 主数据导入架构明确为后端解析 `.xlsx`：前端仅检查扩展名和 10MB 大小限制，不读取工作表内容；已移除按文件名制造校验结果、模拟整批成功和虚假的错误报告。后端接口接入后，前端展示服务端返回的上传进度、逐行错误和报告地址。
+- API 错误适配层保留业务错误码、`requestId`、`traceId`；登录、企业审核、角色与权限主要失败态展示可复制追踪标识，接口失败仍不回退模拟成功。
+- 浏览器逐页检查 Admin 9 个主要业务路由；桌面与 390px 窄屏均无页面级横向溢出，修复了头程订单日期范围控件将窄屏筛选网格撑宽的问题，控制台无业务错误。
+- 两端登录页完成生产环境隔离：本地开发继续提供联调账号预填/提示，生产表单默认留空。Admin 21 个测试文件、148 项测试和 Client 82 项测试均通过，两端 `pnpm typecheck`、`pnpm build` 均通过；扫描生产 `dist` 对平台/商户联调账号、联调密码及开发提示零匹配。
+- 已读取后端 `phase1-business-maturity-regression-report.md` 并从 Gateway OpenAPI/真实只读请求复核契约：商户个人资料、成员资料及 roleIds、角色 permissionIds、往来单位候选均真实返回。Client 已移除个人资料和成员静态成功路径，接入修改密码、成员新增/编辑/启停/重置密码、角色权限全量保存与 SENDER/RECEIVER 候选；82 项测试、类型检查和生产构建通过，生产联调账号扫描零匹配。角色编辑/启停/删除路径未进入 OpenAPI，Admin 订单查询又要求显式 target tenantId，前端暂不猜测这两部分契约。
+
+### Client 成熟度报告接入与联调加固（2026-07-30）
+
+- 后端成熟度报告确认个人资料、修改密码、成员完整维护、角色权限回显与保存、仓库详情、往来单位候选、订单草稿/提交及平台快递只读信息已通过回归；客户端相应真实接口均已接入，不回退模拟成功。
+- 订单列表与详情已区分真实空数据和加载失败，均提供原位重试；编辑抽屉、路由离开和浏览器刷新/关闭均增加未保存草稿保护。
+- 选择收货仓时加载真实详情并回显地址、截单时间；历史订单优先展示仓库地址快照。订单详情映射快递公司、快递单号、收货仓地址和收货时间。
+- 往来单位按 `SENDER -> SHIPPER`、`RECEIVER -> CONSIGNEE` 查询启用候选；当前测试数据清理后候选为空，客户端保持真实空态，不恢复演示单位。
+- 角色 `permissionIds` 已映射为客户端权限码，权限保存执行真实全量替换；角色编辑、启停、删除虽已通过后端回归，但路径未进入当前 Gateway OpenAPI，页面继续隐藏对应写入口。
+- 代码门禁通过：Client 89 项自动化测试、`pnpm typecheck` 和 `pnpm build` 均成功。最新复测时 `192.168.110.149:9000` 再次拒绝连接，完整浏览器联调待 Gateway 恢复后继续。
+
+### Client Gateway 重启后浏览器联调（2026-07-30）
+
+- Gateway 重启后健康检查返回 `UP`，商户登录业务码为 `0`；浏览器真实登录成功，工作台、我的信息、企业成员和角色管理页均正常读取，控制台无错误。
+- 个人资料真实回显用户名、姓名、电话、邮箱和企业；成员接口真实返回 5 条记录，其中 1 条启用、4 条历史回归数据已停用，角色和联系方式均正常展示。
+- 浏览器发现角色页直接打开时未加载成员关系，导致成员数显示为 0；现已改为在拥有成员列表权限时并行加载角色与成员，统计按真实 `roleIds` 计算。
+- 服务随后再次超时，菜单权限页初始化期间原实现会因会话上下文失败清空 Token 并跳回登录。现已调整为临时网络故障或刷新超时保留有效会话，只有明确 401/`A0401` 才清理会话。
+- 修复后 89 项自动化测试、TypeScript 检查和生产构建通过；Gateway 当前健康检查仍超时，菜单权限、企业资料、仓库和头程订单浏览器验收待服务恢复后继续。
+
+### Client 后端修改后重新联调（2026-07-30）
+
+- Gateway 健康检查恢复为 `UP`，商户账号可重新登录；浏览器完成业务总览、头程订单列表、订单详情、创建表单、仓库详情和草稿编辑的真实只读验收。
+- 修复业务总览仍展示演示初始值的问题：首页现在按权限加载真实企业资料、成员和订单，显示企业已审核、1 名启用成员和 1 条真实草稿；接口失败时提供页面内重试。
+- 修复头程订单页未加载企业资料导致错误显示“待审核”的问题；页面现在真实显示企业已审核，可提交资格与服务端状态一致。
+- 修复真实草稿点击编辑时对 Vue 响应式对象调用 `structuredClone` 导致的 `DataCloneError`；保存与提交前也统一复制为纯草稿数据。
+- 修复从列表直接编辑只使用简要记录、造成货物和收发货快照为空的问题；编辑前先读取完整详情，并为已不在候选中的往来单位展示“历史快照”名称。
+- 真实仓库详情已回显“深圳头程收货仓”、广东省深圳市地址和每日 16:00 截单时间。现有旧草稿仍引用已失效仓库 `2001`，客户端会清空选择并提示重新选择；该样本关联需后端清理。
+- 当前订单详情的快递公司和快递单号均为空，客户端正确显示只读空态；需后端准备含快递信息的样本后复测有值场景。
+- 当前订单的部分中文字段由接口直接返回 `????`，涉及仓库名称、发货方、品名、渠道名称和备注；英文、数字、货物数量重量及收货方地址正常。该问题应由后端检查初始化脚本、数据库字符集或写入编码。
+- 过程中 Gateway 曾短暂返回 502/401，页面失败态、重试和会话清理行为符合预期；重新登录后恢复。最终代码门禁通过：Client 94 项自动化测试、`pnpm typecheck` 和 `pnpm build` 均成功。
+
+### Client 后端只读契约核对与复测（2026-07-31）
+
+- 联调方式调整为前端代码可修改、`baiyue-firstleg/` 后端仓库只读。后端每次拉取后优先核对相关 Controller、DTO、Service、Repository 与回归脚本，不改后端 Java、SQL、配置或文档。
+- 后端已存在商户角色编辑、状态和删除接口，客户端已接入 `PUT /api/merchant/v1/iam/roles/{roleId}`、`PUT /api/merchant/v1/iam/roles/{roleId}/status`、`DELETE /api/merchant/v1/iam/roles/{roleId}`，不再执行本地假更新。
+- 下单服务端强制校验主往来单位 `customerId`，并用服务端往来单位名称覆盖客户端 `customerName`；客户端创建和编辑请求现以所选发货方 ID 填充 `customerId`，发货方和收货方详情仍分别保存订单快照。
+- 往来单位主数据类型为 `CUSTOMER / SUPPLIER / BOTH`，不是订单角色 `SENDER / RECEIVER`。客户端改为一次读取当前租户启用候选，并允许同一候选用于发货方或收货方。
+- 本地 Gateway 真实登录成功，角色页读取两个内置角色及权限数正常；当前无自定义角色样本，未执行角色写操作。订单页当前返回 0 个启用收货仓，“创建订单”正确禁用，因此往来单位下拉仍待仓库样本恢复后只读验收。
+- 代码门禁通过：Client 94 项自动化测试、`pnpm typecheck` 和 `pnpm build` 均成功。新增契约断言覆盖 `customerId`、往来单位后端类型/双订单角色映射，以及角色编辑、状态、删除真实调用。
+
+### Admin 后端只读契约核对与角色接入（2026-07-31）
+
+- 从后端 `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 仍包含订单驳回接口，与当前订单与客户“不设置已驳回状态”的确认结论冲突，本轮明确不接入该接口；企业资料审核驳回不受此订单规则影响。