# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目架构

这是一个基于Flask的现代化数据库查询比对工具，支持Cassandra和Redis两大数据源的数据一致性验证。采用模块化架构设计，支持单表查询、TWCS分表查询、多主键查询和Redis集群比对等多种复杂场景。

### 核心组件架构

**主应用 (app.py)**
- 应用入口和全局配置管理
- 模块导入和路由设置
- 日志系统初始化

**模块化后端 (modules/)**
- `api_routes.py`: 所有Flask路由和请求处理逻辑
  - Cassandra查询API：`/api/query`, `/api/sharding-query`
  - Redis比对API：`/api/redis/compare`
  - 配置管理API：配置组CRUD操作
  - 查询历史API：历史记录的保存和回放
- `database.py`: SQLite数据库管理
  - 数据库初始化和表结构创建
  - 版本控制和字段动态添加
  - 事务处理和连接管理
- `query_engine.py`: Cassandra查询引擎
  - 单表查询和分表查询执行
  - 多主键查询支持（复合主键SQL构建）
  - 并行查询和性能优化
- `redis_query.py`: Redis查询引擎
  - 全Redis数据类型支持（String/Hash/List/Set/ZSet/Stream）
  - 随机采样和指定Key两种查询模式
  - 集群模式的自动检测和连接
- `data_comparison.py`: 数据比对引擎
  - JSON和数组的智能深度比较
  - 复合主键的精确匹配算法
  - 数据质量评估和建议生成
- `cassandra_client.py` / `redis_client.py`: 数据库客户端
  - 连接管理和错误处理
  - 性能监控和连接池优化
- `config_groups.db`: SQLite数据库，存储配置组、查询历史和日志

**前端 (原生JavaScript + Bootstrap)**
- `templates/index.html`: 工具集合首页，提供功能导航
- `templates/db_compare.html`: Cassandra比对界面
  - 支持单表、分表和多主键三种查询模式
  - 分表模式切换和参数配置
  - 实时查询日志和性能监控
- `templates/redis_compare.html`: Redis比对界面
  - 集群配置和连接管理
  - 随机采样和指定Key两种查询模式
  - 全数据类型支持的结果展示
- `static/js/app.js`: Cassandra查询的前端逻辑
  - 配置管理和表单处理
  - 分页展示和数据可视化
  - 多主键查询的UI适配
- `static/js/redis_compare.js`: Redis比对的前端逻辑
  - Redis集群配置管理
  - 查询模式切换和参数设置
  - 多类型数据的格式化展示

### 关键功能模块

**Cassandra数据比对引擎**
- 支持复杂JSON字段的深度比较
- 数组字段的顺序无关比较
- 字段级别的差异统计和分析
- 数据质量评估和建议生成
- 支持包含和排除特定字段的比较
- 多主键数据比对：支持复合主键的精确匹配和差异检测

**Redis数据比对引擎**
- 全数据类型支持：String、Hash、List、Set、ZSet、Stream
- 智能JSON检测和深度比较
- 集群和单节点模式的自动适配
- 随机采样和指定Key两种查询模式
- 性能监控和连接时间统计

**分表查询功能模块**
- **时间戳提取算法**：使用 `re.sub(r'\D', '', key)` 删除Key中所有非数字字符
- **分表索引计算**：公式 `int(numbers) // interval_seconds % table_count`
- **混合查询场景**：支持生产分表+测试单表等组合
- **并行查询**：多分表同时查询以提高性能

**多主键查询功能模块**
- **复合主键格式**：主键字段逗号分隔，查询值逗号分隔
- **SQL构建逻辑**：自动选择IN查询或OR条件组合
- **数据匹配算法**：统一处理单主键和复合主键匹配
- **向后兼容**：完全兼容现有单主键查询

