kt财务机器人

## 📋 目录
1. [系统概述](#系统概述)
2. [核心功能](#核心功能)
3. [技术架构](#技术架构)
4. [配置参数](#配置参数)
5. [API接口](#api接口)
6. [数据库结构](#数据库结构)
7. [部署说明](#部署说明)
8. [使用指南](#使用指南)
9. [故障排查](#故障排查)
10. [维护指南](#维护指南)

---

## 系统概述

### 基本信息
- **项目名称**: KT财务管家 Telegram Bot
- **机器人用户名**: @ktyyds_bot
- **版本**: 2.0
- **开发语言**: Python 3.13
- **运行平台**: macOS (Darwin 25.1.0)
- **部署时间**: 2025-10-14

### 功能定位
本机器人是一个完整的财务管理系统，与网站数据库实时双向同步，支持交易记录查询、手动添加、实时推送等功能。

---

## 核心功能

### 1. 交易记录查询
#### 1.1 查看历史记录
- **功能**: 分批显示所有交易记录
- **特点**:
  - 每批30条记录
  - 按时间倒序排列（最新在前）
  - 实时从数据库读取
  - 显示总金额和交易笔数

#### 1.2 按年查询
- 动态生成年份按钮
- 显示该年所有交易
- 统计年度总金额

#### 1.3 按月查询
- 支持2024-2025年月份查询
- 可切换年份
- 显示月度交易明细和合计

#### 1.4 按日期查询
- 两步选择：先选月份，再选日期
- 显示当日所有交易详情
- 支持多币种显示

#### 1.5 关键词查询（智能搜索）
- **支持字段**: 描述、金额、币种、日期、交易类型
- **搜索逻辑**:
  - 空格分隔 = AND逻辑（同时满足）
  - `|` 或 `或` = OR逻辑（满足任一）
  - 引号 `"` = 精确匹配短语
- **示例**:
  - `午餐 USDT` → 同时包含"午餐"和"USDT"
  - `午餐|晚餐` → 包含"午餐"或"晚餐"
  - `"工资发放"` → 精确匹配"工资发放"
- **限制**: 最多显示50条，分批30条发送

### 2. 手动添加交易
- **支持类型**: 收入、支出
- **支持币种**: USDT、CNY
- **权限控制**:
  - 白名单用户免密码
  - 普通用户需验证密码
  - 密码验证在本次启动期间有效
- **数据流程**:
  1. 机器人验证权限
  2. 输入交易信息
  3. 保存到数据库
  4. 广播通知所有订阅用户

### 3. 实时推送功能
- **开启/关闭**: 在"我的设置"中切换
- **推送触发条件**:
  - 网站创建新交易 → 推送给所有订阅用户
  - 网站删除交易 → 通知所有订阅用户
  - 机器人手动添加 → 广播给所有订阅用户
- **推送内容**:
  - 交易类型、金额、币种
  - 交易日期、描述
  - 项目、备注信息

### 4. 用户管理（管理员功能）
- 查看所有用户列表
- 查看用户权限状态（管理员/已禁用）
- 管理密码验证限制
- 白名单管理

### 5. 快捷命令
- `/start` - 显示主菜单
- `/status` - 查看订阅状态
- `/history` - 查看历史记录
- `/query` - 查询记录

---

## 技术架构

### 系统架构图
```
┌─────────────────┐      ┌──────────────────┐      ┌─────────────────┐
│  Telegram API   │◄────►│  Python Bot      │◄────►│  SQLite DB      │
│                 │      │  (telegram_       │      │  (finance_      │
│                 │      │   webhook_bot.py) │      │   remote.db)    │
└─────────────────┘      └──────────────────┘      └─────────────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │  FastAPI Webhook │
                         │  (Port 8889)     │
                         └──────────────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │  网站系统API     │
                         │  (创建/删除交易) │
                         └──────────────────┘
```

### 核心技术栈
- **Bot框架**: python-telegram-bot (20.x)
- **Web服务**: FastAPI + Uvicorn
- **数据库**: SQLite 3
- **定时任务**: APScheduler
- **异步处理**: asyncio
- **HTTP客户端**: httpx
- **日志**: Python logging

### 文件结构
```
/Users/fuwuqi/
├── telegram_webhook_bot.py    # 主程序（3500+行）
├── bot.pid                     # 进程ID文件
├── bot.log                     # 运行日志
├── bot_users.json              # 用户数据
├── finance_remote.db           # 财务数据库
├── deleted_transaction_ids.txt # 已删除交易ID
├── keep_bot_alive.sh           # 守护脚本
├── guardian.log                # 守护日志
└── set_bot_commands.py         # 命令菜单设置```

---

## 配置参数

### 1. Telegram Bot 配置
```python
# Bot Token (敏感信息)
BOT_TOKEN = "8422152380:AAFH5AfUHRdbfSzDPIfGHexSRTUqL6R-ok0"

# Webhook配置
WEBHOOK_HOST = "192.168.9.28"
WEBHOOK_PORT = 8889
WEBHOOK_PATH = "/webhook/transaction"
WEBHOOK_SECRET = "ktapp.cc"
```

### 2. 数据库配置
```python
# 数据库文件路径
DATABASE_PATH = "/Users/fuwuqi/finance_remote.db"

# 用户数据文件
USERS_FILE = "/Users/fuwuqi/bot_users.json"

# 已删除交易ID文件
DELETED_IDS_FILE = "/Users/fuwuqi/deleted_transaction_ids.txt"
```

###  3. 业务配置
```python
# 手动添加交易密码
MANUAL_ADD_PASSWORD = "2024"

# 管理员用户ID
ADMIN_USERS = [7817859891]

# 白名单用户（免密码）
MANUAL_ADD_AUTHORIZED_USERS = []

# 认证用户
AUTHENTICATED_USERS = [7817859891, 7405371531]

# 订阅用户
SUBSCRIBED_USERS = [7817859891, 7405371531]

# 禁用用户
BANNED_USERS = []
```

### 4. 日志配置
```python
# 日志级别
LOG_LEVEL = logging.INFO

# 日志文件
LOG_FILE = "/Users/fuwuqi/bot.log"

# 日志格式
LOG_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
```

### 5. 定时任务配置
```python
# 每日报告时间
DAILY_REPORT_TIME = "00:00"

# 每月报告日期
MONTHLY_REPORT_DAY = 1
```

---

## API接口

### 1. Webhook 接口

#### 1.1 创建交易 (POST)
**端点**: `http://192.168.9.28:8889/webhook/transaction`

**请求头**:
```http
Authorization: Bearer ktapp.cc
Content-Type: application/json
```

**请求体**:
```json
{
  "id": 1234,
  "type": "支出",
  "amount": 100.50,
  "currency": "USDT",
  "exchangeRateToBase": 1.0,
  "amountInBase": 100.50,
  "categoryId": 1,
  "accountId": 1,
  "transactionDate": "2025-10-14",
  "description": "午餐",
  "project": "生活费",
  "memo": "备注信息",
  "createdAt": "2025-10-14T12:00:00"
}
```

**响应**:
```json
{
  "status": "received",
  "id": 1234
}
```

#### 1.2 删除交易 (DELETE)
**端点**: `http://192.168.9.28:8889/webhook/transaction/{transaction_id}`

**请求头**:
```http
Authorization: Bearer ktapp.cc
```

**响应**:
```json
{
  "status": "deleted",
  "id": 1234
}
```

#### 1.3 健康检查 (GET)
**端点**: `http://192.168.9.28:8889/webhook/health`

**响应**:
```json
{
  "status": "healthy",
  "bot_running": true,
  "subscribed_users": 2,
  "total_transactions": 573
}
```

#### 1.4 统计信息 (GET)
**端点**: `http://192.168.9.28:8889/webhook/stats`

**响应**:
```json
{
  "authenticated_users": 2,
  "subscribed_users": 2,
  "admin_users": 1,
  "banned_users": 0,
  "total_transactions": 573,
  "deleted_transactions": 0
}
```

---

## 数据库结构

### 财务交易表 (finance_transactions)
```sql
CREATE TABLE finance_transactions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    type TEXT NOT NULL,                     -- 交易类型：收入/支出
    amount REAL NOT NULL,                   -- 金额
    currency TEXT NOT NULL,                 -- 币种：USDT/CNY
    exchange_rate_to_base REAL NOT NULL,    -- 汇率
    amount_in_base REAL NOT NULL,           -- 基础货币金额
    category_id INTEGER,                    -- 分类ID
    account_id INTEGER,                     -- 账户ID
    transaction_date TEXT NOT NULL,         -- 交易日期
    description TEXT,                       -- 描述
    project TEXT,                           -- 项目
    memo TEXT,                              -- 备注
    created_at TEXT NOT NULL,               -- 创建时间
    is_deleted INTEGER NOT NULL DEFAULT 0,  -- 软删除标记
    deleted_at TEXT                         -- 删除时间
);
```

### 用户数据结构 (bot_users.json)
```json
{
  "authenticated_users": [7817859891, 7405371531],
  "subscribed_users": [7817859891, 7405371531],
  "admin_users": [7817859891],
  "banned_users": [],
  "manual_add_authorized_users": [],
  "user_history_sent": {
    "7817859891": [608, 609, 610, 611, 612, 613]
  }
}
```

---

## 部署说明

### 环境要求
- **操作系统**: macOS / Linux
- **Python版本**: 3.13+
- **必需库**:
  ```
  python-telegram-bot==20.x
  fastapi==0.100.0+
  uvicorn==0.23.0+
  apscheduler==3.10.0+
  httpx==0.24.0+
  ```

### 安装步骤

#### 1. 安装Python依赖
```bash
pip3 install python-telegram-bot fastapi uvicorn apscheduler httpx
```

#### 2. 配置文件
将以下文件放置在 `/Users/fuwuqi/` 目录：
- `telegram_webhook_bot.py` - 主程序
- `finance_remote.db` - 数据库
- `bot_users.json` - 用户数据
- `keep_bot_alive.sh` - 守护脚本

#### 3. 设置权限
```bash
chmod +x /Users/fuwuqi/telegram_webhook_bot.py
chmod +x /Users/fuwuqi/keep_bot_alive.sh
```

#### 4. 启动机器人
```bash
# 方式1: 直接启动
python3 /Users/fuwuqi/telegram_webhook_bot.py

# 方式2: 后台启动
nohup python3 /Users/fuwuqi/telegram_webhook_bot.py > /Users/fuwuqi/bot.log 2>&1 &

# 方式3: 使用守护脚本（推荐）
nohup /Users/fuwuqi/keep_bot_alive.sh > /Users/fuwuqi/guardian.log 2>&1 &
```

#### 5. 验证运行状态
```bash
# 检查进程
ps aux | grep telegram_webhook_bot.py

# 查看日志
tail -f /Users/fuwuqi/bot.log

# 查看守护日志
tail -f /Users/fuwuqi/guardian.log
```

### 自动启动配置

#### macOS (LaunchAgent)
创建文件 `~/Library/LaunchAgents/com.kt.telegrambot.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.kt.telegrambot</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/python3</string>
        <string>/Users/fuwuqi/telegram_webhook_bot.py</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/fuwuqi/bot.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/fuwuqi/bot_error.log</string>
</dict>
</plist>
```

加载服务:
```bash
launchctl load ~/Library/LaunchAgents/com.kt.telegrambot.plist
launchctl start com.kt.telegrambot
```

---

## 使用指南

### 快速开始

#### 1. 启动对话
在Telegram中搜索 `@ktyyds_bot` 或直接访问链接，发送 `/start` 命令。

#### 2. 主菜单功能
- 📖 使用教程 - 查看详细使用说明
- 📚 查看历史记录 - 浏览所有交易记录
- 🔍 查询记录 - 按多种方式查询
- 📊 手动添加 - 手动创建新交易
- ⚙️ 我的设置 - 管理推送和个人设置
- ⚙️ 管理面板 - 管理员专用功能

### 查询操作指南

#### 按年查询
1. 点击 "🔍 查询记录"
2. 选择 "📅 按年查询"
3. 选择年份
4. 查看该年所有交易

#### 按月查询
1. 点击 "🔍 查询记录"
2. 选择 "📅 按月查询"
3. 选择月份（可切换年份）
4. 查看该月所有交易

#### 按日期查询
1. 点击 "🔍 查询记录"
2. 选择 "📅 按日期查询"
3. 先选择月份
4. 再选择具体日期
5. 查看当日所有交易

#### 关键词查询
1. 点击 "🔍 查询记录"
2. 选择 "🔎 关键词查询"
3. 输入搜索关键词：
   - 单个关键词: `午餐`
   - AND逻辑: `午餐 USDT`
   - OR逻辑: `午餐|晚餐`
   - 精确匹配: `"工资发放"`
4. 获取匹配结果

### 手动添加交易

#### 操作步骤
1. 点击 "📊 手动添加"
2. 如需密码，输入: `2024`
3. 按提示输入交易信息：
   ```
   交易类型,金额,币种,日期,描述
   ```
4. 示例：
   ```
   支出,50,USDT,2025-10-14,午餐
   ```
5. 确认后自动保存并通知所有订阅用户

### 管理推送

#### 开启推送
1. 点击 "⚙️ 我的设置"
2. 点击 "🔔 开启推送"
3. 开始接收实时交易通知

#### 关闭推送
1. 点击 "⚙️ 我的设置"
2. 点击 "🔕 关闭推送"
3. 停止接收推送消息

---

## 故障排查

### 常见问题

#### 1. 机器人无响应
**原因**: 进程可能崩溃或卡死

**解决方案**:
```bash
# 检查进程
ps aux | grep telegram_webhook_bot.py

# 查看日志错误
tail -100 /Users/fuwuqi/bot.log | grep ERROR

# 重启机器人
kill $(cat /Users/fuwuqi/bot.pid)
sleep 2
nohup python3 /Users/fuwuqi/telegram_webhook_bot.py > /Users/fuwuqi/bot.log 2>&1 &
```

#### 2. 按钮点击超时
**原因**: 缺少 `await query.answer()` 响应

**解决方案**: 已在所有callback处理器添加立即响应，正常不会出现

#### 3. 消息发送失败
**错误**: `Message is too long`

**原因**: 单条消息超过Telegram 4096字符限制

**解决方案**: 已实现自动分批发送（每批30条）

#### 4. 数据库锁定
**错误**: `database is locked`

**原因**: SQLite并发访问冲突

**解决方案**:
```python
# 已实现连接超时和重试机制
conn = sqlite3.connect(DATABASE_PATH, timeout=30)
```

#### 5. Webhook端口被占用
**错误**: `[Errno 48] address already in use`

**解决方案**:
```bash
# 查找占用进程
lsof -ti:8889

# 杀死进程
lsof -ti:8889 | xargs kill -9

# 重启机器人
nohup python3 /Users/fuwuqi/telegram_webhook_bot.py > /Users/fuwuqi/bot.log 2>&1 &
```

#### 6. 多实例冲突
**错误**: `Conflict: terminated by other getUpdates request`

**原因**: 多个机器人实例同时运行

**解决方案**:
```bash
# 杀死所有实例
pkill -9 -f telegram_webhook_bot.py

# 等待2秒
sleep 2

# 启动单个实例
nohup python3 /Users/fuwuqi/telegram_webhook_bot.py > /Users/fuwuqi/bot.log 2>&1 &
```

### 日志分析

#### 正常运行日志
```
2025-10-14 18:57:41,563 - __main__ - INFO - ✅ 已加载 2 个认证用户, 2 个订阅用户, 1 个管理员
2025-10-14 18:57:41,573 - __main__ - INFO - ✅ 已从数据库加载 573 条活跃交易记录
2025-10-14 18:57:41,960 - telegram.ext.Application - INFO - Application started
2025-10-14 18:57:42,997 - httpx - INFO - HTTP Request: POST https://api.telegram.org/bot.../getUpdates "HTTP/1.1 200 OK"
```

#### 错误日志关键词
- `ERROR` - 错误级别
- `httpx.RemoteProtocolError` - 连接超时
- `telegram.error.NetworkError` - 网络错误
- `sqlite3.OperationalError` - 数据库错误
- `KeyError` / `AttributeError` - 代码逻辑错误

---

## 维护指南

### 日常维护

#### 1. 日志管理
```bash
# 查看实时日志
tail -f /Users/fuwuqi/bot.log

# 查看最近100行
tail -100 /Users/fuwuqi/bot.log

# 查找错误
grep ERROR /Users/fuwuqi/bot.log

# 清理日志（保留最近1000行）
tail -1000 /Users/fuwuqi/bot.log > /Users/fuwuqi/bot.log.tmp
mv /Users/fuwuqi/bot.log.tmp /Users/fuwuqi/bot.log
```

#### 2. 数据库维护
```bash
# 备份数据库
cp /Users/fuwuqi/finance_remote.db /Users/fuwuqi/finance_remote_backup_$(date +%Y%m%d).db

# 检查数据库完整性
sqlite3 /Users/fuwuqi/finance_remote.db "PRAGMA integrity_check;"

# 优化数据库
sqlite3 /Users/fuwuqi/finance_remote.db "VACUUM;"

# 查询数据统计
sqlite3 /Users/fuwuqi/finance_remote.db "SELECT COUNT(*) FROM finance_transactions WHERE is_deleted=0;"
```

#### 3. 进程监控
```bash
# 检查进程状态
ps aux | grep telegram_webhook_bot.py | grep -v grep

# 查看进程运行时间
ps -p $(cat /Users/fuwuqi/bot.pid) -o etime=

# 查看守护脚本状态
tail -20 /Users/fuwuqi/guardian.log
```

#### 4. 网络监控
```bash
# 检查Webhook端口
lsof -i:8889

# 测试健康检查
curl http://192.168.9.28:8889/webhook/health

# 测试统计接口
curl http://192.168.9.28:8889/webhook/stats
```

### 定期维护任务

#### 每日任务
- [ ] 检查bot.log是否有ERROR
- [ ] 确认进程正常运行
- [ ] 验证推送功能正常

#### 每周任务
- [ ] 备份数据库
- [ ] 清理日志文件
- [ ] 检查磁盘空间
- [ ] 更新用户列表

#### 每月任务
- [ ] 数据库完整性检查
- [ ] 数据库优化(VACUUM)
- [ ] 系统更新检查
- [ ] 性能评估

### 更新部署

#### 代码更新流程
1. **备份当前版本**
   ```bash
   cp /Users/fuwuqi/telegram_webhook_bot.py /Users/fuwuqi/telegram_webhook_bot.py.bak
   cp /Users/fuwuqi/finance_remote.db /Users/fuwuqi/finance_remote.db.bak
   ```

2. **停止机器人**
   ```bash
   kill $(cat /Users/fuwuqi/bot.pid)
   ```

3. **部署新代码**
   ```bash
   # 替换Python文件
   cp /path/to/new/telegram_webhook_bot.py /Users/fuwuqi/
   ```

4. **语法检查**
   ```bash
   python3 -m py_compile /Users/fuwuqi/telegram_webhook_bot.py
   ```

5. **启动新版本**
   ```bash
   nohup python3 /Users/fuwuqi/telegram_webhook_bot.py > /Users/fuwuqi/bot.log 2>&1 &
   sleep 3
   ps aux | grep telegram_webhook_bot.py | grep -v grep | awk '{print $2}' > /Users/fuwuqi/bot.pid
   ```

6. **验证功能**
   - 发送 `/start` 命令
   - 测试查询功能
   - 测试手动添加
   - 检查推送功能

### 性能优化

#### 数据库优化
```sql
-- 添加索引
CREATE INDEX IF NOT EXISTS idx_transaction_date ON finance_transactions(transaction_date);
CREATE INDEX IF NOT EXISTS idx_is_deleted ON finance_transactions(is_deleted);
CREATE INDEX IF NOT EXISTS idx_created_at ON finance_transactions(created_at);

-- 定期清理软删除数据（可选）
DELETE FROM finance_transactions WHERE is_deleted=1 AND deleted_at < date('now', '-90 days');
```

#### 内存优化
- 分批查询大数据集
- 及时释放数据库连接
- 限制并发推送数量

#### 网络优化
- 使用httpx异步请求
- 实现请求重试机制
- 优化消息批次大小

---

## 安全说明

### 敏感信息
以下信息需妥善保管，切勿泄露：
- Bot Token: `8422152380:AAFH5AfUHRdbfSzDPIfGHexSRTUqL6R-ok0`
- Webhook Secret: `ktapp.cc`
- 手动添加密码: `2024`
- 数据库文件: `finance_remote.db`

### 安全建议
1. 定期更换密码和Token
2. 限制文件访问权限
3. 使用HTTPS webhook（生产环境）
4. 定期备份数据
5. 监控异常访问
6. 及时更新依赖库

### 权限管理
- **管理员**: 完全访问权限
- **白名单用户**: 免密码手动添加
- **认证用户**: 需密码验证
- **订阅用户**: 接收推送通知
- **禁用用户**: 无法使用机器人

---

## 技术支持

### 联系方式
- **机器人**: @ktyyds_bot
- **管理员**: Telegram ID 7817859891

### 文档更新
- **版本**: 2.0
- **最后更新**: 2025-10-14
- **文档作者**: Claude Code AI Assistant

### 相关资源
- Telegram Bot API: https://core.telegram.org/bots/api
- python-telegram-bot文档: https://docs.python-telegram-bot.org/
- FastAPI文档: https://fastapi.tiangolo.com/
- SQLite文档: https://www.sqlite.org/docs.html

---

## 附录

### A. 命令完整列表
| 命令 | 说明 | 权限 |
|------|------|------|
| /start | 显示主菜单 | 所有用户 |
| /status | 查看订阅状态 | 所有用户 |
| /history | 查看历史记录 | 认证用户 |
| /query | 查询记录 | 认证用户 |
| /users | 用户列表 | 管理员 |

### B. 按钮功能映射
| callback_data | 功能 | 位置 |
|---------------|------|------|
| subscribe | 开启推送 | 我的设置 |
| unsubscribe | 关闭推送 | 我的设置 |
| show_tutorial | 使用教程 | 主菜单 |
| show_history | 查看历史 | 主菜单 |
| query_records | 查询记录 | 主菜单 |
| query_keyword | 关键词查询 | 查询方式 |
| query_select_year | 按年查询 | 查询方式 |
| query_select_month | 按月查询 | 查询方式 |
| query_select_date | 按日期查询 | 查询方式 |
| manual_add | 手动添加 | 主菜单 |
| my_settings | 我的设置 | 主菜单 |
| admin_panel | 管理面板 | 主菜单 |
| back_to_main | 返回主菜单 | 各子菜单 |

### C. 错误代码说明
| 代码 | 说明 | 解决方案 |
|------|------|----------|
| 401 | Webhook认证失败 | 检查Authorization头 |
| 404 | 交易不存在 | 确认交易ID有效 |
| 409 | 多实例冲突 | 杀死其他实例 |
| 429 | 请求频率过高 | 减少请求频率 |
| 500 | 服务器内部错误 | 查看日志详情 |

### D. 数据统计
截至 2025-10-14:
- 总交易记录: 573 条
- 活跃用户: 2 人
- 订阅用户: 2 人
- 管理员: 1 人
- 运行时长: 稳定运行
- 平均响应时间: < 1秒

---

**文档结束**