- docs/architecture.md replaces system-design.md: component map, run state machine with an explicit waiting-reason catalogue, key sequences (dispatch, execute/verify/repair, integrate, release, IDE launch, lessons), data model, API surface, identity and trust model, isolation modes (host for local development, kata for production), deployment topology, ADRs, known limitations and a requirement-to-test verification matrix. - docs/development.md: local setup, one-command start, first wish, IDE, MCP and the test matrix (integration toggles are explicit). - docs/operations.md: production prerequisites, explicit deployment mode, component configuration, Kubernetes provisioner, tenants and quotas, IDE gateway routing and lifecycle, delivery, monitoring, backup/restore, incident handling and known risks. Merges the former observability, recovery, billing-entitlements and runbook documents. - Contract documents move to docs/reference/; evidence narratives that pointed at machine-local /private/tmp files are removed and the UI reference is rewritten for the target console. - Delete docs for removed scope: workspace snapshot handoff and private application access. - README rewritten as a concise entry point. The documents describe the target state that the following implementation commits realise. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.9 KiB
3.9 KiB
管理台设计规范
管理台位于 apps/web,使用 Next.js App Router、React、SWR 与 Lucide 图标。所有列表、状态、预算与操作反馈都来自真实的控制面数据,不内置演示数据或模拟流程。
视觉基线
概念图:apps/web/design/console-concept.png(零数据状态的工作概览)。
- 颜色使用
globals.css顶部的设计变量(导航--nav、页面背景--page、主操作--accent、边框--line、正文与次要文字--ink/--muted等),组件中不直接写十六进制颜色。 - 正文与次要文字对白色背景的对比度不低于 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 工作区、项目运行、项目经验、设置(验证命令、安装命令、交付配置、验收配置) | GET/PATCH /v1/projects/:id、/workspaces、/lessons |
运行记录 /runs |
运行列表与筛选;提交愿望 | GET /v1/runs、POST /v1/projects/:id/wishes |
运行详情 /runs/:id |
阶段进度、等待原因与对应操作、实时事件、代码变更(按文件的 diff)、验证证据(命令、退出码、输出尾部)、交付信息 | GET /v1/runs/:id、/events/stream、/delivery、POST /commands |
发布与审批 /releases |
发布列表;审批对话框展示需求目标、项目、环境(是否生产)、commit、镜像、验证摘要与过期时间 | GET /v1/releases、POST /v1/approvals/:id/decision |
环境 /environments |
环境列表与创建、Runner 注册、部署密钥引用、解锁 | /v1/environments* |
执行器 /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_DEV_AUTH_TOKEN自动登录;生产模式不接受开发令牌。 - OIDC 使用 discovery、授权码 + PKCE(S256)、state 与 nonce,并校验 ID token 的签名、issuer 与 audience。
- 会话保存在加密的 HttpOnly Cookie 中,浏览器脚本无法读取;access token 过期前使用 refresh token 自动续期。
- 写请求校验
Origin,代理拒绝上游重定向;界面上的权限控制只用于体验,最终以 API 的角色与成员检查为准。 - 打开 IDE 时,
/ide/:id/launch在服务端调用 API 获取 30 秒一次性启动地址,access token 不出现在 URL 中。
环境变量: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。