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

4.5 KiB
Raw Blame History

模块:控制面 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,权限模型不同,不能混用。