lodefusi/HarmonyOS--waterapp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

上传文件至「/」

Browse Source
This commit is contained in:
lodefusi
2026-07-13 04:23:56 +00:00
parent e3c810b1a6
commit fa5de4d10f
1 changed files with 293 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CODEBASE_OVERVIEW.md
+293
View File
@@ -0,0 +1,293 @@
# 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. **测试缺失**：测试文件均为样板代码，无实际测试逻辑