# CLAUDE.md

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

## Project Overview

This is `clinic_data_service`, a Go-based TiDB diagnostics and analysis tool that provides:
- **Slow Query Analysis**: Processes TiDB slow query logs from S3, analyzes patterns, and sends reports to Feishu
- **Traffic Mirroring Query Comparison**: Compares query performance between two TiDB clusters (e.g., baseline vs canary)
- **Multi-Cloud Data Proxy**: Unified query interface supporting AWS Athena, GCP BigQuery, AliCloud MaxCompute, and DuckDB
- **Performance Metrics Analysis**: Cluster health checks, TiKV monitoring, and metrics comparison

## Development Commands

### Building
```bash
# Build main CLI application
go build -o pasefile

# Build API server (traffic mirroring)
go build -o clinic-api ./cmd/api
```


### Running Applications
```bash
# Run slow query analysis (default mode)
./pasefile -day=20250701 -task=slowquery

# Run TopSQL analysis
./pasefile -day=20250701 -task=topsql

# Run API server (port 8087)
go run cmd/api/main.go

```

### Testing
```bash
# Run all tests
go test ./...

# Run specific test
go test -v -run TestSlowQueryCheckDaily

# Run cluster comparison test with arguments
go test -v -run TestComparePerformance -timeout=120s -args \
  -prod=1379661944646416054 \
  -prodStart=2025-11-11T13:58:00Z \
  -prodEnd=2025-11-11T23:08:01Z \
  -replay=10255290801445290516 \
  -replayStart=2025-11-23T21:00:00Z \
  -replayEnd=2025-11-24T06:10:01Z

# Run data proxy tests
go test -v ./test/...
```

### Dependencies
```bash
# Install/update dependencies
go mod tidy

# Download dependencies
go mod download
```

## Architecture

### Multi-Engine Query System
The project uses a pluggable query engine architecture:
- **Engine Interface** ([pkg/engine/engine.go](pkg/engine/engine.go)): Defines `QueryEngine` interface with `Execute()`, `Name()`, and `Health()` methods
- **Engine Router** ([pkg/engine_router/router.go](pkg/engine_router/router.go)): Routes queries to appropriate engine based on cloud vendor
- **Supported Engines**:
  - AWS Athena ([pkg/engine/athena.go](pkg/engine/athena.go))
  - GCP BigQuery ([pkg/engine/bigquery.go](pkg/engine/bigquery.go))
  - AliCloud MaxCompute ([pkg/engine/maxcompute.go](pkg/engine/maxcompute.go))
  - DuckDB ([pkg/engine/duckdb.go](pkg/engine/duckdb.go))
- **SQL Dialect Support** ([pkg/dialect/](pkg/dialect/)): Translates between standard SQL and vendor-specific dialects

### Entry Points
1. **CLI Application** ([main.go](main.go)):
   - Downloads S3 log files
   - Processes local slow query logs
   - Analyzes patterns and generates reports
   - Sends Feishu notifications

2. **API Server** ([cmd/api/main.go](cmd/api/main.go)):
   - Port 8087 (configurable via `API_ADDR` env var)
   - Traffic mirroring query comparison endpoints
   - OpenTelemetry tracing enabled



### Core Services
- **DataProxyService** ([pkg/service/dataproxy_service.go](pkg/service/dataproxy_service.go)): Core query execution service with engine routing
- **SlowQueryAnalyzer** ([pkg/service/slowquery_analyzer.go](pkg/service/slowquery_analyzer.go)): Analyzes slow query patterns from data engines
- **ClusterDiffService** ([pkg/service/cluster_diff_svc.go](pkg/service/cluster_diff_svc.go), [pkg/service/cluster_diff_api.go](pkg/service/cluster_diff_api.go)): Compares performance metrics between clusters

### Data Flow
1. **S3 → SQLite → Analysis → Feishu** (slow query analysis):
   - S3 logs downloaded ([pkg/s3/](pkg/s3/))
   - Parsed into SQLite ([pkg/parser/](pkg/parser/), [pkg/dao/](pkg/dao/))
   - Queried and analyzed ([pkg/query/query.go](pkg/query/query.go))
   - Results pushed to Feishu ([pkg/thirdapi/feishu/](pkg/thirdapi/feishu/))

