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

初始化提交：添加福建水务业务系统初步设计文档

Browse Source
This commit is contained in:
tangweijie 2025-05-08 15:07:03 +08:00
commit 60a217da4f
22 changed files with 2967 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
.gitignore vendored Normal file
View File

@ -0,0 +1,17 @@
# 系统文件
.DS_Store
Thumbs.db
# 编辑器文件
.vscode/
.idea/
*.swp
*.swo
# 临时文件
*.tmp
*.bak
*~
# 其他
.cursor/

18
README.md Normal file
View File

@ -0,0 +1,18 @@
# 福建水务业务系统初步设计文档
本仓库包含福建水务业务系统的初步设计文档，包括系统架构、模块设计、接口设计、数据库设计、部署设计等内容。
## 文档目录
- [设计计划](./water_biz_design_plan.md)
- [文档目录](./water_biz_doc_toc.md)
- [系统概述](./water_biz_summary.md)
- [系统架构](./water_biz_system_architecture.md)
- [模块设计](./water_biz_module_design.md)
- [接口设计](./water_biz_interface_design.md)
- [数据库设计](./water_biz_database_design.md)
- [部署设计](./water_biz_deployment_design.md)
## 版本信息
初始版本：1.0.0

BIN
ori_doc/【功能需求清单】水务营收系统 _英迈 0428.xlsx Normal file
View File

Binary file not shown.

BIN
ori_doc/新营收系统需求相关材料/202-营业收费管理系统需求规格说明书 - 需求+设计.doc Normal file
View File

Binary file not shown.

BIN
ori_doc/新营收系统需求相关材料/202-营业收费管理系统需求规格说明书20240412.doc Normal file
View File

Binary file not shown.

BIN
ori_doc/新营收系统需求相关材料/202-营业收费管理系统需求规格说明书20240415.doc Normal file
View File

Binary file not shown.

BIN
ori_doc/新营收系统需求相关材料/202-设备管理系统需求规格说明书.doc Normal file
View File

Binary file not shown.

BIN
ori_doc/新营收系统需求相关材料/物联网集抄及营收平台关于水表数据交互需求及接口规范V1.2-20220921.docx Normal file
View File

Binary file not shown.

BIN
ori_doc/新营收系统需求相关材料/福建水投PDA操作手册.docx Normal file
View File

Binary file not shown.

BIN
ori_doc/新营收系统需求相关材料/福建水投微网厅操作手册.docx Normal file
View File

Binary file not shown.

BIN
ori_doc/新营收系统需求相关材料/福建水投营收系统操作手册.docx Normal file
View File

Binary file not shown.

BIN
ori_doc/新营收系统需求相关材料/营收系统_用户操作手册.docx Normal file
View File

Binary file not shown.

BIN
ori_doc/新营收系统需求相关材料/营收系统_详细设计说明书.docx Normal file
View File

Binary file not shown.

BIN
ori_doc/新营收系统需求相关材料/营收系统_需求规格说明书.docx Normal file
View File

Binary file not shown.

272
water_biz_database_design.md Normal file
View File

@ -0,0 +1,272 @@
# 福建水务营收系统数据库设计
## 一、数据库设计概述
福建水务营收系统采用关系型数据库MySQL作为主要存储系统，结合Redis缓存提升性能。数据库设计遵循标准化原则，确保数据完整性、一致性和高效性。
## 二、数据库架构设计
### 1. 数据库架构图
```mermaid
graph TD
App[应用服务] --> Master[(主数据库)]
Master --> Slave1[(从数据库1)]
Master --> Slave2[(从数据库2)]
App --> Redis[(Redis缓存)]
subgraph 主从复制架构
Master
Slave1
Slave2
end
subgraph 缓存层
Redis
end
```
### 2. 主要特点
- **读写分离**: 主库负责写操作，从库负责读操作，提高系统吞吐量
- **数据冗余**: 通过主从复制实现数据冗余，提高可用性
- **缓存加速**: 使用Redis缓存热点数据，减轻数据库压力
- **分库设计**: 按业务功能划分为多个逻辑库，便于管理和维护
- **分表策略**: 对大表采用分表策略，提高查询效率
## 三、数据模型设计
### 1. 实体关系图(ER图)
```mermaid
erDiagram
SYS_USER ||--o{ SYS_USER_ROLE : has
SYS_ROLE ||--o{ SYS_USER_ROLE : assigned_to
SYS_ROLE ||--o{ SYS_ROLE_MENU : has
SYS_MENU ||--o{ SYS_ROLE_MENU : assigned_to
WATER_CUSTOMER ||--o{ WATER_METER : owns
WATER_METER ||--o{ WATER_METER_READING : has
WATER_METER_READING ||--o{ WATER_BILLING : generates
WATER_CUSTOMER ||--o{ WATER_BILLING : billed
WATER_BILLING ||--o{ WATER_PAYMENT : paid_by
WATER_PAYMENT ||--o{ WATER_INVOICE : has
WATER_PRICE ||--o{ WATER_BILLING : applied_to
WATER_EMPLOYEE ||--o{ WATER_METER_READING : records
WATER_SERVICE_POINT ||--o{ WATER_EMPLOYEE : works_at
```
### 2. 数据库表结构设计
#### 2.1 系统管理模块
##### SYS_USER (用户表)
| 字段名 | 数据类型 | 长度 | 是否必填 | 主键 | 说明 |
|-------|---------|------|---------|-----|------|
| id | bigint | 20 | 是 | 是 | 用户ID |
| username | varchar | 50 | 是 | 否 | 用户名 |
| password | varchar | 100 | 是 | 否 | 密码 |
| nickname | varchar | 50 | 否 | 否 | 昵称 |
| dept_id | bigint | 20 | 否 | 否 | 部门ID |
| phone | varchar | 11 | 否 | 否 | 手机号 |
| email | varchar | 50 | 否 | 否 | 邮箱 |
| gender | tinyint | 4 | 否 | 否 | 性别 |
| avatar | varchar | 100 | 否 | 否 | 头像 |
| status | tinyint | 4 | 是 | 否 | 状态(0正常,1停用) |
| login_ip | varchar | 50 | 否 | 否 | 最后登录IP |
| login_date | datetime | - | 否 | 否 | 最后登录时间 |
| creator | varchar | 64 | 否 | 否 | 创建者 |
| create_time | datetime | - | 是 | 否 | 创建时间 |
| updater | varchar | 64 | 否 | 否 | 更新者 |
| update_time | datetime | - | 是 | 否 | 更新时间 |
| deleted | bit | 1 | 是 | 否 | 是否删除 |
##### SYS_ROLE (角色表)
| 字段名 | 数据类型 | 长度 | 是否必填 | 主键 | 说明 |
|-------|---------|------|---------|-----|------|
| id | bigint | 20 | 是 | 是 | 角色ID |
| name | varchar | 30 | 是 | 否 | 角色名称 |
| code | varchar | 100 | 是 | 否 | 角色编码 |
| sort | int | 11 | 是 | 否 | 显示顺序 |
| status | tinyint | 4 | 是 | 否 | 状态(0正常,1停用) |
| type | tinyint | 4 | 是 | 否 | 角色类型 |
| remark | varchar | 500 | 否 | 否 | 备注 |
| creator | varchar | 64 | 否 | 否 | 创建者 |
| create_time | datetime | - | 是 | 否 | 创建时间 |
| updater | varchar | 64 | 否 | 否 | 更新者 |
| update_time | datetime | - | 是 | 否 | 更新时间 |
| deleted | bit | 1 | 是 | 否 | 是否删除 |
#### 2.2 客户水表模块
##### WATER_CUSTOMER (客户表)
| 字段名 | 数据类型 | 长度 | 是否必填 | 主键 | 说明 |
|-------|---------|------|---------|-----|------|
| id | bigint | 20 | 是 | 是 | 客户ID |
| customer_no | varchar | 50 | 是 | 否 | 客户编号 |
| name | varchar | 100 | 是 | 否 | 客户名称 |
| type | tinyint | 4 | 是 | 否 | 客户类型(1居民,2企业,3政府,4其它) |
| contact | varchar | 50 | 否 | 否 | 联系人 |
| phone | varchar | 20 | 否 | 否 | 联系电话 |
| address | varchar | 200 | 否 | 否 | 地址 |
| id_card | varchar | 20 | 否 | 否 | 身份证号 |
| bank_account | varchar | 50 | 否 | 否 | 银行账号 |
| bank_name | varchar | 100 | 否 | 否 | 开户行 |
| status | tinyint | 4 | 是 | 否 | 状态(0正常,1冻结) |
| creator | varchar | 64 | 否 | 否 | 创建者 |
| create_time | datetime | - | 是 | 否 | 创建时间 |
| updater | varchar | 64 | 否 | 否 | 更新者 |
| update_time | datetime | - | 是 | 否 | 更新时间 |
| deleted | bit | 1 | 是 | 否 | 是否删除 |
##### WATER_METER (水表表)
| 字段名 | 数据类型 | 长度 | 是否必填 | 主键 | 说明 |
|-------|---------|------|---------|-----|------|
| id | bigint | 20 | 是 | 是 | 水表ID |
| meter_no | varchar | 50 | 是 | 否 | 水表编号 |
| customer_id | bigint | 20 | 是 | 否 | 客户ID |
| meter_type | tinyint | 4 | 是 | 否 | 水表类型(1普通,2IC卡,3智能) |
| caliber | varchar | 20 | 否 | 否 | 口径规格 |
| install_date | date | - | 否 | 否 | 安装日期 |
| initial_reading | decimal | 10,2 | 是 | 否 | 起始读数 |
| current_reading | decimal | 10,2 | 是 | 否 | 当前读数 |
| install_address | varchar | 200 | 否 | 否 | 安装地址 |
| status | tinyint | 4 | 是 | 否 | 状态(0正常,1故障,2停用) |
| reading_cycle | tinyint | 4 | 是 | 否 | 抄表周期(1月,2季,3年) |
| description | varchar | 500 | 否 | 否 | 备注说明 |
| creator | varchar | 64 | 否 | 否 | 创建者 |
| create_time | datetime | - | 是 | 否 | 创建时间 |
| updater | varchar | 64 | 否 | 否 | 更新者 |
| update_time | datetime | - | 是 | 否 | 更新时间 |
| deleted | bit | 1 | 是 | 否 | 是否删除 |
#### 2.3 抄表收费模块
##### WATER_METER_READING (抄表记录表)
| 字段名 | 数据类型 | 长度 | 是否必填 | 主键 | 说明 |
|-------|---------|------|---------|-----|------|
| id | bigint | 20 | 是 | 是 | 抄表记录ID |
| meter_id | bigint | 20 | 是 | 否 | 水表ID |
| reading_date | date | - | 是 | 否 | 抄表日期 |
| reading | decimal | 10,2 | 是 | 否 | 本次读数 |
| last_reading | decimal | 10,2 | 是 | 否 | 上次读数 |
| water_usage | decimal | 10,2 | 是 | 否 | 用水量 |
| reading_type | tinyint | 4 | 是 | 否 | 抄表类型(1人工,2远传,3用户自报) |
| reader_id | bigint | 20 | 否 | 否 | 抄表员ID |
| status | tinyint | 4 | 是 | 否 | 状态(0正常,1异常,2已确认) |
| remark | varchar | 500 | 否 | 否 | 备注 |
| photo_url | varchar | 255 | 否 | 否 | 水表照片URL |
| creator | varchar | 64 | 否 | 否 | 创建者 |
| create_time | datetime | - | 是 | 否 | 创建时间 |
| updater | varchar | 64 | 否 | 否 | 更新者 |
| update_time | datetime | - | 是 | 否 | 更新时间 |
| deleted | bit | 1 | 是 | 否 | 是否删除 |
##### WATER_BILLING (水费账单表)
| 字段名 | 数据类型 | 长度 | 是否必填 | 主键 | 说明 |
|-------|---------|------|---------|-----|------|
| id | bigint | 20 | 是 | 是 | 账单ID |
| bill_no | varchar | 50 | 是 | 否 | 账单编号 |
| customer_id | bigint | 20 | 是 | 否 | 客户ID |
| meter_id | bigint | 20 | 是 | 否 | 水表ID |
| meter_reading_id | bigint | 20 | 是 | 否 | 抄表记录ID |
| billing_period | varchar | 20 | 是 | 否 | 账单周期(yyyyMM) |
| billing_date | date | - | 是 | 否 | 账单日期 |
| water_usage | decimal | 10,2 | 是 | 否 | 用水量 |
| water_fee | decimal | 10,2 | 是 | 否 | 水费金额 |
| sewage_fee | decimal | 10,2 | 是 | 否 | 污水处理费 |
| other_fee | decimal | 10,2 | 否 | 否 | 其他费用 |
| total_amount | decimal | 10,2 | 是 | 否 | 总金额 |
| due_date | date | - | 是 | 否 | 缴费截止日期 |
| status | tinyint | 4 | 是 | 否 | 状态(0未缴费,1已缴费,2部分缴费,3已逾期) |
| remark | varchar | 500 | 否 | 否 | 备注 |
| creator | varchar | 64 | 否 | 否 | 创建者 |
| create_time | datetime | - | 是 | 否 | 创建时间 |
| updater | varchar | 64 | 否 | 否 | 更新者 |
| update_time | datetime | - | 是 | 否 | 更新时间 |
| deleted | bit | 1 | 是 | 否 | 是否删除 |
## 四、数据库优化设计
### 1. 索引设计策略
- **主键索引**: 每个表都有自增主键
- **外键索引**: 对引用外键的字段创建索引
- **唯一索引**: 对唯一性字段创建唯一索引
- **复合索引**: 对常用查询条件组合创建复合索引
- **覆盖索引**: 针对高频查询设计覆盖索引减少回表操作
### 2. 分表策略
针对大表采用如下分表策略:
- **水表读数表(WATER_METER_READING)**: 按年份分表，如WATER_METER_READING_2023
- **水费账单表(WATER_BILLING)**: 按年份分表，如WATER_BILLING_2023
- **支付记录表(WATER_PAYMENT)**: 按年份分表，如WATER_PAYMENT_2023
- **系统日志表(SYS_OPERATE_LOG)**: 按月份分表，如SYS_OPERATE_LOG_202305
### 3. 缓存策略
采用Redis缓存以下数据:
- **系统字典**: 缓存系统字典数据，减少数据库查询
- **用户权限**: 缓存用户权限数据，提高权限验证效率
- **热点数据**: 缓存常用查询结果，如水价信息、客户基本信息
- **计数器**: 缓存计数器数据，如未读消息数、待办任务数
## 五、数据库安全设计
### 1. 访问控制
- **最小权限原则**: 应用连接数据库账号仅分配必要的操作权限
- **账号隔离**: 按模块分配不同的数据库账号
- **IP限制**: 限制数据库服务器访问IP
- **加密连接**: 使用SSL/TLS加密数据库连接
### 2. 数据加密
- **敏感数据加密**: 对身份证号、银行账号等敏感信息进行加密存储
- **传输加密**: 数据传输过程加密
- **密码加盐哈希**: 用户密码采用加盐哈希后存储
### 3. 审计日志
- **操作审计**: 记录数据库关键操作日志
- **登录审计**: 记录数据库登录日志
- **变更审计**: 记录重要数据变更日志
## 六、数据备份与恢复
### 1. 备份策略
- **全量备份**: 每天凌晨进行一次全量备份
- **增量备份**: 每小时进行一次增量备份
- **归档日志**: 开启binlog日志，支持按时间点恢复
- **备份校验**: 定期检查备份数据完整性
### 2. 恢复策略
- **即时恢复**: 支持基于binlog的即时点恢复
- **快速恢复**: 设计快速恢复方案，明确恢复步骤和责任人
- **恢复演练**: 定期进行数据恢复演练，验证备份有效性
## 七、数据库监控与维护
### 1. 性能监控
- **指标监控**: CPU使用率、内存使用、磁盘IO、连接数等
- **慢查询分析**: 监控并分析慢查询日志
- **资源使用分析**: 分析数据库资源使用情况
### 2. 定期维护
- **碎片整理**: 定期进行表碎片整理
- **统计信息更新**: 定期更新统计信息
- **参数优化**: 根据运行情况优化数据库参数

