TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: reorganize by module

Browse Source
This commit is contained in:
wren
2026-05-09 20:04:08 +08:00
parent 29873eaecd
commit c9d7a693b8
23 changed files with 2161 additions and 197 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/迁移与兼容/历史API与权限文档索引.md
+30
View File
@@ -0,0 +1,30 @@
# 历史 API 与权限文档索引
> 最后整理：2026-05-04
> 说明：`new_doc_review/auth_doc/` 目录以历史阶段的 API、RBAC、前端对接快照为主，适合补背景，不适合作为当前系统唯一事实来源。
## 使用方式
- 当前主链路以 `docs/HANDOFF.md` 与 `docs/迁移与兼容/旧接口文档导航.md` 为准
- `new_doc_review/auth_doc/` 里的文档，多数写于旧接口或 PostgREST 仍是主依赖的时期
- 若历史文档与现网代码冲突，以现网代码和主文档为准
## 建议优先查阅的历史文档
| 主题 | 文档 | 说明 |
|------|------|------|
| RBAC 总说明 | `new_doc_review/auth_doc/RBAC_API_GUIDE_V3.4.md` | 当前最接近可用的 RBAC API 总览 |
| RBAC 历史全量设计 | `new_doc_review/auth_doc/RBAC_COMPLETE_GUIDE_V3.3.md` | 适合追溯设计演进 |
| 入口模块 API | `new_doc_review/auth_doc/ENTRY_MODULE_API.md`、`new_doc_review/auth_doc/entry_modules_api.md` | 入口模块旧接口资料 |
| 文档类型 API | `new_doc_review/auth_doc/document_types_api.md` | 文档类型早期接口说明 |
| 评查点前端接口 | `new_doc_review/auth_doc/review_points_api_frontend.md` | 评查点老链路前端接口说明 |
| 交叉评查 | `new_doc_review/auth_doc/交叉评查接口文档.md`、`new_doc_review/auth_doc/交叉评查接口对接状态报告.md` | 交叉评查历史对接资料 |
| 路由 / 共享权限 | `new_doc_review/auth_doc/通用权限前端对接文档.md`、`new_doc_review/auth_doc/通用权限前端对接文档(1).md`、`new_doc_review/auth_doc/角色-路由权限实现方案.md` | 一个是 RBAC 总对接文档，一个是共享权限专项说明，一个是后端设计说明 |
## 本次清理
- 已删除被新版覆盖或明显重复的副本：
- `new_doc_review/auth_doc/entry_modules_api(1).md`
- `new_doc_review/auth_doc/交叉评查接口文档(1).md`
- `new_doc_review/auth_doc/API_RESPONSE_EXAMPLES_V3.2.md`
- 保留 `new_doc_review/auth_doc/API_RESPONSE_EXAMPLES_V3.3.md` 作为现存最新响应示例
docs/迁移与兼容/旧接口文档导航.md
+39
View File
@@ -0,0 +1,39 @@
# 旧接口文档导航（已归档）
> 最后更新：2026-05-09
> 说明：原 `docs/接口/` 目录已按模块拆分。本文只保留“旧分类到新位置”的映射，避免老链接失效后找不到文档。
## 旧目录去向
| 旧分类 | 新位置 |
|---|---|
| 接口总导航 | `docs/README.md` |
| 首页入口 / 菜单 | `docs/入口模块/` |
| 文档上传 / 列表 / 评查 | `docs/文档管理/` |
| 文档类型 / 评查点分组 | `docs/评查点分组/` |
| 系统使用统计 | `docs/系统使用统计/` |
| 权限 / 路由 / 初始化 SQL | `docs/权限与地区隔离/` |
| RAG 聊天 | `docs/RAG/` |
| 用户迁移 / 历史资料 | `docs/迁移与兼容/` |
## 旧文档对应新路径
- `入口模块绑定最终设计方案.md` → `docs/入口模块/入口模块绑定最终设计方案.md`
- `文档上传与列表接口分析.md` → `docs/文档管理/文档上传与列表接口分析.md`
- `评查点分组目标结构与迁移方案.md` → `docs/评查点分组/评查点分组目标结构与迁移方案.md`
- `评查点分组迁移执行前检查清单.md` → `docs/评查点分组/评查点分组迁移执行前检查清单.md`
- `旧规则绑定表下线观察与删表草案.md` → `docs/评查点分组/旧规则绑定表下线观察与删表草案.md`
- `系统使用统计最终需求.md` → `docs/系统使用统计/系统使用统计最终需求.md`
- `系统使用统计接口设计.md` → `docs/系统使用统计/系统使用统计接口设计.md`
- `系统使用统计表设计.md` → `docs/系统使用统计/系统使用统计表设计.md`
- `系统使用统计开发任务拆解.md` → `docs/系统使用统计/系统使用统计开发任务拆解.md`
- `用户权限与权限点清单.md` → `docs/权限与地区隔离/用户权限与权限点清单.md`
- `用户权限初始化SQL.sql` → `docs/权限与地区隔离/用户权限初始化SQL.sql`
- `RAG聊天接口.md` → `docs/RAG/RAG聊天接口.md`
- `老用户迁移脚本说明.md` → `docs/迁移与兼容/老用户迁移脚本说明.md`
## 使用建议
- 日常开发不要再新增 `docs/接口/` 这种“文档类型目录”
- 以后统一按模块建目录、按模块归档
- 如果某个新文档同时涉及多个模块，优先放主要责任模块目录，并在 `docs/README.md` 里补导航
docs/迁移与兼容/老用户迁移脚本说明.md
+190
View File
@@ -0,0 +1,190 @@
# 老用户迁移脚本说明
这份说明对应两个文件：
- `scripts/migrate_legacy_users.py`
- `scripts/user_rbac_migration_audit.sql`
目标很明确：
- 把老系统 `docauditai` 的用户主数据迁到新系统 `leaudit_platform`
- 当前先迁：`sso_users` + `user_role`
- 新系统角色基础数据使用当前新库已经初始化好的 `roles`
---
## 1. 为什么现在先这样迁
当前真实情况是：
- 老库 `sso_users = 4106`
- 老库 `user_role = 11`
- 也就是大多数老用户没有显式角色记录
所以这次迁移不能只“复制 user_role”，还必须带一条默认规则：
- 老用户没有角色时，自动落到 `common`
这正是 `scripts/migrate_legacy_users.py` 已经处理好的逻辑。
---
## 2. 脚本会做什么
脚本默认只做 dry-run，不写入。
它会：
1. 连接老库 `docauditai`
2. 连接新库 `leaudit_platform`
3. 读取老库 `sso_users`
4. 读取老库 `user_role + roles`
5. 按新系统允许的角色集合收口：
- `provincial_admin`
- `admin`
- `common`
- `super_admin`
6. 如果老用户没有角色，则自动指定 `common`
7. 迁移 `sso_users`
8. 迁移 `user_role`
9. 重置新库 `sso_users.id` 序列
---
## 3. 脚本的关键规则
## 3.1 保留老用户 ID
脚本会尽量保留老库 `sso_users.id` 写入新库。
这样做的好处是：
- 后续如果业务表开始引用用户 ID，语义更稳定
- 后台排查时新旧库用户编号一致，方便核对
## 3.2 地区字段只认 `area`
迁移时：
- 会把老库 `sso_users.area` 带到新库
- 并做基础 trim / 别名归一化
## 3.3 无角色用户自动补 `common`
这是当前最重要的迁移策略。
因为老库 4106 个用户里，4098 个没有显式 `user_role`。
如果不补：
- 新系统大量用户会迁过去但无法使用
## 3.4 幂等设计
脚本不是只适合跑一次。
它支持：
- `sub` 已存在时更新用户资料
- `user_role` 已存在时跳过重复插入
所以可以重复执行。
---
## 4. 使用方式
## 4.1 先做 dry-run
```bash
python3 scripts/migrate_legacy_users.py
```
我已经实际跑过 dry-run，当前输出结果是：
- `legacy_users_total: 4106`
- `default_common_role: 4098`
- `insert_user: 4106`
- `admin: 4`
- `common: 4101`
- `provincial_admin: 1`
- `id_conflicts: 0`
这说明：
- 迁移逻辑当前是通的
- 角色映射结果和老库真实分布一致
- 当前没有发现 ID 冲突
## 4.2 正式执行迁移
```bash
python3 scripts/migrate_legacy_users.py --apply
```
---
## 5. 迁移前审计 SQL
如果你想先单独跑审计，用这个：
```bash
psql -h 172.16.0.81 -p 54302 -U docauditai_admin -d docauditai -f scripts/user_rbac_migration_audit.sql
```
它会检查：
- 用户总数
- 地区分布
- 重复 `sub`
- 重复 `username`
- 空地区用户
- 无角色用户
- 脏 `user_role`
- 脏 `role_permissions`
- 脏 `role_route`
---
## 6. 当前不迁什么
这版脚本当前不迁：
- `permissions`
- `role_permissions`
- `sys_routes`
- `role_route`
原因不是不能迁，而是：
- 新系统已经有自己当前阶段的 seed 权限集
- 当前最急的是先把“用户能登录、能识别角色、能拿到地区”打通
也就是说，这一版脚本优先解决：
- 用户主数据迁入
- 默认角色补齐
- 登录可用
---
## 7. 推荐执行顺序
建议严格按这个顺序：
1. 确认 `scripts/user_rbac_schema_patch.sql` 已执行
2. 确认 `scripts/user_rbac_seed.sql` 已执行
3. 先跑 `scripts/user_rbac_migration_audit.sql`
4. 再跑 `python3 scripts/migrate_legacy_users.py` 做 dry-run
5. 最后跑 `python3 scripts/migrate_legacy_users.py --apply`
---
## 8. 下一步衔接
老用户迁进去之后，下一步应该继续做：
1. 用新迁入用户实际验证 `/auth/login` 和 `/auth/me`
2. 把文档列表、评查结果接口接上 `ALL / DEPT / SELF` 数据范围控制
3. 再决定是否迁移老库的完整 `permissions / role_permissions / sys_routes / role_route`