# 模块: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)。