2026-09-28 16:01:16 +08:00
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；批量导入后端解析接口尚未形成最终验收证据 |
@@ -2,6 +2,12 @@

 三期以头程物流“03 出仓”为范围，完成从排柜、订舱、拖车和仓内拣货，到封柜、报关、国内出仓并等待装船的业务闭环。

+## 当前主体模型与开工禁令
+
+- 三期继续按业务单租户、“平台—客户”两级开发，客户之间严格隔离。Java 与接口中的业务 `tenant_id > 0` / `tenantId` 当前表示客户 ID；`tenant_id=0` 是平台身份、平台 RBAC 和平台公共仓库、快递公司、托盘、库位等公共资源技术作用域。客户往来单位、订单、文件和费用仍归属客户 `tenant_id>0`。
+- 三期不得新增租户主表、租户选择器、客户所属租户配置、租户切换、租户级 RBAC 或租户级配置，也不得把当前 `tenant_id` 从客户 ID 改义为上级租户 ID。
+- `tenant`、`Tenant*`、`merchant`、接口路径和字段属于历史兼容命名，继续保留；真实租户能力必须等未来独立需求、数据迁移和跨服务契约方案确认后再实施。
+
 ## 文档

 - [三期开发规划：国内出仓](三期开发规划.md)
@@ -13,4 +19,4 @@

 ## 当前状态

-三期处于范围规划阶段，当前开工结论为 `NO-GO`。当前以原型图片中的“完成国内出仓，等待装船”为阶段终点。动作依赖与并行关系、排柜规则、PDA 设备、拖车协作、柜封照片清单、报关回执及放行门禁、港务/船期信息范围和来源仍需在启动前确认。产品和业务完成确认后先进入契约与任务准备，六项开工准入全部通过后再进入全面功能开发。
+三期处于范围规划阶段，当前开工结论为 `NO-GO`。当前以原型图片中的“完成国内出仓，等待装船”为阶段终点。动作依赖与并行关系、排柜规则、PDA 设备、拖车协作、柜封照片清单、报关回执及放行门禁、港务/船期信息范围和来源仍需在启动前确认。产品和业务完成确认后先进入契约与任务准备，六项开工准入全部通过后再进入全面功能开发；通过准入也不授权引入真实租户层。
@@ -5,6 +5,8 @@
 > 流程依据：[出仓流程](参考资料/出仓流程.png)中的头程物流“03 出仓”；当前以图片中的“完成国内出仓，等待装船”为阶段终点  
 > 前置阶段：[一期文档](../一期/README.md) · [二期文档](../二期/README.md)

+> 主体模型与硬约束：三期只实现“平台—客户”两级，业务 `tenant_id > 0` / `tenantId` 当前表示客户 ID；`tenant_id=0` 是平台身份、平台 RBAC 和平台公共仓储资源技术作用域，客户往来单位、订单、文件和费用归属客户 `tenant_id>0`。禁止新增租户主表、租户选择器、客户所属租户配置、租户切换、租户级 RBAC 或租户级配置，禁止把现有 `tenant_id` 改义为上级租户 ID；历史类名、路径和字段继续兼容。
+
 ## 一、三期目标

 三期承接二期“货物完成到仓、实测、差异处理和指定库位”的结果，将已受理货物转化为可执行、可追踪、可审计的国内出仓任务。
@@ -224,7 +226,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片

 ### 服务端 `baiyue-firstleg`

- 最终保证身份、租户、仓库数据范围、权限、状态、门禁、幂等、并发和审计。
+- 最终保证身份、客户归属、仓库数据范围、权限、状态、门禁、幂等、并发和审计。
 - 管理出仓、排柜、订舱、拖车、拣货、装柜、报关和时间线的事务边界。
 - 文件上传校验类型、大小、内容和权限；使用不可预测标识和授权下载。
 - 为船期、车队、海关等外部接口预留适配层，但三期不承诺正式对接。
@@ -2,6 +2,12 @@

 二期以头程物流“02 到仓”为作业主线，完成预约取货、送货上门、入库测量、差异记录和指定库位闭环，并增加头程费用项目、计费规则、费用试算和费用明细。产品已确认二期不建设应收应付、对账、收付款、核销、发票和利润模块。

