144 lines
3.5 KiB
Markdown
144 lines
3.5 KiB
Markdown
# 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 -r requirements.txt
|
||
```
|
||
|
||
### 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` 可选（不填时不做在线汇率转换）。
|
||
- `UPDATE_OWNER_ID` 可选（建议配置为你的 Telegram 用户 ID，仅该用户可执行 `/update`）。
|
||
- `AUTO_UPDATE_REMOTE` 可选（默认 `gitllc`）。
|
||
- `AUTO_UPDATE_BRANCH` 可选（默认 `main`）。
|
||
|
||
### 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`）
|
||
- `/update` 拉取最新代码、安装依赖并自动重启（仅 `UPDATE_OWNER_ID` 指定用户可用）
|
||
- `/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 ⭐ |