745
water_biz_deployment_design.md Normal file
View File

@ -0,0 +1,745 @@
# 福建水务营收系统部署运维设计
## 一、部署架构设计
### 1. 总体部署架构
福建水务营收系统采用分层部署架构，确保系统的高可用性、可扩展性和安全性。系统部署架构如下图所示：
```mermaid
graph TD
subgraph 接入层
LB1[负载均衡器-主]
LB2[负载均衡器-备]
end
subgraph Web应用层
WEB1[Web服务器1]
WEB2[Web服务器2]
WEB3[Web服务器3]
end
subgraph 应用服务层
APP1[应用服务器1]
APP2[应用服务器2]
APP3[应用服务器3]
end
subgraph 数据存储层
subgraph MySQL集群
MasterDB[(主数据库)]
SlaveDB1[(从数据库1)]
SlaveDB2[(从数据库2)]
end
subgraph Redis集群
RedisMaster[(Redis主节点)]
RedisSlave1[(Redis从节点1)]
RedisSlave2[(Redis从节点2)]
end
subgraph 文件存储
MinIO1[MinIO节点1]
MinIO2[MinIO节点2]
end
end
LB1 --> WEB1
LB1 --> WEB2
LB1 --> WEB3
LB2 --> WEB1
LB2 --> WEB2
LB2 --> WEB3
WEB1 --> APP1
WEB1 --> APP2
WEB1 --> APP3
WEB2 --> APP1
WEB2 --> APP2
WEB2 --> APP3
WEB3 --> APP1
WEB3 --> APP2
WEB3 --> APP3
APP1 --> MasterDB
APP1 --> SlaveDB1
APP1 --> SlaveDB2
APP1 --> RedisMaster
APP1 --> RedisSlave1
APP1 --> RedisSlave2
APP1 --> MinIO1
APP1 --> MinIO2
APP2 --> MasterDB
APP2 --> SlaveDB1
APP2 --> SlaveDB2
APP2 --> RedisMaster
APP2 --> RedisSlave1
APP2 --> RedisSlave2
APP2 --> MinIO1
APP2 --> MinIO2
APP3 --> MasterDB
APP3 --> SlaveDB1
APP3 --> SlaveDB2
APP3 --> RedisMaster
APP3 --> RedisSlave1
APP3 --> RedisSlave2
APP3 --> MinIO1
APP3 --> MinIO2
MasterDB --> SlaveDB1
MasterDB --> SlaveDB2
RedisMaster --> RedisSlave1
RedisMaster --> RedisSlave2
```
### 2. 物理部署方案
#### 2.1 硬件配置要求
| 服务器类型 | 数量 | CPU | 内存 | 存储 | 网络 | 用途 |
|-----------|------|-----|------|------|------|------|
| 负载均衡服务器 | 2 | 8核 | 16GB | 200GB SSD | 双千兆网卡 | 负载均衡、反向代理 |
| Web服务器 | 3 | 16核 | 32GB | 200GB SSD | 千兆网卡 | 部署前端应用 |
| 应用服务器 | 3 | 16核 | 64GB | 500GB SSD | 千兆网卡 | 部署后端应用 |
| 数据库服务器 | 3 | 32核 | 128GB | 2TB SSD RAID10 | 千兆网卡 | 部署MySQL数据库 |
| 缓存服务器 | 3 | 16核 | 64GB | 500GB SSD | 千兆网卡 | 部署Redis缓存 |
| 存储服务器 | 2 | 16核 | 32GB | 10TB RAID5 | 千兆网卡 | 文件存储 |
| 监控服务器 | 1 | 8核 | 16GB | 500GB SSD | 千兆网卡 | 运行监控系统 |
| 备份服务器 | 1 | 8核 | 16GB | 20TB RAID6 | 千兆网卡 | 数据备份 |
#### 2.2 网络拓扑
```mermaid
graph TD
Internet((互联网)) --> FW[防火墙]
FW --> DMZ{DMZ区域}
DMZ --> LB[负载均衡器]
LB --> Web{Web服务区}
Web --> App{应用服务区}
App --> DB{数据库区}
App --> Cache{缓存区}
App --> Storage{存储区}
```
#### 2.3 安全区域划分
- **互联网区域**: 外部用户访问区域
- **DMZ区域**: 部署负载均衡器和反向代理服务器
- **Web服务区**: 部署Web服务器
- **应用服务区**: 部署应用服务器
- **数据库区**: 部署数据库服务器
- **缓存区**: 部署缓存服务器
- **存储区**: 部署文件存储服务器
## 二、软件部署方案
### 1. 软件环境配置
#### 1.1 操作系统配置
- **操作系统**: CentOS 8.x / Ubuntu 20.04 LTS
- **内核参数优化**:
```
net.ipv4.tcp_max_syn_backlog = 8192
net.core.somaxconn = 4096
net.ipv4.tcp_fin_timeout = 30
net.ipv4.tcp_keepalive_time = 1200
vm.swappiness = 10
```
#### 1.2 Web服务器配置
- **软件**: Nginx 1.20+
- **配置要点**:
- 启用HTTP/2协议
- 启用GZIP压缩
- 配置SSL证书
- 配置反向代理
- 静态资源缓存策略
#### 1.3 应用服务器配置
- **软件**: JDK 11+, Spring Boot 2.7.x
- **配置要点**:
- JVM参数优化: `-Xms4g -Xmx4g -XX:+UseG1GC`
- 应用配置参数化
- 配置健康检查接口
- 配置日志输出级别
#### 1.4 数据库服务器配置
- **软件**: MySQL 8.0+
- **配置要点**:
- 主从复制配置
- 缓冲池优化
- 慢查询日志配置
- 备份策略配置
#### 1.5 缓存服务器配置
- **软件**: Redis 6.0+
- **配置要点**:
- 持久化配置
- 内存管理策略
- 主从复制配置
- 密码认证
### 2. 部署流程
#### 2.1 准备阶段
1. 服务器初始化
- 操作系统安装与配置
- 网络配置
- 安全配置（防火墙、SELinux等）
2. 基础软件安装
- 安装JDK
- 安装Nginx
- 安装MySQL
- 安装Redis
- 安装MinIO
#### 2.2 应用部署阶段
1. 前端部署
- 构建前端项目
- 将构建产物部署到Web服务器
- 配置Nginx虚拟主机
2. 后端部署
- 构建后端项目
- 配置数据库连接
- 配置Redis连接
- 配置MinIO连接
- 部署JAR包到应用服务器
3. 数据库初始化
- 创建数据库
- 导入初始数据
- 配置数据库账户权限
#### 2.3 验证阶段
1. 功能验证
- 用户登录验证
- 核心业务流程验证
- 外部系统接口验证
2. 性能验证
- 并发性能测试
- 响应时间测试
- 数据库性能测试
## 三、容器化部署方案
### 1. Docker容器配置
#### 1.1 容器镜像设计
- **前端镜像**: 基于Nginx，包含前端静态资源
- **后端镜像**: 基于OpenJDK，包含后端JAR包
- **数据库镜像**: 基于MySQL官方镜像
- **缓存镜像**: 基于Redis官方镜像
#### 1.2 容器编排设计
使用Docker Compose进行容器编排，示例配置文件:
```yaml
version: '3'
services:
nginx:
image: nginx:1.20
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx/conf:/etc/nginx/conf.d
- ./nginx/ssl:/etc/nginx/ssl
- ./nginx/html:/usr/share/nginx/html
networks:
- frontend-network
depends_on:
- backend
backend:
image: water-biz-backend:1.0
environment:
- SPRING_PROFILES_ACTIVE=prod
- SPRING_DATASOURCE_URL=jdbc:mysql://mysql:3306/water_biz
- SPRING_REDIS_HOST=redis
volumes:
- ./logs:/app/logs
networks:
- frontend-network
- backend-network
depends_on:
- mysql
- redis
mysql:
image: mysql:8.0
environment:
- MYSQL_ROOT_PASSWORD=secret
- MYSQL_DATABASE=water_biz
- MYSQL_USER=water_biz
- MYSQL_PASSWORD=water_biz_pwd
volumes:
- mysql-data:/var/lib/mysql
- ./mysql/init:/docker-entrypoint-initdb.d
networks:
- backend-network
redis:
image: redis:6.0
command: redis-server --requirepass redis_pwd
volumes:
- redis-data:/data
networks:
- backend-network
networks:
frontend-network:
backend-network:
volumes:
mysql-data:
redis-data:
```
### 2. Kubernetes部署方案
#### 2.1 K8s部署架构
```mermaid
graph TD
subgraph Kubernetes集群
Ingress[Ingress控制器]
subgraph 前端命名空间
FrontSVC[前端服务]
FrontPod1[前端Pod1]
FrontPod2[前端Pod2]
FrontPod3[前端Pod3]
end
subgraph 后端命名空间
BackSVC[后端服务]
BackPod1[后端Pod1]
BackPod2[后端Pod2]
BackPod3[后端Pod3]
end
subgraph 数据库命名空间
MySQLSVC[MySQL服务]
MySQLSTS[MySQL StatefulSet]
MySQLPod1[MySQL主节点]
MySQLPod2[MySQL从节点1]
MySQLPod3[MySQL从节点2]
end
subgraph 缓存命名空间
RedisSVC[Redis服务]
RedisSTS[Redis StatefulSet]
RedisPod1[Redis主节点]
RedisPod2[Redis从节点1]
RedisPod3[Redis从节点2]
end
end
Ingress --> FrontSVC
FrontSVC --> FrontPod1
FrontSVC --> FrontPod2
FrontSVC --> FrontPod3
FrontPod1 --> BackSVC
FrontPod2 --> BackSVC
FrontPod3 --> BackSVC
BackSVC --> BackPod1
BackSVC --> BackPod2
BackSVC --> BackPod3
BackPod1 --> MySQLSVC
BackPod1 --> RedisSVC
BackPod2 --> MySQLSVC
BackPod2 --> RedisSVC
BackPod3 --> MySQLSVC
BackPod3 --> RedisSVC
MySQLSVC --> MySQLSTS
MySQLSTS --> MySQLPod1
MySQLSTS --> MySQLPod2
MySQLSTS --> MySQLPod3
RedisSVC --> RedisSTS
RedisSTS --> RedisPod1
RedisSTS --> RedisPod2
RedisSTS --> RedisPod3
```
#### 2.2 K8s资源配置示例
**前端Deployment配置**:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: water-biz-frontend
namespace: water-biz-frontend
spec:
replicas: 3
selector:
matchLabels:
app: water-biz-frontend
template:
metadata:
labels:
app: water-biz-frontend
spec:
containers:
- name: water-biz-frontend
image: water-biz-frontend:1.0
ports:
- containerPort: 80
resources:
requests:
memory: "256Mi"
cpu: "200m"
limits:
memory: "512Mi"
cpu: "500m"
livenessProbe:
httpGet:
path: /health
port: 80
initialDelaySeconds: 30
periodSeconds: 10
```
**后端Deployment配置**:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: water-biz-backend
namespace: water-biz-backend
spec:
replicas: 3
selector:
matchLabels:
app: water-biz-backend
template:
metadata:
labels:
app: water-biz-backend
spec:
containers:
- name: water-biz-backend
image: water-biz-backend:1.0
ports:
- containerPort: 8080
env:
- name: SPRING_PROFILES_ACTIVE
value: "prod"
- name: SPRING_DATASOURCE_URL
valueFrom:
configMapKeyRef:
name: water-biz-config
key: database.url
resources:
requests:
memory: "1Gi"
cpu: "500m"
limits:
memory: "2Gi"
cpu: "1000m"
livenessProbe:
httpGet:
path: /actuator/health
port: 8080
initialDelaySeconds: 60
periodSeconds: 15
```
## 四、系统运维方案
### 1. 监控方案
#### 1.1 监控架构
```mermaid
graph TD
App[应用服务] --> Prometheus[Prometheus]
DB[数据库] --> Prometheus
OS[操作系统] --> Prometheus
Net[网络设备] --> Prometheus
Prometheus --> Grafana[Grafana]
Prometheus --> AlertManager[告警管理器]
AlertManager --> Email[邮件通知]
AlertManager --> SMS[短信通知]
AlertManager --> WeChat[微信通知]
```
#### 1.2 监控指标
- **系统层监控**
- CPU使用率
- 内存使用率
- 磁盘I/O
- 网络流量
- 进程数
- **应用层监控**
- JVM指标（堆内存、GC情况）
- 线程池状态
- HTTP请求统计
- 业务接口响应时间
- 异常统计
- **数据库监控**
- 连接数
- 查询性能
- 事务状态
- 锁等待情况
- 缓存命中率
- **业务层监控**
- 登录成功/失败次数
- 抄表数据录入量
- 水费收缴情况
- 系统并发用户数
- 业务处理量
### 2. 日志管理
#### 2.1 日志采集架构
```mermaid
graph TD
App[应用服务] -- 日志文件 --> Filebeat[Filebeat]
Filebeat --> Logstash[Logstash]
Logstash --> ES[Elasticsearch]
ES --> Kibana[Kibana]
```
#### 2.2 日志分类
- **系统日志**: 操作系统、中间件产生的日志
- **应用日志**: 应用运行产生的日志
- **业务日志**: 业务操作产生的日志
- **安全日志**: 安全相关操作产生的日志
- **审计日志**: 需要审计的关键操作日志
#### 2.3 日志保留策略
| 日志类型 | 线上保留时间 | 归档保留时间 |
|---------|------------|-------------|
| 系统日志 | 7天 | 30天 |
| 应用日志 | 15天 | 90天 |
| 业务日志 | 30天 | 1年 |
| 安全日志 | 90天 | 3年 |
| 审计日志 | 1年 | 5年 |
### 3. 备份恢复策略
#### 3.1 备份策略
- **数据库备份**
- 全量备份: 每天凌晨进行一次全量备份
- 增量备份: 每小时进行一次增量备份
- 实时备份: 开启binlog实时备份
- **应用备份**
- 配置文件备份: 每次变更时备份
- 代码版本备份: 使用Git保存代码版本
- **系统备份**
- 系统镜像备份: 每季度进行一次系统镜像备份
- 关键配置备份: 每次变更时备份
#### 3.2 恢复策略
- **数据库恢复**
- 按时间点恢复: 可恢复到任意时间点
- 备份文件恢复: 使用备份文件进行恢复
- 模拟演练: 每季度进行一次恢复演练
- **应用恢复**
- 版本回滚: 可回滚到任意版本
- 配置恢复: 使用备份配置进行恢复
### 4. 安全运维
#### 4.1 账号管理
- **最小权限原则**: 账号权限满足工作所需的最小权限
- **权限分离**: 开发、测试、运维账号权限分离
- **定期审计**: 每季度进行一次账号权限审计
- **账号生命周期**: 严格管理账号创建、变更、注销流程
#### 4.2 漏洞管理
- **定期扫描**: 每月进行一次系统漏洞扫描
- **及时修复**: 关键漏洞24小时内修复
- **补丁管理**: 建立补丁管理制度，定期更新系统补丁
#### 4.3 安全审计
- **操作审计**: 记录所有关键操作
- **登录审计**: 记录所有登录行为
- **异常行为检测**: 检测并报警异常操作行为
### 5. 容量规划
#### 5.1 容量评估指标
- **用户数**: 系统支持的最大并发用户数
- **数据量**: 系统数据增长预测
- **存储容量**: 存储空间增长预测
- **网络带宽**: 网络流量增长预测
#### 5.2 扩容策略
- **水平扩容**: 增加服务器节点数量
- **垂直扩容**: 提升单台服务器配置
- **分库分表**: 对大表进行分库分表
- **冷热数据分离**: 将冷数据迁移到低成本存储
## 五、持续集成与部署
### 1. CI/CD流程
```mermaid
graph LR
Code[代码提交] --> Build[构建]
Build --> UnitTest[单元测试]
UnitTest --> CodeScan[代码扫描]
CodeScan --> Package[打包]
Package --> Deploy[部署测试环境]
Deploy --> IntTest[集成测试]
IntTest --> UAT[用户验收测试]
UAT --> Prod[生产环境部署]
```
### 2. 环境管理
- **开发环境**: 供开发人员开发和单元测试使用
- **测试环境**: 供测试人员进行功能测试
- **预生产环境**: 与生产环境配置相同，用于最终验证
- **生产环境**: 正式运行环境
### 3. 发布管理
#### 3.1 发布流程
1. **发布申请**: 提交发布申请，说明发布内容
2. **审批**: 相关负责人审批
3. **预发布**: 在预生产环境部署验证
4. **发布计划**: 制定详细的发布计划和回滚计划
5. **正式发布**: 按计划在生产环境发布
6. **验证**: 发布后进行功能验证
7. **监控**: 发布后密切监控系统运行情况
#### 3.2 发布策略
- **蓝绿发布**: 准备两个环境，一个运行旧版本，一个运行新版本，验证后切换流量
- **金丝雀发布**: 先将新版本部署到一小部分服务器，验证无误后逐步扩大范围
- **灰度发布**: 先对一小部分用户开放新版本，验证无误后逐步扩大用户范围
## 六、灾备方案
### 1. 灾备架构
```mermaid
graph TD
subgraph 主数据中心
PrimaryApp[应用服务器集群]
PrimaryDB[数据库集群]
PrimaryStorage[存储集群]
end
subgraph 灾备数据中心
DRApp[应用服务器集群]
DRDB[数据库集群]
DRStorage[存储集群]
end
PrimaryDB -- 实时同步 --> DRDB
PrimaryStorage -- 定期同步 --> DRStorage
PrimaryApp -- 配置同步 --> DRApp
```
### 2. 灾难恢复流程
1. **灾难发生**: 确认主数据中心不可用
2. **启动灾备**: 激活灾备数据中心
3. **DNS切换**: 将DNS解析指向灾备中心
4. **数据验证**: 验证数据完整性
5. **恢复服务**: 恢复业务服务
6. **用户通知**: 通知用户服务已恢复
7. **故障修复**: 修复主数据中心故障
8. **数据同步**: 将灾备中心数据同步回主中心
9. **切回主中心**: 将服务切回主数据中心
### 3. 灾备演练
- **演练频率**: 每半年进行一次灾备演练
- **演练方式**: 模拟主数据中心故障，激活灾备中心
- **演练评估**: 评估恢复时间目标(RTO)和恢复点目标(RPO)达成情况
## 七、运维工具链
### 1. 运维工具清单
| 类别 | 工具 | 用途 |
|-----|------|-----|
| 配置管理 | Ansible | 自动化配置管理 |
| 容器管理 | Docker, Kubernetes | 容器化部署与编排 |
| 持续集成 | Jenkins, GitLab CI | 自动化构建与部署 |
| 监控告警 | Prometheus, Grafana, AlertManager | 系统监控与告警 |
| 日志管理 | ELK Stack | 日志收集与分析 |
| 数据库管理 | MySQL Workbench, Redis Desktop Manager | 数据库运维管理 |
| 网络管理 | Netdata, Smokeping | 网络监控与故障排查 |
| 安全管理 | Nessus, OpenVAS | 安全漏洞扫描 |
### 2. 自动化运维脚本
- **系统巡检脚本**: 定期检查系统状态
- **数据备份脚本**: 自动执行数据备份
- **日志清理脚本**: 自动清理过期日志
- **性能基线采集脚本**: 采集系统性能基线
## 八、运维管理规范
### 1. 变更管理规范
- **变更申请**: 所有变更必须提交申请
- **变更评审**: 重要变更必须经过评审
- **变更窗口**: 生产环境变更只能在指定时间窗口进行
- **变更通知**: 提前通知相关人员
- **变更回滚**: 制定详细的回滚方案
### 2. 事件管理规范
- **事件分级**: 按影响范围和严重程度分级
- **响应时间**: 不同级别事件的响应时间要求
- **升级流程**: 事件升级的条件和流程
- **通知机制**: 事件通知的方式和对象
- **事后复盘**: 重大事件后必须进行复盘
### 3. 问题管理规范
- **问题记录**: 所有问题必须记录
- **根因分析**: 分析问题根本原因
- **解决方案**: 制定问题解决方案
- **知识库**: 建立问题知识库
- **经验总结**: 定期总结问题处理经验

