# 智慧水务管理系统 — 系统设计文档

> 版本：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 |