修改模版内容

2025-08-12 16:27:21 +08:00
parent cdf7e36ba3
commit 8d7c4e3730
1 changed files with 0 additions and 394 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,394 +0,0 @@
-# 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数据库)
-```
-
-### 开发最佳实践
- **错误处理**：每个模块都有详细的错误分类和处理机制
- **日志记录**：使用统一的日志系统，支持不同级别的日志输出
- **性能监控**：查询时间和连接时间的详细统计
- **配置管理**：支持配置的导入导出和版本管理
- **数据安全**：敏感信息（密码）的安全处理