1

2026-08-05 15:52:51 +08:00
parent a70377c007
commit ee6e633d9f
11 changed files with 80 additions and 46 deletions
@@ -2,6 +2,12 @@

 一期目标是完成平台后台与企业客户端的真实业务基础，以及头程订单最小闭环。

+## 当前主体模型
+
+- 一期及后续未单独启用租户能力的阶段统一按“平台—客户”两级开发，当前是业务单租户、平台管理多客户、客户严格隔离。
+- Java 与接口中的 `tenant_id > 0`、`tenantId` 当前表示客户 ID，是客户隔离兼容字段；`tenant_id=0` 是平台账号和平台 RBAC 的技术作用域，不是可管理租户。
+- 历史表名、类名、接口路径和字段保留 `tenant` 命名，但不得据此新增租户主表、租户选择器、租户级权限或把现有字段改义为上级租户。
+
 ## 文档

 - [一期开发进度表](一期开发进度表.md)
@@ -19,5 +25,5 @@

 - 平台后台：内部账号登录、客户及企业资料审核、内部用户、角色权限、平台收货仓、快递公司、往来单位和头程订单；工作台不作为一期交付项。
 - 企业客户端：中文邮箱/手机号加密码登录、免审核企业注册、企业资料、成员角色权限、头程下单、订单列表和详情；企业资料经平台人工审核通过后才允许提交订单，一期不接短信/邮箱验证码及微信、企业微信登录。
- 服务端：认证、租户隔离、权限、文件、基础资料、订单状态机、幂等和审计。
+- 服务端：认证、基于兼容字段 `tenant_id` 的客户隔离、权限、文件、基础资料、订单状态机、幂等和审计。
 - 不包含工作台、部门/组织架构、完整 WMS、FBA/海外目的仓服务、在线报价、财务结算、完整报关清关、外部物流接口、多语言及微信/企业微信登录；快递公司和往来单位一期支持批量导入，不提供导出。
@@ -4,6 +4,8 @@
 > 创建日期：2026-07-28  
 > 适用范围：`apps/client-web`、`apps/admin-web`、`baiyue-firstleg`

+> 主体模型：本设计按“平台—客户”两级执行。现有 `tenant_id > 0` / `tenantId` 当前表示客户 ID，是客户隔离兼容字段；`tenant_id=0` 是平台技术作用域。历史命名继续兼容，不在一期引入真实租户层。
+
 ## 一、目标

 一期形成可验收的最小订单闭环：
@@ -36,7 +38,7 @@

 - 客户端：订单列表、组合筛选、创建、编辑草稿、提交、详情、取消。
 - 管理后台：企业资料审核通过、订单列表、详情、待审核订单人工修改、受理、负责人分配和状态更新。
- 服务端：真实租户隔离、权限校验、状态机、幂等提交、并发控制和操作时间线。
+- 服务端：基于兼容字段 `tenant_id` 的客户隔离、权限校验、状态机、幂等提交、并发控制和操作时间线。
 - 公共契约：订单状态、运输方式、优先级、列表摘要和详情模型。
 - 平台收货仓：后台维护国内收货仓档案和启停状态；客户端新建订单只选择已启用仓库。
 - 快递公司：后台人员统一维护快递公司档案和启停状态；企业客户端不维护，订单详情只读展示履约快递信息。
@@ -60,18 +62,18 @@

 | 参与者 | 数据范围 | 主要操作 |
 |---|---|---|
-| 企业成员 | 当前租户订单 | 查看列表与详情 |
-| 企业订单操作员 | 当前租户订单 | 创建、编辑草稿、提交、取消 |
-| 企业管理员 | 当前租户订单 | 拥有企业端全部订单权限 |
+| 企业成员 | 当前客户订单 | 查看列表与详情 |
+| 企业订单操作员 | 当前客户订单 | 创建、编辑草稿、提交、取消 |
+| 企业管理员 | 当前客户订单 | 拥有企业端全部订单权限 |
 | 平台运营 | 获授权数据范围内订单 | 审核、人工修改、受理、分配负责人 |
 | 平台操作员 | 获授权数据范围内订单 | 订舱、更新运输状态与处理说明 |
 | 平台超级管理员 | 全部订单 | 平台端全部订单操作 |

