kami_gateway/CLAUDE.md

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

# 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

# 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 框架构建的支付网关系统。它处理支付处理、订单管理和供应商集成，支持各种支付方式包括礼品卡和其他支付渠道。

开发命令

构建和运行

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

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

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

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

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

Docker 操作

# 构建 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 文件）
• 工具函数测试
• 服务层测试