# 平台搭建设计方案

## 一、技术选型确认

### 后端技术栈
- **语言**：Go 1.21+ LTS
- **Web框架**：Gin
- **ORM**：GORM
- **数据库**：MySQL 8.0
- **配置管理**：Viper
- **日志**：Zap
- **JWT**：golang-jwt/jwt
- **参数验证**：go-playground/validator
- **实时通信**：HTTP长轮询（暂不用WebSocket）

### 前端技术栈
- **框架**：Vue 3.4+
- **构建工具**：Vite
- **状态管理**：Pinia
- **HTTP客户端**：Axios
- **管理后台UI**：Element Plus
- **移动端UI**：Vant
- **动画**：Canvas 2D

### 部署环境
- **云服务**：阿里云ECS（2核4G）
- **Web服务器**：Nginx
- **数据库**：MySQL 8.0
- **容器化**：Docker Compose（开发环境）

---

## 二、模块边界划分

### 后端模块
1. **api层**：HTTP路由和控制器
2. **model层**：数据模型定义
3. **service层**：业务逻辑处理
4. **repository层**：数据访问层
5. **middleware层**：中间件（CORS、Auth、Logger、RateLimit）
6. **pkg层**：工具包（JWT、密码、验证、响应）
7. **config层**：配置管理

### 前端模块（3个独立项目）
1. **admin**：管理后台
2. **screen**：大屏幕展示
3. **mobile**：移动端H5

---

## 三、文件清单与职责

### 后端文件结构
```
backend/
├── cmd/
│   └── server/
│       └── main.go                    # 程序入口，初始化配置、数据库、路由
├── internal/
│   ├── api/
│   │   ├── v1/
│   │   │   ├── auth.go               # 认证相关接口
│   │   │   ├── activity.go           # 活动管理接口
│   │   │   ├── checkin.go            # 签到接口
│   │   │   ├── danmaku.go            # 弹幕接口
│   │   │   ├── lottery.go            # 抽奖接口
│   │   │   ├── moneygame.go          # 数钱游戏接口
│   │   │   └── order.go              # 订单接口
│   │   └── router.go                 # 路由配置
│   ├── model/
│   │   ├── user.go                   # 用户模型
│   │   ├── activity.go               # 活动模型
│   │   ├── checkin.go                # 签到模型
│   │   ├── danmaku.go                # 弹幕模型
│   │   ├── lottery.go                # 抽奖模型
│   │   ├── moneygame.go              # 数钱游戏模型
│   │   └── order.go                  # 订单模型
│   ├── service/
│   │   ├── auth.go                   # 认证业务逻辑
│   │   ├── activity.go               # 活动业务逻辑
│   │   ├── checkin.go                # 签到业务逻辑
│   │   ├── danmaku.go                # 弹幕业务逻辑
│   │   ├── lottery.go                # 抽奖业务逻辑
│   │   ├── moneygame.go              # 数钱游戏业务逻辑
│   │   └── order.go                  # 订单业务逻辑
│   ├── repository/
│   │   ├── user.go                   # 用户数据访问
│   │   ├── activity.go               # 活动数据访问
│   │   ├── checkin.go                # 签到数据访问
│   │   ├── danmaku.go                # 弹幕数据访问
│   │   ├── lottery.go                # 抽奖数据访问
│   │   ├── moneygame.go              # 数钱游戏数据访问
│   │   └── order.go                  # 订单数据访问
│   ├── middleware/
│   │   ├── cors.go                   # 跨域中间件
│   │   ├── auth.go                   # 认证中间件
│   │   ├── logger.go                 # 日志中间件
│   │   └── rate_limit.go             # 限流中间件
│   ├── pkg/
│   │   ├── jwt.go                    # JWT工具
│   │   ├── password.go               # 密码加密工具
│   │   ├── validator.go              # 参数验证工具
│   │   └── response.go               # 统一响应格式
│   └── config/
│       └── config.go                 # 配置加载和管理
├── config/
│   ├── config.yaml                   # 开发环境配置
│   └── config.prod.yaml              # 生产环境配置
├── scripts/
│   ├── build.sh                      # 构建脚本
│   └── deploy.sh                     # 部署脚本
├── go.mod
└── go.sum
```

### 前端文件结构（admin示例）
```
frontend/admin/
├── public/
│   └── favicon.ico
├── src/
│   ├── api/                          # API接口定义
│   │   ├── auth.js
│   │   ├── activity.js
│   │   ├── checkin.js
│   │   ├── danmaku.js
│   │   ├── lottery.js
│   │   ├── moneygame.js
│   │   └── order.js
│   ├── assets/                       # 静态资源
│   ├── components/                   # 公共组件
│   ├── router/                       # 路由配置
│   ├── stores/                       # Pinia状态管理
│   ├── utils/                        # 工具函数
│   ├── views/                        # 页面视图
│   │   ├── auth/
│   │   ├── activity/
│   │   ├── checkin/
│   │   ├── lottery/
│   │   └── moneygame/
│   ├── App.vue
│   └── main.js
├── .env.development                  # 开发环境变量
├── .env.production                   # 生产环境变量
├── index.html
├── package.json
└── vite.config.js
```

