release(main): 清理本地配置并重组文档结构

2026-03-30 19:03:17 +08:00
parent 244c424126
commit aa6cdd40e9
23 changed files with 215 additions and 541 deletions
@@ -0,0 +1,116 @@
+# Docs Reorganization Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Reorganize `docs/` into stable long-lived sections, remove obsolete files, normalize document headers, and repair repository references.
+
+**Architecture:** Keep `docs/plans/` as historical implementation records, move active operating material into `docs/guides/`, move review and governance material into `docs/audits/`, keep `docs/postman/` for collection assets, and add `docs/README.md` as the top-level navigation entrypoint.
+
+**Tech Stack:** Markdown, shell file operations, ripgrep
+
+---
+
+### Task 1: Create the target docs structure
+
+**Files:**
+- Create: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/README.md`
+- Create: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/guides/`
+- Create: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/audits/`
+
+**Step 1: Write the failing test**
+
+Manual expectation: `docs/README.md`, `docs/guides/`, and `docs/audits/` do not yet exist.
+
+**Step 2: Run test to verify it fails**
+
+Run: `find docs -maxdepth 1 -type d -o -type f | sort`
+Expected: FAIL to show the new structure.
+
+**Step 3: Write minimal implementation**
+
+Create the new directories and the docs index file.
+
+**Step 4: Run test to verify it passes**
+
+Run: `find docs -maxdepth 2 | sort`
+Expected: PASS with `docs/README.md`, `docs/guides`, and `docs/audits`.
+
+### Task 2: Move active docs into semantic directories
+
+**Files:**
+- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/guides/release-checklist.md`
+- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/guides/setup-config-api.md`
+- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/audits/auth-session-acceptance.md`
+- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/audits/setup-config-code-audit.md`
+- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/audits/storage-persistence-audit.md`
+- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/audits/storage-persistence-governance.md`
+- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/audits/enterprise-ui-acceptance-checklist.md`
+
+**Step 1: Write the failing test**
+
+Manual expectation: the documents still live in mixed root paths.
+
+**Step 2: Run test to verify it fails**
+
+Run: `find docs -maxdepth 2 -type f | sort`
+Expected: FAIL to show the desired grouping.
+
+**Step 3: Write minimal implementation**
+
+Move each document into `guides/` or `audits/`.
+
+**Step 4: Run test to verify it passes**
+
+Run: `find docs -maxdepth 2 -type f | sort`
+Expected: PASS with the regrouped files.
+
+### Task 3: Remove obsolete docs and local artifacts
+
+**Files:**
+- Delete: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/workbench-ui-optimization.md`
+- Delete: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/plans/2026-03-05-rd-monitor-design.md`
+- Delete: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/plans/2026-03-05-rd-monitor-implementation.md`
+
+**Step 1: Write the failing test**
+
+Manual expectation: the obsolete files still appear in `git status`.
+
+**Step 2: Run test to verify it fails**
+
+Run: `git status --short docs`
+Expected: FAIL because the obsolete docs are still present in tracked history.
+
+**Step 3: Write minimal implementation**
+
+Remove the obsolete files from the working tree and index.
+
+**Step 4: Run test to verify it passes**
+
+Run: `find docs -maxdepth 2 -type f | sort`
+Expected: PASS without the removed files.
+
+### Task 4: Normalize titles, metadata, and references
+
+**Files:**
+- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/README.md`
+- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/README.md`
+- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/.gitignore`
+- Modify: moved docs under `docs/guides/` and `docs/audits/`
+
+**Step 1: Write the failing test**
+
+Manual expectation: old paths are still referenced and several docs use inconsistent headings.
+
+**Step 2: Run test to verify it fails**
+
+Run: `rg -n "docs/(release-checklist|setup-config-api|storage-persistence|auth-session-acceptance|ui/enterprise-ui-acceptance-checklist)" README.md docs backend frontend .github`
+Expected: FAIL with old path references.
+
+**Step 3: Write minimal implementation**
+
+Update headings, add concise metadata blocks where useful, write `docs/README.md`, and fix references to the new paths.
+
+**Step 4: Run test to verify it passes**
+
+Run: `rg -n "docs/(release-checklist|setup-config-api|storage-persistence|auth-session-acceptance|ui/enterprise-ui-acceptance-checklist)" README.md docs backend frontend .github`
+Expected: PASS with only the new organized paths.