13 KiB
13 KiB
Waterapp — 代码库总览
项目简介
Waterapp 是一款基于 华为鸿蒙（HarmonyOS / OpenHarmony） 原生开发的水生态全流程管理系统，结合 AI 能力实现实时水质监测、数据分析与预警。应用采用 ArkUI（ArkTS）框架构建，同时包含一个 Node.js MQTT 后端用于数据模拟与消息代理。
核心功能
- 实时水质六项指标监测（水温、pH、电导率、COD、氨氮、余氯）
- ECharts 图表可视化
- 设备管理（绑定/列表/状态查看）
- 设备报警追踪与统计分析
- 六项水质指标年度对比分析
- AI 智能分析（Dify API / OpenAI 兼容 API）
- 碳汇计算与趋势展示
- 用户登录注册
技术栈
| 层级 | 技术 |
|---|---|
| 平台 | HarmonyOS / OpenHarmony 6.x+（API 22-23） |
| UI 框架 | ArkUI（声明式 UI，ArkTS 语言） |
| 构建系统 | Hvigor |
| 包管理器 | Ohpm |
| 开发工具 | DevEco Studio |
| 跨平台 | ArkUI-X（支持 Android / iOS 导出） |
| HTTP 客户端 | @kit.NetworkKit |
| MQTT | @ohos/mqtt |
| 图表 | ECharts 5.x（WebView 内嵌） |
| AI API | Dify API（主）+ OpenAI 兼容 API（备用） |
| 后端 | Node.js + aedes（MQTT Broker）+ mqtt 客户端 |
| 测试 | @ohos/hypium + @ohos/hamock |
目录结构
Waterapp/
├── AppScope/ # 应用级资源
│ ├── app.json5 # 应用元数据（bundleName、版本号等）
│ └── resources/base/
│ ├── element/string.json # 应用名称字符串
│ └── media/ # 自适应图标（前景/背景/layered_image）
│
├── entry/ # 主模块（entry 类型）
│ ├── build-profile.json5 # 模块构建配置
│ ├── hvigorfile.ts # 模块 Hvigor 构建脚本
│ ├── oh-package.json5 # 模块 Ohpm 包配置
│ ├── obfuscation-rules.txt # 代码混淆规则
│ └── src/
│ ├── main/
│ │ ├── module.json5 # 模块清单（权限、abilities、deviceTypes）
│ │ ├── ets/
│ │ │ ├── entryability/
│ │ │ │ └── EntryAbility.ets # 应用入口（UIAbility）
│ │ │ ├── pages/
│ │ │ │ ├── Login.ets # 登录/注册页
│ │ │ │ ├── Index.ets # 主首页（Tab 导航）
│ │ │ │ └── Details.ets # 设备详情页（Tab 导航）
│ │ │ ├── components/
│ │ │ │ ├── Equipment.ets # 设备管理列表
│ │ │ │ ├── Add.ets # 添加/绑定设备
│ │ │ │ ├── user.ets # 用户个人中心
│ │ │ │ ├── WaterMonitor.ets # 实时水质监测面板
│ │ │ │ ├── DeviceAlarm.ets # 设备报警列表与统计
│ │ │ │ ├── ContrastAnalysis.ets # 对比分析 + AI 分析
│ │ │ │ └── CarbonCalc.ets # 碳汇计算
│ │ │ ├── utils/
│ │ │ │ ├── Config.ets # 应用配置常量（API URL、密钥等）
│ │ │ │ ├── RequestUtil.ets # HTTP 请求工具（GET/POST/PUT）
│ │ │ │ ├── ApiService.ets # API 服务层（主版本）
│ │ │ │ ├── ApiService.ts.ets # API 服务层（备用版本）
│ │ │ │ └── MqttService.ets # MQTT 客户端服务
│ │ │ └── model/
│ │ │ ├── LoginInterface.ets
│ │ │ ├── UserInfoInterface.ets
│ │ │ ├── DeviceListInterface.ets
│ │ │ ├── AlarmItemInterface.ets
│ │ │ ├── Alarmltemlnterface.ets # 重复文件（拼写错误）
│ │ │ ├── AlarmStatisticsInterface.ets
│ │ │ ├── CarbonInfoInterface.ets
│ │ │ ├── StatisticalInterface.ets
│ │ │ ├── EutrophicationItemInterface.ets
│ │ │ ├── SeaRangeInterface.ets
│ │ │ ├── WaterTemperatureStore.ets
│ │ │ ├── AiMessageInterface.ets
│ │ │ ├── OpenAiRequestBody.ets
│ │ │ ├── DifyRequestBody.ets
│ │ │ └── RequestModel.ets
│ │ ├── resources/
│ │ │ ├── base/
│ │ │ │ ├── element/ # string.json / color.json / float.json
│ │ │ │ ├── media/ # 启动图标、自适应图标
│ │ │ │ └── profile/
│ │ │ │ └── main_pages.json # 路由配置（3 个页面）
│ │ │ └── rawfile/ # 原始资源（图标 + ECharts HTML）
│ │ │ ├── Equipment/ # 设备图标
│ │ │ ├── Login/ # 登录图标
│ │ │ ├── add/ # 添加设备图标
│ │ │ ├── daohang/ # 导航栏图标（5 个标签）
│ │ │ ├── index_false/ # 未选中标签图标
│ │ │ ├── index_true/ # 选中标签图标
│ │ │ ├── user/ # 用户页图标
│ │ │ ├── ces/ # 地图图片
│ │ │ └── chart/ # ECharts HTML 文件
│ │ │ ├── line_chart.html # 实时水质折线图
│ │ │ ├── carbon_chart.html # 碳汇趋势图
│ │ │ └── contrast_chart.html # 对比分析图
│ ├── mock/
│ │ └── mock-config.json5 # Mock 配置（空）
│ ├── ohosTest/ # 设备端测试
│ │ └── ets/test/
│ │ ├── List.test.ets
│ │ └── Ability.test.ets
│ └── test/ # 本地单元测试
│ ├── List.test.ets
│ └── LocalUnit.test.ets
│
├── mqtt-backend/ # Node.js MQTT 后端
│ ├── package.json # 依赖（aedes, mqtt）
│ ├── server.js # MQTT Broker（aedes + TCP 服务器）
│ ├── simulator.js # 模拟水质数据生成器
│ └── README.md # 后端使用说明
│
├── .arkui-x/ # ArkUI-X 跨平台配置
│ ├── arkui-x-config.json5
│ ├── android/ # Android 平台输出
│ └── ios/ # iOS 平台输出
│
├── .hvigor/ # Hvigor 构建缓存
├── .idea/ # IDE 配置
├── oh_modules/ # Ohpm 依赖
├── build-profile.json5 # 应用级构建配置
├── hvigorfile.ts # 根级 Hvigor 构建脚本
├── oh-package.json5 # 根级 Ohpm 依赖
├── oh-package-lock.json5 # 依赖锁文件
├── local.properties # 本地属性（指向 ArkUI-X SDK）
├── code-linter.json5 # 代码检查规则
└── .gitignore
页面路由与导航
应用采用 两层 Tab 导航架构：
第一层：Index.ets（主首页，3 个 Tab）
| Tab | 组件 | 功能 |
|---|---|---|
| 设备 | Equipment |
设备列表卡片，点击进入详情 |
| 添加 | Add |
绑定新设备表单 |
| 我的 | User |
个人中心、统计概览、退出登录 |
第二层：Details.ets（设备详情，5 个 Tab）
| Tab | 组件 | 功能 |
|---|---|---|
| 水情检测 | WaterMonitor |
MQTT 实时水质数据 + ECharts 折线图 |
| 设备报警 | DeviceAlarm |
报警列表、统计、点位地图 |
| AI 预测 | AiPredict |
组件缺失，选中会崩溃 |
| 对比分析 | ContrastAnalysis |
六项指标年度对比 + AI 分析 |
| 碳汇计算 | CarbonCalc |
碳汇能力统计与趋势图 |
页面间使用 router.pushUrl() 导航，数据通过 AppStorage 传递。
状态管理
使用 HarmonyOS 内置 AppStorage 进行全局状态管理：
| 键 | 类型 | 用途 |
|---|---|---|
token |
string | 认证令牌（登录设置，退出删除） |
point |
object | 当前选中设备（设备列表设置，详情页读取） |
newDevice |
object | 新绑定设备（添加页设置，设备列表消费） |
组件内部使用 @State 管理局部 UI 状态。
数据流架构
MQTT 设备 → MQTT Broker (server.js) → @ohos/mqtt (MqttService.ets)
→ EventEmitter → WaterMonitor 组件 → ECharts 图表
HTTP API (:8080) → RequestUtil.ets → ApiService.ets → 各组件
AI API (Dify / Volcengine) → ContrastAnalysis 组件（SSE 流式调用）
各文件详细说明
应用入口
EntryAbility.ets — 继承 UIAbility，在 onWindowStageCreate 中加载 pages/Login 作为首页。处理应用生命周期（创建、销毁、前后台切换）。
页面
Login.ets — 登录/注册页。支持测试账号（test / 123456）和 HTTP API 登录。含光晕动画和波纹效果。标题："鸿蒙+AI水生态全流程管理系统"。
Index.ets — 主首页。深色科技蓝渐变主题，含 3 个 Tab 的底部导航栏。
Details.ets — 设备详情页。从 AppStorage('point') 读取当前设备，含 5 个 Tab 的底部导航栏。
组件
Equipment.ets — 设备卡片列表，显示名称、编号、状态（正常运行/异常报警）。含两个硬编码初始设备（长江监测点 A、B）。点击进入详情页。
Add.ets — 设备绑定表单。输入设备编号和名称，通过 AppStorage 传递给设备列表。
user.ets — 个人中心。含头像、统计卡片（设备总数/异常数）、菜单项（报告生成 TODO、系统设置 TODO、退出登录）、版本信息。
WaterMonitor.ets — 核心监测组件：
- MQTT 连接（
tcp://192.168.31.100:1883，主题sea_status） - 显示 4 个基础指标（水温、pH、电导率、COD）+ 氨氮 + 余氯
- ECharts WebView 实时折线图（5 秒更新）
- 无 MQTT 数据时回退至模拟数据
DeviceAlarm.ets — 报警监控：
- 报警统计（总数 + 水质超标数）
- 设备点位地图
- 按时间段统计（今日/本周/本月）
- 报警记录列表（含当前值 vs 标准值）
- 5 条模拟报警 + API 真实数据
ContrastAnalysis.ets — 对比分析：
- 六项指标切换（水温、COD、pH、余氯、电导率、氨氮）
- 月度年度趋势 ECharts 图
- AI 分析：SSE 流式调用 Dify API
- 错误状态处理（网络/API/空数据）
CarbonCalc.ets — 碳汇计算：
- 3 张统计卡片（上月平均温度、碳汇能力、平均 pH）
- 6 个月碳汇趋势 ECharts 图
- 监测点分布地图（4 个模拟点 + API 数据）
工具/服务
Config.ets — 应用配置常量：
| 常量 | 值 |
|---|---|
BASE_URL |
http://192.168.31.100:8080 |
AI_PRIMARY_URL |
http://192.168.31.26 |
AI_BACKUP_URL |
https://ark.cn-beijing.volces.com |
AI_BACKUP_MODEL |
doubao-seed-2-0-code-preview-260215 |
TIMEOUT |
30000ms |
RequestUtil.ets — HTTP 工具类，封装 GET/POST/PUT 请求，支持 Bearer Token 认证。
ApiService.ets — API 端点封装：登录、注册、设备列表、水质数据、报警、碳汇等。
MqttService.ets — MQTT 单例客户端。连接 tcp://192.168.31.100:1883，订阅 sea_status 主题，通过 EventEmitter 广播数据。
模型（14 个接口文件）
定义应用中所有数据结构：登录/用户/设备/报警/碳汇/水质指标/AI 消息等。
图表（rawfile HTML）
- line_chart.html — 余氯 + 氨氮实时双线图
- carbon_chart.html — 12 个月碳汇趋势面积图
- contrast_chart.html — 年度指标对比图（含最值标记）
设计主题
全应用统一使用科技蓝/水质主题：
- 深色渐变背景（
#0a1628→#0d2847→#1677FF） - 荧光绿强调色（
#00FF88） - 指标卡片红/橙/紫色编码
- 毛玻璃/发光效果 UI 元素
已知问题
- 缺失组件：
AiPredict.ets被Details.ets导入但不存在，切换至该 Tab 会导致应用崩溃 - 硬编码凭据：
Config.ets和ContrastAnalysis.ets中包含明文 API Key - 硬编码 IP：
192.168.31.100、192.168.31.26遍布代码 - 重复文件：
ApiService.ets/ApiService.ts.ets、AlarmItemInterface.ets/Alarmltemlnterface.ets - 模拟数据依赖：所有组件在 API 失败时回退至硬编码模拟数据，生产环境缺乏降级策略
- 测试缺失：测试文件均为样板代码，无实际测试逻辑