# 老用户迁移脚本说明

这份说明对应两个文件：

- `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`