-服务端必须从已验证身份中取得租户上下文。客户端传入的 `tenantId`、`customerId` 或查询参数不能作为授权依据。
+服务端必须从已验证身份中取得客户归属上下文。客户端传入的 `tenantId`、`customerId` 或查询参数不能单独作为授权依据；其中 `tenantId` 是客户 ID 的兼容参数名。

 企业客户端菜单和操作权限由企业管理员为本企业角色分配。一个成员可拥有多个角色，权限取角色权限并集；一期不引入部门或组织架构，成员直接归属企业。企业管理员不能配置平台后台菜单，也不能跨企业授权。

-客户读取、更新、提交和取消订单时，服务端必须同时匹配订单 ID、当前租户 ID 和删除标记；不允许先按全局 ID 查出订单后再仅依赖前端隐藏。
+客户读取、更新、提交和取消订单时，服务端必须同时匹配订单 ID、当前客户 ID（兼容字段 `tenant_id`）和删除标记；不允许先按全局 ID 查出订单后再仅依赖前端隐藏。

 平台国内收货仓由后台统一维护，企业客户只读选择。停用仓库不得用于新建或重新提交订单，但不能破坏历史订单已经保存的仓库名称；一期首批覆盖义乌、深圳、青岛、上海、宁波和厦门，不将其与 FBA/海外目的仓混为同一模型。

@@ -119,10 +121,10 @@

 | 字段 | 必填阶段 | 说明 |
 |---|---|---|
-| `id` | 服务端生成 | 内部稳定 ID，不承载租户信息 |
-| `orderNo` | 提交时生成 | 客户可见业务单号；租户内和平台范围均应唯一 |
-| `tenantId` | 服务端注入 | 不接受客户指定 |
-| `referenceNo` | 可选 | 客户内部参考号；建议租户内非强制唯一 |
+| `id` | 服务端生成 | 内部稳定 ID，不承载客户归属信息 |
+| `orderNo` | 提交时生成 | 客户可见业务单号；客户内和平台范围均应唯一 |
+| `tenantId` | 服务端注入 | 当前表示客户 ID；历史兼容字段，不接受客户指定 |
+| `referenceNo` | 可选 | 客户内部参考号；建议客户内非强制唯一 |
 | `receivingWarehouseId` | 提交必填 | 平台国内收货仓 ID；提交时必须存在且处于启用状态 |
 | `receivingWarehouseName` | 服务端保存 | 下单时仓库名称冗余，兼容列表和旧消费者 |
 | `receivingWarehouseSnapshot` | 服务端保存 | 下单时仓库展示快照，至少包含 ID、编码、名称、省、市和详细地址 |
@@ -236,9 +238,9 @@

 | 方法 | 路径 | 权限编码 | 说明 |
 |---|---|---|---|
-| `GET` | `/api/v1/client/first-leg-orders` | `order:first-leg:list` | 当前租户订单分页列表 |
+| `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` | 当前租户订单详情 |
+| `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` | 按状态规则取消 |
@@ -287,7 +289,7 @@

 ### 请求一致性

- 创建和提交接口接受 `Idempotency-Key`，服务端按租户、用户、接口和键去重。
+- 创建和提交接口接受 `Idempotency-Key`，服务端按客户、用户、接口和键去重。
 - 更新请求携带 `version`；版本不一致返回冲突，不静默覆盖。
 - 提交和状态动作在同一事务内更新订单、版本和时间线。
 - 分页参数统一为 `page`、`pageSize`，并设置服务端最大页容量。
@@ -323,7 +325,7 @@

 ## 八、测试与验收

