docs: 补充Jenkins和K8s只读观测设计

docs/superpowers/specs/2026-06-18-admin-environment-dashboard-design.md

@@ -11,9 +11,9 @@ Admin 当前 `/dashboard/analytics` 仍是 Vben 示例页，展示用户量、
 - Admin `/dashboard/analytics` 当前是静态页面，可整体替换。
 - Admin 已有 QQBot、插件任务、系统日志、Blog/Asset 等 API wrapper，但没有统一环境状态 wrapper。
 - API 已有 runtime health、系统日志、QQBot 汇总、NapCat runtime、插件平台、插件任务、MinIO 和 WordPress 信号源。
-- API 源码内没有 Jenkins/K8s/部署状态 Controller 或 Service；实时部署观察目前主要靠 `mcp/ktWorkflow` 与 NAS/K8s 外部命令。
+- API 源码内没有 Jenkins/K8s/部署状态 Controller 或 Service；实时部署观察目前主要靠 `mcp/ktWorkflow` 与 NAS/K8s 外部命令。本轮需要补齐 Jenkins/K8s 只读观测适配器，但只允许读取发布证据，不允许执行部署或 K8s 写操作。
 
-因此第一版必须采用“API 统一聚合合同 + Admin 拓扑消费”的结构：页面不散拼多个旧接口；API 不伪造未接入的环境状态；高风险动作先显式禁用或跳转，不直接执行。
+因此第一版必须采用“API 统一聚合合同 + Admin 拓扑消费”的结构：页面不散拼多个旧接口；API 不伪造环境状态；Jenkins/K8s 作为只读观测节点接入；高风险动作先显式禁用或跳转，不直接执行。
 
 ## 已确认决策
 
@@ -23,7 +23,7 @@ Admin 当前 `/dashboard/analytics` 仍是 Vben 示例页，展示用户量、
 4. 第一版只允许低风险动作：刷新、执行只读自检、打开日志、跳转到已有管理页、打开外部只读入口。
 5. 重启 Pod、触发 Jenkins 部署、DB 写入、重建 NapCat 容器、启停插件或定时任务等高风险动作，第一版只能作为 disabled action 展示原因和未来入口。
 6. API 聚合接口必须受 Admin JWT 保护，返回 Vben 统一响应，不泄露密钥、token、原始 env、QQBot 大字段或未脱敏日志。
-7. Jenkins/K8s 如果暂时没有可由 API 安全读取的凭据或适配器，也必须在拓扑中显示为 `unknown` / `unwired`，不能从页面消失或伪造成正常。
+7. Jenkins/K8s 第一版必须接入只读观测：Jenkins 读取最近构建、提交、结果和时间；K8s 读取 Deployment、Pod、镜像、ready 数、restartCount 和事件摘要。缺配置或读取失败时显示 `unknown` / `down` 与失败证据，不能显示 `unwired` 或伪造成健康。
 
 ## 目标
 
@@ -32,15 +32,16 @@ Admin 当前 `/dashboard/analytics` 仍是 Vben 示例页，展示用户量、
 - 把现有分散信号源收敛到一个只读聚合服务，保持每个信号源可独立降级。
 - 在 UI 上明确区分 `ok`、`degraded`、`down`、`blocked`、`unknown`、`unwired`。
 - 用证据字段解释每个状态来自哪里、何时检查、是否实时、是否缓存、失败原因是什么。
-- 为后续接入 Jenkins/K8s 只读观测、部署记录、任务运行历史和自动化恢复留出合同扩展点。
+- 接入 Jenkins/K8s 只读观测，展示线上部署链路状态，但不提供任何操作能力。
+- 为后续部署记录历史、任务运行历史和自动化恢复留出合同扩展点。
 
 ## 非目标
 
 - 不在第一版执行部署、重启、数据库写入、插件启停、NapCat 容器重建等高风险动作。
 - 不把 Admin 页面做成营销式图表页或静态展示页。
 - 不绕过现有 QQBot、NapCat、插件平台、WordPress、MinIO 的业务边界。
