ops-assistant/README.md

🦞 虾记 Xiaji-Go

一个支持 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 信号，干净退出

📦 快速开始

二进制运行

# 1. 复制配置文件
cp config.yaml.example config.yaml

# 2. 编辑配置（填入 Bot Token 等信息）
vi config.yaml

# 3. 运行
./xiaji-go

Docker 运行

# 1. 准备配置文件
cp config.yaml.example config.yaml
vi config.yaml

# 2. 使用 docker-compose
docker-compose up -d

# 或直接 docker run
docker run -d \
  --name xiaji-go \
  -p 9521:9521 \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  -v $(pwd)/data:/app/data \
  ouaone/xiaji-go:latest

从源码编译

# 需要 Go 1.22+、GCC（gojieba 依赖 CGO）
make build

# 交叉编译 Linux
make build-linux

⚙️ 配置说明

server:
  port: 9521                    # 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:9521：

• 📊 今日支出 / 本月支出 / 总记录数统计
• 📋 最近 50 条记录列表
• 🔍 按分类筛选
• 🗑️ 删除记录
• 📥 CSV 导出（Excel 兼容 BOM 编码）

🏗️ 项目结构

xiaji-go/
├── 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