# R1 任务上下文：HWLAB v0.3 非 Workbench 页面全量重写

## 1. 用户目标

- 全量重写 HWLAB v0.3 除 Workbench 主工作流外的 Cloud Web 页面：
  - 不在旧页面上继续叠加局部美化和兼容层。
  - MDTODO 也可重写实现，但保留已经成熟的布局设计和工作流语义。
  - 后端能力不足时可以补强，并按明确职责合理拆分微服务。
- 视觉与交互方向：
  - 工业风、高信息密度和稳定工作界面。
  - 通过渐进披露优先展示名称、身份、主状态、关键能力、主要 blocker 和高频操作。
  - 详情、诊断、日志、原始 JSON、配置和低频操作进入展开区、Inspector、Drawer 或 Dialog。
  - 不做营销式 hero、装饰性指标墙或以裸 JSON 代替产品界面。
- 通用能力优先：
  - 先抽取表格、卡片、弹窗、抽屉、日志、Markdown、JSON、状态、异步反馈和有界工作区等模块。
  - 承载实体集合的页面统一支持图标卡片和列表/表格切换。
  - 不适合实体集合的页面提供等价的紧凑/舒适密度或内容显示方式切换，避免制造无意义图标视图。
  - 视图、筛选、排序、分页、选中对象和详情标签应通过稳定 URL 恢复。
- HWPOD 重点：
  - 设备页使用带克制状态动效的电路板图标卡片，并提供高密度列表模式。
  - HWPOD 页面至少拆为“设备资源”“HWPOD Node”“节点接入”三个可深链子标签。
  - Node 页面管理已连接节点，并明确展示每个 node 下挂载的零到多个 HWPOD。
  - 接入页允许从网页下载 Python 单文件 `hwlab-node.py`，展示版本、SHA-256、安装条件、配置步骤和连接验证。

## 2. OA SPEC 战略对齐

- 战略来源：
  - [PJ2026-01 HWLAB 总规格](../../../../project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md)。
  - [HWLAB Cloud 阶段规格](../../../../project-management/PJ2026-01/specs/stage-cloud-spec-20260601.md)。
  - [PJ2026-0104 客户端](../../../../project-management/PJ2026-01/specs/PJ2026-0104-client.md)。
  - [PJ2026-0101 硬件池](../../../../project-management/PJ2026-01/specs/PJ2026-0101-hardware-pool.md)。
  - [PJ2026-0105 用户管理](../../../../project-management/PJ2026-01/specs/PJ2026-0105-user-management.md)。
- 最终目标判断：
  - 页面重写的目的不是孤立美化，而是把真实硬件资源、Agent 执行、Harness/RL 事实、多用户协同和运营管理投影成一致、可理解、可操作的云端入口。
  - Cloud 阶段要求从“单用户本地验证”走向“多人多端云端开箱即用”，因此页面主路径应优先解决项目协同、任务继续操作、硬件接入、HWPOD 可用性、用户/组织上下文和可行动 blocker。
  - HWPOD 页面必须表达 target device、workspace、debug probe 和 io probe 四要素，以及 node、能力、占用、操作结果和原始硬件事实，不能把动效电路板做成与真实状态无关的装饰。
  - Web、CLI 和 HTTP API 必须共享任务、权限、错误和结果语义；前端不得通过字段猜测、名称去重或跨接口临时拼装生成业务真相。
  - 每个页面组必须绑定唯一主责 L1/L2 和原入口验收，避免落入 L0 明确排除的“孤立工具美化”。
- SPEC-first：
  - 全站信息架构、跨领域 API、长期数据模型或微服务边界发生稳定变化时，先确认或修订对应 OA SPEC。
  - P0 规格应补齐主责编号、系统边界、目标架构图、数据流图、关键时序图、原子需求和验收入口。
  - 实现文件按项目规则引用确认后的 SPEC 编号和实现版本。

## 3. 当前实现事实

- 权威源码与快照：
  - HWLAB v0.3 Web 位于 NC01 固定 workspace 的 `web/hwlab-cloud-web`。
  - 调查快照 HEAD 为 `220e7897e15f5e48e6e94ec144cbcfdefc509431`；正式执行前必须从当前 `origin/v0.3` 基线重新盘点。
  - UniDesk 本地 `src/components/frontend/src/hwlab.tsx` 只是硬编码外部地址的跳转壳，不是 HWLAB v0.3 页面源码。
- 当前路由族：
  - 应用壳与认证：登录、注册、404。
  - 项目：Projects、MDTODO。
  - 用户：Dashboard、API Keys、Usage、Billing、Settings、Help。
  - 管理：Access、Secrets、External Secret、Users、Admin Billing、HWPOD、Provider Profiles。
  - 系统与工具：Performance、Skills、Gate、OpenCode 外壳。
  - `/workbench*` 主工作流不在本任务内重写。
