# 水电煤用量记录

**Repository Path**: roobooo/Usage-Monitor

## Basic Information

- **Project Name**: 水电煤用量记录
- **Description**: 用来记录水电煤的日常使用情况，对比历史数据
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-06
- **Last Updated**: 2026-03-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 家庭能耗管家 - 水电气全能版 (Utility Usage Monitor)

一个用于记录、分析和对比家庭水、电、气三种能源消耗情况的现代化Web应用，支持智能OCR识别账单、多视图数据分析和云端同步功能。

## ✨ 主要功能

### 📊 数据管理
- **三合一管理**: 支持电费、水费、燃气费的统一管理
- **手动录入**: 支持按月录入用量和费用数据
- **智能OCR**: 批量上传账单图片，自动识别并提取数据（支持支付宝/微信/国网/燃气公司账单）
- **数据导入**: 支持从JSON、文本文件导入历史数据
- **数据导出**: 导出所有数据为JSON格式（推荐使用 `data.json` 统一格式）
- **智能数据同步**: 优先读取 `data.json` 完整数据文件，自动回退到分文件格式
- **云端同步**: 支持从data文件夹同步数据，支持本地JSON存储

### 📈 多视图分析
- **月度对比分析**: 多年度用量和费用对比，支持按年份筛选
- **阶梯累计分析**: 年度累计用量与阶梯计价的突破点分析
- **智能字段识别**: 自动识别不同格式的用量和费用字段

### ⚙️ 阶梯计价设置
- **分类型设置**: 电费、水费、燃气费分别设置阶梯标准
- **实时状态**: 实时显示当前阶梯状态和累计用量
- **突破点分析**: 阶梯突破点可视化分析
- **自动保存**: 设置自动保存到本地存储

### 🎨 现代化界面
- **三色主题**: 电费（紫色）、水费（蓝色）、燃气（橙色）专属主题
- **响应式设计**: 支持桌面和移动端
- **平滑动画**: 流畅的交互效果和视觉反馈
- **实时统计**: 实时显示年度费用、用量、阶梯状态等关键指标

## 🚀 快速开始

### 在线使用
直接在浏览器中打开 `index.html` 文件即可使用，无需安装任何依赖。

### 本地部署
1. 克隆项目（选择其中一个）：
```bash
# 使用Gitee（国内访问快）
git clone https://gitee.com/roobooo/Usage-Monitor.git
cd Usage-Monitor

# 或使用GitHub
git clone https://github.com/covetworld-png/Usage-Monitor.git
cd Usage-Monitor
```

2. 启动本地服务器
```bash
# 使用Python
python -m http.server 8000

# 或使用Node.js
npx http-server -p 8000

# 或直接在浏览器中打开HTML文件
```

3. 在浏览器中访问 `http://localhost:8000`

## 📖 使用指南

### 1. 能源类型切换
应用顶部有三个标签页，分别对应：
- **电费**: 紫色主题，单位：度
- **水费**: 蓝色主题，单位：吨
- **燃气**: 橙色主题，单位：立方米

### 2. 阶梯计价设置
首次使用时，请根据当地政策分别设置三种能源的阶梯标准：
- **电费**: 第一阶梯：0-260度，第二阶梯：261-600度，第三阶梯：601度以上
- **水费**: 第一阶梯：0-180吨，第二阶梯：181-260吨，第三阶梯：261吨以上
- **燃气**: 第一阶梯：0-300立方米，第二阶梯：301-600立方米，第三阶梯：601立方米以上

设置会自动保存到本地，仅对当前类型生效。

### 3. 数据录入
#### 手动录入
在"手动添加"区域填写日期、用量和费用金额。

#### OCR智能识别
1. 点击"AI识别导入"区域或拖拽多张账单图片
2. 系统自动识别图片中的用量、费用和日期信息
3. 支持电费、水费、燃气账单的自动识别
4. 核对识别结果后确认导入

#### 文件导入
支持多种格式的数据导入：
1. **JSON格式**: 支持新版全量数据格式和旧版单类型数组格式
2. **文本格式**: 支持sample-data.txt格式的文本文件
3. **自动字段识别**: 智能识别不同字段名的用量和费用数据

