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

# 虫虫出海订单与客户开发进度表

> 创建日期：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 仍包含订单驳回接口，与当前订单与客户“不设置已驳回状态”的确认结论冲突，本轮明确不接入该接口；企业资料审核驳回不受此订单规则影响。