# CLAUDE.md

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

## 项目架构

这是一个基于 Flask 的数据库查询比对工具，用于比较 Cassandra 数据库中生产环境和测试环境的数据差异。现已支持单表查询和TWCS分表查询两种模式。

### 核心组件架构

**后端 (Flask)**
- `app.py`: 主应用文件，包含所有API端点和数据处理逻辑
  - 数据库连接管理（Cassandra + SQLite）
  - 查询执行和结果比对算法
  - 配置组管理（CRUD操作）
  - JSON字段特殊处理和数组比较逻辑
  - 查询历史记录管理
  - **分表查询功能（新增）**：
    - `ShardingCalculator`类：TWCS时间分表计算器
    - `execute_sharding_query()`：分表查询执行
    - `execute_mixed_query()`：混合查询支持（生产分表+测试单表组合）
    - `/api/sharding-query`：分表查询API端点
- `config_groups.db`: SQLite数据库，存储用户保存的配置组、查询历史和分表配置

**前端 (原生JavaScript + Bootstrap)**
- `templates/db_compare.html`: 主界面模板，**现已支持单表和分表双模式**
  - 分表模式切换开关
  - 生产/测试环境独立分表配置
  - 分表参数配置（时间间隔、分表数量）
  - 分表查询信息展示
- `templates/index.html`: 工具集合首页
- `static/js/app.js`: 核心前端逻辑
  - 配置管理和表单处理
  - 差异结果的分页展示系统
  - 原生数据展示（多种视图模式：格式化、原始、差异对比、树形）
  - 高级错误处理和用户反馈
  - **分表查询支持（新增）**：
    - `toggleShardingMode()`：分表模式切换
    - `getShardingConfig()`：分表配置获取
    - `displayShardingInfo()`：分表查询结果展示

**分表查询功能模块（重要新增）**
- **时间戳提取算法（已更新）**：
  - **新规则**：使用 `re.sub(r'\D', '', key)` 删除Key中所有非数字字符
  - 将提取到的数字字符串转换为整数作为时间戳
  - 支持任意格式的Key，只要包含数字即可
  - 示例：`wmid_1609459200` → `1609459200`，`abc123def456` → `123456`
- **分表索引计算**：
  - 公式：`int(numbers) // interval_seconds % table_count`
  - 默认配置：604800秒间隔（7天），14张分表
  - 支持自定义配置
- **混合查询场景**：
  - 生产环境分表 + 测试环境单表
  - 生产环境分表 + 测试环境分表  
  - 生产环境单表 + 测试环境分表
  - 生产环境单表 + 测试环境单表

**核心文件**
- `app.py`: 唯一的主应用文件，包含所有功能实现
- `config_groups.db`: SQLite数据库文件

### 关键功能模块

**数据比对引擎**
- 支持复杂JSON字段的深度比较
- 数组字段的顺序无关比较
- 字段级别的差异统计和分析
- 数据质量评估和建议生成
- 支持包含和排除特定字段的比较

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

## 开发相关命令

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

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

# 自定义端口运行
# 修改app.py最后一行：app.run(debug=True, port=XXXX)

# 生产环境运行
# python app.py 或使用WSGI服务器如gunicorn
```

### 调试和日志
```bash
# 应用启动后，查询日志可通过以下API获取：
# GET /api/query-logs - 获取查询日志
# DELETE /api/query-logs - 清空查询日志

# 日志级别：INFO, WARNING, ERROR
# 所有Cassandra查询和SQL操作都会记录到查询日志中
```

### 测试和验证
```bash
# 主要通过Web界面进行功能测试
# 单表查询测试：http://localhost:5000/db-compare
# 分表查询测试：在Web界面中开启分表模式

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

### 开发模式
应用默认运行在debug模式，代码修改后自动重启。访问：
- http://localhost:5000 - 工具集合首页  
- http://localhost:5000/db-compare - 数据库比对工具

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

### 项目特点
- **单文件架构**：所有后端逻辑都在 `app.py` 中实现（1400+行代码）
- **内存日志系统**：使用 `QueryLogCollector` 类在内存中收集查询日志
- **SQLite本地存储**：配置组和查询历史存储在本地 `config_groups.db` 文件中
- **前端原生实现**：使用原生JavaScript + Bootstrap，无现代前端框架

## API架构说明

