存量应用迁移指南

本指南只适用于 legacy-migration。目标是把身份提供方统一到 IWish Auth，同时保留业务 App 对自身业务授权的所有权。不要把“统一登录”误解成“把所有角色搬到 Auth”。没有需要保留的生产账号和历史身份数据时，使用新应用接入，不要生成迁移计划或 mapping ledger。

1. 盘点

列出旧登录入口、密码与 session、用户主键、所有引用用户的业务外键、本地成员、角色、permission、字段规则、记录归属、客户范围、管理员界面和审计。标记哪些是身份事实，哪些是 App 业务规则。建立 staging 数据副本与回滚方案，production 暂不变更。

2. 身份关联

为本地成员增加唯一 iwish_auth_user_id，来源只能是 Auth 受控目录或 App Session 的 user.id。保留原本地用户主键和所有业务外键。通过私有 migration ledger 在切换前预绑定现有用户，人工处理邮箱冲突；运行时禁止按邮箱自动合并。内部员工不再维护本地密码，外部账号也只在 Auth 使用邀请与邮箱密码。

公开仓库只提交无 PII 的迁移计划 1.0，逐用户邮箱、姓名、Auth User ID 和匹配证据留在 App 私有数据库或加密离线工件。使用 iwish-auth migration validate 校验计数和切换闸门。

3. 保留本地授权

保留或重建 viewer/member/manager/admin、permission、数据范围和角色管理 UI。把旧授权逻辑整理成服务端统一函数，并增加无成员、停用、权限不足和越权测试。不要把本地角色上传到 Auth，也不要调用旧 requirePermission 或远程权限检查。

4. 接入 SSO

创建 Manifest 2.0、组织级 App 开通、OAuth Client 和 callback。接入 PKCE login/callback/logout、HttpOnly Cookie 和 requireAppAccess。随后按 iwish_auth_user_id 加载本地成员并执行本地授权。需要项目信息时读取 clientAssignments，但不把 assignment 直接作为高风险动作权限。

5. Staging 验收

验证真实飞书登录、外部邮箱登录、免重复登录、跨 App 隔离、无本地成员 403、本地角色变化、项目分工变化、员工离职、全局登出和错误 callback。对比迁移前后本地用户 ID、角色、项目负责人、创建人、审批人和历史审计。特别验证 assignment 存在但本地权限不足仍拒绝，以及 assignment 为空不会全量授权。

6. 一刀切上线

冻结成员和权限配置，确认冲突与待处理账号为 0，备份映射和本地授权数据，原子写入预绑定后部署新版本，并立即关闭旧登录入口、本地密码登录和旧 session 接受逻辑。保留本地角色管理，不删除业务授权表。监控 401/403、callback、无映射和本地授权拒绝率。出现身份级故障按上一部署和映射快照回滚；不得通过恢复长期双登录或信任伪造 Header 临时放行。

完成标准

所有身份只来自 Auth；所有业务授权只来自 App 本地；预绑定用户命中原本地用户和原业务数据；Auth 停用和离职能阻断访问；本地角色撤销能立即阻断业务动作；客户项目上下文变化不会静默扩大权限；Client Secret、App Session、逐用户映射和员工敏感字段没有泄漏。