baa-conductor

T-017-status-runtime.md

 1---
 2task_id: T-017
 3title: Status API 运行时入口
 4status: done
 5branch: feat/T-017-status-runtime
 6repo: /Users/george/code/baa-conductor
 7base_ref: main@c5e007b
 8depends_on:
 9  - T-010
10write_scope:
11  - apps/status-api/**
12updated_at: 2026-03-22
13---
14
15# T-017 Status API 运行时入口
16
17## 目标
18
19把 status-api 从“包内 handler 骨架”推进到“有可挂载运行时入口”的程度。
20
21## 统一开工要求
22
23- 必须从当前最新 `origin/main` 切出该分支
24- 新 worktree 进入后先执行 `npx --yes pnpm install`
25- 不允许从其他任务分支切分支
26
27## 本任务包含
28
29- 明确 status-api 对外入口
30- 整理 `GET /healthz`、`GET /v1/status`、`GET /v1/status/ui`
31- 提供最小 fetch handler 或 node server adapter
32
33## 本任务不包含
34
35- 修改 control-api-worker
36- 修改 conductor
37- 真实部署配置
38
39## 建议起始文件
40
41- `apps/status-api/src/index.ts`
42- `apps/status-api/src/service.ts`
43- `apps/status-api/src/render.ts`
44
45## 交付物
46
47- 可挂载的 status-api 入口
48- 更完整的 HTML/JSON 响应骨架
49
50## 验收
51
52- `npx --yes pnpm --filter @baa-conductor/status-api typecheck`
53- `npx --yes pnpm --filter @baa-conductor/status-api build`
54- 入口结构清晰，后续可直接接入 launchd 或本地 HTTP server
55
56## files_changed
57
58- `apps/status-api/package.json`
59- `apps/status-api/tsconfig.json`
60- `apps/status-api/src/contracts.ts`
61- `apps/status-api/src/index.ts`
62- `apps/status-api/src/runtime.ts`
63- `apps/status-api/src/service.ts`
64- `coordination/tasks/T-017-status-runtime.md`
65
66## commands_run
67
68- `npx --yes pnpm install`
69- `npx --yes pnpm --filter @baa-conductor/status-api typecheck`
70- `npx --yes pnpm --filter @baa-conductor/status-api build`
71- `node --input-type=module -e "import { createStatusApiRuntime } from './apps/status-api/dist/apps/status-api/src/index.js'; ..."`
72
73## result
74
75- 已将 status-api 从包内 handler 扩展为可挂载的 fetch 运行时入口，新增 `createStatusApiRuntime()` 与 `createStatusApiFetchHandler()`，可直接对接标准 `Request`/`Response`。
76- 已整理对外路由面，明确以 `GET /healthz`、`GET /v1/status`、`GET /v1/status/ui` 为 canonical surface，并把 `/`、`/ui` 保留为 UI 别名。
77- 已将 `build` 改为真实 `tsc` 发射，确认生成 `apps/status-api/dist/**` 产物，并用构建后的运行时代码冒烟验证三条 GET 路由。
78
79## risks
80
81- 默认运行时仍使用 `StaticStatusSnapshotLoader`；真正接入 D1 或本地控制平面数据库仍需由后续整合步骤注入 `D1StatusSnapshotLoader`。
82- 当前 dist 入口路径受 `rootDir: ../..` 影响为 `dist/apps/status-api/src/*.js`；如果后续统一构建任务收敛到平铺的 `dist/index.js`，需要同步调整 `package.json` 的 `main`/`exports`。
83- fetch 运行时假设宿主环境提供标准 Fetch API；若后续必须在更旧的 Node 版本运行，需要额外补 polyfill 或改为 node server adapter。
84
85## next_handoff
86
87- 在 status-api 的宿主进程中注入真实 `D1StatusSnapshotLoader`，把 `createStatusApiRuntime()` 挂到本地 HTTP server、launchd 进程或上层 router。
88- 若仓库后续统一 dist 布局，顺手把 `@baa-conductor/status-api` 的导出路径更新到新的 build 产物位置。
89
90## notes
91
92- `2026-03-21`: 创建第三波任务卡
93- `2026-03-22`: 从 `main@c5e007b` 建立独立 worktree，补齐 status-api fetch 运行时入口与 canonical route surface，完成验证并进入 review。