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

docs: rewrite 01_Overview documents with clear boundaries

Browse Source
This commit is contained in:
tangweijie 2026-03-11 14:59:31 +08:00
parent 6474880b4a
commit 1ed95dbe70
5 changed files with 320 additions and 1075 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 | `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` 目录体系下，并要求自动完成迁移与路径治理 | 正面影响，正式设计文档已实现统一收口，目录边界更清晰；工具链与治理脚本已与新结构对齐，后续维护、检索、导出与跨代理协作成本显著降低 |
| 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 文档体系已形成“目录索引 + 检索白名单 + 元数据标准 + 导航索引 + 周检机制 + 自动门禁”闭环；可显著提升检索命中率、减少历史资料干扰、增强跨代理执行一致性与可追溯性 |

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

@ -138,6 +138,15 @@
## ✅ 最新完成任务 (持续更新)
### 📋 `01_Overview` 三文档深度重写
- [x] **完成总体层文档结构重写** ✅ (2026-03-11)
- [x] 重写 `docs/design/01_Overview/01_System_Overview.md` 为“背景/目标/范围/术语”导览文档 ✅
- [x] 重写 `docs/design/01_Overview/02_System_Architecture.md` 为“架构原则/边界/协同”文档，统一达梦数据库口径 ✅
- [x] 重写 `docs/design/01_Overview/04_System_Diagrams.md` 为“图谱目录 + 总体图集”文档 ✅
- [x] 修复旧图谱节点重复标识问题，提升 Mermaid 可维护性 ✅
- [x] 执行 `validate-file`、`check-links`、`validate-mermaid`、`check-ai-governance` 校验通过 ✅
### 📋 `01_Overview` 目录治理
- [x] **完成总体设计目录职责澄清与结构收敛** ✅ (2026-03-11)

348
docs/design/01_Overview/01_System_Overview.md
View File

