From 6474880b4a0cd6d905ee2241e888b0ded818a8c4 Mon Sep 17 00:00:00 2001 From: tangweijie <877588133@qq.com> Date: Wed, 11 Mar 2026 14:48:15 +0800 Subject: [PATCH] docs: tidy 01_Overview structure and governance --- .../00_Management/01_Project_Progress.md | 1 + .../design/00_Management/03_Task_Checklist.md | 9 +++++ docs/design/01_Overview/01_System_Overview.md | 12 ++++++- .../01_Overview/02_System_Architecture.md | 12 ++++++- docs/design/01_Overview/04_System_Diagrams.md | 21 ++++++++++- docs/design/01_Overview/README.md | 36 ++++++++++++------- 6 files changed, 75 insertions(+), 16 deletions(-) diff --git a/docs/design/00_Management/01_Project_Progress.md b/docs/design/00_Management/01_Project_Progress.md index 0bbcf85..66d8548 100644 --- a/docs/design/00_Management/01_Project_Progress.md +++ b/docs/design/00_Management/01_Project_Progress.md @@ -111,6 +111,7 @@ | 变更时间 | 变更类型 | 变更内容 | 变更原因 | 影响评估 | | ---------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 2026-03-11 | `01_Overview` 目录治理与结构澄清 | 对 `docs/design/01_Overview/` 实施轻量治理：重写目录说明 `README.md`，明确四个文件的职责边界与阅读顺序；为 `01_System_Overview.md`、`02_System_Architecture.md`、`04_System_Diagrams.md` 补充 Front Matter 元数据（文档角色、权威级别、检索优先级）；修复 `01_System_Overview.md` 中迁移遗留的旧路径引用（`../02_Detailed/`、`../03_Technical/` → 新目录路径）；补充 `04_System_Diagrams.md` 的标题与文档定位说明，统一图文关系 | 用户反馈 `docs/design/01_Overview` 文件混乱，需要先完成目录职责澄清和基础可维护性治理 | 正面影响，总体设计目录从“文件并列”升级为“主稿+支撑文档”结构，文档职责与入口更清晰；迁移残留链接已清理，AI 检索与人工维护成本同步下降 | | 2026-03-11 | 正式设计文档目录体系迁移至 `docs/design/` | 将原仓库根目录下 `00_Management/`、`01_High_Level/`、`02_Detailed/`、`03_Technical/`、`04_Appendix/` 全量迁移至 `docs/design/` 下新目录：`00_Management/`、`01_Overview/`、`02_Detailed_Design/`、`03_Technical_Design/`、`04_Appendix/`；同步迁移 Archive 配套 `_images` 目录；批量修复仓库内路径引用，更新 `README.md`、`AGENTS.md`、`CLAUDE.md`、`scripts/unified_export.sh` 与 `scripts/check-ai-doc-governance.sh` 等关键入口与工具脚本，确保导出/校验链路与目录结构一致 | 用户要求将既有五大目录体系统一迁移到 `docs/design` 目录体系下，并要求自动完成迁移与路径治理 | 正面影响，正式设计文档已实现统一收口，目录边界更清晰；工具链与治理脚本已与新结构对齐，后续维护、检索、导出与跨代理协作成本显著降低 | | 2026-03-11 | AI 文档优化专项全自动落地 | 按 `docs/design/00_Management/09_AI_Document_Optimization_Plan.md` 一次性完成四阶段动作：补齐一级目录 `README.md`（7/7）、新增 `docs/design/00_Management/10_AI_Retrieval_Whitelist.md`、新增 `docs/design/00_Management/11_Main_Doc_Chapter_Index.md`、为六个主文档补齐 Front Matter（6/6）、新增 `docs/design/00_Management/12_AI_Weekly_Audit_Template.md` 与首份周检记录 `docs/design/00_Management/13_AI_Weekly_Audit_2026W11.md`，并新增 `scripts/check-ai-doc-governance.sh` 接入 pre-push 门禁 | 用户要求“全自动全弄了”，需将 AI 优化规划从阶段计划直接落地为可执行资产与可验证结果 | 正面影响，AI 文档体系已形成“目录索引 + 检索白名单 + 元数据标准 + 导航索引 + 周检机制 + 自动门禁”闭环；可显著提升检索命中率、减少历史资料干扰、增强跨代理执行一致性与可追溯性 | | 2026-03-11 | AI 文档优化专项规划 | 新增 `docs/design/00_Management/09_AI_Document_Optimization_Plan.md`，形成 4 周可执行优化方案（2026-03-12 至 2026-04-08），明确现状基线、阶段目标、交付物、验收指标与风险应对；重点覆盖目录索引补齐、主文档 Front Matter 标准化、超长文档可检索化与 AI 抽检门禁固化 | 用户要求“规划文档是否对 AI 优化”，需要将现状评估转化为可执行的阶段计划与量化验收标准 | 正面影响，AI 文档治理从“规则存在”升级为“按周推进 + 指标验收”的专项机制，可提升 AI 检索命中率、降低历史文档干扰并增强跨代理一致性 | diff --git a/docs/design/00_Management/03_Task_Checklist.md b/docs/design/00_Management/03_Task_Checklist.md index 278e076..8557fd0 100644 --- a/docs/design/00_Management/03_Task_Checklist.md +++ b/docs/design/00_Management/03_Task_Checklist.md @@ -138,6 +138,15 @@ ## ✅ 最新完成任务 (持续更新) +### 📋 `01_Overview` 目录治理 + +- [x] **完成总体设计目录职责澄清与结构收敛** ✅ (2026-03-11) + - [x] 重写 `docs/design/01_Overview/README.md`，明确主稿与支撑文档职责边界 ✅ + - [x] 补充 `01_System_Overview.md`、`02_System_Architecture.md`、`04_System_Diagrams.md` 的 Front Matter 元数据 ✅ + - [x] 修复 `01_System_Overview.md` 迁移遗留旧路径（`../02_Detailed/`、`../03_Technical/`）✅ + - [x] 为 `04_System_Diagrams.md` 补齐标题与文档定位说明，避免“纯图文件”可读性差 ✅ + - [x] 执行 `validate-file`、`check-links`、`validate-mermaid` 校验通过 ✅ + ### 📋 正式设计目录迁移至 `docs/design` - [x] **完成五大正式文档目录迁移** ✅ (2026-03-11) diff --git a/docs/design/01_Overview/01_System_Overview.md b/docs/design/01_Overview/01_System_Overview.md index 39dbfd2..e1f3d3a 100644 --- a/docs/design/01_Overview/01_System_Overview.md +++ b/docs/design/01_Overview/01_System_Overview.md @@ -1,3 +1,13 @@ +--- +doc_id: HL-01-OVERVIEW +doc_role: supporting_document +authority: supporting +scope: 总体设计-系统概述 +source_of_truth: false +last_reviewed: 2026-03-11 +retrieval_priority: P1 +--- + # 福建水务营收系统概要设计文档 ## 文档信息 @@ -298,4 +308,4 @@ **文档导航**： - 下一章：[二、系统架构设计](02_System_Architecture.md) -- 相关文档：[模块功能设计](../02_Detailed/02_Module_Design.md) | [数据库设计](../03_Technical/01_Database_Design.md) | [接口设计](../03_Technical/03_Interface_Design.md) \ No newline at end of file +- 相关文档：[模块功能设计](../02_Detailed_Design/02_Module_Design.md) | [数据库设计](../03_Technical_Design/01_Database_Design.md) | [接口设计](../03_Technical_Design/03_Interface_Design.md) diff --git a/docs/design/01_Overview/02_System_Architecture.md b/docs/design/01_Overview/02_System_Architecture.md index 58e43cd..05ec8fa 100644 --- a/docs/design/01_Overview/02_System_Architecture.md +++ b/docs/design/01_Overview/02_System_Architecture.md @@ -1,3 +1,13 @@ +--- +doc_id: HL-02-ARCHITECTURE +doc_role: supporting_document +authority: supporting +scope: 总体设计-系统架构 +source_of_truth: false +last_reviewed: 2026-03-11 +retrieval_priority: P1 +--- + # 福建水务营收系统架构设计文档 ## 文档信息 @@ -733,4 +743,4 @@ graph - 服务注册与发现：服务的自动注册和发现 - 服务路由：根据请求参数进行服务路由 - 服务降级：在服务不可用时提供降级策略 -- 服务监控：实时监控服务的可用性和性能 \ No newline at end of file +- 服务监控：实时监控服务的可用性和性能 diff --git a/docs/design/01_Overview/04_System_Diagrams.md b/docs/design/01_Overview/04_System_Diagrams.md index 4bd5f3a..8d5690f 100644 --- a/docs/design/01_Overview/04_System_Diagrams.md +++ b/docs/design/01_Overview/04_System_Diagrams.md @@ -1,3 +1,22 @@ +--- +doc_id: HL-04-DIAGRAMS +doc_role: supporting_document +authority: supporting +scope: 总体设计-系统图谱 +source_of_truth: false +last_reviewed: 2026-03-11 +retrieval_priority: P1 +--- + +# 福建水务营收系统总体图谱 + +## 文档定位 + +本文件用于集中维护总体层图谱，作为 `03_Summary_Design.md` 的配套图示文档。 +图示修改需与主文档架构描述同步，避免“图文口径不一致”。 + +## 系统整体架构图 + ```mermaid flowchart TD @@ -102,4 +121,4 @@ flowchart TD class C1,C2,C3,C4,C5,D1,D2,D3,D4,D5,D6,E1,E2 businessLayer class F1,F2,F3,F4,F5,F6 infrastructureLayer class G1,G2,G3 dataLayer -``` \ No newline at end of file +``` diff --git a/docs/design/01_Overview/README.md b/docs/design/01_Overview/README.md index 4a256f4..e341f98 100644 --- a/docs/design/01_Overview/README.md +++ b/docs/design/01_Overview/README.md @@ -1,22 +1,32 @@ -# 01_High_Level 总体设计入口 +# 01_Overview 总体设计目录说明 -## 目录用途 +## 目录定位 -`docs/design/01_Overview/` 用于维护系统总体设计、架构边界、子系统划分与概要设计主稿。 +`docs/design/01_Overview/` 仅用于承载“总体层”文档，重点描述系统边界、架构分层、子系统职责与概要设计主稿，不承载详细实现细节。 -## 权威文档 +## 文件职责矩阵 -- `03_Summary_Design.md`（主文档）：概要设计单一真源 +| 文件 | 角色 | 维护要求 | +| --- | --- | --- | +| `01_System_Overview.md` | 系统概述（背景、术语、引用） | 保持引言性质，不扩展实现细节 | +| `02_System_Architecture.md` | 总体架构说明（分层、技术栈、边界） | 与主文档架构口径保持一致 | +| `03_Summary_Design.md` | **概要设计主文档（单一真源）** | 优先维护；涉及范围变更时同步其余文档 | +| `04_System_Diagrams.md` | 图谱文档（图文配套） | 只维护图示与图注，不重复大段正文 | -## 关联文档 +## 与目录外文档的关系 -- `01_System_Overview.md`：系统概述 -- `02_System_Architecture.md`：系统架构说明 -- `04_System_Diagrams.md`：系统图谱与图例 +- `docs/design/01_Project_Overview.md` 为“项目导览文档”，用于跨目录导航与接手说明； +- 该文件不是总体设计主稿，不替代 `03_Summary_Design.md`。 -## 维护原则 +## 建议阅读顺序 -- 概要层只描述结构、职责、边界与关键接口原则 -- 不承载详细实现细节与代码级内容 -- 修改主文档后需同步检查图文一致性与章节引用 +1. `03_Summary_Design.md`（先建立主口径） +2. `01_System_Overview.md`（查看背景与术语） +3. `02_System_Architecture.md`（查看架构细节） +4. `04_System_Diagrams.md`（对照图示核对一致性） +## 维护规则 + +- 概要层文档禁止新增“最终版/修订版/新-xxx”平行稿； +- 涉及编号、模块边界、接口边界变更时，需同步检查本目录全部文件； +- 修改后至少执行：`make validate-file FILE=docs/design/01_Overview/<文件名>`、`make check-links`、`make validate-mermaid`。