docs: tidy 01_Overview structure and governance
This commit is contained in:
parent
747de59934
commit
6474880b4a
@ -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 检索命中率、降低历史文档干扰并增强跨代理一致性 |
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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)
|
||||
- 相关文档：[模块功能设计](../02_Detailed_Design/02_Module_Design.md) | [数据库设计](../03_Technical_Design/01_Database_Design.md) | [接口设计](../03_Technical_Design/03_Interface_Design.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
|
||||
- 服务注册与发现：服务的自动注册和发现
|
||||
- 服务路由：根据请求参数进行服务路由
|
||||
- 服务降级：在服务不可用时提供降级策略
|
||||
- 服务监控：实时监控服务的可用性和性能
|
||||
- 服务监控：实时监控服务的可用性和性能
|
||||
|
||||
@ -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
|
||||
```
|
||||
```
|
||||
|
||||
@ -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`。
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user