baa-conductor

T-003-control-api.md

 1---
 2task_id: T-003
 3title: Control API Worker
 4status: done
 5branch: feat/T-003-control-api
 6repo: /Users/george/code/baa-conductor
 7base_ref: main@56e9a4f
 8depends_on:
 9  - T-002
10write_scope:
11  - apps/control-api-worker/**
12updated_at: 2026-03-21
13---
14
15# T-003 Control API Worker
16
17## 目标
18
19实现 Cloudflare Worker 风格的 control API 骨架，把设计中的关键接口落成代码结构。
20
21## 统一开工要求
22
23- 必须从 `main@56e9a4f` 切出该分支
24- 新 worktree 进入后先执行 `npx --yes pnpm install`
25- 不允许从其他任务分支切分支
26
27## 本任务包含
28
29- 明确路由注册方式
30- 为核心接口建立 handler 骨架
31- 整理 request/response schema
32- 预留 D1 绑定与鉴权挂载点
33
34## 本任务不包含
35
36- 完整 lease 算法
37- 真实 worker 调度
38- 前端页面
39
40## 建议起始文件
41
42- `apps/control-api-worker/src/index.ts`
43- `DESIGN.md` 第 11 节
44
45## 交付物
46
47- 可扩展的 Worker 路由骨架
48- 核心接口清单与占位 handler
49
50## 验收
51
52- 至少包含 heartbeat、acquire、tasks、steps、system state 路由骨架
53- 结构上便于后续接 D1
54
55## files_changed
56
57- `apps/control-api-worker/src/index.ts`
58- `apps/control-api-worker/src/contracts.ts`
59- `apps/control-api-worker/src/schemas.ts`
60- `apps/control-api-worker/src/handlers.ts`
61- `apps/control-api-worker/src/router.ts`
62- `apps/control-api-worker/tsconfig.json`
63- `coordination/tasks/T-003-control-api.md`
64
65## commands_run
66
67- `npx --yes pnpm install`
68- `npx --yes pnpm --filter @baa-conductor/control-api-worker typecheck`
69- `npx --yes pnpm --filter @baa-conductor/control-api-worker build`
70
71## result
72
73- 已将 `control-api-worker` 重构为 Cloudflare Worker 风格入口，提供默认 `fetch` 导出、请求 ID、统一 JSON 错误包和基础 404/405/400 处理。
74- 已注册设计第 11 节要求的核心路由骨架，覆盖 controller heartbeat、leader acquire、tasks、steps、system state，以及 task/log/run 查询接口。
75- 已整理每条路由的 request/response schema 描述，并预留 D1 repository 注入与 Bearer token 鉴权挂载点，便于 `T-004` 与 `T-010` 继续接线。
76
77## risks
78
79- 所有业务 handler 目前仍返回 `501 not_implemented`，真实 lease、claim、checkpoint、task 读写逻辑尚未接入 D1。
80- 当前只做 JSON 解析与授权挂点，没有做字段级 runtime 校验；后续接真实写路径时需要补请求校验或约束收口。
81- 未注入 `tokenVerifier` 时会跳过实际鉴权，仅保留授权模型上下文；生产接入前必须补齐 verifier 装配。
82
83## next_handoff
84
85- `T-004` 可直接在现有 route registry 上接 leader/task/step 写路径，复用 ownership resolver、auth hook 和 repository 注入点。
86- `T-010` 可直接复用 `GET /v1/system/state`、`GET /v1/tasks/:task_id`、`GET /v1/tasks/:task_id/logs`、`GET /v1/runs/:run_id` 的接口合同与统一响应结构。
87
88## notes
89
90- `2026-03-21`: 创建任务卡
91- `2026-03-21`: 实际按指令从 `main@56e9a4f` 切出，任务卡已同步该基线。