**用户界面特性**
- 分页系统（差异记录和相同记录）
- 实时搜索和过滤
- 原生数据展示（JSON语法高亮、树形视图）
- 配置导入导出和管理
- 详细的错误诊断和故障排查指南
- 查询历史记录和复用
- 查询日志系统：实时显示SQL执行日志，支持日志级别过滤

## 开发相关命令

### 环境设置
```bash
# 安装依赖
pip install -r requirements.txt

# 运行应用（默认端口5000）
python app.py

# 开发模式启动（支持热重载）
# app.py中默认开启debug=True

# 生产环境运行
# 使用WSGI服务器如gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 app:app
```

### 测试和验证
```bash
# 主要通过Web界面进行功能测试
# Cassandra单表查询：http://localhost:5000/db-compare
# Redis数据比对：http://localhost:5000/redis-compare
# 工具集合首页：http://localhost:5000

# Cassandra多主键查询测试示例：
# 1. 在主键字段中输入：docid,id
# 2. 在查询Key值中输入（每行一组）：
#    8825C293B3609175B2224236E984FEDB,8825C293B3609175B2224236E984FED
#    9925C293B3609175B2224236E984FEDB,9925C293B3609175B2224236E984FED

# Redis查询测试示例：
# 1. 配置两个Redis集群连接
# 2. 选择随机采样模式，设置采样数量
# 3. 或选择指定Key模式，输入要比对的Key列表

# 数据库初始化（如果config_groups.db不存在）
# 通过访问Web界面会自动创建数据库表结构
```

### 依赖项
- Flask==2.3.3
- cassandra-driver==3.29.1
- redis==5.0.1

### 项目特点
- **模块化架构**：清晰的代码组织和职责分离
- **双数据源支持**：同时支持Cassandra和Redis数据比对
- **智能查询引擎**：针对不同数据源的优化查询策略
- **SQLite本地存储**：配置组、查询历史和日志的本地持久化
- **前端原生实现**：使用原生JavaScript + Bootstrap，无现代前端框架依赖
- **多模式支持**：单表查询、分表查询、多主键查询、Redis比对的统一架构

## API架构说明

### Cassandra相关API端点
- `GET /api/default-config`: 获取默认Cassandra配置
- `POST /api/query`: 执行单表数据库查询比对（支持多主键查询）
- `POST /api/sharding-query`: 执行分表查询比对（支持多主键查询）
- `GET /api/config-groups`: 获取所有Cassandra配置组
- `POST /api/config-groups`: 创建新Cassandra配置组
- `GET /api/config-groups/<id>`: 获取特定Cassandra配置组
- `DELETE /api/config-groups/<id>`: 删除Cassandra配置组

### Redis相关API端点
- `POST /api/redis/compare`: 执行Redis数据比对
- `POST /api/redis/test-connection`: 测试Redis连接
- `GET /api/redis/config-groups`: 获取所有Redis配置组
- `POST /api/redis/config-groups`: 创建新Redis配置组
- `GET /api/redis/config-groups/<id>`: 获取特定Redis配置组
- `DELETE /api/redis/config-groups/<id>`: 删除Redis配置组
- `GET /api/redis/query-history`: 获取Redis查询历史
- `POST /api/redis/query-history`: 保存Redis查询历史
- `GET /api/redis/query-history/<id>`: 获取特定Redis历史记录
- `DELETE /api/redis/query-history/<id>`: 删除Redis历史记录

### 通用API端点
- `POST /api/init-db`: 初始化SQLite数据库
- `GET /api/query-history`: 获取Cassandra查询历史
- `POST /api/query-history`: 保存Cassandra查询历史
- `GET /api/query-history/<id>`: 获取特定Cassandra历史记录
- `GET /api/query-history/<id>/results`: 获取历史记录的完整结果数据
- `DELETE /api/query-history/<id>`: 删除Cassandra历史记录
- `GET /api/query-logs`: 获取查询日志（支持limit参数）
- `GET /api/query-logs/history/<id>`: 获取特定历史记录的相关日志
- `DELETE /api/query-logs`: 清空查询日志

