# CLAUDE.md

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

## Project Overview

This is a payment gateway system built with Go using the Beego framework. It handles payment processing, order
management, and supplier integration for various payment methods including gift cards and other payment channels.

## Development Commands

### Building and Running

```bash
# Build the application
./build.sh

# Run the application
go run main.go

# Run tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run specific test
go test ./internal/service/supplier/third_party -run TestAppleSupplier
```

### Docker Operations

```bash
# Build Docker image
docker build -f deploy/Dockerfile -t kami-gateway .

# Run with Docker (adjust environment variables as needed)
docker run -p 12309:12309 \
  -e serverName="Development" \
  -e gatewayAddr="http://localhost:12309" \
  -e portalAddr="http://localhost:12310" \
  -e shopAddr="http://localhost:12311" \
  kami-gateway
```

## Architecture Overview

### Core Components

1. **Controllers** (`internal/controllers/`): HTTP request handlers
    - `base_controller.go`: Base controller with common functionality
    - `payfor_controller.go`: Payment processing endpoints

2. **Services** (`internal/service/`): Business logic layer
    - `backend/`: Backend management services
    - `pay_for/`: Payment processing services
    - `supplier/`: Third-party supplier integrations
    - `notify/`: Order notification handling

3. **Models** (`internal/models/`): Data models and database operations
    - `order/`: Order-related models
    - `merchant/`: Merchant management
    - `accounts/`: Account management
    - `system/`: System configuration

4. **Supplier Integration** (`internal/service/supplier/third_party/`):
    - Multiple payment supplier implementations (Apple, Walmart, etc.)
    - Pool-based order processing system
    - Queue-based task management

### Key Dependencies

- **Beego v2**: Web framework
- **OpenTelemetry**: Distributed tracing
- **Redis**: Caching and session management
- **MySQL**: Primary database
- **Prometheus**: Metrics collection

### Configuration

The application uses environment variables for configuration:

- `serverName`: Server identifier
- `gatewayAddr`: Gateway service address
- `portalAddr`: Portal service address
- `shopAddr`: Shop service address
- `proxy*`: Proxy configuration for external requests

### Database Schema

The system uses MySQL with the following main entities:

- Orders and order settlements
- Merchant accounts and configurations
- Agent profit tracking
- Payment channel management

### Testing

The project includes unit tests for critical components:

- Supplier integration tests (`*_test.go` files)
- Utility function tests
- Service layer tests

---

# CLAUDE.md (中文版本)

此文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。

## 项目概述

这是一个使用 Go 和 Beego 框架构建的支付网关系统。它处理支付处理、订单管理和供应商集成，支持各种支付方式包括礼品卡和其他支付渠道。

## 开发命令

### 构建和运行

```bash
# 构建应用程序
./build.sh

# 运行应用程序
go run main.go

# 运行测试
go test ./...

# 运行测试并生成覆盖率报告
go test -cover ./...

# 运行特定测试
go test ./internal/service/supplier/third_party -run TestAppleSupplier
```

### Docker 操作

```bash
# 构建 Docker 镜像
docker build -f deploy/Dockerfile -t kami-gateway .

# 使用 Docker 运行（根据需要调整环境变量）
docker run -p 12309:12309 \
  -e serverName="Development" \
  -e gatewayAddr="http://localhost:12309" \
  -e portalAddr="http://localhost:12310" \
  -e shopAddr="http://localhost:12311" \
  kami-gateway
```

## 架构概述

### 核心组件

1. **控制器** (`internal/controllers/`): HTTP 请求处理器
    - `base_controller.go`: 具有通用功能的基础控制器
    - `payfor_controller.go`: 支付处理端点

2. **服务层** (`internal/service/`): 业务逻辑层
    - `backend/`: 后台管理服务
    - `pay_for/`: 支付处理服务
    - `supplier/`: 第三方供应商集成
    - `notify/`: 订单通知处理

3. **模型** (`internal/models/`): 数据模型和数据库操作
    - `order/`: 订单相关模型
    - `merchant/`: 商户管理
    - `accounts/`: 账户管理
    - `system/`: 系统配置

4. **供应商集成** (`internal/service/supplier/third_party/`):
    - 多个支付供应商实现（Apple、Walmart 等）
    - 基于池的订单处理系统
    - 基于队列的任务管理

### 主要依赖项

- **Beego v2**: Web 框架
- **OpenTelemetry**: 分布式追踪
- **Redis**: 缓存和会话管理
- **MySQL**: 主数据库
- **Prometheus**: 指标收集

### 配置

应用程序使用环境变量进行配置：

- `serverName`: 服务器标识符
- `gatewayAddr`: 网关服务地址
- `portalAddr`: 门户服务地址
- `shopAddr`: 商店服务地址
- `proxy*`: 外部请求的代理配置

### 数据库架构

系统使用 MySQL，包含以下主要实体：

- 订单和订单结算
- 商户账户和配置
- 代理商利润跟踪
- 支付渠道管理

### 测试

项目包含关键组件的单元测试：

- 供应商集成测试（`*_test.go` 文件）
- 工具函数测试
- 服务层测试