# Project Context

## Purpose

A comprehensive card redemption platform (卡密兑换平台) that manages various types of gift cards and payment processing,
including Apple, T-Mall, JD, Walmart, and C-Trip cards. The platform handles order processing, merchant management, user
authentication, and integration with multiple external payment providers.

## Tech Stack

- **Framework**: GoFrame v2 with heavy code generation usage
- **Language**: Go 1.21+
- **Database**: MySQL with dual database setup (kami_v2 primary, kami legacy)
- **Cache**: Redis for caching, sessions, rate limiting
- **Authentication**: JWT with TOTP support, multi-login capability
- **Authorization**: Casbin RBAC
- **Tracing**: OpenTelemetry with custom headers (x-service-token)
- **Task Scheduling**: Cron jobs with graceful shutdown
- **Container**: Docker with Kubernetes deployment
- **API**: RESTful APIs with OpenTelemetry instrumentation

## Project Conventions

### Code Style

- Go standard formatting (`gofmt`)
- Verb-led naming for change IDs (add-, update-, remove-, refactor-)
- Kebab-case for file and directory names
- Domain separation with clear business boundaries

### Architecture Patterns

- **DAO/DO/Entity pattern**: GoFrame ORM with generated data access layers
- **API-First**: Controllers generated from api/ definitions
- **Domain-Driven Design**: Each business domain has its own logic folder
- **Dual Database**: Separate connections for primary and legacy data
- **Graceful Shutdown**: Implemented for cron jobs and connection pools
- **Code Generation Workflow**: Database changes → make dao → make service → make ctrl

### Testing Strategy

- Focused test coverage in critical business logic areas
- Unit tests for domain logic in `internal/logic/*/`
- Integration tests for external platform integrations
- Test command: `go test ./...` with verbose mode for specific packages
- Critical areas: Apple account management, T-Mall order processing, rate limiting

### Git Workflow

- **Main branch**: `develop` (primary development branch)
- **Feature branches**: Created from develop for new features
- **Commit format**: Conventional commits with type(scope): description
- **Code generation**: Automated through Makefile targets
- **Deployment**: Docker-based with auto-generated git-based tags

## Domain Context

### Business Domains

- **Card Platform Management**: Apple, T-Mall, JD, Walmart, C-Trip, and generic redemption cards
- **Order Processing**: Complete lifecycle with callbacks, status tracking, summaries
- **Merchant Management**: Configurations, deployments, hidden settings, steal rules
- **Channel & Road Management**: Business routing with road pools and entrance management
- **User Management**: Authentication, roles, authorization
- **Payment Processing**: Payment methods, deductions, statistics
- **JDCookie Management**: Cookie rotation, order processing, account management

### Key Concepts

- **Steal Rules**: Automated card acquisition logic
- **Road Pools**: Business routing management
- **Cookie Rotation**: JD account management strategy
- **Order Callbacks**: Asynchronous payment status notifications
- **Rate Limiting**: Redis-based access control

## Important Constraints

- **Security**: Built-in rate limiting, IP/device restrictions, authentication middleware
- **Performance**: Optimized for high-volume card redemption operations
- **Scalability**: Designed for multi-tenant architecture with merchant isolation
- **Compliance**: Payment processing industry standards
- **Reliability**: Graceful shutdown, error handling, monitoring integration

## External Dependencies

- **T-Mall**: OAuth gateway integration with eco.taobao.com
- **JD**: JD API integration with cookie management
- **Walmart**: Walmart API integration
- **C-Trip**: Travel platform API integration
- **Agiso**: App authentication service
- **Redis**: Caching, sessions, rate limiting
- **MySQL**: Primary and legacy data storage
- **OpenTelemetry**: Distributed tracing and monitoring
