# 审计记录补追与嵌套目录清理

**发现日期**：2026-04-20
**发现上下文**：2026-04-20 历史批次预审过程中，放宽 `.gitignore` 白名单后暴露出 `docs/audit/changes/changes/` 嵌套目录

## 背景

开发机迁移（79d3c2e 提交）前后，`docs/audit/changes/` 下意外出现了一个同名嵌套子目录 `docs/audit/changes/changes/`，其中堆积了 127 份审计记录 md 文件。推测原因是迁移脚本或某次批量拷贝时，误把 `docs/audit/changes/` 整个目录作为源，再次写入到了它自身下面，形成了 `changes/changes/` 的路径嵌套。

同时期 `.gitignore` 将 `docs/audit/` 整目录屏蔽（仅白名单少量文件），导致此后新增的审计记录长期无法入仓。主目录 `docs/audit/changes/` 当前仅有 33 份入仓 md，而嵌套目录累积了 127 份。

用户最初的设想是直接 `rm -rf docs/audit/changes/changes/` 了事。但实地核查发现：嵌套目录里相当一部分文件从未进入过 git 任何分支的 history（即未 commit 的孤本），一旦删除就永久丢失。因此需要先对 127 份做全量分类，再按类别分阶段处理，不能一删了之。

本 PRD 即用于指导后续清理动作，独立可执行。

## 扫描结果统计

| 分类 | 数量 | 含义 | 处理方式 |
|------|------|------|---------|
| A 纯副本 | 30 | 主目录同名同内容（diff 无输出） | 可直接删除嵌套版本 |
| B 内容漂移 | 1 | 主目录同名但内容不同 | 人工比对选最新 |
| C 已 commit 的孤本 | 0 | 主目录无，git history 有 | 无此类 |
| D 未 commit 的孤本 | 96 | 主目录无，git history 也无 | **最高优先级补追**，删除即永久丢失 |
| **合计** | 127 | | |

扫描方法：对 `docs/audit/changes/changes/*.md` 每个文件，先查 `docs/audit/changes/<同名>.md` 是否存在，存在则用 `diff -q` 比对内容；不存在则用 `git log --all --oneline -- docs/audit/changes/<文件名>` 查历史。扫描时主目录文件数 33，嵌套目录文件数 127。

## 类别 D：未 commit 的孤本清单（最高风险，共 96 份）

以下 96 份文件仅存在于 `docs/audit/changes/changes/`，且 git 所有分支 history 中均无记录。删除即永久丢失。

