新增项目启动规划和AGENTS文档，详细描述现场互动SaaS平台的项目概述、团队配置、预算规划、产品功能及运营策略
This commit is contained in:
446
doc/thinking/platform_setup.md
Normal file
446
doc/thinking/platform_setup.md
Normal file
@@ -0,0 +1,446 @@
|
||||
# 平台搭建设计方案
|
||||
|
||||
## 一、技术选型确认
|
||||
|
||||
### 后端技术栈
|
||||
- **语言**：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日
|
||||
**状态**：待确认
|
||||
Reference in New Issue
Block a user