一刀切迁移 Playbook

本 Playbook 用于把已有业务 App 迁移到 IWish Auth SSO，同时保留 App 本地授权。所有演练先在独立 staging 完成，production 必须有明确变更窗口、负责人和回滚证据。

A. 基线

• 记录生产版本、数据库备份、用户数、本地成员数、角色数和关键权限测试。
• 列出旧登录、密码重置、session、身份 Header 与旁路入口。
• 列出本地角色、permission、字段和数据范围规则，不把它们迁入 Auth。
• 列出所有引用本地用户主键的业务外键和历史审计字段。
• 建立旧用户到 iwish_auth_user_id 的私有映射 ledger 和异常清单。
• 生成无 PII 的迁移计划 1.0，并运行 iwish-auth migration validate。

B. Staging 接入

• 创建 Manifest 2.0、独立 OAuth Client、精确 callback 和组织开通。
• 接入 PKCE、服务端 code exchange、HttpOnly Cookie、requireAppAccess、单 App/全局登出。
• 本地成员按 Auth ID 查找；无成员、停用、无角色一律 403。
• 预绑定用户 SSO 后命中原本地用户主键、原角色和原业务数据。
• 未映射用户不创建空账号；运行期邮箱关联已禁用。
• 恢复本地角色管理 UI、服务端 permission 与数据范围检查、变更审计。
• clientAssignments 仅按业务需要消费，不自动授权。

C. 真实验收

• 内部飞书员工和外部邮箱账号均完成 SSO。
• viewer/member/manager/admin 的页面、接口、字段、导出和设置规则通过。
• assignment 存在但本地权限不足 403；assignment 为空不扩大权限。
• 本地角色撤销立即生效；Auth 客户分工变化不修改本地角色。
• 专用飞书账号 active -> inactive/resigned 后新旧 session 都被阻断。
• callback 错误、code 重放、跨 App session 和伪造 Header 被拒绝。
• 本地用户 ID、项目负责人、创建人、审批人和历史审计前后一致。
• 旧登录和旧 Session 在模拟切换后不可继续使用。

D. 上线窗口

• 冻结身份映射和本地角色配置，确认 conflicts=0、pending=0，执行最终备份并记录 SHA256。
• 原子写入最终预绑定映射并校验唯一索引、总数和业务外键。
• 部署后关闭旧登录、本地密码和旧 session 接受路径。
• 验证真实登录、关键 API、本地管理员角色、登出和撤权。
• 监控 Auth 401/403、callback 错误和 App 本地授权拒绝率。

E. 回滚

回滚只恢复上一稳定部署和映射/数据库快照，不恢复长期双登录、Auth Proxy 或可伪造身份 Header。若 Auth 身份不可用，业务 App 应 fail closed。若仅本地映射或权限迁移错误，可回滚 App 代码和本地迁移数据，不需要修改 Auth 客户项目或飞书目录。

完成后进入至少 24 小时、推荐 168 小时观察期。观察期通过后才删除旧密码 hash、旧 Session 表和旧登录代码。归档配置、验证记录、审计日志、版本、负责人、异常账号与回滚结果；production Secret 和逐用户 PII 不得进入交接包。