tangweijie/fujian_water_biz_doc
1
0
Fork 0
Code Issues Pull Requests 12 Actions Packages Projects Releases 1 Wiki Activity

docs: 持续优化主文档导航与AI检索白名单

Browse Source
This commit is contained in:
tangweijie 2026-03-11 15:52:42 +08:00
parent ed58e82d99
commit b1463e4e48
5 changed files with 73 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/design/00_Management/01_Project_Progress.md
View File

@ -111,6 +111,7 @@
| 变更时间 | 变更类型 | 变更内容 | 变更原因 | 影响评估 |
| ---------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 2026-03-11 | 主文档导航索引与检索白名单持续优化 | 持续优化 AI 检索与导航资产：1）重写 `docs/design/00_Management/11_Main_Doc_Chapter_Index.md`，将旧目录路径（`01_High_Level`、`02_Detailed`、`03_Technical`）统一修正为 `01_Overview`、`02_Detailed_Design`、`03_Technical_Design`，并补充详细设计分模块正文入口；2）更新 `docs/design/00_Management/10_AI_Retrieval_Whitelist.md`，将章节索引与模块追溯索引提升至 P1，并将 `11~15` 分模块正文纳入 P2；3）同步修订 `docs/design/01_Project_Overview.md` 对详细设计目录职责的描述。 | 用户要求“持续优化”，需要在已完成重构基础上继续提升导航准确性与 AI 检索稳定性 | 正面影响，主文档导航与白名单策略与当前目录结构完全对齐，减少旧路径误导和检索漂移；分模块正文入口更明确，便于按模块持续迭代。 |
| 2026-03-11 | `01_Detailed_Design` 模块正文去重重构 | 将 `docs/design/02_Detailed_Design/01_Detailed_Design.md` 中五大模块章节（统一平台、营收业务、客户服务、表务、报装与签章）改为“章节定位 + 模块摘要矩阵 + 分模块正文链接”，移除重复详细正文；同步将 `02_Module_Traceability_Index.md` 的模块级链接切换至 `11_UP_Detailed.md`、`12_REV_Detailed.md`、`13_CS_Detailed.md`、`14_METER_Detailed.md`、`15_INST_Detailed.md`，确保主详设与分模块正文职责清晰且链接可用。 | 用户要求“模块正文改为仅保留摘要 + 链接到分模块文件，彻底去重” | 正面影响，主详设从“重复正文集合”收敛为“总册导航与口径文档”，显著降低双份维护成本，后续按模块独立迭代时的一致性和可追溯性更高。 |
| 2026-03-11 | `02_Detailed_Design` 新增分模块正文文件 | 在 `docs/design/02_Detailed_Design/` 新增 `11_UP_Detailed.md`、`12_REV_Detailed.md`、`13_CS_Detailed.md`、`14_METER_Detailed.md`、`15_INST_Detailed.md` 五份模块正文文件，并为每份文档补齐 Front Matter、精简导航与模块锚点；同步在 `01_Detailed_Design.md` 增加“模块正文文件索引”，更新 `README.md`、`docs/design/02_Detailed_Design/README.md`、`scripts/unified_export.sh`、`02_Module_Traceability_Index.md` 引用与导出清单。 | 用户提出“详细设计没有分模块”，要求新增模块正文文档 | 正面影响，详细设计形成“主详设总册 + 分模块正文”的双层组织，模块维护颗粒度更清晰；评审、检索、按模块协作改稿效率提升。 |
| 2026-03-11 | `02_Detailed_Design` 结构重组与主稿导航标准化 | 对 `docs/design/02_Detailed_Design/` 执行“单一真源 + 专项补充”重构：1）将并行稿迁入归档（`04_Appendix/Archive/03_Design_Docs/02_Module_Design_legacy_20260311.md`、`03_CA_Installation_Design_legacy_20260311.md`）；2）新增 `02_Module_Traceability_Index.md`（模块-接口-数据域追溯索引）与 `03_CA_Esignature_Supplement.md`（报装电子签章专项补充）；3）重写 `01_Detailed_Design.md` 顶部为“章节导航（精简）”并补齐稳定锚点（`sec-preface`、`sec-overall-design`、`sec-module-detail`、`sec-platform-detail`、`sec-revenue-detail`、`sec-customer-detail`、`sec-meter-detail`、`sec-installation-detail`、`sec-database-detail`、`sec-interface-detail`、`sec-security-detail`、`sec-deployment-detail`、`sec-appendix`）；4）同步更新 README、导出脚本与附录引用。 | 用户确认按重组方案执行，要求解决 `02_Detailed_Design` 混乱问题并形成可长期维护结构 | 正面影响，详细设计目录职责边界明确：主详设聚焦权威正文，索引与CA细节分离；旧并行稿退出正式入口，口径冲突与维护噪音显著降低；章节定位和 AI 检索稳定性提升。 |