文本文件格式示例：
```
2023-01 用电量：123.45度 电费：¥234.56
2023-02 用电量：145.67度 电费：¥267.89
```

#### 数据同步
- **本地存储**: 数据自动保存到浏览器LocalStorage
- **智能文件同步**: 支持从data文件夹同步JSON格式的数据文件
  - **推荐**: 使用统一格式的 `data.json` 文件（通过网页"导出数据"功能生成）
  - **兼容**: 也支持分开的文件格式（electricity.json, water.json, gas.json, config.json）
  - **智能加载**: 系统优先读取 `data.json`，如果不存在则回退读取分文件
- **云端同步**: 支持LeanCloud云端数据同步（需配置）

### 4. 数据分析
- **月度对比分析**: 查看多年用量趋势，识别高峰和低谷月份
- **阶梯累计分析**: 分析年度用量在阶梯计价中的分布情况
- **阶梯突破明细**: 查看每年进入二阶、三阶的具体月份和用量分布

## 🛠️ 技术栈

- **前端框架**: 原生HTML5 + CSS3 + JavaScript (ES6+)
- **UI框架**: Tailwind CSS
- **图表库**: Chart.js
- **OCR引擎**: Tesseract.js (支持中英文识别)
- **图标库**: Font Awesome
- **数据存储**: LocalStorage + 本地JSON文件 + LeanCloud云端同步
- **智能识别**: 自动字段识别算法，支持多种数据格式

## 🔧 数据格式说明

### 推荐的数据文件格式
项目支持两种数据文件格式，**推荐使用统一的 `data.json` 格式**：

#### 1. 统一格式（推荐）
将所有数据合并到一个 `data.json` 文件中，这是通过网页"导出数据"功能生成的完整格式：
```json
{
  "version": "2.0",
  "data": {
    "electricity": [
      {"date": "2024-01", "kwh": 748, "cost": 380, "timestamp": "...", "source": "manual"},
      {"date": "2024-02", "kwh": 762, "cost": 392.7, "timestamp": "...", "source": "manual"}
    ],
    "water": [
      {"date": "2024-01", "usage": 12.5, "cost": 45.6, "timestamp": "...", "source": "manual"}
    ],
    "gas": [
      {"date": "2024-01", "usage": 45.3, "cost": 123.4, "timestamp": "...", "source": "manual"}
    ]
  },
  "tierSettings": {
    "electricity": {"tier1": 260, "tier2": 600},
    "water": {"tier1": 180, "tier2": 260},
    "gas": {"tier1": 300, "tier2": 600}
  }
}
```

**使用方式**：
1. 在网页中编辑数据后，点击"导出数据"按钮下载 `data.json`
2. 将下载的 `data.json` 文件放置在项目的 `data/` 文件夹中
3. 刷新网页，系统会自动加载 `data.json` 中的完整数据

#### 2. 分开格式（兼容旧版）
将数据分开存储在多个文件中（系统会自动回退到这种格式）：
- `electricity.json`: 电费数据
- `water.json`: 水费数据
- `gas.json`: 燃气数据
- `config.json`: 阶梯设置（可选）

**注意**：系统优先读取 `data.json`，如果不存在则回退读取分文件。

### 数据字段支持
系统智能识别以下字段名：
- **用量字段**: `usage`, `kwh`, `amount`, `quantity`, `degree`, `用电`, `水量`, `气量`等
- **费用字段**: `cost`, `fee`, `price`, `total`, `费用`, `金额`等
- **日期字段**: `date` (格式: YYYY-MM)

### 导入文件格式
1. **新版JSON格式** (全量数据):
```json
{
  "version": "2.0",
  "data": {
    "electricity": [...],
    "water": [...],
    "gas": [...]
  },
  "tierSettings": {
    "electricity": {"tier1": 260, "tier2": 600},
    "water": {"tier1": 180, "tier2": 260},
    "gas": {"tier1": 300, "tier2": 600}
  }
}
```

2. **旧版JSON格式** (单类型数组):
```json
[
  {"date": "2023-01", "kwh": 123.45, "cost": 234.56},
  {"date": "2023-02", "usage": 145.67, "fee": 267.89}
]
```