190
water_biz_design_plan.md Normal file
View File

@ -0,0 +1,190 @@
# 福建水务营收系统概要设计文档编写计划
## 一、项目背景与概述
福建水务营收系统是基于RuoYi-Vue-Pro和yudao-ui-admin-vue3框架开发的一套现代化水务营收管理系统，旨在满足原有系统的所有功能需求，并通过技术升级提升系统的性能、安全性和用户体验。
## 二、系统设计总体规划
### 1. 设计依据
- 原系统《营收系统_详细设计说明书》
- 原系统《营收系统_需求规格说明书》
- 原系统《营收系统_用户操作手册》
- RuoYi-Vue-Pro框架开发文档
- yudao-ui-admin-vue3框架开发文档
### 2. 设计原则
- **继承性原则**：确保新系统覆盖原有系统的所有功能
- **先进性原则**：采用当前主流技术架构和开发框架
- **扩展性原则**：设计良好的扩展接口，支持未来功能扩展
- **安全性原则**：符合国家相关安全规范，确保系统安全可靠
- **易用性原则**：优化用户界面，提升用户体验
## 三、编写工作步骤与时间规划
### 第一阶段：需求分析（2周）
1. **原系统功能梳理**
- 研读原系统文档，提取核心功能点
- 整理功能清单与功能描述
- 确认需保留的功能与新增功能
2. **业务流程梳理**
- 梳理现有业务流程
- 设计优化后的业务流程图
- 与业务部门确认流程优化点
### 第二阶段：系统架构设计（2周）
1. **技术架构设计**
- 前端技术架构设计
- 后端技术架构设计
- 数据库架构设计
- 集成方案设计
2. **系统功能模块划分**
- 功能模块划分
- 模块间关系设计
- 接口设计原则
### 第三阶段：详细设计（3周）
1. **系统功能模块详细设计**
- 用户管理模块
- 水表管理模块
- 抄表管理模块
- 收费管理模块
- 账务管理模块
- 票据管理模块
- 营业网点管理模块
- 报表管理模块
- 系统管理模块
2. **数据库设计**
- 实体关系图设计
- 数据表结构设计
- 数据字典编制
3. **接口设计**
- 内部模块接口设计
- 外部系统接口设计
- API文档编制
### 第四阶段：非功能性设计（1周）
1. **性能设计**
- 并发处理设计
- 数据库优化设计
- 缓存策略设计
2. **安全设计**
- 用户认证与授权设计
- 数据安全设计
- 审计日志设计
3. **部署设计**
- 系统部署架构
- 服务器配置要求
- 备份恢复方案
### 第五阶段：文档整合与评审（2周）
1. **文档整合**
- 汇总各模块设计文档
- 统一文档格式与风格
- 完善文档引用与附录
2. **文档评审**
- 内部技术评审
- 与业务部门确认
- 根据反馈修改文档
## 四、人员分工建议
对于多人协作编写文档，建议按照以下方式进行分工：
### 1. 按模块分工
- **架构师**：负责系统总体架构设计、技术选型、非功能性设计
- **业务分析师**：负责需求分析、业务流程梳理、功能规划
- **前端设计师**：负责前端架构设计、UI/UX设计、前端模块设计
- **后端开发负责人**：负责后端架构设计、核心模块设计、安全设计
- **数据库设计师**：负责数据库设计、数据模型设计、性能优化设计
### 2. 按系统功能分工
- **基础模块组**：负责用户管理、权限管理、系统管理等基础功能设计
- **业务核心组**：负责水表管理、抄表管理、收费管理等核心业务功能设计
- **财务模块组**：负责账务管理、票据管理等财务相关功能设计
- **报表分析组**：负责报表管理、数据分析等统计分析功能设计
- **集成对接组**：负责与外部系统的接口设计、数据同步设计
## 五、文档规范与模板
### 1. 文档格式规范
- 使用Markdown格式编写
- 章节层级不超过4级
- 图表统一使用PlantUML或Mermaid格式
- 术语表达保持一致性
### 2. 设计文档模板
每个功能模块的设计文档应包含以下内容：
```markdown
# [模块名称]设计说明
## 1. 功能概述
[简要描述该模块的主要功能和目标]
## 2. 功能列表
[列出该模块包含的所有功能点]
## 3. 业务流程
[使用流程图描述主要业务流程]
## 4. 数据模型
[描述该模块涉及的主要数据实体及关系]
## 5. 接口设计
[描述该模块提供的接口，包括参数、返回值等]
## 6. 界面设计
[提供界面原型或描述，说明界面交互逻辑]
## 7. 安全考虑
[描述该模块的安全控制措施]
## 8. 特殊说明
[其他需要说明的事项]
```
## 六、Cursor Rules配置
为了使用Cursor更高效地完成概要设计文档，建议配置以下规则：
1. **文档结构检查**：确保文档结构符合预定义的模板
2. **术语一致性检查**：确保整个文档中术语使用的一致性
3. **图表格式化**：自动格式化PlantUML或Mermaid图表代码
4. **引用链接检查**：确保文档内的交叉引用有效
5. **中文标点规范**：确保使用规范的中文标点符号
## 七、协作工具与流程
1. **版本控制**：使用Git进行文档版本控制
2. **协作平台**：使用GitLab/GitHub进行协作
3. **评审工具**：使用MR/PR进行文档评审
4. **任务管理**：使用项目管理工具（如JIRA）跟踪文档编写进度
## 八、成果交付物
最终交付物应包括：
1. 系统概要设计说明书（主文档）
2. 各功能模块详细设计说明
3. 数据库设计说明书
4. 接口设计说明书
5. 部署运维设计说明书

