76 lines
4.4 KiB
Markdown
76 lines
4.4 KiB
Markdown
# 模块: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)。
|