+## 当前主体模型
+
+- 二期继续按“平台—客户”两级开发。`tenant_id > 0` / `tenantId` 当前表示客户 ID，用于客户隔离；`tenant_id=0` 是平台技术作用域。
+- 不新增真实租户、租户选择器或租户级 RBAC，也不把兼容字段重定义为上级租户。历史路径、字段与配置名继续保留。
+- 平台公共仓库、快递公司、托盘、库位等公共资源统一归属平台技术作用域 `tenant_id=0`，不绑定客户；客户往来单位、订单、文件和费用继续按所属客户 `tenant_id>0` 严格隔离。`10001` 是客户 ID，不得用于公共资源归属。
+
 ## 文档

 - [二期 V2 需求确认清单（当前会议填写）](二期V2需求确认清单.md)
@@ -30,7 +36,7 @@
 - 测量批次：`2084556854154715137`
 - 费用单：`FBAF-2084549769916538881-1`
 - 计费结果：实重 `20kg`，体积 `0.24m³`，计费量 `40.08kg`，费用 `440.68 CNY`
- 自动化测试：Firstleg 77 项、Warehouse 68 项、共享资源租户专项 3 项全部通过
+- 自动化测试：Firstleg 77 项、Warehouse 68 项、公共仓储技术归属专项（历史测试名含“资源租户”）3 项全部通过
 - 在线验证：7 个隔离服务健康状态均为 `UP`

 本地 OCR 未配置真实供应商凭证，因此本轮验证的是“图片上传成功、OCR 返回失败、人工修正并确认、继续完成计费入库”的可用降级链路。真实 OCR 识别准确率仍需在测试环境使用现场秤图验证。
@@ -7,6 +7,8 @@

 > 技术状态（2026-08-04）：任务 `019fc6f9-8dcf-74e1-bc68-d42f15d7802a` 已完成核心正常主链路开发和真实 API 回归。以下“产品确认状态”仍由产品/业务负责人填写，技术完成不自动等同于产品确认。

+> 主体模型：二期只实现“平台—客户”两级；业务数据的 `tenant_id>0` 是客户隔离兼容字段，平台公共仓储资源归属 `tenant_id=0`。下表历史“资源租户”均指公共主数据技术归属，不代表真实租户。
+
 ## 一、使用说明

 - 本清单是二期 V2 的唯一会议确认入口。
@@ -129,9 +131,9 @@ C1 至 C8 确认后，原 P2-Q14 至 P2-Q16 不再单独维护，避免形成两
 | C5 KG/CBM 规则 | 已实现并验证样本 | 实重 `20kg`、体积重 `40.08kg`，取 `40.08kg` 计费 |
 | C6 费用项目白名单 | 技术能力已具备，业务内容待确认 | 本轮使用测试价格 `11 CNY/kg`，不能代替正式费用白名单 |
 | C7 费用发送与入库节点 | 已实现 | 审核通过后自动生成费用 `440.68 CNY`，最终 `SENT + INBOUNDED` |
-| C8 托盘与库位 | 已实现 | 托盘、库位、预占、确认占用及资源租户快照已验证 |
+| C8 托盘与库位 | 已实现 | 托盘、库位、预占、确认占用及公共主数据技术归属快照已验证 |
 | T1 第三方测量参数 | 接口能力已实现，供应商参数待定 | 正式签名密钥、设备编码和供应商联调环境仍需确认 |
 | T2 OCR 参数 | 降级链路已验证，真实供应商待接入 | 本地 OCR 未配置，已验证失败后人工修正继续入库 |
-| T3 托盘库位基础资料 | 已实现并通过 API 创建 | 公共仓资源租户为 `10001`，分配状态 `CONFIRMED` |
+| T3 托盘库位基础资料 | 已实现并通过 API 创建 | 当前公共主数据技术归属规则为 `tenant_id=0`，分配状态 `CONFIRMED`；`10001` 不再作为公共资源归属 |

 完整接口与回归证据见 [二期前端联调报告（2026-08-04）](二期前端联调报告-2026-08-04.md)。
@@ -5,6 +5,8 @@
 > 代码基线：`test-01` 分支，提交 `25d2a13`  
 > 使用对象：平台后台前端、商户端前端、第三方测量系统联调人员

