pikasTech-unidesk/TEST.md

# UniDesk Manual Test Plan

## T1 CLI 可观测性与配置校验

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts help`、`bun scripts/cli.ts config show`、`bun scripts/cli.ts check`，确认每条命令都有 JSON 输出、失败时包含错误对象、`config.json` 是唯一配置来源，且 TypeScript 检查覆盖 `scripts/` 与 `src/components/`。

## T2 Docker 栈异步启动

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts server start`，确认命令立即返回 job id；随后运行 `bun scripts/cli.ts job status latest` 观察构建和启动进度，直到 job 状态为 `succeeded`，且输出包含 `.state/jobs/` 日志路径和 `logs/{YYYYMMDD}/` 服务日志路径。

## T3 主 server 自接入 Provider Gateway

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts server status` 和 `bun scripts/cli.ts debug health`，确认公网只监听 frontend 与 provider ingress，backend-core 和 database 显示为 Docker 内部端口，`/api/nodes` 中存在 `main-server` provider，状态为 `online`，`/api/nodes/system-status` 中存在 CPU/内存/硬盘采样，`/api/nodes/docker-status` 中存在 `main-server` 的 Docker 快照，且 provider 标签中能看到 Docker socket 可用性。

## T4 前端控制台连通

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：先用 `bun scripts/cli.ts server status` 获取 frontend URL，再用浏览器访问该 URL，使用默认账号 `admin` 和默认密码 `Liang6516.` 登录，确认左侧主模块、顶部当前模块子标签、核心指标、Provider 控件和事件流可见；页面布局应紧凑、信息密度高、字体不过大，且移动端宽度下左侧栏转为高度一致、较窄、单行不换行的横向模块条，内容较少的主内容页和空状态也必须从顶部向下排列，不得上下居中留白。

## T5 真实任务下发链路

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts debug dispatch main-server docker.ps`，随后运行 `bun scripts/cli.ts debug health` 或在前端事件流中确认任务状态经历 `accepted`、`running`、`succeeded`，并能看到 provider 通过 Docker socket 返回容器列表摘要。

## T6 日志第一现场验证

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts server logs --tail-bytes 20000`，实际读取输出中列出的 `logs/{YYYYMMDD}/` 文件，确认 backend-core、frontend、provider-gateway、database 都有实时日志；日志不得只有启动行，错误日志必须包含可定位的错误消息或 stack。

## T7 停止与端口释放

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts server stop`，确认立即返回 job id；等待 `bun scripts/cli.ts job status latest` 成功后运行 `bun scripts/cli.ts server status`，确认 frontend 与 provider ingress 公网端口不再监听，backend-core 与 database 没有宿主机端口映射，容器状态不再运行。

## Issue 记录

测试发现的问题写入 `docs/issue/`，文件命名为 `{NN}_{issue_title}_{YYYYMMDD}.md`，其中 `NN` 从 `01` 递增；问题文档必须包含复现命令、实际输出摘要、期望行为和修复判定标准。

## T8 Playwright 公网前端 E2E

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：确认 `config.json` 的 `network.publicHost` 是主 server 公网地址，运行 `bun scripts/cli.ts e2e run`，要求 JSON 中 `network:only-frontend-provider-ports`、`network:core-public-blocked`、`network:database-public-blocked`、`network:findjob-public-blocked`、`core:internal-overview`、`provider:self-node-online`、`provider:gateway-version-label`、`provider:system-status`、`provider:docker-status`、`provider:upgrade-plan`、`provider-ingress:public-health`、`microservice:catalog-findjob`、`microservice:catalog-pipeline`、`microservice:findjob-health`、`microservice:findjob-summary`、`microservice:findjob-jobs-preview`、`microservice:pipeline-status`、`microservice:pipeline-health`、`microservice:pipeline-snapshot`、`database:named-volume-write`、`frontend:login-provider-visible`、`frontend:public-provider-info-visible`、`frontend:no-naked-json-before-click`、`frontend:system-monitor-visible`、`frontend:upgrade-plan-dispatch`、`frontend:docker-status-visible`、`frontend:gateway-version-records-visible`、`frontend:provider-operation-availability-visible`、`frontend:microservice-catalog-visible`、`frontend:findjob-integrated-visible`、`frontend:pipeline-integrated-visible` 全部 passed；打开输出的 screenshotPath，确认 Playwright 访问的是公网 frontend，页面上能看到 `main-server`、`Main Server Provider`、`D601`、`FindJob`、`Pipeline`、`SSH 透传`、`远程更新` 和结构化控件。

