88 lines
4.8 KiB
Markdown
88 lines
4.8 KiB
Markdown
|
# 第 7 轮工作计划（轻量合并版）：文档技术选型漂移门禁
|
|||
|
|
|
|||
|
|
更新日期：2026-08-01
|
|||
|
|
|
|||
|
|
## 1. 本轮目标
|
|||
|
|
|
|||
|
|
修正 `docs/architecture/overview.md` 与 `docs/product/positioning.md` 中「桌面 = Tauri（后期/规划）」的过时描述（当前实现为 Electron 43.2.0），并新增黄金门禁测试：文档中桌面技术选型描述必须与代码事实（`apps/desktop/package.json` 为 Electron）一致或明确标注「待决策」，漂移直接失败；矩阵 117 行「跨层契约和文档同轮同步」的文档漂移项收口。
|
|||
|
|
|
|||
|
|
## 2. 背景和当前状态
|
|||
|
|
|
|||
|
|
- 当前已完成：契约侧差异检查与 schema 清单门禁（第 2 轮）；桌面实现为 Electron（`apps/desktop/package.json` electron 43.2.0 / electron-builder 26.15.3，`docs/architecture/desktop.md` 已如实记录）。
|
|||
|
|
- 当前缺口：`overview.md` 第 64 行「桌面 | Tauri（后期）」、`positioning.md` 第 19 行「后续桌面壳（Tauri，规划）」与 Electron 现状矛盾，属矩阵 117 行点名的「Hybrid、Tauri/Electron 文档描述漂移」；无门禁测试防止复现。
|
|||
|
|
- 本轮为什么现在做：矩阵 117 行剩余验收「增加契约生成/差异检查和文档清单门禁，漂移直接阻断合并」；纯文档 + 测试，本地可验证。
|
|||
|
|
- Workspace preflight：第 6 轮收口（447 passed）；服务 8003/5173 正常；共享脏工作区、无提交。
|
|||
|
|
- 方向分析：Q1 推荐选项 C（契约/文档漂移门禁），目标续跑轮授权执行。
|
|||
|
|
|
|||
|
|
## 3. 本轮工作方向
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
overview.md「Tauri（后期）」/ positioning.md「Tauri（规划）」与 Electron 现状矛盾
|
|||
|
|
-> 修订为「Electron（当前实现）；Tauri 目标态待产品/架构决策」
|
|||
|
|
-> 新增黄金门禁：桌面技术选型描述必须含 Electron 或「待决策」标记，否则失败
|
|||
|
|
-> 矩阵 117 行漂移项收口；CHANGELOG
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 4. 已确认决策
|
|||
|
|
|
|||
|
|
任务重量：
|
|||
|
|
- 档位：轻型（2 个文档文件 + 1 个黄金测试）。
|
|||
|
|
- 规模依据：纯文档修订 + 门禁测试，无生产代码行为变化；风险 LOW。
|
|||
|
|
- 选择原因：矩阵 117 行明确点名的漂移项，最小可验证增量。
|
|||
|
|
|
|||
|
|
P0/P1 决策（按 Q1 推荐采纳）：
|
|||
|
|
- 决策 1（P0）：本轮切片 = 文档技术选型漂移门禁（选项 C 的文档部分）。
|
|||
|
|
- 决策 2（P1）：不新建分支、不提交、不推送。
|
|||
|
|
- 决策 3（P1）：验证深度 = 聚焦门禁测试 + 全量黄金回归。
|
|||
|
|
|
|||
|
|
默认假设：
|
|||
|
|
- 假设 1：桌面技术选型事实以 `apps/desktop/package.json`（Electron）为准；Tauri 是否作为最终目标态属产品/架构决策，本轮不替用户决定，只在文档中明确标注「待决策」。
|
|||
|
|
- 假设 2：门禁测试检查 `docs/architecture/overview.md`、`docs/product/positioning.md` 中出现桌面技术选型表述的行，必须包含 `Electron` 或 `待决策`/`待定`，且不得出现孤立「Tauri（后期/规划）」式绝对描述。
|
|||
|
|
- 假设 3：`plan.md` 蓝图中的 Tauri 目标态保留（蓝图允许超前于实现），本轮只修落地文档。
|
|||
|
|
|
|||
|
|
未决但不阻塞：Tauri vs Electron 终局决策（产品/架构）；契约生成自动化（schema → pydantic/TS）。
|
|||
|
|
|
|||
|
|
## 5. 范围
|
|||
|
|
|
|||
|
|
In scope:
|
|||
|
|
- `docs/architecture/overview.md`：技术选型表「桌面」行修订。
|
|||
|
|
- `docs/product/positioning.md`：「形态」行修订。
|
|||
|
|
- `tests/golden/test_doc_drift.py`（新）：文档技术选型门禁（含 Hybrid 描述一致性检查）。
|
|||
|
|
- `docs/product/plan-completion-matrix.md`：117 行注记（文档漂移项收口，契约生成自动化仍剩余）。
|
|||
|
|
- `docs/CHANGELOG.md`：追加条目。
|
|||
|
|
|
|||
|
|
Out of scope:
|
|||
|
|
- Tauri/Electron 终局决策、契约生成自动化、其他 Partial/Missing 项。
|
|||
|
|
- 提交/推送/合并/清理用户改动。
|
|||
|
|
|
|||
|
|
## 6. 成功标准
|
|||
|
|
|
|||
|
|
- 聚焦：`python -m pytest -q tests/golden/test_doc_drift.py -p no:cacheprovider` 通过。
|
|||
|
|
- 全量：`python -m pytest tests/golden -q -p no:cacheprovider`（固定 .venv）≥ 447。
|
|||
|
|
- ruff 干净；git diff --check 无空白错误；文档无乱码。
|
|||
|
|
|
|||
|
|
## 7. 验证方式
|
|||
|
|
|
|||
|
|
- 门禁测试对修订前后文档的断言；全量黄金回归。
|
|||
|
|
|
|||
|
|
## 8. 关键风险
|
|||
|
|
|
|||
|
|
| 风险 | 影响 | 控制方式 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| 门禁误伤未来文档 | 无关文档失败 | 只检查桌面技术选型相关行 + 允许「待决策」标记 |
|
|||
|
|
| 修订引入新的不一致 | 文档再次漂移 | 门禁测试锁定 Electron/待决策 二者必有其一 |
|
|||
|
|
|
|||
|
|
## 9. 停止条件
|
|||
|
|
|
|||
|
|
- 全量黄金测试非本轮相关回归无法快速定位时暂停。
|
|||
|
|
- 任何提交/推送/合并/清理操作停下等待授权。
|
|||
|
|
|
|||
|
|
## 10. 本轮完成定义
|
|||
|
|
|
|||
|
|
- 文档修订、门禁测试、矩阵/CHANGELOG 回写完成；聚焦与全量通过；不提交。
|
|||
|
|
- 收口：报告主要结论、关键洞察、需要特别留意的地方。
|
|||
|
|
|
|||
|
|
## 11. 下一步
|
|||
|
|
|
|||
|
|
轻量合并版：主 agent 实现 + 验证 + 收口报告。
|