9
docs/design/00_Management/03_Task_Checklist.md
View File

@ -138,6 +138,15 @@
## ✅ 最新完成任务 (持续更新)
### 📋 主文档导航与白名单持续优化
- [x] **完成主文档导航索引路径与入口修正** ✅ (2026-03-11)
- [x] 重写 `11_Main_Doc_Chapter_Index.md` 的旧目录路径，统一到 `01_Overview` / `02_Detailed_Design` / `03_Technical_Design` ✅
- [x] 增补详细设计“分模块正文入口”导航（`11~15`）✅
- [x] 更新 `10_AI_Retrieval_Whitelist.md`：章节索引与模块追溯索引提升至 P1，分模块正文纳入 P2 ✅
- [x] 修订 `01_Project_Overview.md` 对详细设计目录职责描述 ✅
- [x] 更新项目进度文件记录本次持续优化动作 ✅
### 📋 `01_Detailed_Design` 模块正文去重
- [x] **完成主详设模块正文“摘要化 + 链接化”改造** ✅ (2026-03-11)

18
docs/design/00_Management/10_AI_Retrieval_Whitelist.md
View File

@ -20,14 +20,21 @@
1. `docs/design/00_Management/06_Directory_Governance_Baseline.md`
2. `docs/design/00_Management/08_AI_Agent_Maintenance_SOP.md`
3. `docs/design/00_Management/09_AI_Document_Optimization_Plan.md`
4. `docs/design/00_Management/01_Project_Progress.md`
5. `docs/design/00_Management/03_Task_Checklist.md`
4. `docs/design/00_Management/11_Main_Doc_Chapter_Index.md`
5. `docs/design/02_Detailed_Design/02_Module_Traceability_Index.md`
6. `docs/design/00_Management/01_Project_Progress.md`
7. `docs/design/00_Management/03_Task_Checklist.md`
### P2：辅助映射资料
1. `docs/guides/BACKEND_CURRENT_STATUS.md`
2. `docs/guides/BACKEND_TABLE_MAPPING.md`
3. `docs/design/00_Management/04_Writing_Guide.md`
1. `docs/design/02_Detailed_Design/11_UP_Detailed.md`
2. `docs/design/02_Detailed_Design/12_REV_Detailed.md`
3. `docs/design/02_Detailed_Design/13_CS_Detailed.md`
4. `docs/design/02_Detailed_Design/14_METER_Detailed.md`
5. `docs/design/02_Detailed_Design/15_INST_Detailed.md`
6. `docs/guides/BACKEND_CURRENT_STATUS.md`
7. `docs/guides/BACKEND_TABLE_MAPPING.md`
8. `docs/design/00_Management/04_Writing_Guide.md`
### P3：历史资料（仅核对来源）
@ -52,4 +59,3 @@
- 白名单命中率（抽检）≥ 95%
- 由 Archive 直接输出正式结论的次数 = 0
- 系统名称与数据库口径冲突次数 = 0

80
docs/design/00_Management/11_Main_Doc_Chapter_Index.md
View File

