优化

AGENTS.md

@@ -6,13 +6,28 @@
 - 普通开发先读本文件、目标模块 `AGENTS.md` 和相邻代码；项目概览或聚合构建问题再读 `README.md`、`pom.xml`，跨服务架构、端口数据库、根目录结构、启动或部署问题再读 `docs/头程项目目录结构与服务说明.md`。
 - 本仓只承载国内头程业务。尾程源码、数据库、Redis、Nacos 和内部接口不得并入本仓。
 
-## 当前主体层级（重要）
+## 当前主体与隔离模型（重要，所有阶段必须遵守）
 
-- 完整目标模型原计划为“租户—平台—客户”三级，但当前阶段采用 **单租户、多客户**：整个系统只有一个隐式的默认租户，平台在该租户内运营和管理多个客户，客户之间必须严格隔离。
-- 当前不向业务侧引入或开放租户概念，不建设租户管理、租户切换、租户级配置或多租户隔离能力；现阶段需求、接口、权限、数据范围和用户可见文案均按“平台—客户”两级使用。
-- 当前真正的数据隔离边界是客户。服务端必须校验客户归属和访问权限，不得因为系统处于单租户模式而放松客户之间的数据隔离。
-- 代码、数据库和接口中已有的 `tenant`、`Tenant*`、`tenant_id`、`merchant` 等历史结构和兼容契约不得仅因当前未开放租户概念而贸然删除或重命名；修改前必须核对其当前实际承载的是默认租户、客户归属还是历史命名，避免破坏现有调用方和未来演进空间。
-- 预计约一年后再独立引入显式租户能力。届时存量客户统一归属到一个默认租户，再基于确认后的三级关系、租户隔离规则和迁移方案扩展多租户；当前开发不得提前实现未经确认的多租户业务，也不得做会显著增加未来迁移成本的不可逆改动。
+- 完整目标模型原计划为“租户—平台—客户”三级，但为尽快上线，当前约一年内采用 **业务单租户、平台管理多客户、客户严格隔离** 的模式。当前没有可管理、可选择或可切换的上级租户，也没有真实的“租户—平台—客户”三级关系。
+- “业务单租户”只是产品阶段约束，不表示代码中存在一个供所有数据共用的默认租户 ID。现有代码和数据库的 `tenant_id` 已经广泛承载 **客户 ID**，是当前客户隔离键；严禁把所有客户数据的 `tenant_id` 统一改成同一个值，否则会直接破坏客户隔离。
+- 当前需求、一期、二期、三期及后续未明确启用租户能力的开发，统一按“平台—客户”两级实现。不得自行新增租户主表、租户管理、租户切换、租户级配置、客户所属租户选择、租户级权限或其他显式多租户能力。
+
+当前代码中的主体标识固定按下表理解：
+
+| 现有结构 | 当前业务含义 | 修改约束 |
+|---|---|---|
+| `iam_tenant.id = 0`、`tenant_type = PLATFORM` | 平台技术作用域 | 必须保留为平台账号、平台角色和平台权限范围，不是未来的默认租户 |
+| `iam_tenant.id > 0`、`tenant_type = MERCHANT` | 平台直接服务的客户；`iam_tenant` 的这些记录当前直接作为客户主档 | 客户列表和客户业务只能使用 `MERCHANT` 记录，不得把平台记录当客户 |
+| Auth/JWT/业务表中的 `tenant_id > 0` | 当前登录客户或数据所属客户的 ID | 商户端从认证上下文取得；平台代客操作显式携带目标客户；Repository/Mapper 必须按该值过滤 |
+| RBAC 数据中的 `tenant_id = 0` | 平台权限或供客户复用的全局角色/权限模板 | 不代表真实上级租户，不能作为客户数据隔离条件 |
+| Order/Firstleg 等业务中的 `customer_id` | 订单往来单位、发货客户或其他业务客户快照，具体以模块契约为准 | 不是 IAM 平台客户 ID，不能替代 `tenant_id` 做当前客户隔离 |
+| `DEFAULT_TENANT_ID`、`public-tenant-id` 等配置 | 平台公共仓库和主数据的技术归属配置，当前固定为平台作用域 `0` | 不代表未来默认租户；公共资源不得再绑定普通客户 `10001`，变更时必须同步 Warehouse 种子、存量迁移及全部消费者 |
+
+- 当前真正的数据隔离边界是上述客户 ID。服务端必须校验客户归属和访问权限；商户请求不得信任前端传入其他客户 ID，平台跨客户查询或代客操作必须同时受平台应用域、权限码和目标客户条件约束。
+- 平台维护并供所有客户使用的公共仓库、往来单位、快递公司、托盘、库位等公共资源统一归属平台技术作用域 `tenant_id = 0`；客户订单、文件、费用和其他客户私有数据继续使用客户 `tenant_id > 0`。往来单位不是客户私有数据，不能按客户复制或隔离。不得再使用演示客户 `10001` 充当公共资源所有者。
+- 代码、数据库和接口中已有的 `tenant`、`Tenant*`、`tenant_id`、`merchant` 等名称属于历史命名和兼容契约，当前不做大规模重命名；但新增代码和文档必须按本节解释其真实含义，禁止看到名称后推断系统已经存在显式租户层。
+- 预计约一年后再以独立需求引入真实租户。届时应优先新增独立租户主表或明确的上级 `root_tenant_id`，把所有存量 `MERCHANT` 客户统一归属到一个默认租户，再迁移 Auth、JWT、跨服务 DTO 和各服务数据库；不得原地把现有 `iam_tenant.id` 或业务 `tenant_id` 从客户 ID 改义为上级租户 ID。
+- 用户在后续对话明确调整本模型之前，本节是所有新模块和分期任务的事实来源；原型、历史设计或代码中的“租户”文案不得自动扩大实现范围。
 
 ## 模块快速索引
 
@@ -91,7 +106,7 @@
 ## 通用修改约束
 
 - Controller 只做协议转换，Service 负责编排，Repository/Mapper 负责持久化；不要跨层堆放业务逻辑。
-- 当前采用单租户多客户模式。客户数据必须保留客户归属维度，并由服务端执行平台/客户访问域、客户数据隔离、数据范围和按钮权限校验；默认租户不能替代客户隔离条件，也不得据此允许跨客户访问。
+- 当前采用业务单租户、平台管理多客户模式。现有 `tenant_id` 是客户归属与隔离键，客户数据必须保留该维度，并由服务端执行平台/客户访问域、客户数据隔离、数据范围和按钮权限校验；不得把它统一替换为所谓默认租户 ID，也不得据此允许跨客户访问。
 - 修改 SQL、DTO、事件或公共组件时同步检查所有生产者与消费者；优先保持兼容，不能兼容时写清迁移顺序。
 - 对外 HTTP JSON 中的 Java `Long/long` 统一输出字符串，请求同时接受字符串 ID；业务模块禁止重复添加局部 ID 转换器，OpenAPI 必须同步声明字符串契约。
 - 普通业务成功与失败统一使用 HTTP 200，并以响应体字符串 `code` 判断；`code == "200"` 才成功。网关/Servlet Security 的真实 401/403、协议与基础设施错误、Warehouse readiness 503、Audit 202 和 Event Bridge 内部鉴权边界除外；完整约定见 `docs/统一响应约定改造方案-HTTP200.md`。