docs: add comprehensive README for open-source usage
This commit is contained in:
Xiaolan Bot
141
README.md
141
README.md
@@ -1 +1,140 @@
|
|||||||
power by gemini
|
# SubMind
|
||||||
|
|
||||||
|
一个基于 Telegram 的订阅管理机器人，帮助你记录订阅、设置提醒、查看支出统计并导入/导出数据。
|
||||||
|
|
||||||
|
## 功能特性
|
||||||
|
|
||||||
|
- ➕ 添加订阅（名称、费用、货币、分类、到期日、周期、续费方式、备注）
|
||||||
|
- 📋 列出订阅并查看详情
|
||||||
|
- 🗂️ 按分类浏览订阅
|
||||||
|
- ✏️ 编辑订阅信息
|
||||||
|
- 🗑️ 删除订阅
|
||||||
|
- 🔔 提醒设置（到期日提醒、提前 N 天提醒、手动续费一键确认）
|
||||||
|
- 📊 统计图（按分类汇总月均支出）
|
||||||
|
- 📥 CSV 导入
|
||||||
|
- 📤 CSV 导出
|
||||||
|
- 💱 多货币换算（支持缓存汇率）
|
||||||
|
|
||||||
|
## 技术栈
|
||||||
|
|
||||||
|
- Python 3.10+
|
||||||
|
- [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot)
|
||||||
|
- SQLite
|
||||||
|
- pandas + matplotlib
|
||||||
|
- dateparser
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
### 1) 克隆项目
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/zkysimon/SubMind.git
|
||||||
|
cd SubMind
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2) 安装依赖
|
||||||
|
|
||||||
|
建议使用虚拟环境：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m venv .venv
|
||||||
|
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||||
|
pip install -U pip
|
||||||
|
pip install python-telegram-bot pandas matplotlib python-dateutil dateparser python-dotenv requests
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3) 配置环境变量
|
||||||
|
|
||||||
|
复制并填写 `.env`：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp .env.example .env
|
||||||
|
```
|
||||||
|
|
||||||
|
`.env` 示例：
|
||||||
|
|
||||||
|
```env
|
||||||
|
TELEGRAM_TOKEN="<YOUR_TELEGRAM_BOT_TOKEN>"
|
||||||
|
EXCHANGE_API_KEY="<YOUR_EXCHANGE_API_KEY>"
|
||||||
|
```
|
||||||
|
|
||||||
|
说明：
|
||||||
|
- `TELEGRAM_TOKEN` 必填。
|
||||||
|
- `EXCHANGE_API_KEY` 可选（不填时不做在线汇率转换）。
|
||||||
|
|
||||||
|
### 4) 运行
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python SubMind.py
|
||||||
|
```
|
||||||
|
|
||||||
|
首次启动会自动初始化数据库（默认 `submind.db`）。
|
||||||
|
|
||||||
|
## Bot 命令
|
||||||
|
|
||||||
|
- `/start` 开始使用
|
||||||
|
- `/add_sub` 添加订阅
|
||||||
|
- `/list_subs` 查看所有订阅
|
||||||
|
- `/list_categories` 按分类查看
|
||||||
|
- `/stats` 查看统计图
|
||||||
|
- `/import` 导入 CSV
|
||||||
|
- `/export` 导出 CSV
|
||||||
|
- `/set_currency <CODE>` 设置主货币（例如 `USD`、`CNY`）
|
||||||
|
- `/help` 帮助
|
||||||
|
- `/cancel` 取消当前流程
|
||||||
|
|
||||||
|
## CSV 导入格式
|
||||||
|
|
||||||
|
导入文件需包含以下列：
|
||||||
|
|
||||||
|
- `name`
|
||||||
|
- `cost`
|
||||||
|
- `currency`
|
||||||
|
- `category`
|
||||||
|
- `next_due`
|
||||||
|
- `frequency_unit`（`day` / `week` / `month` / `year`）
|
||||||
|
- `frequency_value`（正整数）
|
||||||
|
- `renewal_type`（`auto` / `manual`）
|
||||||
|
- `notes`（可选）
|
||||||
|
|
||||||
|
示例：
|
||||||
|
|
||||||
|
```csv
|
||||||
|
name,cost,currency,category,next_due,frequency_unit,frequency_value,renewal_type,notes
|
||||||
|
Netflix,15.99,USD,影音,2026-03-01,month,1,auto,
|
||||||
|
VPS,60,CNY,开发,2026-03-12,month,1,manual,生产环境
|
||||||
|
```
|
||||||
|
|
||||||
|
## 数据与迁移
|
||||||
|
|
||||||
|
- 使用 SQLite（文件：`submind.db`）。
|
||||||
|
- 启动时自动执行兼容性检查和必要字段补齐。
|
||||||
|
- 建议升级前先备份数据库：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp submind.db submind.db.bak
|
||||||
|
```
|
||||||
|
|
||||||
|
## 常见问题
|
||||||
|
|
||||||
|
### 1) 统计图中文乱码怎么办？
|
||||||
|
程序会尝试下载中文字体到 `fonts/` 目录；若网络不可达，可手动放置字体文件。
|
||||||
|
|
||||||
|
### 2) 为什么汇率没变化？
|
||||||
|
请检查 `EXCHANGE_API_KEY` 是否配置正确。未配置时会使用原货币金额。
|
||||||
|
|
||||||
|
### 3) 旧消息按钮点不动？
|
||||||
|
更新后建议重新执行 `/list_categories` 或 `/list_subs` 刷新最新按钮。
|
||||||
|
|
||||||
|
## 安全说明
|
||||||
|
|
||||||
|
- 项目已对订阅编辑/提醒等关键路径做用户归属校验（`user_id`）。
|
||||||
|
- 数据库操作使用参数化查询，并对可编辑字段做白名单约束。
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
可按你的开源策略补充（例如 MIT）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
如果这个项目对你有帮助，欢迎 Star ⭐
|
||||||
Reference in New Issue
Block a user