pikasTech-unidesk/docs/MDTODO/details/hwlab-web-product-experience/R1_Context.md

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 总规格。
  • HWLAB Cloud 阶段规格。
  • PJ2026-0104 客户端。
  • PJ2026-0101 硬件池。
  • PJ2026-0105 用户管理。
• 最终目标判断：
  • 页面重写的目的不是孤立美化，而是把真实硬件资源、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 和诊断错误。