docs: 落地目录治理基线与校验钩子草案

.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: local
+    hooks:
+      - id: validate-markdown-files
+        name: Validate changed markdown files
+        entry: scripts/precommit-validate-markdown.sh
+        language: system
+        files: \.md$
+      - id: check-links-pre-push
+        name: Check markdown links (pre-push)
+        entry: make check-links
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
+      - id: validate-mermaid-pre-push
+        name: Validate mermaid syntax (pre-push)
+        entry: make validate-mermaid
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
+

00_Management/01_Project_Progress.md

@@ -111,6 +111,7 @@
 
 | 变更时间   | 变更类型                                          | 变更内容                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | 变更原因                                                                                                                       | 影响评估                                                                                                                                                                                                                                                                                                                                                                             |
 | ---------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 2026-03-11 | 目录治理工程化基线落地                            | 新增 `00_Management/06_Directory_Governance_Baseline.md`（目录治理基线清单）与 `00_Management/07_Migration_Mapping_Template.md`（迁移映射模板），明确主文档单一真源、Archive 边界、目录命名规则、迁移流程、门禁指标及角色责任；新增 `.pre-commit-config.yaml` 与 `scripts/precommit-validate-markdown.sh`，将 `make validate-file`、`make check-links`、`make validate-mermaid` 纳入提交前/推送前校验草案 | 用户要求提供“可执行的目录治理方案”，并确认需要直接落地模板与自动化校验入口                                                     | 正面影响，目录治理从“规则说明”升级为“可执行流程 + 模板 + 工具门禁”；可显著降低平行版本扩散、链接失效和图文不一致风险，提升后续文档维护效率与交付稳定性                                                                                                                                                                                                                              |
 | 2026-03-10 | 统一主详设整编                                    | 将 `02_Detailed/01_Detailed_Design.md` 重构为统一《福建水务营收系统详细设计说明书》，整合模块设计、CA电子签章、数据库、接口、安全、部署等分散文档内容；统一系统名称、章节体系、模块/接口编号及数据库口径为达梦数据库 8.0+，并清理部署章节残留脚本碎片                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | 用户要求以唯一主详设文件完成整编交付，避免多份详设并存、章节口径不一致及旧数据库表述残留                                       | 正面影响，主详设结构更完整统一，可直接交付实施，数据库与章节口径一致，后续维护与评审成本显著降低                                                                                                                                                                                                                                                                                     |
 | 2026-03-10 | Archive归档整理                                   | 重组 `04_Appendix/Archive/` 历史资料目录，按需求、操作手册、历史设计、原始附件、数据字典、整合资料分层归档；迁移 Markdown 与配套 `_images` 目录；同步修正 `00_Management/04_Writing_Guide.md` 中数据字典旧路径引用                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | 用户要求提升历史资料可检索性，明确 Archive 职责边界，并避免图片相对路径失效与旧引用残留                                        | 正面影响，历史资料结构更清晰，检索效率提升，引用路径与目录职责统一，降低后续维护成本                                                                                                                                                                                                                                                                                                 |
 | 2024-12-19 | 微网厅功能对齐                                    | 根据福建水投微网厅操作手册核对调整子系统4功能：删除WECHAT-005营业网点服务中的预约/排队叫号/预约提醒功能，在WECHAT-006业务办理服务中添加缺失的一户多人口申请功能，将更名过户申请分离为独立的更名业务和过户业务                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | 用户要求子系统4不要出现操作手册中没有的功能，并核对删除多余功能                                                                | 正面影响，确保微网厅系统功能与实际操作手册完全一致，避免设计与实施不符                                                                                                                                                                                                                                                                                                               |

00_Management/03_Task_Checklist.md

@@ -163,6 +163,17 @@
   - [x] 在 `README.md` 中补充 `Codex / AGENTS` 使用说明，便于仓库入口快速理解代理工作方式 ✅
   - [x] 更新项目管理文件记录本次代理适配工作 ✅
 
