leaudit-platform-backend/docs/用户权限开发TaskList.md

# 用户权限开发 TaskList

> 目标：在 `leaudit-platform` 里，基于当前真实业务落地一套 **单地区隔离 + 角色权限 + 数据范围控制** 的用户体系，并能把老系统用户数据平滑迁移过来。

这份文档不是泛泛设计稿，而是后续开发的执行清单。

---

## 1. 当前结论先说清楚

当前这条线，应该按下面原则做，不要再发散：

- 用户地区只认 `sso_users.area`
- 数据隔离只做单地区，不做多地区授权
- 当前业务角色只保留：
  - `provincial_admin`
  - `admin`
  - `common`
- `super_admin` 只作为可选系统维护角色
- 数据范围只保留：
  - `ALL`
  - `DEPT`
  - `SELF`
- 新系统要兼容老系统已有数据结构，不要为了“理论优雅”把老数据迁移难度抬高

---

## 2. 当前新系统现状盘点

## 2.0 本次实际检查结果（2026-04-29）

我已经实际检查了当前 `leaudit_platform` 新库和老库 `docauditai`，结论如下：

- 新库 `leaudit_platform` 原先 **完全没有** 这 7 张核心 RBAC 表：
  - `sso_users`
  - `roles`
  - `user_role`
  - `permissions`
  - `role_permissions`
  - `sys_routes`
  - `role_route`
- 新库现阶段只有 `leaudit_*` 业务表，所以原有认证/权限代码其实处于“代码已写、库表未落地”的状态
- 我已经补了可执行 SQL：
  - `scripts/user_rbac_schema_patch.sql`
  - `scripts/user_rbac_seed.sql`
  - `scripts/user_rbac_migration_audit.sql`
- 我已经把 `schema_patch + seed` 执行进当前新库
- 当前新库 RBAC 初始化结果：
  - `roles = 4`
  - `permissions = 30`
  - `role_permissions = 90`
  - `sys_routes = 9`
  - `role_route = 30`
  - `sso_users = 0`
  - `user_role = 0`

老库 `docauditai` 的迁移审计关键结果：

- `sso_users = 4106`
- `roles = 3`
- `user_role = 11`
- `permissions = 133`
- `role_permissions = 222`
- `sys_routes = 34`
- `role_route = 95`
- 老库 **没有空地区、没有重复 sub、没有重复 username**
- 老库 **4106 个用户里有 4098 个没有角色**
- 老库真实角色分布非常集中：
  - `common = 6`
  - `admin = 4`
  - `provincial_admin = 1`

这说明：

- 老系统用户登录主数据是可迁的
- 但角色并不是“每个用户都显式分配了 user_role”
- 新系统迁移时必须补一轮“默认角色落地策略”，不能只机械复制 `user_role`

## 2.1 已有能力

当前新系统已经有这些基础：

- 已有 `sso_users` 登录查询逻辑
- 已有 JWT 签发与鉴权
- 已有 `user_role / roles / role_permissions / permissions` 的查询代码雏形
- 已有受保护路由统一挂载 JWT 依赖：`fastapi_modules/fastapi_leaudit/controllers/__init__.py`
- 已有认证入口：`/auth/login`、`/auth/password_login`

## 2.2 当前实际代码路径

当前这条线的核心代码在：

- `fastapi_modules/fastapi_leaudit/services/impl/authServiceImpl.py`
- `fastapi_modules/fastapi_leaudit/services/impl/permissionServiceImpl.py`
- `fastapi_common/fastapi_common_security/jwtService.py`
- `fastapi_common/fastapi_common_security/security.py`
- `fastapi_modules/fastapi_leaudit/controllers/auth/authController.py`

## 2.3 当前最关键的问题

### 问题 1：权限设计文档和实际代码字段名不一致

当前代码查的是：

- `roles.role_key`
- `permissions.permission_key`
- `role_permissions.grant_type`

但我前面新写的初始化 SQL 用的是：

- `roles.role_name`
- `permissions.permission_code`

这说明：

