模块: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 而不是清空,避免网络抖动时页面显示成「没有项目」。
两个前端陷阱
- 不要在组件里重新推导状态。 阶段、等待原因、风险都来自 API;前端只做映射。
waiting.ts 已经承担了「原因 → 指引」的唯一映射,新增原因必须在此补齐。
- 不要引入服务端依赖到客户端 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 的端到端链路 |
修改时的检查清单
- 新增页面:同时补
console-shell 导航与权限判断。
- 新增等待原因:改
packages/contracts → apps/web/src/lib/waiting.ts → 运行详情卡片,三处缺一不可。
- 改 Diff 渲染:先确认
patch.ts 的解析测试,再改组件。
- 改登录:生产模式必须拒绝开发令牌,回调重放必须被拒绝(
docs/requirements.md FR-A1)。