294 lines
13 KiB
Markdown
294 lines
13 KiB
Markdown
# 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 元素
|
||
|
||
---
|
||
|
||
## 已知问题
|
||
|
||
1. **缺失组件**：`AiPredict.ets` 被 `Details.ets` 导入但不存在，切换至该 Tab 会导致应用崩溃
|
||
2. **硬编码凭据**：`Config.ets` 和 `ContrastAnalysis.ets` 中包含明文 API Key
|
||
3. **硬编码 IP**：`192.168.31.100`、`192.168.31.26` 遍布代码
|
||
4. **重复文件**：`ApiService.ets` / `ApiService.ts.ets`、`AlarmItemInterface.ets` / `Alarmltemlnterface.ets`
|
||
5. **模拟数据依赖**：所有组件在 API 失败时回退至硬编码模拟数据，生产环境缺乏降级策略
|
||
6. **测试缺失**：测试文件均为样板代码，无实际测试逻辑
|