- **现阶段不能直接执行那份初始化 SQL 到现有库**
- 必须先按当前实际数据库字段重新收一版正式建表/初始化方案

### 问题 2：登录后只取“一个角色”

当前 `authServiceImpl.py` 里：

```python
SELECT r.role_key ... LIMIT 1
```

这意味着：

- 多角色用户会被截断成单角色
- JWT 中的 `roles` 没真正使用起来
- 后续 `ALL > DEPT > SELF` 的数据范围收敛逻辑无法成立

### 问题 3：JWT 里没有真正放入完整权限集

当前 JWT 虽然支持 `roles` 字段，但登录时只传了：

- `userRole`
- `area`

没有把：

- 全量角色列表
- 权限点列表
- 最终数据范围摘要

稳定打进去。

这会导致：

- `/me` 接口还不完整
- 前端拿不到统一用户权限视图
- 后端每次都要重新查库，且现有逻辑并未闭环

### 问题 4：当前没有统一的数据范围注入层

现在只是“能查角色 / 权限”，但还没有真正统一实现：

- 文档列表自动按 `area` 过滤
- 用户列表自动按 `area` 过滤
- 评查 run / result 自动按文档归属校验

也就是说：

- **功能权限雏形有了，数据权限还没有真正落地**

### 问题 5：OAuth 登录仍然可能把 area 当外部输入覆盖

当前 OAuth 登录里：

- `Area=requestData.get("area")`
- 然后直接 `UPDATE sso_users SET ... area = :area`

这是很危险的。

因为这意味着：

- 前端或调用方传什么 area，就可能把用户地区改掉
- 数据隔离基础字段可能被外部请求污染

后续必须改成：

- area 只能来自后台可信源
- 登录请求不能直接覆盖 area

### 问题 6：新用户自动创建后没有默认角色闭环

当前 OAuth 首登自动插入 `sso_users`，但代码里没有看到紧接着分配默认 `common` 角色的闭环。

风险：

- 新用户建出来了，但没有角色
- 没角色则权限查询为空
- 前端表现为“登录成功但啥也看不到”

### 问题 7：密码仍然是明文比对

当前 `PasswordLogin()` 里：

- 直接 `user.get("password") != Password`

这是明显安全风险。

即使当前先沿用旧系统，也至少要在 tasklist 里明确：

- 第一阶段兼容旧明文
- 第二阶段升级为哈希存储与校验

### 问题 8：缺少统一的 `/api/auth/me`

当前文档里已经定义了 `/api/auth/me`，但现有 controller 里还没有真正落地。

这会影响：

- 前端初始化用户态
- 角色/权限/地区统一回显
- 登录后刷新恢复

---

## 3. 老系统可迁移数据结论

基于老项目 `docauditai` 的数据库快照和代码分析，当前可直接继承的核心表是：

- `sso_users`
- `roles`
- `user_role`
- `permissions`
- `role_permissions`
- `sys_routes`
- `role_route`

## 3.1 老系统 `sso_users` 关键字段

老系统 `sso_users` 目前至少包含：

- `id`
- `sub`
- `username`
- `nick_name`
- `phone_number`
- `email`
- `ou_id`
- `ou_name`
- `status`
- `is_leader`
- `password`
- `try_count`
- `try_login_time`
- `area`
- `tenant_name`
- `dep_short_name`
- `dep_name`
- `mq_person_uuid`
- `mq_account_uuid`
- `mq_synced_at`
- `created_at`
- `updated_at`
- `deleted_at`

### 迁移判断

这说明：

- 新系统**完全没必要重新发明用户主表**
- 最优方案是：
  - 继续沿用 `sso_users`
  - 补必要索引/约束/注释
  - 修正其业务语义

## 3.2 老系统 `roles` 关键字段

老系统 `roles` 目前至少包含：

- `id`
- `role_key`
- `role_name`
- `data_scope`
- `description`
- `parent_role_id`
- `priority`
- `is_system_role`
- `permissions_cache`
- `metadata`
- `created_at`
- `updated_at`

