leaudit-platform-backend/docs/权限与地区隔离/高风险数据库迁移清单与执行顺序.md

高风险数据库迁移清单与执行顺序

适用范围：leaudit-platform 当前从 area/region 过渡到 tenant_code 的高风险数据库收口阶段
更新日期：2026-05-21
文档定位：明确高风险阶段数据库需要补哪些字段、为什么补、执行顺序是什么、哪些脚本需要先后落地。

---

1. 目标

本清单只解决一个核心问题：

当前多个核心业务表仍没有把 tenant_code 作为真实归属主字段，导致代码层即使传了 tenant_code，最终也只是转成中文 area/region 去查。

高风险数据库阶段的目标是：

1. 所有核心业务主表具备真实 tenant_code
2. 查询和写入具备切到 tenant_code 主链的基础
3. 历史 area/region/default/省级/公共 有明确回填路径

---

2. 高风险表清单

2.1 必须补字段的主表

D1 leaudit_documents

当前现状：

1. 模型层只有 region
2. 文档、公文、交叉评查、版本链大量依赖该表

必须新增：

1. tenant_code VARCHAR(64) NULL

建议索引：

1. idx_leaudit_documents_tenant_code
2. idx_leaudit_documents_type_tenant_name_latest 说明：替代当前依赖 region 的版本匹配索引

D2 contract_templates

当前现状：

1. 主表只有 region
2. service 返回里仍存在 '' AS tenant_code

必须新增：

1. tenant_code VARCHAR(64) NULL

建议索引：

1. idx_contract_templates_tenant_code_active
2. uq_contract_templates_tenant_code_code_active

D3 usage_login_events

当前现状：

1. 只有 area_snapshot
2. 登录统计无法稳定按租户回溯

必须新增：

1. tenant_code_snapshot VARCHAR(64) NULL
2. tenant_name_snapshot VARCHAR(128) NULL

建议索引：

1. idx_usage_login_events_tenant_code

D4 rag_dataset

当前现状：

1. 只有 area
2. 数据集可见性和编辑权限仍依赖旧地区模型

必须新增：

1. tenant_code VARCHAR(64) NULL

建议索引：

1. idx_rag_dataset_tenant_code
2. 后续可替代 idx_rag_dataset_area

D5 rag_chat_app

当前现状：

1. 只有 area
2. 聊天应用可见性仍跟旧地区字段耦合

必须新增：

1. tenant_code VARCHAR(64) NULL

建议索引：

1. idx_rag_chat_app_tenant_code

D8 evaluation_points

当前现状：

1. 真实运行链路仍使用旧表 evaluation_points
2. 评查点模块代码已切到 tenant_code 优先，但旧表仍可能只有 area
3. 若数据库不补列，模块只能长期停留在兼容态

必须新增：

1. tenant_code VARCHAR(64) NULL
2. tenant_name VARCHAR(128) NULL

建议索引：

1. idx_evaluation_points_tenant_code
2. idx_evaluation_points_group_tenant_code
3. idx_evaluation_points_group_pid_tenant_code

2.2 暂不直接补字段，但依赖主表收口的表

D6 govdoc_runs / govdoc_rule_results / govdoc_report_artifacts

结论：

1. 暂不优先单独加 tenant_code
2. 先通过 govdoc_runs.document_id -> leaudit_documents.tenant_code 间接收口
3. 等主链稳定后，再评估是否补冗余快照列提升报表与筛选性能

D7 leaudit_audit_runs / 评查结果衍生表

结论：

1. 暂不优先单独加 tenant_code
2. 先通过 document_id -> leaudit_documents.tenant_code 收口
3. 若后续统计或明细页性能不足，再追加快照字段

---

3. 历史数据回填规则

3.1 统一回填原则

所有历史回填统一按下面顺序处理：

1. 若已有 tenant_code 且合法，保留
2. 否则根据原 tenant_code 对应编码直接回填
3. 否则根据 tenant_name
4. 否则根据 area
5. 否则根据 region
6. 若值为 default / 公共 / 省级 / 空值，回填为规范编码

规范编码建议：

1. PUBLIC
2. PROVINCIAL

3.2 别名映射来源

优先使用：

1. sys_tenants
2. sys_tenant_aliases

不再允许长期使用硬编码映射表作为正式来源。

3.3 风险点

以下数据回填前必须预检：

1. 同一个中文地区名是否映射到多个租户编码
2. 是否存在脏数据：空格、大小写、历史缩写混用
3. 是否存在已经改名但旧数据仍用旧租户名的记录

---

4. 执行顺序

4.1 第一步：补列，不切读写

执行内容：

1. 给 leaudit_documents
2. contract_templates
3. usage_login_events
4. rag_dataset
5. rag_chat_app
6. evaluation_points

先补 tenant_code 或快照字段及索引。

目标：

1. 不影响当前存量逻辑
2. 为后续渐进式代码改造做准备

4.2 第二步：做历史回填

执行内容：

1. 用 sys_tenant_aliases 回填历史 region/area
2. 对 PUBLIC/PROVINCIAL 做统一归并

目标：

1. 让存量数据先具备基础 tenant_code
2. 避免代码一切换就出现大量空值

4.3 第三步：后端改读写

执行内容：

1. 文档模块先切
2. 公文模块第二个切
3. 合同模板第三个切
4. 统计与 RAG 随后切

目标：

1. 读写统一以 tenant_code 为主
2. region/area 退化为兼容展示字段

4.4 第四步：补约束与清理旧索引

等代码和数据稳定后再做：

1. 评估 tenant_code 是否可加 NOT NULL
2. 评估是否可将唯一索引从 region 改为 tenant_code
3. 逐步淘汰旧 area/region 主过滤索引

---

5. 本轮建议新增的 SQL 脚本

建议新增一个统一高风险迁移脚本：

1. scripts/创建sql/schema_tenant_code_high_risk_phase1.sql
2. scripts/创建sql/schema_evaluation_points_tenant_cleanup.sql

建议内容：

1. 给核心业务表补 tenant_code / tenant_code_snapshot
2. 建立基础索引
3. 执行首轮历史回填
4. 对评查点旧表单独补 tenant_code/tenant_name 与共享域标准编码回填

后续再拆第二阶段脚本：

1. scripts/创建sql/migrate_tenant_code_high_risk_phase2_cleanup.sql

用于：

1. 强化约束
2. 调整唯一索引
3. 清理旧索引

---

6. 验收标准

数据库层本阶段完成后，应满足：

1. 核心业务主表都能查到 tenant_code
2. 核心历史数据回填完成率可统计
3. PUBLIC / PROVINCIAL 已规范化
4. 后端可以在不依赖中文 area/region 的前提下完成后续主链改造

---

7. 本轮直接执行项

本轮直接开始：

1. 新增 schema_tenant_code_high_risk_phase1.sql
2. 先补列与索引
3. 加入首轮基于 sys_tenant_aliases 的历史回填 SQL
4. 评查点模块单独补充 schema_evaluation_points_tenant_cleanup.sql，用于旧表 evaluation_points 的收尾

随后再进入 service 层改造。