kami_backend/docs/CLAUDE.md

OpenSpec Instructions

These instructions are for AI assistants working in this project.

Always open @/openspec/AGENTS.md when the request:

• Mentions planning or proposals (words like proposal, spec, change, plan)
• Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
• Sounds ambiguous and you need the authoritative spec before coding

Use @/openspec/AGENTS.md to learn:

• How to create and apply change proposals
• Spec format and conventions
• Project structure and guidelines

Keep this managed block so 'openspec update' can refresh the instructions.

CLAUDE.md

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

Development Commands

This project uses GoFrame (GF) framework and includes a custom Makefile that delegates to hack/hack.mk:

Building and Running

• make build - Build binary using GoFrame CLI (gf build -ew)
• go run main.go - Run the application directly
• make up - Update GoFrame and CLI to latest version (gf up -a)

Code Quality & Linting

• go fmt ./... - Format all Go files
• go vet ./... - Run Go vet for potential issues
• go mod tidy - Clean up module dependencies

Code Generation (GoFrame CLI)

• make ctrl - Generate controllers from API definitions (gf gen ctrl)
• make dao - Generate DAO/DO/Entity files from database schema (gf gen dao)
• make service - Generate service interfaces (gf gen service)
• make enums - Generate enum files from Go code (gf gen enums)
• make pb - Generate protobuf files (gf gen pb)
• make pbentity - Generate protobuf files for database tables (gf gen pbentity)

Important: After database schema changes, run code generation in order: make dao → make service → make ctrl

Testing

• go test ./... - Run all tests
• go test -v ./internal/logic/... - Run tests for specific packages
• go test ./internal/logic/card_apple_account -v - Run tests for specific module
• go test -run TestName - Run specific test
• go test -race ./... - Run tests with race detection
• go test -cover ./... - Run tests with coverage report

Docker & Deployment

• make image - Build Docker image with auto-generated git-based tag
• make image.push - Build and push Docker image
• make deploy - Deploy to kubernetes environment using kustomize
• Environment Variables: Set serverName env var for service identification in OpenTelemetry
• Deployment Config: Uses manifest/deploy/kustomize/overlays/${_ENV} for environment-specific configs

Configuration Files:

• hack/config.yaml: Code generation configuration with database connections and paths
• manifest/config/config.yaml: Application runtime configuration

Architecture Overview

This is a Go-based backend service for a card redemption platform (卡密兑换平台) using the GoFrame framework:

Application Entry & Flow

• main.go: Entry point with OpenTelemetry initialization, sets service name from serverName env var, starts cmd.Main
• internal/cmd/cmd.go: HTTP server setup, binds controllers under /api with middleware stack, registers monitoring and cron tasks

Database Architecture (Dual Database Setup)

The system uses two MySQL databases configured in manifest/config/config.yaml:

• default (kami_v2): Primary database
• v1 (kami): Legacy database with v1 prefix for generated models

Code generation configuration in hack/config.yaml defines separate DAO generation for each database with appropriate prefixes. Current generation uses the kami database with v1 prefix for backward compatibility.

Business Domain Structure

Card Platform Management:

• Apple cards (card_apple_*): Account management, order processing, steal rules
• T-Mall cards (card_t_mall_*): Account management, order processing, shop management
• JD cards (card_jd_*, card_original_jd_*): JD card variants
• Walmart cards (card_walmart_*): Walmart card management
• C-Trip cards (card_c_trip_*): Travel card management
• Redeem cards (card_redeem_*): Generic redemption system

Core Business Systems:

• 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 (JWT + TOTP), roles, Casbin authorization
• Payment Processing: Payment methods, deductions, statistics
• Restriction Management: IP/device tracking for access control
• JDCookie Management: Cookie rotation, order processing, account management

Technology Stack Details

• Framework: GoFrame v2 with heavy code generation usage
• Language: Go 1.24+ (see go.mod)
• Database: MySQL with GoFrame ORM (DAO/DO/Entity pattern), dual database support
• Cache: Redis for caching, sessions, rate limiting
• Tracing: OpenTelemetry with custom headers (x-service-token)
• Monitoring: Built-in metrics, health checks, monitor tasks
• Task Scheduling: Cron jobs with graceful shutdown
• Authentication: JWT with TOTP support, multi-login capability
• Authorization: Casbin RBAC with model/policy files
• Rate Limiting: Redis-based with configurable rules

External Integrations

All external platform integrations are abstracted in utility/integration/:

• 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

Configuration System

• Primary Config: manifest/config/config.yaml
• Code Gen Config: hack/config.yaml (database connections, generation paths)
• Environment Support: serverName variable for service identification
• Secret Management: Encryption keys for frontend/backend, token configuration

Critical Development Patterns

• Code Generation Workflow: Database changes → make dao → make service → make ctrl
• API-First: Controllers generated from api/ definitions in /api folder
• Domain Separation: Each business domain has its own logic folder with clear boundaries
• Middleware Stack: CORS, response handling, error handling, gzip, and context management
• Graceful Shutdown: Implemented for cron jobs and connection pools in cmd.go:83-92
• Security: Built-in rate limiting, IP/device restrictions, authentication middleware

Testing Strategy

Focused test coverage in critical business logic areas:

• Apple account management (internal/logic/card_apple_account/)
• T-Mall order processing (internal/logic/card_t_mall_order/)
• Rate limiting (internal/logic/limiter/)
• Business logic validation with comprehensive test coverage