carrydela/mygoTgChanBot

Fork 1

Files

dela d82badc6e3 first

2026-02-04 22:33:45 +08:00

6.1 KiB

Raw Permalink Blame History

这是一份为了正式开发准备的 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)

.
├── 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 (存元数据，如创建时间，用于排序)

{"name": "iOS", "created_at": 1698123456}

Bucket: `Entries`

Key: 短 ID (如 "a1b2c")
Value: 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 核心

触发: 管理员回复某条消息，发送 /post (可带参数：/post 自定义标题)。
响应: 机器人不立即转发。它读取 DB 里的分类列表，生成一个 Inline Keyboard (按钮面板)。

请选择分类： [ 🍎 iOS ] [ 🤖 Android ] [ 💻 Windows ] [ ❌ 取消 ]

选择: 管理员点击 [ 🍎 iOS ] 按钮。
处理 (Callback):

机器人收到回调事件 OnCallback。
获取原消息内容、管理员刚才输入的标题（需要暂存在 Context 或解析 Payload）。
执行转发 -> 生成链接 -> 存入 DB -> 触发目录更新。

清理: 机器人删除那个带有按钮的面板，保持群聊整洁。

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)

由于分类现在是动态的，渲染顺序建议如下：

从 DB 读取所有 Categories。
排序：按字母顺序 (A-Z) 或创建时间 (Oldest First)。
遍历排序后的分类列表：

从内存 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 开始写代码了。

6.1 KiB Raw Permalink Blame History Unescape Escape