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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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