admin/danyang-match
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
4e1827295d003be4d432420ac9b346421846bd3a
danyang-match/docs/文档治理报告-2026-09-18.md
T
WorkBuddy 4e1827295d docs: 新增 Phase 23 收尾与 UAT 就绪计划 + 2026-09-18 文档治理报告（方案任务四、五） 
- 新建 docs/superpowers/plans/2026-09-18-phase23-closeout-and-uat-readiness.md（superpowers 计划格式），
  五批：批 1 快速收尾（ui-tests 15 个契约接入 CI —— 目前**只在本地手工跑**，CI 无把关）/
  批 2 Phase 23 剩余（E2E 场景真实实现 + INV-011 显式守卫 + CI 串联 E2E【需基础设施决策】+
  Phase 22 Deployment/Ops 口径复验）/ 批 3 代码级遗留清偿 / 批 4 UAT 就绪【需用户协作】/
  批 5 Phase 25-26 前置登记。STATUS.md 与客户需求基线计划均已引用（方案明确要求）。

- 新建 docs/文档治理报告-2026-09-18.md：五任务执行核对；本轮 9 项缺口（D1~D9）逐项处置；
  删除/归档/头注/保留四张清单；悬空引用二分结论（naive 扫描 29 处，其中 **24 处是「已删除对象清单」
  里的合法治理证据**，真实悬空 5 处）；**docs/ 目录被 safe-delete 钩子整体移除的事故记录与恢复过程**；
  验证证据；4 项遗留。

验证：UI 契约门禁 **14/14 PASS**；ui-document-baseline-contracts 通过（锚点齐全）；
database 文档 59 表 / 46 迁移与迁移文件实测一致。
2026-09-18 21:15:39 +08:00

11 KiB
Raw Blame History

文档治理报告 — 2026-09-18

范围：善缘丹阳公益婚恋服务平台全仓文档（约 200 份）。 触发：用户「很多久的项目文档已经废弃，请按照最新的文档要求审查下」。 性质：先只读审查（2026-09-18 首轮），再按审查结论逐项处置（同日续做）。 结论：治理方案的五个任务至此全部落地；过程中发现并处置 9 项缺口、1 起环境级事故、2 份漏网文档。

一、「最新的文档要求」的出处（易踩空的前提）

治理要求不在 Git 里 —— 它是 .zcode/plans/plan-sess_455ccc48-2c82-47b0-b4c6-1f923e813e1b.md （《文档治理 + 进度审查 + 下一阶段计划》，2026-09-18 20:11）。

.zcode/ 被 .gitignore 排除，git log 完全看不到，只存在于文件系统上。 → 教训：听到「按最新要求」时，先 ls -t .zcode/plans/，否则会拿旧规范去审。

方案的五个任务：①删除失效文档 → ②归档 + 头注 → ③状态文件同步 → ④下一阶段计划 → ⑤治理报告。

二、五任务执行核对（截至本轮收尾）

# 要求 实际 判定
一 删失效文档 ~63 份 c77e6fc 删 65 份（tag docs-cleanup-* 可恢复） ✅
二 4 份归档 + 5 处头注 归档 ✅；头注补至 5 处（本轮补 部署架构…方案.md） ✅
三 同步 5 个状态文件 STATUS / JIRA / 基线计划 / PENDING_DECISIONS / REMAINING_WORK+database，本轮全部完成 ✅
四 新建 Phase23 收尾计划 本轮新建 docs/superpowers/plans/2026-09-18-phase23-closeout-and-uat-readiness.md（五批） ✅
五 新建治理报告 本文件 ✅

三、本轮处置的 9 项缺口

