kami_boss/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 Go-based web application called jhboss (Kami Boss) - a merchant management and payment gateway system built with the Beego framework. The application handles various aspects of payment processing, merchant management, agent operations, and financial transactions.

Development Commands

Building and Running

# Run the application (development mode)
go run main.go

# Build the application
go build -o boss main.go

# Install dependencies
go mod tidy

# Download dependencies
go mod download

Testing

# Run all tests
go test ./...

# Run tests in specific package
go test ./internal/utils/mfa/

# Run tests with verbose output
go test -v ./...

Development Tools

# Format code
go fmt ./...

# Run linter (if golangci-lint is installed)
golangci-lint run

# Vet code for potential issues
go vet ./...

Architecture

Framework and Structure

• Framework: Beego v2.3.8 (Go web framework)
• Database: MySQL with ORM (Beego ORM)
• Cache/Sessions: Redis (optional, configured in app.conf)
• Architecture Pattern: MVC (Model-View-Controller)

Directory Structure

├── main.go                    # Application entry point
├── internal/
│   ├── config/               # Configuration management
│   ├── controllers/          # HTTP request handlers
│   ├── models/              # Database models and ORM setup
│   ├── routers/             # Route definitions
│   ├── service/             # Business logic layer
│   ├── utils/               # Utility functions and helpers
│   ├── common/              # Common constants and types
│   └── datas/               # Data access layer
├── conf/                    # Configuration files
├── static/                  # Static assets (CSS, JS, images)
├── views/                   # Template files
└── logs/                    # Application logs

Key Components

Controllers (internal/controllers/)

• baseController: Common base functionality for all controllers
• loginController: Authentication and session management
• getController: Data retrieval operations
• addController: Data creation operations
• updateController: Data modification operations
• deleteController: Data deletion operations
• camelController: Camel payment platform integration
• pageController: Page rendering and navigation

Models (internal/models/)

Organized by domain:

• accounts/: Account management and history
• agent/: Agent information and profit tracking
• merchant/: Merchant deployment and load information
• order/: Order processing, profit, and settlement
• payfor/: Payment processing
• road/: Payment channel management
• system/: System configuration (users, roles, menus, permissions)
• notify/: Notification handling
• user/: User management

Services (internal/service/)

• queryService: Data query operations
• updateService: Data update operations
• addService: Data creation operations
• deleteService: Data deletion operations
• sendNotifyMerchantService: Merchant notification services
• token.go: Token management
• summary.go: Data aggregation and reporting

Configuration

• Main Config: conf/app.conf - Contains database, Redis, gateway, and application settings
• Environment Variables: Uses gatewayAddr and portalAddr environment variables
• Dynamic Config: AES encryption parameters fetched from kami_backend:12401

Database Setup

The application uses MySQL with the following connection details configured in conf/app.conf:

• Host: 127.0.0.1:3306
• Database: kami
• The ORM models are auto-registered in internal/models/init.go

External Integrations

• Gateway Service: kami_gateway:12309 - Payment gateway integration
• Portal Service: 127.0.0.1:12400 - User portal integration
• Backend Service: kami_backend:12401 - Backend API for configuration

Deployment

Docker Development

# Build and run with Docker Compose
docker-compose -f deploy/docker-compose-local.yaml up -d --build

# Production deployment
docker-compose -f deploy/docker-compose.yaml up -d --build

Docker Configuration

• Multi-stage build with Go 1.24 builder and Alpine Linux runtime
• Support for Chinese proxy configuration (USE_PROXY=1)
• Automatic SSL certificate installation for external services
• Wait-for-it script ensures MySQL is available before startup
• Application runs on port 12306

Jenkins CI/CD

• Automated pipeline in Jenkinsfile for building and deploying
• Supports container orchestration and restart functionality
• Build failures don't block subsequent stages

Key Features

• Merchant management and deployment
• Payment channel (road) management
• Order processing and profit tracking
• Agent management and commission tracking
• User authentication with MFA (TOTP)
• Role-based access control
• Financial reporting and data export
• Real-time notifications

Development Notes

• Application runs on port 12306 by default
• Logs are written to ./logs/app.log with daily rotation
• Session timeout is set to 24 hours
• Debug mode is enabled in development
• The codebase includes Chinese comments and variable names