## T9 Database 命名卷持久化

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：向 `unidesk_e2e_markers` 插入一个唯一 marker，运行 `bun scripts/cli.ts server start` 并等待 `job status latest` 为 `succeeded`，再用 `docker exec unidesk-database psql -U unidesk -d unidesk` 查询该 marker 仍存在；同时审查 `docker-compose.yml` 和 `scripts/src/docker.ts`，确认 CLI server 控制没有使用 `down -v` 或 volume 删除命令。

## T10 前端 JSON 控件化展示

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts e2e run`，确认 `frontend:no-naked-json-before-click` passed；再用浏览器登录 frontend，确认节点标签、事件 payload、任务 payload/result 都渲染为徽标、字段摘要、表格或卡片，页面初始状态没有裸 JSON，只有点击 `查看原始JSON` 后才出现原始 JSON 弹窗或高级编辑区。

## T11 资源节点 Docker 状态

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts e2e run`，确认 `provider:docker-status` 和 `frontend:docker-status-visible` passed；再用浏览器登录 frontend，进入左侧 `资源节点` 和顶部 `Docker 状态` 子标签，确认可以像 Docker Desktop 一样看到当前节点的 Containers、Images、Volumes、Networks 指标、容器表格、镜像/卷/网络侧栏和 Docker daemon 摘要，并确认数据库命名卷 `unidesk_pgdata_10gb` 在 Volumes 区域和数据库命名卷卡片中显式可见。

## T12 前端 TypeScript + React 源码约束

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `find src/components/frontend -type f \\( -name '*.js' -o -name '*.jsx' \\) -print`，确认没有手写 frontend JS/JSX 源码；运行 `bun scripts/cli.ts check`，确认 `src/components/frontend/src/app.tsx` 纳入 TypeScript 检查，且浏览器请求 `/app.js` 由 frontend Bun server 从 TSX 转译生成。

## T13 资源节点任务管理器曲线

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts e2e run`，确认 `provider:system-status` 和 `frontend:system-monitor-visible` passed；再用浏览器登录 frontend，进入左侧 `资源节点` 和顶部 `资源监控` 子标签，确认可以像 Windows 任务管理器一样看到 CPU、Memory、Disk 当前用量和历史曲线，Memory 明确显示为不含 Linux page cache / buffer 的实际内存占用，并能执行 `Provider Gateway 升级` 的 `预检升级`。

## T14 Provider Gateway 远程升级

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts debug dispatch main-server provider.upgrade`，随后查看任务历史或 `bun scripts/cli.ts debug health`，确认 `provider.upgrade` 通过真实 WebSocket 下发并以 `mode: plan` 成功返回升级计划且计划中包含 `policy: "always-enabled"`、`--no-deps` 和 `--force-recreate`；对明确要升级或重建 `provider-gateway` 容器的计算节点，必须再运行 `bun scripts/cli.ts debug dispatch <PROVIDER_ID> provider.upgrade --mode schedule --wait-ms 15000`，确认任务成功、result 包含 updater 容器信息、节点随后重新上线。在非主 server 的计算节点上，必须使用 `bun scripts/cli.ts --main-server-ip 74.48.78.17 debug dispatch <PROVIDER_ID> provider.upgrade --mode schedule --wait-ms 15000` 做同一验证，证明该节点能通过公网 frontend remote CLI 自测自动升级，且不需要指定 `--main-server-key`。正式执行计算节点 `provider-gateway` 重建/升级只能通过前端 `资源监控` 的 `执行升级` 或等价的 `provider.upgrade mode=schedule` 显式调度完成，不能通过 `bun scripts/cli.ts ssh <PROVIDER_ID>` 或 Host SSH 维护桥同步执行自重建命令，也不能通过 `PROVIDER_UPGRADE_ENABLED` 或等价开关禁用远程升级。