---

## 四、核心数据结构定义

### 配置结构
```go
type Config struct {
    Server   ServerConfig
    Database DatabaseConfig
    JWT      JWTConfig
    Log      LogConfig
}

type ServerConfig struct {
    Port    string
    Mode    string // debug/release
}

type DatabaseConfig struct {
    Host     string
    Port     string
    User     string
    Password string
    DBName   string
}

type JWTConfig struct {
    Secret string
    Expire int // hours
}

type LogConfig struct {
    Level  string
    Output string
}
```

### 统一响应格式
```go
type Response struct {
    Code    int         `json:"code"`
    Message string      `json:"message"`
    Data    interface{} `json:"data,omitempty"`
}
```

---

## 五、核心接口定义

### 认证接口
- `POST /api/v1/auth/register` - 用户注册
- `POST /api/v1/auth/login` - 用户登录

### 活动接口（需认证）
- `POST /api/v1/activity` - 创建活动
- `GET /api/v1/activity` - 获取活动列表
- `GET /api/v1/activity/:id` - 获取活动详情
- `PUT /api/v1/activity/:id` - 更新活动
- `DELETE /api/v1/activity/:id` - 删除活动

### 签到接口
- `POST /api/v1/mobile/checkin` - 扫码签到（公开）
- `GET /api/v1/activity/:activityId/checkin` - 获取签到列表（需认证）
- `GET /api/v1/activity/:activityId/checkin/export` - 导出签到列表（需认证）

### 弹幕接口
- `POST /api/v1/mobile/danmaku` - 发送弹幕（公开）
- `GET /api/v1/mobile/danmaku/:activityId` - 获取弹幕列表（公开，长轮询）

### 抽奖接口
- `POST /api/v1/activity/:activityId/lottery` - 创建抽奖（需认证）
- `GET /api/v1/activity/:activityId/lottery` - 获取抽奖列表（需认证）
- `POST /api/v1/activity/:activityId/lottery/:id/draw` - 执行抽奖（需认证）
- `GET /api/v1/activity/:activityId/lottery/:id/winners` - 获取中奖名单（需认证）

### 数钱游戏接口
- `POST /api/v1/activity/:activityId/moneygame` - 创建游戏（需认证）
- `GET /api/v1/activity/:activityId/moneygame` - 获取游戏列表（需认证）
- `POST /api/v1/activity/:activityId/moneygame/:id/start` - 开始游戏（需认证）
- `POST /api/v1/mobile/moneygame/:id/tap` - 点击数钱（公开）
- `GET /api/v1/activity/:activityId/moneygame/:id/rank` - 获取排名（公开）

### 订单接口
- `POST /api/v1/order` - 创建订单（需认证）
- `GET /api/v1/order` - 获取订单列表（需认证）
- `POST /api/v1/order/:id/pay` - 支付订单（需认证）

---

## 六、数据库表创建顺序

1. **users** - 用户表（基础表）
2. **activities** - 活动表（依赖users）
3. **checkins** - 签到表（依赖activities）
4. **danmakus** - 弹幕表（依赖activities）
5. **lotteries** - 抽奖表（依赖activities）
6. **lottery_winners** - 中奖记录表（依赖lotteries和checkins）
7. **money_games** - 数钱游戏表（依赖activities）
8. **money_game_records** - 游戏记录表（依赖money_games和checkins）
9. **orders** - 订单表（依赖users和activities）

---

## 七、任务拆分

### 阶段1：后端项目初始化
1. 创建backend目录
2. 初始化Go模块（go mod init）
3. 创建项目目录结构（cmd/internal/config/scripts）
4. 安装依赖包（gin, gorm, viper, zap, jwt等）
5. 创建配置文件（config.yaml和config.prod.yaml）
6. 实现配置加载功能（internal/config/config.go）
7. 实现日志初始化功能（使用Zap）
8. 实现统一响应格式工具（internal/pkg/response.go）
9. 实现JWT工具（internal/pkg/jwt.go）
10. 实现密码加密工具（internal/pkg/password.go）
11. 实现参数验证工具（internal/pkg/validator.go）

### 阶段2：数据库初始化
1. 创建数据库（live_cloud）
2. 实现数据库连接初始化（internal/config/config.go中添加InitDB函数）
3. 创建用户模型（internal/model/user.go）
4. 创建活动模型（internal/model/activity.go）
5. 创建签到模型（internal/model/checkin.go）
6. 创建弹幕模型（internal/model/danmaku.go）
7. 创建抽奖模型（internal/model/lottery.go）
8. 创建中奖记录模型（internal/model/lottery_winner.go）
9. 创建数钱游戏模型（internal/model/moneygame.go）
10. 创建游戏记录模型（internal/model/moneygame_record.go）
11. 创建订单模型（internal/model/order.go）
12. 实现数据库自动迁移（在main.go中调用AutoMigrate）