+## ✅ 最新完成任务 (目录治理工程化)
+
+### 📋 可执行目录治理方案落地
+
+- [x] **新增目录治理基线与迁移模板** ✅ (2026-03-11)
+  - [x] 新增 `00_Management/06_Directory_Governance_Baseline.md`，明确主文档单一真源、Archive 边界、命名规则、迁移流程、门禁指标 ✅
+  - [x] 新增 `00_Management/07_Migration_Mapping_Template.md`，提供批次化迁移映射、引用修复、校验记录、风险回退模板 ✅
+  - [x] 新增 `.pre-commit-config.yaml` 草案，将 `validate-file`、`check-links`、`validate-mermaid` 纳入提交前/推送前校验流程 ✅
+  - [x] 新增 `scripts/precommit-validate-markdown.sh`，支持按本次变更文件逐一执行 `make validate-file` ✅
+  - [x] 更新项目进度文件记录本次目录治理工程化动作 ✅
+
 ## ✅ 最新完成任务 (2024-12-19)
 
 ### 📋 新增引言文档

00_Management/06_Directory_Governance_Baseline.md

@@ -0,0 +1,87 @@
+# 福建水务营收系统目录治理基线清单
+
+## 1. 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 项目名称 | 福建水务营收系统 |
+| 文档类型 | 目录治理基线 |
+| 版本 | v1.0 |
+| 状态 | 生效 |
+| 生效日期 | 2026-03-11 |
+
+## 2. 适用范围
+
+- 本清单适用于仓库根目录及全部子目录的 Markdown 正式文档治理。
+- 本清单与 `00_Management/02_Delivery_Standards.md`、`00_Management/04_Writing_Guide.md` 联合生效。
+- 冲突处理优先级：用户当次要求 > 主文档统一口径 > 本清单 > Archive 历史资料。
+
+## 3. 主文档单一真源
+
+以下文件为正式交付主文档，新增正式内容必须优先并入对应主文档：
+
+- `01_High_Level/03_Summary_Design.md`
+- `02_Detailed/01_Detailed_Design.md`
+- `03_Technical/01_Database_Design.md`
+- `03_Technical/03_Interface_Design.md`
+- `03_Technical/04_Security_Design.md`
+- `03_Technical/05_Deployment_Design.md`
+
+治理规则：
+
+- 禁止新增“新-xxx”“最终版”“修订版”等平行正式稿。
+- 历史版本仅允许进入 `04_Appendix/Archive/`，并保留来源说明。
+- 如需拆分主文档章节，应先在主文档中定义章节入口与回链。
+
+## 4. 目录与命名规则
+
+### 4.1 目录职责
+
+- `00_Management/`：管理制度、进度、任务、治理规则。
+- `01_High_Level/`：概要设计（结构、边界、职责、关键接口）。
+- `02_Detailed/`：详细设计（流程、规则、约束、模块实现层面设计）。
+- `03_Technical/`：数据库、接口、安全、部署等专题设计。
+- `04_Appendix/Archive/`：历史资料归档，不作为正式主稿替代。
+
+### 4.2 文件命名
+
+- 正式文档：`NN_中文主题.md`。
+- 图片目录：`<同名文档>_images/`。
+- 禁止无语义命名（如 `temp.md`、`final_v3.md`）。
+
+### 4.3 编号与术语
+
+- 模块编号与接口编号必须区分，接口编号优先采用 `IF-` 前缀。
+- 项目名称统一为“福建水务营收系统”。
+- 数据库与技术口径以当前主文档为准，历史资料只作为核对来源。
+
+## 5. 变更流程（可执行）
+
+每次目录或文档结构调整按以下步骤执行：
+
+1. 在 `00_Management/03_Task_Checklist.md` 新增或勾选对应任务项。
+2. 建立本次变更的《迁移映射表》（见 `00_Management/07_Migration_Mapping_Template.md`）。
+3. 执行内容迁移（Markdown 与 `_images` 目录必须成组迁移）。
+4. 修复相对链接、目录入口链接、文内锚点引用。
+5. 执行校验命令：
+   - `make validate-file FILE=<目标文件>`
+   - `make check-links`
+   - `make validate-mermaid`
+6. 在 `00_Management/01_Project_Progress.md` 记录变更条目并说明影响。
+
+## 6. 验收门禁
+
+任一项不通过即视为本次治理未完成：
+
+- 断链数量 = 0。
+- Mermaid 语法错误 = 0。
+- 新增平行正式稿数量 = 0。
+- 结构变更登记完成率（Progress + Checklist）= 100%。
+- 主文档口径冲突项 = 0（系统名称、数据库口径、编号规则）。
+
+## 7. 角色与责任
+
+- 文档负责人：提出结构调整、确认主文档承载位置。
+- 执行人：按映射表迁移并修复链接与图文一致性。
+- 复核人：按门禁项复核，并确认变更记录已同步。
+

