zfc/bindbox-game
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
bindbox-game/.planning/codebase/STACK.md
win 5ede909be4 docs: map existing codebase
2026-03-21 16:01:32 +08:00

5.5 KiB
Raw Permalink Blame History

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