# DataTools Pro 系统架构设计

## 1. 系统概述

### 1.1 项目简介
DataTools Pro 是一个企业级数据处理与比对工具平台，专注于提供高效、精准、可视化的数据分析解决方案。系统支持Cassandra数据库和Redis集群的数据比对分析，具备分表查询、多主键查询、配置管理等企业级功能。

### 1.2 设计目标
- **高性能**: 支持大规模数据查询和比对处理
- **高可用**: 企业级稳定性和容错能力
- **易扩展**: 模块化设计，便于功能扩展
- **用户友好**: 直观的Web界面和操作体验
- **安全性**: 数据安全和访问控制

### 1.3 技术栈
```
前端技术栈:
├── 原生JavaScript (ES6+)
├── Bootstrap 5.1.3
├── Font Awesome 6.0.0
└── 模块化架构 (ES6 Modules)

后端技术栈:
├── Python 3.7+
├── Flask 2.3.3
├── Cassandra Driver 3.29.1
├── Redis Client
└── SQLite (配置存储)

数据存储:
├── Apache Cassandra (主要数据源)
├── Redis Cluster (缓存和数据源)
└── SQLite (配置和历史数据)
```

## 2. 整体架构

### 2.1 架构概览
```
┌─────────────────────────────────────────────────────────────┐
│                    DataTools Pro 架构图                      │
├─────────────────────────────────────────────────────────────┤
│  前端层 (Frontend Layer)                                   │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐│
│  │   首页模块      │  │ Cassandra工具   │  │   Redis工具     ││
│  │   index.html    │  │ db_compare.html │  │redis_compare.html││
│  └─────────────────┘  └─────────────────┘  └─────────────────┘│
│              │                   │                   │        │
│  ┌───────────────────────────────────────────────────────────┐│
│  │              模块化JavaScript架构                          ││
│  │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐││
│  │ │ config  │ │  utils  │ │   api   │ │   ui    │ │  nav    │││
│  │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘││
│  └───────────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────────┤
│  网关层 (Gateway Layer)                                     │
│  ┌───────────────────────────────────────────────────────────┐│
│  │                Flask Web Server                           ││
│  │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐││
│  │ │  静态资源   │ │  API路由    │ │      模板渲染           │││
│  │ │  服务       │ │  处理       │ │      引擎               │││
│  │ └─────────────┘ └─────────────┘ └─────────────────────────┘││
│  └───────────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────────┤
│  业务逻辑层 (Business Logic Layer)                          │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐│
│  │   查询引擎      │  │   数据比对      │  │   配置管理      ││
│  │ QueryEngine     │  │ DataComparison  │  │ ConfigManager   ││
│  └─────────────────┘  └─────────────────┘  └─────────────────┘│
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐│
│  │   分表处理      │  │   日志收集      │  │   Redis处理     ││
│  │ ShardingCalc    │  │ QueryLogger     │  │ RedisClient     ││
│  └─────────────────┘  └─────────────────┘  └─────────────────┘│
├─────────────────────────────────────────────────────────────┤
│  数据访问层 (Data Access Layer)                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐│
│  │  Cassandra      │  │  Redis Cluster  │  │   SQLite DB     ││
│  │  客户端         │  │  客户端         │  │   本地存储      ││
│  └─────────────────┘  └─────────────────┘  └─────────────────┘│
├─────────────────────────────────────────────────────────────┤
│  数据存储层 (Data Storage Layer)                            │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐│
│  │   生产环境      │  │   测试环境      │  │   配置数据      ││
│  │  Cassandra      │  │  Cassandra      │  │   SQLite        ││
│  └─────────────────┘  └─────────────────┘  └─────────────────┘│
│  ┌─────────────────┐  ┌─────────────────┐                    │
│  │   生产Redis     │  │   测试Redis     │                    │
│  │   集群          │  │   集群          │                    │
│  └─────────────────┘  └─────────────────┘                    │
└─────────────────────────────────────────────────────────────┘
```

### 2.2 核心组件

#### 2.2.1 前端架构
```javascript
// 模块化架构设计
static/js/
├── app-main.js              // 主应用入口，统一管理
└── modules/
    ├── config.js            // 配置管理 - API端点、UI配置
    ├── utils.js             // 工具函数 - 通用功能库
    ├── api.js               // HTTP客户端 - 统一请求处理
    ├── ui.js                // UI组件 - 提示、模态框、分页
    └── navigation.js        // 导航管理 - 路由、面包屑、快捷键
```