### 核心API端点
- `GET /api/default-config`: 获取默认数据库配置
- `POST /api/query`: 执行单表数据库查询比对（原有功能）
- `POST /api/sharding-query`: 执行分表查询比对（新增功能）
- `GET /api/config-groups`: 获取所有配置组
- `POST /api/config-groups`: 创建新配置组
- `GET /api/config-groups/<id>`: 获取特定配置组
- `DELETE /api/config-groups/<id>`: 删除配置组
- `POST /api/init-db`: 初始化SQLite数据库
- `GET /api/query-history`: 获取查询历史
- `POST /api/query-history`: 保存查询历史
- `GET /api/query-history/<id>`: 获取特定历史记录
- `DELETE /api/query-history/<id>`: 删除历史记录
- `GET /api/query-logs`: 获取查询日志（支持limit参数）
- `DELETE /api/query-logs`: 清空查询日志

### 查询比对流程

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

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

## 数据结构和配置

### 数据库配置结构

**单表查询配置**：
```javascript
{
  pro_config: {
    cluster_name, datacenter, hosts[], port, 
    username, password, keyspace, table
  },
  test_config: { /* 同上 */ },
  keys: ["主键字段名"],
  fields_to_compare: ["字段1", "字段2"], // 空数组=全部字段
  exclude_fields: ["排除字段"],
  values: ["key1", "key2", "key3"] // 要查询的Key值
}
```

**分表查询配置**：
```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张表）
  }
}
```

### 查询结果结构
```javascript
{
  total_keys, pro_count, test_count,
  differences: [{ key, field, pro_value, test_value, message }],
  identical_results: [{ key, 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
    }
  }
}
```

## 开发注意事项

### 代码修改指导
- **单文件开发**：所有后端功能都在 `app.py` 中，修改时要注意代码结构清晰
- **数据库模式变更**：修改SQLite表结构需要考虑向后兼容性
- **前端JavaScript**：位于 `static/js/app.js`，使用原生JS，注意浏览器兼容性
- **HTML模板**：使用Jinja2模板引擎，主要文件在 `templates/` 目录

### 核心类和函数位置（app.py）
- `QueryLogCollector`类：日志收集系统（第20-46行）
- `ShardingCalculator`类：分表计算器（第64行开始）
- 数据库连接：`create_cassandra_connection()`
- 查询比对：`execute_query()` 和 `execute_sharding_query()`
- API路由：使用Flask装饰器定义

### 分表功能开发指导
- **时间戳解析（已更新）**：`ShardingCalculator.extract_timestamp_from_key()` 新规则
  - 使用 `re.sub(r'\D', '', key)` 删除所有非数字字符
  - 将提取的数字字符串转换为整数作为时间戳
  - 不再进行时间戳有效性验证，支持任意数字组合
- **分表索引计算**：使用公式 `int(numbers) // interval_seconds % table_count`
- **错误处理**：Key中没有数字字符时会记录到 `failed_keys` 中
- **混合查询**：支持生产环境分表+测试环境单表的组合场景
- **前端状态**：分表模式通过 `toggleShardingMode()` 切换，影响UI和提示文本

### Cassandra连接处理
- 连接包含详细的错误诊断和重试机制
- 使用DCAwareRoundRobinPolicy避免负载均衡警告
- 连接超时设置为10秒
- 失败时提供网络连通性测试
- 支持认证（PlainTextAuthProvider）
- 支持集群配置（cluster_name, datacenter）

### 前端状态管理
- `currentResults`: 存储最新查询结果
- 分页状态：`currentIdenticalPage`, `currentDifferencePage`
- 过滤状态：`filteredIdenticalResults`, `filteredDifferenceResults`
- **日志状态（新增）**：`allQueryLogs` - 存储所有查询日志

### JSON和数组字段处理
- `normalize_json_string()`: 标准化JSON字符串用于比较
- `compare_array_values()`: 数组的顺序无关比较
- `is_json_field()`: 智能检测JSON字段
- 前端提供专门的JSON语法高亮和树形展示

### 错误处理策略
- 后端：分类错误（connection_error, validation_error, query_error, system_error）
- 前端：详细错误展示，包含配置信息、解决建议、连接测试工具
- 提供交互式故障排查指南
- **查询日志（新增）**：所有SQL执行和错误信息都会记录到查询日志中

### 性能考虑
- 大数据集的分页处理
- 原生数据的延迟加载
- JSON格式化的客户端缓存
- 搜索和过滤的防抖处理

### SQLite数据库表结构

**config_groups表**
- id: 主键
- name: 配置组名称（唯一）
- description: 描述
- pro_config: 生产环境配置（JSON）
- test_config: 测试环境配置（JSON）
- query_config: 查询配置（JSON）
- **sharding_config: 分表配置（JSON，新增字段）**
- created_at/updated_at: 时间戳

**query_history表**
- id: 主键
- name: 查询名称
- description: 描述
- pro_config/test_config/query_config: 配置（JSON）
- query_keys: 查询的键值（JSON）
- results_summary: 结果摘要（JSON）
- execution_time: 执行时间
- total_keys/differences_count/identical_count: 统计数据
- created_at: 时间戳