@ -8,304 +8,110 @@ last_reviewed: 2026-03-11
retrieval_priority: P1
---
# 福建水务营收系统概要设计文档
# 福建水务营收系统系统概述
## 文档信息
| 项目信息 | 详情 |
|---------|------|
| **项目名称** | 福建水务营收系统 |
| **文档类型** | 概要设计文档 |
| **技术框架** | RuoYi-Vue-Pro + yudao-ui-admin-vue3 |
| **文档版本** | v1.0 |
| **编写日期** | 2024-12-19 |
| **文档状态** | ✅ 已完成 |
## 1. 文档定位
## 目录
- [引言](#引言)
- [编写目的](#编写目的)
- [背景](#背景)
- [定义](#定义)
- [参考资料](#参考资料)
本文档用于说明福建水务营收系统的建设背景、目标、范围边界、涉众角色与基础术语，作为总体设计层的导览入口。
详细的模块设计、接口定义、数据结构与部署实现，以主文档和专项文档为准，不在本文重复展开。
---
## 2. 项目背景与建设目标
# 引言
### 2.1 项目背景
## 编写目的
福建水务营收系统面向水务企业营收管理与客户服务全流程，覆盖抄表、开账、收费、账务、工单、表务、报装与渠道服务。
项目目标是将分散业务统一到可评审、可交付、可持续维护的体系下，支撑集团化与多组织协同。
### 文档目标
### 2.2 建设目标
本文档是福建水务营收系统的概要设计文档，旨在为系统的详细设计、开发实施、测试验证、运维管理等后续工作提供重要的技术依据和指导方案。
- 建立统一平台能力，支撑认证、权限、组织、参数、租户与审计监控。
- 建立营收业务主链路，覆盖客户、计量、收费、账务与客服服务。
- 建立独立业务子系统，支撑移动抄表、工单、表务与报装场景。
- 建立基础服务子系统，统一发票、支付结算、消息能力。
- 满足安全合规、国产化适配与持续交付要求。
### 编写目的
## 3. 系统范围与边界
- **指导系统开发**：为开发团队提供清晰、完整、可执行的技术架构方案和实施蓝图
- **规范设计标准**：建立统一的技术标准和开发规范，确保系统架构的一致性和可维护性
- **评审技术方案**：为项目技术评审、方案论证提供详细的技术文档支撑
- **支撑项目管理**：为项目管理、进度控制、质量管控提供技术基础和评估依据
- **保障系统质量**：通过详细的设计说明确保系统的可靠性、安全性、可扩展性和高性能
### 3.1 范围内
### 目标读者
| 分类 | 范围说明 |
| --- | --- |
| 平台能力 | 统一认证、权限、租户、组织、参数、监控 |
| 核心业务 | 客户资料、抄表开账、营业收费、账务处理、发票、催缴、统计 |
| 业务子系统 | 手机抄表 APP、微网厅、工单管理、表务管理、报装业务 |
| 基础服务 | 发票服务、支付与银行结算、消息服务 |
| 外部集成 | 银行、第三方支付、短信/邮件/站内信、物联网、CA 能力 |
本文档的主要读者包括：
### 3.2 范围外
| 读者类型 | 主要关注点 | 使用目的 |
|---------|-----------|----------|
| **系统架构师** | 技术架构设计、技术选型方案 | 架构设计评审、技术方案优化 |
| **项目经理** | 项目范围、技术风险、实施计划 | 项目管理、进度控制、风险评估 |
| **开发工程师** | 技术实现方案、接口设计、数据库设计 | 系统开发、代码实现、模块集成 |
| **测试工程师** | 功能设计、性能指标、接口规范 | 测试用例设计、测试计划制定 |
| **运维工程师** | 部署架构、监控方案、运维策略 | 系统部署、运维管理、性能优化 |
| **业务分析师** | 业务功能、流程设计、用户体验 | 需求验证、业务流程梳理 |
| **甲方技术团队** | 整体技术方案、质量标准、交付成果 | 技术评审、验收标准制定 |
| 分类 | 说明 |
| --- | --- |
| 代码实现细节 | 具体类设计、SQL、接口字段定义 |
| 运维脚本实现 | 启停脚本、部署脚本、监控规则细项 |
| 测试用例细节 | 测试步骤、断言口径、执行结果 |
### 预期用途
## 4. 涉众与角色
- **开发阶段**：作为系统详细设计和编码实现的技术指导文档
- **测试阶段**：作为系统测试、集成测试、性能测试的参考标准
- **部署阶段**：作为系统部署、环境配置、运维管理的操作指南
- **维护阶段**：作为系统维护、功能扩展、技术升级的参考依据
- **培训阶段**：作为技术培训、知识传递的重要教材
| 角色 | 关注重点 |
| --- | --- |
| 项目管理与评审人员 | 范围边界、建设目标、交付范围 |
| 架构与开发人员 | 子系统职责、总体边界、协同关系 |
| 测试与运维人员 | 系统分层、部署原则、安全与可运维约束 |
| 甲方技术人员 | 交付口径一致性、可追溯性、后续维护可行性 |
## 背景
## 5. 术语与缩略语（概要层）
### 项目背景
### 5.1 业务术语
随着福建省水务行业数字化转型的深入推进和"数字福建"战略的全面实施，传统的水务营收管理系统已无法满足现代化管理的需要。为了提升水务企业的服务效率、管理水平和客户体验，迫切需要构建一套现代化、智能化、集成化的福建水务营收系统。
| 术语 | 说明 |
| --- | --- |
| 营收业务系统（SYS-002） | 核心营收业务承载子系统 |
| 微网厅（SYS-004） | 面向外部客户服务的线上渠道 |
| 表务管理（SYS-006） | 水表设备与库存相关管理域 |
| 报装业务（SYS-007） | 新装/改装/流程办理相关业务域 |
#### 业务发展需求
- **集团化管理**：支持福建水务集团及下属分公司的统一管理和分级运营
- **多租户架构**：实现"一套系统、多级管理"的集团化运营模式
- **移动化办公**：支持抄表员移动抄表、客户移动缴费等移动化业务
- **智能化服务**：集成物联网技术，实现远程抄表、智能监控等功能
- **一体化平台**：整合营收、客服、表务等多业务系统的一体化平台
### 5.2 技术术语
#### 技术升级需求
- **现代化技术栈**：采用先进的微服务架构和前后端分离技术
- **国产化适配**：全面适配华为OpenGauss等国产化数据库和中间件
- **云原生部署**：支持容器化部署和云原生架构
- **安全合规**：满足等保三级安全要求和行业安全规范
| 术语 | 说明 |
| --- | --- |
| SSO | 单点登录能力 |
| RBAC | 基于角色的访问控制 |
| OAuth2.0 + CAS | 统一认证与单点登录协议组合 |
| IF- 编号 | 接口编号前缀，用于与模块编号区分 |
### 系统现状
## 6. 关联文档
#### 现有系统问题
- **技术架构陈旧**：基于传统单体架构，扩展性和维护性较差
- **数据孤岛严重**：各子系统数据分散，缺乏统一的数据管理
- **用户体验不佳**：界面设计过时，操作流程复杂，移动端支持不足
- **集成能力弱**：与外部系统集成困难，接口标准化程度低
- **运维成本高**：系统运维复杂，故障定位困难，升级部署风险大
### 6.1 本目录文档
#### 业务挑战
- **客户服务效率低**：传统柜台服务模式，客户等待时间长
- **抄表作业不规范**：人工抄表易出错，实时性差
- **收费方式单一**：主要依赖现金收费，线上支付渠道不完善
- **数据分析能力弱**：缺乏有效的数据分析和决策支持工具
- 系统架构说明：`02_System_Architecture.md`
- 概要设计主文档（单一真源）：`03_Summary_Design.md`
- 总体图谱文档：`04_System_Diagrams.md`
### 相关系统
### 6.2 跨目录主文档
本系统需要与多个相关系统进行数据交换和业务协同：
- 详细设计主文档：`../02_Detailed_Design/01_Detailed_Design.md`
- 数据库设计主文档：`../03_Technical_Design/01_Database_Design.md`
- 接口设计主文档：`../03_Technical_Design/03_Interface_Design.md`
- 安全设计主文档：`../03_Technical_Design/04_Security_Design.md`
- 部署设计主文档：`../03_Technical_Design/05_Deployment_Design.md`
#### 内部系统
- **企业ERP系统**：财务数据同步、资产管理集成
- **GIS地理信息系统**：管网信息、客户位置信息集成
- **客户服务系统**：客户信息管理、服务工单处理
- **水质监测系统**：水质数据采集和分析
- **SCADA生产调度系统**：生产数据监控和调度
### 6.3 对齐与核对资料
#### 外部系统
- **银行代扣系统**：支持工商银行、建设银行等主要银行的代扣业务
- **第三方支付平台**：微信支付、支付宝等移动支付接口
- **短信服务平台**：阿里云短信、腾讯云短信等消息推送服务
- **物联网平台**：智能水表、远程抄表设备的数据采集
- **政务服务平台**：与当地政务服务网的数据对接
- 后端现状：`../../guides/BACKEND_CURRENT_STATUS.md`
- 后端表映射：`../../guides/BACKEND_TABLE_MAPPING.md`
- 历史资料归档：`../04_Appendix/Archive/`
#### 监管系统
- **水务行业监管平台**：向省市水务部门报送运营数据
- **价格监管系统**：水价政策执行情况报送
- **环保监测系统**：污水处理和环保数据上报
## 7. 阅读路径建议
### 建设环境
1. 先阅读 `03_Summary_Design.md`，建立统一口径。
2. 再阅读 `02_System_Architecture.md`，理解总体边界和架构原则。
3. 对照 `04_System_Diagrams.md`，核对图文一致性。
4. 按需进入详细设计、数据库和接口主文档。
#### 技术环境
- **开发框架**：基于RuoYi-Vue-Pro开源框架进行定制开发
- **数据库**：华为OpenGauss 5.0+企业版，支持主从复制和读写分离
- **中间件**：Redis 6.0集群、RabbitMQ消息队列、MinIO对象存储
- **部署环境**：支持Docker容器化部署和Kubernetes集群管理
- **监控运维**：集成Prometheus + Grafana监控体系
## 8. 维护要求
#### 基础设施环境
- **网络环境**：千兆局域网，支持VPN远程接入
- **安全环境**：防火墙、入侵检测、安全审计等安全防护体系
- **机房环境**：符合国家A级机房标准，具备完善的电力、空调、监控设施
- **灾备环境**：建设异地灾备中心，实现数据同步和业务连续性
## 定义
### 专业术语
| 术语 | 英文全称 | 中文定义 | 备注 |
|------|---------|----------|------|
| **抄表** | Meter Reading | 定期读取水表示数，记录客户用水量的业务过程 | 包括人工抄表和远程抄表 |
| **开账** | Billing | 根据抄表数据计算水费，生成客户账单的业务过程 | 核心营收业务 |
| **阶梯水价** | Tiered Water Pricing | 按用水量分档计费的水价政策 | 节水政策工具 |
| **水表** | Water Meter | 测量和记录水流量的计量设备 | 包括机械表和智能表 |
| **远传水表** | Remote Water Meter | 具备远程数据传输功能的智能水表 | 物联网设备 |
| **客户编号** | Customer Code | 唯一标识客户的业务编码 | 业务主键 |
| **水表编号** | Meter Code | 唯一标识水表的设备编码 | 设备标识 |
| **账务** | Accounting | 客户费用计算、账单管理、收费处理等财务业务 | 财务核心 |
| **收费** | Billing Collection | 向客户收取水费的业务过程 | 包括现金、刷卡、移动支付等 |
| **营业网点** | Service Outlet | 提供客户服务的营业场所 | 线下服务渠道 |
| **工单** | Work Order | 记录和跟踪业务处理过程的管理单据 | 流程管理工具 |
| **多租户** | Multi-tenancy | 支持多个独立客户共享同一应用实例的架构模式 | 技术架构模式 |
### 技术术语
| 术语 | 英文全称 | 中文定义 | 备注 |
|------|---------|----------|------|
| **微服务** | Microservices | 将单体应用拆分为多个独立服务的架构模式 | 现代架构模式 |
| **容器化** | Containerization | 使用容器技术打包和部署应用的技术方案 | Docker技术 |
| **API网关** | API Gateway | 统一管理和路由API请求的服务组件 | 微服务架构组件 |
| **负载均衡** | Load Balancing | 将请求分发到多个服务实例的技术 | 高可用技术 |
| **缓存** | Cache | 临时存储频繁访问数据以提高性能的技术 | 性能优化技术 |
| **消息队列** | Message Queue | 异步消息传递的中间件技术 | 系统解耦技术 |
| **数据库连接池** | Database Connection Pool | 管理数据库连接的资源池技术 | 性能优化技术 |
| **ORM** | Object-Relational Mapping | 对象关系映射，简化数据库操作的技术 | 数据访问技术 |
| **JWT** | JSON Web Token | 基于JSON的安全令牌标准 | 认证技术 |
| **RESTful** | Representational State Transfer | 基于HTTP的Web服务架构风格 | 接口设计规范 |
### 缩略语
| 缩略语 | 英文全称 | 中文含义 | 使用场景 |
|--------|----------|----------|----------|
| **RuoYi** | 若依开源框架 | 基于Spring Boot的快速开发框架 | 后端开发框架 |
| **Vue** | Vue.js | 渐进式JavaScript框架 | 前端开发框架 |
| **SaaS** | Software as a Service | 软件即服务 | 服务模式 |
| **B/S** | Browser/Server | 浏览器/服务器架构 | 系统架构模式 |
| **M/S** | Mobile/Server | 移动端/服务器架构 | 移动应用架构 |
| **RBAC** | Role-Based Access Control | 基于角色的访问控制 | 权限管理模式 |
| **SSO** | Single Sign-On | 单点登录 | 认证技术 |
| **DTO** | Data Transfer Object | 数据传输对象 | 数据传输模式 |
| **VO** | Value Object | 值对象 | 数据展示模式 |
| **DO** | Data Object | 数据对象 | 数据持久化模式 |
| **DAO** | Data Access Object | 数据访问对象 | 数据访问模式 |
| **MVC** | Model-View-Controller | 模型-视图-控制器 | 设计模式 |
| **IoT** | Internet of Things | 物联网 | 技术领域 |
| **GPS** | Global Positioning System | 全球定位系统 | 定位技术 |
| **GIS** | Geographic Information System | 地理信息系统 | 地理信息技术 |
### 业务术语规范
#### 客户管理相关
- **用户**：指系统的操作用户，如管理员、抄表员等
- **客户**：指水务服务的最终用户，即用水客户
- **账户**：客户在系统中的业务账户，用于记录用水和缴费信息
- **档案**：客户的基本信息档案，包括身份、地址、联系方式等
#### 计量收费相关
- **周期**：抄表计费的时间周期，通常为月度
- **示数**：水表显示的累计用水量数值
- **用量**：某个周期内的实际用水量
- **水费**：根据用水量和水价计算的费用
- **滞纳金**：逾期未缴费产生的违约金
#### 设备管理相关
- **表具**：水表设备的统称
- **口径**：水表的流量规格，如DN15、DN20等
- **厂商**：水表生产厂家
- **型号**：水表的具体型号规格
## 参考资料
### 国家标准和行业规范
| 标准编号 | 标准名称 | 版本 | 适用范围 |
|---------|----------|------|----------|
| **GB/T 778.1-2018** | 饮用冷水水表和热水水表 第1部分：技术要求 | 2018版 | 水表技术规范 |
| **GB/T 778.2-2018** | 饮用冷水水表和热水水表 第2部分：试验方法 | 2018版 | 水表检测标准 |
| **CJ/T 133-2019** | 电子远传水表 | 2019版 | 远传水表技术规范 |
| **GB 50015-2019** | 建筑给水排水设计标准 | 2019版 | 给排水工程设计 |
| **CJ/T 224-2019** | 城市供水水质标准 | 2019版 | 供水水质要求 |
### 信息安全标准
| 标准编号 | 标准名称 | 版本 | 适用范围 |
|---------|----------|------|----------|
| **GB/T 22239-2019** | 信息安全技术 网络安全等级保护基本要求 | 2019版 | 等保三级合规 |
| **GB/T 25070-2019** | 信息安全技术 网络安全等级保护安全设计技术要求 | 2019版 | 安全设计规范 |
| **GB/T 28448-2019** | 信息安全技术 网络安全等级保护测评要求 | 2019版 | 安全测评标准 |
| **GM/T 0054-2018** | 信息系统密码应用基本要求 | 2018版 | 密码应用规范 |
### 软件工程标准
| 标准编号 | 标准名称 | 版本 | 适用范围 |
|---------|----------|------|----------|
| **GB/T 8566-2007** | 信息技术 软件生存周期过程 | 2007版 | 软件开发流程 |
| **GB/T 16260.1-2006** | 软件工程 产品质量 第1部分：质量模型 | 2006版 | 软件质量标准 |
| **GB/T 15532-2008** | 计算机软件测试规范 | 2008版 | 软件测试规范 |
| **ISO/IEC 25010:2011** | Systems and software Quality Requirements and Evaluation (SQuaRE) | 2011版 | 软件质量国际标准 |
### 技术参考文档
#### 开发框架文档
- **RuoYi-Vue-Pro官方文档** - [https://doc.iocoder.cn/](https://doc.iocoder.cn/)
- **Spring Boot官方文档** - [https://spring.io/projects/spring-boot](https://spring.io/projects/spring-boot)
- **Vue 3官方文档** - [https://vuejs.org/](https://vuejs.org/)
- **Element Plus组件库文档** - [https://element-plus.org/](https://element-plus.org/)
#### 数据库文档
- **华为OpenGauss数据库文档** - [https://opengauss.org/](https://opengauss.org/)
- **Redis官方文档** - [https://redis.io/documentation](https://redis.io/documentation)
- **MyBatis-Plus官方文档** - [https://baomidou.com/](https://baomidou.com/)
#### 部署运维文档
- **Docker官方文档** - [https://docs.docker.com/](https://docs.docker.com/)
- **Kubernetes官方文档** - [https://kubernetes.io/docs/](https://kubernetes.io/docs/)
- **Nginx官方文档** - [https://nginx.org/en/docs/](https://nginx.org/en/docs/)
### 业务参考资料
#### 水务行业资料
- **《城市供水条例》** - 国务院令第158号
- **《城市供水价格管理办法》** - 国家发改委、住建部令第47号
- **《福建省城市供水管理办法》** - 福建省政府令第169号
- **《福建省阶梯水价实施方案》** - 福建省发改委文件
#### 项目相关文档
- **《福建水务营收系统需求分析报告》** - v2.0
- **《福建水务营收系统可行性研究报告》** - v1.0
- **《福建水务营收系统项目建设方案》** - v1.5
- **《现有系统调研报告》** - v1.0
- **《业务流程梳理报告》** - v2.1
### 技术选型参考
#### 架构设计参考
- **《微服务架构设计模式》** - Chris Richardson著
- **《Spring微服务实战》** - John Carnell著
- **《Vue.js设计与实现》** - 尤雨溪著
- **《分布式系统架构与实现》** - 李智慧著
#### 数据库设计参考
- **《数据库系统概念》** - Abraham Silberschatz著
- **《高性能MySQL》** - Baron Schwartz著
- **《Redis设计与实现》** - 黄健宏著
#### 安全设计参考
- **《Web安全深度剖析》** - 张炳帅著
- **《网络安全等级保护实施指南》** - 公安部信息安全等级保护评估中心编
---
## 本章小结
本章作为福建水务营收系统概要设计文档的引言部分，明确了文档的编写目的、项目背景、相关定义和参考资料。为后续的详细技术设计提供了必要的背景信息和术语基础。
**核心要点**：
- 📋 明确了文档的目标读者和预期用途
- 🏗️ 阐述了项目建设背景和技术升级需求
- 📚 建立了统一的术语规范和技术标准
- 📖 提供了完整的参考资料和技术依据
**文档导航**：
- 下一章：[二、系统架构设计](02_System_Architecture.md)
- 相关文档：[模块功能设计](../02_Detailed_Design/02_Module_Design.md) | [数据库设计](../03_Technical_Design/01_Database_Design.md) | [接口设计](../03_Technical_Design/03_Interface_Design.md)
- 本文档仅维护“概述级”信息，不引入实现细节。
- 出现与 `03_Summary_Design.md` 不一致时，以主文档为准并及时修正。
- 修改后至少执行：
- `make validate-file FILE=docs/design/01_Overview/01_System_Overview.md`
- `make check-links`

816
docs/design/01_Overview/02_System_Architecture.md
View File

@ -8,739 +8,151 @@ last_reviewed: 2026-03-11
retrieval_priority: P1
---
# 福建水务营收系统架构设计文档
# 福建水务营收系统总体架构说明
## 文档信息
| 项目信息 | 详情 |
|---------|------|
| **项目名称** | 福建水务营收系统 |
| **文档类型** | 概要设计文档 |
| **技术框架** | RuoYi-Vue-Pro + yudao-ui-admin-vue3 |
| **文档版本** | v1.0 |
| **编写日期** | 2024-12-19 |
| **文档状态** | ✅ 已完成 |
## 1. 文档定位
## 目录
- [系统架构概述](#系统架构概述)
- [技术架构](#技术架构)
- [应用架构](#应用架构)
- [数据架构](#数据架构)
- [安全架构](#安全架构)
- [部署架构](#部署架构)
- [接口架构](#接口架构)
本文档用于沉淀系统总体架构的分层方式、子系统边界和跨系统协同原则，作为 `03_Summary_Design.md` 的架构视图补充。
本文不承载模块级实现细节、接口字段细节和数据库字段细节，避免与主文档重复维护。
## 系统架构概述
## 2. 设计输入与约束
福建水务营收系统采用多层架构设计，旨在支持集团化的集中管理、统一资源管理的业务需求。系统架构的设计目标是实现"一个业务平台、一网通平台"的建设目标，为集团及下属各分公司提供统一的营业收费系统。
### 2.1 输入来源
系统架构主要包括以下核心特点：
- 多租户架构：支持集团、分公司、营业站点的多层级租户管理模式
- 统一资源服务：统一的福建水务系统运行资源环境
- 统一平台应用：统一业务流程，集中汇集数据
- 统一对外接口：提供标准的接口和能力
- 主文档：`03_Summary_Design.md`（唯一真源）
- 详细设计：`../02_Detailed_Design/01_Detailed_Design.md`
- 技术专项：`../03_Technical_Design/`
- 历史与对照资料：`../04_Appendix/Archive/`、`../../guides/`
### 系统总体架构图
### 2.2 约束原则
- 项目名称统一为“福建水务营收系统”。
- 接口编号与模块编号区分，接口编号使用 `IF-` 前缀。
- 数据库总体口径保持与主文档一致（达梦数据库 8.0+）。
- 图文必须一致；图示变更需同步核对主文档对应章节。
## 3. 总体逻辑架构
```mermaid
graph TB
subgraph USER["用户层"]
A1[Web管理端<br/>yudao-ui-admin-vue3]
A2[移动抄表端<br/>uni-app]
A3[客户微信端<br/>微信小程序]
A4[客户支付宝端<br/>支付宝小程序]
flowchart TB
subgraph Layer_Presentation["表现层"]
P_Web["Web 管理端"]
P_App["手机抄表 APP"]
P_Channel["微网厅/渠道端"]
end
subgraph GATEWAY["网关层"]
B1[Nginx负载均衡]
B2[API网关<br/>统一认证/权限控制]
subgraph Layer_Gateway["接入与网关层"]
G_Api["API 网关"]
G_Auth["统一认证与鉴权"]
end
subgraph APP["应用层"]
C1[营收管理<br/>RuoYi-Vue-Pro]
C2[客户服务<br/>RuoYi-Vue-Pro]
C3[表务管理<br/>RuoYi-Vue-Pro]
C4[统计分析<br/>RuoYi-Vue-Pro]
subgraph Layer_Business["业务服务层"]
B_SYS001["SYS-001 统一平台"]
B_SYS002["SYS-002 营收业务系统"]
B_SYS003["SYS-003 手机抄表 APP 服务"]
B_SYS004["SYS-004 微网厅系统"]
B_SYS005["SYS-005 工单管理系统"]
B_SYS006["SYS-006 表务管理系统"]
B_SYS007["SYS-007 报装业务系统"]
B_SYS008["SYS-008 发票服务子系统"]
B_SYS009["SYS-009 支付与银行结算子系统"]
B_SYS010["SYS-010 消息服务子系统"]
end
subgraph SERVICE["服务层"]
D1[权限服务<br/>Spring Security]
D2[工作流服务<br/>Flowable]
D3[消息服务<br/>Redis MQ]
D4[文件服务<br/>MinIO/OSS]
subgraph Layer_Infrastructure["基础能力层"]
I_Workflow["工作流能力"]
I_File["文件与附件能力"]
I_Monitor["监控与审计能力"]
I_Integration["外部集成适配能力"]
end
subgraph DATA["数据层"]
E1[(OpenGauss 5.0+<br/>主从架构)]
E2[(Redis 6.0<br/>集群缓存)]
E3[文件存储<br/>分布式存储]
subgraph Layer_Data["数据层"]
D_DM["达梦数据库 8.0+"]
D_Redis["Redis 缓存"]
D_Object["对象存储"]
end
subgraph EXTERNAL["外部接口"]
F1[银行接口<br/>代扣/托收]
F2[支付接口<br/>微信/支付宝]
F3[短信接口<br/>阿里云/腾讯云]
F4[物联网接口<br/>智能水表]
end
%% 层级间调用关系
USER -.->|请求访问| GATEWAY
GATEWAY -.->|负载均衡<br/>路由转发| APP
APP -.->|服务调用| SERVICE
APP -.->|外部集成| EXTERNAL
SERVICE -.->|数据访问| DATA
Layer_Presentation --> Layer_Gateway
Layer_Gateway --> Layer_Business
Layer_Business --> Layer_Infrastructure
Layer_Business --> Layer_Data
```
### 物理部署架构图
## 4. 子系统边界矩阵
```mermaid
graph TB
subgraph DMZ["DMZ区域"]
subgraph "负载均衡集群"
LB1[负载均衡器<br/>Nginx Cluster]
WAF[Web应用防火墙]
end
end
subgraph APPZONE["应用服务区"]
subgraph "Web服务集群"
WEB1[Web服务器1<br/>8核32G]
WEB2[Web服务器2<br/>8核32G]
end
subgraph "应用服务集群"
APP1[应用服务器1<br/>16核64G]
APP2[应用服务器2<br/>16核64G]
end
end
subgraph DATAZONE["数据服务区"]
subgraph "数据库集群"
DB1[OpenGauss主库<br/>32核128G]
DB2[OpenGauss从库<br/>32核128G]
end
subgraph "缓存集群"
REDIS1[Redis主节点<br/>16核32G]
REDIS2[Redis从节点<br/>16核32G]
REDIS3[Redis哨兵<br/>8核16G]
end
subgraph "文件存储"
FILE1[文件服务器1<br/>8核32G 10TB]
FILE2[文件服务器2<br/>8核32G 10TB]
end
end
subgraph MGMT["管理服务区"]
MONITOR[监控服务器<br/>8核16G]
BACKUP[备份服务器<br/>8核32G 20TB]
JUMP[跳板服务器<br/>4核8G]
end
%% 区域间调用关系
Internet -.->|外网访问| DMZ
DMZ -.->|负载均衡<br/>安全过滤| APPZONE
APPZONE -.->|数据访问<br/>业务处理| DATAZONE
MGMT -.->|监控管理<br/>备份恢复| DATAZONE
MGMT -.->|系统监控<br/>运维管理| APPZONE
```
| 子系统 | 核心职责 | 边界说明 |
| --- | --- | --- |
| SYS-001 统一平台 | 认证、权限、组织、参数、租户、监控 | 不承载具体行业业务流程 |
| SYS-002 营收业务系统 | 客户、抄表开账、收费、账务、客服核心能力 | 通过接口调用基础服务，不重复建设 |
| SYS-003 手机抄表 APP | 现场作业、移动采集、任务处理 | 以移动作业能力为主，不替代后台管理 |
| SYS-004 微网厅系统 | 客户线上服务与查询缴费 | 以渠道服务为主，不承载后台运营管理 |
| SYS-005 工单管理系统 | 工单流转、状态跟踪、绩效统计 | 专注工单域，不内嵌收费结算逻辑 |
| SYS-006 表务管理系统 | 表务档案、库存、设备管理 | 专注设备与库存域，不承担账务处理 |
| SYS-007 报装业务系统 | 报装流程、工程与档案管理 | 专注报装域流程，不替代统一工单 |
| SYS-008 发票服务子系统 | 开票与供应商适配 | 对外提供开票能力，不承载支付流程 |
| SYS-009 支付与银行结算子系统 | 聚合支付、银行结算、对账 | 对外提供资金结算能力，不承载发票逻辑 |
| SYS-010 消息服务子系统 | 短信/邮件/站内信等消息分发 | 对外提供消息能力，不承载业务决策 |
## 技术架构
## 5. 跨系统协同原则
系统采用B/S和M/S相结合的架构模式，基于现代化的技术栈构建。
### 5.1 接口协同
### 技术栈总览
- 子系统间交互通过标准化接口进行，避免跨库直连。
- 接口编号遵循 `IF-` 前缀规则，保持可追踪性。
- 对外集成能力由基础服务子系统统一收口，业务系统按需调用。
```mermaid
graph TB
subgraph FRONTEND["🏷 前端技术栈"]
FE1["Vue 3 + TypeScript<br/>Element Plus UI"]
FE2["Vite + Pinia<br/>Router + Axios"]
end
subgraph BACKEND["📦 后端技术栈"]
BE1["Spring Boot 3.x<br/>Spring Security"]:::spring
BE2["MyBatis Plus<br/>OpenGauss"]:::db
BE3["Redis缓存<br/>Knife4j文档"]:::cache
end
subgraph MIDDLEWARE["⚙️ 中间件服务"]
MW1["Nginx负载均衡<br/>Redis集群"]
MW2["Flowable工作流<br/>Quartz定时"]
MW3["MinIO存储<br/>消息队列"]
end
subgraph MOBILE["📱 移动应用"]
MB1["uni-app跨平台<br/>uView UI"]
MB2["微信/支付宝小程序<br/>H5响应式"]
MB3["GPS定位+NFC<br/>设备接口"]
end
%% 技术栈间调用关系
FRONTEND -.->|HTTP请求<br/>API调用| BACKEND
MOBILE -.->|跨平台调用<br/>API集成| BACKEND
BACKEND -.->|服务集成<br/>中间件调用| MIDDLEWARE
classDef spring fill:#6db33f,color:white
classDef db fill:#f9d27d
classDef cache fill:#b5e6c0
```
### 5.2 事务与一致性
### 系统数据流向图
- 同步事务优先控制在单子系统内部。
- 跨系统流程采用“状态驱动 + 补偿机制”的一致性策略。
- 关键状态变更需具备审计记录与回溯能力。
```mermaid
flowchart TD
subgraph COLLECT["数据采集层"]
A1[移动抄表APP<br/>数据采集]
A2[智能水表<br/>远程数据]
A3[Web管理端<br/>业务录入]
A4[客户端小程序<br/>用户数据]
A5[外部系统<br/>接口数据]
end
subgraph ACCESS["数据接入层"]
B1[API网关<br/>数据验证]
B2[数据清洗<br/>格式转换]
B3[消息队列<br/>异步处理]
B4[数据缓存<br/>临时存储]
end
subgraph PROCESS["业务处理层"]
C1[抄表服务<br/>水量计算]
C2[收费服务<br/>账单生成]
C3[账务服务<br/>财务处理]
C4[工单服务<br/>流程处理]
C5[统计服务<br/>数据分析]
end
subgraph STORAGE["数据存储层"]
D1[(OpenGauss主库<br/>核心业务数据)]
D2[(OpenGauss从库<br/>查询数据)]
D3[(Redis缓存<br/>热点数据)]
D4[文件存储<br/>附件图片]
D5[(备份库<br/>历史数据)]
end
subgraph SERVICE["数据服务层"]
E1[查询服务<br/>数据检索]
E2[报表服务<br/>统计分析]
E3[接口服务<br/>对外开放]
E4[推送服务<br/>消息通知]
end
subgraph PRESENT["数据展现层"]
F1[管理后台<br/>业务操作]
F2[统计大屏<br/>可视化展示]
F3[移动端<br/>现场作业]
F4[客户端<br/>自助服务]
F5[第三方系统<br/>数据集成]
end
%% 数据流向关系
COLLECT -.->|数据采集<br/>格式验证| ACCESS
ACCESS -.->|数据接入<br/>清洗转换| PROCESS
PROCESS -.->|业务处理<br/>数据持久化| STORAGE
STORAGE -.->|数据查询<br/>统计分析| SERVICE
SERVICE -.->|数据服务<br/>接口调用| PRESENT
PRESENT -.->|用户反馈<br/>业务交互| PROCESS
```
## 6. 数据架构原则
### 服务端技术架构
- 核心业务数据统一落地至达梦数据库体系。
- 缓存仅用于性能优化，不作为业务真源。
- 主数据（客户、账户、设备、组织）在归属子系统维护，跨系统通过接口共享。
- 涉及敏感信息的数据遵循加密与脱敏规范，具体规则见安全专项文档。
系统采用基于RuoYi-Vue-Pro框架的技术架构：
## 7. 部署架构原则
- **操作系统**：国产 Linux 操作系统
- **数据库**：华为OpenGauss 5.0+数据库，企业级国产数据库
- **应用框架**：基于RuoYi-Vue-Pro框架定制开发
- 核心框架：Spring Boot 3.x，支持JDK 17/21
- ORM框架：MyBatis Plus，增强的MyBatis
- 权限框架：Spring Security，基于RBAC的权限管理
- 数据缓存：Redis + Redisson，高性能缓存和分布式锁
- 工作流引擎：Flowable，灵活的工作流处理
- 任务调度：基于Quartz的CRON任务调度
- 服务监控：Spring Boot Admin、SkyWalking APM
- 消息队列：基于Redis的轻量级消息队列
- 文档生成：Knife4j，基于Swagger的API文档生成
- 代码生成：自动化CRUD和表单代码生成器
- 多租户：基于字段隔离的SaaS多租户设计
- 系统采用分层部署，接入层、业务层、数据层职责清晰。
- 支持容器化部署与统一运维管理，满足扩展与回滚要求。
- 网络访问遵循内外网分区与最小权限原则。
- 外部集成链路采用统一接入策略，降低耦合风险。
### 客户端技术架构
## 8. 安全与合规原则
#### Web管理端架构 (yudao-ui-admin-vue3)
- 统一认证、统一授权、统一审计。
- 关键业务接口启用访问控制、参数校验和日志追踪。
- 敏感数据执行分类保护与最小暴露。
- 安全设计细则以 `../03_Technical_Design/04_Security_Design.md` 为准。
**核心技术组成：**
- Vue 3.x + TypeScript：现代化前端框架
- Element Plus：企业级UI组件库
- Pinia：新一代状态管理
- Vue Router：路由管理
- Axios：HTTP请求库
- ECharts：数据可视化图表
- Vite：快速构建工具
## 9. 非功能性要求（概要层）
**架构特点：**
- 基于Composition API的组件开发模式
- TypeScript提供类型安全保障
- 模块化的项目结构设计
- 响应式的状态管理机制
- 统一的HTTP请求封装
- 完善的权限控制体系
| 维度 | 架构要求 |
| --- | --- |
| 可用性 | 关键链路具备故障隔离与恢复能力 |
| 可扩展性 | 子系统边界稳定、能力可水平扩展 |
| 可维护性 | 文档、编号、接口边界可追踪 |
| 可观测性 | 关键流程具备日志、指标、审计记录 |
#### 移动端架构 (uni-app)
> 量化指标、容量规格与性能参数，以主文档和部署专项文档为准。
**技术栈组成：**
```mermaid
graph TB
subgraph FRAMEWORK["跨平台框架"]
M1[uni-app 3.x]
M2[Vue 3 Composition API]
M3[TypeScript支持]
end
subgraph UIKIT["UI组件库"]
N1[uView UI 2.0]
N2[uni-ui组件]
N3[自定义水务组件]
end
subgraph DEVICE["设备能力"]
P1[相机API<br/>水表拍照]
P2[NFC读取<br/>水表标签]
P3[GPS定位<br/>抄表轨迹]
P4[扫码API<br/>二维码扫描]
end
subgraph NETWORK["网络通信"]
Q1[uni.request<br/>HTTP请求]
Q2[WebSocket<br/>实时通信]
Q3[文件上传<br/>图片处理]
end
%% 移动架构调用关系
FRAMEWORK -.->|UI渲染<br/>组件调用| UIKIT
FRAMEWORK -.->|设备调用<br/>原生能力| DEVICE
FRAMEWORK -.->|网络通信<br/>数据交互| NETWORK
```
## 10. 与主文档映射
### 技术特性
| 本文档章节 | 主文档对应章节 |
| --- | --- |
| 总体逻辑架构 | `03_Summary_Design.md` 中“系统架构设计/系统的逻辑架构设计” |
| 子系统边界矩阵 | `03_Summary_Design.md` 中“子系统定义/子系统列表” |
| 跨系统协同原则 | `03_Summary_Design.md` 中“子系统间关系/主要接口定义” |
| 数据与部署原则 | `03_Summary_Design.md` 中“系统的物理架构设计” |
- **单点登录**：OAuth2 + JWT实现统一认证
- **数据交换**：基于RESTful API的系统内部数据交换与共享
- **统一报表平台**：集成JimuReport，支持自定义报表设计与生成
- **大屏设计**：集成GoView，支持可视化大屏设计
- **安全保障**：满足安全等保三级要求
- 密码加密：BCrypt加密算法
- 防XSS攻击：表单数据过滤
- 防SQL注入：参数化查询
- 防CSRF攻击：Token验证
- **性能规格**：支持200并发用户，50并发移动设备，系统响应时间不超过3秒
- **扩展容量**：支持100万客户的业务量，满足企业3-5年的业务发展需求
## 11. 维护规则
## 应用架构
### 微服务应用架构图
```mermaid
graph TD
subgraph ACCESS["接入层"]
GW[API网关]
AUTH[认证服务]
end
subgraph BUSINESS["业务服务层"]
SYS[系统服务]
CUST[客户服务]
READ[抄表服务]
BILL[账单服务]
PAY[收费服务]
ORDER[工单服务]
RPT[报表服务]
end
subgraph SUPPORT["支撑服务层"]
METER[水表管理]
WF[工作流引擎]
PAY_GW[支付网关]
IOT[物联网]
end
subgraph DATA["数据存储层"]
DB[(OpenGauss数据库)]
REDIS[(Redis缓存)]
FILE_STORE[文件存储]
end
%% 层级间的调用关系
ACCESS -.->|请求路由<br/>认证授权| BUSINESS
BUSINESS -.->|服务调用| SUPPORT
BUSINESS -.->|数据访问| DATA
SUPPORT -.->|数据访问| DATA
```
### 服务治理架构
```mermaid
graph TB
subgraph REGISTRY["服务发现与注册"]
NACOS[Nacos注册中心<br/>服务注册/发现/配置]
end
subgraph MESH["服务网格层"]
subgraph BALANCE["负载均衡"]
LB[Ribbon负载均衡<br/>客户端负载均衡]
FEIGN[OpenFeign<br/>服务间调用]
end
subgraph PROTECTION["容错保护"]
CB[Sentinel熔断器<br/>流量控制/熔断降级]
RETRY[重试机制<br/>失败重试]
end
subgraph TRACING["链路追踪"]
TRACE[SkyWalking<br/>分布式链路追踪]
METRIC[Micrometer<br/>指标收集]
end
end
subgraph CONFIG_MGMT["配置管理"]
CONFIG[Nacos Config<br/>配置中心]
SECRET[配置加密<br/>敏感信息保护]
end
subgraph MONITORING["监控告警"]
MONITOR[Spring Boot Admin<br/>应用监控]
ALERT[告警系统<br/>异常通知]
LOG[ELK日志系统<br/>日志聚合分析]
end
%% 服务治理调用关系
REGISTRY -.->|服务发现<br/>配置下发| MESH
MESH -.->|配置获取<br/>服务注册| CONFIG_MGMT
MESH -.->|监控数据<br/>链路追踪| MONITORING
```
### 应用模块设计
系统应用架构基于业务域划分，主要包括以下核心应用模块：
#### 统一平台
- 单点登录：统一认证入口，支持多种登录方式
- 系统管理：组织机构、员工管理、角色权限管理、菜单配置等
- 流程节点提醒：工作流节点到期和状态变更提醒
#### 营收系统
- 系统管理：水价管理、用户档案管理、更名过户管理等
- 抄表开账：册本管理、抄表录入、复核开账等
- 收费管理：柜台收费、特殊开账、柜台结账、批量缴费等
- 账务处理：预存调整、未销调整、已销调整、分账调整等
- 发票管理：发票查询、发票开具、电子发票等
- 代收业务：实时收费、银行代扣、银行托收等
#### 客户服务
- 微信、支付宝服务窗：账户绑定、用水查询、在线缴费等
- 历史账单：账单查询、用水分析、账单推送等
- 电子发票：发票申请、发票查询、发票下载等
- 营业网点：网点查询、网点导航、业务指南等
#### 表务系统
- 表务工单：换表工单、移表工单、拆表工单、复装工单等
- 表务仓库：新表入库、水表检定、水表领用、水表出库等
- 水表参数与基础信息：水表厂家管理、水表型号管理等
- 物联网对接与数据同步：厂家设备信息管理、远程抄表数据同步等
#### 报装管理
- 报装流程：报装申请、方案设计、合同签订、施工管理等
- 一户一表管理：改造计划、改造实施、用户转换等
#### 统计分析
- 报表查询：标准报表、自定义报表、报表导出打印等
- 欠费查询：欠费情况统计、欠费用户明细、欠费分析等
- 缴费记录：缴费情况统计、缴费明细查询、缴费趋势分析等
- 用水分析：用水量统计、用水趋势分析、异常用水分析等
## 数据架构
系统数据架构基于客户关系数据库为核心和基础，实现客户全生命周期管理。
### OpenGauss数据库架构
#### 主从高可用架构
```mermaid
graph
subgraph DBCLUSTER["OpenGauss高可用集群"]
MASTER[("OpenGauss主库<br/>Primary Node<br/>读写操作")]
STANDBY[("OpenGauss备库<br/>Standby Node<br/>只读操作")]
CASCADE[("OpenGauss级联备库<br/>Cascade Standby<br/>负载分担")]
MASTER -.->|流复制| STANDBY
STANDBY -.->|级联复制| CASCADE
end
subgraph APPLAYER["应用层"]
APP1[应用服务器1]
APP2[应用服务器2]
APP3[应用服务器3]
end
subgraph POOLING["连接池"]
POOL[连接池<br/>HikariCP<br/>Druid]
end
subgraph MANAGEMENT["监控管理"]
MON[OpenGauss Monitor<br/>性能监控]
BACKUP[定时备份<br/>gs_backup]
end
%% 高可用架构调用关系
APPLAYER -.->|连接请求<br/>负载均衡| POOLING
POOLING -.->|数据访问<br/>读写分离| DBCLUSTER
MANAGEMENT -.->|监控管理<br/>备份恢复| DBCLUSTER
```
#### 分片存储架构
```mermaid
graph TB
subgraph DISTRIBUTED["OpenGauss分布式架构"]
subgraph COORDINATOR["协调节点"]
CN1[协调节点1<br/>Coordinator Node]
CN2[协调节点2<br/>Coordinator Node]
end
subgraph DATANODE1["数据节点组1"]
DN1_1[数据节点1-主<br/>Datanode Primary]
DN1_2[数据节点1-备<br/>Datanode Standby]
DN1_1 -.->|主备同步| DN1_2
end
subgraph DATANODE2["数据节点组2"]
DN2_1[数据节点2-主<br/>Datanode Primary]
DN2_2[数据节点2-备<br/>Datanode Standby]
DN2_1 -.->|主备同步| DN2_2
end
subgraph GTM_CLUSTER["GTM节点"]
GTM[全局事务管理器<br/>GTM Master]
GTM_S[GTM备节点<br/>GTM Standby]
GTM -.->|备份| GTM_S
end
end
%% 分布式架构调用关系
COORDINATOR -.->|分片路由<br/>查询协调| DATANODE1
COORDINATOR -.->|分片路由<br/>查询协调| DATANODE2
COORDINATOR -.->|事务管理<br/>全局一致性| GTM_CLUSTER
```
### 数据模型设计
- **客户信息模型**：包含客户基础信息、表卡信息、账户信息、联系人信息等
- **业务数据模型**：抄表数据、收费数据、账务数据、发票数据等
- **工单数据模型**：表务工单、报装工单、业务工单等
- **配置数据模型**：系统参数、水表参数、价格体系等
- **报表数据模型**：统计数据、分析数据、预测数据等
- **物联网数据模型**：设备信息、状态信息、实时数据等
### 数据集成与共享
- **统一数据标准**：定义统一的数据标准和数据字典，符合OpenGauss规范
- **数据集成机制**：采用OpenGauss XA事务实现系统间的数据一致性
- **数据共享机制**：基于OpenGauss外部数据包装器(FDW)实现跨库数据访问
- **数据同步策略**：支持实时流复制、定时数据同步、批量ETL处理等
### OpenGauss特性应用
#### 性能优化特性
- **向量化执行引擎**：批量数据处理，提升OLAP查询性能30-50%
- **列存储引擎**：统计报表类查询，压缩比高达10:1
- **分区表技术**：按月份分区存储抄表数据，支持分区裁剪
- **并行查询**：复杂统计查询自动并行执行
- **智能优化器**：自适应查询计划，持续性能优化
#### 企业级特性
- **在线扩容**：支持不停机新增数据节点
- **故障自愈**：主备节点故障自动切换，RTO < 10秒
- **读写分离**：自动路由读请求到备节点，减轻主库压力
- **负载均衡**：连接池级别的智能负载均衡
- **全量/增量备份**：支持热备份，最小备份粒度到事务级
## 安全架构
系统安全架构基于OpenGauss数据库的企业级安全特性，满足等保三级要求和国产化安全标准：
### OpenGauss数据安全架构
#### 数据加密安全
```mermaid
graph
subgraph ENCRYPT["加密层级"]
direction TB
L1[传输层加密<br/>SSL/TLS/国密SM]
L2[存储层加密<br/>TDE透明数据加密]
L3[字段级加密<br/>敏感字段加密]
L4[备份加密<br/>备份文件加密]
end
subgraph KEYMANAGE["密钥管理"]
direction TB
KMS[密钥管理系统<br/>Key Management]
HSM[硬件安全模块<br/>Hardware Security]
ROT[密钥轮换<br/>Key Rotation]
end
subgraph GUOMI["国密算法"]
direction TB
SM2[SM2椭圆曲线<br/>非对称加密]
SM3[SM3哈希算法<br/>消息摘要]
SM4[SM4分组密码<br/>对称加密]
end
%% 安全层级调用关系
ENCRYPT -.->|密钥依赖<br/>加密管理| KEYMANAGE
KEYMANAGE -.->|算法调用<br/>国密支持| GUOMI
```
#### 访问控制安全
```mermaid
graph
subgraph AUTHENTICATION["身份认证"]
direction TB
AUTH1[用户名密码认证]
AUTH2[LDAP集成认证]
AUTH3[Kerberos认证]
AUTH4[证书认证]
end
subgraph AUTHORIZATION["权限控制"]
direction TB
RBAC[基于角色的权限控制<br/>Role-Based Access Control]
RLS[行级安全策略<br/>Row Level Security]
CLS[列级安全控制<br/>Column Level Security]
TENANT[多租户数据隔离<br/>Multi-Tenant Isolation]
end
subgraph AUDITING["审计监控"]
direction TB
AUDIT[操作审计日志<br/>Audit Logging]
MONITOR[实时安全监控<br/>Security Monitoring]
ALERT[安全告警<br/>Security Alert]
REPORT[合规报告<br/>Compliance Report]
end
%% 安全控制流程
AUTHENTICATION -.->|身份验证<br/>授权检查| AUTHORIZATION
AUTHORIZATION -.->|权限监控<br/>操作审计| AUDITING
```
### 网络安全
- **边界防护**：防火墙、入侵检测/防御系统
- **访问控制**：基于角色的访问控制(RBAC)
- **通信安全**：SSL/TLS加密传输，支持国密算法
- **安全监控**：实时监控网络安全状态和异常访问
### 数据安全特性
- **透明数据加密(TDE)**：自动加密存储数据，支持SM4国密算法
- **行级安全(RLS)**：基于用户角色的行级数据访问控制
- **列级权限**：敏感字段的精细化访问控制
- **动态脱敏**：查询时自动脱敏显示敏感信息
- **数据备份安全**：备份文件自动加密，支持增量备份
- **审计日志**：完整记录所有数据库操作，支持合规审计
### 多租户安全隔离
- **逻辑隔离**：基于tenant_id的数据隔离
- **连接隔离**：租户间连接池隔离
- **权限隔离**：租户级别的权限管理
- **资源隔离**：CPU、内存、IO资源限制
### 应用安全
- **身份认证**：多因素认证，支持短信验证码、邮箱验证等
- **授权管理**：细粒度的权限控制，支持菜单、按钮、数据权限
- **安全审计**：用户操作审计，关键业务操作全程记录
- **密码策略**：密码复杂度、定期更换、失败锁定等安全策略
- **会话管理**：会话超时、并发限制、单点登录等
### 接口安全
- **接口认证**：基于JWT Token的接口认证
- **接口授权**：基于角色的接口授权和权限验证
- **接口加密**：敏感数据的加密传输，支持国密算法
- **接口防护**：防重放、防篡改、防SQL注入等安全措施
- **接口限流**：基于IP、用户、应用的多维度限流策略
## 部署架构
系统采用集中部署的模式，基于集团私有云环境进行部署。
### 物理部署
- **生产环境**：高可用集群部署
- 应用服务器：2台或以上服务器，负载均衡
- **OpenGauss数据库集群**：主从+级联备架构，支持自动故障切换
- 缓存服务器：Redis集群
- 文件服务器：冗余存储
- **灾备环境**：异地灾备，定期数据同步，支持OpenGauss流复制
- **测试环境**：用于系统测试和验证，单节点OpenGauss部署
- **开发环境**：用于系统开发和集成测试，单节点OpenGauss部署
### 逻辑部署
- **应用服务器集群**：负责业务逻辑处理，支持水平扩展
- **OpenGauss数据库集群**：负责数据存储和管理，提供高可用保障
- **文件服务器**：负责文档和附件存储，支持分布式存储
- **缓存服务器**：Redis集群提高系统性能
- **负载均衡服务器**：实现请求分发和负载均衡
- **移动应用服务**：提供移动端API服务
- **API网关**：统一的接口管理和控制
### 容器部署
- 基于Docker容器技术实现微服务部署
- 使用Kubernetes进行容器编排和管理
- 支持容器的自动扩缩容和故障转移
- 实现服务的灰度发布和版本控制
## 接口架构
系统提供标准化的接口，实现与外部系统的集成和数据交换。
### 外部接口
- 银行接口：实现与银行系统的对接，支持代扣、托收等功能
- 支付宝/微信接口：支持在线支付功能
- 短信接口：支持短信通知和验证码功能
- 集抄系统接口：实现与智能水表集中抄表系统的对接
- 政务系统接口：实现与地方政务平台和政务APP的对接
- 消火栓系统接口：实现与消火栓系统的对接
- 环卫系统接口：实现与环卫系统的对接
- OA系统接口：实现与OA系统的工作流对接
### 内部接口
- ESB服务接口：系统内部模块间的数据交换
- 报表接口：提供报表数据查询和生成功能
- 查询接口：提供数据查询功能
- 业务处理接口：提供业务处理功能
- 消息通知接口：提供消息推送和通知功能
- 工作流接口：提供工作流处理和状态查询功能
### 接口标准
- 接口协议：RESTful API、WebService、消息队列等
- 数据格式：JSON、XML等
- 接口安全：身份认证、授权、加密传输等
- 接口文档：统一的接口文档和示例代码
- 接口测试：提供接口测试工具和环境
### 接口服务管理
- API网关：统一的接口入口和管理
- 服务注册与发现：服务的自动注册和发现
- 服务路由：根据请求参数进行服务路由
- 服务降级：在服务不可用时提供降级策略
- 服务监控：实时监控服务的可用性和性能
- 本文档仅维护“总体层原则”，不扩展为详细设计文档。
- 若与主文档冲突，必须先修正本文档并在台账登记。
- 修改后至少执行：
- `make validate-file FILE=docs/design/01_Overview/02_System_Architecture.md`
- `make check-links`
- `make validate-mermaid`

221
docs/design/01_Overview/04_System_Diagrams.md
View File

@ -10,115 +10,132 @@ retrieval_priority: P1
# 福建水务营收系统总体图谱
## 文档定位
## 1. 文档定位
本文件用于集中维护总体层图谱，作为 `03_Summary_Design.md` 的配套图示文档。
图示修改需与主文档架构描述同步，避免“图文口径不一致”。
本文件用于集中维护总体层图示，作为 `03_Summary_Design.md` 的图形化补充。
图示中的系统边界与命名口径需与主文档保持一致。
## 系统整体架构图
## 2. 图谱目录
| 图编号 | 图名称 | 对应文档 |
| --- | --- | --- |
| OV-DIAG-01 | 总体分层架构图 | `02_System_Architecture.md` |
| OV-DIAG-02 | 子系统协同关系图 | `03_Summary_Design.md` |
| OV-DIAG-03 | 外部集成边界图 | `03_Summary_Design.md` |
## 3. OV-DIAG-01 总体分层架构图
```mermaid
flowchart TD
%% 数据层
%% 基础服务层
subgraph DL["🗄️ 数据层 - Data Layer"]
G1[("达梦数据库 8.0+<br/>主从架构")]
G2[("Redis 6.0+<br/>分布式缓存")]
G3["MinIO<br/>分布式文件存储"]
end
subgraph ISL["🔧 基础服务层 - Infrastructure Service Layer"]
F1["权限服务<br/>RBAC权限控制"]
F2["工作流服务<br/>Flowable引擎"]
F3["消息服务<br/>异步消息处理"]
F4["文件服务<br/>文档附件管理"]
F5["支付服务<br/>第三方支付集成"]
F6["缓存服务<br/>Redis集群"]
end
%% 业务服务层
subgraph BSL["⚙️ 业务服务层 - Business Service Layer"]
%% 统一平台
subgraph UP["📋 SYS-001 统一平台"]
direction TB
C1["单点登录<br/>SSO"]
C2["系统管理<br/>System Management"]
C3["权限控制<br/>RBAC"]
C4["租户管理<br/>Multi-tenant"]
C5["系统监控<br/>Monitoring"]
end
%% 营收业务系统
subgraph RBS["💧 SYS-002 营收业务系统"]
direction TB
subgraph RBS_CORE["营收核心模块"]
direction LR
D1["营收核心模块<br/>客户资料 • 抄表开账<br/>营业收费 • 账务处理"]
D2["营收扩展模块<br/>发票管理 • 催缴管理<br/>统计分析 • 代收业务"]
D3["表务管理模块<br/>基础管理 • 仓库管理<br/>设备档案管理"]
end
subgraph RBS_EXTENSION["营收扩展模块"]
direction LR
D2["发票管理<br/>Invoice Management"]
D3["催缴管理<br/>Collection Management"]
D4["统计分析<br/>Statistical Analysis"]
D5["代收业务<br/>Collection Business"]
end
D4["报装业务模块<br/>流程管理 • 工程管理<br/>档案管理"]
D5["客户服务模块<br/>账户绑定 • 信息查询<br/>在线缴费 • 电子发票"]
D6["工单管理模块<br/>业务清单 • 上报清单<br/>稽查工单 • 换表工单"]
end
%% 手机抄表APP
subgraph MRA["📱 SYS-003 手机抄表APP"]
E1["核心功能<br/>登录 • 搜索<br/>采集任务管理"]
E2["辅助功能<br/>换表工单 • 其他工单<br/>个人设置"]
end
flowchart TB
subgraph L1["表现层"]
L1_Web["Web 管理端"]
L1_App["手机抄表 APP"]
L1_Channel["微网厅/渠道端"]
end
%% 网关层
subgraph GL["🔒 网关层 - Gateway Layer"]
B1["API网关<br/>Spring Cloud Gateway"]
B2["负载均衡<br/>Nginx集群"]
B3["认证授权<br/>Spring Security + OAuth2.0"]
subgraph L2["接入与网关层"]
L2_GW["API 网关"]
L2_AUTH["统一认证与鉴权"]
end
%% 表现层
subgraph PL["🖥️ 表现层 - Presentation Layer"]
A1["Web管理端<br/>Vue3 + Element Plus"]
A2["移动抄表APP<br/>uni-app"]
A3["微信公众号<br/>微网厅服务"]
A4["支付宝生活号<br/>在线服务"]
subgraph L3["业务服务层"]
L3_SYS001["SYS-001 统一平台"]
L3_SYS002["SYS-002 营收业务系统"]
L3_SYS003["SYS-003 手机抄表 APP 服务"]
L3_SYS004["SYS-004 微网厅系统"]
L3_SYS005["SYS-005 工单管理系统"]
L3_SYS006["SYS-006 表务管理系统"]
L3_SYS007["SYS-007 报装业务系统"]
L3_SYS008["SYS-008 发票服务子系统"]
L3_SYS009["SYS-009 支付与银行结算子系统"]
L3_SYS010["SYS-010 消息服务子系统"]
end
PL --> GL
GL --> BSL
BSL --> DL
DL --> ISL
%% 样式定义
classDef presentationLayer fill:#e1f5fe,stroke:#01579b,stroke-width:2px
classDef gatewayLayer fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
classDef businessLayer fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
classDef infrastructureLayer fill:#fff3e0,stroke:#e65100,stroke-width:2px
classDef dataLayer fill:#fce4ec,stroke:#880e4f,stroke-width:2px
%% 应用样式
class A1,A2,A3,A4 presentationLayer
class B1,B2,B3 gatewayLayer
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
subgraph L4["基础能力层"]
L4_Workflow["工作流能力"]
L4_File["文件与附件能力"]
L4_Monitor["监控与审计能力"]
L4_Adapt["外部集成适配能力"]
end
subgraph L5["数据层"]
L5_DM["达梦数据库 8.0+"]
L5_Redis["Redis 缓存"]
L5_Object["对象存储"]
end
L1 --> L2
L2 --> L3
L3 --> L4
L3 --> L5
```
## 4. OV-DIAG-02 子系统协同关系图
```mermaid
flowchart LR
SYS001["SYS-001 统一平台"]
SYS002["SYS-002 营收业务系统"]
SYS003["SYS-003 手机抄表 APP"]
SYS004["SYS-004 微网厅系统"]
SYS005["SYS-005 工单管理系统"]
SYS006["SYS-006 表务管理系统"]
SYS007["SYS-007 报装业务系统"]
SYS008["SYS-008 发票服务子系统"]
SYS009["SYS-009 支付与银行结算子系统"]
SYS010["SYS-010 消息服务子系统"]
SYS001 --> SYS002
SYS001 --> SYS003
SYS001 --> SYS004
SYS001 --> SYS005
SYS001 --> SYS006
SYS001 --> SYS007
SYS002 --> SYS005
SYS002 --> SYS006
SYS002 --> SYS007
SYS002 --> SYS008
SYS002 --> SYS009
SYS002 --> SYS010
SYS003 --> SYS002
SYS004 --> SYS002
SYS005 --> SYS010
SYS006 --> SYS010
SYS007 --> SYS010
SYS008 --> SYS010
SYS009 --> SYS010
```
## 5. OV-DIAG-03 外部集成边界图
```mermaid
flowchart LR
subgraph Inner["福建水务营收系统"]
Inner_SYS002["SYS-002 营收业务系统"]
Inner_SYS008["SYS-008 发票服务子系统"]
Inner_SYS009["SYS-009 支付与银行结算子系统"]
Inner_SYS010["SYS-010 消息服务子系统"]
end
Ext_Bank["银行系统"]
Ext_Payment["第三方支付平台"]
Ext_Invoice["发票服务商"]
Ext_IoT["物联网/水表平台"]
Ext_Msg["短信/邮件渠道"]
Ext_CA["CA/电子签章平台"]
Inner_SYS009 --> Ext_Bank
Inner_SYS009 --> Ext_Payment
Inner_SYS008 --> Ext_Invoice
Inner_SYS002 --> Ext_IoT
Inner_SYS010 --> Ext_Msg
Inner_SYS008 --> Ext_CA
```
## 6. 图谱维护要求
- 图示只描述总体层信息，不替代正文规则与约束说明。
- 图示命名、子系统编号、数据库口径需与主文档一致。
- 图示改动后必须执行 `make validate-mermaid` 与 `make check-links`。