-- 不要求 API Pod 内直接持有生产 kubeconfig、Jenkins 写权限或 NAS SSH 写权限。
+- 不要求 API Pod 内持有 Jenkins 写权限、K8s 写权限或 NAS SSH 写权限。
-- 不把外部不可读的 Jenkins/K8s 状态假装成健康。
+- 不把 Jenkins/K8s 读态失败、凭据缺失或 RBAC 缺失假装成健康。
 - 不在本轮新增长期运行的后台巡检任务或历史表，除非后续实施计划明确需要。
 
 ## 信息架构
@@ -126,7 +127,7 @@ QQBot 层
 - `external-link`：只能提供外部入口，API 不能直接读取。
 - `unwired`：设计中必须存在，但当前未接入真实信号。
 
-拓扑节点不得因为没有接入真实读取就隐藏。未接入的 Jenkins/K8s 节点第一版应显示为 `unknown` 或 `unwired`，并在证据抽屉写明“API 当前没有只读观测适配器”。
+拓扑节点不得因为没有接入真实读取就隐藏。Jenkins/K8s 在第一版必须接入只读观测适配器；如果配置、网络、凭据或 RBAC 缺失，节点状态应为 `unknown` 或 `down`，证据抽屉写明具体失败点，不能再标为 `unwired`。
 
 ## API 合同
 
@@ -407,8 +408,10 @@ blocked > down > degraded > unknown/unwired > ok
 
 来源：
 
-- 第一版默认 `unwired` / `external-link`。
+- Jenkins 只读 API：读取指定 job 的最近 build number、result、building、timestamp、duration、commit/hash、branch 和构建 URL。
-- 如果后续配置只读 Jenkins token、只读 K8s service account 或 deploy-observation evidence 文件，才能升级为 `live` 或 `cached`。
+- K8s 只读 API：读取指定 namespace/deployment 的 generation、observedGeneration、replicas、updatedReplicas、readyReplicas、availableReplicas、镜像、Pod phase、restartCount 和最近 warning event 摘要。
+- Deploy observation evidence：如果已有 `mcp/ktWorkflow deploy-observation` 产物或等价线上证据文件，可作为 `cached` 证据补充 Jenkins/K8s live 读取。
+- 外部链接：Jenkins/K8s Dashboard 链接只作为跳转，不替代只读状态读取。
 
 节点：
 
@@ -420,15 +423,26 @@ blocked > down > degraded > unknown/unwired > ok
 第一版行为：
 
 - 拓扑上显示节点。
-- 提供外部链接或“未配置只读观测适配器”的证据。
+- Jenkins/K8s/NAS 节点必须有只读观测证据或明确的读取失败证据。
+- 只允许 `GET` / list/watch 等只读能力；K8s RBAC 必须限制为 deployment、pod、event、replicaset 等观测资源的 `get/list/watch`。
+- Jenkins 凭据必须是只读账号或只读 token，不允许 job build、replay、configure、credential 相关权限。
 - 高风险动作如“触发部署”“重启 Pod”“查看敏感 Secret”全部 disabled。
 
-后续扩展：
+读取字段：
 
-- 新增只读 deploy evidence adapter。
+- Jenkins：jobPath、buildNumber、result、building、branch、commitSha、commitMessageSummary、startedAt、durationMs、url。
-- 读取最近 Jenkins build number、commit、result。
+- K8s Deployment：namespace、name、generation、observedGeneration、replicas、updatedReplicas、readyReplicas、availableReplicas、currentImage、desiredImage。
-- 读取 K8s deployment generation/ready/updated/pod restartCount。
+- K8s Pod：podName、phase、ready、restartCount、image、nodeName 可选、startedAt、lastWarningReason。
-- 只读证据仍必须脱敏，不暴露 kubeconfig、token、Secret。
+- NAS Runtime：第一版只展示 `external-link` 或 cached deploy-observation 证据，不执行 SSH；如果没有可读证据，状态为 `unknown` 且写明未配置只读 NAS 证据源。
+
+失败语义：
+
+- Jenkins token 缺失或 403：`unknown`，evidence 写明 `jenkins-readonly-auth-missing` 或 `jenkins-readonly-forbidden`。
+- Jenkins 最近 build failed：`down` 或 `degraded`，按是否影响当前线上镜像判断。
+- K8s RBAC 403：`unknown`，evidence 写明 `k8s-readonly-rbac-forbidden`。
+- Deployment 未就绪：`down`。
+- Pod restartCount 增长或 warning event：`degraded`。
+- 只读证据必须脱敏，不暴露 kubeconfig、token、Secret、完整 Jenkins console log。
 
 ## 安全总控 Action Catalog
 
