first
This commit is contained in:
dela
201
docs/dev.md
Normal file
201
docs/dev.md
Normal file
@@ -0,0 +1,201 @@
|
||||
这是一份为了**正式开发**准备的 V2.0 架构设计文档。
|
||||
|
||||
相比于 V1.x 版本，**V2.0 的核心变革**在于：**从“配置文件定义分类”转变为“数据库管理分类” + “交互式按钮投稿”**。这将极大地提升机器人的易用性和数据的规范性。
|
||||
|
||||
你可以把这份文档保存为 `README.md` 或 `SPEC.md`，作为你的开发圣经。
|
||||
|
||||
---
|
||||
|
||||
# 📘 Telegram 频道目录机器人 V2.0 开发文档
|
||||
|
||||
## 1. 项目愿景 (Vision)
|
||||
|
||||
打造一个**交互式、数据库驱动**的 Telegram 频道内容管理系统 (CMS)。
|
||||
管理员不再需要在配置文件中硬编码分类，也不需要手动输入容易出错的分类指令。通过**指令管理分类** + **点击按钮投稿**，实现高效、规范的频道运营。
|
||||
|
||||
* **核心特性**：
|
||||
* **严格分类**：分类必须先创建才能使用，杜绝拼写错误。
|
||||
* **交互体验**：`/post` 唤起内联键盘 (Inline Keyboard)，点选分类。
|
||||
* **动态维护**：随时添加/删除分类，无需重启机器人。
|
||||
* **CRUD**：支持对条目的增删改查。
|
||||
* **高并发**：Producer-Consumer 架构 + Ticker 防抖。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 2. 技术栈 (Tech Stack)
|
||||
|
||||
* **语言**: Go (Golang) 1.20+
|
||||
* **框架**: `gopkg.in/telebot.v3` (利用其强大的 `Handle` 和 `Callback` 机制)
|
||||
* **数据库**: `go.etcd.io/bbolt` (BoltDB)
|
||||
* **辅助库**: `github.com/teris-io/shortid` (生成短 ID)
|
||||
|
||||
---
|
||||
|
||||
## 3. 目录结构 (Directory Layout)
|
||||
|
||||
```text
|
||||
.
|
||||
├── cmd
|
||||
│ └── bot
|
||||
│ └── main.go # 程序入口
|
||||
├── config.yaml # 仅存储 Token 和 AdminIDs (不再存分类)
|
||||
├── bot.db # BoltDB 数据文件
|
||||
├── internal
|
||||
│ ├── config # 配置加载
|
||||
│ ├── storage # DB 操作 (Entries & Categories)
|
||||
│ ├── telegram # Bot 逻辑层
|
||||
│ │ ├── handlers_cat.go # 分类管理 (/cat_add 等)
|
||||
│ │ ├── handlers_post.go # 投稿交互 (/post & Callback)
|
||||
│ │ └── handlers_entry.go # 条目管理 (/del, /edit)
|
||||
│ └── toc # 目录渲染与调度 (Manager)
|
||||
└── go.mod
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据库设计 (Database Schema)
|
||||
|
||||
V2.0 新增了 `Categories` Bucket，实现了分类的完全数据化。
|
||||
|
||||
### Bucket: `AppConfig`
|
||||
|
||||
* `"toc_msg_id"` -> `[]byte("12345")` (目录总帖 ID)
|
||||
|
||||
### Bucket: `Categories` (新增)
|
||||
|
||||
* **Key**: 分类名称 (如 `"iOS"`)
|
||||
* **Value**: JSON (存元数据，如创建时间，用于排序)
|
||||
```json
|
||||
{"name": "iOS", "created_at": 1698123456}
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Bucket: `Entries`
|
||||
|
||||
* **Key**: 短 ID (如 `"a1b2c"`)
|
||||
* **Value**: JSON
|
||||
```json
|
||||
{
|
||||
"id": "a1b2c",
|
||||
"category": "iOS",
|
||||
"title": "微信多开",
|
||||
"link": "https://t.me/...",
|
||||
"timestamp": 1698123999
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 5. 交互流程设计 (Interaction Flow)
|
||||
|
||||
### 5.1 分类管理 (Category Management)
|
||||
|
||||
* 管理员发送 `/cat_add iOS`。
|
||||
* 机器人写入 DB `Categories` Bucket。
|
||||
* 机器人的内存缓存更新。
|
||||
|
||||
### 5.2 投稿流程 (The Post Flow) - *V2.0 核心*
|
||||
|
||||
1. **触发**: 管理员回复某条消息，发送 `/post` (可带参数：`/post 自定义标题`)。
|
||||
2. **响应**: 机器人**不**立即转发。它读取 DB 里的分类列表，生成一个 **Inline Keyboard** (按钮面板)。
|
||||
> **请选择分类：**
|
||||
> `[ 🍎 iOS ]` `[ 🤖 Android ]`
|
||||
> `[ 💻 Windows ]` `[ ❌ 取消 ]`
|
||||
|
||||
|
||||
3. **选择**: 管理员点击 `[ 🍎 iOS ]` 按钮。
|
||||
4. **处理 (Callback)**:
|
||||
* 机器人收到回调事件 `OnCallback`。
|
||||
* 获取原消息内容、管理员刚才输入的标题（需要暂存在 Context 或解析 Payload）。
|
||||
* 执行转发 -> 生成链接 -> 存入 DB -> 触发目录更新。
|
||||
|
||||
|
||||
5. **清理**: 机器人删除那个带有按钮的面板，保持群聊整洁。
|
||||
|
||||
---
|
||||
|
||||
## 6. 指令手册 (Command Manual)
|
||||
|
||||
### 🛠 分类管理
|
||||
|
||||
| 指令 | 作用 | 逻辑 |
|
||||
| --- | --- | --- |
|
||||
| `/cat_add [名字]` | 新建分类 | 存入 DB，去重检查 |
|
||||
| `/cat_del [名字]` | 删除分类 | 删除 DB Key (**注意**: 需决定是否同时删除该分类下的条目) |
|
||||
| `/cat_list` | 查看分类 | 列出当前所有可用分类 |
|
||||
|
||||
### 📝 内容投稿
|
||||
|
||||
| 指令 | 作用 | 逻辑 |
|
||||
| --- | --- | --- |
|
||||
| `/post` | 投稿 (原标题) | 弹出按钮面板供选择 |
|
||||
| `/post [标题]` | 投稿 (新标题) | 弹出按钮面板，点击后使用该[标题] |
|
||||
|
||||
### ⚙️ 条目维护 (CRUD)
|
||||
|
||||
| 指令 | 作用 | 逻辑 |
|
||||
| --- | --- | --- |
|
||||
| `/del [ID]` | 删除条目 | 根据短 ID 删除 |
|
||||
| `/edit [ID] [新标题]` | 修改标题 | 修改 DB 中的 Title |
|
||||
| `/move [ID] [新分类]` | 移动分类 | 修改 DB 中的 Category |
|
||||
| `/list [分类]` | 查询 ID | 列出某分类下的 ID 用于维护 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 目录渲染逻辑 (Rendering)
|
||||
|
||||
由于分类现在是动态的，渲染顺序建议如下：
|
||||
|
||||
1. 从 DB 读取所有 `Categories`。
|
||||
2. **排序**：按字母顺序 (A-Z) 或 创建时间 (Oldest First)。
|
||||
3. 遍历排序后的分类列表：
|
||||
* 从内存 Cache 中取出该分类下的 `Entries`。
|
||||
* 拼接 Markdown。
|
||||
* 如果某个分类下没有条目，可以选择**不显示**该分类标题，或者显示但留空。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 8. 开发路线图 (Roadmap)
|
||||
|
||||
建议按以下顺序开发，每个阶段都可以运行测试：
|
||||
|
||||
* **Phase 1: 基础设施**
|
||||
* 初始化 BoltDB，建立 `Categories` 和 `Entries` 两个 Bucket。
|
||||
* 实现 `storage` 包的 CRUD 函数。
|
||||
|
||||
|
||||
* **Phase 2: 分类管理**
|
||||
* 实现 `/cat_add` 和 `/cat_list`。
|
||||
* 测试：添加几个分类，重启机器人，确保分类还在。
|
||||
|
||||
|
||||
* **Phase 3: 交互式投稿 (难点)**
|
||||
* 实现 `/post`：只负责发按钮面板。
|
||||
* 实现 `OnCallback`：处理按钮点击，完成转发和存库逻辑。
|
||||
* **验证**：点击按钮能成功把数据送进 DB。
|
||||
|
||||
|
||||
* **Phase 4: 目录自动化**
|
||||
* 接入 `Manager` 和 `Ticker`。
|
||||
* 实现动态渲染逻辑（遍历 DB 里的分类进行拼接）。
|
||||
* 实现 EditMessage 自动刷新。
|
||||
|
||||
|
||||
* **Phase 5: 维护功能**
|
||||
* 补全 `/del`, `/edit` 等修补指令。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
这个文档是否足够清晰？如果没问题，你可以直接把这个发给 Cursor/Windsurf 等 AI 编程助手，或者自己按照 Phase 1 开始写代码了。
|
||||
Reference in New Issue
Block a user