139
water_biz_doc_toc.md Normal file
View File

@ -0,0 +1,139 @@
# 福建水务营收系统概要设计文档目录
## 前言
本文档为福建水务营收系统的概要设计文档，基于RuoYi-Vue-Pro后端框架和yudao-ui-admin-vue3前端框架，旨在满足原有系统的所有功能需求，并通过技术升级提升系统的性能、安全性和用户体验。
## 目录
### 一、设计计划
- [设计计划文档](water_biz_design_plan.md)
- 项目背景与概述
- 系统设计总体规划
- 编写工作步骤与时间规划
- 人员分工建议
- 文档规范与模板
- Cursor Rules配置
- 协作工具与流程
- 成果交付物
- [Cursor Rules配置指南](cursor_rules.md)
- Cursor Rules概述
- 基础规则配置
- 业务领域规则
- 图表规范
- 代码示例规范
- 引用链接规范
- 表格规范
- 自定义规则配置方法
- 规则应用建议
- 常见问题解决
### 二、系统架构设计
- [系统架构概要设计](water_biz_system_architecture.md)
- 系统架构概述
- 总体架构设计
- 系统分层设计
- 核心模块设计
- 数据库设计
- 接口设计
- 安全设计
- 高可用设计
- 扩展性设计
- 部署架构
### 三、模块功能设计
- [核心模块功能设计](water_biz_module_design.md)
- 系统功能模块概览
- 用户管理模块
- 水表管理模块
- 抄表管理模块
- 收费管理模块
- 账务管理模块
- 票据管理模块
- 营业网点管理模块
- 报表管理模块
- 系统管理模块
- 集成接口模块
### 四、数据库设计
- [数据库设计](water_biz_database_design.md)
- 数据库设计概述
- 数据库架构设计
- 数据模型设计
- 数据库表结构设计
- 数据库优化设计
- 数据库安全设计
- 数据备份与恢复
- 数据库监控与维护
### 五、接口设计
- [接口设计](water_biz_interface_design.md)
- 接口设计概述
- 接口设计原则
- 内部模块接口
- 外部系统接口
- 接口安全设计
- 接口测试策略
- 接口文档管理
### 六、部署运维设计
- [部署运维设计](water_biz_deployment_design.md)
- 部署架构设计
- 软件部署方案
- 容器化部署方案
- 系统运维方案
- 持续集成与部署
- 灾备方案
- 运维工具链
- 运维管理规范
### 七、总结
- [概要设计文档总结](water_biz_summary.md)
- 文档构成
- 主要内容概述
- 编写建议
- 后续工作建议
- 常见问题与解决方案
## 附录
### 附录A：参考文档
- 原系统《营收系统_详细设计说明书》
- 原系统《营收系统_需求规格说明书》
- 原系统《营收系统_用户操作手册》
- RuoYi-Vue-Pro框架开发文档
- yudao-ui-admin-vue3框架开发文档
### 附录B：术语表
| 术语 | 定义 |
|-----|-----|
| 抄表 | 指读取水表示数的过程 |
| 水价 | 指每立方米水的价格 |
| 阶梯水价 | 按用水量分段计价的水价政策 |
| 远传水表 | 能够自动传输读数的智能水表 |
| 账务 | 指水费收取后的账务处理过程 |
| RBAC | 基于角色的访问控制(Role-Based Access Control) |
| JWT | JSON Web Token，用于身份认证的开放标准 |
| Redis | 内存数据结构存储，用作数据库、缓存和消息中间件 |
### 附录C：项目成员
| 角色 | 姓名 | 职责 |
|-----|-----|-----|
| 项目经理 | [姓名] | 整体项目规划与管理 |
| 架构师 | [姓名] | 系统架构设计 |
| 前端负责人 | [姓名] | 前端技术选型与设计 |
| 后端负责人 | [姓名] | 后端技术选型与设计 |
| 数据库设计师 | [姓名] | 数据库设计与优化 |
| 测试负责人 | [姓名] | 测试策略与测试用例设计 |
| 运维负责人 | [姓名] | 部署方案与运维设计 |