### 阶段3：中间件开发
1. 实现CORS中间件（internal/middleware/cors.go）
2. 实现认证中间件（internal/middleware/auth.go）
3. 实现日志中间件（internal/middleware/logger.go）
4. 实现限流中间件（internal/middleware/rate_limit.go）

### 阶段4：Repository层开发
1. 实现用户Repository（internal/repository/user.go）
2. 实现活动Repository（internal/repository/activity.go）
3. 实现签到Repository（internal/repository/checkin.go）
4. 实现弹幕Repository（internal/repository/danmaku.go）
5. 实现抽奖Repository（internal/repository/lottery.go）
6. 实现数钱游戏Repository（internal/repository/moneygame.go）
7. 实现订单Repository（internal/repository/order.go）

### 阶段5：Service层开发
1. 实现认证Service（internal/service/auth.go）
2. 实现活动Service（internal/service/activity.go）
3. 实现签到Service（internal/service/checkin.go）
4. 实现弹幕Service（internal/service/danmaku.go）
5. 实现抽奖Service（internal/service/lottery.go）
6. 实现数钱游戏Service（internal/service/moneygame.go）
7. 实现订单Service（internal/service/order.go）

### 阶段6：API层开发
1. 实现路由配置（internal/api/router.go）
2. 实现认证接口（internal/api/v1/auth.go）
3. 实现活动接口（internal/api/v1/activity.go）
4. 实现签到接口（internal/api/v1/checkin.go）
5. 实现弹幕接口（internal/api/v1/danmaku.go）
6. 实现抽奖接口（internal/api/v1/lottery.go）
7. 实现数钱游戏接口（internal/api/v1/moneygame.go）
8. 实现订单接口（internal/api/v1/order.go）

### 阶段7：主程序入口
1. 实现main.go（cmd/server/main.go）
2. 加载配置
3. 初始化日志
4. 初始化数据库
5. 设置路由
6. 启动HTTP服务器

### 阶段8：前端项目初始化（3个独立项目）
1. 创建frontend目录
2. 初始化admin项目（npm create vite@latest）
3. 安装admin依赖（vue-router, pinia, axios, element-plus）
4. 创建admin项目目录结构（src/api, src/components, src/router, src/stores, src/views, src/utils）
5. 初始化screen项目（npm create vite@latest）
6. 安装screen依赖（vue-router, pinia, axios）
7. 创建screen项目目录结构
8. 初始化mobile项目（npm create vite@latest）
9. 安装mobile依赖（vue-router, pinia, axios, vant）
10. 创建mobile项目目录结构

### 阶段9：前端基础配置
1. 配置Vite（vite.config.js）
2. 配置环境变量（.env.development和.env.production）
3. 配置Axios（src/utils/request.js）
4. 配置路由（src/router/index.js）
5. 配置Pinia（src/stores/index.js）
6. 配置Element Plus（admin项目）
7. 配置Vant（mobile项目）

### 阶段10：Docker开发环境
1. 创建docker-compose.yml
2. 配置MySQL服务
3. 创建启动脚本

### 阶段11：构建和部署脚本
1. 创建后端构建脚本（scripts/build.sh）
2. 创建后端部署脚本（scripts/deploy.sh）
3. 配置前端打包（vite build）

---

## 八、配置文件模板

### config.yaml（开发环境）
```yaml
server:
  port: "8080"
  mode: "debug"

database:
  host: "localhost"
  port: "3306"
  user: "root"
  password: "123456"
  dbname: "live_cloud"

jwt:
  secret: "your-secret-key-change-in-production"
  expire: 24

log:
  level: "debug"
  output: "stdout"
```

### config.prod.yaml（生产环境）
```yaml
server:
  port: "8080"
  mode: "release"

database:
  host: "your-mysql-host"
  port: "3306"
  user: "your-mysql-user"
  password: "your-mysql-password"
  dbname: "live_cloud"

jwt:
  secret: "your-production-secret-key"
  expire: 24

log:
  level: "info"
  output: "file"
```

### docker-compose.yml
```yaml
version: '3.8'

services:
  mysql:
    image: mysql:8.0
    container_name: live_cloud_mysql
    environment:
      MYSQL_ROOT_PASSWORD: 123456
      MYSQL_DATABASE: live_cloud
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql

volumes:
  mysql_data:
```

---

## 九、注意事项

1. **编码规范**：使用`gofmt`格式化Go代码，使用ESLint和Prettier格式化前端代码
2. **日志记录**：在关键操作处添加日志记录，便于问题排查
3. **错误处理**：统一错误处理和响应格式
4. **参数验证**：所有输入参数都需要验证
5. **安全防护**：
   - 密码使用BCrypt加密
   - JWT Token有效期控制
   - SQL注入防护（使用GORM参数化查询）
   - XSS防护（前端输入过滤）
6. **性能优化**：
   - 数据库查询使用索引
   - 避免N+1查询
   - 合理使用连接池
7. **测试**：后续需要添加单元测试和集成测试

---

**记录时间**：2026年1月31日
**状态**：待确认