飞书身份边界

内部员工的飞书身份就是 IWish Auth 的统一员工身份。auth_users 只是权限、会话、审计和外键所需的不可见技术主体，管理后台不得要求维护第二套“Auth 内部员工账号”。业务 App 禁止直接接飞书，只能读取 IWish Auth 返回的稳定身份上下文。

1. 身份来源

飞书真实工作邮箱不作为内部身份主键。Auth 使用稳定飞书标识和受控 synthetic email，避免与外部邮箱身份错误合并。

Supabase Auth 的企业登录 provider 标识为 custom:feishu。该值只属于 IWish Auth 平台配置，业务 App 不得直接使用它发起飞书授权。

2. 飞书同步内容

IWish Auth 同步：

• 公司部门层级和部门状态。
• 员工、工号、职位、上级、部门关系和在职状态。
• 离职、冻结、未入职等状态变化。

同步采用全量分页、批次写入和成功后 finalize。任何分页或字段权限错误都不能把本轮未读到的员工误判为离职。

3. 业务 App 可以获取什么

App session 的 employee 可能包含：

{
  "feishuUserId": "ou_xxx",
  "openId": "ou_xxx",
  "unionId": "on_xxx",
  "employeeNo": "E1001",
  "workEmail": "staff@example.com",
  "jobTitle": "广告优化师",
  "managerUserId": "ou_manager",
  "departmentIds": ["od_marketing"],
  "departmentNames": ["广告投放部"],
  "employmentStatus": "active",
  "lastSyncedAt": "2026-07-20T08:00:00Z"
}

字段可能为 null 或空数组，业务 App 必须容忍。employmentStatus 不是权限，仍需检查 permissions。

4. 业务 App 禁止事项

• 不创建自己的飞书应用来完成统一登录。
• 不请求飞书 OAuth、通讯录或 tenant token。
• 不保存飞书 access token、refresh token、App Secret 或用户凭据。
• 不通过飞书邮箱自动合并外部账号。
• 不复制部门/员工为另一套可编辑主数据。
• 不通过直接查询 Auth/Supabase 表获取员工。

业务 App 只使用 IWish Auth SDK 返回的稳定上下文。是否展示部门、按部门筛选或使用职位属于业务 App 自身决策。

5. 离职与组织变化

员工离职或冻结后，IWish Auth 会使统一登录和 App session 失效，并停止返回有效 clientAssignments。业务 App 不应等待本地人工禁用。

部门调整会在后续 session 上下文中反映。业务 App 如果缓存部门用于报表，需要设置明确的同步/失效策略，不能把缓存作为身份来源。

6. 外部账号边界

外部客户不要求拥有飞书账号。管理员可以先独立创建客户项目，再按需邀请外部访问账号。外部账号是否能查看某个项目取决于 App 权限和业务 App 数据授权，不由“客户项目存在”自动推导。

7. 平台管理边界

飞书目录状态由 GET /v1/admin/feishu/status 查询，手动同步由受保护的 Admin API 发起。只读管理需要 auth.feishu.read，执行同步需要 auth.feishu.sync。这些权限只授予平台管理员，不属于业务 App Manifest。