feat: add tenant-scoped rule and permission management

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

@@ -0,0 +1,285 @@
+# 高风险数据库迁移清单与执行顺序
+
+> 适用范围：`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 层改造。