**设计模式**: 模块化 + 单例模式
**核心特性**:
- ES6模块化，避免全局变量污染
- 统一的配置管理和错误处理
- 响应式UI组件和交互增强
- 键盘快捷键和无障碍支持

#### 2.2.2 后端架构
```python
# 模块化后端设计
modules/
├── api_routes.py           // API路由定义和请求处理
├── cassandra_client.py     // Cassandra数据库连接和操作
├── redis_client.py         // Redis集群连接和操作
├── query_engine.py         // 查询引擎和SQL构建
├── data_comparison.py      // 数据比对算法和分析
├── sharding.py             // 分表计算和时间戳处理
├── config_manager.py       // 配置组管理和持久化
├── query_logger.py         // 查询日志收集和管理
└── database.py             // SQLite数据库操作
```

**设计模式**: 分层架构 + 依赖注入
**核心特性**:
- 单一职责原则，模块解耦
- 统一的错误处理和日志记录
- 连接池管理和资源优化
- 配置驱动的灵活部署

## 3. 核心功能模块

### 3.1 Cassandra数据比对模块

#### 3.1.1 功能特性
- **多模式查询**: 单表查询、分表查询、多主键查询
- **时间分表支持**: TWCS (Time Window Compaction Strategy) 分表计算
- **复合主键**: 支持多字段组合主键查询
- **字段级比对**: 支持包含/排除字段的精细化比较
- **JSON处理**: 智能JSON字段识别和深度比较

#### 3.1.2 核心算法
```python
# 分表索引计算算法
def calculate_shard_index(timestamp, interval_seconds, table_count):
    """
    计算分表索引
    - timestamp: 从Key中提取的时间戳
    - interval_seconds: 分表时间间隔(默认604800秒=7天)
    - table_count: 分表数量(默认14张表)
    """
    return int(timestamp) // interval_seconds % table_count

# 时间戳提取算法
def extract_timestamp_from_key(key):
    """
    从Key中提取时间戳 - 删除所有非数字字符
    示例: 'wmid_1609459200' -> 1609459200
    """
    return re.sub(r'\D', '', key)

# 复合主键匹配算法
def match_composite_key(record, key_fields, key_values):
    """
    复合主键匹配逻辑
    - 支持单主键和复合主键统一处理
    - 自动类型转换和字段验证
    """
    if len(key_fields) == 1:
        return str(record.get(key_fields[0])) == str(key_values[0])
    else:
        return all(
            str(record.get(field)) == str(value) 
            for field, value in zip(key_fields, key_values)
        )
```

### 3.2 Redis集群比对模块

#### 3.2.1 功能特性
- **多数据类型支持**: String、Hash、List、Set、ZSet
- **查询模式**: 随机采样、指定Key查询
- **集群管理**: 多节点集群配置和连接管理
- **性能监控**: 连接状态、查询耗时统计
- **批量操作**: 大批量Key的并行处理

#### 3.2.2 Redis集群架构
```python
# Redis集群连接配置
{
    "cluster_name": "生产集群",
    "nodes": [
        {"host": "127.0.0.1", "port": 6379},
        {"host": "127.0.0.1", "port": 6380}
    ],
    "password": "optional_password",
    "socket_timeout": 3,
    "socket_connect_timeout": 3,
    "max_connections_per_node": 16
}
```

### 3.3 数据比对引擎

#### 3.3.1 比对算法
```python
# 数据比对核心逻辑
class DataComparison:
    def compare_results(self, pro_data, test_data, key_fields):
        """
        数据比对主算法:
        1. 构建数据索引映射 (基于主键)
        2. 逐字段深度比较
        3. JSON字段特殊处理
        4. 数组字段顺序无关比较
        5. 生成差异报告和统计
        """
        differences = []
        identical_results = []
        field_diff_count = {}
        
        # 构建生产数据索引
        pro_index = self.build_data_index(pro_data, key_fields)
        test_index = self.build_data_index(test_data, key_fields)
        
        # 执行比对逻辑
        for key, pro_record in pro_index.items():
            if key in test_index:
                test_record = test_index[key]
                diffs = self.compare_records(pro_record, test_record)
                if diffs:
                    differences.extend(diffs)
                else:
                    identical_results.append({
                        'key': key, 
                        'pro_fields': pro_record,
                        'test_fields': test_record
                    })
        
        return {
            'differences': differences,
            'identical_results': identical_results,
            'field_diff_count': field_diff_count,
            'summary': self.generate_summary(differences, identical_results)
        }
```

