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

76 lines
4.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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