- 当前通用组件只有基础版本：
  - `DataTable` 只有行列和 slot，没有统一排序、筛选、选择、列配置、服务端分页、密度或窗口化。
  - `BaseDialog` 未完整处理初始焦点、焦点圈定和关闭后恢复。
  - Log、Markdown、JSON、状态、blocker 和异步刷新仍有页面私有实现。
  - `workbench.css` 混合 Workbench 与普通页面样式，已经超过 3000 行治理边界。
  - 大量 DTO 仍是 `Record<string, unknown>`，部分页面猜测多种字段形态。
- 当前 HWPOD 页面缺陷：
  - 把 WebSocket node、spec 和虚构 group 扁平混合成同一种行，丢失一 node 对多 HWPOD 的显式拓扑。
  - 混淆 service ready、node online 和 HWPOD available 三种状态。
  - 没有 node 详情、挂载设备、版本、in-flight、能力差异、安装阶段或接入引导。
- 当前 HWPOD 后端已有可复用能力：
  - `GET /v1/hwpod/specs` 返回 HWPOD spec；首屏不应默认 `probe=1` 全量探测。
  - `GET /v1/hwpod-node-ops` 返回在线 node、capabilities、心跳、最近诊断和全局 pending。
  - `POST /v1/hwpod-node-ops` 承载受控 node 操作。
  - `GET /v1/hwlab-node/update` 返回版本、下载 URL、SHA 和发布说明。
  - `GET /v1/hwlab-node/download/hwlab-node.py` 提供 Python 单文件下载。
  - `/v1/hwpod-node/ws` 承载节点主动出站连接。
- 当前 HWPOD 后端缺口：
  - 声明但离线的 node、在线但未挂 spec 的 node 与 HWPOD 的统一拓扑。
  - 单 node 的 in-flight、并发上限、busy、安装/注册/workspace/HWPOD readiness 阶段。
  - declared 与 actual capability mismatch 分类。
  - 持久化且分页的 operation result、诊断和日志。
  - 有界列表/详情 DTO；当前 spec discovery 会携带完整 document。
  - WebSocket registry 当前在单副本 Cloud API 内存中，不是持久化 HWPOD 服务事实。

## 4. 目标产品与信息架构

- 全站应用壳：
  - 导航按用户工作流组织，不按后端服务名堆砌。
  - 保留现有 `navId`/ACL、同源 HttpOnly 会话和安全 redirect，变更时原子迁移。
  - 桌面、紧凑桌面和移动端都有明确导航与内容滚动所有者。
  - Dashboard 成为用户/组织范围的继续工作入口，聚合项目、任务、HWPOD、额度和主要异常，不在浏览器并发拼装领域事实。
- HWPOD：
  - “设备资源”展示 HWPOD 四要素、node、能力、可用/占用状态、主要 blocker 和最近 operation。
  - “HWPOD Node”展示 nodeId、平台、版本、首见/末见、心跳、能力、in-flight、诊断和挂载 HWPOD 子集合。
  - “节点接入”展示下载、校验、安装、配置和分阶段 readiness；不得把下载完成或 WebSocket connected 冒充 HWPOD ready。
- Projects 与 MDTODO：
  - Projects 提供集合、状态/来源筛选、项目详情、任务活动和 blocker 深链。
  - MDTODO 保留有界三栏、Rxx 树→正文→报告层级、Source/File 工具栏、inline edit、报告关闭/调整/全屏、RESTful 深链和公共 Workbench launch。
  - MDTODO 重写后不得 import Workbench 私有 store；只能通过公共 Project Management 和 Workbench Launch API 联动。
- 用户与协同：
  - 用户入口围绕账户、组织、组织项目/工作台、API key、额度、usage、账单和偏好组织。
  - 页面不虚构未落地的支付、scope、轮换、跨设备同步或组织能力；需要时先补业务域 SPEC/API。
- 管理与系统：
  - Users、Access、Secrets、Billing、Provider Profiles 使用集合→Inspector/详情→低频 Dialog 的一致交互。
  - Secrets 继续只披露对象、key、presence、fingerprint 和摘要，保留 dry-run/plan 边界。
  - Performance、Gate、Skills 和 OpenCode 外壳按“状态→问题→证据→动作”渐进披露，不把原始日志或 iframe 错误直接铺满页面。

## 5. 通用前端能力

- Foundation：
  - 工业风 tokens、字体、间距、边框、状态色、阴影、动效和 reduced-motion。
  - Button、IconButton、Field、Select、Chip、Tooltip、StatusBadge 和紧凑 MetricStrip。
- Layout：
  - AppShell、PageHeader、PageCommandBar、StatusStrip、SectionFrame、InspectorDrawer 和 BoundedWorkspace。
  - 主区域内部滚动，避免 document 级长页和外层横向溢出。
- Collections：
  - `DataGrid<T>`、`VirtualList<T>` 和 `ResourceCollection<T>`。
  - 图标卡片与列表/表格共享同一数据源、筛选、排序、选择和详情合同。
  - 支持 sticky header、列显隐、键盘选择、服务端 cursor pagination 和大集合窗口化。
- Overlays：
  - Dialog、Drawer、Popover 和 ConfirmDialog 统一 Portal、Esc、focus trap、焦点恢复、scroll lock、busy 和 ARIA。
