迁移指南

IWish Auth 采用一刀切迁移，不提供 Auth Proxy 或长期双登录。迁移需要先在 staging 完整验收，再在单个 App 的维护窗口直接切换。

1. 迁移前盘点

建立清单：

• 本地用户表、密码字段、session 表和登录入口。
• 本地角色、权限节点、路由守卫和前端可见性判断。
• 用户与员工、部门、客户或项目的映射。
• 服务账号、定时任务和 API token。
• 登录相关邮件、找回密码、邀请和管理员页面。
• 所有 callback、域名、反向代理和 cookie 设置。

2. 权限映射

不要直接把旧角色名当成新 permission。先把每个受保护业务动作映射为 {app}.{resource}.{action}，再把权限组合成 App 角色。

旧判断	新权限	备注
role === "sales" 可看联系人	crm.contact.read	角色成为 crm.sales 模板
isAdmin 可导出	crm.contact.export	高风险动作独立授权
负责 Acme 项目	不做 permission	使用 clientAssignments + 业务数据授权

3. 建立接入配置

1. 确定 appKey 和 Manifest。
2. 在 dev 同步 Manifest。
3. 创建 dev OAuth client 和精确 callback。
4. 给试点组织开通 App。
5. 给试点用户分配角色。

4. 替换登录

• 新增 /auth/login、/auth/callback、/auth/logout。
• 使用 SDK 创建 App session。
• 把全部受保护服务端路由迁移到 requireAuth / requireAppAccess。
• 删除或禁用本地登录、注册、找回密码和管理员重置密码入口。
• 删除浏览器可访问的 client secret 或 Supabase 配置。

外部账号的邀请和邮箱密码登录发生在 IWish Auth Portal，不在业务 App 重建。

5. 替换权限

• 把服务端本地角色判断替换为 requirePermission。
• 前端菜单可根据 session permissions 隐藏，但服务端必须再次检查。
• 移除本地统一角色分配写入口。
• 保留业务记录归属、字段级规则和客户数据过滤。
• 按需消费 clientAssignments，不强制所有 App 使用。

6. 用户映射

内部员工以飞书身份为准，使用 IWish Auth user.id 作为跨 App 稳定主体。旧 App 需要建立一次性 legacy_user_id -> iwish_user_id 映射，不得根据邮箱在请求时动态猜测。

外部账号由管理员邀请或创建，明确映射后再开放业务数据。

7. 切换策略

在 staging 完成所有验证后：

1. 冻结旧用户和角色管理写入。
2. 导入并复核用户映射。
3. 同步 prod Manifest，创建 prod OAuth client。
4. 部署新版本并切换登录入口。
5. 立即运行未登录、登录、权限、登出和关键业务 smoke test。
6. 观察 Auth 错误率和业务关键指标。
7. 在确认窗口结束后删除旧密码和 session 数据。

8. 回滚边界

回滚是应用版本回滚，不是长期双系统。回滚包必须在切换前准备，并包含：

• 上一个应用版本。
• 配置和 callback 回滚步骤。
• 数据写入兼容说明。
• 触发阈值和负责人。

已经删除的密码不能恢复。若必须回滚到旧登录，应在迁移前明确安全批准和短时恢复方案。

9. 迁移完成证据

• 旧登录和本地角色写入口不可访问。
• 关键路由使用 SDK 权限检查。
• Manifest、OAuth client 和角色分配有审计记录。
• 内部员工飞书登录、外部账号邮箱登录均通过。
• 角色撤销、员工离职和 App 停用能使访问失效。
• 业务数据授权和客户项目范围没有扩大。
• 密钥扫描、回归、监控和回滚演练通过。