2. **API Request → Engine Router → Cloud Engine → Response** (data proxy):
   - Request received ([pkg/handlers/dataproxy_handler.go](pkg/handlers/dataproxy_handler.go))
   - Routed to appropriate engine ([pkg/engine_router/router.go](pkg/engine_router/router.go))
   - Query executed on cloud platform
   - Results formatted and returned

### Configuration System
- **Main Config** ([pkg/config/config.go](pkg/config/config.go)): Application settings, S3, Feishu credentials
- **DataProxy Config** ([pkg/config/dataproxy_config.go](pkg/config/dataproxy_config.go)): Multi-cloud engine configurations
- **Metrics Config** ([pkg/config/metrics/](pkg/config/metrics/)): Prometheus metrics and query definitions
- **Cluster Config** (`configs/cluster.yaml`): Organization and cluster metadata

Configuration files in `configs/`:
- `config-dev.yaml`: Development environment
- `config-prod.yaml`: Production environment
- `config-dataproxy.yaml`: Cloud vendor engine settings
- `config-metrics.yaml`: Metrics query templates
- `cluster.yaml`: Cluster and organization definitions

## Key Patterns

### Testing Patterns
- Tests are at package root level (e.g., `slow_query_test.go`, `cluster_compare_test.go`)
- Tests use `flag` package for command-line arguments
- Integration tests in `test/` directory
- Tests require initialization: `Init()` loads config and sets up logging

### Logging
- Custom logging package at [pkg/log/](pkg/log/)
- Context-based tracing with `log.StartTrace()` and `log.EndTrace()`
- Zap logger integration
- Log files written to configured `LogDir`

### Error Handling
- Custom error types in [pkg/errors/](pkg/errors/)
- API errors ([pkg/errors/api_error.go](pkg/errors/api_error.go))
- DataProxy errors ([pkg/errors/dataproxy_error.go](pkg/errors/dataproxy_error.go))

### Database Access
- SQLite for local slow query storage with GORM ([pkg/dao/sqllite_crud.go](pkg/dao/sqllite_crud.go), [pkg/dao/sqlLite_inti.go](pkg/dao/sqlLite_inti.go))
- MySQL for aggregated statistics with GORM ([pkg/dao/mysql_crud.go](pkg/dao/mysql_crud.go), [pkg/dao/mysql_init.go](pkg/dao/mysql_init.go))
- Models defined in [pkg/model/](pkg/model/)

## Third-Party Integrations

### Feishu (Lark)
- SDK: `github.com/larksuite/oapi-sdk-go/v3`
- Send card messages and create document blocks
- Configured via `feishu` section in config YAML

### AWS Services
- S3: `github.com/aws/aws-sdk-go`
- Athena: `github.com/aws/aws-sdk-go-v2/service/athena`
- STS for role assumption

### Prometheus
- Client: `github.com/prometheus/client_golang`
- Query API interactions in [pkg/prometheus/](pkg/prometheus/)

### GCP
- BigQuery: `cloud.google.com/go/bigquery`

## Common Tasks

### Adding a New Query Engine
1. Implement `QueryEngine` interface in `pkg/engine/`
2. Add configuration struct to [pkg/config/dataproxy_config.go](pkg/config/dataproxy_config.go)
3. Register engine in [pkg/engine_router/router.go](pkg/engine_router/router.go) `NewRouter()`
4. Add dialect support if SQL syntax differs

### Adding New Slow Query Pattern
1. Define pattern detection logic in slow query analysis
2. Add pattern to query templates in [pkg/query/query.go](pkg/query/query.go)
3. Update Feishu report formatting

### Adding New API Endpoint
1. Define handler in [pkg/handlers/](pkg/handlers/)
2. Register route in [pkg/server/router.go](pkg/server/router.go) `NewRouter()`
3. Add corresponding service method if needed

## Important Notes

- This codebase uses Chinese comments extensively alongside English
- Configuration is environment-specific; always use appropriate config file
- S3 credentials and Feishu tokens are sensitive; never commit to git
- The project uses Go 1.24.0 features
- Some engine implementations (like DuckDB) may be incomplete placeholders
- AWS role assumption is used for cross-account access
- Tests may require AWS credentials and S3 access to run successfully