wishforge-ide/wiki/modules/api-control-plane.md

63 lines
4.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 模块:控制面 API(apps/api)
## 职责
`apps/api` 是平台的**唯一事实来源**:项目与成员、愿望与运行、租约与证据、发布与审批、额度与用量、连接器与模型代理。它自己不跑模型、不跑测试,而是把长时间工作交给 Temporal(`apps/worker`)和目标环境的 Runner。
## 启动与组装顺序
入口 `apps/api/src/main.ts:24` 的 `bootstrap()`:
1. `requireDeploymentMode(process.env)`(`main.ts:25`):部署模式必须显式声明,默认拒绝(fail closed),不靠 `NODE_ENV` 推断。
2. 删除迁移用管理员凭据(`main.ts:27-28`),并对数据库角色做安全检查 `store.assertSafeRole()`(`apps/api/src/db/store.ts:108-110`):超级用户或 `BYPASSRLS` 角色会让租户隔离失效,因此拒绝启动。
3. 若派发开启,强制要求 Temporal TLS 文件与租户命名空间(`main.ts:30-34`),避免通过未认证或共享命名空间派发。
4. 组装 `Services(new ControlPlane(store))`,启动后台技能沉淀与资源对账 worker。
## 代码地图
| 文件 | 职责 | 关键点 |
|---|---|---|
| `apps/api/src/main.ts` | 启动、依赖组装、后台循环 | 206 行;fail-closed 配置校验 |
| `apps/api/src/http.ts` | REST 路由与 DTO 校验 | 933 行;NestJS 控制器;`/v1` 与 `/internal` |
| `apps/api/src/domain/control-plane.ts` | 运行状态机 | 1564 行;`submit:358`、`lease:931`、`transition:1076`、`evidence:1213` |
| `apps/api/src/domain/releases.ts` | 发布绑定、审批、回滚 | 724 行;`releaseBinding:42`、`request:280`、`decide:435`、`rollback:662` |
| `apps/api/src/domain/runner-broker.ts` | Runner 注册、任务队列、回执 | 508 行;`register:54`、`poll:127`、`result:290` |
| `apps/api/src/domain/provider-proxy.ts` | 模型网关代理与短期令牌 | 933 行;原始密钥不进入执行环境 |
| `apps/api/src/domain/local-poc.ts` | POC 绑定与构建证据校验 | `assertPocBuild`;`POC_BINDING_REQUIRED` 等错误码 |
| `apps/api/src/domain/integration-lease.ts` | 每项目单一集成者 | 与 fencing token 配合 |
| `apps/api/src/domain/entitlements.ts` | 套餐限额与并发预留 | 与 `usage.ts` 配合 |
| `apps/api/src/domain/skills.ts` | 项目技能沉淀 | 423 行;后台 harvest |
| `apps/api/src/domain/lessons.ts` | 运行经验注入 | 90 行 |
| `apps/api/src/mcp.ts` | MCP Streamable HTTP 服务 | 8 个工具;OAuth 资源元数据 |
| `apps/api/src/auth.ts`、`internal-auth.ts` | 人类会话与内部身份 | 身份类型见 `packages/contracts/src/index.ts:85` |
| `apps/api/src/dispatcher.ts` | Outbox → Temporal 派发 | 多副本安全 |
| `apps/api/src/db/store.ts` | PostgreSQL 事务与 RLS 上下文 | 每个事务 `set_config('app.tenant_id', …)`(`:116`) |
| `apps/api/src/db/migrate.ts`、`migrations/` | 版本化迁移 | `npm run db:migrate` |
| `apps/api/src/telemetry.ts` | OpenTelemetry 与指标 | Prometheus |
## 数据层约束
- 每个租户事务在进入时设置 `app.tenant_id` 与 `app.actor_id`(`apps/api/src/db/store.ts:116-119`),RLS 策略据此过滤;应用层另有检查,两者都不能省。
- Outbox 表把「状态已提交」与「工作流已派发」解耦:`outbox()` 只取未投递且到期的记录,按 `run.signal` → `workspace.reconcile` → 其他排序(`apps/api/src/db/store.ts:264`),投递成功写 `delivered_at`,失败累加 `attempts` 并退避。
- 清理策略:已投递 outbox 保留 7 天,幂等记录 30 天(`apps/api/src/db/store.ts:84`)。
## 测试集
| 测试 | 覆盖 |
|---|---|
| `tests/control-plane.test.ts` | 提交、租约、阶段迁移、证据 |
| `tests/control-hardening.test.ts` | 取消/补充/暂停的级联失效、越权、租约边界 |
| `tests/local-loop.test.ts` | 本地端到端主链路 |
| `tests/local-poc-delivery.test.ts` | POC 发布绑定、签名回执、回滚 |
| `tests/entitlements-usage.test.ts` | 配额与计量 |
| `tests/internal-auth.test.ts`、`tests/auth-expiry.test.ts` | 身份与过期 |
| `tests/path-rules.test.ts` | 后端路径规则 |
| `tests/mcp.test.ts` | MCP 工具契约 |
## 修改时的检查清单
1. 改状态迁移:必须同时更新 `packages/contracts` 的 schema、`tests/control-plane.test.ts` 与前端等待指引。
2. 改证据结构:确认历史证据仍能反序列化;证据是审计资产。
3. 改发布绑定字段:会让既有审批失效,需要在 PR 中说明。
4. 新增路由:`/v1` 面向人类与连接器,`/internal` 面向 worker/verifier,权限模型不同,不能混用。