00_Management/07_Migration_Mapping_Template.md

@@ -0,0 +1,57 @@
+# 福建水务营收系统文档迁移映射表模板
+
+## 1. 使用说明
+
+- 本模板用于目录整理、文件迁移、编号调整、引用修复等结构性变更。
+- 每次结构调整必须新建一个“批次记录”，并在完成后归档到项目进度。
+- 迁移时必须保证 Markdown 与同名 `_images/` 目录成组处理。
+
+## 2. 批次信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 批次编号 | DG-YYYYMMDD-01 |
+| 变更主题 | 目录治理批次（示例） |
+| 发起日期 | YYYY-MM-DD |
+| 执行人 | 待填写 |
+| 复核人 | 待填写 |
+| 状态 | 进行中 / 已完成 |
+
+## 3. 迁移映射明细
+
+| 序号 | 旧路径 | 新路径 | 对象类型 | 是否含 `_images` | 链接修复状态 | 编号同步状态 | 执行人 | 复核结果 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | `旧文件路径` | `新文件路径` | 正式文档 / Archive / 附件 | 是 / 否 | 未开始 / 已完成 | 不涉及 / 已完成 | 待填写 | 待复核 |
+
+## 4. 引用修复清单
+
+| 序号 | 受影响文件 | 引用类型 | 修复前 | 修复后 | 验证结果 |
+| --- | --- | --- | --- | --- | --- |
+| 1 | `00_Management/04_Writing_Guide.md` | 相对路径 | `旧引用` | `新引用` | 通过 / 未通过 |
+
+## 5. 校验记录
+
+| 校验项 | 命令 | 结果 | 时间 | 备注 |
+| --- | --- | --- | --- | --- |
+| 单文档校验 | `make validate-file FILE=<目标文件>` | 通过 / 未通过 | YYYY-MM-DD HH:mm |  |
+| 全库链接校验 | `make check-links` | 通过 / 未通过 | YYYY-MM-DD HH:mm |  |
+| Mermaid 校验 | `make validate-mermaid` | 通过 / 未通过 | YYYY-MM-DD HH:mm |  |
+
+## 6. 风险与回退
+
+| 风险项 | 触发条件 | 应对策略 | 回退动作 |
+| --- | --- | --- | --- |
+| 图片失链 | `_images` 未同步迁移 | 补迁并批量修复引用 | 回退到迁移前路径 |
+| 章节锚点失效 | 标题重命名未同步 | 全文检索并修复锚点 | 恢复旧标题并逐步迁移 |
+| 口径冲突 | 主文档与历史文档冲突 | 以主文档统一口径为准 | 暂停发布并复核 |
+
+## 7. 收口确认
+
+完成前需全部勾选：
+
+- [ ] 迁移映射表字段已完整填写
+- [ ] 所有受影响链接已修复并验证通过
+- [ ] 模块/接口编号及正文引用已同步
+- [ ] `00_Management/01_Project_Progress.md` 已登记
+- [ ] `00_Management/03_Task_Checklist.md` 已勾选
+

scripts/precommit-validate-markdown.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+files=("$@")
+
+if [ "${#files[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+echo "开始校验本次变更的 Markdown 文件..."
+for file in "${files[@]}"; do
+  if [ ! -f "$file" ]; then
+    continue
+  fi
+  echo "校验: $file"
+  ./scripts/doc-toolkit.sh validate "$file"
+done
+echo "Markdown 文件校验通过"