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

> 适用范围：`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](/home/wren-dev/Porject/leaudit-platform/scripts/创建sql/schema_evaluation_points_tenant_cleanup.sql)，用于旧表 `evaluation_points` 的收尾

随后再进入 service 层改造。