docs: 精简概要导航并标准化章节锚点

This commit is contained in:
tangweijie 2026-03-11 15:07:58 +08:00
parent 1ed95dbe70
commit 375f9e5482
3 changed files with 53 additions and 252 deletions

View File

@ -111,6 +111,7 @@
| 变更时间 | 变更类型 | 变更内容 | 变更原因 | 影响评估 |
| ---------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 2026-03-11 | `03_Summary_Design` 导航精简与锚点标准化 | 在 `docs/design/01_Overview/03_Summary_Design.md` 中将顶部导航收敛为“章节导航(精简)”,移除冗长目录块,建立稳定锚点体系(`sec-preface``sec-overall-design``sec-subsystems``sec-sys-001~010``sec-nfr`)并同步章节跳转链接;执行 `make validate-file FILE=docs/design/01_Overview/03_Summary_Design.md``make check-links``make validate-mermaid``make check-ai-governance`。 | 用户要求“章节导航精简 + 锚点标准化”,并希望直接落地可执行结果 | 正面影响,超长主文档定位成本显著下降,章节跳转稳定性提升,后续标题调整时链接不易失效,便于 AI 检索与评审维护。 |
| 2026-03-11 | `01_Overview` 三文档深度重写 | 按“主文档单一真源、支撑文档不重复”原则重写 `docs/design/01_Overview/01_System_Overview.md``docs/design/01_Overview/02_System_Architecture.md``docs/design/01_Overview/04_System_Diagrams.md`1`01` 收敛为背景/目标/范围/术语导览移除实现细节2`02` 收敛为总体架构原则、子系统边界与协同规则,统一数据库口径为达梦数据库 8.0+3`04` 重建为图谱目录 + 三张总体图,并修复旧图中重复节点标识问题;同步完成 `validate-file``check-links``validate-mermaid``check-ai-governance` 校验 | 用户要求对 `docs/design/01_Overview` 混乱状态进行重写,形成可维护、可交付、可对齐主稿的总体层结构 | 正面影响,`01_Overview` 目录实现“导览文档 + 架构文档 + 图谱文档”分工清晰,重复内容显著减少,口径冲突(尤其数据库选型)已消除,后续评审和维护成本下降 |
| 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` 目录体系下,并要求自动完成迁移与路径治理 | 正面影响,正式设计文档已实现统一收口,目录边界更清晰;工具链与治理脚本已与新结构对齐,后续维护、检索、导出与跨代理协作成本显著降低 |

View File

@ -138,6 +138,15 @@
## ✅ 最新完成任务 (持续更新)
### 📋 `03_Summary_Design` 章节导航精简与锚点标准化
- [x] **完成概要主文档导航收敛与稳定锚点改造** ✅ (2026-03-11)
- [x] 顶部导航替换为“章节导航(精简)”,并移除超长目录块 ✅
- [x] 为前言、系统总体设计、子系统总览、SYS-001~SYS-010、非功能章节补齐 `sec-*` 显式锚点 ✅
- [x] 导航链接全部对齐到标准化锚点,避免依赖自动标题锚点 ✅
- [x] 执行 `make validate-file FILE=docs/design/01_Overview/03_Summary_Design.md``make check-links``make validate-mermaid``make check-ai-governance` 校验通过 ✅
- [x] 更新项目进度文件记录本次变更 ✅
### 📋 `01_Overview` 三文档深度重写
- [x] **完成总体层文档结构重写** ✅ (2026-03-11)

View File

@ -10,30 +10,31 @@ retrieval_priority: P0
# 福建水务营收系统概要设计说明书
## 快速定位导航
## 章节导航(精简)
- [前言](#前言)
- [系统总体设计](#系统总体设计)
- [子系统1设计: 统一平台](#子系统1设计-统一平台)
- [子系统2设计: 营收业务系统](#子系统2设计-营收业务系统)
- [子系统3设计: 手机抄表APP](#子系统3设计-手机抄表app)
- [子系统4设计: 微网厅系统](#子系统4设计-微网厅系统)
- [子系统5设计: 工单管理系统](#子系统5设计-工单管理系统)
- [子系统6设计: 表务管理系统](#子系统6设计-表务管理系统)
- [子系统7设计: 报装业务系统](#子系统7设计-报装业务系统)
- [子系统8设计: 发票服务子系统](#子系统8设计-发票服务子系统)
- [子系统9设计: 支付与银行结算子系统](#子系统9设计-支付与银行结算子系统)
- [子系统10设计: 消息服务子系统](#子系统10设计-消息服务子系统)
- [非功能性需求的设计](#非功能性需求的设计)
- [前言](#sec-preface)
- [系统总体设计](#sec-overall-design)
- [子系统设计SYS-001~SYS-010](#sec-subsystems)
- [SYS-001 统一平台](#sec-sys-001)
- [SYS-002 营收业务系统](#sec-sys-002)
- [SYS-003 手机抄表APP](#sec-sys-003)
- [SYS-004 微网厅系统](#sec-sys-004)
- [SYS-005 工单管理系统](#sec-sys-005)
- [SYS-006 表务管理系统](#sec-sys-006)
- [SYS-007 报装业务系统](#sec-sys-007)
- [SYS-008 发票服务子系统](#sec-sys-008)
- [SYS-009 支付与银行结算子系统](#sec-sys-009)
- [SYS-010 消息服务子系统](#sec-sys-010)
- [非功能性需求设计](#sec-nfr)
| 文件状态: | 文档密级: | 公开 |
| :--- | :--- | :--- |
| 【√】草稿 | | |
| 【】修改稿 | | |
| 【】正式发布 | | |
| | **当前版本:** | **V1.4** |
| | **当前版本:** | **V1.6** |
| | **作者:** | **唐伟杰** |
| | **完成日期:** | **2025-08-01** |
| | **完成日期:** | **2025-08-18** |
## 版本历史
@ -47,242 +48,7 @@ retrieval_priority: P0
| 2025-08-18 | V1.5 | 唐伟杰 | 架构调整将营收业务系统中的工单、表务、报装剥离为独立子系统SYS-005/006/007更新目录、功能范围、子系统列表、关系图与接口定义保留客户服务模块在营收业务系统中的作用。 |
| 2025-08-18 | V1.6 | 唐伟杰 | 合并第三方支付能力至SYS-009"支付与银行结算子系统"统一消息服务重编号为SYS-010更新总体目标、功能范围、接口定义、子系统列表与相关架构图。 |
# 目录
- [福建水务营收系统概要设计说明书](#福建水务营收系统概要设计说明书)
- [版本历史](#版本历史)
- [目录](#目录)
- [前言](#前言)
- [编写目的](#编写目的)
- [背景](#背景)
- [术语与缩略语](#术语与缩略语)
- [参考资料](#参考资料)
- [系统总体设计](#系统总体设计)
- [任务概述](#任务概述)
- [系统总体目标](#系统总体目标)
- [功能范围](#功能范围)
- [SYS-001 统一平台](#sys-001-统一平台)
- [SYS-002 营收业务系统](#sys-002-营收业务系统)
- [SYS-003 手机抄表APP](#sys-003-手机抄表app)
- [SYS-004 微网厅系统](#sys-004-微网厅系统)
- [SYS-005 工单管理系统](#sys-005-工单管理系统)
- [SYS-006 表务管理系统](#sys-006-表务管理系统)
- [SYS-007 报装业务系统](#sys-007-报装业务系统)
- [SYS-008 发票服务子系统(基础服务)](#sys-008-发票服务子系统基础服务)
- [SYS-009 支付与银行结算子系统(基础服务)](#sys-009-支付与银行结算子系统基础服务)
- [SYS-010 消息服务子系统(基础服务)](#sys-010-消息服务子系统基础服务)
- [系统涉众与用户特点](#系统涉众与用户特点)
- [设计概述](#设计概述)
- [总体约束](#总体约束)
- [系统依赖外部接口](#系统依赖外部接口)
- [设计方案概述](#设计方案概述)
- [系统架构设计](#系统架构设计)
- [系统的逻辑架构设计](#系统的逻辑架构设计)
- [整体架构图](#整体架构图)
- [层级说明](#层级说明)
- [系统数据流向图](#系统数据流向图)
- [系统的物理架构设计](#系统的物理架构设计)
- [物理部署图](#物理部署图)
- [网络连接](#网络连接)
- [硬件配置规格](#硬件配置规格)
- [达梦数据库分布式架构](#达梦数据库分布式架构)
- [容器化部署架构](#容器化部署架构)
- [子系统定义](#子系统定义)
- [子系统列表](#子系统列表)
- [子系统间关系](#子系统间关系)
- [子系统调用关系图](#子系统调用关系图)
- [主要接口定义](#主要接口定义)
- [子系统1设计: 统一平台](#子系统1设计-统一平台)
- [任务概述](#任务概述-1)
- [设计概述](#设计概述-1)
- [总体约束](#总体约束-1)
- [子系统外部接口](#子系统外部接口)
- [设计方案概述](#设计方案概述-1)
- [子系统架构设计](#子系统架构设计)
- [模块定义](#模块定义)
- [模块列表](#模块列表)
- [模块间关系](#模块间关系)
- [模块描述](#模块描述)
- [UP-001: 单点登录](#up-001-单点登录)
- [UP-002: 系统管理](#up-002-系统管理)
- [UP-003: 权限控制](#up-003-权限控制)
- [UP-004: 租户管理](#up-004-租户管理)
- [UP-005: 系统监控](#up-005-系统监控)
- [子系统2设计: 营收业务系统](#子系统2设计-营收业务系统)
- [任务概述](#任务概述-2)
- [营收核心模块群](#营收核心模块群)
- [客户服务模块群](#客户服务模块群)
- [设计概述](#设计概述-2)
- [总体约束](#总体约束-2)
- [子系统外部接口](#子系统外部接口-1)
- [设计方案概述](#设计方案概述-2)
- [子系统架构设计](#子系统架构设计-1)
- [模块定义](#模块定义-1)
- [模块列表](#模块列表-1)
- [营收核心模块群](#营收核心模块群-1)
- [客户服务模块群](#客户服务模块群-1)
- [模块间关系](#模块间关系-1)
- [营收核心模块群关系](#营收核心模块群关系)
- [客户服务模块群关系](#客户服务模块群关系)
- [模块群间协作关系](#模块群间协作关系)
- [模块描述](#模块描述-1)
- [REV-001: 客户资料管理](#rev-001-客户资料管理)
- [REV-002: 抄表开账](#rev-002-抄表开账)
- [REV-003: 营业收费](#rev-003-营业收费)
- [REV-004: 账务处理](#rev-004-账务处理)
- [REV-005: 发票管理](#rev-005-发票管理)
- [REV-006: 催缴管理](#rev-006-催缴管理)
- [REV-007: 统计分析](#rev-007-统计分析)
- [REV-008: 代收业务](#rev-008-代收业务)
- [REV-009: 业务参数配置](#rev-009-业务参数配置)
- [客户服务模块群描述](#客户服务模块群描述)
- [CS-001: 账户绑定管理](#cs-001-账户绑定管理)
- [CS-002: 信息查询服务](#cs-002-信息查询服务)
- [CS-003: 在线缴费服务](#cs-003-在线缴费服务)
- [CS-004: 电子发票服务](#cs-004-电子发票服务)
- [CS-005: 营业网点服务](#cs-005-营业网点服务)
- [CS-006: 业务办理服务](#cs-006-业务办理服务)
- [CS-007: 柜面扫码支付](#cs-007-柜面扫码支付)
- [子系统3设计: 手机抄表APP](#子系统3设计-手机抄表app)
- [任务概述](#任务概述-3)
- [设计概述](#设计概述-3)
- [总体约束](#总体约束-3)
- [子系统外部接口](#子系统外部接口-2)
- [设计方案概述](#设计方案概述-3)
- [子系统架构设计](#子系统架构设计-2)
- [模块定义](#模块定义-2)
- [模块列表](#模块列表-2)
- [模块间关系](#模块间关系-2)
- [模块描述](#模块描述-2)
- [MOBILE-001: 登录认证](#mobile-001-登录认证)
- [MOBILE-002: 首页搜索](#mobile-002-首页搜索)
- [MOBILE-003: 采集任务管理](#mobile-003-采集任务管理)
- [MOBILE-004: 现场上报](#mobile-004-现场上报)
- [MOBILE-005: 个人与设置](#mobile-005-个人与设置)
- [MOBILE-006: 数据同步](#mobile-006-数据同步)
- [子系统4设计: 微网厅系统](#子系统4设计-微网厅系统)
- [任务概述](#任务概述-4)
- [设计概述](#设计概述-4)
- [总体约束](#总体约束-4)
- [子系统外部接口](#子系统外部接口-3)
- [设计方案概述](#设计方案概述-4)
- [子系统架构设计](#子系统架构设计-3)
- [模块定义](#模块定义-3)
- [模块列表](#模块列表-3)
- [模块间关系](#模块间关系-3)
- [模块描述](#模块描述-3)
- [WECHAT-001: 账户绑定管理](#wechat-001-账户绑定管理)
- [WECHAT-002: 信息查询服务](#wechat-002-信息查询服务)
- [WECHAT-003: 在线缴费服务](#wechat-003-在线缴费服务)
- [WECHAT-004: 电子发票服务](#wechat-004-电子发票服务)
- [WECHAT-005: 营业网点服务](#wechat-005-营业网点服务)
- [WECHAT-006: 业务办理服务](#wechat-006-业务办理服务)
- [WECHAT-007: 账户流水](#wechat-007-账户流水)
- [WECHAT-008: 账号与机构管理](#wechat-008-账号与机构管理)
- [子系统5设计: 工单管理系统](#子系统5设计-工单管理系统)
- [任务概述](#任务概述-5)
- [设计概述](#设计概述-5)
- [总体约束](#总体约束-5)
- [子系统外部接口](#子系统外部接口-4)
- [设计方案概述](#设计方案概述-5)
- [子系统架构设计](#子系统架构设计-4)
- [模块定义](#模块定义-4)
- [模块列表](#模块列表-4)
- [模块间关系](#模块间关系-4)
- [模块描述](#模块描述-4)
- [WORK-001: 工单中心](#work-001-工单中心)
- [WORK-002: 流程引擎](#work-002-流程引擎)
- [WORK-003: 监控预警](#work-003-监控预警)
- [WORK-004: 绩效统计](#work-004-绩效统计)
- [子系统6设计: 表务管理系统](#子系统6设计-表务管理系统)
- [任务概述](#任务概述-6)
- [设计概述](#设计概述-6)
- [总体约束](#总体约束-6)
- [子系统外部接口](#子系统外部接口-5)
- [设计方案概述](#设计方案概述-6)
- [子系统架构设计](#子系统架构设计-5)
- [模块定义](#模块定义-5)
- [模块列表](#模块列表-5)
- [模块间关系](#模块间关系-5)
- [模块描述](#模块描述-5)
- [METER-001: 表务基础管理](#meter-001-表务基础管理)
- [METER-002: 仓库与库存管理](#meter-002-仓库与库存管理)
- [METER-003: 设备档案管理](#meter-003-设备档案管理)
- [子系统7设计: 报装业务系统](#子系统7设计-报装业务系统)
- [任务概述](#任务概述-7)
- [设计概述](#设计概述-7)
- [设计方案概述](#设计方案概述-7)
- [子系统外部接口](#子系统外部接口-6)
- [子系统架构设计](#子系统架构设计-6)
- [模块定义](#模块定义-6)
- [模块列表](#模块列表-6)
- [模块间关系](#模块间关系-6)
- [模块描述](#模块描述-6)
- [INST-001: 报装流程管理](#inst-001-报装流程管理)
- [INST-002: 工程管理](#inst-002-工程管理)
- [INST-003: 档案管理](#inst-003-档案管理)
- [子系统8设计: 发票服务子系统](#子系统8设计-发票服务子系统)
- [任务概述](#任务概述-8)
- [设计概述](#设计概述-8)
- [总体约束](#总体约束-7)
- [设计方案概述](#设计方案概述-8)
- [子系统外部接口](#子系统外部接口-7)
- [子系统架构设计](#子系统架构设计-7)
- [模块定义](#模块定义-7)
- [模块列表](#模块列表-7)
- [模块间关系](#模块间关系-7)
- [模块描述](#模块描述-7)
- [INV-001: 统一开票网关](#inv-001-统一开票网关)
- [INV-002: 供应商适配器](#inv-002-供应商适配器)
- [INV-003: 回执处理](#inv-003-回执处理)
- [INV-004: 存证与签章](#inv-004-存证与签章)
- [子系统9设计: 支付与银行结算子系统](#子系统9设计-支付与银行结算子系统)
- [任务概述](#任务概述-9)
- [设计概述](#设计概述-9)
- [总体约束](#总体约束-8)
- [设计方案概述](#设计方案概述-9)
- [子系统外部接口SYS-009](#子系统外部接口sys-009)
- [子系统架构设计](#子系统架构设计-8)
- [模块定义](#模块定义-8)
- [模块列表](#模块列表-8)
- [模块间关系](#模块间关系-8)
- [模块描述](#模块描述-8)
- [PAY-001: 统一支付/代扣网关](#pay-001-统一支付代扣网关)
- [PAY-002: 渠道适配器](#pay-002-渠道适配器)
- [PAY-003: 银行适配器](#pay-003-银行适配器)
- [PAY-004: 回调处理](#pay-004-回调处理)
- [PAY-005: 对账处理](#pay-005-对账处理)
- [PAY-006: 加解密/签名](#pay-006-加解密签名)
- [子系统10设计: 消息服务子系统](#子系统10设计-消息服务子系统)
- [任务概述](#任务概述-10)
- [设计概述](#设计概述-10)
- [总体约束](#总体约束-9)
- [子系统外部接口](#子系统外部接口-8)
- [设计方案概述](#设计方案概述-10)
- [子系统架构设计](#子系统架构设计-9)
- [模块定义](#模块定义-9)
- [模块列表](#模块列表-9)
- [模块间关系](#模块间关系-9)
- [模块描述](#模块描述-9)
- [MSG-001: 消息网关模块](#msg-001-消息网关模块)
- [MSG-002: 短信服务模块](#msg-002-短信服务模块)
- [MSG-003: 邮件服务模块](#msg-003-邮件服务模块)
- [MSG-004: 站内信模块](#msg-004-站内信模块)
- [MSG-005: 微信通知模块](#msg-005-微信通知模块)
- [MSG-006: 模板管理模块](#msg-006-模板管理模块)
- [MSG-007: 外部系统适配模块](#msg-007-外部系统适配模块)
- [非功能性需求的设计](#非功能性需求的设计)
- [性能的考虑](#性能的考虑)
- [兼容性的考虑](#兼容性的考虑)
- [安全的考虑](#安全的考虑)
- [可移植性的考虑](#可移植性的考虑)
- [关键技术特性](#关键技术特性)
- [响应式设计](#响应式设计)
- [安全保障](#安全保障)
- [集成与测试的考虑](#集成与测试的考虑)
- [可扩展性的考虑](#可扩展性的考虑)
- [可靠性的考虑](#可靠性的考虑)
- [可维护性的考虑](#可维护性的考虑)
<a id="sec-preface"></a>
# 前言
@ -346,6 +112,8 @@ retrieval_priority: P0
- 《Spring Cloud微服务架构设计指南》
- 《福建水务营收系统需求规格说明书》
<a id="sec-overall-design"></a>
# 系统总体设计
## 任务概述
@ -1177,6 +945,9 @@ graph TB
| IF-MSG-003 | 站内信接口 | 发送系统站内消息 | 各业务系统 | HTTP/REST | 用户ID、消息标题、消息内容、消息类型 | 发送结果、消息状态、已读状态 |
| IF-MSG-005 | 外部系统对接接口 | 对接OA/智水擎等外部系统 | OA系统/智水擎/水投数科APP | HTTP/REST | 系统标识、消息类型、接收用户、消息内容 | 对接状态、消息分发结果 |
<a id="sec-subsystems"></a>
<a id="sec-sys-001"></a>
# 子系统1设计: 统一平台
## 任务概述
@ -1930,6 +1701,8 @@ graph TD
- Redis存储实时监控数据
- WebSocket实时推送监控信息
<a id="sec-sys-002"></a>
# 子系统2设计: 营收业务系统
## 任务概述
@ -2872,6 +2645,8 @@ flowchart TD
- 二维码动态生成与管理
- POS机硬件设备对接
<a id="sec-sys-003"></a>
# 子系统3设计: 手机抄表APP
## 任务概述
@ -3075,6 +2850,8 @@ graph TD
<a id="sec-sys-004"></a>
# 子系统4设计: 微网厅系统
## 任务概述
@ -3306,6 +3083,8 @@ flowchart TD
Notify --> End([结束])
```
<a id="sec-sys-005"></a>
# 子系统5设计: 工单管理系统
## 任务概述
@ -3439,6 +3218,8 @@ graph TD
- SLA达成率考核指标
- 绩效报表自动生成导出
<a id="sec-sys-006"></a>
# 子系统6设计: 表务管理系统
## 任务概述
@ -3544,6 +3325,8 @@ graph TD
- 批次管理与质检记录追溯
- 档案查询与历史轨迹记录
<a id="sec-sys-007"></a>
# 子系统7设计: 报装业务系统
## 任务概述
@ -3733,6 +3516,8 @@ graph TD
- 审核意见记录
- 补充资料管理
<a id="sec-sys-008"></a>
# 子系统8设计: 发票服务子系统
## 任务概述
@ -3861,6 +3646,8 @@ graph TD
- 数字签章与下载链接
- 审计日志与合规留痕
<a id="sec-sys-009"></a>
# 子系统9设计: 支付与银行结算子系统
## 任务概述
@ -4028,6 +3815,8 @@ graph TD
- 密钥管理与定期轮换
- 数据安全传输保障
<a id="sec-sys-010"></a>
# 子系统10设计: 消息服务子系统
## 任务概述
@ -4222,6 +4011,8 @@ graph TD
- 水投数科app消息推送
- 外部API接口适配
<a id="sec-nfr"></a>
# 非功能性需求的设计
## 性能的考虑