```
2026-02-26__etl-bugfix-dim-staff-rankname-assistant-daily-table-area.md
2026-02-26__p1-p2-p3-fullstack-integration.md
2026-02-26__retention-clue-refactor.md
2026-02-26__root-file-gitignore-h5ui-cleanup.md
2026-02-27__biz-day-cutoff-prd-sync-check.md
2026-02-27__p4-core-business-routes-triggers.md
2026-02-28__multi-module-accumulated-changes.md
2026-03-01__dwd-cleanup-ods-fix-dim-staff-repair.md
2026-03-01__dws-numeric-precision-ods-siteid-fix.md
2026-03-02__etl-unified-analysis-hook-merge.md
2026-03-02__spi-calibration-nonzero-median.md
2026-03-03__miniprogram-dev-debug-panel.md
2026-03-04__fullstack-accumulated-changes.md
2026-03-06__fix-api-client-post-method.md
2026-03-06__fix-db-operations-dsn-proxy.md
2026-03-07__task3-project-tag-docs-sync.md
2026-03-08__p5-ai-spec-review-category-enum-align.md
2026-03-10__multi-module-ai-apps-task-defense-miniprogram.md
2026-03-12__board-finance-overview-wxss-calibration.md
2026-03-12__miniprogram-dev-docs-finalize.md
2026-03-12__multi-module-ai-taskdefense-miniprogram-etl.md
2026-03-12__pixel-audit-structured-methodology.md
2026-03-13__board-finance-line-height-audit.md
2026-03-13__board-finance-rpx-formula-correction.md
2026-03-13__task-list-h5-rewrite.md
2026-03-15__ddl-baseline-consolidation-bd-manual-reorg.md
2026-03-18__rns1-e2e-fdw-direct-connect-bugfix.md
2026-03-19__card-type-id-doc-sync.md
2026-03-19__coach-tier-hardcode-fix.md
2026-03-19__level-map-hardcode-fix.md
2026-03-19__rns12-db-audit.md
2026-03-20__ai-prompt-refinement-board-coach-mock.md
2026-03-20__h2-fdw-to-direct-etl-unification.md
2026-03-20__miniprogram-docs-sync.md
2026-03-20__r3-skill-type-filter-rebuild.md
2026-03-20__rns1-ai-autonomous-decision-risk-audit.md
2026-03-20__rns13-board-apis-e2e-fix.md
2026-03-20__rns14-chat-fdw-filter-audit.md
2026-03-20__rns14-chat-module-r3-filter-rebuild.md
2026-03-22__db-field-walkthrough-batch-fix.md
2026-03-22__ddl-db-structure-diff-bd-manual-audit.md
2026-03-22__ddl_bd_manual_consistency_fix.md
2026-03-22__dev-trace-log-fullstack-feature.md
2026-03-22__ns4-ddl-merge-deleted-at.md
2026-03-22__p14-task15-final-checkpoint.md
2026-03-22__p16-spec-closing-doc-sync.md
2026-03-22__trace-path-fix-miniprogram-login-race.md
2026-03-22__zombie-task-graceful-shutdown-rerun.md
2026-03-23__ddl-merge-rejection-count-cancelled.md
2026-03-23__disable-to-remove-user-auth-model-fix.md
2026-03-23__mysites-tenant-filter-time-format-nickname-display.md
2026-03-23__review-modal-phone-display-auto-match-identity-label.md
2026-03-23__role-routing-page-guard.md
2026-03-23__tenant-admin-case-insensitive-username.md
2026-03-23__tenant-admin-review-modal-dynamic-roles.md
2026-03-23__tenant-admin-site-access-root-fix.md
2026-03-23__tenant-user-approval-site-filter.md
2026-03-23__trigger-jobs-admin-web-miniprogram-cleanup.md
2026-03-24__add_missing_cfg_skill_type.md
2026-03-24__ddl-migration-merge-and-archive.md
2026-03-24__fix-tier-nodes-empty-progress-bar.md
2026-03-24__lookback_days_60_to_90.md
2026-03-24__miniprogram-avatar-nickname-feature.md
2026-03-24__p17-assistant-ownership-task-engine.md
2026-03-24__p18-task-engine-dashboard.md
2026-03-24__perf-page-data-fix.md
2026-03-24__review-modal-avatar-layout.md
2026-03-24__soft-delete-user-site-roles-binding.md
2026-03-24__trigger-jobs-clear-task-interaction.md
2026-03-24_fix_cfg_skill_type_missing_records.md
2026-03-25__baseline-relationship-building-tasks.md
2026-03-25__baseline-task-independent-connection-fix.md
2026-03-25__perf-to-task-detail-member-query.md
2026-03-25__perf-wxml-missing-member-id.md
2026-03-25__task-detail-service-records-6-improvements.md
2026-03-25__tenant-users-soft-delete-upsert-fix.md
2026-03-26__etl-missing-fields-phase1-ddl-mappings.md
2026-03-26__net-income-calibration-all-pages.md
2026-03-27__board-finance-double-format-fix.md
2026-03-27__board-finance-integration-T2.md
2026-03-27__board-finance-phase2-t1-t6.md
2026-03-27__board-finance-wxml-format-tabs-cleanup.md
2026-03-27__miniprogram-permission-unification.md
2026-03-27__task-list-recent60d-and-wxml-formatting.md
2026-03-28__board-finance-5fixes.md
2026-03-28__board-finance-dws-area-refactor-audit.md
2026-03-28__fix-miniprogram-login-landing-page.md
2026-03-29__board-lazy-loading-pagination.md
2026-03-29__coach-detail-500-field-name-fix.md
2026-03-29__coach-detail-design-alignment.md
2026-03-29__coach-detail-style-aggregation-fix.md
2026-03-29__dws-task-engine-etl-orchestration.md
2026-03-29__fix-recall-completion-event-chain.md
2026-03-31__task-engine-overhaul.md
2026-04-05__kiro-to-claude-code-migration.md
2026-04-08__fix13-recall-events-refactor.md
```

注意其中一份为 `2026-03-24_fix_cfg_skill_type_missing_records.md`（单下划线），与同日的 `2026-03-24__add_missing_cfg_skill_type.md` 命名风格不同，疑似历史遗留命名，补追时保持原名即可。

## 类别 B：内容漂移清单（需人工比对，共 1 份）

```
2026-04-06__v1-cleanup-ddl-consolidation.md
```

处理提示：主目录版本与嵌套版本在 2026-04-06 的 v1 整理 commit（779b2f6）前后可能经历过修订，需逐行对比选最新信息最完整的一版。

## 类别 C：已 commit 的孤本清单（可恢复，共 0 份）

本次扫描未发现此类文件。主目录缺失的 94 份全部属于 D 类未 commit 孤本。

## 类别 A：纯副本清单（可直接删除，共 30 份）

以下 30 份文件在主目录有同名同内容版本，嵌套副本可安全删除。

