# 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. **测试缺失**：测试文件均为样板代码，无实际测试逻辑