From 1ed95dbe70af8477bce85b01cd6197641f664d71 Mon Sep 17 00:00:00 2001 From: tangweijie <877588133@qq.com> Date: Wed, 11 Mar 2026 14:59:31 +0800 Subject: [PATCH] docs: rewrite 01_Overview documents with clear boundaries --- .../00_Management/01_Project_Progress.md | 1 + .../design/00_Management/03_Task_Checklist.md | 9 + docs/design/01_Overview/01_System_Overview.md | 348 ++------ .../01_Overview/02_System_Architecture.md | 816 +++--------------- docs/design/01_Overview/04_System_Diagrams.md | 221 ++--- 5 files changed, 320 insertions(+), 1075 deletions(-) diff --git a/docs/design/00_Management/01_Project_Progress.md b/docs/design/00_Management/01_Project_Progress.md index 66d8548..ed4fc71 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/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 文档体系已形成“目录索引 + 检索白名单 + 元数据标准 + 导航索引 + 周检机制 + 自动门禁”闭环；可显著提升检索命中率、减少历史资料干扰、增强跨代理执行一致性与可追溯性 | diff --git a/docs/design/00_Management/03_Task_Checklist.md b/docs/design/00_Management/03_Task_Checklist.md index 8557fd0..924cf37 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/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) diff --git a/docs/design/01_Overview/01_System_Overview.md b/docs/design/01_Overview/01_System_Overview.md index e1f3d3a..d6b5306 100644 --- a/docs/design/01_Overview/01_System_Overview.md +++ b/docs/design/01_Overview/01_System_Overview.md @@ -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` diff --git a/docs/design/01_Overview/02_System_Architecture.md b/docs/design/01_Overview/02_System_Architecture.md index 05ec8fa..59551cf 100644 --- a/docs/design/01_Overview/02_System_Architecture.md +++ b/docs/design/01_Overview/02_System_Architecture.md @@ -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管理端
yudao-ui-admin-vue3] - A2[移动抄表端
uni-app] - A3[客户微信端
微信小程序] - A4[客户支付宝端
支付宝小程序] +flowchart TB + subgraph Layer_Presentation["表现层"] + P_Web["Web 管理端"] + P_App["手机抄表 APP"] + P_Channel["微网厅/渠道端"] end - - subgraph GATEWAY["网关层"] - B1[Nginx负载均衡] - B2[API网关
统一认证/权限控制] + + subgraph Layer_Gateway["接入与网关层"] + G_Api["API 网关"] + G_Auth["统一认证与鉴权"] end - - subgraph APP["应用层"] - C1[营收管理
RuoYi-Vue-Pro] - C2[客户服务
RuoYi-Vue-Pro] - C3[表务管理
RuoYi-Vue-Pro] - C4[统计分析
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[权限服务
Spring Security] - D2[工作流服务
Flowable] - D3[消息服务
Redis MQ] - D4[文件服务
MinIO/OSS] + + subgraph Layer_Infrastructure["基础能力层"] + I_Workflow["工作流能力"] + I_File["文件与附件能力"] + I_Monitor["监控与审计能力"] + I_Integration["外部集成适配能力"] end - - subgraph DATA["数据层"] - E1[(OpenGauss 5.0+
主从架构)] - E2[(Redis 6.0
集群缓存)] - E3[文件存储
分布式存储] + + subgraph Layer_Data["数据层"] + D_DM["达梦数据库 8.0+"] + D_Redis["Redis 缓存"] + D_Object["对象存储"] end - - subgraph EXTERNAL["外部接口"] - F1[银行接口
代扣/托收] - F2[支付接口
微信/支付宝] - F3[短信接口
阿里云/腾讯云] - F4[物联网接口
智能水表] - end - - %% 层级间调用关系 - USER -.->|请求访问| GATEWAY - GATEWAY -.->|负载均衡
路由转发| 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[负载均衡器
Nginx Cluster] - WAF[Web应用防火墙] - end - end - - subgraph APPZONE["应用服务区"] - subgraph "Web服务集群" - WEB1[Web服务器1
8核32G] - WEB2[Web服务器2
8核32G] - end - - subgraph "应用服务集群" - APP1[应用服务器1
16核64G] - APP2[应用服务器2
16核64G] - end - end - - subgraph DATAZONE["数据服务区"] - subgraph "数据库集群" - DB1[OpenGauss主库
32核128G] - DB2[OpenGauss从库
32核128G] - end - - subgraph "缓存集群" - REDIS1[Redis主节点
16核32G] - REDIS2[Redis从节点
16核32G] - REDIS3[Redis哨兵
8核16G] - end - - subgraph "文件存储" - FILE1[文件服务器1
8核32G 10TB] - FILE2[文件服务器2
8核32G 10TB] - end - end - - subgraph MGMT["管理服务区"] - MONITOR[监控服务器
8核16G] - BACKUP[备份服务器
8核32G 20TB] - JUMP[跳板服务器
4核8G] - end - - %% 区域间调用关系 - Internet -.->|外网访问| DMZ - DMZ -.->|负载均衡
安全过滤| APPZONE - APPZONE -.->|数据访问
业务处理| DATAZONE - MGMT -.->|监控管理
备份恢复| DATAZONE - MGMT -.->|系统监控
运维管理| 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
Element Plus UI"] - FE2["Vite + Pinia
Router + Axios"] - end - - subgraph BACKEND["📦 后端技术栈"] - BE1["Spring Boot 3.x
Spring Security"]:::spring - BE2["MyBatis Plus
OpenGauss"]:::db - BE3["Redis缓存
Knife4j文档"]:::cache - end - - subgraph MIDDLEWARE["⚙️ 中间件服务"] - MW1["Nginx负载均衡
Redis集群"] - MW2["Flowable工作流
Quartz定时"] - MW3["MinIO存储
消息队列"] - end - - subgraph MOBILE["📱 移动应用"] - MB1["uni-app跨平台
uView UI"] - MB2["微信/支付宝小程序
H5响应式"] - MB3["GPS定位+NFC
设备接口"] - end - - %% 技术栈间调用关系 - FRONTEND -.->|HTTP请求
API调用| BACKEND - MOBILE -.->|跨平台调用
API集成| BACKEND - BACKEND -.->|服务集成
中间件调用| MIDDLEWARE - - classDef spring fill:#6db33f,color:white - classDef db fill:#f9d27d - classDef cache fill:#b5e6c0 -``` +### 5.2 事务与一致性 -### 系统数据流向图 +- 同步事务优先控制在单子系统内部。 +- 跨系统流程采用“状态驱动 + 补偿机制”的一致性策略。 +- 关键状态变更需具备审计记录与回溯能力。 -```mermaid -flowchart TD - subgraph COLLECT["数据采集层"] - A1[移动抄表APP
数据采集] - A2[智能水表
远程数据] - A3[Web管理端
业务录入] - A4[客户端小程序
用户数据] - A5[外部系统
接口数据] - end - - subgraph ACCESS["数据接入层"] - B1[API网关
数据验证] - B2[数据清洗
格式转换] - B3[消息队列
异步处理] - B4[数据缓存
临时存储] - end - - subgraph PROCESS["业务处理层"] - C1[抄表服务
水量计算] - C2[收费服务
账单生成] - C3[账务服务
财务处理] - C4[工单服务
流程处理] - C5[统计服务
数据分析] - end - - subgraph STORAGE["数据存储层"] - D1[(OpenGauss主库
核心业务数据)] - D2[(OpenGauss从库
查询数据)] - D3[(Redis缓存
热点数据)] - D4[文件存储
附件图片] - D5[(备份库
历史数据)] - end - - subgraph SERVICE["数据服务层"] - E1[查询服务
数据检索] - E2[报表服务
统计分析] - E3[接口服务
对外开放] - E4[推送服务
消息通知] - end - - subgraph PRESENT["数据展现层"] - F1[管理后台
业务操作] - F2[统计大屏
可视化展示] - F3[移动端
现场作业] - F4[客户端
自助服务] - F5[第三方系统
数据集成] - end - - %% 数据流向关系 - COLLECT -.->|数据采集
格式验证| ACCESS - ACCESS -.->|数据接入
清洗转换| PROCESS - PROCESS -.->|业务处理
数据持久化| STORAGE - STORAGE -.->|数据查询
统计分析| SERVICE - SERVICE -.->|数据服务
接口调用| PRESENT - PRESENT -.->|用户反馈
业务交互| 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
水表拍照] - P2[NFC读取
水表标签] - P3[GPS定位
抄表轨迹] - P4[扫码API
二维码扫描] - end - - subgraph NETWORK["网络通信"] - Q1[uni.request
HTTP请求] - Q2[WebSocket
实时通信] - Q3[文件上传
图片处理] - end - - %% 移动架构调用关系 - FRAMEWORK -.->|UI渲染
组件调用| UIKIT - FRAMEWORK -.->|设备调用
原生能力| DEVICE - FRAMEWORK -.->|网络通信
数据交互| 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 -.->|请求路由
认证授权| BUSINESS - BUSINESS -.->|服务调用| SUPPORT - BUSINESS -.->|数据访问| DATA - SUPPORT -.->|数据访问| DATA -``` - -### 服务治理架构 - -```mermaid -graph TB - subgraph REGISTRY["服务发现与注册"] - NACOS[Nacos注册中心
服务注册/发现/配置] - end - - subgraph MESH["服务网格层"] - subgraph BALANCE["负载均衡"] - LB[Ribbon负载均衡
客户端负载均衡] - FEIGN[OpenFeign
服务间调用] - end - - subgraph PROTECTION["容错保护"] - CB[Sentinel熔断器
流量控制/熔断降级] - RETRY[重试机制
失败重试] - end - - subgraph TRACING["链路追踪"] - TRACE[SkyWalking
分布式链路追踪] - METRIC[Micrometer
指标收集] - end - end - - subgraph CONFIG_MGMT["配置管理"] - CONFIG[Nacos Config
配置中心] - SECRET[配置加密
敏感信息保护] - end - - subgraph MONITORING["监控告警"] - MONITOR[Spring Boot Admin
应用监控] - ALERT[告警系统
异常通知] - LOG[ELK日志系统
日志聚合分析] - end - - %% 服务治理调用关系 - REGISTRY -.->|服务发现
配置下发| MESH - MESH -.->|配置获取
服务注册| CONFIG_MGMT - MESH -.->|监控数据
链路追踪| MONITORING -``` - -### 应用模块设计 - -系统应用架构基于业务域划分，主要包括以下核心应用模块： - -#### 统一平台 -- 单点登录：统一认证入口，支持多种登录方式 -- 系统管理：组织机构、员工管理、角色权限管理、菜单配置等 -- 流程节点提醒：工作流节点到期和状态变更提醒 - -#### 营收系统 -- 系统管理：水价管理、用户档案管理、更名过户管理等 -- 抄表开账：册本管理、抄表录入、复核开账等 -- 收费管理：柜台收费、特殊开账、柜台结账、批量缴费等 -- 账务处理：预存调整、未销调整、已销调整、分账调整等 -- 发票管理：发票查询、发票开具、电子发票等 -- 代收业务：实时收费、银行代扣、银行托收等 - -#### 客户服务 -- 微信、支付宝服务窗：账户绑定、用水查询、在线缴费等 -- 历史账单：账单查询、用水分析、账单推送等 -- 电子发票：发票申请、发票查询、发票下载等 -- 营业网点：网点查询、网点导航、业务指南等 - -#### 表务系统 -- 表务工单：换表工单、移表工单、拆表工单、复装工单等 -- 表务仓库：新表入库、水表检定、水表领用、水表出库等 -- 水表参数与基础信息：水表厂家管理、水表型号管理等 -- 物联网对接与数据同步：厂家设备信息管理、远程抄表数据同步等 - -#### 报装管理 -- 报装流程：报装申请、方案设计、合同签订、施工管理等 -- 一户一表管理：改造计划、改造实施、用户转换等 - -#### 统计分析 -- 报表查询：标准报表、自定义报表、报表导出打印等 -- 欠费查询：欠费情况统计、欠费用户明细、欠费分析等 -- 缴费记录：缴费情况统计、缴费明细查询、缴费趋势分析等 -- 用水分析：用水量统计、用水趋势分析、异常用水分析等 - -## 数据架构 - -系统数据架构基于客户关系数据库为核心和基础，实现客户全生命周期管理。 - -### OpenGauss数据库架构 - -#### 主从高可用架构 - -```mermaid -graph - subgraph DBCLUSTER["OpenGauss高可用集群"] - MASTER[("OpenGauss主库
Primary Node
读写操作")] - STANDBY[("OpenGauss备库
Standby Node
只读操作")] - CASCADE[("OpenGauss级联备库
Cascade Standby
负载分担")] - - MASTER -.->|流复制| STANDBY - STANDBY -.->|级联复制| CASCADE - end - - subgraph APPLAYER["应用层"] - APP1[应用服务器1] - APP2[应用服务器2] - APP3[应用服务器3] - end - - subgraph POOLING["连接池"] - POOL[连接池
HikariCP
Druid] - end - - subgraph MANAGEMENT["监控管理"] - MON[OpenGauss Monitor
性能监控] - BACKUP[定时备份
gs_backup] - end - - %% 高可用架构调用关系 - APPLAYER -.->|连接请求
负载均衡| POOLING - POOLING -.->|数据访问
读写分离| DBCLUSTER - MANAGEMENT -.->|监控管理
备份恢复| DBCLUSTER -``` - -#### 分片存储架构 - -```mermaid -graph TB - subgraph DISTRIBUTED["OpenGauss分布式架构"] - subgraph COORDINATOR["协调节点"] - CN1[协调节点1
Coordinator Node] - CN2[协调节点2
Coordinator Node] - end - - subgraph DATANODE1["数据节点组1"] - DN1_1[数据节点1-主
Datanode Primary] - DN1_2[数据节点1-备
Datanode Standby] - DN1_1 -.->|主备同步| DN1_2 - end - - subgraph DATANODE2["数据节点组2"] - DN2_1[数据节点2-主
Datanode Primary] - DN2_2[数据节点2-备
Datanode Standby] - DN2_1 -.->|主备同步| DN2_2 - end - - subgraph GTM_CLUSTER["GTM节点"] - GTM[全局事务管理器
GTM Master] - GTM_S[GTM备节点
GTM Standby] - GTM -.->|备份| GTM_S - end - end - - %% 分布式架构调用关系 - COORDINATOR -.->|分片路由
查询协调| DATANODE1 - COORDINATOR -.->|分片路由
查询协调| DATANODE2 - COORDINATOR -.->|事务管理
全局一致性| 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[传输层加密
SSL/TLS/国密SM] - L2[存储层加密
TDE透明数据加密] - L3[字段级加密
敏感字段加密] - L4[备份加密
备份文件加密] - end - - subgraph KEYMANAGE["密钥管理"] - direction TB - KMS[密钥管理系统
Key Management] - HSM[硬件安全模块
Hardware Security] - ROT[密钥轮换
Key Rotation] - end - - subgraph GUOMI["国密算法"] - direction TB - SM2[SM2椭圆曲线
非对称加密] - SM3[SM3哈希算法
消息摘要] - SM4[SM4分组密码
对称加密] - end - - %% 安全层级调用关系 - ENCRYPT -.->|密钥依赖
加密管理| KEYMANAGE - KEYMANAGE -.->|算法调用
国密支持| GUOMI -``` - -#### 访问控制安全 - -```mermaid -graph - subgraph AUTHENTICATION["身份认证"] - direction TB - AUTH1[用户名密码认证] - AUTH2[LDAP集成认证] - AUTH3[Kerberos认证] - AUTH4[证书认证] - end - - subgraph AUTHORIZATION["权限控制"] - direction TB - RBAC[基于角色的权限控制
Role-Based Access Control] - RLS[行级安全策略
Row Level Security] - CLS[列级安全控制
Column Level Security] - TENANT[多租户数据隔离
Multi-Tenant Isolation] - end - - subgraph AUDITING["审计监控"] - direction TB - AUDIT[操作审计日志
Audit Logging] - MONITOR[实时安全监控
Security Monitoring] - ALERT[安全告警
Security Alert] - REPORT[合规报告
Compliance Report] - end - - %% 安全控制流程 - AUTHENTICATION -.->|身份验证
授权检查| AUTHORIZATION - AUTHORIZATION -.->|权限监控
操作审计| 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` diff --git a/docs/design/01_Overview/04_System_Diagrams.md b/docs/design/01_Overview/04_System_Diagrams.md index 8d5690f..0ebccc1 100644 --- a/docs/design/01_Overview/04_System_Diagrams.md +++ b/docs/design/01_Overview/04_System_Diagrams.md @@ -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+
主从架构")] - G2[("Redis 6.0+
分布式缓存")] - G3["MinIO
分布式文件存储"] - end - subgraph ISL["🔧 基础服务层 - Infrastructure Service Layer"] - F1["权限服务
RBAC权限控制"] - F2["工作流服务
Flowable引擎"] - F3["消息服务
异步消息处理"] - F4["文件服务
文档附件管理"] - F5["支付服务
第三方支付集成"] - F6["缓存服务
Redis集群"] - end - - %% 业务服务层 - subgraph BSL["⚙️ 业务服务层 - Business Service Layer"] - %% 统一平台 - subgraph UP["📋 SYS-001 统一平台"] - direction TB - C1["单点登录
SSO"] - C2["系统管理
System Management"] - C3["权限控制
RBAC"] - C4["租户管理
Multi-tenant"] - C5["系统监控
Monitoring"] - end - - %% 营收业务系统 - subgraph RBS["💧 SYS-002 营收业务系统"] - direction TB - subgraph RBS_CORE["营收核心模块"] - direction LR - D1["营收核心模块
客户资料 • 抄表开账
营业收费 • 账务处理"] - D2["营收扩展模块
发票管理 • 催缴管理
统计分析 • 代收业务"] - D3["表务管理模块
基础管理 • 仓库管理
设备档案管理"] - end - subgraph RBS_EXTENSION["营收扩展模块"] - direction LR - D2["发票管理
Invoice Management"] - D3["催缴管理
Collection Management"] - D4["统计分析
Statistical Analysis"] - D5["代收业务
Collection Business"] - end - - D4["报装业务模块
流程管理 • 工程管理
档案管理"] - D5["客户服务模块
账户绑定 • 信息查询
在线缴费 • 电子发票"] - D6["工单管理模块
业务清单 • 上报清单
稽查工单 • 换表工单"] - end - - %% 手机抄表APP - subgraph MRA["📱 SYS-003 手机抄表APP"] - E1["核心功能
登录 • 搜索
采集任务管理"] - E2["辅助功能
换表工单 • 其他工单
个人设置"] - end +flowchart TB + subgraph L1["表现层"] + L1_Web["Web 管理端"] + L1_App["手机抄表 APP"] + L1_Channel["微网厅/渠道端"] end - %% 网关层 - subgraph GL["🔒 网关层 - Gateway Layer"] - B1["API网关
Spring Cloud Gateway"] - B2["负载均衡
Nginx集群"] - B3["认证授权
Spring Security + OAuth2.0"] + subgraph L2["接入与网关层"] + L2_GW["API 网关"] + L2_AUTH["统一认证与鉴权"] end - %% 表现层 - subgraph PL["🖥️ 表现层 - Presentation Layer"] - A1["Web管理端
Vue3 + Element Plus"] - A2["移动抄表APP
uni-app"] - A3["微信公众号
微网厅服务"] - A4["支付宝生活号
在线服务"] + 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`。