- 租户 A 无法读取、更新、提交或取消租户 B 的订单。
+- 客户 A 无法读取、更新、提交或取消客户 B 的订单。
 - 草稿可以反复保存，提交请求重复发送只产生一次状态变化。
 - 待审核订单仅允许当前企业获授权成员或获授权平台人员修改核心业务字段，修改后状态保持待审核且必须完整留痕；其他非草稿状态禁止修改。
 - 服务端拒绝非法状态跳转和缺少权限的状态动作。
@@ -351,7 +353,7 @@
 4. 实现后台基础资料维护、快递公司/往来单位批量导入和企业客户端往来单位只读查询。
 5. 实现客户工作台订单列表、创建和详情页面，静态阶段通过 API 适配层提供可替换数据源。
 6. 将管理后台订单 Pinia 模拟操作迁移到同一 API 契约，并接入履约快递信息。
-7. 增加跨租户、状态机、幂等、基础资料越权和前端业务流程测试。
+7. 增加跨客户拒绝、状态机、幂等、基础资料越权和前端业务流程测试。

 ## 十、已确认实施决策

@@ -5,6 +5,8 @@
 > 当前阶段：一期功能基本完成，进入测试环境部署、业务样本补齐和验收收口。双端核心页面已接真实 API；后端 19 个 Reactor 模块、169 项测试及本地真实接口回归已通过。2026-08-03 最新门禁中，Client 99 项测试和双端生产构建通过，Admin 129 项测试中 122 项通过、7 项失败，需先修正企业审核标识映射及其余页面断言后再做最终验收
 > 总体状态：收口中（暂不标记一期完成）

+> 主体模型：当前只实现“平台—客户”两级；`tenant_id > 0` 是客户 ID 兼容字段，`tenant_id=0` 是平台技术作用域。进度项中的历史 `tenant` 命名不得解释为真实租户层。
+
 头程订单一期闭环范围与接口草案见 `一期头程订单闭环设计.md`。

 ## 原型依据与进度口径
@@ -44,7 +46,7 @@
 |---|---|---|---:|---|---|---|---|
 | 基础工程 | 前后端工程、数据库、环境、接口规范 | 测试中 | 92% | 2026-07-27 | 待排期 | 待分配 | 双端工程、Gateway、认证、统一响应、数据库脚本和 OpenAPI 基础已完成；待测试环境迁移、配置发布和部署核验 |
 | 后台客户管理 | 客户档案、企业资料审核、启停和资料维护 | 测试中 | 88% | 2026-07-27 | 待排期 | 待分配 | 客户档案、资质和审核已接真实 API；当前 Admin 测试暴露审核记录 `reviewId`/租户字段映射风险，修复后需用待审/驳回样本验收 |
-| 后台管理 | 内部用户、角色、权限 | 测试中 | 93% | 2026-07-27 | 待排期 | 待分配 | 内部用户完整生命周期、角色权限回显与保存、权限资源维护均已接真实 API；待受限账号、停用权限即时生效和跨租户 403 验收 |
+| 后台管理 | 内部用户、角色、权限 | 测试中 | 93% | 2026-07-27 | 待排期 | 待分配 | 内部用户完整生命周期、角色权限回显与保存、权限资源维护均已接真实 API；待受限账号、停用权限即时生效和跨客户 403 验收 |
 | 后台头程订单 | 订单列表、详情、审核、受理、处理、完成、取消及履约信息 | 测试中 | 93% | 2026-07-27 | 待排期 | 待分配 | 订单状态流转、内部备注及快递信息已接真实 API；待准备完整状态与快递有值样本完成浏览器验收 |
 | 平台收货仓 | 平台维护国内收货仓；客户端选择启用仓库 | 测试中 | 92% | 2026-07-28 | 待排期 | 待分配 | 后台增改查和启停、客户端选择、详情及订单快照均已接真实 API；待测试环境初始化启用仓库并验收停用与历史引用 |
 | 快递公司维护 | 平台后台维护快递公司档案、启停及订单履约信息关联 | 测试中 | 90% | 2026-07-28 | 待排期 | 待分配 | 后台分页、详情、新增、编辑、启停和订单履约快递已接真实 API；批量导入后端解析接口尚未形成最终验收证据 |