# TanStack Start dashboard：真实 control-plane 手工联调记录

> 最终复核已覆盖先前审核指出的两项缺口：原登记的 `plan01-gateway`（`127.0.0.1:28187`）通过真实 UI 完成启动与停止；竞品流程使用匿名临时浏览器完成抖音作者预览与加入监听，并确认临时 runtime 已清理。最终生命周期录制：`/home/rogee/.config/browser-harness/agent-workspace/recordings/creatorhub-registered-native-gateway-lifecycle-final`；竞品录制：`/home/rogee/.config/browser-harness/agent-workspace/recordings/creatorhub-anonymous-competitor-final`。

## 验收范围

- 分支：`feat/tanstack-start-dashboard`
- 当前源码版本：`45a29ea`（工作区包含未提交的迁移修改）
- 前端：`http://127.0.0.1:4176`
- control-plane：`http://127.0.0.1:8082`
- 验证数据库：`creatorhub-plan01-pg`，宿主端口 `15432`
- 浏览器工具：`browser-harness`
- 录制：`/home/rogee/.config/browser-harness/agent-workspace/recordings/creatorhub-tanstack-control-plane-pass3`，50 帧
- 交互录制：`.../creatorhub-tanstack-control-plane-actions-pass2`，82 帧；native 环境启动/停止重试：`.../creatorhub-tanstack-control-plane-native-environment-pass2` 与 `.../creatorhub-tanstack-control-plane-native-environment-stop-final`，各 8 帧

录制文件保留在本机工作区，没有复制进仓库：画面包含本地开发账号、账号标识和环境标识。本文不保存密码、Cookie、token 或录制内容中的敏感数据。

## 手工流程结果

登录前先清除当前标签页的本地会话，再通过 `browser-harness` 的真实输入事件填写登录表单；没有预置 localStorage 登录状态。

| 流程 | 路由 | 验证结果 |
| --- | --- | --- |
| 登录 | `/login` → `/accounts` | 跳转成功，会话已建立，无 alert |
| 账号 | `/accounts` | 显示账号列表与账号操作，无错误文案 |
| 环境 | `/browsers` | 使用原登记的 `plan01-gateway`（`127.0.0.1:28187`）完成真实启动：页面显示“运行中 / 可调度 / CDP `http://127.0.0.1:19000`”；随后真实停止，页面显示“已停止 / 运行实例缺失” |
| 竞品 | `/creator/competitors` | 使用 `https://www.douyin.com/video/7685553258340830507` 完成匿名解析，页面显示作者预览并确认作者，随后确认加入监听；API 验证新增启用监听记录，匿名 runtime 已释放并清理 |
| 工作台 | `/creator/workbench` | 显示评论、线索、规则、事件监听、私信和操作记录页签，无错误文案 |
| 任务 | `/tasks` | 显示任务筛选和空状态，无错误文案 |

逐页加载检查确认：URL 与 TanStack 文件路由一致、主标题存在，正文不包含“控制面代理不可用”“网络请求失败”或“认证已过期”等通用错误。实际操作产生的领域提示（账号详情说明、竞品无可用已登录账号、gateway 启动失败）均保留在下方操作记录，不被当成成功。

## 联调边界检查

- `/healthz`：`204`
- `/readyz`：`204`
- `/api/gateways`：`200`
- `/api/phase-a/accounts`：`200`
- `/api/browsers`：`200`
- `/api/creator/accounts`：`200`
- `/api/creator/updates`：通过前端 `/api` 代理收到初始 `retry: 5000` SSE 事件；测试客户端主动超时断开后 control-plane 仍返回 `/healthz 204`

本次联调还覆盖了真实 `/api` 代理，而不是 Playwright mock。Playwright 仍只作为既有响应式回归测试，不作为本记录的真实 control-plane 证据。

## 实际交互操作记录

第二份 browser-harness 录制：`/home/rogee/.config/browser-harness/agent-workspace/recordings/creatorhub-tanstack-control-plane-actions-pass2`，82 帧；录制对应以下真实 UI 操作：

