diff --git a/CODEBASE_OVERVIEW.md b/CODEBASE_OVERVIEW.md new file mode 100644 index 0000000..6974ca9 --- /dev/null +++ b/CODEBASE_OVERVIEW.md @@ -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. **测试缺失**：测试文件均为样板代码，无实际测试逻辑