#### 3.3.2 JSON处理算法
```python
def compare_json_values(pro_value, test_value):
    """
    JSON值比较算法:
    1. 智能检测JSON格式
    2. 规范化JSON字符串
    3. 深度比较对象结构
    4. 数组顺序无关比较
    """
    if self.is_json_field(pro_value) and self.is_json_field(test_value):
        try:
            pro_obj = json.loads(pro_value)
            test_obj = json.loads(test_value)
            return self.deep_compare_objects(pro_obj, test_obj)
        except:
            return pro_value == test_value
    return pro_value == test_value
```

## 4. 数据流架构

### 4.1 查询执行流程
```mermaid
graph TD
    A[用户请求] --> B[前端验证]
    B --> C[API路由]
    C --> D{查询类型}
    D -->|单表查询| E[QueryEngine.execute_query]
    D -->|分表查询| F[QueryEngine.execute_sharding_query]
    E --> G[数据库连接]
    F --> H[分表计算]
    H --> G
    G --> I[并行查询执行]
    I --> J[数据收集]
    J --> K[DataComparison.compare_results]
    K --> L[结果分析]
    L --> M[日志记录]
    M --> N[响应返回]
```

### 4.2 配置管理流程
```mermaid
graph TD
    A[配置创建/更新] --> B[ConfigManager验证]
    B --> C[SQLite持久化]
    C --> D[配置缓存更新]
    D --> E[前端状态同步]
    
    F[配置加载] --> G[SQLite查询]
    G --> H[配置反序列化]
    H --> I[前端配置应用]
```

## 5. 性能优化策略

### 5.1 查询优化
- **连接池管理**: 复用数据库连接，减少连接开销
- **并行查询**: 多线程并行执行生产和测试环境查询
- **分批处理**: 大量Key分批查询，避免内存溢出
- **索引优化**: 合理设计Cassandra分区键和聚簇键

### 5.2 前端性能
- **懒加载**: 按需加载JS模块和数据
- **虚拟分页**: 大数据集的分页展示
- **防抖节流**: 用户输入和搜索的性能优化
- **缓存策略**: 查询结果和配置数据的客户端缓存

### 5.3 内存管理
- **流式处理**: 大数据集的流式读取和处理
- **及时释放**: 查询完成后及时释放数据库连接和内存
- **垃圾回收**: Python和JavaScript的内存回收优化

## 6. 扩展性设计

### 6.1 水平扩展
- **无状态设计**: 应用层无状态，支持负载均衡
- **配置外部化**: 支持配置中心和环境变量
- **容器化**: Docker容器化部署
- **微服务拆分**: 可拆分为独立的查询服务和比对服务

### 6.2 功能扩展
- **插件架构**: 支持自定义数据源和比对算法
- **API开放**: RESTful API支持第三方集成
- **规则引擎**: 可配置的数据验证和比对规则
- **报告生成**: 支持多种格式的报告导出

## 7. 安全架构

### 7.1 数据安全
- **连接加密**: 支持SSL/TLS加密连接
- **密码管理**: 敏感信息加密存储
- **访问控制**: 基于角色的权限管理
- **审计日志**: 完整的操作审计记录

### 7.2 系统安全
- **输入验证**: 严格的参数验证和SQL注入防护
- **错误处理**: 不暴露敏感系统信息
- **会话管理**: 安全的会话管理机制
- **网络安全**: 防火墙和网络隔离

## 8. 监控和运维

### 8.1 系统监控
- **性能指标**: 查询耗时、成功率、错误率
- **资源监控**: CPU、内存、网络使用情况
- **业务指标**: 查询量、用户活跃度、功能使用统计
- **告警机制**: 异常情况的实时告警

### 8.2 日志管理
- **结构化日志**: JSON格式的结构化日志
- **日志分级**: INFO、WARNING、ERROR、DEBUG
- **日志轮转**: 自动日志清理和归档
- **日志分析**: 支持ELK等日志分析工具

## 9. 技术债务和改进计划

### 9.1 当前技术债务
- **单体应用**: 所有功能集中在单个Flask应用中
- **前端技术**: 使用原生JavaScript，缺乏现代化框架
- **测试覆盖**: 缺乏完整的单元测试和集成测试
- **文档完善**: API文档和代码注释需要完善

### 9.2 改进计划
- **微服务改造**: 逐步拆分为独立的微服务
- **前端升级**: 考虑引入Vue.js或React框架
- **CI/CD**: 建立完整的持续集成和部署流程
- **性能测试**: 建立性能基准和压力测试

---

**版本**: v2.0.0  
**更新日期**: 2024-08-05  
**维护者**: DataTools Pro Team