4.6 KiB
4.6 KiB
控制台:进度、证据、报告与用量
控制台负责什么
apps/web 是 Next.js 工作台,职责是交互与 BFF 转换,不直接触碰业务数据库。所有业务事实来自 apps/api,前端只做展示与转发。这条边界可以在 apps/web/src/app/api/[...path]/route.ts 这类代理路由中看到,也由 tests/console-bundle.test.ts 保护:控制台可以打包 packages/contracts 的纯函数(例如 permissions.ts),但不能把服务端实现拉进浏览器包。
页面与能力
| 页面 | 前端入口 | 主要能力 |
|---|---|---|
| 概览 | apps/web/src/features/dashboard.tsx |
待确认、运行中、失败等聚合指标 |
| 运行列表 | apps/web/src/features/runs.tsx:69 RunsView |
按阶段/状态筛选,进入详情 |
| 新建愿望 | apps/web/src/features/runs.tsx:422 NewWishView |
目标、验收标准、模型选择、AI 优化 |
| 运行详情 | apps/web/src/features/runs.tsx:789 RunDetailView |
阶段、事件、Diff、等待卡片、继续/取消/补充需求、代码审核、撤销改动 |
| 发布与审批 | apps/web/src/features/releases.tsx |
批准/拒绝、一键回滚、环境状态 |
| 项目设置 | apps/web/src/features/project-settings.tsx |
目标分支、验证命令、验证配置、可用模型、后端路径规则 |
| 成员与权限 | apps/web/src/features/members.tsx |
成员、账户类型与项目级权限 |
| 环境 | apps/web/src/features/environments.tsx |
环境与应用地址 |
| 执行器 | apps/web/src/features/providers.tsx |
模型/执行器连接与凭据 |
| 用量 | apps/web/src/features/usage.tsx |
月度 token、按运行明细、CSV 导出 |
| Agent 与技能 | apps/web/src/features/agent.tsx、skills.tsx、lessons.tsx |
提示词/模型版本、项目技能与经验 |
| 运行报告 | apps/web/src/app/reports/wishes/[id]、apps/web/src/features/wish-report.tsx |
单次愿望的交付报告 |
事件流与断线续读
- 查询历史事件:
GET /v1/runs/:id/events?after=<cursor>(apps/api/src/http.ts:444)。 - 实时订阅:
GET /v1/runs/:id/events/stream(apps/api/src/http.ts:447)。 - 事件类型的中文标签集中在
apps/web/src/lib/events.ts:58的eventLabel;新增事件类型而忘记补标签,会让详情页出现原始英文类型名,这是可观察的缺陷。
SSE 的设计要求是「断线重连后不丢失、不重复事件」(docs/requirements.md FR-C2),因此游标是接口契约的一部分,而不是前端缓存技巧。
Diff 与代码审核
运行详情页展示生成的文件 Diff,后端审核卡片复用同一渲染。审核动作通过 POST /v1/runs/:id/code-review(apps/api/src/http.ts:492)提交,批准绑定被审核的 commit 与需求版本;批准后运行自动继续合入,不再重复检查。
证据展示
- 证据隔离标签:
apps/web/src/lib/evidence-isolation.ts,用于让用户区分「沙箱内验证」与「本机 host 模式」的结果。 - 产物:
GET /v1/runs/:id/artifacts(apps/api/src/http.ts:502),存储契约见docs/reference/artifact-storage.md与apps/api/src/domain/artifacts.ts。 - 交付:
GET /v1/runs/:id/delivery(apps/api/src/http.ts:506)。
报告与用量
- 运行报告:
apps/api/src/domain/wish-report.ts,把一次运行的目标、验证证据、合入 commit 与交付结果整理成可读报告;测试tests/wish-report.test.ts。 - 用量与配额:
apps/api/src/domain/usage.ts、entitlements.ts;测试tests/entitlements-usage.test.ts。关键语义是「暂停、等待中或已结束的运行不长期占用预留额度」,因此暂停后应能提交新愿望。 - 通知:
apps/api/src/domain/notifications.ts;测试tests/notifications.test.ts。
已知边界
- 控制台不做业务判定:所有状态与阶段以 API 返回为准,前端不做乐观状态机。
- 「待确认」指标同时聚合
waiting运行、awaiting_approval发布与pending审批;取消运行时应级联失效,否则会出现「运行已取消但待确认仍大于 0」的历史问题(docs/wishforge-summary.md:217-221)。
代码入口与测试集
| 关注点 | 入口 | 测试 |
|---|---|---|
| 页面组件 | apps/web/src/features/*.tsx |
tests/console-bundle.test.ts |
| 前端纯逻辑 | apps/web/src/lib/*.ts |
apps/web/src/lib/*.test.ts |
| BFF 代理 | apps/web/src/app/api/[...path]/route.ts |
tests/application-access.test.ts |
| 事件与报告 API | apps/api/src/http.ts:444-512 |
tests/local-loop.test.ts、tests/wish-report.test.ts |