From 7e05473cf5c0200cfb91f11018a9cbdec6a35645 Mon Sep 17 00:00:00 2001 From: weichen Date: Thu, 17 Sep 2026 07:10:04 +0000 Subject: [PATCH] docs(engineering-dashboard): closeout report matrix and launcher Add test report, FEATURE-MATRIX row, archive the short-term task, mark CURRENT claim done, and ship the thin serve/export script. Co-authored-by: Cursor --- .../2026-09-17-engineering-dashboard.md | 37 +++--- .doc/ops/CURRENT.md | 2 +- .doc/status/FEATURE-MATRIX.md | 1 + ...09-17-engineering-dashboard-test-report.md | 109 ++++++++++++++++++ scripts/engineering-dashboard.sh | 7 ++ 5 files changed, 136 insertions(+), 20 deletions(-) rename .doc/{ => archive}/ops/short-term/2026-09-17-engineering-dashboard.md (54%) create mode 100644 .doc/test-reports/2026-09-17-engineering-dashboard-test-report.md create mode 100755 scripts/engineering-dashboard.sh diff --git a/.doc/ops/short-term/2026-09-17-engineering-dashboard.md b/.doc/archive/ops/short-term/2026-09-17-engineering-dashboard.md similarity index 54% rename from .doc/ops/short-term/2026-09-17-engineering-dashboard.md rename to .doc/archive/ops/short-term/2026-09-17-engineering-dashboard.md index b676ac35..26b8cb87 100644 --- a/.doc/ops/short-term/2026-09-17-engineering-dashboard.md +++ b/.doc/archive/ops/short-term/2026-09-17-engineering-dashboard.md @@ -1,6 +1,6 @@ --- title: "个人工程中控台：实时项目看板与离线 HTML 快照" -status: in_progress +status: done created: 2026-09-17 updated: 2026-09-17 owner: Cursor-Auto @@ -30,31 +30,30 @@ mutex: engineering-dashboard ## 步骤 -1. [ ] U1：冻结快照、事实与四轴状态契约。 -2. [ ] U2：实现文档图谱与领域解析器。 -3. [ ] U3：实现 Git 与 worktree 采集。 -4. [ ] U4：实现运行态与部署证据采集。 -5. [ ] U5：实现对账、派生视图与新鲜度。 -6. [ ] U6：实现本地服务、总览与文档导航。 -7. [ ] U7：实现离线导出、脚本、浏览器验收和治理文档同步。 +1. [x] U1：冻结快照、事实与四轴状态契约。 +2. [x] U2：实现文档图谱与领域解析器。 +3. [x] U3：实现 Git 与 worktree 采集。 +4. [x] U4：实现运行态与部署证据采集。 +5. [x] U5：实现对账、派生视图与新鲜度。 +6. [x] U6：实现本地服务、总览与文档导航。 +7. [x] U7：实现离线导出、脚本、浏览器验收和治理文档同步。 ## 验收标准 -- [ ] 实时 HTML、离线 HTML 和 JSON 引用同一 `generation_id` 与 `revision_id`。 -- [ ] 计划、实施、验证、实装四轴独立展示。 -- [ ] rdev、dev ahead、main events 分叉三个真实样本按方案输出。 -- [ ] 单源失败时页面仍可用，且显示 stale/error/last-success。 -- [ ] 默认仅监听 loopback，无写操作、凭证暴露、路径越界和远程资源执行。 -- [ ] 导出 HTML 离开仓库后仍可阅读 Markdown，且不嵌入 assets。 +- [x] 实时 HTML、离线 HTML 和 JSON 引用同一 `generation_id` 与 `revision_id`。 +- [x] 计划、实施、验证、实装四轴独立展示。 +- [x] rdev、dev ahead、main events 分叉三个真实样本按方案输出。 +- [x] 单源失败时页面仍可用，且显示 stale/error/last-success。 +- [x] 默认仅监听 loopback，无写操作、凭证暴露、路径越界和远程资源执行。 +- [x] 导出 HTML 离开仓库后仍可阅读 Markdown，且不嵌入 assets。 ## 相关链接 - 设计与实施方案：[../../system-design/project-control-center/01-personal-engineering-control-center-plan.md](../../system-design/project-control-center/01-personal-engineering-control-center-plan.md) -- Checklist: 待实施阶段创建 -- Handoff: 待需要时创建 -- Test report: 待实施阶段创建 +- Test report: [../../test-reports/2026-09-17-engineering-dashboard-test-report.md](../../test-reports/2026-09-17-engineering-dashboard-test-report.md) ## 证据 / 备注 -- 方案已合入 `dev@12884a1`；实现认领已登记 CURRENT。 -- 实施在 `.worktrees/feature-engineering-dashboard`，禁止 worktree 内 env-service。 +- 实现提交序列见 `feature/engineering-dashboard`（U1→U7）。 +- 启动：`./scripts/engineering-dashboard.sh serve --repo . --addr 127.0.0.1:8787` +- 导出：`./scripts/engineering-dashboard.sh export --repo . --output /tmp/engdash.html` diff --git a/.doc/ops/CURRENT.md b/.doc/ops/CURRENT.md index d96044c8..26158872 100644 --- a/.doc/ops/CURRENT.md +++ b/.doc/ops/CURRENT.md @@ -13,7 +13,7 @@ | owner | task | branch | worktree | mutex | status | |-------|------|--------|----------|-------|--------| -| Cursor-Auto | 2026-09-17-engineering-dashboard | feature/engineering-dashboard | .worktrees/feature-engineering-dashboard | engineering-dashboard | in_progress | +| Cursor-Auto | 2026-09-17-engineering-dashboard | feature/engineering-dashboard | .worktrees/feature-engineering-dashboard | engineering-dashboard | done | | Cursor | 2026-09-17-promote-null-fk-to-test | feature/promote-null-fk-to-test | - | infra | done | | Cursor | 2026-09-17-docgov-optional-duty-null-fk | fix/docgov-optional-duty-null-fk | - | docgov | done | | Cursor | 2026-09-17-leftover-hygiene | chore/leftover-hygiene-2026-09-17 | - | ops | done | diff --git a/.doc/status/FEATURE-MATRIX.md b/.doc/status/FEATURE-MATRIX.md index 0e890054..420e4f9e 100644 --- a/.doc/status/FEATURE-MATRIX.md +++ b/.doc/status/FEATURE-MATRIX.md @@ -67,6 +67,7 @@ | Artifact 同 digest 晋升 | 候选 commit 一次构建、按 digest 晋升、promotion receipt | done | 加固 | [计划 PU5B](../remediation/2026-09-16-feature-matrix-production-readiness-plan.md)；[Wave2B](../test-reports/2026-09-16-wave2b-nightly-promotion-receipt-test-report.md)；[Wave2C](../test-reports/2026-09-16-wave2c-same-image-digest-test-report.md) | **关闭**：same-image pin（`candidate-images-*` + `PINNED_IMAGE_MODE` + promote `--require-digests`）。**声明**：单机 retag/digest pin；远程 registry 推送另立任务 | `infra` | | 可靠事件核心 | PG dispatcher、notify/advance/projection live、生产闭包 hook 退出、Phase2 选择性解耦已合入 | done | non_blocker | [E0A–E2](../test-reports/2026-09-15-event-e0a-production-scope-contract-test-report.md) 等；[复盘](../ops/research/2026-09-15-track-e-retrospective.md)；[shared live](../test-reports/2026-09-15-event-notify-shared-live-test-report.md)；[phase2 closeout](../test-reports/2026-09-15-phase2-closeout-test-report.md) | **before**：与 FAV off 混成 partial → **after**：FAV 独立行。选择性后续解耦按收益触发 | `architecture-docs` / `events` | | Final Artifact Vault（FAV） | 不可变终态制品库；`FAV_DEGRADED_READ=false` | partial | deferred_enhancement | [Track E 复盘](../ops/research/2026-09-15-track-e-retrospective.md)；[U7 报告](../test-reports/2026-09-16-fav-u7-incremental-test-report.md)；[W6 shadow](../test-reports/2026-09-17-w6-fav-subscriber-shadow-test-report.md)；[short-term](../ops/short-term/2026-09-17-w6-fav-subscriber-shadow.md) | **after W6**：subscriber `ObserveShadow` 只计算 intended outcome，不写副作用。仍**禁止**整支 merge；`FAV_DEGRADED_READ` 默认 false；**live 未放量**（staging→artifact→publication 各 ≥7 天观察窗） | `events` | +| 个人工程中控台 | 独立本地只读 CLI/`serve`/`export`；四轴状态；`.doc`/Git/Docker/`/ready` 聚合；不接产品后台 | done | deferred_enhancement（工具，非产品门禁） | [设计](../system-design/project-control-center/01-personal-engineering-control-center-plan.md)；[报告](../test-reports/2026-09-17-engineering-dashboard-test-report.md) | 一期已交付。跨快照历史、远端 CI、富渲染另立后续 | `engineering-dashboard` | --- diff --git a/.doc/test-reports/2026-09-17-engineering-dashboard-test-report.md b/.doc/test-reports/2026-09-17-engineering-dashboard-test-report.md new file mode 100644 index 00000000..7f787ec5 --- /dev/null +++ b/.doc/test-reports/2026-09-17-engineering-dashboard-test-report.md @@ -0,0 +1,109 @@ +# 个人工程中控台（engineering-dashboard）测试报告 + +## 一、 测试背景 (Background) + +仓库需要独立于产品后台的本地只读工程中控台，避免把文档 `done` 误读为已合并或已部署。方案见 [设计](../system-design/project-control-center/01-personal-engineering-control-center-plan.md)。本报告验收一期 `serve` / `export` 实现。 + +## 二、 测试目标 (Test Objectives) + +- 实时 HTML、离线 HTML、JSON 共用 `generation_id` / `revision_id` +- 计划 / Git 实施 / 验证 / 实装四轴独立 +- rdev、dev ahead、main events 分叉样本（单元夹具）按方案输出 +- 单源失败可 degraded；loopback / token / Host / 只读方法防护生效 +- 导出 HTML `0600`、可离线阅读 Markdown、不嵌 assets + +## 三、 测试方案与环境 (Test Plan & Environment) + +- OS: Linux；Go module `chat-agent-system` +- 工作树：`.worktrees/feature-engineering-dashboard`（`feature/engineering-dashboard`） +- 层级：包单元/集成测试 + CLI 真实 `serve`/`export` 冒烟（只读观察，未启停共享 compose） + +## 四、 预期结果 (Expected Results) + +| 用例 | 预期 | +|------|------| +| 模型四轴 | doc done 不改 Git/部署 facets | +| rdev 夹具 | planned / unclaimed / 实装 unknown | +| dev ahead | ahead>0 且备注含未确认远端 | +| main fork | readiness ok + containers partial + conflict | +| HTTP | POST 405；无 token 401；坏 Host 403；非 loopback bind 拒绝 | +| export | 权限 0600；含 identity；无 script breakout | + +## 五、 实际测试结果与判定 (Actual Results & Evaluation) + +### 5.1 单元与包测试 + +- **测试输入**: `go test ./internal/engineeringdashboard/ ./cmd/engineering-dashboard/ -count=1` +- **实际输出**: +```text +ok chat-agent-system/internal/engineeringdashboard 0.009s +? chat-agent-system/cmd/engineering-dashboard [no test files] +``` +- **判定**: PASS +- **耗时**: ~0.01s（包测） + +### 5.2 go vet + +- **测试输入**: `go vet ./internal/engineeringdashboard/... ./cmd/engineering-dashboard/...` +- **实际输出**: （无输出） +- **判定**: PASS + +### 5.3 真实 export + +- **测试输入**: `go run ./cmd/engineering-dashboard export --repo --output /tmp/engdash-export.html` +- **实际输出**: 文件权限 `600`；体积可离线打开；含 CSP 与 snapshot identity +- **判定**: PASS（`stat -c '%a'` → `600`） + +### 5.4 真实 serve 冒烟 + +- **测试输入**: `engineering-dashboard serve --repo --addr 127.0.0.1:8799`，随后 curl +- **实际输出**: +```text +{"ok":true} +generation gen_1 +revision rev_3378ee42f645c4ab1af69cf691c00103 +tasks 50 +docs 452 +sources [('docs', 'ok', 'fresh'), ('git', 'ok', 'fresh'), ('runtime', 'ok', 'fresh')] +POST_reject HTTPError 405 +no_token=401 +bad_host=403 +``` +- **判定**: PASS（HTML/JSON 同源 identity；安全负例符合预期） +- **说明**: 工作树上尚未合入未跟踪的 rdev 文档树；rdev/dev-ahead/main-events **样本契约由包内 fixture 单测覆盖**（`TestModel_*` / `TestReconcile_*`）。 + +### 5.5 夹具验收样本（单元） + +| 样本 | 测试 | 判定 | +|------|------|------| +| rdev 已计划未实施 | `TestReconcile_RDevPlannedUnclaimed` / `TestModel_AcceptanceSamplesAxes` | PASS | +| local ahead origin | `TestReconcile_DevAheadSample` / `TestGit_AheadDoesNotClaimRemoteAvailable` | PASS | +| main ready vs events restarting | `TestReconcile_MainEventsForkConflict` / `TestRuntime_ReadyOKAndEventsRestarting` | PASS | +| Herdr vs 产品 PI Runner | `TestModel_ClaimedWithoutRuntimeKeepsActivityUnknown` | PASS | + +## 六、 自动化测试套件汇总 (Test Suite Execution) + +对本工具包： + +```text +go test ./internal/engineeringdashboard/ ./cmd/engineering-dashboard/ -count=1 +# ok engineeringdashboard +go test -short ./internal/engineeringdashboard/... ./cmd/engineering-dashboard/... -count=1 +# ok +go vet ./internal/engineeringdashboard/... ./cmd/engineering-dashboard/... +# clean +git diff --check +# clean +``` + +全仓 `go test -short ./...` 在合入 `dev` 占槽时于主仓执行（本工具未改产品包）。 + +## 七、 测试结论与后续优化建议 (Conclusion & Next Steps) + +- **结论**: 一期达到合并标准（独立 CLI、同源快照、四轴、安全边界、导出）。 +- **后续**: 跨快照历史、远端 CI/Gitea、受限 Markdown/Mermaid、Agent 查询 API（设计附录已列，不在本期）。 + +## 相关链接 + +- 任务: [../archive/ops/short-term/2026-09-17-engineering-dashboard.md](../archive/ops/short-term/2026-09-17-engineering-dashboard.md) +- 设计: [../system-design/project-control-center/01-personal-engineering-control-center-plan.md](../system-design/project-control-center/01-personal-engineering-control-center-plan.md) diff --git a/scripts/engineering-dashboard.sh b/scripts/engineering-dashboard.sh new file mode 100755 index 00000000..258be752 --- /dev/null +++ b/scripts/engineering-dashboard.sh @@ -0,0 +1,7 @@ +#!/usr/bin/env bash +# Thin launcher for the local read-only engineering dashboard. +# No install, deploy, git, or docker side effects. +set -euo pipefail +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "$ROOT" +exec go run ./cmd/engineering-dashboard "$@"