feat: 世界杯48强夺冠盘、管理端调赔与项目文档

- 固定48强基准数据、同步种子与后台世界杯夺冠页

- 补全 user_preferences 迁移文件;新增启动指南与默认数据说明

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
2026-06-03 16:19:36 +08:00
parent 3b739982a1
commit 95abbcb470
17 changed files with 1157 additions and 92 deletions

344
docs/项目启动指南.md Normal file
View 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. 启动数据库(二选一)
#### 方案 ADocker已安装 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` | 仅 APIwatch |
| `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) — 产品需求(若存在)
---
*文档随仓库脚本与端口变更时请同步更新。*

178
docs/默认数据说明.md Normal file
View File

@@ -0,0 +1,178 @@
# 默认数据说明
执行 `pnpm db:migrate` 后数据库仅有**表结构**;执行 **`pnpm db:seed`** 后会写入下文演示数据。
种子脚本位置:`apps/api/prisma/seed.ts`
> **注意**:以下为开发演示用途。生产环境务必修改密码、`JWT_SECRET`,勿直接使用默认账号。
---
## migrate 与 seed 的区别
| 命令 | 作用 |
|------|------|
| `pnpm db:migrate` | 按 Prisma 迁移**建表 / 改表**(用户、赛事、盘口、注单等) |
| `pnpm db:seed` | 在已有表结构中**写入演示账号、赛事、赔率、内容等** |
推荐顺序:先 `db:migrate`,再 `db:seed`
种子多为 **upsert**重复执行一般不会重复创建用户但会补全赛事、48 强夺冠盘等。
---
## 一、默认账号
| 用户名 | 密码 | 角色 | 说明 |
|--------|------|------|------|
| `admin` | `Admin@123` | 平台管理员 | 绑定 `SUPER_ADMIN` 角色 |
| `agent1` | `Agent@123` | 一级代理 | 授信额度 **100,000** |
| `agent2` | `Agent@123` | 二级代理 | 上级为 agent1授信 **30,000** |
| `player1` | `Player@123` | 玩家 | 挂靠 agent1 |
| 入口 | 地址 |
|------|------|
| 管理后台admin / agent1 / agent2 | http://localhost:5174 |
| 玩家前台player1 | http://localhost:5173 |
| 接口 | 路径 |
|------|------|
| 管理端登录 | `POST /api/manage/auth/login` |
| 玩家端登录 | `POST /api/player/auth/login` |
---
## 二、默认环境与端口
| 项 | 默认值 |
|----|--------|
| API | http://localhost:3000 ,全局前缀 `/api` |
| Swagger | http://localhost:3000/api/docs |
| 管理后台 | http://localhost:5174 |
| 玩家前台 | http://localhost:5173 |
| Docker PostgreSQL | 用户/密码/库:`thebet365` @ `localhost:5432` |
| Docker Redis | `localhost:6379`(当前 API 逻辑以 Postgres 为主) |
`apps/api/.env` 模板见根目录 `.env.example`,主要项:
| 变量 | 示例 | 说明 |
|------|------|------|
| `DATABASE_URL` | `postgresql://thebet365:thebet365@localhost:5432/thebet365` | 数据库连接 |
| `JWT_SECRET` | 长随机串 | **生产必须修改** |
| `JWT_PLAYER_EXPIRES` | `24h` | 玩家 Token |
| `JWT_ADMIN_EXPIRES` | `2h` | 管理员 Token |
| `JWT_AGENT_EXPIRES` | `8h` | 代理 Token |
| `PORT` | `3000` | API 端口 |
| `UPLOAD_DIR` | 空 | 默认 `apps/api/uploads` |
---
## 三、默认赛事与盘口
### 联赛
| 代码 | 名称 |
|------|------|
| `EPL` | 英超 / Premier League |
| `WC2026` | 2026 世界杯(加拿大、墨西哥、美国) |
### 已发布场次(约 9 场)
- **英超 2 场**:如曼联 vs 切尔西(开球时间为相对当前的演示时间)
- **世界杯 7 场**:如墨西哥-南非、美国-巴拉圭、法国-阿根廷等2026-06 固定日期)
每场在尚无盘口时会自动创建演示玩法,包括但不限于:
- 全场 / 半场:独赢、让球、大小、单双
- 全场 / 半场 / 下半场:波胆(多档比分选项)
赔率均为种子脚本中的**示例数值**,可在管理后台赛事相关流程中调整(非冠军盘)。
### 世界杯 48 强夺冠盘
| 项 | 说明 |
|----|------|
| 数据来源 | `apps/api/src/domains/catalog/wc2026-outright-teams.ts` |
| 队伍数 | **48** 支,含排名与中英文名 |
| 默认赔率 | 如法国 4.95、英格兰 6.3、苏格兰 2500 等 |
| 玩家端 | 足球页 → **「优胜冠军」** |
| 管理端 | 菜单 **「世界杯夺冠」** → 可改赔率 |
| 恢复基准 | 点击 **「应用表格基准数据」** 与代码表对齐 |
`pnpm db:seed` 会以 `forceCanonical: true` 同步 48 强;已有选项的赔率仅在「应用基准」或重新 seed 时按文件覆盖。
---
## 四、玩家演示数据player1
| 项 | 默认值 |
|----|--------|
| 可用余额 | **88,888.88** |
| 账变流水 | 2 笔演示充值(`DEMO-DEP-001` / `DEMO-DEP-002` |
| 语言偏好 | `zh-CN` |
| 示例注单 | `DEMO-BET-001`:待结算单关;`DEMO-BET-002`:已赢且已结算单关 |
---
## 五、运营内容(玩家首页)
| 类型 | 数量 | 说明 |
|------|------|------|
| Banner | 3 | 欢迎投注、首存礼遇、热门赛事 |
| 走马灯TICKER | 1 | 欢迎语 + 理性投注提示 |
| 公告NOTICE | 1 | 每周一 04:0005:00 维护通知 |
图片路径示例:`/uploads/banners/welcome.svg` 等。
重复执行 seed 时,已存在的同类内容可能因 `catch` 跳过,不会无限重复插入。
---
## 六、权限与库内多语言
### 角色与权限
- 角色:`SUPER_ADMIN`(超级管理员)
- 权限示例:`users.create``users.view``agents.create``agents.view``wallet.deposit``wallet.withdraw``matches.manage``settlement.confirm``cashback.confirm``content.manage``reports.view`
### i18n_messages 表
种子仅写入少量玩家端 key中 / 英 / 马来),例如 `nav.home``bet.place_bet`
**管理后台与玩家端大部分文案在代码内**`admin-messages``player` 内 vue-i18n不全部存数据库。
---
## 七、管理后台默认行为
| 项 | 默认 |
|----|------|
| 界面语言 | 中文 `zh-CN``localStorage``admin_locale` |
| 可选语言 | 中文、English、Bahasa Melayu |
| 登录页 | 若开启「快速登录(调试)」可一键 admin / agent |
---
## 八、如何查看 / 重置
```bash
# 可视化浏览所有表
pnpm db:studio
# 重新写入种子(不删表,多为 upsert
pnpm db:seed
```
仅想恢复 **48 强夺冠赔率** 为代码基准:管理后台 → **世界杯夺冠****应用表格基准数据**
清空数据库后重来:
```bash
docker compose down -v # 会删除 Docker 数据卷,慎用
docker compose up -d
pnpm db:migrate
pnpm db:seed
```
---
## 相关文档
- [项目启动指南.md](./项目启动指南.md) — 安装、启动、排错
- [README.md](../README.md) — 项目概览