这是一份为了**正式开发**准备的 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 开始写代码了。