新增系统设计文档：技术选型/架构/数据库/接口/部署/安全/决策记录

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 |