diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 00000000..e221c616 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,570 @@ +# 智慧水务管理系统 — 系统设计文档 + +> 版本：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 用户权限体系 + +```sql +-- 部门表 +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 设备管理（物联网） + +```sql +-- 设备模型定义 +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） + +```sql +-- 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 营业收费 + +```sql +-- 用水户 +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 巡检系统 + +```sql +-- 巡检路线 +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 报警管理 + +```sql +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 统一响应格式 + +```json +{ + "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 |