@ -2,7 +2,7 @@
## 1. 目的
为 AI Agent 和维护人员提供“主文档快速定位入口”，降低超长文档检索成本。
为 AI Agent 和维护人员提供“主文档快速定位入口”，降低超长文档检索成本，并统一目录迁移后的稳定路径。
## 2. 主文档导航
@ -12,30 +12,45 @@
| 快速入口 | 链接 |
| --- | --- |
| 前言 | [前言](../01_High_Level/03_Summary_Design.md#前言) |
| 系统总体设计 | [系统总体设计](../01_High_Level/03_Summary_Design.md#系统总体设计) |
| 子系统1设计 | [子系统1设计: 统一平台](../01_High_Level/03_Summary_Design.md#子系统1设计-统一平台) |
| 子系统2设计 | [子系统2设计: 营收业务系统](../01_High_Level/03_Summary_Design.md#子系统2设计-营收业务系统) |
| 子系统3设计 | [子系统3设计: 手机抄表APP](../01_High_Level/03_Summary_Design.md#子系统3设计-手机抄表app) |
| 子系统4设计 | [子系统4设计: 微网厅系统](../01_High_Level/03_Summary_Design.md#子系统4设计-微网厅系统) |
| 子系统5设计 | [子系统5设计: 工单管理系统](../01_High_Level/03_Summary_Design.md#子系统5设计-工单管理系统) |
| 子系统6设计 | [子系统6设计: 表务管理系统](../01_High_Level/03_Summary_Design.md#子系统6设计-表务管理系统) |
| 子系统7设计 | [子系统7设计: 报装业务系统](../01_High_Level/03_Summary_Design.md#子系统7设计-报装业务系统) |
| 子系统8设计 | [子系统8设计: 发票服务子系统](../01_High_Level/03_Summary_Design.md#子系统8设计-发票服务子系统) |
| 子系统9设计 | [子系统9设计: 支付与银行结算子系统](../01_High_Level/03_Summary_Design.md#子系统9设计-支付与银行结算子系统) |
| 子系统10设计 | [子系统10设计: 消息服务子系统](../01_High_Level/03_Summary_Design.md#子系统10设计-消息服务子系统) |
| 非功能性需求 | [非功能性需求的设计](../01_High_Level/03_Summary_Design.md#非功能性需求的设计) |
| 前言 | [前言](../01_Overview/03_Summary_Design.md#sec-preface) |
| 系统总体设计 | [系统总体设计](../01_Overview/03_Summary_Design.md#sec-overall-design) |
| 子系统总览 | [子系统设计总览](../01_Overview/03_Summary_Design.md#sec-subsystems) |
| SYS-001 统一平台 | [SYS-001](../01_Overview/03_Summary_Design.md#sec-sys-001) |
| SYS-002 营收业务 | [SYS-002](../01_Overview/03_Summary_Design.md#sec-sys-002) |
| SYS-003 手机抄表APP | [SYS-003](../01_Overview/03_Summary_Design.md#sec-sys-003) |
| SYS-004 微网厅系统 | [SYS-004](../01_Overview/03_Summary_Design.md#sec-sys-004) |
| SYS-005 工单管理系统 | [SYS-005](../01_Overview/03_Summary_Design.md#sec-sys-005) |
| SYS-006 表务管理系统 | [SYS-006](../01_Overview/03_Summary_Design.md#sec-sys-006) |
| SYS-007 报装业务系统 | [SYS-007](../01_Overview/03_Summary_Design.md#sec-sys-007) |
| SYS-008 发票服务子系统 | [SYS-008](../01_Overview/03_Summary_Design.md#sec-sys-008) |
| SYS-009 支付与银行结算 | [SYS-009](../01_Overview/03_Summary_Design.md#sec-sys-009) |
| SYS-010 消息服务子系统 | [SYS-010](../01_Overview/03_Summary_Design.md#sec-sys-010) |
| 非功能性需求设计 | [非功能性需求](../01_Overview/03_Summary_Design.md#sec-nfr) |
### 2.2 详细设计主文档
### 2.2 详细设计主文档（总册）
文档：`docs/design/02_Detailed_Design/01_Detailed_Design.md`
| 快速入口 | 链接 |
| --- | --- |
| 编写目的 | [编写目的](../02_Detailed/01_Detailed_Design.md#编写目的) |
| 总体目标 | [总体目标](../02_Detailed/01_Detailed_Design.md#总体目标) |
| 逻辑架构设计 | [逻辑架构设计](../02_Detailed/01_Detailed_Design.md#逻辑架构设计) |
| 子系统与模块划分 | [子系统与模块划分](../02_Detailed/01_Detailed_Design.md#子系统与模块划分) |
| 编写目的 | [编写目的](../02_Detailed_Design/01_Detailed_Design.md#编写目的) |
| 系统总体设计 | [系统总体设计](../02_Detailed_Design/01_Detailed_Design.md#sec-overall-design) |
| 模块设计总览 | [详细模块设计](../02_Detailed_Design/01_Detailed_Design.md#sec-module-detail) |
| 数据库详细设计 | [数据库详细设计](../02_Detailed_Design/01_Detailed_Design.md#sec-database-detail) |
| 接口详细设计 | [接口详细设计](../02_Detailed_Design/01_Detailed_Design.md#sec-interface-detail) |
| 安全详细设计 | [安全详细设计](../02_Detailed_Design/01_Detailed_Design.md#sec-security-detail) |
| 部署与运维设计 | [部署与运维设计](../02_Detailed_Design/01_Detailed_Design.md#sec-deployment-detail) |
| 附录 | [附录](../02_Detailed_Design/01_Detailed_Design.md#sec-appendix) |
### 2.2.1 详细设计分模块正文
| 模块正文 | 链接 |
| --- | --- |
| 统一平台 | [11_UP_Detailed](../02_Detailed_Design/11_UP_Detailed.md#sec-content) |
| 营收业务 | [12_REV_Detailed](../02_Detailed_Design/12_REV_Detailed.md#sec-content) |
| 客户服务 | [13_CS_Detailed](../02_Detailed_Design/13_CS_Detailed.md#sec-content) |
| 表务管理 | [14_METER_Detailed](../02_Detailed_Design/14_METER_Detailed.md#sec-content) |
| 报装与签章 | [15_INST_Detailed](../02_Detailed_Design/15_INST_Detailed.md#sec-content) |
### 2.3 数据库设计主文档
@ -43,11 +58,11 @@
| 快速入口 | 链接 |
| --- | --- |
| 前言 | [前言](../03_Technical/01_Database_Design.md#前言) |
| 表结构设计 | [表结构设计](../03_Technical/01_Database_Design.md#表结构设计) |
| SYS-002 客户与账户关系表 | [客户与账户关系表](../03_Technical/01_Database_Design.md#sys-002-客户与账户关系表-biz_cust--biz_account) |
| 视图设计 | [视图的设计](../03_Technical/01_Database_Design.md#视图的设计) |
| 索引设计与性能优化 | [索引设计与性能优化](../03_Technical/01_Database_Design.md#索引设计与性能优化) |
| 前言 | [前言](../03_Technical_Design/01_Database_Design.md#前言) |
| 表结构设计 | [表结构设计](../03_Technical_Design/01_Database_Design.md#表结构设计) |
| 视图设计 | [视图的设计](../03_Technical_Design/01_Database_Design.md#视图的设计) |
| 索引设计与性能优化 | [索引设计与性能优化](../03_Technical_Design/01_Database_Design.md#索引设计与性能优化) |
| 安全保密设计 | [安全保密设计](../03_Technical_Design/01_Database_Design.md#安全保密设计) |
### 2.4 接口设计主文档
@ -55,21 +70,22 @@
| 快速入口 | 链接 |
| --- | --- |
| 接口设计范围 | [接口设计范围](../03_Technical/03_Interface_Design.md#接口设计范围) |
| 外部接口设计 | [外部接口设计](../03_Technical/03_Interface_Design.md#外部接口设计) |
| 内部接口设计 | [内部接口设计](../03_Technical/03_Interface_Design.md#内部接口设计) |
| 数据对象与表口径 | [数据对象与表口径](../03_Technical/03_Interface_Design.md#数据对象与表口径) |
| 接口安全与异常处理 | [接口安全与异常处理](../03_Technical/03_Interface_Design.md#接口安全与异常处理) |
| 接口设计范围 | [接口设计范围](../03_Technical_Design/03_Interface_Design.md#接口设计范围) |
| 设计原则与统一约束 | [设计原则与统一约束](../03_Technical_Design/03_Interface_Design.md#设计原则与统一约束) |
| 外部接口设计 | [外部接口设计](../03_Technical_Design/03_Interface_Design.md#外部接口设计) |
| 内部接口设计 | [内部接口设计](../03_Technical_Design/03_Interface_Design.md#内部接口设计) |
| 数据对象与表口径 | [数据对象与表口径](../03_Technical_Design/03_Interface_Design.md#数据对象与表口径) |
| 接口安全与异常处理 | [接口安全与异常处理](../03_Technical_Design/03_Interface_Design.md#接口安全与异常处理) |
### 2.5 安全与部署主文档
| 文档 | 快速入口 |
| --- | --- |
| `docs/design/03_Technical_Design/04_Security_Design.md` | [安全设计概述](../03_Technical/04_Security_Design.md#安全设计概述)、[数据安全设计](../03_Technical/04_Security_Design.md#数据安全设计) |
| `docs/design/03_Technical_Design/05_Deployment_Design.md` | [部署概述](../03_Technical/05_Deployment_Design.md#部署概述)、[部署架构](../03_Technical/05_Deployment_Design.md#部署架构)、[监控运维](../03_Technical/05_Deployment_Design.md#监控运维) |
| `docs/design/03_Technical_Design/04_Security_Design.md` | [安全设计概述](../03_Technical_Design/04_Security_Design.md#安全设计概述)、[数据安全设计](../03_Technical_Design/04_Security_Design.md#数据安全设计) |
| `docs/design/03_Technical_Design/05_Deployment_Design.md` | [部署概述](../03_Technical_Design/05_Deployment_Design.md#部署概述)、[部署架构](../03_Technical_Design/05_Deployment_Design.md#部署架构)、[监控运维](../03_Technical_Design/05_Deployment_Design.md#监控运维) |
## 3. 使用说明
- 先从本索引进入主文档目标章节，再进行细节检索。
- 涉及实现细节时，优先从主详设总册进入分模块正文，再回到技术专项文档核对。
- 涉及跨文档问题时，先定位 P0 主文档，再补充 P1/P2 资料。

5
docs/design/01_Project_Overview.md
View File

@ -92,7 +92,7 @@
```text
docs/design/00_Management/ 项目管理、进度、交付标准、编写指南
docs/design/01_Overview/ 系统概述、系统架构、概要设计、系统图谱
docs/design/02_Detailed_Design/ 详细设计、模块设计、CA 安装设计
docs/design/02_Detailed_Design/ 详细设计总册、模块追溯索引、分模块正文、CA 专项补充
docs/design/03_Technical_Design/ 数据库、表结构、接口、安全、部署、加密
docs/design/04_Appendix/ 附录与 Archive 历史资料
assets/ 图片、模板等静态资源
@ -109,6 +109,7 @@ scripts/ 导出、校验、处理脚本
| 总体概览 | `docs/design/01_Overview/01_System_Overview.md` | 系统背景、术语、参考资料等总览信息 |
| 概要设计 | `docs/design/01_Overview/03_Summary_Design.md` | 概要设计主稿 |
| 详细设计 | `docs/design/02_Detailed_Design/01_Detailed_Design.md` | 详细设计主稿 |
| 详细设计分模块正文 | `docs/design/02_Detailed_Design/11_UP_Detailed.md` ~ `15_INST_Detailed.md` | 按模块独立维护的详细正文 |
| 数据库设计 | `docs/design/03_Technical_Design/01_Database_Design.md` | 数据库设计主稿 |
| 接口设计 | `docs/design/03_Technical_Design/03_Interface_Design.md` | 接口设计主稿 |
| 安全设计 | `docs/design/03_Technical_Design/04_Security_Design.md` | 安全设计主稿 |
@ -180,4 +181,4 @@ scripts/ 导出、校验、处理脚本
---
如无特殊说明，`docs/design/` 下的文档应以“导览、对齐、整编、摘要”为目标，避免重复复制正式主文档的大段正文。
如无特殊说明，`docs/design/` 下的文档应以“导览、对齐、整编、摘要”为目标，避免重复复制正式主文档的大段正文。