leaudit-platform-backend/docs/迁移与兼容/老用户迁移脚本说明.md

老用户迁移脚本说明

这份说明对应两个文件：

• scripts/migrate_legacy_users.py
• scripts/创建sql/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

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 正式执行迁移

python3 scripts/migrate_legacy_users.py --apply

---

5. 迁移前审计 SQL

如果你想先单独跑审计，用这个：

psql -h 172.16.0.81 -p 54302 -U docauditai_admin -d docauditai -f scripts/创建sql/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/创建sql/user_rbac_schema_patch.sql 已执行
2. 确认 scripts/创建sql/user_rbac_seed.sql 已执行
3. 先跑 scripts/创建sql/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