### 迁移判断

建议：

- 保留 `role_key` 作为机器标识
- 保留 `role_name` 作为中文/展示名
- 继续使用 `data_scope`
- `parent_role_id / permissions_cache / metadata` 可以先保留但不作为第一阶段核心依赖

## 3.3 老系统 `permissions` 关键字段

老系统 `permissions` 目前至少包含：

- `id`
- `permission_key`
- `module`
- `resource`
- `action`
- `description`
- `display_name`
- `permission_type`
- `is_system`
- `metadata`
- `parent_id`
- `sort_order`
- `route_id`
- `api_path`
- `api_method`
- `created_at`
- `updated_at`

### 迁移判断

建议：

- 不要再新造 `permission_code`
- 直接沿用 `permission_key`
- 后续新系统全部按 `permission_key` 统一

## 3.4 老系统 `role_permissions` 关键字段

老系统 `role_permissions` 目前至少包含：

- `role_id`
- `permission_id`
- `grant_type`
- `data_scope`
- `condition_filter`
- `metadata`
- `created_at`
- `updated_at`

### 迁移判断

建议：

- 继续保留 `grant_type`
- 第一阶段只用 `GRANT`
- `DENY` 能力先兼容不扩展
- `condition_filter` 暂不作为第一阶段核心能力

---

## 4. 最终推荐表结构策略

这里不是从零建库，而是：

- **以老系统实际表结构为准**
- 对新系统补齐缺失字段、索引、语义约束
- 避免再造第二套平行用户权限模型

## 4.1 `sso_users` 目标策略

### 保留字段

- 保留老系统现有字段不动
- 核心业务字段继续认：`area`

### 必须加的约束 / 索引

建议检查并补：

- `UNIQUE(sub)`
- `INDEX(area)`
- `INDEX(status)`
- `INDEX(deleted_at)`
- `INDEX(username)`

### 字段语义正式化

- `sub`：统一身份唯一标识
- `username`：登录名 / 工号 / 展示账号
- `nick_name`：真实姓名
- `area`：用户主地区，也是默认数据隔离依据
- `password`：短期兼容旧值，后续迁移为哈希

## 4.2 `roles` 目标策略

继续沿用：

- `role_key`：机器标识，例如 `provincial_admin`
- `role_name`：中文展示名，例如“省级管理员”
- `data_scope`：默认数据范围

建议正式保留的角色：

- `provincial_admin`
- `admin`
- `common`
- `super_admin`（可选）

## 4.3 `permissions` 目标策略

继续沿用：

- `permission_key`
- `api_path`
- `api_method`
- `route_id`

建议后续所有新权限都按下面格式命名：

- `auth:me:read`
- `documents:list:read`
- `documents:upload:write`
- `audit:run:execute`
- `rules:binding:update`

不要混用：

- 一部分 `documents.list`
- 一部分 `document:read:all`

必须统一成一种风格。

### 我建议

直接收口成老系统已有风格：

- `module:resource:action`

这样能和老数据完全对齐。

## 4.4 `role_permissions` 目标策略

继续沿用：

- `grant_type`
- `data_scope`

建议唯一约束明确为：

- `(role_id, permission_id, grant_type, data_scope)`

但在第一阶段实际配置时：

- 尽量只放 `GRANT`
- `data_scope` 按权限点是否涉及数据决定

## 4.5 `user_role` 目标策略

继续沿用现有结构即可。

关键点不是表结构，而是后端逻辑必须支持：

- 一个用户可以挂多个角色
- 登录时不能 `LIMIT 1`
- 权限汇总和数据范围要支持多角色收敛

## 4.6 `sys_routes / role_route` 目标策略

继续沿用旧系统结构即可。

重点是：

- 前端菜单权限可以继续从这里出
- 但 **接口权限不能只依赖菜单权限**
- API 权限必须还是走 `permissions / role_permissions`

---

## 5. 当前逻辑漏洞清单（必须按优先级修）

## P0：必须先修

### 5.1 角色/权限字段命名统一