476
water_biz_interface_design.md Normal file
View File

@ -0,0 +1,476 @@
# 福建水务营收系统接口设计
## 一、接口设计概述
福建水务营收系统采用RESTful风格设计API接口，通过HTTP协议提供服务。系统接口分为内部模块间接口和外部系统集成接口两大类，遵循统一的接口规范和安全策略。
## 二、接口设计原则
### 1. 设计原则
- **RESTful风格**: 接口遵循REST架构风格
- **版本控制**: 在URL中包含版本信息
- **统一响应**: 统一的响应格式和状态码
- **参数校验**: 严格的参数校验确保数据有效性
- **权限控制**: 基于JWT和RBAC的接口权限控制
- **幂等性**: 确保关键操作的幂等性
- **文档完善**: 详细的接口文档说明
### 2. 接口地址规范
```
https://{domain}/api/v{version}/{module}/{resource}/{action}
```
- **domain**: 系统域名
- **version**: 接口版本号，如v1
- **module**: 功能模块，如user、meter
- **resource**: 资源名称，通常为复数形式
- **action**: 可选的操作名称
### 3. 响应格式规范
所有接口统一返回JSON格式数据，基本结构如下：
```json
{
"code": 0, // 状态码，0表示成功，非0表示失败
"msg": "success", // 状态描述
"data": { // 响应数据，可能是对象、数组或null
// 具体的业务数据
},
"timestamp": 1621234567890 // 响应时间戳
}
```
### 4. 状态码规范
| 状态码 | 说明 |
|-------|------|
| 0 | 成功 |
| 1000-1999 | 用户认证相关错误 |
| 2000-2999 | 权限相关错误 |
| 3000-3999 | 参数相关错误 |
| 4000-4999 | 业务相关错误 |
| 5000-5999 | 系统内部错误 |
## 三、内部模块接口
### 1. 用户认证模块接口
#### 1.1 用户登录
- **接口地址**: `/api/v1/auth/login`
- **请求方式**: POST
- **接口描述**: 用户登录认证接口
- **请求参数**:
| 参数名 | 类型 | 是否必填 | 说明 |
|-------|------|---------|-----|
| username | String | 是 | 用户名 |
| password | String | 是 | 密码 |
| captcha | String | 否 | 验证码 |
| captchaId | String | 否 | 验证码ID |
- **响应示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expireTime": 1621234567890,
"userInfo": {
"userId": 1,
"username": "admin",
"nickname": "管理员",
"avatar": "https://example.com/avatar.jpg",
"permissions": ["sys:user:list", "sys:user:create"]
}
},
"timestamp": 1621234567890
}
```
#### 1.2 刷新令牌
- **接口地址**: `/api/v1/auth/refresh-token`
- **请求方式**: POST
- **接口描述**: 刷新访问令牌
- **请求参数**:
| 参数名 | 类型 | 是否必填 | 说明 |
|-------|------|---------|-----|
| refreshToken | String | 是 | 刷新令牌 |
- **响应示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expireTime": 1621234567890
},
"timestamp": 1621234567890
}
```
### 2. 水表管理模块接口
#### 2.1 水表列表查询
- **接口地址**: `/api/v1/meter/meters`
- **请求方式**: GET
- **接口描述**: 查询水表信息列表
- **请求参数**:
| 参数名 | 类型 | 是否必填 | 说明 |
|-------|------|---------|-----|
| customerId | Long | 否 | 客户ID |
| meterNo | String | 否 | 水表编号 |
| meterType | Integer | 否 | 水表类型 |
| status | Integer | 否 | 水表状态 |
| pageNo | Integer | 否 | 页码，默认1 |
| pageSize | Integer | 否 | 每页记录数，默认10 |
- **响应示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"total": 100,
"list": [
{
"id": 1,
"meterNo": "M20230001",
"customerName": "张三",
"meterType": 1,
"meterTypeName": "普通水表",
"installAddress": "福建省福州市台江区",
"currentReading": 120.5,
"status": 0,
"statusName": "正常"
}
],
"pageNum": 1,
"pageSize": 10,
"totalPages": 10
},
"timestamp": 1621234567890
}
```
#### 2.2 水表详情查询
- **接口地址**: `/api/v1/meter/meters/{id}`
- **请求方式**: GET
- **接口描述**: 查询水表详细信息
- **路径参数**:
| 参数名 | 类型 | 是否必填 | 说明 |
|-------|------|---------|-----|
| id | Long | 是 | 水表ID |
- **响应示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"id": 1,
"meterNo": "M20230001",
"customerId": 1,
"customerName": "张三",
"meterType": 1,
"meterTypeName": "普通水表",
"caliber": "DN20",
"installDate": "2023-01-15",
"initialReading": 0,
"currentReading": 120.5,
"installAddress": "福建省福州市台江区",
"status": 0,
"statusName": "正常",
"readingCycle": 1,
"readingCycleName": "月",
"description": "安装在一楼进水口",
"createTime": "2023-01-15 10:00:00",
"updateTime": "2023-05-10 15:30:00"
},
"timestamp": 1621234567890
}
```
### 3. 抄表管理模块接口
#### 3.1 提交抄表数据
- **接口地址**: `/api/v1/reading/meter-readings`
- **请求方式**: POST
- **接口描述**: 提交水表读数
- **请求参数**:
| 参数名 | 类型 | 是否必填 | 说明 |
|-------|------|---------|-----|
| meterId | Long | 是 | 水表ID |
| reading | Decimal | 是 | 本次读数 |
| readingDate | Date | 是 | 抄表日期 |
| readingType | Integer | 是 | 抄表类型(1人工,2远传,3用户自报) |
| photoUrl | String | 否 | 水表照片URL |
| remark | String | 否 | 备注 |
- **响应示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"id": 1,
"meterId": 1,
"meterNo": "M20230001",
"readingDate": "2023-05-10",
"reading": 120.5,
"lastReading": 100.0,
"waterUsage": 20.5,
"readingType": 1,
"readingTypeName": "人工抄表",
"status": 0,
"statusName": "正常"
},
"timestamp": 1621234567890
}
```
### 4. 收费管理模块接口
#### 4.1 生成水费账单
- **接口地址**: `/api/v1/billing/generate-bills`
- **请求方式**: POST
- **接口描述**: 根据抄表数据生成水费账单
- **请求参数**:
| 参数名 | 类型 | 是否必填 | 说明 |
|-------|------|---------|-----|
| meterReadingIds | Array | 是 | 抄表记录ID数组 |
| billingPeriod | String | 是 | 账单周期(yyyyMM) |
| dueDate | Date | 是 | 缴费截止日期 |
- **响应示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"successCount": 10,
"failCount": 0,
"billIds": [1, 2, 3]
},
"timestamp": 1621234567890
}
```
#### 4.2 缴费处理
- **接口地址**: `/api/v1/payment/payments`
- **请求方式**: POST
- **接口描述**: 处理用户缴费
- **请求参数**:
| 参数名 | 类型 | 是否必填 | 说明 |
|-------|------|---------|-----|
| billId | Long | 是 | 账单ID |
| paymentAmount | Decimal | 是 | 支付金额 |
| paymentMethod | Integer | 是 | 支付方式(1现金,2银行卡,3微信,4支付宝) |
| paymentDate | Date | 是 | 支付日期 |
| transactionNo | String | 否 | 交易流水号 |
| remark | String | 否 | 备注 |
- **响应示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"id": 1,
"billId": 1,
"billNo": "B20230510001",
"customerName": "张三",
"paymentAmount": 100.0,
"paymentMethod": 1,
"paymentMethodName": "现金",
"paymentDate": "2023-05-10",
"receiptNo": "R20230510001"
},
"timestamp": 1621234567890
}
```
## 四、外部系统接口
### 1. 银行支付接口
#### 1.1 银行代扣申请
- **接口地址**: `/api/v1/external/bank/deduction`
- **请求方式**: POST
- **接口描述**: 向银行发起代扣申请
- **请求参数**:
| 参数名 | 类型 | 是否必填 | 说明 |
|-------|------|---------|-----|
| bankCode | String | 是 | 银行代码 |
| billIds | Array | 是 | 账单ID数组 |
| batchNo | String | 是 | 批次号 |
- **响应示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"batchNo": "BK20230510001",
"totalAmount": 1000.0,
"totalCount": 10,
"requestTime": "2023-05-10 10:00:00",
"status": "PROCESSING"
},
"timestamp": 1621234567890
}
```
### 2. 微信支付接口
#### 2.1 发起微信支付
- **接口地址**: `/api/v1/external/wechat/create-order`
- **请求方式**: POST
- **接口描述**: 创建微信支付订单
- **请求参数**:
| 参数名 | 类型 | 是否必填 | 说明 |
|-------|------|---------|-----|
| billId | Long | 是 | 账单ID |
| openId | String | 是 | 用户微信openId |
| amount | Decimal | 是 | 支付金额 |
- **响应示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"prepayId": "wx2023051010000000000000000000",
"nonceStr": "ibuaiVcKdpRxkhJA",
"timeStamp": "1621234567",
"signType": "MD5",
"paySign": "70EA570631E4BB79628FBCA90534C63FF7FADD89"
},
"timestamp": 1621234567890
}
```
### 3. 短信通知接口
#### 3.1 发送短信通知
- **接口地址**: `/api/v1/external/sms/send`
- **请求方式**: POST
- **接口描述**: 发送短信通知
- **请求参数**:
| 参数名 | 类型 | 是否必填 | 说明 |
|-------|------|---------|-----|
| phone | String | 是 | 手机号 |
| templateId | String | 是 | 短信模板ID |
| params | Object | 是 | 短信参数 |
- **响应示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"messageId": "SMS20230510001",
"sendTime": "2023-05-10 10:00:00",
"status": "SENT"
},
"timestamp": 1621234567890
}
```
## 五、接口安全设计
### 1. 认证机制
- **JWT认证**: 使用JWT进行接口认证，访问需要权限的接口时必须在请求头中携带有效的Token
- **Token刷新**: 提供Token刷新机制，避免频繁登录
- **多端登录控制**: 支持控制同一账号多端登录策略
### 2. 权限控制
- **RBAC权限模型**: 基于角色的权限控制，精细化权限管理
- **接口权限**: 每个接口绑定权限标识，通过注解方式声明
- **数据权限**: 支持部门级、用户级数据权限控制
### 3. 安全防护
- **参数验证**: 严格校验请求参数，防止非法参数
- **SQL注入防护**: 使用参数绑定方式防止SQL注入
- **XSS防护**: 过滤请求参数中的恶意脚本
- **CSRF防护**: 使用Token验证防止CSRF攻击
- **接口限流**: 对关键接口实施限流措施，防止恶意攻击
- **日志追踪**: 记录接口调用日志，便于安全审计
## 六、接口测试策略
### 1. 单元测试
- 编写接口单元测试，验证接口功能正确性
- 使用MockMVC进行Controller层测试
- 使用Mock框架模拟外部依赖
### 2. 集成测试
- 编写接口集成测试，验证接口与其他组件的交互
- 使用测试容器进行数据库测试
- 测试完整业务流程
### 3. 性能测试
- 使用JMeter等工具进行接口性能测试
- 测试接口响应时间
- 测试接口并发处理能力
- 测试系统在高负载下的稳定性
## 七、接口文档管理
### 1. 文档生成
- 使用Swagger/Knife4j自动生成接口文档
- 通过API注解提供详细的接口说明
- 支持在线调试接口
### 2. 版本管理
- 明确的接口版本控制策略
- 接口变更记录
- 兼容性说明
### 3. 文档发布
- 提供在线接口文档站点
- 支持导出PDF、HTML等格式
- 权限控制，限制文档访问范围

