# Feishu V1 Task Breakdown

状态：draft
最后更新：2026-03-22
依赖文档：

- `specs/organization/organization.md`
- `docs/vendor-profiles/feishu/README.md`
- `docs/vendor-profiles/feishu/mobile-auto-join-prerequisites.md`

## 总体目标

在不破坏现有 `workspace-first`、`unit -> team -> effective_grant` 的前提下，为 `agentteam-org` 落地 Feishu v1：

- 支持 Feishu 作为首个 `auth_provider`
- 支持 Feishu 作为首个 `directory_provider`
- 支持最小目录导入
- 支持基于 SSO / 已验证邮箱手机号的 organization auto-join

## 非目标

- 不完整镜像飞书通讯录全部资源
- 不把 org chart 回灌到 core
- 不在登录热路径里抓整棵通讯录
- 不因为自动加入 organization 而自动开放全部 workspace

## Step 1：sync provenance 基础骨架

目标：

- 先补通用 sync provenance，给后续 Feishu worker 一个稳定落点

计划：

- 建立 sync run / claim skeleton
- 让 `MarkOrganization*Synced` 能挂接 provenance
- 暴露最小 read-only explainability

验收标准：

- provider-linked team/unit/member 至少能追溯到最近一次 sync run

回归命令：

- `GOCACHE=/tmp/agentteam-go-cache go test ./agentteam-org ./internal/appapi -parallel 1`
- `cd web && npm run build`

预期 commit：

- `add org sync provenance skeleton`

## Step 2：Feishu binding 与 provider 配置

目标：

- 让 organization 能声明 Feishu 作为 auth/directory vendor，并保存最小 tenant/app/root-department 配置

计划：

- 新增 provider binding / sparse settings 模型
- 区分 `auth_provider` 与 `directory_provider`
- 保存 root department 列表
- 明确 directory token 获取方式与 secret 管理

验收标准：

- organization 能稳定保存 Feishu profile 配置
- 不需要把 vendor-specific 字段暴露给 core

回归命令：

- `GOCACHE=/tmp/agentteam-go-cache go test ./agentteam-org ./internal/appapi -parallel 1`
- `cd web && npm run build`

预期 commit：

- `add feishu provider config skeleton`

## Step 3：auth-binding / directory-binding 分离

目标：

- 防止把 Feishu 认证键和目录键混成同一个 `external_id`

计划：

- 为 auth-binding 建独立存储
- 定义目录对象继续使用 `external_provider/external_id`
- 明确 `user_id`、`open_id`、`union_id` 的使用边界

验收标准：

- 目录同步主键可稳定使用 `user_id` / `open_department_id`
- 登录绑定可单独保存 Feishu auth 侧身份

回归命令：

- `GOCACHE=/tmp/agentteam-go-cache go test ./agentteam-org ./internal/appapi -parallel 1`

预期 commit：

- `separate feishu auth and directory bindings`

## Step 4：Feishu 目录导入 worker

目标：

- 以 `tenant_access_token` 为主，完成最小目录全量导入

计划：

- `department/get` 校验 root department
- `department/children` 递归拉部门树
- `user/find_by_department` 拉直属用户
- 写入 `organization_unit`
- 写入 `organization_member`
- 写入 `organization_member_unit_membership`
- 复用现有 reconcile 编译 grant

验收标准：

- 指定 root department 下的部门树和直属用户能稳定落地到本地投影
- 单父树、成员归属、状态门禁保持正确

回归命令：

- `GOCACHE=/tmp/agentteam-go-cache go test ./agentteam-org ./internal/appapi -parallel 1`
- `cd web && npm run build`

预期 commit：

- `add feishu directory import worker`

## Step 5：verified email/mobile bootstrap matching

目标：

- 让本地登录用户能用已验证邮箱/手机号命中唯一 Feishu directory user

当前状态（`2026-03-23`）：

- verified email bootstrap matching：completed
- verified mobile bootstrap matching：completed

计划：

- 封装 `user/batch_get_id` bootstrap 查询
- 只接受已验证 email/mobile
- 明确唯一命中与歧义处理
- 拒绝企业邮箱、未验证联系信息、非唯一匹配

验收标准：

- 命中唯一 directory user 时可完成 member bind
- 多命中或无命中时有清晰错误，不会加入错误 organization

回归命令：

- `GOCACHE=/tmp/agentteam-go-cache go test ./agentteam-org ./internal/appapi -parallel 1`

预期 commit：

- `add feishu bootstrap matching`

## Step 6：Feishu SSO auto-join

目标：

- 用户通过 Feishu SSO 或 verified email/mobile 登录后，可自动加入对应 organization

当前状态（`2026-03-23`）：

- Feishu SSO auto-join：completed
- verified email auto-join：completed
- verified mobile auto-join：completed

计划：

- 在登录后挂接 auth-binding / bootstrap matching
- 只做 organization member bind
- 不在登录热路径里全量同步目录
- 目录未完成时允许“先加入 organization，再等 sync 补齐 unit”

验收标准：

- 用户能自动进入正确 organization
- 不会自动拥有全部 workspace

回归命令：

- `GOCACHE=/tmp/agentteam-go-cache go test ./agentteam-org ./internal/appapi -parallel 1`
- `cd web && npm run build`
- `cd web && GOCACHE=/tmp/agentteam-go-cache npm run e2e -- e2e/org.spec.ts`

预期 commit：

- `add feishu org auto join`

## Step 6.1：mobile fallback auth prerequisites

目标：

- 完成 AgentTeam 通用 mobile identity / verification / login surface，并让 Feishu verified mobile fallback 可直接挂接到既有 auto-join contract

当前状态（`2026-03-23`）：completed

已落地：

- `users.mobile` / `users.mobile_verified_at`
- authenticated user mobile verification flow
- 兼容旧 `{ email, password }` wire contract 的 verified mobile login
- `FindUserByMobile` / `FindUserByLoginIdentifier`
- provider-local `batch_get_id.mobiles` auto-join

验收标准：

- verified mobile login 能稳定拿到本地 verified mobile identity
- 不把 Feishu provider 细节回灌到 core 通用 auth 模型

回归命令：

- `GOCACHE=/tmp/agentteam-go-cache go test ./agentteam-org ./internal/appapi -parallel 1`

预期 commit：

- `add mobile auth identity`

## Step 7：运维可见性与管理面

目标：

- 让管理员看得到 Feishu profile 状态、root department、最近同步结果与 auto-join 失败原因

计划：

- org settings 增加 vendor profile surface
- sync run / claim explainability 接到 UI
- 暴露 bootstrap / ambiguity / scope error

验收标准：

- 管理员能判断“为什么没同步进来”或“为什么没自动加入”

回归命令：

- `GOCACHE=/tmp/agentteam-go-cache go test ./agentteam-org ./internal/appapi -parallel 1`
- `cd web && npm run build`
- `cd web && GOCACHE=/tmp/agentteam-go-cache npm run e2e -- e2e/org.spec.ts`

预期 commit：

- `surface feishu sync and auto join status`