+> 术语与现行规则校正：当前产品只有“平台—客户”两级。客户业务中的 `tenantId` / `tenant_id` 表示客户 ID 兼容字段；“资源租户”历史术语表示公共主数据技术归属。平台公共仓库、快递公司、托盘和库位现归属 `tenant_id=0`，客户往来单位、订单、文件和费用归属客户 `tenant_id>0`；报告中的 `10001` 是已失效的历史联调样本，不得继续作为公共资源归属。
+
 ## 一、联调结论

 二期后端主流程、平台测量、OCR 重量、客服审核、FBA 计费、费用发布、入库完成、库位和托盘维护、客户只读查询、第三方测量回传接口均已形成代码闭环。
@@ -84,7 +86,7 @@ Authorization: Bearer <accessToken>
 Content-Type: application/json
 ```

-平台代目标企业操作的接口还必须传 `tenantId` 查询参数。后端同时校验登录应用类型、操作者数据范围、目标租户、仓库和资源归属；不能只依靠前端隐藏按钮实现隔离。
+平台代目标企业操作的接口还必须传代表目标客户的 `tenantId` 查询参数。后端同时校验登录应用类型、操作者数据范围、目标客户、仓库和资源归属；不能只依靠前端隐藏按钮实现隔离。

 所有有副作用且要求幂等的接口必须传：

@@ -493,7 +495,7 @@ image：该条箱规唯一对应的 JPG/PNG/BMP 图片，最大 5 MB
 8. 提交测量，验证状态变为 `MEASURE_PENDING`，托盘和库位结果已生成。
 9. 先走一次驳回 → 修改 → 重新提交，验证旧页面版本提交被拒绝。
 10. 客服审核通过，随后重新查询详情和 `/fees/latest`，验证自动变为 `INBOUNDED / SENT`。
-11. 商户账号查询 `inbound-billing`，验证只读数据、跨租户 403/404 和未发布费用不可见。
+11. 商户账号查询 `inbound-billing`，验证只读数据、跨客户 403/404 和未发布费用不可见。
 12. 调整一次已发布费用，验证新版本可见、旧版本被替代且入库状态不回退。
 13. 验证重复点击使用同一幂等键不会重复计费、重复托盘或重复占位。
 14. 验证无权限按钮、直接构造越权请求、空态、加载态、异常提示和移动端展示。
@@ -543,7 +545,7 @@ D:\apache-maven-3.8.8\bin\mvn.cmd clean test -pl order,firstleg,warehouse,file,i
 - 测量提交时托盘拆分、库位预占/确认、失败回滚、幂等重试。
 - 客服驳回、通过后自动计费/发布/入库、中断续跑。
 - FBA 计费规则选择、已发布费用调整和状态不回退。
- 客户只见本租户已发布费用，平台/商户身份及跨租户隔离。
+- 客户只见本客户已发布费用，平台/商户身份及跨客户隔离。
 - 第三方签名、防重放、事件幂等、仓库范围及不越权推进状态。
 - 第三方一条箱规对应一条订单货物明细和一张图片、重复绑定拦截、图片补偿清理。
 - 库位/托盘主数据约束、A0 共享溢出及活动占用唯一性契约。
@@ -560,7 +562,7 @@ D:\apache-maven-3.8.8\bin\mvn.cmd clean test -pl order,firstleg,warehouse,file,i
 2. Gateway、Nacos、Redis、MySQL、服务间令牌和各微服务的真实 HTTP 联通。
 3. OCR 引擎对现场秤图的识别准确率、超时和失败重试。
 4. 并发提交、并发抢托盘/库位、A0 多托盘共享在真实数据库事务下的压力验证。
-5. 浏览器端完整登录、刷新 Token、权限按钮、403、跨租户、空态、加载态和重复提交体验。
+5. 浏览器端完整登录、刷新 Token、权限按钮、403、跨客户拒绝、空态、加载态和重复提交体验。
 6. 当前托盘管理没有独立启停和状态筛选接口；本期页面只做查询、新增、编辑、删除。

 上述内容是本报告初版时的阶段结论。2026-08-04 已继续完成真实数据库迁移和隔离端口在线 HTTP 回归，最终结论以第十七章为准。
@@ -598,20 +600,20 @@ D:\apache-maven-3.8.8\bin\mvn.cmd clean test -pl order,firstleg,warehouse,file,i
 - 7 个隔离服务健康检查均为 `UP`。
 - Firstleg 自动化测试 77 项通过。
 - Warehouse 自动化测试 68 项通过。
- 共享资源租户专项测试 3 项通过。
+- 公共仓储技术归属专项（历史测试名含“资源租户”）3 项通过。

 ### 17.3 前端需要采用的最终契约

 - 入库详情已经返回 `version`，测量审核、驳回等乐观锁请求必须使用服务端最新版本。
 - Long 类型 ID 继续按字符串处理。
 - 客服审核通过后由后端自动完成计费、费用发送和入库，前端成功后刷新详情与最新费用，不串行调用补偿接口。
- 平台操作公共收货仓时，业务租户与仓储资源租户由后端分别校验，前端不自行改写资源租户。
+- 平台操作公共收货仓时，订单客户归属与公共主数据技术归属由后端分别校验，前端不自行改写技术归属字段。
 - OCR 未配置时会返回明确失败状态，页面必须允许人工修正识别重量并确认，不能把 OCR 失败等同于整条业务失败。

 ### 17.4 本轮修复

 1. 补齐 `fl_inbound_weight_result.created_by`、`updated_by`，修复称重结果登记 SQL 失败。
-2. 增加 `firstleg.inbound.warehouse-resource-tenant-id`，支持商户订单使用公共资源租户下的仓库、托盘和库位；本轮测试值为 `10001`。
+2. 增加历史兼容配置 `firstleg.inbound.warehouse-resource-tenant-id`，支持商户订单使用公共主数据技术归属下的仓库、托盘和库位；2026-08-04 本轮曾使用 `10001` 验证，但该样本已失效，现行公共资源归属必须为平台技术作用域 `0`。
 3. 仓储确认结果回传并保留 `reservationNo`，避免分配快照写入空预占单号。
 4. 入库详情 `InboundOrderSummary` 增加 `version`。
 5. `fl_inbound_pallet_allocation` 增加 `warehouse_resource_tenant_id`，保留历史资源归属快照。
@@ -5,6 +5,8 @@
 > 后端范围：只读核对 `baiyue-firstleg/`，本任务不修改后端  
 > 当前基线：以后端现有 Controller、DTO、权限和状态机为可联调事实；V2 待确认项不擅自补成前端规则

+> 主体模型：前端只呈现“平台—客户”两级；接口 `tenantId` 当前表示客户 ID。任务中的“租户切换”统一理解为客户切换，不新增租户选择器或租户级权限。
+
 本轮不存在“等待后端提供接口文档”的前置任务。每个前端对话直接只读当前工作区 `baiyue-firstleg/` 中的 Controller、DTO、Service、Repository、OpenAPI 和权限 SQL；发现契约问题只登记，不修改后端。

 ## 一、结论
@@ -116,7 +118,7 @@ Client 只修改现有 `FirstLegOrdersView.vue` 的订单详情抽屉，新增
 - 浏览器代码使用现有 `/api` 基地址，不硬编码 Gateway 地址。
 - 普通业务 HTTP 200 后仍需判断响应体 `code === "200"`。
 - Java Long 在 JSON 中按字符串处理，前端不得转为 `Number`。
- Admin 当前接口显式需要目标 `tenantId`；切换企业必须清空仓库、详情、编辑、上传和幂等上下文。
+- Admin 当前接口显式需要代表目标客户的 `tenantId`；切换企业必须清空仓库、详情、编辑、上传和幂等上下文。
 - 409 表示版本或并发冲突，页面应刷新最新详情，不静默覆盖。
 - 审核通过、驳回、异常放行和费用写操作按 Controller 要求携带 `Idempotency-Key`。

@@ -149,11 +151,11 @@ Client 只修改现有 `FirstLegOrdersView.vue` 的订单详情抽屉，新增
 | `P2-ADM-07` | 船司 FBA 价格 | 独占 `modules/fba-pricing/carrier-rates/**` 及测试 | 查询、详情、新版本、停用、起运仓/渠道/船司/FBA 仓/价格和有效期 | 只读 `PlatformFbaMasterDataController` 价格契约 | W1 |
 | `P2-ADM-08` | 库位管理 | 独占 `modules/warehouse-resources/locations/**` 及测试 | 企业/仓库级联、筛选分页、CRUD、启停、乐观锁、状态限制、响应式 | 现有企业选择器和仓库 API | W1 |
 | `P2-ADM-09` | 托盘管理 | 独占 `modules/warehouse-resources/pallets/**` 及测试 | 企业/仓库级联、筛选分页、CRUD；不虚构状态或启停 | 现有企业选择器和仓库 API | W1 |
-| `P2-ADM-10` | 入库详情工作台组装 | 独占 `modules/inbounds/pages/InboundOrderDetailView.vue`、`components/InboundWorkflowWorkspace.vue` 及测试 | 将 ADM-01 至 ADM-05 组件组装为详情页；统一刷新、租户切换清理、操作成功回读和托盘库位只读结果 | ADM-01 至 ADM-05 | W2 |
+| `P2-ADM-10` | 入库详情工作台组装 | 独占 `modules/inbounds/pages/InboundOrderDetailView.vue`、`components/InboundWorkflowWorkspace.vue` 及测试 | 将 ADM-01 至 ADM-05 组件组装为详情页；统一刷新、客户切换清理、操作成功回读和托盘库位只读结果 | ADM-01 至 ADM-05 | W2 |
 | `P2-ADM-11` | Admin 全局装配 | 独占各模块 `routes.ts`、`app/router/index.ts`、`core/navigation/adminNavigation.ts` 及对应测试 | 接入全部 Admin 页面、菜单和权限；首个可访问路由正确；不恢复接收审核/费用项目原型菜单 | ADM-06 至 ADM-10 | W3 |
 | `P2-ADM-12` | 海外仓阶梯费用 | 建议独占 `modules/overseas-storage-fees/**` 及测试；路由和菜单在集成时统一修改 | 分页、详情、新增、编辑、删除；客户唯一性、连续阶梯校验、乐观锁冲突、权限态和未保存保护 | `PlatformOverseasStorageFeeController` | W1 |
 | `P2-CLI-01` | 商户订单入库费用只读展示 | `apps/client-web/src/modules/first-leg/api/inboundBilling.ts`、`types/inboundBilling.ts`、`components/InboundBillingPanel.vue`、`views/FirstLegOrdersView.vue` 及测试 | 成功/待发布/失败/重试、快速切单、320/720/桌面；无写动作，不消费内部字段 | 只读 `MerchantInboundBillingController` 及 DTO/Service | W1 |
-| `P2-QA-01` | Admin 跨模块回归 | 以新增集成测试和联调记录为主，不重构业务实现 | 租户切换、401/403、业务码、409、幂等、重复提交、图片异常、空/加载/失败、权限按钮、窄屏；运行 test/typecheck/build | `P2-ADM-11` | W4 |
+| `P2-QA-01` | Admin 跨模块回归 | 以新增集成测试和联调记录为主，不重构业务实现 | 客户切换、401/403、业务码、409、幂等、重复提交、图片异常、空/加载/失败、权限按钮、窄屏；运行 test/typecheck/build | `P2-ADM-11` | W4 |
 | `P2-QA-02` | Client 安全与展示验收 | 只读审查和补测试，避免与 CLI-01 同时改订单页 | 不展示内部备注/历史；A0404 中性态；响应隔离；test/typecheck/build | `P2-CLI-01` | W2 |

 ### 6.2 推荐并行波次
@@ -7,6 +7,8 @@
 > 产品确认：[2026-07-31 产品确认合并记录](产品回传/2026-07-31-产品确认合并记录.md)  
 > 前置阶段：[一期文档](../一期/README.md)

+> 主体模型：二期只实现“平台—客户”两级。`tenant_id > 0` / `tenantId` 是客户 ID 兼容字段，`tenant_id=0` 是平台技术作用域；不得新增真实租户、租户选择器、租户级 RBAC 或重定义现有隔离字段。
+
 ## 一、二期目标

 二期承接一期“客户下单并选择平台收货仓”的结果，完成货物从待到仓、实际收货、测量、差异记录到指定库位的作业闭环，并在实测数据之上完成头程费用计算。
@@ -37,7 +39,7 @@
 - 申报数据与实测数据对比、差异记录、客户通知和审计。
 - 最小库位档案、上架任务、指定库位和位置历史。
 - 头程费用项目、计费规则版本、费用试算、人工费用、调整、确认和费用明细。
- 服务端权限、租户隔离、状态、幂等、并发、文件鉴权、审计和历史快照。
+- 服务端权限、基于兼容字段 `tenant_id` 的客户隔离、状态、幂等、并发、文件鉴权、审计和历史快照。

 ### 明确不纳入二期

@@ -205,7 +207,7 @@

 ### 国内头程后端 `baiyue-firstleg/`

- 最终保证身份、租户、仓库数据范围、状态转换、幂等、并发和审计。
+- 最终保证身份、客户归属、仓库数据范围、状态转换、幂等、并发和审计。
 - 管理到仓单、收货批次、处理单元、标签、测量、差异通知、库位、上架、位置和冲正事务边界。
 - 管理计费规则版本、费用生成幂等、三位向上取整、费用调整和历史复算。
 - 文件访问使用不可预测标识和授权下载，不信任客户端文件名与 MIME 类型。
@@ -287,5 +289,5 @@
 5. 实现库位、上架任务和位置历史，不建设隔离和容量校验。
 6. 确认 P2-Q14 至 Q16，建立头程费用项目和计费规则版本。
 7. 接入实测和业务事件，完成费用试算、人工补录、调整和费用明细。
-8. 完成租户隔离、幂等、计费复算、文件安全、审计和回归测试。
+8. 完成跨客户隔离、幂等、计费复算、文件安全、审计和回归测试。
 9. 使用脱敏初始化数据联调、验收和发布。
@@ -5,6 +5,8 @@
 > 依据：二期原型、现有二期需求优化稿及 2026-08-01 新增流程说明  
 > 本文只定义二期范围和业务契约，不代表功能已经开发完成。

+> 主体模型：本文业务数据中的“租户”历史术语与 `tenantId` / `tenant_id` 字段，当前均按客户归属兼容语义理解；产品只有“平台—客户”两级。`tenant_id=0` 是平台身份、RBAC 和平台公共仓储资源技术作用域，客户往来单位、订单、文件和费用使用所属客户 `tenant_id>0`。二期不引入真实租户层。
+
 > 技术实现状态更新（2026-08-04）：任务 `019fc6f9-8dcf-74e1-bc68-d42f15d7802a` 已完成核心正常主链路开发，并通过本地测试 MySQL 和隔离端口真实 API 回归。产品/业务待确认项仍以第九章和《二期 V2 需求确认清单》为准。

 ## 一、结论
@@ -34,7 +36,7 @@
 - 托盘基础资料、库位及库位占用放在仓库服务。
 - 测量图、称重图继续使用文件服务。
 - 客户通知通过现有事件桥接服务发送，不在入库事务中同步调用外部消息渠道。
- 权限继续复用 IAM，所有后台按钮做到租户、企业、仓库数据范围校验。
+- 权限继续复用 IAM，所有后台按钮做到客户归属、企业、仓库数据范围校验。

 ## 二、核心业务规则

@@ -123,7 +125,7 @@ Idempotency-Key: 第三方事件号

 接口校验：

- 入仓码必须存在，且属于请求中的仓库和租户绑定关系。
+- 入仓码必须存在，且属于请求中的仓库和客户归属关系。
 - 入库单必须处于待测量或测量被驳回状态；已入库、已作废、费用已发送的数据不得覆盖。
 - 长宽高必须大于 0，单位统一为厘米；数量必须为正整数。
 - 同一个 `appKey + eventNo` 重复请求返回第一次结果，不重复新增明细。
@@ -172,7 +174,7 @@ POST /api/platform/inbounds/{inboundId}/weight-results/confirm

 计费匹配顺序：

-1. 根据租户、客户和生效时间选择客户计费规则版本。
+1. 根据客户归属、业务客户和生效时间选择客户计费规则版本；两类客户含义必须按字段契约区分。
 2. 根据起运仓、渠道/计费类型、船司、FBA 目的仓和生效时间匹配船司价格。
 3. 计算实测体积、实重和折算量。
 4. 按客户规则确定 KG 或 CBM 计费口径，并取实际量与折算量中的较大值。
@@ -280,7 +282,7 @@ POST /api/platform/inbounds/{inboundId}/weight-results/confirm
 | 仓库服务 | 托盘资料、库位资料、可用库位查询、预占/确认/释放 | 托盘、库位、库位占用、预占记录 |
 | 文件服务 | 称重图片、测量图片和附件 | 文件元数据和对象存储引用 |
 | 事件桥接服务 | 客户通知的可靠投递 | Outbox 消费记录、通知结果 |
-| IAM | 租户、企业、仓库范围和按钮权限 | 新增二期权限资源，不新增业务数据 |
+| IAM | 客户归属、企业、仓库范围和按钮权限 | 新增二期权限资源，不新增业务数据 |

 头程与仓库分库，不能依赖跨库事务。采用“仓库库位预占 → 头程确认入库 → 仓库确认占用”的幂等 Saga；补偿只释放仍处于预占状态的库位，已经完成实物入库的记录不得被通知失败反向释放。

@@ -313,7 +315,7 @@ POST /internal/location-reservations/{reservationNo}/confirm
 POST /internal/location-reservations/{reservationNo}/release
 ```

-所有写接口必须支持幂等键；所有查询由后端基于登录上下文注入租户和企业范围，禁止相信前端传入的 `tenantId`。
+所有写接口必须支持幂等键；所有查询由后端基于登录上下文注入客户归属和企业范围，禁止单独相信前端传入的 `tenantId`；该参数当前表示目标客户 ID。

 ## 六、页面范围

@@ -338,7 +340,7 @@ POST /internal/location-reservations/{reservationNo}/release

 | ID | 模块 | 交付内容 | 优先级 |
 |---|---|---|---|
-| P2-01 | 契约、状态与权限 | 状态机、错误码、按钮权限、租户/企业/仓库数据范围 | P0 |
+| P2-01 | 契约、状态与权限 | 状态机、错误码、按钮权限、客户/企业/仓库数据范围 | P0 |
 | P2-02 | 入库单 | 列表、详情、入仓码和操作历史 | P0 |
 | P2-03 | 第三方测量 | 签名、幂等、长宽高回传、原始报文留档和查询 | P0 |
 | P2-04 | OCR 称重 | 图片关联、OCR、人工校正、单位换算、确认和重量汇总 | P0 |
@@ -373,7 +375,7 @@ POST /internal/location-reservations/{reservationNo}/release
 - 库位数量不足、被并发抢占或已停用时，入库失败且不能留下半完成费用/占用。
 - 重复点击发送费用只产生一份费用快照、一组托盘和一次入库结果。
 - 客户通知失败时入库状态不回滚，系统自动重试并可查失败原因。
- 跨租户、跨企业、跨仓库查询和操作全部返回 403，并记录安全审计。
+- 跨客户、跨企业、跨仓库查询和操作全部拒绝，并记录安全审计；具体使用 HTTP 状态还是业务码以接口统一响应契约为准。

 ## 九、仍需业务最终确认的事项

@@ -407,7 +409,7 @@ POST /internal/location-reservations/{reservationNo}/release
 - 客服测量审核通过后自动计费、发送费用并完成入库。
 - FBA 目的仓计费按实重和体积重取大，本轮 `20kg` 与 `40.08kg` 取 `40.08kg`。
 - 入库详情、费用快照、托盘和库位分配结果查询。
- 公共收货仓资源租户与商户业务租户分离。
+- 公共收货仓的公共主数据技术归属与商户订单的客户归属分别校验；这只是当前兼容实现，不形成真实租户层。

 ### 11.2 最终验证数据

@@ -423,7 +425,7 @@ POST /internal/location-reservations/{reservationNo}/release

 ### 11.3 已落地配置与数据快照

-公共仓资源租户配置：
+公共仓主数据技术归属配置（配置名保留历史 `tenant` 命名）：

 ```yaml
 firstleg:
@@ -431,10 +433,10 @@ firstleg:
    warehouse-resource-tenant-id: ${WAREHOUSE_RESOURCE_TENANT_ID:0}
 ```

-默认值 `0` 保持租户独立仓逻辑；本地联调使用 `10001`。托盘分配快照已保存 `warehouse_resource_tenant_id` 和 `reservation_no`，避免配置变化后无法追溯历史资源归属。
+公共仓库、快递公司、托盘和库位当前统一使用平台技术作用域 `tenant_id=0`，不得绑定客户 `10001` 或其他客户 ID。客户往来单位、订单、文件和费用仍使用所属客户 `tenant_id>0`。托盘分配快照继续保存历史字段 `warehouse_resource_tenant_id` 和 `reservation_no`，其中公共资源归属值应为 `0`，避免配置变化后无法追溯历史资源归属。

 ### 11.4 尚未关闭的环境验收项

 - 接入真实 OCR 供应商凭证后，以现场秤图验证识别准确率、超时和重试。
- 前端浏览器完成登录、权限按钮、403、跨租户、重复提交、空态和移动端体验验收。
+- 前端浏览器完成登录、权限按钮、403、跨客户拒绝、重复提交、空态和移动端体验验收。
 - C1-C8 产品结论仍需产品/业务负责人正式填写，技术实现通过不等于代替产品确认。