553
water_biz_module_design.md Normal file
View File

@ -0,0 +1,553 @@
# 福建水务营收系统核心模块功能设计
## 一、系统功能模块概览
福建水务营收系统是一套现代化的水务管理系统，按照业务功能划分为若干个核心模块，每个模块负责特定的业务处理。本文档详细描述各个核心模块的功能设计。
## 二、用户管理模块
### 1. 功能概述
用户管理模块负责系统用户的信息管理、认证授权、密码安全策略等功能，是系统的基础管理模块。
### 2. 功能列表
- 用户信息管理：用户信息的添加、修改、删除、查询
- 用户认证：用户登录认证、密码修改、密码重置
- 角色管理：角色的添加、修改、删除、查询
- 权限管理：基于RBAC模型的权限控制
- 部门管理：部门的添加、修改、删除、查询
- 岗位管理：岗位的添加、修改、删除、查询
- 用户分组：用户按业务需求进行分组管理
- 操作日志：记录用户操作行为
- 登录日志：记录用户登录情况
### 3. 业务流程
```mermaid
graph TD
A[用户登录] --> B{验证身份}
B -- 成功 --> C[获取用户权限]
B -- 失败 --> D[返回错误信息]
C --> E[生成用户菜单]
E --> F[进入系统]
```
### 4. 核心功能说明
1. **基于RBAC的权限控制**
- 支持菜单权限、功能权限、数据权限三级权限控制
- 灵活的权限分配机制，支持角色继承
- 完善的权限验证机制，确保系统安全
2. **多因素认证**
- 支持账号密码认证
- 支持短信验证码认证
- 支持验证码认证
- 支持记住我功能
3. **安全策略**
- 密码复杂度要求
- 密码定期更换
- 账号锁定策略
- 登录异常检测
## 三、水表管理模块
### 1. 功能概述
水表管理模块负责管理用户水表的基础信息、生命周期管理、状态变更等功能，为抄表和收费提供基础数据支持。
### 2. 功能列表
- 水表信息管理：水表基础信息的添加、修改、删除、查询
- 水表安装管理：记录水表安装信息，生成安装工单
- 水表更换管理：记录水表更换信息，生成更换工单
- 水表拆除管理：记录水表拆除信息，生成拆除工单
- 水表维修管理：记录水表维修信息，生成维修工单
- 水表巡检管理：记录水表巡检信息，生成巡检工单
- 水表状态管理：管理水表的运行状态
- 批量导入导出：支持批量导入导出水表信息
- 水表档案管理：维护水表的历史记录和档案资料
### 3. 业务流程
```mermaid
graph TD
A[新增水表信息] --> B[生成水表编号]
B --> C[关联用户信息]
C --> D[初始化水表状态]
D --> E[安装水表]
E --> F[完成安装]
G[水表故障] --> H[生成维修工单]
H --> I[指派维修人员]
I --> J[维修处理]
J --> K[更新水表状态]
L[水表报废] --> M[生成更换工单]
M --> N[拆除旧表]
N --> O[安装新表]
O --> P[更新水表信息]
```
### 4. 核心功能说明
1. **水表生命周期管理**
- 安装：记录安装时间、安装位置、起始读数等信息
- 维修：记录维修原因、维修时间、维修人员等信息
- 更换：记录更换原因、更换时间、新旧表信息等
- 拆除：记录拆除原因、拆除时间、最终读数等信息
2. **水表分类管理**
- 按类型分类：普通水表、智能水表、IC卡水表、远传水表等
- 按口径分类：DN15、DN20、DN25等规格
- 按用途分类：居民用水、商业用水、工业用水等
3. **水表批量操作**
- 批量导入：支持Excel导入水表信息
- 批量更新：支持批量更新水表状态
- 批量导出：支持导出水表数据进行分析
## 四、抄表管理模块
### 1. 功能概述
抄表管理模块负责水表读数的采集、审核、异常处理等功能，是水费计算的基础和前提。
### 2. 功能列表
- 抄表计划管理：抄表计划的制定、修改、删除、查询
- 抄表任务分配：根据抄表员区域分配抄表任务
- 抄表数据录入：支持多种方式录入抄表数据
- 抄表数据审核：对录入的抄表数据进行审核
- 异常数据处理：对异常抄表数据进行处理
- 抄表统计分析：抄表完成率、抄表准确率等统计
- 水量分析：用水量异常分析、同比环比分析
- 远程抄表管理：自动采集远传水表数据
- 抄表路线管理：规划优化抄表路线
- 抄表工作量统计：统计抄表员工作量
### 3. 业务流程
```mermaid
graph TD
A[制定抄表计划] --> B[生成抄表任务]
B --> C[分配抄表员]
C --> D[抄表数据采集]
D --> E{数据审核}
E -- 正常 --> F[生成水费账单]
E -- 异常 --> G[异常处理]
G --> H[重新抄表]
H --> E
G -- 确认异常 --> I[人工核实]
I --> F
```
### 4. 核心功能说明
1. **多种抄表方式支持**
- 人工抄表：通过手持终端录入数据
- 远程抄表：自动采集远传水表数据
- 用户自报：用户通过网站、APP自行上报读数
- 图片识别：通过上传水表照片自动识别读数
2. **异常数据处理**
- 零水量：连续几个月无用水的异常处理
- 用水量突增：较往常用水量突然增加的异常处理
- 用水量突减：较往常用水量突然减少的异常处理
- 重复录入：相同水表多次录入数据的处理
- 倒走水量：当前读数小于上次读数的处理
3. **抄表质量控制**
- 抄表准确率考核
- 抄表覆盖率考核
- 抄表及时率考核
- 抄表异常处理率考核
## 五、收费管理模块
### 1. 功能概述
收费管理模块负责水费的计算、收取、欠费管理等功能，是系统的核心业务模块。
### 2. 功能列表
- 水费计算：根据抄表数据和水价政策计算水费
- 水费账单生成：生成用户水费账单
- 水费收取：多渠道收取水费
- 催缴管理：欠费催缴通知和管理
- 优惠政策管理：各类用户优惠政策的设置和应用
- 水价管理：不同用户类型、阶梯水价的管理
- 缴费记录管理：记录和查询用户缴费历史
- 收费统计分析：收费率、收费金额等统计分析
- 坐收中心管理：营业厅收费管理
- 稽查管理：对违规用水行为的稽查和处理
### 3. 业务流程
```mermaid
graph TD
A[抄表数据确认] --> B[计算水费]
B --> C[生成账单]
C --> D[通知用户]
D --> E{用户缴费}
E -- 按时缴费 --> F[完成缴费]
E -- 逾期未缴 --> G[催缴通知]
G --> H{是否缴费}
H -- 是 --> F
H -- 否 --> I[强制催缴]
I --> J{是否缴费}
J -- 是 --> F
J -- 否 --> K[停水处理]
K --> L{是否缴费}
L -- 是 --> M[恢复供水]
M --> F
```
### 4. 核心功能说明
1. **多种收费方式支持**
- 营业厅收费：用户前往营业厅缴费
- 银行代扣：通过银行自动代扣水费
- 网上支付：通过网站、APP在线支付
- 微信支付：通过微信公众号、小程序支付
- 支付宝支付：通过支付宝支付
- 预存抵扣：预存水费自动抵扣
- 第三方代收：通过合作的第三方机构代收
2. **水价政策管理**
- 基础水价设置
- 阶梯水价设置
- 特殊时期水价调整
- 不同用户类型水价设置
- 季节性水价调整
3. **欠费管理**
- 欠费记录管理
- 催缴通知管理
- 停水管理
- 恢复供水管理
- 滞纳金计算
## 六、账务管理模块
### 1. 功能概述
账务管理模块负责系统财务账务处理，包括收费入账、销账、退费等功能，是系统财务管理的核心模块。
### 2. 功能列表
- 收费入账：收费记录的财务入账处理
- 销账管理：已收费用的销账处理
- 退费管理：退费申请、审批、执行
- 坏账管理：无法收回的水费坏账处理
- 日结管理：每日收费的结算和统计
- 月结管理：每月收费的结算和统计
- 年结管理：年度收费的结算和统计
- 账务调整：账务数据的调整和修正
- 收费报表：各类收费统计报表生成
- 财务对账：与财务系统的对账功能
### 3. 业务流程
```mermaid
graph TD
A[收费记录] --> B[收费入账]
B --> C{是否需要退费}
C -- 是 --> D[申请退费]
D --> E[退费审批]
E --> F[执行退费]
F --> G[退费入账]
C -- 否 --> H[正常销账]
G --> H
H --> I[日结处理]
I --> J[月结处理]
J --> K[年结处理]
```
### 4. 核心功能说明
1. **账务处理流程**
- 收费入账：记录收费金额、收费方式、收费时间等
- 销账处理：标记账单已缴费，更新账务状态
- 退费处理：处理用户退费申请，执行退费操作
- 调账处理：对账务数据进行调整和修正
2. **财务统计功能**
- 日收费统计：统计每日收费情况
- 月收费统计：统计每月收费情况
- 年收费统计：统计年度收费情况
- 收费方式统计：按收费方式统计收费情况
- 欠费率统计：统计欠费率和欠费金额
3. **财务报表功能**
- 收费日报表：每日收费情况报表
- 收费月报表：每月收费情况报表
- 收费年报表：年度收费情况报表
- 欠费统计报表：欠费情况统计报表
- 坏账统计报表：坏账情况统计报表
## 七、票据管理模块
### 1. 功能概述
票据管理模块负责水费发票的开具、管理、查询等功能，确保票据管理的规范性和合法性。
### 2. 功能列表
- 发票开具：为用户开具水费发票
- 发票作废：对错误发票进行作废处理
- 发票查询：查询发票开具情况
- 发票补打：补打发票
- 发票领用管理：管理发票的领用和库存
- 发票使用统计：统计发票使用情况
- 电子发票管理：管理电子发票的开具和发送
- 票据日志：记录票据操作日志
### 3. 业务流程
```mermaid
graph TD
A[用户缴费] --> B{需要发票}
B -- 需要 --> C[选择发票类型]
C --> D{电子发票/纸质发票}
D -- 电子发票 --> E[生成电子发票]
E --> F[发送至用户邮箱/手机]
D -- 纸质发票 --> G[打印纸质发票]
G --> H[交付用户]
B -- 不需要 --> I[完成缴费]
F --> I
H --> I
```
### 4. 核心功能说明
1. **发票管理功能**
- 发票开具：根据用户缴费情况开具发票
- 发票作废：对错误发票进行作废处理
- 发票重打：对损坏的发票进行重新打印
- 发票查询：查询发票开具情况和历史记录
2. **多种发票类型支持**
- 普通纸质发票
- 增值税普通发票
- 增值税专用发票
- 电子发票
3. **电子发票功能**
- 电子发票生成
- 电子发票发送（邮件、短信等）
- 电子发票查验
- 电子发票下载和打印
## 八、营业网点管理模块
### 1. 功能概述
营业网点管理模块负责管理水务公司的营业网点、窗口、人员等信息，为用户提供线下服务支持。
### 2. 功能列表
- 营业网点管理：网点的添加、修改、删除、查询
- 窗口管理：服务窗口的管理和配置
- 营业时间管理：网点营业时间的设置
- 人员排班管理：营业人员的排班安排
- 业务办理统计：各网点业务办理情况统计
- 网点评价管理：客户对网点服务的评价管理
- 客户查询：查询客户相关信息
- 业务办理：办理各类水务业务
- 现金管理：网点现金收取和管理
### 3. 业务流程
```mermaid
graph TD
A[客户到访] --> B[取号排队]
B --> C[窗口叫号]
C --> D[业务受理]
D --> E{是否需要缴费}
E -- 是 --> F[缴费处理]
F --> G[开具票据]
G --> H[业务完成]
E -- 否 --> H
```
### 4. 核心功能说明
1. **营业网点管理功能**
- 网点信息管理：地址、联系方式、营业时间等
- 窗口设置：服务类型、窗口编号等
- 人员安排：窗口工作人员安排
- 业务统计：业务办理量、收费金额等统计
2. **排队叫号系统**
- 取号管理：客户取号
- 叫号管理：窗口叫号
- 业务分类：不同业务类型的排队管理
- 优先级设置：特殊客户优先处理
3. **网点业务管理**
- 业务类型管理：可办理的业务类型
- 业务流程管理：各类业务的办理流程
- 业务量统计：统计各类业务办理情况
- 服务质量评价：客户对服务的评价管理
## 九、报表管理模块
### 1. 功能概述
报表管理模块负责系统各类统计报表的生成、查询、导出等功能，为管理决策提供数据支持。
### 2. 功能列表
- 营收报表：收费情况统计报表
- 抄表报表：抄表情况统计报表
- 用水分析报表：用水量分析报表
- 客户报表：客户信息统计报表
- 综合分析报表：多维度综合分析报表
- 自定义报表：支持自定义报表配置
- 报表导出：报表数据导出为Excel、PDF等格式
- 报表打印：报表打印功能
- 数据可视化：图表、仪表盘等可视化展示
### 3. 业务流程
```mermaid
graph TD
A[选择报表类型] --> B[设置查询条件]
B --> C[生成报表]
C --> D{操作选择}
D -- 导出 --> E[选择导出格式]
E --> F[保存报表文件]
D -- 打印 --> G[报表打印]
D -- 数据分析 --> H[数据钻取分析]
```
### 4. 核心功能说明
1. **预设报表功能**
- 营收报表：按日、周、月、年统计收费情况
- 抄表报表：抄表率、抄表异常情况统计
- 欠费报表：欠费金额、欠费率等统计
- 用水分析报表：按用户类型、区域等分析用水情况
2. **报表定制功能**
- 自定义报表字段
- 自定义报表条件
- 自定义报表格式
- 自定义报表展示方式
3. **数据可视化功能**
- 折线图：展示趋势变化
- 柱状图：比较数量差异
- 饼图：展示占比情况
- 地图：展示地理分布
- 仪表盘：直观展示关键指标
## 十、系统管理模块
### 1. 功能概述
系统管理模块负责系统基础配置、参数设置、日志管理等功能，确保系统正常运行。
### 2. 功能列表
- 菜单管理：系统菜单的添加、修改、删除、查询
- 字典管理：系统字典的管理
- 参数配置：系统参数的配置
- 通知公告：系统通知和公告管理
- 系统日志：记录系统操作日志
- 登录日志：记录用户登录日志
- 在线用户：查看当前在线用户
- 定时任务：系统定时任务的管理
- 系统监控：监控系统运行状态
- 数据备份：系统数据备份和恢复
### 3. 业务流程
```mermaid
graph TD
A[系统运行] --> B[记录系统日志]
A --> C[记录操作日志]
A --> D[记录登录日志]
A --> E[执行定时任务]
E --> F[备份数据]
B --> G[日志归档]
C --> G
D --> G
G --> H[日志分析]
```
### 4. 核心功能说明
1. **系统配置管理**
- 系统参数配置：各类系统参数的设置
- 字典管理：系统字典数据的维护
- 菜单管理：系统菜单的维护
- 接口管理：系统接口的配置和管理
2. **系统监控功能**
- 服务器监控：监控服务器CPU、内存、磁盘等使用情况
- 数据库监控：监控数据库连接、性能等情况
- 缓存监控：监控Redis缓存使用情况
- 在线用户监控：监控当前在线用户情况
3. **日志管理功能**
- 操作日志：记录用户操作行为
- 登录日志：记录用户登录情况
- 系统日志：记录系统运行日志
- 异常日志：记录系统异常情况
## 十一、集成接口模块
### 1. 功能概述
集成接口模块负责与外部系统的数据交换和集成，实现系统间的无缝连接。
### 2. 功能列表
- 银行支付接口：与银行系统对接，实现水费代扣
- 微信支付接口：与微信支付系统对接
- 支付宝支付接口：与支付宝支付系统对接
- 短信平台接口：与短信平台对接，发送短信通知
- 电子发票接口：与税务系统对接，开具电子发票
- GIS系统接口：与地理信息系统对接
- 物联网平台接口：与物联网平台对接，采集智能水表数据
- 数据交换接口：与其他业务系统进行数据交换
### 3. 业务流程
```mermaid
graph TD
A[系统事件触发] --> B{接口类型}
B -- 支付接口 --> C[发送支付请求]
C --> D[接收支付结果]
D --> E[更新支付状态]
B -- 短信接口 --> F[组装短信内容]
F --> G[调用短信发送]
G --> H[记录发送结果]
B -- 数据同步接口 --> I[准备同步数据]
I --> J[调用同步接口]
J --> K[处理同步结果]
```
### 4. 核心功能说明
1. **支付接口集成**
- 银行代扣接口：实现水费银行代扣功能
- 微信支付接口：通过微信支付水费
- 支付宝支付接口：通过支付宝支付水费
- 支付结果处理：处理支付回调，更新支付状态
2. **通知接口集成**
- 短信通知：抄表通知、缴费通知、催缴通知等
- 邮件通知：电子账单、电子发票等
- 微信通知：通过微信公众号、小程序推送通知
- APP推送：通过移动APP推送通知
3. **数据采集接口集成**
- 智能水表数据采集：远程采集智能水表读数
- 物联网设备数据采集：采集物联网设备监测数据
- 实时数据监控：监控关键设备的实时运行数据
- 数据异常预警：对异常数据进行预警

