174 lines
5.5 KiB
Markdown
174 lines
5.5 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目架构
|
||
|
||
这是一个基于 Flask 的数据库查询比对工具，用于比较 Cassandra 数据库中生产环境和测试环境的数据差异。
|
||
|
||
### 核心组件架构
|
||
|
||
**后端 (Flask)**
|
||
- `app.py`: 主应用文件，包含所有API端点和数据处理逻辑
|
||
- 数据库连接管理（Cassandra + SQLite）
|
||
- 查询执行和结果比对算法
|
||
- 配置组管理（CRUD操作）
|
||
- JSON字段特殊处理和数组比较逻辑
|
||
- 查询历史记录管理
|
||
- `config_groups.db`: SQLite数据库，存储用户保存的配置组和查询历史
|
||
|
||
**前端 (原生JavaScript + Bootstrap)**
|
||
- `templates/db_compare.html`: 主界面模板，包含配置表单和结果展示
|
||
- `templates/index.html`: 工具集合首页
|
||
- `static/js/app.js`: 核心前端逻辑
|
||
- 配置管理和表单处理
|
||
- 差异结果的分页展示系统
|
||
- 原生数据展示（多种视图模式：格式化、原始、差异对比、树形）
|
||
- 高级错误处理和用户反馈
|
||
|
||
**示例代码**
|
||
- `demo/Query.py`: 独立的Cassandra查询比对脚本示例
|
||
- `demo/twcsQuery.py`: 另一个查询示例
|
||
|
||
### 关键功能模块
|
||
|
||
**数据比对引擎**
|
||
- 支持复杂JSON字段的深度比较
|
||
- 数组字段的顺序无关比较
|
||
- 字段级别的差异统计和分析
|
||
- 数据质量评估和建议生成
|
||
- 支持包含和排除特定字段的比较
|
||
|
||
**用户界面特性**
|
||
- 分页系统（差异记录和相同记录）
|
||
- 实时搜索和过滤
|
||
- 原生数据展示（JSON语法高亮、树形视图）
|
||
- 配置导入导出和管理
|
||
- 详细的错误诊断和故障排查指南
|
||
- 查询历史记录和复用
|
||
|
||
## 开发相关命令
|
||
|
||
### 环境设置
|
||
```bash
|
||
# 安装依赖（仅需要Flask和cassandra-driver）
|
||
pip install -r requirements.txt
|
||
|
||
# 运行应用（默认端口5000）
|
||
python app.py
|
||
|
||
# 自定义端口运行
|
||
# 修改app.py最后一行：app.run(debug=True, port=5001)
|
||
```
|
||
|
||
### 开发模式
|
||
应用默认运行在debug模式，代码修改后自动重启。访问 http://localhost:5000 查看首页，http://localhost:5000/db-compare 使用比对工具。
|
||
|
||
### 依赖项
|
||
- Flask==2.3.3
|
||
- cassandra-driver==3.29.1
|
||
|
||
## API架构说明
|
||
|
||
### 核心API端点
|
||
- `GET /api/default-config`: 获取默认数据库配置
|
||
- `POST /api/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>`: 删除历史记录
|
||
|
||
### 查询比对流程
|
||
1. 前端发送配置和Key值列表到 `/api/query`
|
||
2. 后端创建两个Cassandra连接（生产+测试）
|
||
3. 并行执行查询，获取原始数据
|
||
4. 运行比较算法，生成差异报告
|
||
5. 返回完整结果（差异、统计、原始数据）
|
||
|
||
## 数据结构和配置
|
||
|
||
### 数据库配置结构
|
||
```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
|
||
{
|
||
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 }
|
||
}
|
||
```
|
||
|
||
## 开发注意事项
|
||
|
||
### Cassandra连接处理
|
||
- 连接包含详细的错误诊断和重试机制
|
||
- 使用DCAwareRoundRobinPolicy避免负载均衡警告
|
||
- 连接超时设置为10秒
|
||
- 失败时提供网络连通性测试
|
||
- 支持认证（PlainTextAuthProvider）
|
||
- 支持集群配置（cluster_name, datacenter）
|
||
|
||
### 前端状态管理
|
||
- `currentResults`: 存储最新查询结果
|
||
- 分页状态：`currentIdenticalPage`, `currentDifferencePage`
|
||
- 过滤状态：`filteredIdenticalResults`, `filteredDifferenceResults`
|
||
|
||
### JSON和数组字段处理
|
||
- `normalize_json_string()`: 标准化JSON字符串用于比较
|
||
- `compare_array_values()`: 数组的顺序无关比较
|
||
- `is_json_field()`: 智能检测JSON字段
|
||
- 前端提供专门的JSON语法高亮和树形展示
|
||
|
||
### 错误处理策略
|
||
- 后端：分类错误（connection_error, validation_error, query_error, system_error）
|
||
- 前端：详细错误展示，包含配置信息、解决建议、连接测试工具
|
||
- 提供交互式故障排查指南
|
||
|
||
### 性能考虑
|
||
- 大数据集的分页处理
|
||
- 原生数据的延迟加载
|
||
- JSON格式化的客户端缓存
|
||
- 搜索和过滤的防抖处理
|
||
|
||
### SQLite数据库表结构
|
||
|
||
**config_groups表**
|
||
- id: 主键
|
||
- name: 配置组名称（唯一）
|
||
- description: 描述
|
||
- pro_config: 生产环境配置（JSON）
|
||
- test_config: 测试环境配置（JSON）
|
||
- query_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: 时间戳 |