danyang-match/docs/文档治理报告-2026-09-18.md

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

范围：善缘丹阳公益婚恋服务平台全仓文档（约 200 份）。 触发：用户「很多久的项目文档已经废弃，请按照最新的文档要求审查下」。 性质：先只读审查（2026-09-18 首轮），再按审查结论逐项处置（同日续做）。 结论：治理方案的五个任务至此全部落地；过程中处置 9 项缺口、1 起环境级事故、2 份漏网文档， 并在验证阶段抓出 2 处新缺口（bundle 虚报、写死 hash），随后于收尾轮关闭全部 3 项遗留 （漏网报告废止、STATUS 精简、UI 门禁入 CI）。

---

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

治理要求不在 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 自保未覆盖当日提交	⚠️→✅ 先虚后实：初稿声称已建 bundle，磁盘上并不存在；复查发现当时唯一的 restore-checkpoint-…bundle 其 main 停在 f96dcb8（早于 21:15 三个治理提交）→ 已补建 .workbuddy/backup/docs-governance-2026-09-18.bundle（23.3MB，list-heads → main = 4e18272，complete history）	.workbuddy/backup/
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

⚠️ 补记（21:21 收尾复查）：D7 是本轮唯一一处「先报完成、后被证伪」的项 —— 初稿写下 「bundle 覆盖至最新提交」时磁盘上并不存在该文件，且当时唯一的 restore-checkpoint 停在治理提交 之前，等于 3 个治理提交当时毫无 bundle 保护。教训：安全网类交付（bundle / tag / CI 门禁） 必须用可验证命令复核 —— git bundle list-heads 看 ref 指向的提交号、git tag -l、门禁退出码， 而不能以「命令已执行」为准。 这与本项目此前几处「假成功」（生产 /admin/ 返回 200 欢迎页、 E2E 只断言常量字符串）属同一族缺陷：验证信号与被验证对象解耦。

---

四、四张清单

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 自保产物。

一份漏网文档：已处置（2026-09-18 收尾轮） —— docs/Phase-V11-Deployment-Completion-Report.md （2026-09-09，含已被推翻的「16/16 E2E 通过」与「Feature Flags 15 项 PASS」）。它不在方案删除目标 模式内（Phase-V11- 无数字段），且被 docs/Phase-01-V11-Recovery-Completion-Report-2026-09-09.md 援引 —— 删除会制造新的悬空引用。处置：原地重写为废止声明（保留路径，含「是什么 / 为何失效 / 取代者 / 为何保留」四要素），并把 Phase-01 报告与 Phase-13A 废止声明里的引用一并标注为「已废止」。

---

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

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	✅ 已关闭（收尾轮）：目标文件原地重写为废止声明、路径保留；Phase-01 与 Phase-13A 中的引用均标注为「已废止」

⚠️ 本次教训：给目录扫描加 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 处；② 收尾轮整体收敛：951 → 783 行（净减 168） —— 折叠 2026-09-09 期 Phase 0111 任务表、两块已作废的 Phase 22 历史声明、已作废的 Phase 23 声明、重复的 Phase 2426 摘要；并修正两处残留假声明（P26-T06 初始化Feature Flags ✅ (application.yml配置)、Phase 23（V1.1专项测试）— 已完成 ✅）
UI 门禁入 CI（收尾轮）	新增 scripts/run-ui-contracts.mjs 统一执行器 + ci.yml job ui-contracts；ci.yml 经 yaml.safe_load 校验，jobs = backend / admin-web / miniapp / migration / test-shell-guard / ui-contracts / e2e
执行器自身可验证（负向注入）	基线 node scripts/run-ui-contracts.mjs → PASS 14/14、退出 0；注入一个必然失败的守卫 → FAIL、退出 1 且打印原始输出；守卫数量下限分支以 UI_GUARDS_MIN=99 自检 → 正确拒绝报绿
漏网文档处置	Phase-V11-Deployment-Completion-Report.md 原地重写为废止声明（102 → 22 行，未删除）；Phase-01（引用行）与 Phase-13A（废止声明）里的引用同步标注「已废止」
门禁口径	AGENTS.md / STATUS.md 已为 14/14，历史行保留 13/13 并注明时点
bundle 覆盖（可复核）	.workbuddy/backup/docs-governance-2026-09-18.bundle；git bundle verify → records a complete history；list-heads 含 refs/heads/main 与 docs-governance-2026-09-18-1~N 全部治理 tag。⚠️ ref 指向随每次提交变化，引用时不要写死 hash，一律用 list-heads 与 git rev-parse HEAD 现场比对

---

八、遗留与下一步

本节原有 3 项遗留，已在收尾轮（2026-09-18 21:30 起）全部关闭：

原遗留	处置
Phase-V11-Deployment-Completion-Report.md 待决（4.4）	✅ 原地重写为废止声明（未删除）+ 修订 Phase-01 / Phase-13A 中的引用
STATUS.md 后半历史区过长	✅ 收敛 951 → 783 行（净减 168）；折叠 2026-09-09 期任务表与已作废/重复块；修正两处残留假声明
UI 门禁未进 CI（原稿误记为「15 个契约」）	✅ 新增 scripts/run-ui-contracts.mjs + ci.yml job ui-contracts；实测守卫为 14 个，经负向注入与数量下限分支自检

仍需处理（不属文档治理范围，需决策/另开一轮）：

1. Phase 24（UAT）启动需用户确认 —— 后端 669 全绿、UI 门禁 14/14、E2E 已在本机真实执行（49 passed）； 「活栈供给方式」决策已于 2026-09-18 落地为 Compose in CI（见收尾计划 Task 2.3），仅余「在 GitHub Actions 上跑一次绿」需在有 Docker Hub 出口的环境完成。
2. Phase-V11-Deployment-Completion-Report.md 路径仍在（内容已是废止声明） —— 若后续确要真正移除， 须连同 Phase-01 / Phase-13A 两处引用一并处理，并遵守本机删除红线（优先原地重写）。

