chenjiangjiang/kt-financial-system

Fork 0

Files

你的用户名 a06a964bab

Deploy to Production / Build and Test (push) Has been cancelled

Details

Deploy to Production / Deploy to Server (push) Has been cancelled

Details

feat: add Telegram notification settings UI

2025-11-05 02:22:00 +08:00

6.8 KiB

Raw Permalink Blame History

Telegram 通知功能使用说明

功能概述

KT财务系统支持通过Telegram Bot向群组或个人发送账目记录通知。每当添加、更新或删除账目时，系统会自动推送消息到配置的Telegram聊天。

功能特性

✅ 支持多个Telegram Bot配置
✅ 支持发送到群组或个人
✅ 自动推送新增账目记录
✅ 包含完整的交易信息（类型、金额、分类、账户等）
✅ 支持启用/禁用通知
✅ 提供测试功能验证配置

准备工作

1. 创建Telegram Bot

在Telegram中搜索 @BotFather
发送 /newbot 命令
按照提示设置Bot名称和用户名
获取Bot Token（格式：1234567890:ABCdefGHIjklMNOpqrsTUVwxyz）

2. 获取Chat ID

获取个人Chat ID：

在Telegram中搜索 @userinfobot
发送任意消息
Bot会返回你的Chat ID

获取群组Chat ID：

将你的Bot添加到群组
在群组中发送任意消息
访问：https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
在返回的JSON中找到 chat.id 字段（群组ID通常是负数，如：-1001234567890）

API接口

1. 获取所有通知配置

GET /api/telegram/notifications

响应示例：

{
  "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. 创建通知配置

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）

响应示例：

{
  "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. 更新通知配置

PUT /api/telegram/notifications/:id
Content-Type: application/json

{
  "name": "更新后的名称",
  "isEnabled": false
}

说明：所有字段都是可选的，只更新提供的字段。

4. 删除通知配置

DELETE /api/telegram/notifications/:id

5. 测试Telegram配置

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: 请确保：

Bot已被添加到群组
Bot在群组中有发送消息的权限
Chat ID正确（群组ID通常是负数）

Q: 如何禁用某个配置的通知？

A: 调用更新API，设置 isEnabled: false

Q: 可以配置多个Bot吗？

A: 可以！系统支持多个Bot配置，所有启用的配置都会收到通知。

Q: 消息会包含敏感信息吗？

A: 消息只包含账目的基本信息（类型、金额、分类等），不包含用户身份等敏感信息。建议使用私密群组。

技术实现

数据库表结构

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测试

# 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 通知现已集成在 Web 端的系统设置页面：

入口路径：财务系统 → ⚙️ 系统设置 → Telegram 通知配置
列表内容：展示配置名称、Bot Token（掩码）、Chat ID、通知类型、启用状态以及最近更新时间
支持操作：快速启用/禁用、编辑、发送测试通知、删除

新增或编辑配置

点击「➕ 新增配置」或列表中的「编辑」按钮
填写/更新以下字段：
- 配置名称：用于标识通知触达对象（例如“财务通知群”）
- Bot Token：来自 @BotFather 的完整 Token
- Chat ID：个人或群组的 ID（群组需将 Bot 加入并通过 getUpdates 获取）
- 启用状态：控制是否参与通知投递
可直接在弹窗内点击「发送测试」，验证 Bot Token 与 Chat ID 是否有效
点击「创建配置」或「保存更新」提交，成功后自动刷新列表

使用提示

所有启用的配置会在新增账目时同步收到通知
「测试」按钮会向对应的聊天发送标准测试消息，方便确认权限
删除配置后即刻停止向该聊天推送消息

6.8 KiB Raw Permalink Blame History Unescape Escape