```
2026-02-13__api-ods-comparison-v2.md
2026-02-13__api-ods-comparison.md
2026-02-13__api-reference-batch2.md
2026-02-13__api-reference-overhaul.md
2026-02-13__bd-manual-docs-consolidation-ddl-sync.md
2026-02-13__field-drift-report-update.md
2026-02-13__git-repo-reinit-push.md
2026-02-13__remove-legacy-index-cleanup.md
2026-02-14__api-doc-reorg-field-grouping.md
2026-02-14__api-ods-comparison-v3-fixed.md
2026-02-14__api-ods-comparison-v3.md
2026-02-14__api-param-audit-ods-design.md
2026-02-14__drop-dwd-settle-list.md
2026-02-14__drop-ods-settlelist.md
2026-02-14__dws-bugfix-tier-safedecimal.md
2026-02-14__json-refresh-md-patch.md
2026-02-14__json-vs-md-audit.md
2026-02-14__legacy-ods-dwd-cleanup.md
2026-02-14__md-placeholder-fix-cleanup.md
2026-02-14__ods-cleanup-doc-update.md
2026-02-14__ods-vs-summary-comparison.md
2026-02-14__recording-client-timezone-fix.md
2026-02-14__replace-role-area-new-api-doc.md
2026-02-14__skip-words-remark-fix.md
2026-02-15__admin-web-console-db-migration-audit-reorg.md
2026-02-15__audit-consolidation-doc-reorg.md
2026-02-15__backend-deps-bootstrap.md
2026-02-15__docs-database-merge.md
2026-02-15__docs-devnotes-index-cleanup.md
2026-02-15__monorepo-migration-phase1-8.md
```

## 建议的执行顺序

1. **阶段 1：先保全 D 类（96 份）**
   - 在动任何东西前，先 `git add -A && git commit -m "WIP 清理前快照"` 做一次保护 commit
   - 将 `docs/audit/changes/changes/` 下所有 D 类文件复制（不是移动）到 `docs/audit/changes/`
   - 检查 `.gitignore` 是否放行 `docs/audit/changes/*.md`，若未放行则先调整白名单
   - `git add docs/audit/changes/ && git commit -m "补追未入仓的 96 份审计孤本"`

2. **阶段 2：处理 B 类（1 份）**
   - 针对 `2026-04-06__v1-cleanup-ddl-consolidation.md`，用 `diff docs/audit/changes/<该文件> docs/audit/changes/changes/<该文件>` 查看差异
   - 选更完整的一版保留到主目录；将另一版备份到 `_DEL/audit-backup/2026-04-06__v1-cleanup-ddl-consolidation.嵌套版.md` 或类似路径
   - commit 消息"内容漂移修正：v1-cleanup-ddl-consolidation"

3. **阶段 3：恢复 C 类（0 份，跳过）**
   - 本次无 C 类，无需操作

4. **阶段 4：删除嵌套目录**
   - 确认阶段 1、2 已 commit 入仓
   - `rm -rf docs/audit/changes/changes/`
   - `git add -A && git commit -m "清理嵌套目录 docs/audit/changes/changes/"`

## 风险与回滚

- 风险 1：D 类补追后，主目录审计时间线会出现大段 2026-02-26 至 2026-04-08 的批量入仓，commit 时间与文件日期不一致。可接受，目标是保全历史。
- 风险 2：B 类仅 1 份，若选错版本会丢失另一方内容。缓解：另一版强制先备份到 `_DEL/` 再删。
- 风险 3：`.gitignore` 可能仍然屏蔽 `docs/audit/changes/*.md`，导致 `git add` 静默忽略。阶段 1 第一次 `git add` 后必须 `git status` 核对文件是否真的进入了暂存区；若未进入，先修 `.gitignore` 白名单再重试。
- 风险 4：D 类中 `2026-03-24_fix_cfg_skill_type_missing_records.md` 为单下划线命名，可能与同日双下划线版本功能重叠，补追后若发现重复再单独合并。
- 回滚：所有删除前应已有"WIP 清理前快照"commit；任何阶段出问题 `git reset --hard <快照 hash>` 即可恢复。

## 验证

阶段 4 完成后执行以下验证：

- `ls docs/audit/changes/*.md | wc -l` 应等于 33（原）+ 96（D 补追）+ 0（C 恢复）= 129
- 若 B 类合并后主目录文件未增加，则仍为 129；若 B 类创建了新文件名则为 130
- `ls docs/audit/changes/changes/ 2>/dev/null` 应返回空或"目录不存在"
- `git log --oneline -- "docs/audit/changes/"` 应能看到至少 3 次本次操作 commit（快照 / 补追 / 清理）
- 抽查 D 类中的 3 份文件，确认 `git log --all -- "docs/audit/changes/<文件名>"` 返回非空

## 不在本次任务范围

- 审计内容本身的正确性复核（只做文件层面的保全，不审查内容）
- `.gitignore` 结构的长期设计（仅在本次清理中按需放行白名单）
- 其他模块的遗漏审计补追
- 审计看板 `docs/audit/audit_dashboard.md` 的刷新（阶段 4 完成后单独跑 `scripts/audit/gen_audit_dashboard.py`）