### 查询比对流程

**Cassandra单表查询流程（`/api/query`）**：
1. 前端发送配置和Key值列表到 `/api/query`
2. 后端通过 `cassandra_client.py` 创建两个Cassandra连接（生产+测试）
3. `query_engine.py` 并行执行查询，获取原始数据
4. `data_comparison.py` 运行比较算法，生成差异报告
5. 返回完整结果（差异、统计、原始数据）

**Cassandra分表查询流程（`/api/sharding-query`）**：
1. 前端发送配置、Key值列表和分表配置到 `/api/sharding-query`
2. 后端使用 `sharding.py` 中的 `ShardingCalculator` 解析Key中的时间戳
3. 根据分表算法计算每个Key对应的分表名称
4. `query_engine.py` 创建分表映射关系，并行执行分表查询
5. 汇总所有分表结果，执行比较算法
6. 返回包含分表信息的完整结果

**Redis数据比对流程（`/api/redis/compare`）**：
1. 前端发送Redis集群配置和查询参数到 `/api/redis/compare`
2. 后端通过 `redis_client.py` 创建两个Redis连接
3. `redis_query.py` 根据查询模式执行数据获取：
   - 随机采样模式：从源集群随机获取指定数量的Key
   - 指定Key模式：查询用户提供的Key列表
4. 针对每个Key，查询其在两个集群中的值和数据类型
5. 执行智能数据比较（根据数据类型选择比较策略）
6. 返回比对结果和统计信息

## 数据结构和配置

### Cassandra配置结构

**单表查询配置**：
```javascript
{
  pro_config: {
    cluster_name, datacenter, hosts[], port, 
    username, password, keyspace, table
  },
  test_config: { /* 同上 */ },
  keys: ["主键字段名"],  // 支持多个字段，如 ["docid", "id"]
  fields_to_compare: ["字段1", "字段2"], // 空数组=全部字段
  exclude_fields: ["排除字段"],
  values: ["key1", "key2", "key3"] // 单主键或复合主键值
}
```

**分表查询配置**：
```javascript
{
  pro_config: { /* 基础配置同上 */ },
  test_config: { /* 基础配置同上 */ },
  keys: ["主键字段名"],  // 支持复合主键
  fields_to_compare: ["字段1", "字段2"],
  exclude_fields: ["排除字段"],
  values: ["key1", "key2", "key3"],  // 支持复合主键值
  sharding_config: {
    use_sharding_for_pro: true,    // 生产环境是否使用分表
    use_sharding_for_test: false,  // 测试环境是否使用分表
    interval_seconds: 604800,      // 分表时间间隔（默认7天）
    table_count: 14               // 分表数量（默认14张表）
  }
}
```

### Redis配置结构

**Redis集群配置**：
```javascript
{
  source_config: {
    name: "源集群名称",
    nodes: [
      {host: "192.168.1.200", port: 7000},
      {host: "192.168.1.201", port: 7001}
    ],
    password: "redis_password",
    socket_timeout: 3,
    socket_connect_timeout: 3,
    max_connections_per_node: 16
  },
  target_config: { /* 同上 */ },
  query_config: {
    mode: "random_sample",  // 或 "specific_keys"
    sample_size: 1000,      // 随机采样数量（random_sample模式）
    keys: ["key1", "key2"], // 指定Key列表（specific_keys模式）
    key_pattern: "*"        // Key匹配模式（可选）
  }
}
```

**多主键查询格式示例**：
```javascript
// 复合主键配置
keys: ["docid", "id"]

// 复合主键查询值（逗号分隔）
values: [
  "8825C293B3609175B2224236E984FEDB,8825C293B3609175B2224236E984FED",
  "9925C293B3609175B2224236E984FEDB,9925C293B3609175B2224236E984FED"
]
```

### 查询结果结构