### 示例文件
项目提供了以下示例文件供参考：

#### 统一格式示例
- `data/data.json`: 统一格式的完整数据文件（通过网页"导出数据"功能生成）
- `data/sample-data.json`: 统一格式的示例数据文件

#### 分开格式示例（兼容旧版）
- `data/sample-electricity.json`: 电费数据示例文件
- `data/sample-water.json`: 水费数据示例文件
- `data/sample-gas.json`: 燃气数据示例文件
- `data/sample-config.json`: 阶梯设置示例文件

#### 文本格式示例
- `sample-data.txt`: 文本格式的示例数据文件

**使用方式**：
1. **统一格式**: 将 `data.json` 或 `sample-data.json` 放置在 `data/` 文件夹中
2. **分开格式**: 将示例文件重命名为对应的文件名（去掉 `sample-` 前缀）并放置在 `data/` 文件夹中
   - `sample-electricity.json` → `electricity.json`
   - `sample-water.json` → `water.json`
   - `sample-gas.json` → `gas.json`
   - `sample-config.json` → `config.json`

## 📱 浏览器支持

- Chrome 80+
- Firefox 75+
- Safari 13+
- Edge 80+

## 🤝 贡献指南

欢迎提交Issue和Pull Request来改进这个项目！

### 开发环境设置
1. Fork本项目（可以选择Gitee或GitHub仓库）
2. 克隆到本地
3. 在浏览器中直接编辑和测试
4. 提交PR到对应的仓库

**注意**: 项目同时在Gitee和GitHub上维护，请根据您的网络环境选择合适的仓库。

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- 感谢 [Tesseract.js](https://github.com/naptha/tesseract.js) 提供OCR功能
- 感谢 [Chart.js](https://www.chartjs.org/) 提供图表可视化
- 感谢 [Tailwind CSS](https://tailwindcss.com/) 提供现代化UI组件
- 感谢 [LeanCloud](https://leancloud.app/) 提供云端数据存储服务

## 📞 联系方式

项目维护者: [roobooo](https://gitee.com/roobooo)

项目地址:
- **Gitee**: https://gitee.com/roobooo/Usage-Monitor.git
- **GitHub**: https://github.com/covetworld-png/Usage-Monitor.git

## 🔄 更新日志

### v2.1 - 双月计费支持与数据优化
- **双月计费支持**: 水费、燃气费支持双月计费模式，图表自动连线显示
- **智能数据读取**: 优先读取 `data.json` 统一格式文件，简化数据管理
- **图表样式优化**: 双月计费类型使用虚线连接和方形点标记
- **界面改进**: 添加双月计费标识，优化年份切换按钮样式
- **阶梯分析增强**: 新增累计费用分析模式

### v2.0 - 家庭能耗管家全能版
- **三合一管理**: 新增水费、燃气费管理功能
- **智能字段识别**: 自动识别多种字段名的用量和费用数据
- **多格式导入**: 支持JSON、文本文件导入，智能检测数据类型
- **本地文件同步**: 支持从data文件夹同步JSON格式数据
- **增强OCR**: 支持水电气三种账单的智能识别
- **分类型阶梯设置**: 电费、水费、燃气费分别设置阶梯标准
- **实时统计**: 实时显示年度费用、用量、阶梯状态等关键指标

---

**重要提示**:
1. 所有数据默认存储在浏览器本地，不会上传到服务器，确保您的隐私安全
2. 支持本地JSON文件存储，数据可保存在项目文件夹中
3. **推荐使用统一格式**的 `data.json` 文件，通过网页"导出数据"功能生成，便于备份和迁移
4. 系统支持智能字段识别，可自动适配不同格式的数据文件
5. 阶梯设置支持分类型配置，电费、水费、燃气费独立设置
6. **双月计费支持**: 水费、燃气费默认双月计费，图表自动连线显示
7. 可选云端同步功能，需自行配置LeanCloud应用
8. 建议定期导出数据备份，防止数据丢失</content>
<parameter name="filePath">/Users/fangweijun/Documents/claude_code_projects/usage-monitor/README.md