feat: 世界杯48强夺冠盘、管理端调赔与项目文档
- 固定48强基准数据、同步种子与后台世界杯夺冠页 - 补全 user_preferences 迁移文件；新增启动指南与默认数据说明 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
344
docs/项目启动指南.md
Normal file
344
docs/项目启动指南.md
Normal file
@@ -0,0 +1,344 @@
|
||||
# TheBet365 项目启动指南
|
||||
|
||||
本文档汇总本地开发、首次部署与日常启动所需的全部步骤与配置说明。
|
||||
|
||||
---
|
||||
|
||||
## 一、环境要求
|
||||
|
||||
| 工具 | 版本要求 | 说明 |
|
||||
|------|----------|------|
|
||||
| **Node.js** | ≥ 20 | 见根目录 `package.json` → `engines` |
|
||||
| **pnpm** | 8+（推荐最新） | Monorepo 包管理，需先 `corepack enable` 或全局安装 |
|
||||
| **Docker** | 最新稳定版（可选） | 推荐：一键起 PostgreSQL；也可用本机安装的 Postgres |
|
||||
| **PostgreSQL** | 14+（推荐 16） | **必需**（API / Prisma） |
|
||||
| **Git** | 任意 | 拉取代码 |
|
||||
|
||||
> 当前 API **仅依赖 PostgreSQL**；`docker-compose` 里的 Redis 为预留，未安装 Redis 一般不影响本地开发。
|
||||
|
||||
可选：
|
||||
|
||||
- **Docker Compose** v2（`docker compose`，非旧版 `docker-compose`）
|
||||
- Windows 用户建议使用 PowerShell 或 Windows Terminal
|
||||
|
||||
---
|
||||
|
||||
## 二、仓库结构速览
|
||||
|
||||
```
|
||||
thebet365/
|
||||
├── apps/
|
||||
│ ├── api/ NestJS 后端（Prisma + PostgreSQL）
|
||||
│ ├── admin/ 管理后台（平台管理员 + 代理，:5174）
|
||||
│ └── player/ 玩家 H5 前台（:5173）
|
||||
├── packages/
|
||||
│ └── shared/ 共享类型与静态资源（public）
|
||||
├── uploads/ 上传文件目录（Banner 等，API 静态托管）
|
||||
├── docker-compose.yml
|
||||
├── .env.example 环境变量模板
|
||||
└── package.json 根脚本（dev / db:*）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、首次启动（完整流程）
|
||||
|
||||
按顺序执行，**只需做一次**（或换机器 / 清空数据库后重做）。
|
||||
|
||||
### 1. 克隆并进入项目
|
||||
|
||||
```bash
|
||||
cd thebet365
|
||||
```
|
||||
|
||||
### 2. 启动数据库（二选一）
|
||||
|
||||
#### 方案 A：Docker（已安装 Docker Desktop 时）
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
| 服务 | 容器名 | 端口 | 默认账号 |
|
||||
|------|--------|------|----------|
|
||||
| PostgreSQL 16 | `thebet365-postgres` | `5432` | 用户/密码/库：`thebet365` |
|
||||
| Redis 7 | `thebet365-redis` | `6379` | 无密码（可选） |
|
||||
|
||||
`apps/api/.env` 使用：
|
||||
|
||||
```env
|
||||
DATABASE_URL=postgresql://thebet365:thebet365@localhost:5432/thebet365
|
||||
```
|
||||
|
||||
停止：`docker compose down` · 清空数据卷（慎用）：`docker compose down -v`
|
||||
|
||||
**Windows 未识别 `docker` 命令时**：安装 [Docker Desktop for Windows](https://www.docker.com/products/docker-desktop/)，安装后重启 PowerShell，并确保设置里已勾选 **Use WSL 2**（推荐）。也可用 winget：
|
||||
|
||||
```powershell
|
||||
winget install Docker.DockerDesktop
|
||||
```
|
||||
|
||||
#### 方案 B：本机 PostgreSQL（无 Docker）
|
||||
|
||||
1. 安装 PostgreSQL 16（任选其一）：
|
||||
- https://www.postgresql.org/download/windows/
|
||||
- 或 `winget install PostgreSQL.PostgreSQL.16`
|
||||
2. 安装时记住 **超级用户密码**（默认用户常为 `postgres`）。
|
||||
3. 用 **pgAdmin** 或 `psql` 创建与项目一致的数据库（也可改用你自己的账号，同步改 `DATABASE_URL`）：
|
||||
|
||||
```sql
|
||||
CREATE USER thebet365 WITH PASSWORD 'thebet365';
|
||||
CREATE DATABASE thebet365 OWNER thebet365;
|
||||
GRANT ALL PRIVILEGES ON DATABASE thebet365 TO thebet365;
|
||||
```
|
||||
|
||||
4. 编辑 `apps/api/.env`：
|
||||
|
||||
```env
|
||||
DATABASE_URL=postgresql://thebet365:thebet365@localhost:5432/thebet365
|
||||
```
|
||||
|
||||
若只用默认 `postgres` 用户：
|
||||
|
||||
```env
|
||||
DATABASE_URL=postgresql://postgres:你的密码@localhost:5432/thebet365
|
||||
```
|
||||
|
||||
（需已 `CREATE DATABASE thebet365;`）
|
||||
|
||||
5. 确认本机 **5432** 端口 Postgres 服务已启动（Windows「服务」里 `postgresql-x64-16` 为「正在运行」）。
|
||||
|
||||
### 3. 安装依赖
|
||||
|
||||
在**仓库根目录**执行：
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### 4. 配置环境变量
|
||||
|
||||
将根目录模板复制到 API 目录（Nest 从 `apps/api` 工作目录读取 `.env`）：
|
||||
|
||||
```bash
|
||||
cp .env.example apps/api/.env
|
||||
```
|
||||
|
||||
`apps/api/.env` 主要项说明：
|
||||
|
||||
| 变量 | 示例值 | 说明 |
|
||||
|------|--------|------|
|
||||
| `DATABASE_URL` | `postgresql://thebet365:thebet365@localhost:5432/thebet365` | 须与 docker-compose 一致 |
|
||||
| `REDIS_URL` | `redis://localhost:6379` | 预留，与 compose 中 Redis 对应 |
|
||||
| `JWT_SECRET` | 长随机字符串 | **生产环境务必修改** |
|
||||
| `JWT_PLAYER_EXPIRES` | `24h` | 玩家 Token 有效期 |
|
||||
| `JWT_ADMIN_EXPIRES` | `2h` | 管理员 Token |
|
||||
| `JWT_AGENT_EXPIRES` | `8h` | 代理 Token |
|
||||
| `PORT` | `3000` | API 监听端口 |
|
||||
| `NODE_ENV` | `development` | 开发环境 |
|
||||
| `UPLOAD_DIR` | 留空 | 默认使用 `apps/api/uploads`；可填绝对路径 |
|
||||
|
||||
### 5. 数据库迁移与种子数据
|
||||
|
||||
仍在**仓库根目录**：
|
||||
|
||||
```bash
|
||||
pnpm db:generate # 生成 Prisma Client（改 schema 后需要）
|
||||
pnpm db:migrate # 执行迁移（开发环境，可交互命名）
|
||||
pnpm db:seed # 演示账号、赛事、世界杯 48 强夺冠盘等
|
||||
```
|
||||
|
||||
生产环境部署迁移使用：
|
||||
|
||||
```bash
|
||||
pnpm --filter @thebet365/api db:migrate:deploy
|
||||
```
|
||||
|
||||
可视化查看数据（可选）：
|
||||
|
||||
```bash
|
||||
pnpm db:studio
|
||||
```
|
||||
|
||||
### 6. 启动开发服务
|
||||
|
||||
**方式 A：一键启动全部**（API + admin + player + shared 编译监听）
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
**方式 B：分终端启动**（推荐调试时）
|
||||
|
||||
```bash
|
||||
# 终端 1 — 必须先起 API
|
||||
pnpm dev:api
|
||||
|
||||
# 终端 2 — 管理后台
|
||||
pnpm dev:admin
|
||||
|
||||
# 终端 3 — 玩家前台
|
||||
pnpm dev:player
|
||||
```
|
||||
|
||||
> `dev:manage` 与 `dev:admin` 相同，均为管理后台。
|
||||
|
||||
---
|
||||
|
||||
## 四、访问地址
|
||||
|
||||
| 应用 | 地址 | 说明 |
|
||||
|------|------|------|
|
||||
| **API** | http://localhost:3000/api | 全局前缀 `api` |
|
||||
| **Swagger** | http://localhost:3000/api/docs | 接口文档 |
|
||||
| **玩家前台** | http://localhost:5173 | Vite 代理 `/api` → `:3000` |
|
||||
| **管理后台** | http://localhost:5174 | Vite 代理 `/api` → `:3000` |
|
||||
| **静态上传** | http://localhost:3000/uploads/... | 玩家端也可经 `:5173/uploads` 代理 |
|
||||
|
||||
前端开发时**无需单独配置 CORS**，Vite 已将 `/api`（玩家端含 `/uploads`）反向代理到 API。
|
||||
|
||||
---
|
||||
|
||||
## 五、演示账号与默认数据
|
||||
|
||||
`pnpm db:seed` 写入账号、赛事、48 强夺冠、Banner 等。**完整清单**见 **[默认数据说明.md](./默认数据说明.md)**。
|
||||
|
||||
| 角色 | 用户名 | 密码 | 登录入口 |
|
||||
|------|--------|------|----------|
|
||||
| 平台管理员 | `admin` | `Admin@123` | 管理后台 http://localhost:5174 |
|
||||
| 一级代理 | `agent1` | `Agent@123` | 同上（菜单为代理端） |
|
||||
| 二级代理 | `agent2` | `Agent@123` | 同上 |
|
||||
| 玩家 | `player1` | `Player@123` | 玩家前台 http://localhost:5173 |
|
||||
|
||||
管理端：`POST /api/manage/auth/login` · 玩家端：`POST /api/player/auth/login`
|
||||
|
||||
---
|
||||
|
||||
## 六、根目录常用命令
|
||||
|
||||
| 命令 | 作用 |
|
||||
|------|------|
|
||||
| `pnpm dev` | 并行启动各 app 的 `dev` 脚本 |
|
||||
| `pnpm dev:api` | 仅 API（watch） |
|
||||
| `pnpm dev:admin` | 仅管理后台 |
|
||||
| `pnpm dev:player` | 仅玩家前台 |
|
||||
| `pnpm build` | 构建所有 workspace 包 |
|
||||
| `pnpm test` | 运行各包测试 |
|
||||
| `pnpm db:generate` | Prisma Client 生成 |
|
||||
| `pnpm db:migrate` | 开发迁移 |
|
||||
| `pnpm db:seed` | 种子数据（含 WC2026 48 强夺冠） |
|
||||
| `pnpm db:studio` | Prisma Studio |
|
||||
|
||||
---
|
||||
|
||||
## 七、业务数据与上传目录
|
||||
|
||||
详见 **[默认数据说明.md](./默认数据说明.md)**（赛事、盘口、48 强夺冠、player1 余额与注单、Banner 等）。
|
||||
|
||||
- 上传目录默认：`apps/api/uploads/`（可由 `UPLOAD_DIR` 覆盖）
|
||||
|
||||
---
|
||||
|
||||
## 八、生产构建（简述）
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm build
|
||||
# API
|
||||
pnpm --filter @thebet365/api start
|
||||
# 前端产物在各自 apps/*/dist，由 Nginx 等托管，并反向代理 /api 到后端
|
||||
```
|
||||
|
||||
生产务必：
|
||||
|
||||
1. 修改 `JWT_SECRET` 与数据库密码
|
||||
2. 使用 `db:migrate:deploy` 而非 `migrate dev`
|
||||
3. 配置 `NODE_ENV=production` 与真实 `DATABASE_URL`
|
||||
|
||||
---
|
||||
|
||||
## 九、常见问题
|
||||
|
||||
### 1. PowerShell 提示「无法将 docker 识别为 cmdlet」
|
||||
|
||||
- 未安装 Docker，或未加入 PATH → 用上文 **方案 B 本机 PostgreSQL**，或安装 Docker Desktop 后重启终端。
|
||||
|
||||
### 2. `P3015` / `Could not find the migration file at migration.sql`
|
||||
|
||||
- 原因：`apps/api/prisma/migrations/` 下某个迁移目录缺少 `migration.sql`（例如空的 `20260602120000_user_preference_contact`）。
|
||||
- 处理：拉取最新代码后重试 `pnpm db:migrate`；若本地曾误删该文件，需从仓库恢复或删除空目录后重新 `prisma migrate dev`。
|
||||
- 说明：若 `pnpm db:seed` 已成功，说明表结构多半已可用，可先 `pnpm dev:api` 开发；仍建议修好 migrate 以便团队协作。
|
||||
|
||||
**若修复文件后提示 Drift detected（库里有字段但迁移历史未记录）**，在 `apps/api` 下将已存在的迁移标记为已应用（不删数据）：
|
||||
|
||||
```bash
|
||||
cd apps/api
|
||||
pnpm exec prisma migrate resolve --applied 20260602120000_user_preference_contact
|
||||
pnpm exec prisma migrate resolve --applied 20260603102323_zhibo_match_fields
|
||||
pnpm db:migrate
|
||||
```
|
||||
|
||||
仍无法收敛且可接受清空库时：`pnpm exec prisma migrate reset`（会删库），再 `pnpm db:seed`。
|
||||
|
||||
### 3. `pnpm db:migrate` 连接数据库失败
|
||||
|
||||
- Docker 方案：确认 `docker compose up -d` 且 Postgres 健康
|
||||
- 本机方案：确认 PostgreSQL 服务已启动、库 `thebet365` 已创建
|
||||
- 检查 `apps/api/.env` 中 `DATABASE_URL` 主机/端口/账号/密码
|
||||
|
||||
### 4. 管理后台文案显示为 key（如 `user.field.xxx`）
|
||||
|
||||
- 勿在 `apps/admin/src` 下保留误生成的 `*.js`（会抢先于 `.ts` 被 Vite 加载）
|
||||
- 清理缓存后重启：`apps/admin/node_modules/.vite`
|
||||
- 硬刷新浏览器（Ctrl+Shift+R）
|
||||
|
||||
### 5. 前端接口 502 / 代理错误
|
||||
|
||||
- 必须先启动 `pnpm dev:api`，再开 admin/player
|
||||
|
||||
### 6. `agent-form` 等模块导出报错
|
||||
|
||||
- 同上，删除 `apps/admin/src` 内过期 `.js`，重启 dev server
|
||||
|
||||
### 7. 夺冠盘不足 48 队
|
||||
|
||||
```bash
|
||||
pnpm db:seed
|
||||
```
|
||||
|
||||
或在管理后台 **世界杯夺冠 → 应用表格基准数据**。
|
||||
|
||||
### 8. Windows 下 Prisma / ts-node 权限问题
|
||||
|
||||
- 以管理员运行终端，或关闭占用 `5432` 端口的其他 Postgres 实例
|
||||
|
||||
---
|
||||
|
||||
## 十、推荐日常开发顺序
|
||||
|
||||
```text
|
||||
1. docker compose up -d
|
||||
2. pnpm dev:api # 等 API 打印 running
|
||||
3. pnpm dev:admin # 或 pnpm dev:player
|
||||
4. 浏览器打开对应端口
|
||||
```
|
||||
|
||||
改 Prisma schema 后：
|
||||
|
||||
```text
|
||||
pnpm db:generate && pnpm db:migrate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十一、相关文档
|
||||
|
||||
- [README.md](../README.md) — 项目概览与技术栈
|
||||
- [默认数据说明.md](./默认数据说明.md) — seed 后的账号、赛事、夺冠盘、运营内容
|
||||
- [apps/admin/README.md](../apps/admin/README.md) — 管理后台结构
|
||||
- [足球投注平台产品需求与MVP实施计划_PRD_v1.2.md](../足球投注平台产品需求与MVP实施计划_PRD_v1.2.md) — 产品需求（若存在）
|
||||
|
||||
---
|
||||
|
||||
*文档随仓库脚本与端口变更时请同步更新。*
|
||||
Reference in New Issue
Block a user