wishforge-ide/wiki/modules/web-console.md

4.4 KiB
Raw Permalink Blame History

模块:Web 控制台(apps/web)

职责与边界

apps/web 是 Next.js 工作台与 BFF。它负责会话、CSRF、页面渲染、SSE 消费与 Diff 展示;不直接访问业务数据库,所有请求经 apps/web/src/app/api/[...path]/route.ts 转发到 apps/api。这条边界让 API 可以独立部署、独立限流,也让前端无法绕过权限检查。

目录地图

路径 内容
apps/web/src/app/(console)/ 工作台路由组:dashboard 隐含在根页、runs、runs/[id]、runs/new、releases、projects、projects/[id]、projects/new、environments、members、providers、usage、agent
apps/web/src/app/ide/[id] 云 IDE 入口与 launch 路由
apps/web/src/app/login、login/callback、logout OIDC 授权码 + PKCE 与本地开发登录
apps/web/src/app/reports/wishes/[id] 单次愿望报告页
apps/web/src/app/api/[...path] BFF 代理
apps/web/src/features/ 业务页面组件(见下表)
apps/web/src/components/ console-shell.tsx、run-table.tsx、diff-view.tsx、ui.tsx
apps/web/src/lib/ 纯前端逻辑与会话(含配套 *.test.ts)

features/ 组件

文件 页面
dashboard.tsx 概览指标
runs.tsx 运行列表、新建愿望(:422)、运行详情(:789)
releases.tsx 发布、审批、回滚
projects.tsx、project-settings.tsx 项目列表与设置(目标分支、验证命令、模型、后端路径)
environments.tsx 环境与应用地址
members.tsx 成员与账户类型
providers.tsx 执行器/模型连接
usage.tsx 用量与配额
agent.tsx、skills.tsx、lessons.tsx Agent 配置、项目技能、经验
wish-report.tsx 愿望报告
runner-registration.tsx Runner 注册与公钥

lib/ 纯逻辑(每个都有测试)

文件 职责 测试
auth.ts OIDC、会话加密 Cookie、本地访问凭据 auth.test.ts
api.ts SWR 客户端与 ApiError 无独立单测(由端到端 tests/local-loop.test.ts 间接覆盖)
events.ts 事件类型中文标签(:58 eventLabel) events.test.ts
patch.ts unified diff 解析为可渲染行 patch.test.ts
waiting.ts 18 种等待原因的中文指引与 resumable 类型检查覆盖完整性
readiness.ts 数据态 ready/refreshing/stale/unavailable readiness.test.ts
risk.ts 复用 @wishforge/contracts/release-risk risk.test.ts
evidence-isolation.ts 「沙箱验证 / 本机 host」标签 evidence-isolation.test.ts
people.ts 本地账号、操作员与服务的显示名 —
markdown.tsx 受限 Markdown 渲染 markdown.test.ts
browser-id.ts 浏览器标识 browser-id.test.ts
local-access.ts 本机访问开关 local-access.test.ts
types.ts API 响应类型 类型检查

readiness.ts 的 resourceState 值得注意:它把「有旧数据但请求失败」标为 stale 而不是清空,避免网络抖动时页面显示成「没有项目」。

两个前端陷阱

  1. 不要在组件里重新推导状态。 阶段、等待原因、风险都来自 API;前端只做映射。waiting.ts 已经承担了「原因 → 指引」的唯一映射,新增原因必须在此补齐。
  2. 不要引入服务端依赖到客户端 bundle。 packages/contracts/src/permissions.ts 刻意零 import,正是为了让 apps/web 打包它而不把 pg、NestJS 等拉进浏览器。tests/console-bundle.test.ts 会检查这一点。

测试集

测试 覆盖
tests/console-bundle.test.ts 控制台打包边界与禁止依赖
apps/web/src/lib/*.test.ts 会话、事件标签、Diff 解析、就绪态、证据隔离、本地访问
tests/application-access.test.ts 应用地址与访问证据
tests/local-loop.test.ts 通过 BFF 的端到端链路

修改时的检查清单

  1. 新增页面:同时补 console-shell 导航与权限判断。
  2. 新增等待原因:改 packages/contracts → apps/web/src/lib/waiting.ts → 运行详情卡片,三处缺一不可。
  3. 改 Diff 渲染:先确认 patch.ts 的解析测试,再改组件。
  4. 改登录:生产模式必须拒绝开发令牌,回调重放必须被拒绝(docs/requirements.md FR-A1)。