一个面向 Telegram 社群运营的自动化 Bot：入群验证/反机器人、邀请裂变、积分体系、积分商城、管理员多群广播与话题路由。适用于需要“可配置、可部署、可排障”的长期运营社群场景。
详细说明见：
GUIDE.md（部署与排障）、ADMIN_GUIDE.md（管理员指南）、USER_GUIDE.md（用户指南）。
- 入群风控：新成员入群自动禁言 + 验证按钮，超时处理；验证通过自动解禁并可发送欢迎语。
- 邀请裂变：私聊
/invite生成专属 deep link（ref_<referrerId>_<groupId>），好友入群并验证后自动奖励积分。 - 积分系统：签到口令、晒单关键词（盈/损）、每日次数上限；支持积分榜
/top与个人资产/my。 - 积分商城：管理员私聊上架商品（可带图）、群内兑换扣积分、生成核销码、管理员私聊核销鉴权。
- 多群广播：终极管理员在管理群发消息 → 选择类型（早报/分析/战绩/信号/General）→ 按群订阅与 topic 绑定自动分发；支持相册媒体组广播与回复追踪。
- 运维友好：SQLite + WAL、启动时 schema 热更新、旧版
bot_data.json迁移、定时清理旧数据、群失效自动剔除广播。
.
├── main.py # Bot 入口（polling）
├── config.py # 环境变量 + DB 路径等配置
├── handlers/ # 业务模块（验证/邀请/广播/商城/配置面板/互动等）
├── database/storage.py # SQLite 存储层 + 迁移/热更新
├── utils/ # 外部 API/工具封装
├── Dockerfile # 生产部署建议：Docker
├── GUIDE.md # 使用与部署指南（推荐先读）
├── ADMIN_GUIDE.md # 群管理员使用指南
└── USER_GUIDE.md # 普通用户使用指南
要求：Python 3.13+（推荐 Docker 跑生产）。
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt创建 .env：
BOT_TOKEN=xxxxx
ADMIN_GROUP_ID=123456789 # 推荐填你的个人 user_id；也可以是一个“管理员群” chat_id启动：
python main.py启动成功后会看到日志：EchoWave Pro Max (SQLite Edition) 已启动...
构建镜像：
docker build -t echowavebot:latest .运行（推荐挂载目录，持久化 DB + WAL 文件）：
docker run -d \
--name echowavebot \
--restart always \
-v /root/echowave_data:/app/data \
--env-file /root/.env \
echowavebot:latest默认 DB 路径为 data/echowave.db（含 .db-wal/.db-shm），目录挂载能保证容器重启/升级不丢数据。
建议按 ADMIN_GUIDE.md 开启：
- 发送消息
- 删除消息（清理验证消息等）
- 限制成员/解除限制（入群验证禁言/解禁）
- 邀请用户/创建邀请链接（生成入群按钮）
- 管理话题（如使用话题路由广播）
- 查看管理员列表（商城核销鉴权）
用户侧（群内为主）：
/shop积分商城/my我的积分/段位/top积分榜/fear恐慌贪婪指数/help帮助
增长侧（建议私聊 Bot 使用）：
/invite生成邀请链接
管理员侧：
/setup（私聊）配置群：欢迎语/验证开关/积分规则/订阅/话题绑定等/add_product（私聊）上架商品/products（私聊）管理商品/use <核销码>（私聊）核销订单（需在订单所属群有管理员权限）/request_broadcast（群内）申请成为广播群
终极管理员（ADMIN_GROUP_ID）：
/report审计群列表/订阅状态/revoke <chat_id>移除群广播权限/set_topic <news|analysis|marketing|signal>绑定当前话题为某类型路由
更多详见 GUIDE.md 的“常见问题与排障”一节。这里列几个高频：
/invite没有入群按钮：Bot 缺少“创建邀请链接”权限或不在群。- 回执发不进原话题：话题失效会自动降级发送到 General。
- 广播失败：群不存在/被踢会自动移除广播标记。
- 数据丢失：生产环境请务必挂载
data/目录。