wishforge-ide/wiki/features/console-observability-and-usage.md

4.6 KiB
Raw Permalink Blame History

控制台:进度、证据、报告与用量

控制台负责什么

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