# mariohuang233/hmlcrawl architecture

> Architecture diagram of the GitHub repository mariohuang233/hmlcrawl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mariohuang233/hmlcrawl
- Repository: https://github.com/mariohuang233/hmlcrawl

## Overview

这是家庭用电监控全栈应用：采集电表及米家设备日用电数据，存储后由 API 汇总为趋势、充值记录、设备能耗和助手答案，再由看板呈现；低余额与周期报告另有通知流程。保留了 README 明确列出的采集、问答、报告等能力。核心路由、启动与界面有源码摘录；部分服务实现未抽样，其细节连线仅依据 README 明示的职责，未推断服务间调用。

Main entry points: [`src/api/routes.js`](https://github.com/mariohuang233/hmlcrawl/blob/main/src/api/routes.js) (API 路由), [`frontend/src/App.tsx`](https://github.com/mariohuang233/hmlcrawl/blob/main/frontend/src/App.tsx) (React 看板), [`server.js`](https://github.com/mariohuang233/hmlcrawl/blob/main/server.js) (服务启动与调度), [`src/services/xiaomiEnergySync.js`](https://github.com/mariohuang233/hmlcrawl/blob/main/src/services/xiaomiEnergySync.js) (米家能耗同步)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["采集与接入"]
  node_server["服务启动与调度<br/>[server.js]"]
  node_crawler["电表采集器<br/>[crawler.js]"]
  node_xiaomi_sync["米家能耗同步"]
end

subgraph group_backend["服务端查询"]
  node_routes["API 路由<br/>[routes.js]"]
  node_snapshot["仪表盘快照"]
end

subgraph group_state["持久化状态"]
  node_usage[("电表读数<br/>[Usage.js]")]
  node_device_readings[("设备能耗读数")]
  node_alert_state[("告警状态<br/>[AlertState.js]")]
  node_delivery_state[("投递记录<br/>[ReportDelivery.js]")]
end

subgraph group_insights["分析与通知"]
  node_assistant["问答与用电分析"]
  node_device_analytics["设备能耗分析"]
  node_battery_alert["低余额告警"]
  node_report_scheduler["周期报告调度<br/>[dailyReport.js]"]
  node_report_delivery["报告投递"]
end

subgraph group_ui["看板体验"]
  node_dashboard["React 看板<br/>[App.tsx]"]
  node_assistant_ui["用电助手界面"]
  node_trend_ui["趋势与概览组件<br/>[Overview.tsx]"]
  node_device_ui["设备能耗组件<br/>[DeviceEnergy.tsx]"]
  node_api_client["前端 API 客户端<br/>[api.ts]"]
end

node_resident(("家庭用户"))
node_external_crawlers(("本地/移动爬虫"))
node_xiaomi_cloud(("米家云端"))
node_notification(("通知渠道"))

node_resident -->|"查看与提问"| node_dashboard
node_dashboard -->|"请求数据"| node_api_client
node_api_client -->|"调用 API"| node_routes
node_routes -->|"生成快照"| node_snapshot
node_snapshot -->|"读取汇总"| node_usage
node_routes -->|"查询与写入"| node_usage
node_dashboard -->|"展示趋势"| node_trend_ui
node_dashboard -->|"展示能耗"| node_device_ui
node_dashboard -->|"打开助手"| node_assistant_ui
node_assistant_ui -->|"提交问题"| node_api_client
node_routes -->|"分类并回答"| node_assistant
node_assistant -->|"读取用电数据"| node_usage
node_external_crawlers -->|"上报读数"| node_routes
node_server -->|"启动采集"| node_crawler
node_server -->|"启动同步"| node_xiaomi_sync
node_xiaomi_sync -.->|"读取日用电"| node_xiaomi_cloud
node_xiaomi_sync -->|"保存读数"| node_device_readings
node_routes -->|"查询设备分析"| node_device_analytics
node_device_analytics -->|"读取能耗"| node_device_readings
node_routes -->|"处理低余额"| node_battery_alert
node_battery_alert -->|"读写冷却状态"| node_alert_state
node_battery_alert -->|"发送告警"| node_notification
node_server -->|"启动报告任务"| node_report_scheduler
node_report_scheduler -->|"投递周期报告"| node_report_delivery
node_report_delivery -->|"锁定与记录"| node_delivery_state
node_report_delivery -->|"发送报告"| node_notification

click node_server "https://github.com/mariohuang233/hmlcrawl/blob/main/server.js"
click node_crawler "https://github.com/mariohuang233/hmlcrawl/blob/main/src/crawler/crawler.js"
click node_routes "https://github.com/mariohuang233/hmlcrawl/blob/main/src/api/routes.js"
click node_xiaomi_sync "https://github.com/mariohuang233/hmlcrawl/blob/main/src/services/xiaomiEnergySync.js"
click node_dashboard "https://github.com/mariohuang233/hmlcrawl/blob/main/frontend/src/App.tsx"
click node_assistant_ui "https://github.com/mariohuang233/hmlcrawl/blob/main/frontend/src/components/ElectricityAssistant.tsx"
click node_trend_ui "https://github.com/mariohuang233/hmlcrawl/blob/main/frontend/src/components/Overview.tsx"
click node_device_ui "https://github.com/mariohuang233/hmlcrawl/blob/main/frontend/src/components/DeviceEnergy.tsx"
click node_api_client "https://github.com/mariohuang233/hmlcrawl/blob/main/frontend/src/utils/api.ts"
click node_usage "https://github.com/mariohuang233/hmlcrawl/blob/main/src/models/Usage.js"
click node_device_readings "https://github.com/mariohuang233/hmlcrawl/blob/main/src/models/DeviceEnergyReading.js"
click node_assistant "https://github.com/mariohuang233/hmlcrawl/blob/main/src/services/electricityAssistant.js"
click node_device_analytics "https://github.com/mariohuang233/hmlcrawl/blob/main/src/services/deviceEnergyAnalytics.js"
click node_battery_alert "https://github.com/mariohuang233/hmlcrawl/blob/main/src/services/batteryAlertService.js"
click node_alert_state "https://github.com/mariohuang233/hmlcrawl/blob/main/src/models/AlertState.js"
click node_report_scheduler "https://github.com/mariohuang233/hmlcrawl/blob/main/src/services/dailyReport.js"
click node_report_delivery "https://github.com/mariohuang233/hmlcrawl/blob/main/src/services/reportNotificationService.js"
click node_delivery_state "https://github.com/mariohuang233/hmlcrawl/blob/main/src/models/ReportDelivery.js"
click node_snapshot "https://github.com/mariohuang233/hmlcrawl/blob/main/src/services/dashboardSnapshot.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_crawler,node_xiaomi_sync toneBlue
class node_routes,node_snapshot toneAmber
class node_usage,node_device_readings,node_alert_state,node_delivery_state toneMint
class node_assistant,node_device_analytics,node_battery_alert,node_report_scheduler,node_report_delivery toneRose
class node_dashboard,node_assistant_ui,node_trend_ui,node_device_ui,node_api_client,node_resident,node_external_crawlers,node_xiaomi_cloud,node_notification toneIndigo
```

## Components

### 采集与接入

- [服务启动与调度](https://github.com/mariohuang233/hmlcrawl/blob/main/server.js): `server.js`
- [电表采集器](https://github.com/mariohuang233/hmlcrawl/blob/main/src/crawler/crawler.js): `src/crawler/crawler.js`
- [米家能耗同步](https://github.com/mariohuang233/hmlcrawl/blob/main/src/services/xiaomiEnergySync.js): `src/services/xiaomiEnergySync.js`

### 服务端查询

- [API 路由](https://github.com/mariohuang233/hmlcrawl/blob/main/src/api/routes.js): `src/api/routes.js`
- [仪表盘快照](https://github.com/mariohuang233/hmlcrawl/blob/main/src/services/dashboardSnapshot.js): `src/services/dashboardSnapshot.js`

### 持久化状态

- [电表读数](https://github.com/mariohuang233/hmlcrawl/blob/main/src/models/Usage.js): `src/models/Usage.js`
- [设备能耗读数](https://github.com/mariohuang233/hmlcrawl/blob/main/src/models/DeviceEnergyReading.js): `src/models/DeviceEnergyReading.js`
- [告警状态](https://github.com/mariohuang233/hmlcrawl/blob/main/src/models/AlertState.js): `src/models/AlertState.js`
- [投递记录](https://github.com/mariohuang233/hmlcrawl/blob/main/src/models/ReportDelivery.js): `src/models/ReportDelivery.js`

### 分析与通知

- [问答与用电分析](https://github.com/mariohuang233/hmlcrawl/blob/main/src/services/electricityAssistant.js): `src/services/electricityAssistant.js`
- [设备能耗分析](https://github.com/mariohuang233/hmlcrawl/blob/main/src/services/deviceEnergyAnalytics.js): `src/services/deviceEnergyAnalytics.js`
- [低余额告警](https://github.com/mariohuang233/hmlcrawl/blob/main/src/services/batteryAlertService.js): `src/services/batteryAlertService.js`
- [周期报告调度](https://github.com/mariohuang233/hmlcrawl/blob/main/src/services/dailyReport.js): `src/services/dailyReport.js`
- [报告投递](https://github.com/mariohuang233/hmlcrawl/blob/main/src/services/reportNotificationService.js): `src/services/reportNotificationService.js`

### 看板体验

- [React 看板](https://github.com/mariohuang233/hmlcrawl/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [用电助手界面](https://github.com/mariohuang233/hmlcrawl/blob/main/frontend/src/components/ElectricityAssistant.tsx): `frontend/src/components/ElectricityAssistant.tsx`
- [趋势与概览组件](https://github.com/mariohuang233/hmlcrawl/blob/main/frontend/src/components/Overview.tsx): `frontend/src/components/Overview.tsx`
- [设备能耗组件](https://github.com/mariohuang233/hmlcrawl/blob/main/frontend/src/components/DeviceEnergy.tsx): `frontend/src/components/DeviceEnergy.tsx`
- [前端 API 客户端](https://github.com/mariohuang233/hmlcrawl/blob/main/frontend/src/utils/api.ts): `frontend/src/utils/api.ts`

### Other components

- **家庭用户**
- **本地/移动爬虫**
- **米家云端**
- **通知渠道**

## Connections

- 家庭用户 → React 看板: 查看与提问
- React 看板 → 前端 API 客户端: 请求数据
- 前端 API 客户端 → API 路由: 调用 API
- API 路由 → 仪表盘快照: 生成快照
- 仪表盘快照 → 电表读数: 读取汇总
- API 路由 → 电表读数: 查询与写入
- React 看板 → 趋势与概览组件: 展示趋势
- React 看板 → 设备能耗组件: 展示能耗
- React 看板 → 用电助手界面: 打开助手
- 用电助手界面 → 前端 API 客户端: 提交问题
- API 路由 → 问答与用电分析: 分类并回答
- 问答与用电分析 → 电表读数: 读取用电数据
- 本地/移动爬虫 → API 路由: 上报读数
- 服务启动与调度 → 电表采集器: 启动采集
- 服务启动与调度 → 米家能耗同步: 启动同步
- 米家能耗同步 → 米家云端: 读取日用电
- 米家能耗同步 → 设备能耗读数: 保存读数
- API 路由 → 设备能耗分析: 查询设备分析
- 设备能耗分析 → 设备能耗读数: 读取能耗
- API 路由 → 低余额告警: 处理低余额
- 低余额告警 → 告警状态: 读写冷却状态
- 低余额告警 → 通知渠道: 发送告警
- 服务启动与调度 → 周期报告调度: 启动报告任务
- 周期报告调度 → 报告投递: 投递周期报告
- 报告投递 → 投递记录: 锁定与记录
- 报告投递 → 通知渠道: 发送报告