leaudit-platform-backend/docs/权限与地区隔离/评查点模块收尾清单.md

评查点模块收尾清单

适用范围：evaluation_points 旧表仍在线、评查点模块已完成 T5-1 ~ T5-5 首轮 tenant-first 收口后的最终收尾阶段
更新日期：2026-05-21
文档定位：明确评查点模块距离“真正摆脱 area 主边界”还差哪些数据库、后端、前端、验收与风险动作。

---

1. 当前真实状态

评查点模块当前已经完成的不是“全量终态”，而是第一轮高风险收口：

1. 读链路已经 tenant_code 优先
2. 写链路已经 tenant_code 优先
3. 共享域 PUBLIC / PROVINCIAL 已经开始标准化
4. 主链路角色判定已切到 data_scope + permission
5. 旧 area 仍然是物理表兼容字段，不是最终可删除状态

也就是说：

1. 现在已经能明显降低“写错租户、查错范围”的风险
2. 但还不能说评查点模块已经彻底完成租户化

---

2. 收尾目标

评查点模块最终收尾只看 4 个结果：

1. evaluation_points 具备真实 tenant_code
2. 历史 area 已完成可审计回填
3. service 查询与写入不再把 area 当主边界
4. area 退化为展示/兼容字段，最后可评估下线

---

3. 数据库收尾项

3.1 必做

1. 给旧表 evaluation_points 补：
   • tenant_code VARCHAR(64) NULL
   • tenant_name VARCHAR(128) NULL
2. 建索引：
   • idx_evaluation_points_tenant_code
   • idx_evaluation_points_group_tenant_code
   • 如编码唯一性要按租户收口，再评估 uq_evaluation_points_tenant_code_code_active
3. 先不删 area
4. 先不加 NOT NULL

3.2 历史回填规则

统一按下面顺序：

1. 已有合法 tenant_code 保留
2. 否则优先按 sys_tenant_aliases.alias_value -> tenant_code
3. 否则按 sys_tenants.tenant_name -> tenant_code
4. 否则按兼容值兜底：
   • 公共 / default / 空值 -> PUBLIC
   • 省级 / 省局 -> PROVINCIAL
5. tenant_name 与 tenant_code 一起回填

3.3 回填前预检

上线前必须先跑：

1. area 值分布统计
2. area 无法映射租户编码的残留清单
3. code 在跨租户下是否允许重复的预检
4. 公共/省级/省局/default/空值 数量统计

---

4. 后端收尾项

4.1 可以在数据库补字段后立即推进

1. ListPoints / GetPoint 查询彻底改成：
   • 先按 tenant_code
   • tenant_name/area 仅在老数据回填不完整时 fallback
2. CreatePoint / UpdatePoint 默认要求落 tenant_code/tenant_name
3. _evaluation_point_tenant_code_expr() 可从“兼容表达式”逐步收窄到真实列
4. _tenant_scope_match_sql() 的旧中文兼容匹配可以继续缩薄

4.2 等历史回填完成后再推进

1. 去掉读链路里对 公共/default/空值/省局/省级 的多值 fallback
2. 去掉写链路里 area 作为最终归属镜像字段的必要性
3. 评估把 GetPoint / ListPoints 的共享域判断统一下沉到模块 policy

---

5. 前端收尾项

5.1 必查

1. 评查点列表页是否还传 area
2. 新建/编辑页是否还允许手填地区文本
3. 详情页是否仍以 area 为主展示归属
4. 查询缓存 key 是否仍含旧 area

5.2 目标状态

1. 查询主参数只传 tenant_code
2. 展示层显示 tenant_name
3. area 最多只作为历史记录兼容显示

---

6. 验收清单

6.1 数据验收

1. evaluation_points 中 tenant_code 非空占比可统计
2. PUBLIC / PROVINCIAL 记录数量可统计
3. 未映射记录清单可导出

6.2 行为验收

1. 本租户管理员只能看到本租户 + 共享域评查点
2. 本租户管理员不能把评查点改挂到其他租户
3. 全局用户创建非共享评查点，必须显式指定 tenant_code
4. 共享域列表读取优先命中标准编码，不再先靠中文值
5. 新建一个自定义租户后，可正常筛选该租户评查点

6.3 回归验收

1. 旧数据中 公共/default/空值 仍可见
2. 旧数据中 省级/省局 仍可见
3. 评查点分组联动不回归
4. 编码唯一性行为不意外变化

---

7. 剩余风险

高风险

1. 如果数据库不先补 tenant_code，代码层再怎么 tenant-first，也只能停留在兼容态
2. 如果历史回填不先跑，查询口径会长期停在“标准编码 + 中文兼容混合”阶段

中风险

1. 若前端仍持续提交 area，会延长兼容期
2. 若共享域中文常量在别的模块也继续扩散，会影响后续统一执行器接入

低风险

1. tenant_name 展示名后续调整可能影响少量历史展示，不应影响真实边界

---

8. 推荐执行顺序

1. 先执行评查点 tenant_code 补字段与历史回填脚本
2. 再做一次评查点接口联调
3. 再收掉 service 内最厚的 area fallback
4. 最后把这条链接到统一数据范围执行器

---

9. 本轮直接产物

本轮已新增两份配套产物：

1. 本文档：评查点模块收尾清单.md
2. 数据库草案：schema_evaluation_points_tenant_cleanup.sql
3. 执行说明与验证清单：评查点数据库执行说明与验证SQL.md
4. 执行前预检 SQL：precheck_evaluation_points_tenant_cleanup.sql
5. 预检结果判读模板：评查点预检结果判读模板.md