## T15 待处理任务可追溯

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts e2e run`，确认 `frontend:pending-task-drilldown`、`frontend:mobile-nav-fixed-height` 和 `frontend:mobile-content-top-aligned` passed；再登录 frontend，点击 `态势总览` 的 `待处理任务` 指标，确认会进入 `任务调度 / 待处理任务` 子标签，并能看到每个 queued、dispatched、running 任务的 Provider、已等待时间、payload 摘要和 `查看原始JSON` 按钮。backend-core 超过 `TASK_PENDING_TIMEOUT_MS` 的待处理任务必须自动转为 failed，避免总览数字长期卡住。

## T16 任务历史诊断信息

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts e2e run`，确认 `frontend:task-history-diagnostics` passed；再登录 frontend，进入 `任务调度 / 任务历史`，确认每个任务行都能看到状态、任务命令和 id、Provider、任务耗时、载荷摘要、诊断信息、更新时间和 `查看原始JSON` 按钮。失败任务必须在默认表格中显示失败原因以及 exit code、timeout、previous status 等关键字段，完整 result 只能点击 `查看原始JSON` 查看。

## T17 Provider Gateway Host SSH / WSL SSH 维护桥

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：确认目标 provider-gateway 已只读挂载维护私钥目录到 `/run/host-ssh`，目标宿主或 WSL 的 sshd 已启动且 `authorized_keys` 包含对应公钥；运行 `bun scripts/cli.ts debug dispatch main-server host.ssh --wait-ms 15000`，再运行 `bun scripts/cli.ts debug task latest`，确认任务通过真实 WebSocket 下发、状态为 `succeeded`、result 中 `probeLine` 包含 `UNIDESK_SSH_TEST`、`exitCode` 为 0、`hostSshKeyPresent` 为 true。随后运行 `bun scripts/cli.ts ssh main-server hostname`，确认输出是远端 hostname 且进程 exit code 为 0；再用 `printf 'pwd\nexit\n' | bun scripts/cli.ts ssh main-server` 验证无命令参数时能进入并退出远端登录 shell。对 D518 这类无公网 SSH 的 WSL 节点，使用同一命令替换 Provider ID 为 `D518`，必要时先用 debug dispatch 加 `--cwd /home/ubuntu` 覆盖远端工作目录，只能通过 provider-gateway 自连维护桥验证，不得把主 server 直连节点公网 22 端口作为通过标准；在计算节点本机还必须用 `bun scripts/cli.ts --main-server-ip 74.48.78.17 debug dispatch <PROVIDER_ID> host.ssh --wait-ms 15000` 和 `bun scripts/cli.ts --main-server-ip 74.48.78.17 ssh <PROVIDER_ID> hostname` 自测 remote CLI 透传，命令不得要求 `--main-server-key`。

## T18 Provider Gateway 版本与自动更新记录

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts e2e run`，确认 `provider:gateway-version-label`、`frontend:gateway-version-records-visible` 和 `frontend:provider-operation-availability-visible` passed；再登录公网 frontend，进入 `资源节点 / 网关版本`，确认每个 Provider 行都显示 provider-gateway 版本号、升级策略、SSH 透传可用性、远程更新可用性、能力摘要、最近自动更新记录，并在下方以表格记录 `provider.upgrade` 的状态、模式、任务 id、来源、耗时、策略、结果摘要和更新时间。自动更新记录默认必须是结构化控件，不得展示裸 JSON；完整 task/result 只能通过 `查看原始JSON` 按钮查看。

## T19 前端单服务重建

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts server rebuild frontend`，确认命令立即返回 `server_rebuild` job id；随后运行 `bun scripts/cli.ts job status latest` 直到状态为 `succeeded`，stdout 中必须能看到先 build、再按 `frontend` 服务容器 label 移除、最后 `--no-deps frontend` 启动的过程。重建后运行 `bun scripts/cli.ts server status` 和 `bun scripts/cli.ts e2e run`，确认公网 frontend 恢复健康、Playwright 登录通过、database 命名卷未被删除；正式验收不得要求人工执行 `docker rm` 作为兜底。