175
water_biz_summary.md Normal file
View File

@ -0,0 +1,175 @@
# 福建水务营收系统概要设计文档总结
## 一、文档构成
福建水务营收系统概要设计文档包含以下几个主要部分：
1. **设计计划文档**：描述文档编写计划、分工和规范
2. **系统架构设计**：描述系统总体架构和技术选型
3. **模块功能设计**：描述各功能模块的详细设计
4. **数据库设计**：描述数据库结构和优化策略
5. **接口设计**：描述系统内部和外部接口设计
6. **部署运维设计**：描述系统部署架构和运维方案
## 二、主要内容概述
### 1. 设计计划文档
设计计划文档明确了概要设计文档的编写计划、时间规划、人员分工和文档规范，为后续设计工作提供了指导框架。主要内容包括：
- 项目背景与概述
- 系统设计总体规划
- 编写工作步骤与时间规划
- 人员分工建议
- 文档规范与模板
- Cursor Rules配置
- 协作工具与流程
- 成果交付物
### 2. 系统架构设计
系统架构设计描述了福建水务营收系统的总体架构、技术框架和实现方案，为系统开发提供了技术指导。主要内容包括：
- 系统架构概述
- 总体架构设计
- 系统分层设计
- 核心模块设计
- 数据库设计
- 接口设计
- 安全设计
- 高可用设计
- 扩展性设计
- 部署架构
### 3. 模块功能设计
模块功能设计详细描述了系统各个功能模块的设计，包括功能需求、业务流程、实现方式等。主要内容包括：
- 用户管理模块
- 水表管理模块
- 抄表管理模块
- 收费管理模块
- 账务管理模块
- 票据管理模块
- 营业网点管理模块
- 报表管理模块
- 系统管理模块
- 集成接口模块
### 4. 数据库设计
数据库设计描述了系统的数据模型、表结构和数据库优化策略，为数据存储和管理提供了技术方案。主要内容包括：
- 数据库设计概述
- 数据库架构设计
- 数据模型设计
- 数据库表结构设计
- 数据库优化设计
- 数据库安全设计
- 数据备份与恢复
- 数据库监控与维护
### 5. 接口设计
接口设计描述了系统内部模块间的接口和与外部系统的集成接口，为系统集成提供了技术方案。主要内容包括：
- 接口设计概述
- 接口设计原则
- 内部模块接口
- 外部系统接口
- 接口安全设计
- 接口测试策略
- 接口文档管理
### 6. 部署运维设计
部署运维设计描述了系统的部署架构、运维方案和灾备策略，为系统运行维护提供了技术支持。主要内容包括：
- 部署架构设计
- 软件部署方案
- 容器化部署方案
- 系统运维方案
- 持续集成与部署
- 灾备方案
- 运维工具链
- 运维管理规范
## 三、编写建议
### 1. 编写前的准备
- **充分理解原系统**：详细阅读原有系统的需求和设计文档，理解系统功能和业务流程
- **熟悉技术框架**：深入了解RuoYi-Vue-Pro和yudao-ui-admin-vue3框架的功能和架构
- **明确编写范围**：根据项目实际需求，确定概要设计文档的详细程度和范围
- **收集参考资料**：收集相关技术资料、业界最佳实践和类似系统的设计文档作为参考
### 2. 编写过程中的注意事项
- **保持一致性**：确保文档风格、术语使用和格式保持一致
- **关注重点**：重点描述系统架构、核心模块和关键技术方案
- **图文结合**：使用图表辅助说明，提高文档可读性
- **适当详细**：在关键部分提供足够详细的说明，确保开发人员能够理解设计意图
- **考虑全面**：除功能需求外，也要考虑非功能性需求，如性能、安全、可靠性等
- **保持更新**：随着设计的深入，及时更新文档内容
### 3. 多人协作编写策略
- **明确分工**：按模块或专业领域划分编写任务，明确每人负责的部分
- **统一模板**：使用统一的文档模板和编写规范
- **定期评审**：定期组织文档评审会议，确保文档质量和一致性
- **版本控制**：使用Git等工具进行文档版本控制，跟踪文档变更
- **集中整合**：指定专人负责整合各部分文档，确保文档的完整性和一致性
### 4. 编写工具使用建议
- **使用Markdown**：采用Markdown格式编写文档，便于版本控制和协作
- **使用Cursor**：利用Cursor的智能提示和规则检查功能，提高编写效率
- **使用PlantUML/Mermaid**：使用PlantUML或Mermaid绘制架构图、流程图等
- **使用Git**：使用Git进行文档版本控制和协作管理
- **使用自动化工具**：使用自动化工具检查文档格式、拼写和一致性
## 四、后续工作建议
### 1. 文档评审与完善
- 组织技术评审会议，邀请架构师、技术负责人和关键开发人员参与
- 收集评审意见，针对性地修改和完善文档
- 进行文档质量检查，确保文档的完整性、准确性和一致性
### 2. 详细设计与开发
- 基于概要设计文档，进行详细设计，包括具体的类设计、算法设计等
- 按照设计文档指导开发工作，确保实现与设计保持一致
- 在开发过程中，根据实际情况适当调整设计，并更新文档
### 3. 文档维护与更新
- 建立文档变更管理机制，记录文档变更历史
- 根据系统演进情况，定期更新设计文档
- 将设计文档与代码库关联，确保文档与代码的一致性
## 五、常见问题与解决方案
### 1. 文档过于庞大，难以管理
- 采用模块化的文档结构，将文档分为多个独立的部分
- 建立文档索引，便于查找和导航
- 使用自动化工具生成目录和交叉引用
### 2. 文档与实际实现不一致
- 建立设计与开发的反馈机制，及时发现并解决不一致问题
- 在开发过程中，同步更新设计文档
- 定期进行文档审核，确保与实际实现保持一致
### 3. 多人协作导致风格不一致
- 制定统一的文档编写规范和模板
- 使用Cursor Rules自动检查文档风格和格式
- 指定专人负责文档的最终审核和整合
### 4. 文档内容难以理解
- 增加图表和示例，提高文档可读性
- 采用简洁明了的语言，避免晦涩难懂的技术术语
- 对关键概念和术语提供清晰的定义和解释