- Content：
  - Log、Markdown、JSON、Text 和 Trace Viewer 统一搜索、复制、换行、行号、下载和全屏能力。
  - 日志支持 follow/pause 和跳底；JSON 默认折叠；Markdown 使用成熟 parser 与 sanitizer。
- Feedback：
  - 统一 initial-loading、refreshing、partial、empty、error 和 ready。
  - 后台刷新保留上一份成功数据；错误默认给出可理解原因，把 code/requestId/traceId 放入详情。
- Routing：
  - 实体身份和选择进入 REST path。
  - `view`、`density`、`q`、`filter`、`sort`、`cursor` 和详情标签进入 query。
  - localStorage 只能保存纯显示偏好，不能成为实体、权限或业务状态 authority。

## 6. 后端与微服务边界

- 基本原则：
  - 页面需要聚合显示时优先补 typed BFF/read model，不让前端跨多个服务猜测关键事实。
  - 只有独立数据所有权、生命周期、伸缩/连接故障域或权限边界成立时才拆微服务。
  - Cloud API 保持同源鉴权、路由、错误和 correlation 映射，不重新拥有各业务域真相。
- 既有职责必须保留：
  - 项目与 MDTODO 继续由独立 `hwlab-project-management` 服务拥有。
  - 用户、组织、权限、额度、usage 和 billing 继续由用户管理域拥有。
  - HWPOD spec、资源、租约、路由和 operation result 归 HWPOD 服务域。
  - HWPOD Node 的心跳、能力、adapter 执行和原始硬件事实归 AI 网关域。
- HWPOD 候选拆分：
  - 优先评估从 Cloud API 抽取一个 `hwlab-hwpod-service`，统一拥有 spec/registry 投影、node connection、拓扑、operation state/result 和诊断摘要。
  - Connection gateway 先作为该服务内部模块；只有连接规模和 churn 构成独立故障域时再拆。
  - Python 文件可继续由版本化静态 artifact 路径交付，不单独创建安装服务。
  - 用户自助 claim/registration 会引入新的身份与授权合同，未经单独 SPEC 不在本任务内发明。

## 7. 交付顺序

1. OA SPEC、页面/实体/用户旅程、API/DTO、ACL、深链和验收矩阵对齐。
2. 工业设计系统、应用壳、通用集合、Overlay、Viewer、Async 和路由状态模块。
3. typed API/read model 与必要的 HWPOD Service、项目、用户管理后端补强。
4. HWPOD Devices、Nodes 与 Onboarding 重点切片。
5. Dashboard、Projects 和 MDTODO 主工作流。
6. 用户/组织、API key、usage、billing 和偏好页面。
7. 管理与系统工具页面、认证页、404 和 OpenCode 外壳。
8. 删除旧 UI、字段猜测、重复样式和不再使用的兼容实现。
9. 真实入口、性能、无障碍、响应式和深链恢复验收。

## 8. 总体验收

- 产品与契约：
  - 每个页面组可追溯到唯一主责 SPEC 和稳定业务 ID。
  - 前端不再通过 `Record<string, unknown>`、字段名猜测、名称去重或临时多接口拼接生成关键事实。
  - Workbench 不被改写，MDTODO→Workbench 公共启动语义不回退。
- 显示与交互：
  - 实体集合页均有图标卡片和列表/表格切换；非集合页有合理的显示密度或内容模式切换。
  - 卡片与列表显示相同的主状态和 blocker，不形成两套业务逻辑。
  - 选中项、视图、筛选、排序、分页和详情标签可深链并刷新恢复。
  - 日志、Markdown、JSON、错误、加载和局部刷新统一使用通用组件。
- HWPOD：
  - 一 node 对零到多个 HWPOD 的关系来自 typed API。
  - service ready、node online、HWPOD available、leased/busy 和 capability mismatch 分别呈现。
  - 电路板卡片四条链路表达 target/workspace/debug/io；仅真实连接或单 node in-flight 驱动动效。
  - 动效支持 `prefers-reduced-motion`，状态不只依赖颜色。
  - 接入完成态按 downloaded、installed、desktop-visible、registered、workspace-ready 和 hwpod-ready 分阶段判定。
- 布局、无障碍与性能：
  - `1920x1080`、`960x600` 和约 `390px` 手机宽度均有明确导航、滚动所有者和可操作主路径。
  - 无 document 级横向溢出；长表、长树和长日志 DOM 有界。
  - Dialog/Drawer 支持完整键盘、焦点圈定/恢复、Esc、ARIA 和危险操作确认。
  - 隐藏 pane 停止高频更新；动效不造成 layout shift 或持续高 CPU。
- 原入口验证：
  - 使用 NC01/v03 YAML-selected Cloud Web 原入口和 `web-probe observe/analyze` 验证。
  - 覆盖桌面、紧凑桌面、移动端、深链刷新、权限差异、loading/empty/error/partial/ready 和大数据集。
  - HWPOD fixture/E2E 至少覆盖一 node 多 HWPOD、声明离线 node、在线无 spec node、invalid spec、capability mismatch、busy、update available 和诊断错误。
