init: ops-assistant codebase

2026-03-19 21:23:28 +08:00
commit 81deba4766
94 changed files with 10767 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,186 @@
+# 🛠️ 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