@@ -509,7 +523,8 @@ apps/web-antdv-next/src/api/system/environment.ts
 - 新增或触碰函数、方法、handler、job 必须补 JSDoc，参数说明要写来源和用途。
 - 不泄露 secrets、token、password、raw env、kubeconfig、SSH 信息、QQBot 大字段。
 - QQBot 摘要不得返回 `replyText`、base64 图片或过长日志。
-- Jenkins/K8s 未接入时返回 `unwired`，不得伪造健康。
+- Jenkins/K8s 必须接入只读观测；读取失败时返回 `unknown` / `down` 和失败证据，不得退回 `unwired` 或伪造健康。
+- Jenkins/K8s 适配器必须在代码和权限上只读：不得调用 Jenkins build/configure/replay，不得调用 K8s create/update/patch/delete/exec/log secret 等写入或敏感接口。
 
 ## 缓存与成本
 
@@ -520,6 +535,7 @@ apps/web-antdv-next/src/api/system/environment.ts
 - NapCat/account runtime 读取复用现有 TTL，不强制刷新所有账号。
 - WordPress/MinIO 外部探测设置独立短超时。
 - Loki summary 查询失败时只降级日志节点。
+- Jenkins/K8s 只读探测设置独立短超时，读取失败只降级部署层节点。
 
 缓存返回需要在 evidence 中标注：
 
@@ -539,7 +555,8 @@ apps/web-antdv-next/src/api/system/environment.ts
 
 - `GET /system/environment/dashboard` 本地真实请求返回 Vben 包装。
 - 响应中包含 summaryCards、topology.nodes、topology.edges、actions、recentEvents。
-- Jenkins/K8s 未配置时显示 `unwired` 或 `external-link`，不导致接口失败。
+- Jenkins/K8s 节点由只读适配器提供 build/deployment/pod 证据；缺配置、403 或超时时显示 `unknown` / `down` 与原因，不导致接口失败。
+- Jenkins/K8s 适配器没有任何部署、重启、patch、delete、exec 或 secret 读取路径。
 - 任一可模拟信号源失败时接口仍 200，并将对应节点标为 `unknown` / `degraded` / `down`。
 - 不返回敏感字段或 QQBot 大字段。
 
@@ -558,13 +575,15 @@ apps/web-antdv-next/src/api/system/environment.ts
 - 线上 Admin 页面可打开。
 - 线上 dashboard 接口 200。
 - 线上页面至少展示 API Runtime、System Logs、QQBot、NapCat、Plugin Platform、MinIO、WordPress、Jenkins/K8s 节点。
-- 对未接入的 Jenkins/K8s 节点，页面明确展示未接入证据而非健康假象。
+- 线上页面的 Jenkins/K8s 节点展示真实只读观测证据：Jenkins 最近 build、commit、result；K8s Deployment ready/updated、Pod image、restartCount。
+- Jenkins/K8s 操作项只展示 disabled，不允许触发部署、重启 Pod、修改资源或读取 Secret。
 
 ## 测试计划方向
 
 实施计划阶段应覆盖：
 
-- API service 单测：状态严重度聚合、partial failure、unwired 节点、action catalog。
+- API service 单测：状态严重度聚合、partial failure、unwired 节点、action catalog、Jenkins/K8s read-only failure mapping。
+- API Jenkins/K8s adapter 单测：只允许只读路径，覆盖 200、403、timeout、failed build、deployment not ready、pod restart warning。
 - API controller contract spec：鉴权路由、Vben response shape、self-check 只读行为。
 - Admin API wrapper Vitest：请求路径和响应类型。
 - Admin 页面组件测试：拓扑节点、证据抽屉、disabled actions。
@@ -576,8 +595,6 @@ apps/web-antdv-next/src/api/system/environment.ts
 
 后续可以在不破坏第一版合同的基础上增加：
 
-- 只读 Jenkins build adapter。
-- 只读 K8s deployment/pod adapter。
 - deploy observation evidence 入库或文件读取。
 - 安全动作审计表。
 - 二次确认和权限码控制的高风险动作。