eust-w 3217982f32 🔀 Merge project knowledge
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

# Conflicts:
#	apps/web/src/features/projects.tsx
#	apps/web/src/lib/types.ts
#	docs/architecture.md
#	docs/reference/ui.md
#	docs/requirements.md
#	docs/user-manual.md
#	tests/local-loop.test.ts
2026-11-04 12:45:22 +08:00

46 lines
4.9 KiB
Markdown
Raw Permalink 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.

# 管理台设计规范
管理台位于 `apps/web`,使用 Next.js App Router、React、SWR 与 Lucide 图标。所有列表、状态、预算与操作反馈都来自真实的控制面数据,不内置演示数据或模拟流程。
## 视觉基线
概念图:[`apps/web/design/console-concept.png`](../../apps/web/design/console-concept.png)(零数据状态的工作概览)。
- 新增样式使用 `globals.css` 顶部的设计变量(导航 `--navy`、页面背景 `--bg`、表面 `--surface`、主色 `--teal` / `--teal-dark`、边框 `--border`、正文与次要文字 `--ink` / `--muted`、警示 `--amber` / `--red`)。
- 正文与次要文字对白色背景的对比度不低于 4.5:1,焦点环不低于 3:1;最小字号 12 px。
- 桌面端左侧导航 248 px、顶部栏 58 px;760 px 以下使用抽屉导航,抽屉关闭时其中的链接不可聚焦,按 Esc 关闭。
- 所有按钮与表单都有可见焦点、标签和错误反馈,并尊重 `prefers-reduced-motion`。
## 页面
| 页面 | 内容 | 主要接口 |
|---|---|---|
| 工作概览 `/` | 进行中与待处理的运行数、最近运行、项目准备入口 | `GET /v1/dashboard` |
| 项目空间 `/projects` | 项目列表、创建项目 | `GET/POST /v1/projects` |
| 项目详情 `/projects/:id` | 仓库状态(平台仓库失败可重试)、项目运行、项目技能概况(链接到知识库)、设置(目标分支、验证命令、安装命令、交付配置、验收配置) | `GET/PATCH /v1/projects/:id`、`POST /repository`、`/skills` |
| 运行记录 `/runs` | 运行列表与筛选;提交愿望(不可用的执行器不可选并显示原因) | `GET /v1/runs`、`POST /v1/projects/:id/wishes` |
| 运行详情 `/runs/:id` | 阶段进度、等待原因与对应操作、最近一次失败(修复轮的输入);标签页:概览、代码变更(检查点按文件的 diff)、阶段事件(Agent 消息、命令、文件变更、计划)、验证证据(命令、退出码、耗时、输出尾部,合入与冲突);交付结果(合入的 commit 或应用地址) | `GET /v1/runs/:id`、`/events/stream`、`/artifacts`、`/delivery`、`POST /commands` |
| 发布与审批 `/releases` | 发布列表(失败原因);审批对话框展示需求目标与验收标准、项目、环境(是否生产)、验证命令、commit、镜像、审批期限与请求人 | `GET /v1/releases`、`GET /v1/releases/:id/review`、`POST /v1/approvals/:id/decision` |
| 环境 `/environments` | 环境列表与创建、应用地址、Runner 注册、部署密钥引用、部署结果未知时「核对后解锁」 | `/v1/environments*`、`POST /v1/environments/:id/unlock` |
| 执行器 `/providers` | 执行器可用性与能力、保存或撤销 BYOK 凭据、执行器设置(网关、模型、时限,所有者和管理员) | `GET /v1/providers`、`/v1/provider-connections`、`GET /v1/executor-settings`、`PUT /v1/executor-settings/:provider` |
| Agent 配置 `/agent` | 配置版本列表、创建、激活、回滚 | `/v1/agent-bundles*` |
| 用量 `/usage` | 套餐限额与当前用量、本月 token 与按运行明细、CSV 导出 | `GET /v1/entitlements`、`/v1/usage`、`/v1/usage/export` |
等待原因统一由 `src/lib/waiting.ts` 映射为中文说明和可执行操作(例如「连接执行器」「重试仓库创建」「去审批」「补充需求」),不直接展示后端的原始代码。
## 身份与代理
- `/api/*` 是服务端代理,转发到控制面的 `/v1/*` 并附加当前用户的 access token;不存在绕过身份检查的公开 rewrite。
- 只有 `WF_DEPLOYMENT_MODE=development`(且不是 Next 的生产构建)时,服务端才读取 `WF_DEV_AUTH_TOKEN` 自动登录;其他情况一律不接受开发令牌。
- OIDC 使用 discovery、授权码 + PKCE(S256)、state 与 nonce,并校验 ID token 的签名、issuer 与 audience。
- 会话保存在加密的 HttpOnly Cookie 中,浏览器脚本无法读取;access token 过期前 1 分钟内由服务端代理使用 refresh token 续期,会话最长 12 小时。身份服务没有签发 refresh token 时,会话随 access token 结束。
- 写请求校验 `Origin`,代理拒绝上游重定向;界面上的权限控制只用于体验,最终以 API 的角色与成员检查为准。
环境变量:`WF_DEPLOYMENT_MODE`、`WF_API_URL`、`WF_PUBLIC_URL`、`WF_DEV_AUTH_TOKEN`(仅开发)、`OIDC_ISSUER`、`OIDC_CLIENT_ID`、`OIDC_CLIENT_SECRET`(可选)、`WF_SESSION_SECRET`(至少 32 字符)。
## 测试
- `src/lib/auth.test.ts`:会话加密与篡改、生产禁用开发令牌、会话过期、返回地址校验、ID token 签名与 nonce、refresh token 续期与轮换。
- `src/lib/patch.test.ts`:检查点补丁按文件解析(新增、删除、二进制、看起来像文件头的内容行)。
- `tests/run-lifecycle.test.ts`:每个等待原因在 `waiting.ts` 中都有中文说明与操作。