执行纪律：删除类改动仍应分 3 个 commit（①删除 ②归档+头注 ③状态同步+计划+报告）+ 每 commit 后 git tag（单段名，分支名含 / 会被实时清理）+ git bundle create .workbuddy/backup/<phase>-recovery-<date>.bundle --all，并且必须用 git bundle list-heads <file> | grep refs/heads/main 确认指向的是最新提交（否则等于没有安全网，见 D7 补记）。

---

九、遗留清偿第二轮（2026-09-18 夜）—— 活栈供给决策 + features 失实二次修正

9.1 活栈供给方式：已决策（Compose in CI）

决策：CI 的 E2E 活栈在 runner 内用 docker compose 起全栈（postgres + redis + minio + backend）。 备选（未采纳）：service containers + runner 上 mvn package 后 java -jar —— 需为后端另写一套 host 网络配置，等于制造第二条与本地不一致的路径，且增加一份与生产无关的分歧。

本机实测（与 CI 同一序列），2026-09-18：

环节	结果
中间件 healthcheck	postgres / redis / minio 全 Healthy（pg_isready / redis-cli -a … ping / mc ready local）
backend 就绪	GET /api/v1/health/live → 200
seed	幂等可执行（INSERT 0 0；pgcrypto 已存在跳过）
E2E	pytest tests/e2e → 49 passed in 9.31s

本机限制（如实记录）：Docker Hub 不可达（auth.docker.io Bad Gateway）且本地无 temurin 基础镜像 → 未复现 --build；改用本地既有 danyang-match-backend:latest（2026-09-09 构建）为底座，挂载当日 16:24 构建的 jar，使被验证的代码版本与 CI 一致。若不换 jar，就是拿 09-09 的旧代码验 09-18 的用例， 结论无效（该镜像 Created 为 2026-09-09T04:02Z，已实测确认）。

顺带修掉的 6 个 CI 真实缺陷：① minio 滚动 tag（pin RELEASE.2025-09-07T16-13-09Z）；② up 未显式列出 minio（而其 healthcheck 是 backend 启动前置）；③ up --build 耦合构建与起栈、失败日志混杂；④ 就绪窗口 5min 偏紧（首次构建后仍需 Spring 启动 + Flyway 46 迁移）；⑤ 缺 down -v 前置清卷 —— seed 用 ON CONFLICT (username) DO NOTHING，残留卷会让口令停留在上一轮 → 401 且伪装成业务失败（本机复用旧库时 已实际踩到，须手工 UPDATE 密码才能跑）；⑥ job 无 timeout（默认 360 分钟）→ 加 timeout-minutes: 30。

被实测否定的一个假设：pytest -v 会从仓库根误收集 tests/*_test.py（其在 import 期依赖 psycopg2 与 E2E_DB_PASSWORD，会成 collection error）—— 不成立：pytest.ini 的 testpaths = tests/e2e 已限定， 实测从根收集正是 49 个用例且无 error。仍显式写成 pytest tests/e2e -v 作为兜底。

9.2 features 断言失实：二次修正（5 处文档）

背景：本轮自查发现 Phase 22 复验报告 D-22-D 的判据「backend/src/main/resources/*.yml 无 features: 块」 是错的，而上一个收尾轮又把该错误结论照抄进了 STATUS.md（P26-T06 行）—— 属二次传播。

实测事实（可复核）：

文件	是否有 features: 块	依据
application.yml（基础）	❌ 无	grep -rn "^features:" backend/src/main/resources/ 只命中 dev / docker
application-dev.yml	✅ 有（21 键）	自 63cbbff 起；且 spring.profiles.active: dev → 它是默认激活的 profile
application-docker.yml	✅ 有	自 730dddd（Phase 23B）起；compose 设 SPRING_PROFILES_ACTIVE: docker

硬证据：application-dev.yml 的 chat-image-enabled: true 覆盖了 FeatureFlagConfig 的 Java 字段 默认 false —— 若真如原判据所称「仅 Java 字段默认值生效」，该值不可能为 true。

修正落点（5 处）：STATUS.md（P26-T06 行 + Phase 22 段 + 历史声明块）、Phase-22-…-Report.md（表格行 + D-22-D）、 JIRA_BACKLOG.md、Phase-V11-Deployment-Completion-Report.md。

仍然成立的部分：T01–T05 模块开关与 T07 私有桶确实全仓零业务调用点（实测 12 个 flag 的调用点计数全为 0） → 「死配置」结论正确；原文失实的只是来源（非 application.yml、非「仅 Java 默认值」）。

本轮新发现 D-22-E：AppController#getConfig（GET /app/config）返回一份硬编码 features map （imageChatEnabled 恒 true，键名与后端 chatImageEnabled 不一致）→ 与 FeatureFlagConfig 双源， 前端读到的开关可能与实际配置相反（如 appealEnabled 实际默认 false）。不静默改契约，如实登记遗留。

9.3 操作事故：同一文件并行 Edit 会丢失改动

现象：对同一文件在一条消息里发起多个 Edit，会随机丢失其中若干处（读-改-写竞争）。 本轮实测：STATUS.md 3 处丢 1 处、ci.yml 3 处丢 2 处、Phase-22-…-Report.md 2 处侥幸全中。 每处都回报「Successfully edited」—— 成功回执不可作为落盘证据。

纪律：① 同一文件的多处改动必须串行（一次一个 Edit，等结果返回）； ② 任何批量改动后必须回读确认每一处都在（本轮即靠回读发现 timeout-minutes 与 pytest tests/e2e -v 丢失）。

---

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