# Directory Structure

## Top-Level Layout

```
bindbox_game/
├── main.go                    # Application entry point
├── go.mod / go.sum            # Go module definition
├── Makefile                   # Build, test, lint, format commands
├── Dockerfile                 # Docker build config
├── CLAUDE.md                  # AI assistant guidance
│
├── configs/                   # Environment-specific TOML config files
│   ├── dev_configs.toml
│   ├── fat_configs.toml
│   ├── uat_configs.toml
│   ├── pro_configs.toml
│   └── cert/                  # SSL/payment certificates
│
├── internal/                  # Core application code (Go convention)
│   ├── api/                   # HTTP handlers (organized by domain)
│   ├── service/               # Business logic layer
│   ├── repository/mysql/      # Data access layer (GORM)
│   ├── router/                # HTTP routing and middleware
│   ├── pkg/                   # Shared internal packages
│   ├── code/                  # Error code definitions
│   ├── alert/                 # Alert notification system
│   ├── metrics/               # Prometheus metrics
│   ├── proposal/              # Shared types/interfaces
│   └── dblogger/              # Database query logger
│
├── cmd/                       # CLI tools and debug utilities
│   ├── gormgen/               # GORM model code generator
│   ├── mfmt/                  # Import formatter
│   ├── douyin_sync_debug/     # Douyin sync debugging
│   ├── check_order/           # Order checking tool
│   └── ...                    # Various debug/diagnostic tools
│
├── web/admin/                 # Vue 3 admin panel (separate git repo)
│   ├── src/                   # Vue source code
│   ├── dist/                  # Production build output
│   └── package.json           # Frontend dependencies
│
├── migrations/                # SQL migration files (date-prefixed)
├── resources/admin/           # Embedded admin panel assets
├── build/                     # Build output directory
├── deploy/                    # Deployment configurations
├── docs/                      # Documentation
├── logs/                      # Application log files
├── scripts/                   # Utility scripts
└── tools/                     # Standalone analysis/debug tools
```

## Key Locations

### API Handlers (`internal/api/`)

```
api/
├── admin/                     # Admin panel endpoints (~30+ files)
│   ├── activities_admin.go    # Activity CRUD
│   ├── dashboard_*.go         # Dashboard analytics (multiple files)
│   ├── users_admin.go         # User management
│   ├── douyin_orders_admin.go # Douyin order management
│   ├── livestream_admin.go    # Livestream management
│   └── ...
├── activity/                  # Lottery/game activity endpoints
│   ├── lottery_app.go         # Lottery join/draw
│   ├── matching_game_app.go   # Matching game logic
│   └── ...
├── app/                       # Store/product endpoints
│   ├── store.go               # Store items
│   ├── product.go             # Products
│   └── coupon_transfer.go     # Coupon transfers
├── game/                      # Game (minesweeper) endpoints
├── pay/                       # Payment endpoints
├── user/                      # User management endpoints
├── task_center/               # Task center endpoints
├── common/                    # Shared handlers (upload)
├── public/                    # Public livestream endpoints
└── internal/                  # Internal service endpoints
```

### Service Layer (`internal/service/`)

```
service/
├── activity/                  # Activity business logic
│   ├── activity.go            # Service struct and constructor
│   ├── lottery_process.go     # Core lottery algorithm
│   ├── matching_game.go       # Matching game logic
│   ├── scheduler.go           # Settlement scheduler
│   └── strategy/              # Draw strategy pattern
│       ├── strategy.go        # Interface definition
│       ├── default.go         # Standard lottery
│       └── ichiban.go         # Ichiban-style lottery
├── admin/                     # Admin user management
├── user/                      # User business logic (largest service)
├── order/                     # Order processing
├── game/                      # Game ticket management
├── douyin/                    # Douyin integration
│   ├── order_sync.go          # Order synchronization
│   ├── reward_dispatcher.go   # Reward granting
│   └── scheduler.go           # Sync scheduler
├── task_center/               # Task center (worker pattern)
├── finance/                   # Financial/ledger operations
├── product/                   # Product management
├── channel/                   # Marketing channels
├── title/                     # User titles/badges
└── ...
```

### Shared Packages (`internal/pkg/`)

```
pkg/
├── core/          # Custom Gin context wrapper (core.Context, core.Mux)
├── logger/        # Zap-based logger with file rotation
├── redis/         # Redis client initialization
├── jwtoken/       # JWT generation and parsing
├── otel/          # OpenTelemetry integration
├── wechat/        # WeChat Mini Program helpers
├── miniprogram/   # WeChat access token, subscribe messages
├── pay/           # WeChat Pay v3 integration
├── douyin/        # Douyin API client
├── sms/           # Aliyun SMS client
├── validation/    # Input validation
├── httpclient/    # HTTP client wrapper
├── idgen/         # ID generation
├── timeutil/      # Time utility (CST layout)
├── errors/        # Error types
├── points/        # Points calculation utilities
├── notify/        # Notification helpers
├── async/         # Async task utilities
├── cryptoaes/     # AES encryption
├── cryptorsa/     # RSA encryption
├── env/           # Environment detection
├── color/         # Console color output
├── debug/         # Debug utilities
├── cors/          # CORS configuration
├── shutdown/      # Graceful shutdown
├── startup/       # Startup utilities
├── trace/         # Trace utilities
├── util/          # General utilities
├── utils/         # Additional utilities
└── jsonutil/      # JSON helpers
```

## Naming Conventions

### Files
- `*_app.go` — App (mini program) facing handler
- `*_admin.go` — Admin panel handler
- `*_test.go` — Test files (alongside source)
- `*.gen.go` — Generated code (do not edit)
- `*_helper.go` — Helper functions for a domain

### Packages
- Service constructors: `New(logger, db)` returns service struct
- Handler constructors: `New(logger, db, ...)` returns handler struct
- Method naming: `Create*`, `Modify*`, `Delete*`, `List*`, `Get*`

### Database
- Migration files: `YYYYMMDD_description.sql` (e.g., `20260207_add_column.sql`)
- Model files: `internal/repository/mysql/model/*.gen.go`
- DAO files: `internal/repository/mysql/dao/*.gen.go`

### Configuration
- Environment-specific: `{env}_configs.toml`
- Environments: `dev`, `fat`, `uat`, `pro`

## Important Notes

- `web/admin/` is a **separate git repository** (has its own `.git`)
- Generated files in `model/` and `dao/` should never be manually edited
- The `tools/` directory contains standalone Go programs for debugging and analysis
- `cmd/` contains both production tools (gormgen, mfmt) and debug utilities

---
*Generated: 2026-03-21*