Manifest 2.0

Manifest 是业务 App 向 IWish Auth 声明“我是谁、入口在哪里、需要哪些统一上下文”的机器契约。它不是业务角色树，也不承载页面、按钮、字段或数据范围权限。

{
  "$schema": "https://auth-docs-staging.iwishapp.cn/auth-manifest.schema.json",
  "schemaVersion": "2.0",
  "appKey": "crm",
  "name": "CRM 系统",
  "description": "销售客户关系管理",
  "appUrl": "https://crm-staging.example.com",
  "environment": "staging",
  "manifestVersion": "2026.07.22-1",
  "authorizationMode": "application_owned",
  "requiredContext": ["identity", "employee", "departments", "clientAssignments"]
}

字段说明

字段	规则
`schemaVersion`	当前公开版本固定为 `2.0`
`appKey`	全局唯一、全小写，发布后保持稳定
`name` / `description`	中文产品名称与用途说明
`appUrl`	HTTPS 业务入口；仅本地 dev 可按规则使用 localhost
`environment`	`dev`、`staging` 或 `prod`
`manifestVersion`	每次提交唯一，建议日期加序号
`authorizationMode`	业务 App 固定为 `application_owned`
`requiredContext`	`identity`、`employee`、`departments`、`clientAssignments` 的去重子集

identity 提供稳定用户身份；employee 提供飞书员工资料与在职状态；departments 提供部门链路；clientAssignments 提供客户项目与服务职责。业务 App 只声明确实会消费的上下文，字段为空或数组为空时必须正常处理。

明确禁止

Manifest 2.0 不允许 roles、permissions、Client Secret、数据库连接、环境密钥、真实客户 ID 或用户 ID。若提交这些字段，Schema 和 CLI 必须拒绝。业务 App 的 viewer/member/manager/admin 等角色应保存在业务 App 自己的数据库，由业务 App 自己提供管理界面、服务端检查和审计。

预检与同步

管理 API 为 POST /v1/admin/apps/{appKey}/manifest/validate 和 POST /v1/admin/apps/{appKey}/manifest/sync。同步请求必须显式包含 confirmed=true，并使用 Auth 管理员 Bearer Token 或具备 auth.manifest.write 的 Service Token。

iwish-auth manifest validate --file auth.manifest.json
iwish-auth manifest sync --file auth.manifest.json --confirm

预检差异只包含名称、描述、应用地址、授权模式和上下文增删。同步不会写入业务角色或权限表。生产同步应由具备 auth.manifest.write 的管理员或 Service Token 执行，并记录版本、环境、提交人和时间。

版本策略

新增上下文字段通常向后兼容；删除业务正在依赖的上下文需要先修改 App，再发布新 Manifest。appKey、授权模式语义或身份关联键不能静默变更。auth 自身使用独立的内部 Manifest 管理平台权限，不能套用业务 Manifest 2.0。