TanWenyan/leaudit-platform-backend

Fork 0

Files

T

wren c9d7a693b8 docs: reorganize by module

2026-05-09 20:04:08 +08:00

3.9 KiB

Raw Blame History

老用户迁移脚本说明

这份说明对应两个文件：

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，不写入。

它会：

连接老库 docauditai
连接新库 leaudit_platform
读取老库 sso_users
读取老库 user_role + roles
按新系统允许的角色集合收口：
- provincial_admin
- admin
- common
- super_admin
如果老用户没有角色，则自动指定 common
迁移 sso_users
迁移 user_role
重置新库 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/user_rbac_migration_audit.sql

它会检查：

用户总数
地区分布
重复 sub
重复 username
空地区用户
无角色用户
脏 user_role
脏 role_permissions
脏 role_route

6. 当前不迁什么

这版脚本当前不迁：

permissions
role_permissions
sys_routes
role_route

原因不是不能迁，而是：

新系统已经有自己当前阶段的 seed 权限集
当前最急的是先把“用户能登录、能识别角色、能拿到地区”打通

也就是说，这一版脚本优先解决：

用户主数据迁入
默认角色补齐
登录可用

7. 推荐执行顺序

建议严格按这个顺序：

确认 scripts/user_rbac_schema_patch.sql 已执行
确认 scripts/user_rbac_seed.sql 已执行
先跑 scripts/user_rbac_migration_audit.sql
再跑 python3 scripts/migrate_legacy_users.py 做 dry-run
最后跑 python3 scripts/migrate_legacy_users.py --apply

8. 下一步衔接

老用户迁进去之后，下一步应该继续做：

用新迁入用户实际验证 /auth/login 和 /auth/me
把文档列表、评查结果接口接上 ALL / DEPT / SELF 数据范围控制
再决定是否迁移老库的完整 permissions / role_permissions / sys_routes / role_route

3.9 KiB Raw Blame History