Codex
53 lines
3.0 KiB
Markdown
53 lines
3.0 KiB
Markdown
# v0.2 hwlab-cloud-web 服务规格
|
|
|
|
`hwlab-cloud-web` 是 `v0.2` 浏览器工作台，运行在 `hwlab-v02` namespace，内部端口 `8080`，公网经 FRP 暴露为 `http://74.48.78.17:19666/`。
|
|
|
|
## 在系统中的职责划分
|
|
|
|
- 向用户提供 Cloud Workbench、Code Agent 对话、live status、device-pod 右侧面板、trace 展示和帮助内容。
|
|
- 只消费 `hwlab-cloud-api`，不直接访问 Postgres、gateway、device-pod Service、FRP、Kubernetes 或 provider Secret。
|
|
- 为浏览器提供同源代理，避免前端直接跨域调用内部 ClusterIP。
|
|
|
|
## 内部架构
|
|
|
|
- `web/hwlab-cloud-web/app.mjs` 是浏览器端主应用，组织 Workbench 状态、Code Agent 会话缓存、trace 轮询和 device-pod 面板。
|
|
- `internal/dev-entrypoint/http.mjs` 提供静态服务、health 和 HTTP proxy 基础能力。
|
|
- `internal/dev-entrypoint/cloud-web-routes.mjs` 定义可代理到 cloud-api 的同源 API route 和认证边界。
|
|
- `web/hwlab-cloud-web/auth.mjs` 管理工作台登录态；真正的用户权限 authority 仍应收敛到 cloud-api。
|
|
|
|
## API 接口说明
|
|
|
|
| 接口 | 说明 |
|
|
| --- | --- |
|
|
| `GET /` | Cloud Workbench 首屏。 |
|
|
| `GET /health`、`GET /health/live` | 返回 cloud-web 自身 health 和 build metadata。 |
|
|
| `GET /help` | 返回可用 route 摘要。 |
|
|
| `GET /v1`、`GET /v1/...` | 同源代理到 `hwlab-cloud-api`；公开的 Code Agent result/trace 轮询按 route policy 处理。 |
|
|
| `POST /v1/agent/chat`、`POST /v1/agent/chat/cancel` | 同源代理到 cloud-api 的 Code Agent 入口。 |
|
|
| `POST /v1/m3/io`、`POST /json-rpc` | 同源代理到受控 API；不能绕过 cloud-api 直连硬件服务。 |
|
|
|
|
## 测试规格
|
|
|
|
## T1
|
|
|
|
阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：访问 `http://74.48.78.17:19666/` 和 `/health/live`，确认页面和 health 均来自 v02 cloud-web，而不是 DEV/PROD 端口。
|
|
|
|
## T2
|
|
|
|
阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：从同源 `19666` 提交 Code Agent 短连接请求并轮询 result，确认请求经 cloud-web proxy 到 `hwlab-cloud-api`，且 trace 可回放。
|
|
|
|
## T3
|
|
|
|
阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：打开 Workbench device-pod 面板，确认 status/freshness/blocker 显示来自 `/v1/device-pods`，未登录或未授权时必须显示认证/授权 blocker，不得把 fixture 或 blocked fallback 写成真实硬件 DEV-LIVE。
|
|
|
|
## 规格的实现情况
|
|
|
|
| 规格项 | 状态 | 说明 |
|
|
| --- | --- | --- |
|
|
| Workbench 首屏 | 已实现 | 当前页面直接进入工作台，不是 landing page。 |
|
|
| cloud-api 同源代理 | 已实现 | 受 route policy 控制。 |
|
|
| Code Agent UI/trace/result | 已实现 | 支持 provider profile、timeout、trace 轮询和取消。 |
|
|
| device-pod 面板 | 未完全实现 | 当前主要消费 fake/只读 device-pod payload。 |
|
|
| 完整多用户 admin/user UI | 未完全实现 | 登录态存在，权限 authority 仍需按 spec-user-access 收敛到 cloud-api。 |
|
|
|