382
water_biz_system_architecture.md Normal file
View File

@ -0,0 +1,382 @@
# 福建水务营收系统架构概要设计
## 一、系统架构概述
福建水务营收系统采用现代化的分层架构设计，基于RuoYi-Vue-Pro和yudao-ui-admin-vue3框架进行开发，实现了前后端分离、模块化设计、微服务架构等技术特点，提供了高性能、高可靠性、高安全性的水务营收管理解决方案。
## 二、总体架构设计
### 1. 系统架构图
```mermaid
graph TD
Client[客户端层] --> FrontEnd[前端应用层]
FrontEnd --> Gateway[网关层]
Gateway --> Application[应用服务层]
Application --> Infrastructure[基础设施层]
Application --> Database[(数据存储层)]
subgraph 客户端层
WebBrowser[Web浏览器]
MobileApp[移动应用]
WeChat[微信小程序]
end
subgraph 前端应用层
Vue3[Vue3前端框架]
ElementPlus[Element Plus组件库]
VueRouter[Vue Router]
Pinia[Pinia状态管理]
end
subgraph 网关层
SpringCloudGateway[Spring Cloud Gateway]
Auth[认证鉴权]
RateLimit[限流]
LoadBalance[负载均衡]
end
subgraph 应用服务层
UserModule[用户管理模块]
MeterModule[水表管理模块]
ReadingModule[抄表管理模块]
BillingModule[收费管理模块]
AccountModule[账务管理模块]
ReportModule[报表管理模块]
SystemModule[系统管理模块]
end
subgraph 基础设施层
Redis[(Redis缓存)]
MQ[消息队列]
Storage[文件存储]
Schedule[定时任务]
end
subgraph 数据存储层
MySQL[(MySQL数据库)]
MongoDB[(MongoDB)]
end
```
### 2. 技术架构描述
#### 2.1 前端技术架构
福建水务营收系统前端基于yudao-ui-admin-vue3框架开发，主要技术组件包括：
- **框架**：Vue 3.x
- **UI组件库**：Element Plus
- **路由管理**：Vue Router 4.x
- **状态管理**：Pinia
- **HTTP客户端**：Axios
- **构建工具**：Vite
- **代码规范**：ESLint + Prettier
#### 2.2 后端技术架构
后端系统基于RuoYi-Vue-Pro框架开发，主要技术组件包括：
- **框架**：Spring Boot 2.7.x
- **ORM框架**：MyBatis Plus 3.5.x
- **权限框架**：Spring Security
- **缓存**：Redis
- **数据库**：MySQL 8.0
- **消息队列**：内置基于Redis的消息队列
- **文档**：Swagger / Knife4j
- **工作流**：Flowable
- **定时任务**：基于XXLJOB的分布式任务调度
## 三、系统分层设计
### 1. 应用分层
```
+---------------------------+
| 表现层（UI层） |
+---------------------------+
| 应用层（API层） |
+---------------------------+
| 业务层（Service层） |
+---------------------------+
| 数据访问层（DAO层） |
+---------------------------+
| 数据持久层 |
+---------------------------+
```
- **表现层**：负责与用户的交互，包括页面展示、数据校验等
- **应用层**：提供对外的API接口，处理请求参数，返回响应结果
- **业务层**：实现业务逻辑，处理业务规则和流程
- **数据访问层**：提供数据访问接口，进行数据CRUD操作
- **数据持久层**：负责数据的持久化存储
### 2. 模块划分
系统按照业务功能划分为以下核心模块：
```
+------------------------------------------+
| 系统共享模块 |
+------------------------------------------+
| 用户 | 水表 | 抄表 | 收费 | 账务 |
| 管理 | 管理 | 管理 | 管理 | 管理 |
+------------------------------------------+
| 票据 | 营业 | 报表 | 系统 | 集成 |
| 管理 | 网点 | 管理 | 管理 | 接口 |
+------------------------------------------+
| 基础设施模块 |
+------------------------------------------+
```
## 四、核心模块设计
### 1. 用户管理模块
负责系统用户的管理，包括用户注册、认证、授权等功能。基于RBAC（基于角色的访问控制）模型设计，支持细粒度的权限控制。
### 2. 水表管理模块
负责管理水表基础信息，包括水表安装、更换、拆除、维修等生命周期管理，支持普通水表、智能水表、IC卡水表等多种水表类型。
### 3. 抄表管理模块
负责水表读数的采集和管理，支持人工抄表、远传抄表、自报抄表等多种抄表方式，并提供异常数据处理、抄表任务分配等功能。
### 4. 收费管理模块
负责水费的计算、收取和管理，支持多种计费规则和阶梯水价，提供窗口收费、网上支付、银行代扣等多种缴费方式。
### 5. 账务管理模块
负责系统财务账务处理，包括收费入账、销账、退费、坏账处理等功能，与财务系统进行对接。
### 6. 票据管理模块
负责水费发票的开具、作废、查询等管理功能，支持电子发票和纸质发票。
### 7. 报表管理模块
提供系统各类统计报表，包括营收报表、抄表报表、用水分析报表等，支持多维度的数据分析和可视化展示。
### 8. 系统管理模块
提供系统基础管理功能，包括菜单管理、角色管理、权限管理、系统日志等。
## 五、数据库设计
### 1. 数据库架构
系统采用MySQL作为主要关系型数据库，Redis作为缓存数据库。数据库设计遵循以下原则：
- 采用分模块设计，各业务模块数据相对独立
- 合理使用索引，提高查询效率
- 使用存储过程处理复杂业务逻辑
- 采用适当的分表策略处理大数据量表
### 2. 主要数据实体
```mermaid
erDiagram
USER {
int id
string username
string password
int status
}
ROLE {
int id
string name
string code
}
CUSTOMER {
int id
string name
string address
string contact
int customer_type
}
METER {
int id
string meter_no
int meter_type
int status
float initial_reading
}
METER_READING {
int id
int meter_id
float reading
date reading_date
int reading_type
}
BILLING {
int id
int customer_id
int meter_id
float amount
date billing_date
int status
}
PAYMENT {
int id
int billing_id
float amount
date payment_date
int payment_method
}
USER ||--o{ ROLE : has
CUSTOMER ||--o{ METER : owns
METER ||--o{ METER_READING : generates
CUSTOMER ||--o{ BILLING : charged
BILLING ||--o{ PAYMENT : paid_by
```
## 六、接口设计
### 1. 外部接口
系统需要与以下外部系统进行集成：
- **银行支付系统**：提供水费代扣和支付功能
- **微信/支付宝支付**：提供移动端支付功能
- **税务发票系统**：对接电子发票开具功能
- **物联网平台**：对接智能水表数据采集功能
- **GIS地理信息系统**：提供地理位置服务
### 2. 内部接口
系统内部模块间通过RESTful API进行通信，接口设计遵循以下原则：
- 采用RESTful风格设计API
- 使用JWT进行接口认证
- 统一接口返回格式
- 接口版本控制
- 完善的接口文档
## 七、安全设计
### 1. 身份认证与授权
- 基于Spring Security实现身份认证
- 基于RBAC模型实现权限控制
- 支持OAuth2.0协议进行第三方授权
- 采用JWT实现无状态会话管理
### 2. 数据安全
- 敏感数据加密存储
- 数据库访问权限控制
- 数据备份与恢复策略
- 数据传输加密
### 3. 应用安全
- 防SQL注入
- 防XSS攻击
- 防CSRF攻击
- 接口防刷
## 八、高可用设计
### 1. 负载均衡
采用Nginx实现前端负载均衡，提高系统的并发处理能力和可用性。
### 2. 缓存策略
- 采用多级缓存策略，包括本地缓存和分布式缓存
- 热点数据缓存
- 合理的缓存失效策略
### 3. 灾备设计
- 数据库主从复制
- 定期数据备份
- 服务器集群部署
## 九、扩展性设计
### 1. 水平扩展
- 应用服务无状态设计，支持水平扩展
- 数据库读写分离，支持多数据源
### 2. 垂直扩展
- 模块化设计，支持功能独立扩展
- 插件化架构，支持新功能便捷集成
## 十、部署架构
### 1. 部署拓扑图
```mermaid
graph TD
subgraph 生产环境
LB[负载均衡] --> WS1[Web服务器1]
LB --> WS2[Web服务器2]
WS1 --> AS1[应用服务器1]
WS2 --> AS2[应用服务器2]
AS1 --> DB[(主数据库)]
AS2 --> DB
DB --> SDB[(从数据库)]
end
subgraph 灾备环境
DLB[负载均衡] --> DWS[Web服务器]
DWS --> DAS[应用服务器]
DAS --> DDB[(灾备数据库)]
end
DB -.-> DDB
```
### 2. 服务器配置要求
| 服务器类型 | 配置要求 | 数量 |
|---------|---------|-----|
| Web服务器 | 8核16G内存，100G SSD | 2 |
| 应用服务器 | 16核32G内存，200G SSD | 2 |
| 数据库服务器 | 16核64G内存，500G SSD，RAID 10 | 2 |
| 文件服务器 | 8核16G内存，2T存储 | 1 |
## 十一、开发与运维策略
### 1. 开发规范
- 统一的编码规范
- 代码审查机制
- 自动化测试
- 持续集成/持续部署(CI/CD)
### 2. 监控策略
- 系统性能监控
- 业务指标监控
- 异常监控与告警
- 用户行为分析
### 3. 运维工具
- 日志收集与分析工具
- 性能监控工具
- 部署自动化工具
- 数据库运维工具
## 十二、风险与应对策略
| 风险类型 | 风险描述 | 应对策略 |
|---------|---------|---------|
| 性能风险 | 高并发场景下系统性能下降 | 性能测试、缓存优化、数据库优化 |
| 安全风险 | 数据泄露、非授权访问 | 安全审计、加密措施、权限控制 |
| 可靠性风险 | 系统故障、数据丢失 | 高可用架构、数据备份、故障演练 |
| 兼容性风险 | 浏览器兼容性问题 | 兼容性测试、渐进增强设计 |
| 扩展性风险 | 业务增长导致系统扩展困难 | 模块化设计、松耦合架构 |