187 lines
5.0 KiB
Markdown
187 lines
5.0 KiB
Markdown
# 🛠️ Ops-Assistant
|
||
|
||
一个支持 **Telegram Bot** 和 **QQ Bot** 的智能记账机器人，带 Web 管理后台。
|
||
|
||
> 当前稳定版本：`v1.1.12`
|
||
|
||
## 🆕 v1.1.12 更新
|
||
|
||
- 新增渠道管理页：`/channels`（移动端优先，统一 UI）
|
||
- 新增审计页面：`/audit`（中文化）
|
||
- 新增一键生效接口：`POST /api/v1/admin/channels/:platform/apply`
|
||
- 渠道配置安全增强：`***` 脱敏占位符不会覆盖真实 secrets
|
||
- apply 失败返回增强：失败时返回 `stage` 与 `committed` 字段
|
||
- 首页/登录/渠道/审计页面版本显示统一为 `vX.Y.Z`
|
||
|
||
## ✨ 功能特性
|
||
|
||
- **多平台支持**：同时接入 Telegram Bot 和 QQ Bot（WebSocket 模式）
|
||
- **智能记账**：发送自然语言自动识别金额和消费分类（基于 jieba 分词）
|
||
- **150+ 预设分类关键词**：餐饮、交通、购物、饮品、水果、住房、医疗、娱乐等
|
||
- **Web 管理后台**：响应式设计，支持记录查看、删除、CSV 导出
|
||
- **金额精确**：使用分（int64）存储，避免浮点精度问题
|
||
- **优雅关闭**：支持 SIGTERM/SIGINT 信号，干净退出
|
||
|
||
## 📦 快速开始
|
||
|
||
### 二进制运行
|
||
|
||
```bash
|
||
# 1. 复制配置文件
|
||
cp config.yaml.example config.yaml
|
||
|
||
# 2. 编辑配置（填入 Bot Token 等信息）
|
||
vi config.yaml
|
||
|
||
# 3. 运行
|
||
./ops-assistant
|
||
```
|
||
|
||
### Docker 运行
|
||
|
||
```bash
|
||
# 1. 准备配置文件
|
||
cp config.yaml.example config.yaml
|
||
vi config.yaml
|
||
|
||
# 2. 使用 docker-compose
|
||
docker-compose up -d
|
||
|
||
# 或直接 docker run
|
||
docker run -d \
|
||
--name ops-assistant \
|
||
-p 9621:9621 \
|
||
-v $(pwd)/config.yaml:/app/config.yaml:ro \
|
||
-v $(pwd)/data:/app/data \
|
||
ouaone/ops-assistant:latest
|
||
```
|
||
|
||
### 从源码编译
|
||
|
||
```bash
|
||
# 需要 Go 1.22+、GCC（gojieba 依赖 CGO）
|
||
make build
|
||
|
||
# 交叉编译 Linux
|
||
make build-linux
|
||
```
|
||
|
||
## ⚙️ 配置说明
|
||
|
||
```yaml
|
||
server:
|
||
port: 9621 # Web 后台端口
|
||
key: "your-secret-key" # 会话密钥
|
||
|
||
database:
|
||
path: "./xiaji.db" # SQLite 数据库路径
|
||
|
||
admin:
|
||
username: "admin" # Web 后台用户名
|
||
password: "your_password" # Web 后台密码
|
||
|
||
telegram:
|
||
enabled: true # 是否启用 Telegram Bot
|
||
token: "YOUR_BOT_TOKEN" # BotFather 获取的 Token
|
||
|
||
qqbot:
|
||
enabled: false # 是否启用 QQ Bot
|
||
appid: "YOUR_APPID" # QQ 开放平台 AppID
|
||
secret: "YOUR_SECRET" # QQ 开放平台 AppSecret
|
||
```
|
||
|
||
## 💬 使用方式
|
||
|
||
### Telegram Bot 命令
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `/start` | 欢迎信息 |
|
||
| `/help` | 使用帮助 |
|
||
| `/list` | 最近 10 条记录 |
|
||
| `/today` | 今日消费汇总 |
|
||
| 直接发消息 | 自动记账（如"午饭 25元"） |
|
||
|
||
### QQ Bot 关键词
|
||
|
||
| 关键词 | 说明 |
|
||
|--------|------|
|
||
| `帮助` / `菜单` / `功能` | 显示帮助 |
|
||
| `查看` / `记录` / `列表` | 最近 10 条记录 |
|
||
| `今日` / `今天` | 今日消费汇总 |
|
||
| 直接发消息 | 自动记账 |
|
||
|
||
### 记账格式
|
||
|
||
支持多种自然语言格式：
|
||
|
||
```
|
||
午饭 25元
|
||
打车 ¥30
|
||
买咖啡15块
|
||
车费10元
|
||
超市买水果38.5
|
||
```
|
||
|
||
### 消费分类
|
||
|
||
系统预设了 150+ 个关键词，自动匹配以下分类：
|
||
|
||
| 分类 | 示例关键词 |
|
||
|------|-----------|
|
||
| 🍜 餐饮 | 早饭、午饭、晚饭、外卖、火锅、面条 |
|
||
| 🚗 交通 | 打车、车费、地铁、公交、加油 |
|
||
| 🛒 购物 | 买、淘宝、超市、衣服、手机 |
|
||
| ☕ 饮品 | 咖啡、奶茶、星巴克、可乐 |
|
||
| 🍎 水果 | 水果、苹果、香蕉、西瓜 |
|
||
| 🍪 零食 | 零食、面包、蛋糕、甜品 |
|
||
| 🏠 住房 | 房租、水电、物业、宽带 |
|
||
| 📱 通讯 | 话费、流量、充值 |
|
||
| 💊 医疗 | 看病、药、医院、挂号 |
|
||
| 🎮 娱乐 | 电影、游戏、健身、旅游 |
|
||
| 📚 教育 | 书、课、培训、学费 |
|
||
| 🚬 烟酒 | 烟、白酒、红酒 |
|
||
|
||
## 🌐 Web 管理后台
|
||
|
||
访问 `http://localhost:9621`：
|
||
|
||
- 📊 今日支出 / 本月支出 / 总记录数统计
|
||
- 📋 最近 50 条记录列表
|
||
- 🔍 按分类筛选
|
||
- 🗑️ 删除记录
|
||
- 📥 CSV 导出（Excel 兼容 BOM 编码）
|
||
|
||
## 🏗️ 项目结构
|
||
|
||
```
|
||
ops-assistant/
|
||
├── cmd/main.go # 入口文件
|
||
├── config/config.go # 配置加载与验证
|
||
├── version/version.go # 版本信息
|
||
├── models/models.go # 数据模型与分类关键词
|
||
├── internal/
|
||
│ ├── bot/telegram.go # Telegram Bot
|
||
│ ├── qq/qq.go # QQ Bot (WebSocket)
|
||
│ ├── service/finance.go # 记账核心服务（jieba 分词）
|
||
│ └── web/server.go # Web 管理后台
|
||
├── templates/index.html # Web 前端页面
|
||
├── config.yaml.example # 配置示例
|
||
├── Dockerfile # Docker 镜像
|
||
├── docker-compose.yml # Docker Compose
|
||
└── Makefile # 构建脚本
|
||
```
|
||
|
||
## 📋 技术栈
|
||
|
||
- **语言**: Go 1.22
|
||
- **Web 框架**: Gin
|
||
- **数据库**: SQLite (GORM)
|
||
- **分词**: gojieba (结巴分词 Go 版)
|
||
- **Telegram SDK**: go-telegram-bot-api v5
|
||
- **QQ SDK**: tencent-connect/botgo v0.2.1 (WebSocket 模式)
|
||
|
||
## 📄 License
|
||
|
||
MIT
|