要统一到底使用：

- `role_key` 还是 `role_name`
- `permission_key` 还是 `permission_code`

当前结论：

- 统一用 `role_key`
- 统一用 `permission_key`

### 5.2 登录角色查询改成多角色

当前：

- `LIMIT 1`

必须改成：

- 查询全部角色
- JWT 带 `roles`
- 兼容保留一个 `user_role` 主角色字段给旧前端

### 5.3 OAuth 登录禁止直接覆盖 `area`

必须改成：

- 登录入参中的 `area` 不再直接写库
- area 只能来自：
  - 老库已存在值
  - 后台管理维护
  - 后续可信组织同步

### 5.4 新用户自动分配默认角色

OAuth 首登新用户创建后，必须补：

- 自动赋 `common`

### 5.5 `/api/auth/me` 落地

要把当前用户的：

- 基本信息
- `area`
- `roles`
- `permissions`

统一返回。

## P1：第二阶段紧跟着修

### 5.6 数据范围注入

至少要先覆盖：

- 文档列表
- 文档详情
- 用户列表
- 评查状态 / 结果

### 5.7 密码校验升级

短期兼容旧明文，长期迁移到哈希：

- 登录时支持“旧明文兼容 + 新哈希优先”
- 用户下次修改密码时写入哈希

### 5.8 权限缓存 / 权限聚合

后续可以考虑：

- JWT 轻载
- 服务端缓存权限聚合结果

但这不是 P0。

---

## 6. 老系统用户数据迁移策略

## 6.1 迁移原则

不是“把老用户复制一份到新表”，而是：

- **尽可能复用原表结构**
- 用增量清洗 + 角色校正 + 地区校正的方式迁移

## 6.2 迁移对象

第一阶段只迁这几类数据：

1. `sso_users`
2. `roles`
3. `user_role`
4. `permissions`
5. `role_permissions`
6. `sys_routes`
7. `role_route`

## 6.3 `sso_users` 迁移规则

### 必迁字段

- `id`
- `sub`
- `username`
- `nick_name`
- `phone_number`
- `email`
- `ou_id`
- `ou_name`
- `status`
- `is_leader`
- `password`
- `area`
- `tenant_name`
- `dep_name`
- `dep_short_name`
- `created_at`
- `updated_at`
- `deleted_at`

### 可选迁字段

- `mq_person_uuid`
- `mq_account_uuid`
- `mq_synced_at`
- `try_count`
- `try_login_time`

### 迁移前校验

要先出统计：

- `sub` 是否有重复
- `username` 是否有重复
- `area` 是否为空
- `status != 0` 的禁用用户数量
- `deleted_at is not null` 的软删除用户数量

## 6.4 角色映射规则

要先梳理老库中真实 `role_key` 分布。

预期映射：

- `provincial_admin` → 保留
- `admin` → 保留
- `common` → 保留
- 其他历史角色：
  - 先做映射表
  - 无法归类的先落到 `common`
  - 再人工复核

### 明确不再延续的角色

- `city_admin`
- `review_manager`
- `review_user`
- `rule_admin`

如果老库真的还残留这些历史角色，不建议直接带入新系统业务角色定义，应该做映射清洗。

## 6.5 area 清洗规则

迁移前要先把 `sso_users.area` 跑一遍质量检查：

- 是否为空
- 是否存在历史别名
- 是否存在前后空格
- 是否存在同义不同写法

最后要统一成一套稳定值，例如：

- `省局`
- `梅州`
- `云浮`
- `揭阳`
- `潮州`

---

## 7. 开发分阶段 TaskList

下面是正式开发顺序。

## 阶段 A：数据库基线收口

### A1. 先核对当前库真实表结构

目标：

- 以当前数据库真实字段为准
- 不再拿“理想 SQL”直接执行

动作：

- 检查 `sso_users`
- 检查 `roles`
- 检查 `user_role`
- 检查 `permissions`
- 检查 `role_permissions`
- 检查 `sys_routes`
- 检查 `role_route`