- 账号：点击第一条“查看账号”，实际进入 `/accounts/account-committed` 详情页。
- 环境：在原登记的 `plan01-gateway`（`127.0.0.1:28187`）上点击“启动 抖音验收浏览器”，页面显示“运行中 / 可调度 / CDP `http://127.0.0.1:19000`”；再点击停止，页面显示“已停止 / 运行实例缺失”。最终录制见 `creatorhub-registered-native-gateway-lifecycle-final`。
- 竞品：打开“添加监听”，输入 `https://www.douyin.com/video/7685553258340830507`，点击“解析并预览作者”，页面显示作者预览；点击“确认作者并加入队列”，再点击“确认加入监听”，页面显示“相关账号已加入监听队列。”。control-plane API 验证新记录为启用状态；gateway 列表确认只剩已停止的 `plan01-douyin`，没有匿名 runtime。
- 工作台：实际切换“线索、规则、事件监听、私信、操作记录、评论”六个页签，并分别等待内容加载。
- 任务：实际填写并清除账号筛选 `account-committed`，两次列表请求均完成。

早期记录中的旧 Docker gateway 与临时 native gateway 结果保留作历史诊断；最终复核已将登记 gateway 指向可用的 native `127.0.0.1:28187`，并在该登记配置上完成启停录制，不再以临时未登记 gateway 作为验收依据。

## 曾发现并修复的联调阻塞

1. creator SSE 的 `SendStreamWriter` 回调在请求上下文回收后再次调用 `c.RequestCtx()`，会触发 nil pointer panic。现在在开始流式写入前捕获 `requestCtx`，并增加了取消回归测试。
2. 本地验证库的 migration ledger 已记录到较新版本，但实际仍保留 `browser_image`、`image_version`、`old_image_version` 等旧列名，导致浏览器和审计 API 返回 500。开发阶段允许破坏性重建/修正数据库，因此仅在本地验证库执行了 migration 017 对应的表和列重命名；没有加入代码兼容层。旧 Docker image ref 不符合新路径约束，因此该本地修复未强行添加新 check constraint。

## 自动检查结果

| 检查 | 结果 |
| --- | --- |
| `npm --prefix web run test` | 12 files，101/101 passed |
| `npm --prefix web run test:coverage` | Lines 68.57%，高于 65% 门槛 |
| `npm --prefix web run typecheck` | passed |
| `npm --prefix web run build` | passed |
| `npm --prefix web audit --audit-level=low` | 0 vulnerabilities |
| `go test ./...` | passed |
| `go vet ./...` | passed |
| `go build ./cmd/control-plane` | passed |

## 依赖审计数字的解释

目标记录中的“7 个漏洞（1 high、5 moderate、1 low）”是迁移中途的基线，不是当前结果。对应基线 `npm audit --json` 为：

- high：1
- moderate：5
- low：1
- total：7

之后升级了 TanStack Start 到 `1.168.56`、Vite 到 `7.3.6`，并完成 `npm audit fix`。中间结果曾只剩 1 个 low；最终当前 lockfile 的审计结果为 0。因而当前仓库不存在需要继续声明为“仍有 7 个”的漏洞；7 项已作为依赖升级的一部分处理完毕。当前阶段按使用者确认不再扩展安全范围，也不恢复旧 lockfile；恢复旧 lockfile 会重新引入已知漏洞。历史基线与当前 0 的数字保存在 `docs/evidence/tanstack-start-audit-baseline-7.json`，供生产上线前安全复核。

## 构建提示

构建退出码为 0。完整当前输出保存在 `docs/evidence/tanstack-start-build-output.log`，其中可复核 `✓ built`、产物清单及 Nitro 提示。依赖噪声过滤前的完整基线保存在 `docs/evidence/tanstack-start-build-warning-baseline.log`，可复核 TanStack/`use client` 与 Nitro empty-chunk warning；当前配置过滤了已知依赖噪声，仍输出若干 `Generated an empty chunk` 非阻断提示。这些提示不影响产物或联调，按原范围作为后续单独清理项保留。