bindbox-game/.planning/codebase/STRUCTURE.md

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