IWish Auth开发者文档
V1 Alpha GitHub
AI Agent/AI Agent 接入指南

AI Agent 接入指南

让 AI 按确定契约完成 App 改造

AI Agent 接入指南

本指南约束使用 AI 改造业务 App 时的执行边界。Agent 必须先读取 /llms-full.txt、/openapi.json、/auth-manifest.schema.json 和目标仓库现有授权实现，不得根据旧版本记忆猜测 API。

执行顺序

  1. 识别技术栈、服务端入口、数据库、部署方式和测试命令。
  2. 搜索旧登录、密码、session、用户主键、引用用户的业务外键、角色、permission、数据范围和管理员 UI。
  3. 选择接入档案：没有需要保留的生产账号和身份数据时使用 greenfield；已有生产用户、角色、业务外键或旧 Session 时使用 legacy-migration。
  4. 把内容分成“统一身份/公共上下文”和“App 本地业务授权”，记录边界。
  5. 创建 Manifest 2.0，authorizationMode=application_owned，只声明 requiredContext。
  6. 安装 SDK 0.3，接入服务端 login、callback、logout、PKCE、HttpOnly Cookie 和 requireAppAccess。
  7. greenfield：建立新数据库和本地成员/角色；管理员从受控 Auth 目录选择身份并原子分配角色。
  8. legacy-migration：生成迁移计划 1.0、inventory 和私有 mapping ledger；production 切换前完成存量账号预绑定。
  9. 使用 session.user.id 命中 iwish_auth_user_id；legacy-migration 必须保留原本地用户主键和业务外键。
  10. 保留或重建 App 本地角色、permission、数据范围、管理 UI 和本地审计。
  11. 仅在业务需要时消费 employee、departments 和 clientAssignments。
  12. 在独立 staging 完成对应档案的真实 SSO 和负向验收；只有 legacy-migration 执行旧 Session 失效、回滚和一刀切。

禁止事项

  • 不创建 Auth Proxy、长期双登录或第二套内部员工密码。
  • 不直接接飞书、Supabase Auth 或 Auth 数据库。
  • 不自行解析 opaque App Session，不信任 x-user-id 或 x-role。
  • 不在 Auth Manifest 中创建业务 roles/permissions。
  • 不调用已返回 410 的 requirePermission、checkPermission 或远程业务权限 API。
  • 不删除 App 本地角色、字段、记录归属和数据范围授权。
  • 不用 Auth User ID 替换项目负责人、创建人、审批人等业务外键。
  • 不在运行期按邮箱、姓名或手机号自动关联存量账号。
  • 不为未映射存量用户自动创建一个没有历史数据的新账号。
  • 不要求管理员手工复制 Auth User ID。
  • 不在第一次登录时自动授予 admin/viewer 或创建无角色成员。
  • 不为 greenfield 伪造 migration plan、mapping ledger 或历史账号。
  • 不用 clientAssignments 代替 App 本地 permission 或高风险业务授权。
  • 不把 Client Secret、Service Token、Webhook Secret 或 production 数据写入文档和提交。

交付格式

Agent 输出必须包含：接入档案、改动文件、身份边界、本地成员模型、本地角色模型、服务端保护点、上下文消费点、环境变量名、测试结果、已知风险和回滚步骤。只有 legacy-migration 需要业务外键清单、迁移计划、映射计数和冲突清单位置；greenfield 必须明确说明这些工件不适用。Manifest 和适用的迁移计划必须可由当前 Schema/CLI 直接验证。逐用户映射、PII 和 Secret 不得出现在输出正文或 Git。

身份：IWish Auth App Session 0.3
关联：session.user.id -> app_members.iwish_auth_user_id
授权：App 本地角色 + permission + 数据范围
上下文：employee / departments / clientAssignments（按需）
档案：greenfield 或 legacy-migration
迁移：仅 legacy-migration 执行 staging -> 真实验收 -> production 一刀切

自检问题

  1. 所有身份恢复是否来自 IWish Auth session introspection？
  2. 浏览器是否能读取任何 Secret 或 opaque session？
  3. 无本地成员、停用或无角色是否默认 403？
  4. 每个高风险服务端动作是否执行本地 permission 和数据范围检查？
  5. assignment 存在但本地权限不足是否仍拒绝？
  6. assignment 为空是否不会自动全量授权？
  7. 飞书离职后即使本地角色仍存在是否不能访问？
  8. 所有 API 和字段是否存在于 OpenAPI、Schema 或 SDK 导出？
  9. 原本地用户主键和所有业务外键是否保持不变？
  10. production 切换前冲突和待处理账号是否为 0？
  11. 未映射用户是否明确失败，而不是创建空账号？
  12. greenfield 是否通过受控目录创建成员，而不是手工 User ID 或首次登录自动授权？
  13. 当前 App 是否确实需要迁移工件，还是应该使用 greenfield？

任何答案不明确时，Agent 应停止发布并补充测试，不能通过放宽 CORS、callback、Cookie Domain 或错误降级来绕过。