## T20 D601 FindJob Microservice

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts microservice list`，确认 `findjob` 显示为 `providerId=D601`、`public=false`、`frontendOnly=true`、仓库 URL、commit id、`127.0.0.1:3254` 后端映射和 `findjob-server` 容器摘要；运行 `bun scripts/cli.ts microservice health findjob` 和 `bun scripts/cli.ts microservice proxy findjob /api/summary`，确认链路通过 backend-core、D601 provider-gateway 和 D601 本机 FindJob 后端；运行 `bun scripts/cli.ts --main-server-ip 74.48.78.17 microservice health findjob`，确认非主 server 也能通过公网 frontend remote CLI 验证同一链路且不需要 `--main-server-key`。随后运行 `bun scripts/cli.ts e2e run`，确认 microservice 和 frontend FindJob 检查全部 passed；再登录公网 frontend `http://74.48.78.17:18081/`，进入 `微服务 / 服务目录` 和 `微服务 / FindJob`，确认页面以 React 控件显示 D601、仓库引用、私有后端映射、FindJob 指标、岗位预览和草稿报告，默认没有裸 JSON，只有点击 `查看原始JSON` 才显示原始数据。FindJob 业务代码开发和调试必须用 `bun scripts/cli.ts ssh D601 ...` 进入 D601 的 `/home/ubuntu/findjob`，不得把 findjob 全量代码复制进 UniDesk 仓库，也不得占用主 server 部署调试服务。

## T21 D601 Pipeline Microservice

阅读 `AGENTS.md`（本项目 `AGENTS.md` 同时承担 `SKILL.md` 对 `scripts/cli.ts` 的解释职责），然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts microservice list`，确认 `pipeline` 显示为 `providerId=D601`、`public=false`、`frontendOnly=true`、仓库 URL `https://github.com/pikasTech/pipeline`、commit id、`127.0.0.1:18082` 后端映射和 `pipeline-v2-webui` 容器摘要；运行 `bun scripts/cli.ts microservice health pipeline` 和 `bun scripts/cli.ts microservice proxy pipeline '/api/snapshot?__unideskArrayLimit=registry.components:8,runs:3'`，确认链路通过 backend-core、D601 provider-gateway 和 D601 本机 Pipeline 后端，snapshot 返回 `ok=true`、组件 registry 和 Pipeline run 预览；运行 `bun scripts/cli.ts --main-server-ip 74.48.78.17 microservice health pipeline`，确认非主 server 也能通过公网 frontend remote CLI 验证同一链路且不需要 `--main-server-key`。随后运行 `bun scripts/cli.ts e2e run`，确认 microservice 和 frontend Pipeline 检查全部 passed；再登录公网 frontend `http://74.48.78.17:18081/`，进入 `微服务 / 服务目录` 和 `微服务 / Pipeline`，确认页面以 React 控件显示 D601、仓库引用、私有后端映射、Pipeline 组件矩阵、控制图、最近运行和证据日志摘要，默认没有裸 JSON，只有点击 `查看原始JSON` 才显示原始数据。Pipeline 业务代码开发和调试必须用 `bun scripts/cli.ts ssh D601 ...` 进入 D601 的 `/home/ubuntu/pipeline`，不得把 pipeline 全量代码复制进 UniDesk 仓库，也不得占用主 server 部署调试服务。