kami_shop/CLAUDE.md

CLAUDE.md

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

Development Commands

Build and Run

# Build for production (Linux AMD64)
./build.sh

# Development mode
go run main.go

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

Testing

# 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

# 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