# CLAUDE.md

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

## Development Commands

### Build and Run
```bash
# Build for production (Linux AMD64)
./build.sh

# Development mode
go run main.go

# Docker build
docker build -t kami_shop . -f deploy/Dockerfile
```

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

# Run specific test file
go test ./internal/service/scan_shop_test.go

# Run tests with verbose output
go test -v ./...
```

### Docker Deployment
```bash
# Build and deploy with Docker Compose
export VERSION=latest
docker-compose -f deploy/docker-compose.yaml up -d
```

## Project Architecture

This is a **payment processing platform** built with Go and Beego framework, supporting multiple payment methods including WeChat Pay, Alipay, JD.com, Taobao, Pinduoduo, Apple Pay, Walmart, and various gift cards.

### Key Components

**Application Structure**:
- `main.go` - Application entry point with OpenTelemetry initialization
- `internal/controllers/` - HTTP handlers for payment processing
- `internal/service/` - Business logic layer
- `internal/models/` - Data models and database operations
- `internal/routers/` - Route definitions
- `views/` - HTML templates for payment pages (30+ payment method templates)
- `conf/` - Configuration files (app.conf for production, app.local.conf for development)

**External Dependencies**:
- **Database**: MySQL (development: `juhe_pay`, production: `kami`)
- **Cache**: Redis for session management and caching
- **Gateway Service**: `http://localhost:12309` (development) / `http://127.0.0.1:12309` (production)
- **Partial Service**: `http://localhost:12310` (development) / `http://127.0.0.1:12310` (production)

### Configuration

**Development** (`conf/app.local.conf`):
- Port: 12305, Host: localhost
- Database: MySQL on localhost:3306
- Redis: localhost:6379
- Run mode: dev

**Production** (`conf/app.conf`):
- Port: 12305, Host: 0.0.0.0
- Database: MySQL on 127.0.0.1:3306
- Redis: redis:6379 (Docker service)
- Run mode: prod

### Technology Stack

- **Framework**: Beego v2.3.7
- **Language**: Go 1.23.0
- **Observability**: Complete OpenTelemetry stack (tracing, metrics, logging)
- **Logging**: Zap structured logging
- **Concurrency**: Goroutine pooling with ants/v2
- **Security**: AES encryption, Edwards25519 cryptographic operations

### Development Patterns

**Code Organization**:
- Controllers handle HTTP requests and validation
- Service layer implements business logic
- Models manage data persistence
- Utils provide common functionality
- Schema defines request/response structures

**Testing Strategy**:
- Unit tests focused on service layer
- Test files follow `*_test.go` naming convention
- Use standard Go testing package

### Payment Processing Flow

1. Order creation through controller endpoints
2. Service layer processes payment logic
3. Integration with external payment gateways
4. Notification handling for payment callbacks
5. Template-based payment page generation
6. Profit margin calculation and reporting

### Deployment

**Docker Environment**:
- Multi-stage build using golang:1.23 builder
- Alpine Linux runtime image
- Volume mounts for configuration and logs
- Network: 1panel-network
- Health checks and automatic restarts

**CI/CD**:
- Drone CI pipeline with SSH deployment
- Docker image registry push
- Production server deployment via Docker Compose