产出：

- 一份“现网真实表结构快照”
- 一份“目标结构差异清单”

### A2. 出正式迁移 SQL

目标：

- 不是重建表
- 是补字段 / 补索引 / 补约束 / 补初始化数据

动作：

- 修正角色初始化 SQL
- 修正权限初始化 SQL
- 修正菜单初始化 SQL
- 统一全部字段名到现有真实库

产出：

- `用户权限_schema_patch.sql`
- `用户权限_seed.sql`

## 阶段 B：登录与 JWT 收口

### B1. 修 `AuthServiceImpl`

必须改：

- 多角色查询
- 新用户默认角色分配
- OAuth 登录禁止外部覆盖 `area`
- 登录响应统一返回 `roles`
- 兼容返回单个 `user_role`

### B2. 修 `JwtService`

必须改：

- token 中写入 `roles`
- 保留 `user_role`
- 写入 `area`
- 视情况写入精简 `permissions`

### B3. 新增 `/api/auth/me`

返回：

- 用户基本信息
- area
- roles
- permissions

## 阶段 C：权限聚合与数据范围引擎

### C1. 做统一权限聚合服务

目标：

- 给定 `user_id`
- 返回：
  - 角色列表
  - 权限列表
  - 每个权限点最终 data_scope

### C2. 做统一数据范围判定器

目标：

- 输入：用户 + 权限点 + 业务资源
- 输出：
  - `ALL`
  - `DEPT`
  - `SELF`

### C3. 先接到核心接口

优先改：

- `/api/documents/list`
- `/api/audit/run/{RunId}`
- `/api/audit/result/{RunId}`
- `/api/users/list`

## 阶段 D：老用户数据迁移

### D1. 出迁移前检查 SQL

统计：

- 用户数
- 角色分布
- area 分布
- 无角色用户
- 空 area 用户
- 重复 sub / username

### D2. 出迁移脚本

做法：

- 先备份
- 再清洗 area
- 再导入 / 映射角色
- 再补默认角色
- 再跑校验

### D3. 迁移后验收

验收项：

- 登录正常
- `/api/auth/me` 正常
- 文档列表按地区隔离正常
- admin 不能跨区
- provincial_admin 能看全局
- common 只能看自己

## 阶段 E：安全与运维收口

### E1. 密码升级方案

- 兼容旧明文
- 新密码写哈希
- 后续批量升级

### E2. 审计日志

至少记录：

- 登录成功/失败
- 角色变更
- 用户地区变更
- 权限分配变更

### E3. 文档留档

要把以下文档保持最新：

- `docs/用户与地区权限完整设计方案.md`
- `docs/接口/用户权限与权限点清单.md`
- `docs/用户权限开发TaskList.md`

---

## 8. 推荐的实际开发顺序

如果按“马上开始干”的节奏，建议严格按下面顺序：

1. 先检查当前库真实 RBAC 表结构
2. 再把初始化 SQL 改成真实可执行版
3. 再改登录与 JWT
4. 再补 `/api/auth/me`
5. 再做权限聚合与数据范围注入
6. 再做老用户迁移脚本
7. 最后再做密码升级和审计收口

这个顺序的原因很简单：

- 不先确认表结构，后面代码全会写偏
- 不先收口登录态，前端无法稳定接入
- 不先做数据范围，地区隔离只是纸面方案
- 不最后做迁移，容易把脏数据带着跑

---

## 9. 我建议下一步立刻做什么

下一步最应该做的不是直接改 controller，而是：

### 第一步

先把**当前数据库里 7 张核心表的真实结构**完整导出来：

- `sso_users`
- `roles`
- `user_role`
- `permissions`
- `role_permissions`
- `sys_routes`
- `role_route`

### 第二步

基于真实结构，产出两份正式 SQL：

- schema patch SQL
- seed SQL

### 第三步

再开始改：

- `authServiceImpl.py`
- `jwtService.py`
- `/api/auth/me`

也就是说，**下一阶段开发入口就是“数据库真相收口”**。