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

# Technology Stack

**Analysis Date:** 2026-03-21

## Languages

**Primary:**
- Go 1.24.0 - Backend server, all business logic, API handlers
- TypeScript ~5.6.3 - Frontend admin panel (`web/admin/src/`)

**Secondary:**
- SQL - Database migrations (`migrations/` directory)
- TOML - Configuration files (`configs/*.toml`)
- SCSS - Frontend styles (`web/admin/src/assets/styles/`)

## Runtime

**Backend:**
- Go runtime 1.24.0 (toolchain go1.24.2)
- Docker: `golang:1.24-alpine` build stage, `alpine:latest` final stage

**Frontend:**
- Node.js >= 18.0.0

**Package Manager:**
- Go modules (`go.mod` / `go.sum`) - lockfile present
- pnpm >= 8.8.0 - frontend (`web/admin/pnpm-lock.yaml`) - lockfile present

## Frameworks

**Backend Core:**
- `github.com/gin-gonic/gin v1.9.1` - HTTP web framework
- `gorm.io/gorm v1.25.9` - ORM for MySQL
- `gorm.io/gen v0.3.26` - GORM code generation from schema
- `gorm.io/plugin/dbresolver v1.5.0` - Read/write split support

**Frontend Core:**
- Vue 3 `^3.5.21` - UI framework (`web/admin/src/`)
- Vite `^5.4.10` - Build tool and dev server
- Element Plus `^2.11.2` - UI component library
- Pinia `^3.0.3` - State management
- Vue Router `^4.5.1` - Client-side routing
- Tailwind CSS `^4.1.14` - Utility-first CSS

**Testing (Backend):**
- `github.com/stretchr/testify v1.11.1` - Assertions
- `github.com/DATA-DOG/go-sqlmock v1.5.2` - MySQL mock
- `github.com/alicebob/miniredis/v2 v2.36.1` - In-memory Redis for tests
- `gorm.io/driver/sqlite v1.4.3` - SQLite for in-memory test DB (`internal/repository/mysql/testrepo_sqlite.go`)

**Testing (Frontend):**
- Vitest `^1.0.0` - Unit test runner
- `@vue/test-utils ^2.4.0` - Vue component testing

**Build/Dev (Backend):**
- Makefile - Task runner (`Makefile`)
- `golangci-lint` - Linter (install via `make tools`)
- `go-swagger` - Swagger generation (install via `make tools`)
- `cmd/mfmt/main.go` - Custom import formatter (groups: stdlib, local, third-party)
- `cmd/gormgen/main.go` - GORM model/DAO code generator

**Build/Dev (Frontend):**
- ESLint `^9.9.1` + TypeScript ESLint `^8.3.0` - Linting
- Prettier `^3.5.3` - Code formatting
- Stylelint `^16.20.0` - CSS/SCSS linting
- Husky `^9.1.5` + lint-staged - Pre-commit hooks
- Terser `^5.36.0` - Minification
- `vite-plugin-compression ^0.5.1` - Gzip compression for production

## Key Dependencies

**Critical (Backend):**
- `github.com/spf13/viper v1.17.0` - Configuration management (TOML, env var overrides)
- `go.uber.org/zap v1.26.0` - Structured logging
- `gopkg.in/natefinch/lumberjack.v2 v2.2.1` - Log file rotation
- `github.com/golang-jwt/jwt/v5 v5.2.0` - JWT auth tokens
- `github.com/redis/go-redis/v9 v9.17.2` - Redis client (singleton)
- `github.com/go-sql-driver/mysql v1.7.1` - MySQL driver
- `github.com/bytedance/sonic v1.13.2` - High-performance JSON encoder/decoder
- `github.com/bwmarrin/snowflake v0.3.0` - Distributed ID generation
- `github.com/go-resty/resty/v2 v2.10.0` - HTTP client for external API calls
- `github.com/prometheus/client_golang v1.17.0` - Prometheus metrics
- `golang.org/x/crypto v0.44.0` - Cryptographic utilities

**Critical (Frontend):**
- Axios `^1.12.2` - HTTP client for API calls
- Echarts `^6.0.0` - Charts and data visualization
- `@vueuse/core ^13.9.0` - Vue composition utilities
- `pinia-plugin-persistedstate ^4.3.0` - Persistent state storage
- `dayjs ^1.11.19` - Date/time manipulation
- `crypto-js ^4.2.0` - Client-side cryptography
- `xlsx ^0.18.5` - Excel file generation/parsing
- `@wangeditor/editor ^5.1.23` - Rich text editor

**Infrastructure (Backend):**
- `go.opentelemetry.io/otel v1.39.0` - Distributed tracing (OTLP HTTP exporter)
- `github.com/gin-contrib/pprof v1.4.0` - Go profiling endpoint
- `github.com/swaggo/gin-swagger v1.6.0` - Swagger UI embedded in Gin
- `github.com/tealeg/xlsx v1.0.5` - Excel file generation (server-side)
- `github.com/rs/cors/wrapper/gin v0.0.0-20231013084403-73f81b45a644` - CORS middleware

## Configuration

**Backend Environment:**
- Set via `ENV` environment variable: `dev` | `fat` | `uat` | `pro` (default: `fat`)
- Config files embedded into binary at build time via `//go:embed` directives
- Config files: `configs/dev_configs.toml`, `configs/fat_configs.toml`, `configs/uat_configs.toml`, `configs/pro_configs.toml`
- TOML format parsed via Viper (`github.com/spf13/viper`)

**Environment Variable Overrides (at runtime):**
- `MYSQL_ADDR`, `MYSQL_READ_ADDR`, `MYSQL_WRITE_ADDR`, `MYSQL_USER`, `MYSQL_PASS`, `MYSQL_NAME`
- `REDIS_ADDR`, `REDIS_PASS`
- `WECHAT_MCHID`, `WECHAT_SERIAL_NO`, `WECHAT_PRIVATE_KEY_PATH`, `WECHAT_API_V3_KEY`, `WECHAT_NOTIFY_URL`, `WECHAT_PUBLIC_KEY_ID`, `WECHAT_PUBLIC_KEY_PATH`
- `ALIYUN_SMS_ACCESS_KEY_ID`, `ALIYUN_SMS_ACCESS_KEY_SECRET`, `ALIYUN_SMS_SIGN_NAME`, `ALIYUN_SMS_TEMPLATE_CODE`
- `ADMIN_JWT_SECRET` - Admin JWT signing secret override

**Frontend Environment:**
- Vite env vars: `VITE_VERSION`, `VITE_PORT`, `VITE_BASE_URL`, `VITE_API_URL`, `VITE_API_PROXY_URL`
- Dev proxy: `/api` requests forwarded to `VITE_API_PROXY_URL`

**Build:**
- Backend: `Dockerfile` (multi-stage, `golang:1.24-alpine` → `alpine:latest`)
- Server port: `9991` (constant in `configs/constants.go`)
- Container exposes port `9991`

## Platform Requirements

**Development:**
- Go 1.24+
- Node.js >= 18.0.0, pnpm >= 8.8.0
- MySQL instance (read/write addresses)
- Redis instance
- `golangci-lint` and `go-swagger` for linting/docs

**Production:**
- Docker (Linux/amd64 binary, CGO_ENABLED=0)
- Alpine Linux container
- MySQL with optional read replica (master-slave)
- Redis single-node
- Optional: OpenTelemetry-compatible collector (Tempo) at configured OTLP endpoint

---

*Stack analysis: 2026-03-21*