接入流程

1. 职责边界

参与方	负责内容
IWish Auth 平台管理员	App 注册、组织开通、OAuth Client、callback、Manifest、飞书目录、客户项目和平台内部权限
业务 App 开发者	SSO 接入、本地成员、本地角色、本地权限、业务数据范围和本地审计
业务负责人	确认本地角色颗粒度、敏感动作、数据隔离和迁移窗口

Auth 是统一身份和公共上下文来源，不是所有业务 App 的业务授权中心。appKey=auth 的角色权限仅用于 Auth 管理后台。

2. 先选择接入档案

档案	适用条件	身份关联方式	迁移工件
`greenfield`	没有需要保留的生产账号、身份外键和旧 Session	管理员从受控 Auth 目录选择用户并创建 App 本地成员	不需要
`legacy-migration`	已有生产用户、角色、业务外键和历史数据	切换前把 Auth User ID 预绑定到原本地成员	Migration Plan 1.0 + 私有 ledger

不得把新应用伪装成存量迁移，也不得把真实存量应用当作新应用自动创建空账号。

3. 两条标准顺序

greenfield：

创建新 App 数据库和独立 staging。
创建 Manifest 2.0、App 注册、组织开通、OAuth Client 和精确 callback。
App 服务端接入 PKCE、callback、HttpOnly Cookie、session introspection 和登出。
建立本地成员、角色、permission 和 append-only 授权审计。
App 管理员从受控身份目录选择用户并在一个事务中分配本地角色。
验证首次登录不自动创建 admin/viewer，无本地成员和无角色均 fail closed。

legacy-migration：

盘点旧登录、用户主键、业务外键、角色、权限、字段规则和数据范围。
创建独立 staging，禁止直接修改 production 数据。
完成共享的 Manifest、OAuth Client 和 SSO 接入。
生成迁移计划 1.0 和私有 mapping ledger，在切换前预绑定存量用户。
保留本地用户主键、业务外键、角色与权限；所有服务端动作 fail closed。
验证预绑定用户命中原账号、原角色和原业务数据。
完成 staging、回滚和切换闸门后，一刀切关闭旧登录、本地密码和旧 Session。

4. 数据流

飞书 / 外部邮箱 -> IWish Auth -> 一次性授权码 + PKCE
-> 业务 App 服务端 callback -> opaque App Session 0.3
-> iwish_auth_user_id -> App 本地成员 -> App 本地角色与权限
-> 业务数据范围检查 -> 返回结果

iwish_auth_user_id 只用于稳定定位原本地成员。项目负责人、创建人、审批人和审计记录继续引用 App 原用户主键，不替换为 Auth User ID。运行期禁止按邮箱自动合并存量账号。

Manifest 2.0 的 authorizationMode 固定为 application_owned。Auth Session 不返回业务 roles 或 permissions。业务 App 不上传本地角色树，也不调用 Auth 远程权限判断接口。

5. 客户项目上下文

飞书同步提供公司部门和员工目录；Auth 管理员独立创建客户项目，并把 active 员工按销售、技术、运营、优化师等职责绑定到项目。业务 App 可从 clientAssignments 读取当前员工参与的项目和职责，用于默认筛选、工作台入口或流程路由。最终是否能查看、编辑、导出某条业务数据，仍由 App 本地授权和数据规则判断。

6. 禁止事项

业务 App 直接接飞书、Supabase Auth 或 Auth 数据库。
信任 x-user-id、x-role 等浏览器可伪造 Header。
在前端保存 Client Secret 或 opaque App Session。
把 Auth 员工状态、本地角色或项目分工混成一个布尔值。
为业务 App 在 Auth 创建业务角色、权限节点或用户角色映射。
多个 App 共用 OAuth Client、callback 或 session cookie。
让管理员手工复制 Auth User ID，或首次登录自动授予 admin/viewer。

失效链路必须覆盖用户停用、员工离职、组织停用、App 关闭、OAuth Client 停用、单 App 登出和全局登出；本地成员停用和本地角色撤销则由业务 App 自己立即生效。