architecture.md 22KB
architecture.md 22KB
智慧水务管理系统 — 系统设计文档
版本：v1.0 | 日期：2026-06-14 | 作者：bot_pm
一、技术选型
1.1 总体技术栈
| 层次 | 技术 | 版本要求 | 选型理由 |
|---|---|---|---|
| 后端框架 | Spring Cloud Alibaba | 2024.x | 微服务生态成熟，Nacos 服务治理 |
| 单体可回退 | Spring Boot 3.x | 3.3+ | 小规模可单体启动，渐进式拆分 |
| 前端框架 | Vue 3 + TypeScript | 3.5+ | 生态丰富，GIS 组件支持好 |
| 前端 UI | Element Plus + ECharts | 最新 | 大屏可视化 + 中后台表单 |
| 移动端 | Flutter 3.x | 3.24+ | 一套代码 Android/iOS |
| 网关 | Spring Cloud Gateway | 匹配 SC | 统一入口、限流、鉴权 |
| 服务注册/配置 | Nacos | 2.4+ | 服务发现 + 配置中心一体化 |
| 认证授权 | Sa-Token + OAuth2 | 最新 | 轻量级 RBAC，支持 SSO |
| 数据库 | PostgreSQL 16 + PostGIS | 16+ | 空间数据原生支持，替代 Oracle Spatial |
| 时序数据库 | TDengine 3.x | 3.3+ | 物联网时序数据写入性能优，SQL 兼容 |
| 缓存 | Redis 7 + Redisson | 7.2+ | 缓存 + 分布式锁 |
| 消息队列 | Apache Kafka | 3.8+ | IoT 高吞吐实时流 |
| 搜索引擎 | Elasticsearch | 8.x | 日志/文档全文检索 |
| 流程引擎 | Camunda 7 / Flowable | 最新 | BPMN 2.0，用户量大 |
| 对象存储 | MinIO / 阿里云 OSS | 最新 | 文件、视频存储 |
| 容器编排 | Docker Compose → K8s | 最新 | 分步过渡 |
1.2 选型对比与决策
GIS 引擎选型
| 方案 | 优势 | 劣势 | 推荐场景 |
|---|---|---|---|
| 超图 iServer | 国内水利项目标配，二三维一体化 | 授权费高(15-30万) | 预算充足 |
| 开源 MapServer+GeoServer | 免费 | 功能较弱，三维支持差 | 预算有限 |
| Leaflet + Cesium | 前端轻量三维 | 瓦片服务需另配 | 推荐混合方案 |
推荐：短期 GeoServer + Leaflet/Cesium；长期按甲方要求替换为超图。
视频 AI 引擎
| 方案 | 优势 | 劣势 |
|---|---|---|
| 自研训练（YOLOv8） | 可定制 | 需标注数据+3-5人月训练 |
| 采购成熟产品 | 开箱即用 | 10-20万授权费 |
| 对接现有视频平台 SDK | 复用已有投资 | 依赖厂商API |
推荐：优先对接甲方现有视频平台；人员闯入模型采用预训练 YOLO + 少量迁移学习。
二、系统架构
2.1 整体架构图
┌─────────────────────────────────────────────────────────────┐
│ 接入层 (Gateway) │
│ Nginx → Spring Cloud Gateway (限流/鉴权/路由) │
│ 统一入口: Web / Flutter APP / 微信小程序 / OpenAPI │
├─────────────────────────────────────────────────────────────┤
│ 应用服务层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │供水生产 │ │营业收费 │ │巡检管理 │ │大数据分析 │ │
│ │管理服务 │ │服务 │ │服务 │ │服务 │ │
│ ├──────────┤ ├──────────┤ ├──────────┤ ├──────────────┤ │
│ │总览/监测 │ │营收/报装 │ │任务/轨迹 │ │BI看板/报表 │ │
│ │水质/调度 │ │表务/客服 │ │统计/设置 │ │决策模型 │ │
│ │报警/数据 │ │微信/集抄 │ │巡检APP │ │大屏展示 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 流程引擎服务 │ │
│ │ Camunda BPMN → 流程定义/编排/监控 │ │
│ └──────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ 能力层 (中台) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │物联网平台│ │数据引擎 │ │工单引擎 │ │消息通知 │ │
│ │设备接入 │ │汇聚/治理 │ │任务流转 │ │短信/推送/WS │ │
│ │协议适配 │ │服务/目录 │ │跟踪/统计 │ │邮件/订阅 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 基础服务平台 │ │
│ │ 认证授权(Sa-Token) / 用户管理 / 部门管理 / 日志 │ │
│ └──────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ 数据存储层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │PostgreSQL│ │ TDengine │ │ Redis │ │Elasticsearch │ │
│ │+PostGIS │ │ 时序数据 │ │ 缓存/锁 │ │ 搜索/日志 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
│ ┌──────────┐ ┌──────────┐ │
│ │ MinIO │ │ Kafka │ │
│ │ 文件存储 │ │ 消息队列 │ │
│ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────────────────────┤
│ 外部集成层 │
│ ┌────────┐ ┌────────┐ ┌──────────┐ ┌────────┐ ┌────────┐ │
│ │ SCADA │ │ 视频 │ │ 支付宝 │ │ 微信 │ │GIS地图 │ │
│ │ 对接 │ │ 平台 │ │ 生活缴费 │ │ 支付 │ │ 服务 │ │
│ └────────┘ └────────┘ └──────────┘ └────────┘ └────────┘ │
└─────────────────────────────────────────────────────────────┘
2.2 微服务拆分
| 微服务 | 端口 | 职责 | 拆分优先级 |
|---|---|---|---|
wm-gateway |
8080 | API 网关/鉴权/限流 | P0 |
wm-base |
8081 | 用户/角色/菜单/部门/日志 | P0 |
wm-iot |
8082 | 物联网平台：设备接入/协议适配/设备管理 | P0 |
wm-data-engine |
8083 | 数据引擎：汇聚/治理/服务/目录 | P0 |
wm-bpm |
8084 | 流程引擎：Camunda 封装 | P0 |
wm-production |
8085 | 供水生产管理平台全部模块 | P1 |
wm-revenue |
8086 | 营业收费系统全部模块 | P1 |
wm-patrol |
8087 | 巡检管理系统 | P2 |
wm-bi |
8088 | 大数据分析/BI | P2 |
wm-notify |
8089 | 消息通知：短信/极光推送/WebSocket | P1 |
wm-job |
8090 | 定时任务调度(XXL-Job) | P1 |
三、关键模块设计
3.1 物联网平台
设备 → [MQTT Broker(EMQX)] → [Kafka] → [wm-iot]
↑ 设备认证 ↑ 规则引擎路由 ↑ 设备管理/影子/OTA
协议适配器模式：
wm-iot/adapters/
├── MqttAdapter.java # MQTT 适配
├── CoapAdapter.java # CoAP 适配
├── ModbusAdapter.java # Modbus TCP/RTU
├── HttpAdapter.java # HTTP 直连
└── DeviceModelMapper.java # 统一设备模型转换
- 设备影子：Redis 存储设备期望/上报状态，断线自动同步
- OTA 升级：MinIO 存储固件，设备心跳拉取更新
- 数据路由：EMQX 规则引擎 → Kafka Topic 分流（
iot.raw.{deviceType}）
3.2 数据引擎
数据流转：
数据源 → 采集适配 → Kafka → 实时流(Flink) → TDengine(时序)
↘ ↘
批量(Spark) → PostgreSQL(业务数据)
→ Elasticsearch(全文)
治理流水线：
原始数据 → 标准化 → 清洗 → 质控 → 关联 → 入仓
(水利标准映射) (缺失/异常) (质量评分) (血缘) (增量/全量)
3.3 GIS 集成
前端: Vue3 + Leaflet(2D) / Cesium(3D)
↕ WMS/WMTS/TMS
后端: GeoServer(瓦片服务) ← PostGIS(空间数据库)
↑
空间数据: 管网矢量(shp→PostGIS)、监测点位(动态图层)
3.4 报警引擎
IoT数据 → Kafka → wm-iot(数据消费)
↓
规则引擎(阈值判断)
↓
Redis(去重窗口)
↓
wm-notify(通知分发)
↓
┌───────┼────────┐
短信 APP推送 WebSocket(实时弹窗)
报警等级：🟢 提示 → 🟡 一般 → 🟠 严重 → 🔴 紧急
去重策略：同一设备+同一类型+N分钟内只告警一次。
3.5 调度推演引擎
预案模板库 → 参数填充 → 管网水力模型(EPANET) → 调度策略生成
↓
指令下发 → 执行跟踪 → 效果评估
- 爆管模拟：阀门关闭策略 → 影响区域分析 → 应急供水方案
- 水质异常：污染物扩散模拟 → 排放方案
四、数据库设计（核心表）
4.1 用户权限体系
-- 部门表
CREATE TABLE sys_dept (
id BIGINT PRIMARY KEY,
parent_id BIGINT,
dept_name VARCHAR(100),
dept_type VARCHAR(20), -- water_bureau(水利局)/water_company(水务公司)/ops(运维)
sort_order INT,
status TINYINT DEFAULT 1,
created_at TIMESTAMP DEFAULT NOW()
);
-- 用户表
CREATE TABLE sys_user (
id BIGINT PRIMARY KEY,
dept_id BIGINT REFERENCES sys_dept(id),
username VARCHAR(50) UNIQUE NOT NULL,
password VARCHAR(255) NOT NULL,
real_name VARCHAR(50),
phone VARCHAR(20),
email VARCHAR(100),
role_type VARCHAR(30), -- admin/leader/manager/operator/tech
status TINYINT DEFAULT 1,
created_at TIMESTAMP DEFAULT NOW()
);
-- 角色表
CREATE TABLE sys_role (
id BIGINT PRIMARY KEY,
role_name VARCHAR(50) UNIQUE,
role_key VARCHAR(50) UNIQUE, -- admin/supervisor/biz_manager/field_ops/tech_maintain
data_scope VARCHAR(20), -- ALL/DEPT/SELF
description VARCHAR(200),
created_at TIMESTAMP DEFAULT NOW()
);
-- 角色-用户关联
CREATE TABLE sys_user_role (
user_id BIGINT REFERENCES sys_user(id),
role_id BIGINT REFERENCES sys_role(id),
PRIMARY KEY (user_id, role_id)
);
4.2 设备管理（物联网）
-- 设备模型定义
CREATE TABLE iot_device_model (
id BIGINT PRIMARY KEY,
model_key VARCHAR(50) UNIQUE, -- 比如 water_meter_dn15
model_name VARCHAR(100), -- DN15远传水表
vendor VARCHAR(100), -- 厂商
protocol VARCHAR(20), -- MQTT/Modbus/CoAP
properties JSONB, -- 属性定义 [{key, name, unit, data_type, range}]
commands JSONB, -- 支持指令 [{key, name, params}]
created_at TIMESTAMP DEFAULT NOW()
);
-- 设备实例
CREATE TABLE iot_device (
id BIGINT PRIMARY KEY,
device_sn VARCHAR(100) UNIQUE, -- 设备序列号
device_name VARCHAR(200),
model_id BIGINT REFERENCES iot_device_model(id),
device_type VARCHAR(30), -- flow_meter/pressure/valve/water_quality/level
position_type VARCHAR(20), -- water_plant/pressure_station/pipe_network/village
loc_lng DOUBLE PRECISION, -- 经度
loc_lat DOUBLE PRECISION, -- 纬度
geom GEOMETRY(Point, 4326), -- PostGIS 空间坐标
area VARCHAR(50), -- 所属片区
station_id BIGINT, -- 所属站点
status VARCHAR(20), -- online/offline/maintenance/fault
last_report_time TIMESTAMP,
created_at TIMESTAMP DEFAULT NOW()
);
4.3 时序数据（TDengine）
-- TDengine 超级表：设备遥测数据
CREATE STABLE iot_telemetry (
ts TIMESTAMP,
device_sn NCHAR(100),
metric_key NCHAR(50),
metric_value DOUBLE,
quality TINYINT
) TAGS (
device_type NCHAR(30),
area NCHAR(50)
);
-- 按设备类型创建子表
CREATE TABLE flow_data USING iot_telemetry TAGS('flow_meter', '精芒片区');
CREATE TABLE press_data USING iot_telemetry TAGS('pressure', '托里片区');
CREATE TABLE wq_data USING iot_telemetry TAGS('water_quality', '一体化水厂');
4.4 营业收费
-- 用水户
CREATE TABLE rev_customer (
id BIGINT PRIMARY KEY,
customer_no VARCHAR(30) UNIQUE, -- 户号
customer_name VARCHAR(100),
customer_type VARCHAR(20), -- residential/business/enterprise/institution
area VARCHAR(50),
address VARCHAR(300),
phone VARCHAR(20),
id_card VARCHAR(18),
contract_no VARCHAR(50),
status VARCHAR(20) DEFAULT 'active',
created_at TIMESTAMP DEFAULT NOW()
);
-- 水表档案
CREATE TABLE rev_meter (
id BIGINT PRIMARY KEY,
meter_no VARCHAR(50) UNIQUE,
customer_id BIGINT REFERENCES rev_customer(id),
device_id BIGINT REFERENCES iot_device(id), -- 关联IoT设备
caliber VARCHAR(10), -- DN15/DN20/DN40...
meter_type VARCHAR(20), -- mechanical/ultrasonic/electromagnetic
initial_reading DECIMAL(10,2),
install_date DATE,
status VARCHAR(20), -- active/dismantled/scrapped/repaired
created_at TIMESTAMP DEFAULT NOW()
);
-- 抄表记录
CREATE TABLE rev_reading (
id BIGINT PRIMARY KEY,
meter_id BIGINT REFERENCES rev_meter(id),
reading_date DATE,
prev_reading DECIMAL(10,2),
curr_reading DECIMAL(10,2),
consumption DECIMAL(10,2), -- 用水量
read_type VARCHAR(20), -- manual/remote/estimate
reader_id BIGINT,
photo_url VARCHAR(500),
verified TINYINT DEFAULT 0,
created_at TIMESTAMP DEFAULT NOW()
);
-- 水费账单
CREATE TABLE rev_bill (
id BIGINT PRIMARY KEY,
customer_id BIGINT REFERENCES rev_customer(id),
bill_period VARCHAR(10), -- 2026-06
consumption DECIMAL(10,2),
water_fee DECIMAL(10,2),
sewage_fee DECIMAL(10,2),
total_fee DECIMAL(10,2),
paid_fee DECIMAL(10,2) DEFAULT 0,
status VARCHAR(20), -- pending/partial/paid/overdue
due_date DATE,
paid_at TIMESTAMP,
created_at TIMESTAMP DEFAULT NOW()
);
4.5 巡检系统
-- 巡检路线
CREATE TABLE patrol_route (
id BIGINT PRIMARY KEY,
route_name VARCHAR(100),
area VARCHAR(50),
route_points JSONB, -- [{seq, lng, lat, name, device_ids}]
estim_duration INT, -- 预计时长(分钟)
status TINYINT DEFAULT 1,
created_at TIMESTAMP DEFAULT NOW()
);
-- 巡检任务
CREATE TABLE patrol_task (
id BIGINT PRIMARY KEY,
route_id BIGINT REFERENCES patrol_route(id),
assignee_id BIGINT REFERENCES sys_user(id),
task_date DATE,
plan_start TIME,
plan_end TIME,
actual_start TIMESTAMP,
actual_end TIMESTAMP,
status VARCHAR(20), -- pending/in_progress/completed/expired
distance DECIMAL(8,2),
created_at TIMESTAMP DEFAULT NOW()
);
-- 巡检记录
CREATE TABLE patrol_record (
id BIGINT PRIMARY KEY,
task_id BIGINT REFERENCES patrol_task(id),
point_seq INT,
device_id BIGINT REFERENCES iot_device(id),
check_items JSONB, -- [{item, result, value, photo_url, remark}]
gps_lng DOUBLE PRECISION,
gps_lat DOUBLE PRECISION,
record_time TIMESTAMP,
created_at TIMESTAMP DEFAULT NOW()
);
4.6 报警管理
CREATE TABLE alert_rule (
id BIGINT PRIMARY KEY,
rule_name VARCHAR(100),
device_type VARCHAR(30),
metric_key VARCHAR(50),
alert_level VARCHAR(10), -- info/warning/critical/emergency
condition_expr VARCHAR(200), -- "> 0.5" 或 "ABS_DELTA > 10"
threshold_value VARCHAR(50),
debounce_sec INT DEFAULT 300, -- 去重窗口(秒)
notify_scheme_id BIGINT,
enabled TINYINT DEFAULT 1,
created_at TIMESTAMP DEFAULT NOW()
);
CREATE TABLE alert_event (
id BIGINT PRIMARY KEY,
rule_id BIGINT REFERENCES alert_rule(id),
device_id BIGINT REFERENCES iot_device(id),
device_sn VARCHAR(100),
metric_key VARCHAR(50),
metric_value DOUBLE,
threshold VARCHAR(50),
alert_level VARCHAR(10),
message VARCHAR(500),
confirmed_by BIGINT,
confirmed_at TIMESTAMP,
dispatched TINYINT DEFAULT 0, -- 是否已派单
resolved_at TIMESTAMP,
created_at TIMESTAMP DEFAULT NOW()
);
五、接口设计规范
5.1 RESTful API 规范
GET /api/v1/{resource} # 列表查询
GET /api/v1/{resource}/{id} # 详情查询
POST /api/v1/{resource} # 创建
PUT /api/v1/{resource}/{id} # 全量更新
PATCH /api/v1/{resource}/{id} # 部分更新
DELETE /api/v1/{resource}/{id} # 删除
5.2 统一响应格式
{
"code": 200,
"message": "success",
"data": {},
"timestamp": 1718340000000
}
5.3 错误码规范
| 范围 | 说明 |
|---|---|
| 200 | 成功 |
| 400-499 | 客户端错误（参数/权限/资源） |
| 500-599 | 服务端错误 |
| 10001-10099 | 物联网相关 |
| 20001-20099 | 营业收费相关 |
| 30001-30099 | 供水生产相关 |
六、部署方案
6.1 开发环境
Docker Compose 单机部署
├── PostgreSQL 16 + PostGIS
├── TDengine 3.x
├── Redis 7
├── Kafka (单节点)
├── Elasticsearch
├── MinIO
├── EMQX
├── Nacos
└── 各微服务 JAR
6.2 生产环境
K8s 集群 (3 master + 5 worker)
├── ingress-nginx (LB)
├── Spring Cloud Gateway (ClusterIP)
├── 微服务 Pods (HPA自动扩缩)
├── PostgreSQL (主从)
├── TDengine Cluster (3节点)
├── Redis Cluster (6节点)
├── Kafka Cluster (3节点)
├── Elasticsearch Cluster (3节点)
├── MinIO (分布式 4节点)
└── EMQX Cluster (3节点)
6.3 监控体系
| 组件 | 用途 |
|---|---|
| Prometheus + Grafana | 系统指标 + 业务指标 |
| SkyWalking | 分布式链路追踪 |
| ELK (ES + Logstash + Filebeat) | 日志收集分析 |
| AlertManager | 告警管理 |
七、安全设计
| 层面 | 措施 |
|---|---|
| 传输安全 | HTTPS/TLS 1.3，MQTT over TLS |
| 认证 | JWT + Sa-Token，设备端 X.509证书 |
| 授权 | RBAC + 数据权限(片区隔离) |
| 审计 | 全操作日志(登录/操作/异常)，不可删除 |
| 数据安全 | 敏感字段 AES 加密，数据库连接 SSL |
| 等保 | 不低于等保二级，关键业务等保三级 |
| 防护 | SQL注入/ XSS/ CSRF/ DDoS限流 |
八、关键技术决策记录
| # | 决策 | 方案 | 理由 |
|---|---|---|---|
| 1 | GIS引擎 | GeoServer + Leaflet/Cesium | 开源可控，支持标准WMS/WMTS，可平滑迁移超图 |
| 2 | 时序库 | TDengine 3.x | 物联网写入性能优(亿级/天)，SQL兼容，运维简单 |
| 3 | 消息队列 | Kafka | IoT 高吞吐实时流，Exactly-Once 语义 |
| 4 | 流程引擎 | Camunda 7 | BPMN 2.0 标准，Java 原生嵌入，中文社区 |
| 5 | 移动端 | Flutter | 一套代码双端，GIS 地图插件成熟 |
| 6 | 微服务框架 | Spring Cloud Alibaba | Nacos注册配置一体化，Sentinel限流 |
| 7 | API规范 | RESTful + WebSocket(实时) | 前后端分离标准，WS 用于实时监测和报警推送 |
| 8 | 视频AI | 预训练 YOLOv8 + 迁移学习 | 人员闯入场景单一，少量标注即可达到85%+精度 |
文档版本
| 版本 | 日期 | 修订 | 修订人 |
|---|---|---|---|
| v1.0 | 2026-06-14 | 初始版本：技术选型/架构/数据库/部署 | bot_pm |