# 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>"
UPDATE_OWNER_ID="<YOUR_TELEGRAM_USER_ID>"
AUTO_UPDATE_REMOTE="https://git.llc/zimk/SubMind.git"
AUTO_UPDATE_BRANCH="main"
```

说明：
- `TELEGRAM_TOKEN` 必填。
- `EXCHANGE_API_KEY` 可选（不填时不做在线汇率转换）。
- `UPDATE_OWNER_ID` 可选（建议配置为你的 Telegram 用户 ID，仅该用户可执行 `/update`）。
- `AUTO_UPDATE_REMOTE` 可选（默认 `https://git.llc/zimk/SubMind.git`）。
- `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 ⭐