编号 缺口 处置 位置
D1 Phase23 收尾计划不存在 ✅ 新建五批计划；STATUS.md 与基线计划均已引用 docs/superpowers/plans/2026-09-18-…md
D2 治理报告从未落盘却被引用 ✅ 本文件（关闭 docs/archive/design-v1.0/README.md 的悬空引用） 本文件
D3 REMAINING_WORK.md 严重失实 ✅ 整体重写：称 CHANGELOG 3.3MB → 实际 4234 字节；P1-3 指向从未存在的报告；9 项已关闭 / 12 项待办如实重排 REMAINING_WORK.md
D4 database 两份与实况差距大 ✅ 重写：TABLE_INVENTORY 40 表 → 59 表（带来源迁移列）；MIGRATION_GUIDE V001V011 → **V001V046（46 个）** docs/database/*
D5 部署架构文档缺取代头注 ✅ 补 ⚠️ 已被取代（2026-09-18 头注） 根目录 部署架构…方案.md
D6 三个状态文件未同步 ✅ JIRA Epic 总览表补 P14/P15/P19~P23 ✅；基线计划 Phase 07 去 UI REOPENED、Phase 10~15/19 补 ✅、Phase 20/21 勾选、Phase 22 如实标「未复验」、Phase 23 标「部分关闭」；PENDING_DECISIONS 历史部署声明 10 项回写处置 + 补登第三方开放遗留 7 项 三份文档
D7 bundle 自保未覆盖当日提交 ✅ 本轮重跑 git bundle create 覆盖至最新提交 根目录 *.bundle
D8 Phase-13A-V11-Completion-Report.md 逃过删除清单 ✅ 原地重写为废止声明（不用 git rm，理由见第六节） 同路径
D9 门禁口径 13/13（实测 14/14） ✅ AGENTS.md 与 STATUS.md 当前口径改为 14/14；历史时点行保留 13/13 并注明「为该时点数值」 AGENTS.md / STATUS.md

四、四张清单

4.1 删除清单（c77e6fc，65 份，均经三判据核验）

组 份数 说明
docs/Phase-XX-Completion-Report.md 26 V1.0 自报式完成报告，已被各 Phase Recovery 版取代
docs/Phase-XX-V11-Completion-Report.md 21 V1.1 首轮报告，已被复验推翻
旧审查 / 发布报告 13 CODE_REVIEW_REPORT、FIX_PLAN、ISSUE_TRACKER、FINAL-RELEASE-REPORT、Go-NoGo-Checklist、渗透测试报告等
被取代旧计划 4 V1.1_RECOVERY_DEVELOPMENT_PLAN、当前进度校正与严格Phase修复计划、两份 2026-09-14 plan
备忘 1 IDEA.md

恢复方式：tag docs-cleanup-2026-09-18-1/-2 + git log --all -- <path>。

4.2 归档清单（16538d7）

4 份 V1.0 前端设计文档 → docs/archive/design-v1.0/，目录内 README 声明 「已被 2026-09-13 参考图规格整体取代，不得作为实现依据」： 前端UIUX视觉与原型设计规范 / 前端组件库与 Design Token 规范 / 高保真页面原型说明书 / 页面级功能清单与交互流程设计。

4.3 头注清单（5 处）

文件 头注
CHANGELOG.md 📌 指针 → docs/V1_1_CHANGELOG.md
REST API 接口详细设计规范.md ⚠️ 部分取代 → V1.1 增量设计 + docs/api/API_INVENTORY.md
WorkBuddy开发执行总指令…md ⚠️ 已被取代 → 主启动提示词（整合版）
WorkBuddy首轮启动提示词 + Phase 01~26 清单.md ⚠️ 已被取代 → 主启动提示词（整合版）
部署架构、运维监控、备份恢复与升级方案.md ⚠️ 已被取代 → docs/OPS.md + infrastructure/ + Phase 22（本轮补）

4.4 保留清单（零引用 ≠ 可删）

根目录 13 份 V1.0 设计文档被引用数为 0，但它们不是废弃： docs/善缘丹阳 V1.1 数据库与API增量设计.md 自述「增量扩展、兼容 V1.0」， 这 13 份是 V1.0 业务设计的唯一载体；方案已裁定「保留原位」，本轮复核确认无冲突。

其余保留：P0阻断项修复报告_2026-09-15、幂等键/HTTP 语义检修报告（09-18 最新结论）、 gate-output/*.txt（UI 验收证据）、tests/uat/UAT-Test-Cases.md、releases/ 全部、 24 份 *-Recovery-* 报告、.workbuddy/ 与 bundle 自保产物。

另登记一份「保留待决」：docs/Phase-V11-Deployment-Completion-Report.md（2026-09-09，含已被推翻的 「16/16 E2E 通过」）。它不在方案删除目标模式内（Phase-V11- 无数字段），且被保留文档 Phase-01-V11-Recovery-Completion-Report-2026-09-09.md 援引 —— 删除会制造悬空引用。 → 不擅自删除，登记待用户决定（删除需同步修改 Phase-01 的引用）。

五、悬空引用：必须二分，不能一股脑报缺陷

naive 扫描得 29 处，其中 24 处合法（出现在「已删除对象清单」语境：治理方案的 Delete 清单、 UI_CLEANUP_INVENTORY 候选表、UI spec 的 § 删除清单、历史报告叙述）——它们是治理证据，刻意保留。

真实悬空 5 处，本轮全部关闭：

位置 指向 处置
docs/archive/design-v1.0/README.md docs/文档治理报告-2026-09-18.md（从未入库） ✅ 本文件落盘（D2）
docs/superpowers/plans/2026-09-13-miniapp-11-core-pages-redesign.md docs/MINIAPP_REFERENCE_UI_QA_2026-09-13.md（从未入库） ✅ 随 65 份清理一并消除
docs/superpowers/plans/…dual-client-ui-redesign.md docs/UI_REFERENCE_REDESIGN_ACCEPTANCE_2026-09-13.md（从未入库） ✅ 同上
docs/STATUS.md（在途版本） plans/2026-09-18-phase23-closeout-and-uat-readiness.md ✅ 计划已建（D1）；STATUS 已引用
docs/Phase-01-V11-Recovery-…md Phase-V11-Deployment-Completion-Report.md ⚠️ 保留（删除会制造新悬空，见 4.4）

⚠️ 本次教训：给目录扫描加 SKIP 时把 archive 排除，导致归档目录自己的 README 没被扫到， 而它恰好含一处真实悬空。归档目录必须扫。

六、事故记录：docs/ 目录被整体移除（已完整恢复）

项 内容
时间 2026-09-18 21:05（SIGTERM 中断的 git rm 之后）
现象 整个 docs/ 目录从工作区消失；git status 显示 83 个文件全部为 D；.git/index.lock 残留（0 字节，无进程持有）
HEAD 完好（ref: refs/heads/main，历史完整）
根因 本机存在 safe-delete 钩子，会把「删文件」放大为「删父目录」。本仓库 Phase-23 报告第 152 行早已记载：「本仓库禁止用 rm / git rm 删除文件；需要移除内容时改用原地重写（Write/Edit）」
恢复 清理 stale 锁 → git checkout HEAD -- docs/ → 83 个索引文件全部恢复，git status 清零
损失 ① 未跟踪的 docs/文档治理报告-2026-09-18.md（本轮已重建）；② 一份未提交的 STATUS.md 在途改动（另一会话产出，已回退至 HEAD 版本，本轮已重做）
受影响文件 仅 docs/；admin-web / backend / miniapp / infrastructure 等均完好
安全网 恢复后立即 git bundle create .workbuddy/tmp/restore-checkpoint-…bundle main（23MB，bundle verify 通过）

纪律（写入技能）：本仓库一律不用 rm / git rm；移除内容用原地重写； git status 出现整目录 D 时应先查 HEAD 与 index.lock，不要先动工作区文件。

七、验证证据

项 结果
ui-tests/ui-document-baseline-contracts.mjs 通过（锚点齐全：UI REDESIGN ACCEPTED BY USER、管理后台: http://localhost:13520/、Phase 07…已通过用户验收）
UI 契约门禁全量 14/14 PASS（2026-09-18 实测，全部退出码 0）
数据库文档一致性 TABLE_INVENTORY 59 表 ⇄ 迁移实测 59；MIGRATION_GUIDE 46 个 ⇄ 实测 46
STATUS.md 重复区块 「V1.1 本地部署完成」3 处 → 1 处（996 行 → 946 行）
门禁口径 AGENTS.md / STATUS.md 已为 14/14，历史行保留 13/13 并注明时点

八、遗留与下一步

  1. Phase-V11-Deployment-Completion-Report.md 待决（4.4）—— 建议连同 Phase-01-Reports 的引用一并修订后移除。
  2. docs/STATUS.md 后半部历史区仍较长（V1.0 基线状态 与 当前 Phase 段含 2026-09-09 的开发日志）—— 已加「历史记录边界」声明，进一步精简需单独一轮。
  3. UI 门禁进 CI 未做 —— 15 个契约目前只在本地手工执行（无 CI 把关）。已登记为 plans/2026-09-18-phase23-closeout-and-uat-readiness.md 批 1 Task 1.1，是五项遗留里最该先做的一项。
  4. 执行纪律：删除类改动仍应分 3 个 commit（①删除 ②归档+头注 ③状态同步+计划+报告）+ 每 commit 后 git tag（单段名）+ git bundle create。

报告生成: 2026-09-18 — 对应方案任务五；处置明细见 docs/superpowers/plans/2026-09-18-phase23-closeout-and-uat-readiness.md

Reference in New Issue View Git Blame Copy Permalink