People's changes now reach the target branch the same way the agent's do. The IDE credential carries a ref prefix and the Git service runs a pre-receive hook on every push that refuses updates outside it, so the IDE can push only `ide/` branches; the platform's own integration is unaffected. - A wish may name a source branch. The run starts from that branch's head, the agent builds on it, and verification, repair rounds, merging onto a moved target and conflict repair work as before. A missing branch makes the run wait (git_storage) until it is pushed. - Release risk is now computed from the target branch before integration, not from where the run started: a migration committed on the source branch would otherwise have been missed and could have skipped approval. - Clones work on `ide/work`; a plain `git push` publishes it. - The console lists a project's IDE branches with a button to submit a wish that merges one, and the new-wish form has a starting-point field; MCP `submit_wish` accepts `sourceBranch`. The Git service lists branches under a prefix for this (`POST /refs`). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
47 lines
5.1 KiB
Markdown
47 lines
5.1 KiB
Markdown
# 管理台设计规范
|
||
|
||
管理台位于 `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` | 仓库状态(平台仓库失败可重试)、IDE 工作区与从 IDE 推送的 `ide/` 分支(每个分支可以直接「提交愿望合入」)、项目运行、项目经验(查看、添加约定、停用、删除)、设置(目标分支、验证命令、安装命令、交付配置、验收配置) | `GET/PATCH /v1/projects/:id`、`POST /repository`、`/workspaces`、`/branches`、`/lessons`、`/v1/lessons/:id` |
|
||
| 运行记录 `/runs` | 运行列表与筛选;提交愿望(不可用的执行器不可选并显示原因;「起点」可以选一个 IDE 分支,运行从它开始,验证后合入) | `GET /v1/runs`、`POST /v1/projects/:id/wishes`、`GET /v1/projects/:id/branches` |
|
||
| 运行详情 `/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` |
|
||
| 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 的角色与成员检查为准。
|
||
- 打开 IDE 时,`/ide/:id/launch` 在服务端调用 API 获取 30 秒一次性启动地址,access token 不出现在 URL 中。
|
||
|
||
环境变量:`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` 中都有中文说明与操作。
|