**Cassandra查询结果**：
```javascript
{
  total_keys, pro_count, test_count,
  differences: [{ 
    key: {docid: "val1", id: "val2"}, // 支持复合主键对象
    field, pro_value, test_value, message 
  }],
  identical_results: [{ 
    key: {docid: "val1", id: "val2"}, // 支持复合主键对象
    pro_fields, test_fields 
  }],
  field_diff_count: { "field_name": count },
  raw_pro_data: [], raw_test_data: [],
  summary: { overview, percentages, field_analysis, recommendations },
  
  // 分表查询特有字段
  sharding_info: {
    pro_shard_mapping: { "key1": "table_name_0", "key2": "table_name_1" },
    test_shard_mapping: { /* 同上 */ },
    failed_keys: [], // 时间戳提取失败的Key
    shard_stats: {
      pro_tables_used: ["table_0", "table_1"],
      test_tables_used: ["table_0"],
      timestamp_extraction_success_rate: 95.5
    }
  }
}
```

**Redis查询结果**：
```javascript
{
  total_keys, source_count, target_count,
  identical_count, different_count, source_only_count, target_only_count,
  
  // 详细比对结果
  identical_keys: ["key1", "key2"],
  different_keys: [
    {
      key: "key3",
      source_type: "string", target_type: "string",
      source_value: "value1", target_value: "value2",
      message: "Value mismatch"
    }
  ],
  source_only_keys: ["key4"], // 仅源集群存在
  target_only_keys: ["key5"], // 仅目标集群存在
  
  // 统计信息
  type_distribution: {
    "string": 500, "hash": 200, "list": 100,
    "set": 50, "zset": 30, "stream": 20
  },
  consistency_percentage: 85.5,
  
  // 性能统计
  query_time: 2.5,
  source_connection_time: 0.1,
  target_connection_time: 0.15
}
```

## 开发注意事项

### 代码修改指导
- **模块化开发**：功能按模块组织，修改时注意模块间的依赖关系
- **数据库模式变更**：修改SQLite表结构需要考虑向后兼容性
- **前端JavaScript**：分别位于 `static/js/app.js`（Cassandra）和 `static/js/redis_compare.js`（Redis）
- **HTML模板**：使用Jinja2模板引擎，主要文件在 `templates/` 目录

### 关键模块和类位置
- **主应用**：`app.py` - 应用入口和模块集成
- **路由管理**：`modules/api_routes.py` - 所有API端点的实现
- **数据库管理**：`modules/database.py` - SQLite数据库操作
- **Cassandra客户端**：`modules/cassandra_client.py` - 连接管理和查询执行
- **Redis客户端**：`modules/redis_client.py` - Redis连接和性能监控
- **查询引擎**：`modules/query_engine.py` - Cassandra查询逻辑
- **Redis查询**：`modules/redis_query.py` - Redis数据比对逻辑
- **数据比较**：`modules/data_comparison.py` - 智能数据比较算法
- **分表计算**：`modules/sharding.py` - TWCS分表逻辑
- **配置管理**：`modules/config_manager.py` - 配置组管理
- **日志收集**：`modules/query_logger.py` - 查询日志系统

### 模块依赖关系
```
app.py
├── modules/api_routes.py (路由层)
    ├── modules/config_manager.py (配置管理)
    ├── modules/cassandra_client.py (Cassandra连接)
    ├── modules/redis_client.py (Redis连接)
    ├── modules/query_engine.py (Cassandra查询)
    │   ├── modules/sharding.py (分表计算)
    │   └── modules/data_comparison.py (数据比较)
    ├── modules/redis_query.py (Redis查询)
    └── modules/database.py (SQLite数据库)
```

### 开发最佳实践
- **错误处理**：每个模块都有详细的错误分类和处理机制
- **日志记录**：使用统一的日志系统，支持不同级别的日志输出
- **性能监控**：查询时间和连接时间的详细统计
- **配置管理**：支持配置的导入导出和版本管理
- **数据安全**：敏感信息（密码）的安全处理