1

二期/二期需求优化版-v2-测量计费入库主流程.md

@@ -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 产品结论仍需产品/业务负责人正式填写，技术实现通过不等于代替产品确认。