新应用接入

本指南适用于 greenfield：业务 App 没有需要保留的生产账号、本地身份主键、历史身份外键或旧 Session。新应用从第一天使用 IWish Auth 作为唯一身份来源，但业务成员、角色、permission、字段和数据范围仍由 App 自己管理。

1. 数据模型

新应用使用自己的数据库，并至少建立本地成员、角色分配和授权审计：

app_members
  id
  iwish_auth_user_id  # 唯一，不建立跨数据库外键
  status
  created_at

app_member_roles
  member_id
  role_id
  assigned_by
  assigned_at

iwish_auth_user_id 来自受控 Auth 身份目录或经过验证的 App Session，不允许管理员手工复制粘贴 User ID。业务表继续引用 App 自己的 app_members.id，不要把 Auth User ID 扩散为所有业务外键。

2. 成员开通

标准流程是“管理员明确选择身份并分配本地角色”：

App 管理员打开业务 App 自己的成员管理页面。
App 服务端使用最小权限 Service Token 查询当前组织的 Auth 受控身份目录。
管理员选择一个 active 用户，并选择 App 本地角色。
App 在单个事务中创建成员、角色分配和 append-only 审计。
用户通过 IWish Auth SSO 登录；requireAppAccess 成功后，App 按 session.user.id 加载本地成员。

第一次登录不能自动授予 admin、viewer 或其他角色，也不能创建一个没有角色但能进入业务数据的空成员。首个 App 管理员必须通过受控 bootstrap、部署审批或双人复核创建，不能采用“第一个登录的人自动成为管理员”。

3. SSO 与本地授权

Manifest 2.0 固定使用 authorizationMode=application_owned。服务端接入 PKCE login、callback、HttpOnly Cookie、App Session 0.3、requireAppAccess 和登出。每个业务请求按以下顺序处理：

Auth Session -> App access -> 员工状态 -> App 本地成员
-> App 本地角色与 permission -> 字段/记录/数据范围 -> 业务响应

employee、departments 和 clientAssignments 是统一上下文，不是业务 permission。App 可以用客户项目分工做默认筛选、工作台入口或流程路由，但敏感查询、编辑、导出和审批必须再次执行 App 本地授权。

4. 不需要迁移工件

greenfield 不生成 auth-migration-plan.json、mapping ledger、旧密码清理计划或旧 Session 回滚演练。不要为了通过模板而伪造存量账号和迁移数据。只有已经拥有真实生产用户、角色、业务外键和历史数据的 App 才使用 legacy-migration。

新应用仍需创建独立 dev、staging、prod OAuth Client、callback 和 Secret，并在 staging 验证飞书员工、外部邮箱、无本地成员、成员停用、角色撤销、跨 App Session、离职和全局登出。

5. 完成标准

业务 App 没有本地登录、第二套员工密码或直接飞书接入。
浏览器无法读取 Client Secret 或 opaque App Session。
管理员不需要手工输入 Auth User ID。
无本地成员、成员停用、无角色和权限不足全部 fail closed。
首次登录不会自动创建 admin/viewer 或扩大权限。
本地角色变化立即生效，Auth 客户项目上下文变化不会静默扩大权限。
飞书离职、Auth 停用、组织停用或关闭 App 后，即使本地角色仍存在也不能访问。
接入实现只依赖公开 SDK、OpenAPI、Manifest Schema 和文档，不读取 Auth 仓库源码。

下一步阅读接入流程、快速开始和接入验收清单。存量系统请改用存量账号迁移与无感切换。