Common 模块深度分析

src/common 模块构成了 Panda Quantflow 的基础设施层，提供了配置管理、数据库连接、日志系统、定时任务调度以及标准化的数据模型定义。

1. 目录结构概览

src/common/
├── config/           # 配置管理 (Env, INI)
├── connector/        # 数据库连接器 (MySQL, MongoDB, Redis)
├── logging/          # 双层日志系统 (System & User)
├── cron/             # APScheduler 定时任务管理
├── utils/            # 通用工具 (微信推送, IC计算)
└── backtest/         # 回测数据模型定义
    └── model/        # Pydantic 模型

2. 核心子模块详解

2.1 配置管理 (Config)

负责加载环境变量和配置文件，支持多环境切换（Local/Dev/Prod）。

• 文件: src/common/config/config.py

  • 功能: 优先读取环境变量，提供默认配置。
  • 关键函数: load_config() - 构建包含 DB、Redis、Log 配置的字典。
  • 依赖: os

• 文件: src/common/config/project.py

  • 功能: 基于 configparser 解析 .ini 文件。
  • 关键类: ProjectConfig (单例)

2.2 数据库连接器 (Connector)

封装了主流数据库的客户端，实现了连接池管理和异常处理。

• 文件: src/common/connector/mongodb_handler.py

  • 职责: MongoDB 操作封装，支持单节点/副本集。
  • 核心类: DatabaseHandler (单例)
  • 接口: mongo_insert, mongo_find, mongo_update, mongo_delete等

• 文件: src/common/connector/redis_client.py

  • 职责: Redis 操作封装，支持 Pub/Sub 消息机制。
  • 核心类: RedisClient
  • 接口: set/get (String), setHashRedis (Hash), public/subscribe (MQ)

• 文件: src/common/connector/mysql_client.py

  • 职责: MySQL 操作封装，基于 DBUtils 连接池。
  • 核心类: MysqlClient, SunriseMySqlClient

2.3 日志系统 (Logging)

实现了系统级运维日志与用户级业务日志的分离。

• 文件: src/common/logging/system_logger.py

  • 职责: 系统底层日志，支持控制台彩色输出与 JSON 格式化。
  • 核心类: ColoredFormatter

• 文件: src/common/logging/user_logger.py

  • 职责: 记录用户的策略运行日志。
  • 特性: 支持双模式路由：
    • CLOUD 模式: 推送至 RabbitMQ (避免阻塞计算节点)。
    • LOCAL 模式: 直接写入 MongoDB。
  • 核心类: UserLogger

2.4 定时任务 (Cron)

基于 APScheduler 的分布式任务调度基础组件。

• 文件: src/common/cron/crontab_manager.py
  • 职责: 管理调度器生命周期，动态增删任务。
  • 关键函数: init_all_task - 扫描并自动注册 @cron_task 装饰的任务。

2.5 回测数据模型 (Backtest Model)

定义了回测模块与数据库交互的标准 Pydantic 模型。

2.6 通用工具 (Utils)

• index_calculate.py: IC (Information Coefficient) 计算工具，支持 Spearman/Pearson 相关系数，用于因子分析。
• wechat_push.py: 微信消息推送工具 (PushPlus)，用于策略信号通知或报警。