diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..e371926 --- /dev/null +++ b/.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] + diff --git a/00_Management/01_Project_Progress.md b/00_Management/01_Project_Progress.md index 31120a9..dbc8581 100644 --- a/00_Management/01_Project_Progress.md +++ b/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不要出现操作手册中没有的功能，并核对删除多余功能 | 正面影响，确保微网厅系统功能与实际操作手册完全一致，避免设计与实施不符 | diff --git a/00_Management/03_Task_Checklist.md b/00_Management/03_Task_Checklist.md index ead6683..6e70721 100644 --- a/00_Management/03_Task_Checklist.md +++ b/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) ### 📋 新增引言文档 diff --git a/00_Management/06_Directory_Governance_Baseline.md b/00_Management/06_Directory_Governance_Baseline.md new file mode 100644 index 0000000..a559f8e --- /dev/null +++ b/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. 角色与责任 + +- 文档负责人：提出结构调整、确认主文档承载位置。 +- 执行人：按映射表迁移并修复链接与图文一致性。 +- 复核人：按门禁项复核，并确认变更记录已同步。 + diff --git a/00_Management/07_Migration_Mapping_Template.md b/00_Management/07_Migration_Mapping_Template.md new file mode 100644 index 0000000..f134346 --- /dev/null +++ b/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` 已勾选 + diff --git a/scripts/precommit-validate-markdown.sh b/scripts/precommit-validate-markdown.sh new file mode 100755 index 0000000..76fb695 --- /dev/null +++ b/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 文件校验通过"