Sakura-Bot

主题

代码重构总结 ​

本文档总结了项目代码重构的主要改进和优化。

📋 重构概述 ​

本次重构主要集中在高优先级的项目优化，包括：

  1. 依赖版本管理
  2. 配置模块化
  3. 数据库持久化
  4. 代码质量提升

✨ 主要改进 ​

1. 依赖版本管理 ​

改进内容：

  • 为所有依赖添加了具体的版本约束
  • 添加了新的依赖：aiosqlite、pydantic、pydantic-settings

文件： requirements.txt

好处：

  • 避免版本冲突
  • 确保开发和生产环境一致
  • 提高项目稳定性

2. 常量集中管理 ​

新增文件： core/constants.py

功能：

  • 集中管理所有魔法数字和硬编码字符串
  • 定义文件路径常量
  • 定义投票相关常量（Telegram 限制等）
  • 定义时间配置常量
  • 定义默认值

好处：

  • 消除魔法数字
  • 便于统一修改
  • 提高代码可维护性

3. 自定义异常类 ​

新增文件： core/exceptions.py

异常类型：

  • BotError - 基础异常类
  • ConfigurationError - 配置错误
  • AIServiceError - AI 服务错误
  • TelegramAPIError - Telegram API 错误
  • ChannelNotFoundError - 频道未找到
  • InvalidScheduleError - 无效时间配置
  • PollGenerationError - 投票生成错误
  • DatabaseError - 数据库错误
  • ValidationError - 验证错误

好处：

  • 更好的错误分类
  • 便于错误处理和日志记录
  • 提高代码可读性

4. 基于 Pydantic 的配置管理 ​

新增文件： core/settings.py

功能：

  • 使用 Pydantic Settings 管理环境变量
  • 自动类型验证
  • 提供便捷的访问函数
  • 支持配置重载

配置类：

  • TelegramSettings - Telegram 配置
  • AISettings - AI 服务配置
  • ChannelSettings - 频道配置
  • AdminSettings - 管理员配置
  • LogSettings - 日志配置
  • PollSettings - 投票配置

好处：

  • 类型安全
  • 自动验证
  • 更好的 IDE 支持
  • 减少配置错误

5. 缓存管理模块 ​

新增文件： core/cache_manager.py

功能：

  • 讨论组 ID 缓存管理
  • 内存缓存 + 持久化存储
  • 支持单个/批量清除缓存

类： DiscussionCache

好处：

  • 减少 Telegram API 调用
  • 提高性能
  • 重启后保留缓存数据

6. 频道时间配置管理 ​

新增文件： core/channel_config.py

功能：

  • 管理频道级的时间配置
  • 支持每天和每周两种模式
  • 配置验证和标准化
  • 格式化配置显示

类： ChannelScheduleManager

好处：

  • 从 config.py 中分离出来
  • 单一职责原则
  • 更易于维护和测试

7. 投票配置管理 ​

新增文件： core/poll_config.py

功能：

  • 管理频道级的投票配置
  • 支持启用/禁用投票
  • 支持配置发送位置

类： ChannelPollConfigManager

好处：

  • 从 config.py 中分离出来
  • 清晰的配置管理
  • 便于扩展

8. 投票数据数据库管理 ​

新增文件： core/poll_data.py

功能：

  • 使用 SQLite 存储投票重新生成数据
  • 异步数据库操作（aiosqlite）
  • 支持并发访问
  • 自动索引优化

数据表：

  • poll_regenerations - 投票重新生成记录
  • poll_voters - 投票者记录

类： PollRegenerationManager

好处：

  • 替代 JSON 文件存储
  • 更好的性能
  • 支持复杂查询
  • 数据完整性保证

9. 类型提示 ​

改进：

  • 为所有新增模块添加了完整的类型提示
  • 使用 Python 3.10+ 的联合类型语法（int | None）
  • 使用 Literal 类型限制取值范围

好处：

  • 更好的 IDE 支持
  • 减少类型错误
  • 提高代码可读性

10. 文档改进 ​

新增文档字符串：

  • 所有新模块都有详细的文档字符串
  • 使用 Google 风格的文档格式
  • 包含参数说明、返回值、异常等

📊 项目结构变化 ​

新增文件 ​

core/
├── constants.py          # 常量定义
├── exceptions.py         # 自定义异常
├── settings.py           # Pydantic 配置管理
├── cache_manager.py      # 缓存管理
├── channel_config.py     # 频道时间配置
├── poll_config.py        # 投票配置
└── poll_data.py          # 投票数据管理

.dockerignore             # Docker 忽略文件
wiki/
└── REFACTORING_SUMMARY.md # 本文档

修改文件 ​

requirements.txt          # 添加版本约束和新依赖
.gitignore               # 添加新的忽略项

🔄 向后兼容性 ​

为确保平滑过渡，所有新模块都提供了向后兼容的便捷函数：

  • get_discussion_cache() - 替代 LINKED_CHAT_CACHE
  • get_channel_schedule() - 保持原有接口
  • set_channel_schedule() - 保持原有接口
  • get_channel_poll_config() - 保持原有接口
  • set_channel_poll_config() - 保持原有接口

📝 后续工作 ​

以下优化尚未实施，可在后续版本中进行：

中优先级 ​

  1. 更新现有模块使用新的配置系统

    • 修改 main.py 使用 core/settings
    • 更新其他模块导入新模块

  2. 数据迁移脚本

    • 从 .poll_regenerations.json 迁移到 SQLite
    • 提供自动迁移功能

  3. 单元测试

    • 为新模块添加单元测试
    • 测试覆盖率 >= 80%

低优先级 ​

  1. Docker 多阶段构建

    • 优化 Dockerfile
    • 减小镜像体积

  2. AI 客户端抽象

    • 定义 BaseAIProvider 接口
    • 支持更多 AI 模型

  3. Web 管理界面

    • 扩展 core/web/ 目录
    • 提供可视化管理

  4. 日志优化

    • 为不同模块设置不同日志级别
    • 结构化日志输出

🎯 最佳实践 ​

遵循本次重构的最佳实践：

  1. 常量集中管理 - 所有常量定义在 core/constants.py
  2. 类型提示 - 所有函数都应有类型提示
  3. 文档字符串 - 使用 Google 风格的文档字符串
  4. 异常处理 - 使用自定义异常类
  5. 单一职责 - 每个模块只负责一个功能域
  6. 依赖注入 - 使用单例模式管理全局实例
  7. 配置验证 - 使用 Pydantic 进行配置验证
  8. 数据持久化 - 优先使用数据库而非 JSON 文件

📚 参考资料 ​

重构日期： 2026-02-03
版本： v1.3.7+

基于 AGPL-3.0 许可证发布

Sakura-Bot 项目文档