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