docs: distill v03 React Vue parity closeout

docs/reference/spec-v03-workbench-vue-migration.md

@@ -49,6 +49,29 @@ Sub2API `v0.1.136` 对照必须来自真实 frontend 源码，不允许凭记忆
 | `composables/useAutoRefresh.ts` localStorage 保存 enabled/interval/countdown/fetching，组件卸载清 timer | 可作为 Workbench live refresh 和 HWPOD panel refresh 控件基础。 | 不得用 auto-refresh 替代 Code Agent trace subscription；trace 仍由 `useTraceSubscription` 无限 poll 并使用 `activityRef`。 |
 | `composables/useClipboard.ts` Clipboard API + textarea fallback + toast | 可直接迁移为工作台复制 trace/result/session id 的通用 composable。 | 成功/失败文案走 HWLAB app store/i18n；不要把复制行为和业务状态 mutation 耦合。 |
 
+## React 到 Vue 功能补齐分层
+
+React 到 Vue 迁移不能只以 shell/auth smoke 作为完成信号。每次大版本前端迁移都必须先建立 React 基线功能表、目标 Vue 模块表和运行面验证表，再按功能层关闭退化；issue #775 的裸 JS 到 React 迁移退化和 issue #1149 的 React 到 Vue 迁移退化都按这个口径复盘。
+
+| 补齐层 | React 基线能力 | Vue 目标模块 | 验收口径 |
+|---|---|---|---|
+| R1 Workbench 会话与 trace | Markdown 消息、assistant/user action、trace summary、status summary、copy/retry/cancel/replay。 | `stores/workbench`、`components/workbench/*`、`useTraceSubscription`。 | 同源 Workbench route 能创建/选择 session、提交 turn、展示 trace/result/status，并保留 message action。 |
+| R2 Composer 与 session 生命周期 | drafts、provider profile selector、普通 send 不隐式建 session、stale trace cleanup、session delete/select。 | `stores/workbench` getter/action、composer 组件、session sidebar。 | 未选 session 的普通 send 返回 `session_required`；切换/删除 session 不遗留 running trace 或过期 draft。 |
+| R3 Live status 与 HWPOD node ops | health/live、adapter、REST index、live builds、HWPOD specs、node-ops status/freshness/blocker。 | `api/workbench.liveSurface`、HWPOD panel、auto-refresh composable。 | 面板数据来自 `/v1/hwpod-node-ops` 与 `/v1/hwpod/specs?probe=1`，不得用 fixture 或 blocked fallback 代替。 |
+| R4 Access 与 Provider Profiles | OpenFGA subject/resource/decision/relationship 管理，provider profile CRUD、auth JSON/config TOML 脱敏。 | `api/access`、`api/providerProfiles`、admin views、common form/table/dialog。 | CRUD、校验、错误提示和敏感字段脱敏都走同源 API；不得把 profile secret 泄露到 UI、日志或 fixture。 |
+| R5 Gate、Performance、RUM 与 Skills | gate/run status、performance timeline、RUM event/timing、skills install/list/status。 | `api/gates`、`api/performance`、`api/skills`、dashboard/admin views。 | 每个 route 有空态、加载态、失败态和真实 API smoke；performance route 不启动 Workbench live refresh。 |
+| R6 common UI 与横切 composables | table/form/dialog/toast/clipboard/route title/chunk recovery/navigation progress。 | `components/common/*`、`stores/app`、router meta、`useClipboard`、`useTableLoader`、`useForm`。 | 所有业务页复用 common 原语；chunk load 失败可恢复，route title 不回退为 Sub2API 文案。 |
+
+Sub2API 是分层和组件治理参考，不是 HWLAB 的配置来源、运行面来源或鉴权模型。吸收 Sub2API 类平台代码时必须在对照表中明确“可吸收形态”和“必须改写语义”：common table/form/dialog/pagination、router meta/title/chunk recovery、Pinia/api/composable 分层、敏感字段脱敏可以吸收；bearer token、refresh token、上游账号配置、Caddy 暴露策略和 API runtime truth 不得迁入 HWLAB。
+
+## 运行面来源和覆盖判定
+
+迁移后出现“源码曾经成功、运行面又退回”的现象时，先按 source propagation 链路判定，不要直接归因为其他服务覆盖。检查顺序固定为：目标 lane 固定 repo、GitHub source branch、Git mirror sourceHead、PipelineRun sourceCommit、镜像 digest、Argo revision、pod runtime 文件和 public route smoke；只有这些证据显示同一文件在 Git truth 之外被重写时，才进入外部覆盖调查。
+
+已知容易误判为覆盖的来源包括旧 `deploy/deploy.yaml`、历史 guard/preflight、D601 git mirror 同步窗口、落后 worktree 触发的旧 PipelineRun，以及运行面热补被正常 GitOps rollout 覆盖。处理这类问题时，先把旧入口从源码和 CI/CD 路径中清除，再通过原入口 smoke 证明当前 runtime 已经来自目标 commit。
+
+Caddyfile 写入属于 YAML-first 平台运维能力，不属于前端迁移代码。多个 YAML 来源共存时必须使用按 site/key 定位的 managed block merge：每个模块只能维护自己的声明块，禁止整文件覆盖、禁止把 Sub2API 的 Caddy block 当作 HWLAB 公共入口模板、禁止从运行面 Caddyfile 反推本地 YAML。HWLAB public exposure 继续以 HWLAB lane YAML/control-plane 为 truth；Sub2API Caddy 规则只能作为“共享 Caddy 模块支持多来源互不影响”的架构参照。
+
 ## Vue Pinia / Composable 目标映射
 
 | 目标文件 | 责任边界 | 必须暴露的接口 |
@@ -85,5 +108,6 @@ Sub2API `v0.1.136` 对照必须来自真实 frontend 源码，不允许凭记忆
 
 - 源码层：Vue 迁移 PR 至少覆盖 `api/client` inactivity、`useTraceSubscription` polling、`stores/workbench.composer`、`useTraceReattach` placeholder/terminal persistence、HWPOD label mapping。
 - 静态检查：保留 `bun run --cwd web/hwlab-cloud-web check` 或 Vue 等价入口；不得恢复旧 quick prompt、旧 layout smoke 或与当前契约无关的门禁。
+- 功能退化检查：迁移关闭前必须按“React 到 Vue 功能补齐分层”逐项跑 route/API smoke；shell/auth 可用只能证明应用能启动，不能证明 Workbench、Access、Provider、HWPOD、Gate、Performance、Skills 或 common UI 已补齐。
 - 同路径验收：显式创建或选择 Code Agent session 后，通过 Web 同源 path 提交 turn，`result/trace --render web` 使用同一 trace row；未选择 session 的普通 send 必须返回 `session_required`。
 - HWPOD 验收：Vue 面板必须从 `/v1/hwpod-node-ops` 与 `/v1/hwpod/specs?probe=1` 显示 status/freshness/blocker，不得用 fixture 或 blocked fallback 声称真实硬件 DEV-LIVE。