优化项目整合内容

modules/sharding.py

@@ -1,6 +1,41 @@
 """
-分表计算模块
-负责TWCS时间分表的计算和映射
+TWCS分表计算引擎模块
+===================
+
+本模块实现基于TWCS（Time Window Compaction Strategy）策略的时间分表计算功能。
+
+核心功能：
+1. 时间戳提取：从Key中智能提取时间戳信息
+2. 分表索引计算：基于时间窗口计算目标分表索引
+3. 分表映射：将大批量Key映射到对应的分表
+4. 统计分析：提供分表计算的详细统计信息
+
+TWCS分表策略：
+- 时间窗口：可配置的时间间隔（默认7天）
+- 分表数量：可配置的分表总数（默认14张）
+- 计算公式：timestamp // interval_seconds % table_count
+- 表命名：base_table_name + "_" + shard_index
+
+时间戳提取算法：
+- 优先规则：提取Key中最后一个下划线后的数字
+- 备用规则：提取Key中最长的数字序列
+- 容错处理：无法提取时记录到失败列表
+- 格式支持：支持各种Key格式的时间戳提取
+
+应用场景：
+- 大数据表的时间分片：按时间窗口将数据分散到多张表
+- 查询性能优化：减少单表数据量，提高查询效率
+- 数据生命周期管理：支持按时间窗口的数据清理
+- 负载均衡：将查询负载分散到多张表
+
+性能特点：
+- 批量计算：支持大批量Key的高效分表计算
+- 内存友好：使用生成器和迭代器优化内存使用
+- 统计完整：提供详细的计算成功率和分布统计
+- 错误容错：单个Key计算失败不影响整体处理
+
+作者：BigDataTool项目组
+更新时间：2024年8月
 """
 
 import re
@@ -9,7 +44,24 @@ import logging
 logger = logging.getLogger(__name__)
 
 class ShardingCalculator:
-    """分表计算器，基于TWCS策略"""
+    """
+    TWCS分表计算器
+
+    基于Time Window Compaction Strategy实现的智能分表计算器，
+    用于将时间相关的Key映射到对应的时间窗口分表。
+
+    主要特性：
+    - 时间窗口分片：按配置的时间间隔进行分表
+    - 智能时间戳提取：支持多种Key格式的时间戳解析
+    - 负载均衡：通过取模运算实现分表间的负载均衡
+    - 批量处理：高效处理大批量Key的分表映射
+
+    适用场景：
+    - 时序数据的分表存储
+    - 大数据表的性能优化
+    - 数据生命周期管理
+    - 查询负载分散
+    """
     
     def __init__(self, interval_seconds=604800, table_count=14):
         """