feat: 添加Telegram Bot通知功能
✨ 新功能: - 添加Telegram Bot通知支持 - 账目记录自动推送到Telegram - 支持多个Bot配置管理 - 支持群组和个人通知 📊 数据库: - 新增telegram_notification_configs表 - 存储Bot配置和通知类型 🔧 后端API: - GET /api/telegram/notifications - 获取所有配置 - POST /api/telegram/notifications - 创建配置 - PUT /api/telegram/notifications/:id - 更新配置 - DELETE /api/telegram/notifications/:id - 删除配置 - POST /api/telegram/test - 测试Bot配置 💬 通知功能: - 自动发送账目记录通知 - 包含交易类型、金额、分类、账户等信息 - 支持格式化显示(类型图标、状态标识) - 配置创建时自动测试有效性 📝 文档: - 添加完整的使用说明文档 - API接口说明和示例 - 常见问题解答
This commit is contained in:
你的用户名
247
docs/TELEGRAM_NOTIFICATION.md
Normal file
247
docs/TELEGRAM_NOTIFICATION.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# Telegram 通知功能使用说明
|
||||
|
||||
## 功能概述
|
||||
|
||||
KT财务系统支持通过Telegram Bot向群组或个人发送账目记录通知。每当添加、更新或删除账目时，系统会自动推送消息到配置的Telegram聊天。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- ✅ 支持多个Telegram Bot配置
|
||||
- ✅ 支持发送到群组或个人
|
||||
- ✅ 自动推送新增账目记录
|
||||
- ✅ 包含完整的交易信息（类型、金额、分类、账户等）
|
||||
- ✅ 支持启用/禁用通知
|
||||
- ✅ 提供测试功能验证配置
|
||||
|
||||
## 准备工作
|
||||
|
||||
### 1. 创建Telegram Bot
|
||||
|
||||
1. 在Telegram中搜索 `@BotFather`
|
||||
2. 发送 `/newbot` 命令
|
||||
3. 按照提示设置Bot名称和用户名
|
||||
4. 获取Bot Token（格式：`1234567890:ABCdefGHIjklMNOpqrsTUVwxyz`）
|
||||
|
||||
### 2. 获取Chat ID
|
||||
|
||||
#### 获取个人Chat ID：
|
||||
1. 在Telegram中搜索 `@userinfobot`
|
||||
2. 发送任意消息
|
||||
3. Bot会返回你的Chat ID
|
||||
|
||||
#### 获取群组Chat ID：
|
||||
1. 将你的Bot添加到群组
|
||||
2. 在群组中发送任意消息
|
||||
3. 访问：`https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates`
|
||||
4. 在返回的JSON中找到 `chat.id` 字段（群组ID通常是负数，如：`-1001234567890`）
|
||||
|
||||
## API接口
|
||||
|
||||
### 1. 获取所有通知配置
|
||||
|
||||
```http
|
||||
GET /api/telegram/notifications
|
||||
```
|
||||
|
||||
**响应示例**：
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "财务通知群",
|
||||
"botToken": "1234567890:ABCdefGHI...",
|
||||
"chatId": "-1001234567890",
|
||||
"notificationTypes": ["transaction"],
|
||||
"isEnabled": true,
|
||||
"createdAt": "2025-01-01T00:00:00.000Z",
|
||||
"updatedAt": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 创建通知配置
|
||||
|
||||
```http
|
||||
POST /api/telegram/notifications
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "财务通知群",
|
||||
"botToken": "1234567890:ABCdefGHI...",
|
||||
"chatId": "-1001234567890",
|
||||
"notificationTypes": ["transaction"],
|
||||
"isEnabled": true
|
||||
}
|
||||
```
|
||||
|
||||
**说明**：
|
||||
- `name`: 配置名称（必填）
|
||||
- `botToken`: Telegram Bot Token（必填）
|
||||
- `chatId`: 目标聊天ID（必填）
|
||||
- `notificationTypes`: 通知类型数组，目前支持 `["transaction"]`（可选，默认：`["transaction"]`）
|
||||
- `isEnabled`: 是否启用（可选，默认：`true`）
|
||||
|
||||
**响应示例**：
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"id": 1,
|
||||
"name": "财务通知群",
|
||||
"botToken": "1234567890:ABCdefGHI...",
|
||||
"chatId": "-1001234567890",
|
||||
"notificationTypes": ["transaction"],
|
||||
"isEnabled": true,
|
||||
"createdAt": "2025-01-01T00:00:00.000Z",
|
||||
"updatedAt": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**：创建时会自动测试配置，如果Bot Token或Chat ID无效，会返回错误。
|
||||
|
||||
### 3. 更新通知配置
|
||||
|
||||
```http
|
||||
PUT /api/telegram/notifications/:id
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "更新后的名称",
|
||||
"isEnabled": false
|
||||
}
|
||||
```
|
||||
|
||||
**说明**：所有字段都是可选的，只更新提供的字段。
|
||||
|
||||
### 4. 删除通知配置
|
||||
|
||||
```http
|
||||
DELETE /api/telegram/notifications/:id
|
||||
```
|
||||
|
||||
### 5. 测试Telegram配置
|
||||
|
||||
```http
|
||||
POST /api/telegram/test
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"botToken": "1234567890:ABCdefGHI...",
|
||||
"chatId": "-1001234567890"
|
||||
}
|
||||
```
|
||||
|
||||
**说明**：发送测试消息验证Bot Token和Chat ID是否有效。
|
||||
|
||||
## 通知消息格式
|
||||
|
||||
当添加账目记录时，系统会发送以下格式的消息：
|
||||
|
||||
```
|
||||
📋 新增账目记录
|
||||
|
||||
类型：💸 支出
|
||||
金额：CNY 100.00
|
||||
日期：2025-01-15
|
||||
分类：餐饮
|
||||
账户：现金账户
|
||||
状态：✅ 已批准
|
||||
|
||||
备注：午餐费用
|
||||
|
||||
🕐 记录时间：2025-01-15 14:30:00
|
||||
```
|
||||
|
||||
## 通知类型说明
|
||||
|
||||
目前支持的通知类型：
|
||||
- `transaction`: 交易记录通知（新增、更新、删除账目）
|
||||
|
||||
未来可扩展：
|
||||
- `budget`: 预算提醒
|
||||
- `report`: 财务报表
|
||||
- `reimbursement`: 报销审批
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: Bot无法发送消息到群组？
|
||||
**A**: 请确保：
|
||||
1. Bot已被添加到群组
|
||||
2. Bot在群组中有发送消息的权限
|
||||
3. Chat ID正确（群组ID通常是负数）
|
||||
|
||||
### Q: 如何禁用某个配置的通知？
|
||||
**A**: 调用更新API，设置 `isEnabled: false`
|
||||
|
||||
### Q: 可以配置多个Bot吗？
|
||||
**A**: 可以！系统支持多个Bot配置，所有启用的配置都会收到通知。
|
||||
|
||||
### Q: 消息会包含敏感信息吗？
|
||||
**A**: 消息只包含账目的基本信息（类型、金额、分类等），不包含用户身份等敏感信息。建议使用私密群组。
|
||||
|
||||
## 技术实现
|
||||
|
||||
### 数据库表结构
|
||||
|
||||
```sql
|
||||
CREATE TABLE telegram_notification_configs (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
name TEXT NOT NULL,
|
||||
bot_token TEXT NOT NULL,
|
||||
chat_id TEXT NOT NULL,
|
||||
notification_types TEXT NOT NULL, -- JSON数组
|
||||
is_enabled INTEGER NOT NULL DEFAULT 1,
|
||||
created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
### 后端实现
|
||||
|
||||
- `apps/backend/utils/telegram-bot.ts`: Telegram Bot核心功能
|
||||
- `apps/backend/api/telegram/`: 通知配置管理API
|
||||
- `apps/backend/api/finance/transactions.post.ts`: 集成通知发送
|
||||
|
||||
## 示例：使用curl测试
|
||||
|
||||
```bash
|
||||
# 1. 测试Bot配置
|
||||
curl -X POST http://localhost:3000/api/telegram/test \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"botToken": "YOUR_BOT_TOKEN",
|
||||
"chatId": "YOUR_CHAT_ID"
|
||||
}'
|
||||
|
||||
# 2. 创建通知配置
|
||||
curl -X POST http://localhost:3000/api/telegram/notifications \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "测试配置",
|
||||
"botToken": "YOUR_BOT_TOKEN",
|
||||
"chatId": "YOUR_CHAT_ID",
|
||||
"notificationTypes": ["transaction"]
|
||||
}'
|
||||
|
||||
# 3. 添加账目记录（触发通知）
|
||||
curl -X POST http://localhost:3000/api/finance/transactions \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"type": "expense",
|
||||
"amount": 100,
|
||||
"currency": "CNY",
|
||||
"transactionDate": "2025-01-15",
|
||||
"description": "测试通知功能"
|
||||
}'
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
等你提供Telegram Bot Token后，我们可以：
|
||||
1. 在前端添加通知配置管理界面
|
||||
2. 测试实际的消息发送
|
||||
3. 根据需要调整消息格式和内容
|
||||
Reference in New Issue
Block a user