代练玩游戏平台 — 功能说明 & 使用手册

> 后端：FastAdmin （ThinkPHP 5） · 前端：Uniapp H5  

> 后端地址：http://ai-dailian.io  

> 前端地址：http://localhost:8080  

> API 根路径：http://ai-dailian.io/index.php/api  

> 后台管理：http://ai-dailian.io/index.php/admin（账号 admin / test123456）

---

## 一、项目结构

```

ai-dailian.io/

├── houduan/          # 后端（FastAdmin）

│   └── application/

│       ├── api/controller/     # 所有前端 API 控制器

│       │   ├── User.php        # 用户登录/注册

│       │   ├── Square.php      # 首页广场/大神列表

│       │   ├── Skill.php       # 技能管理

│       │   ├── Moment.php      # 动态系统

│       │   ├── Order.php       # 订单系统

│       │   ├── Wallet.php      # 钱包/充值/提现

│       │   ├── Room.php        # 语音房间

│       │   ├── Notify.php      # 消息通知

│       │   └── ProApply.php    # 大神入驻申请

│       └── extra/yipay.php     # 易支付配置（需填写真实参数）

├── qianduan/         # 前端（Uniapp）

│   └── pages/

│       ├── index/index.vue     # 首页（游戏分类 + 推荐大神）

│       ├── square/index.vue    # 大神广场（搜索/筛选/排序）

│       ├── pro/detail.vue      # 大神主页（简介/技能/评价）

│       ├── pro/apply.vue       # 大神入驻申请

│       ├── pro/skills.vue      # 我的技能管理（大神）

│       ├── moment/index.vue    # 动态广场

│       ├── moment/publish.vue  # 发布动态

│       ├── order/create.vue    # 下单页

│       ├── order/list.vue      # 我的订单

│       ├── order/detail.vue    # 订单详情

│       ├── order/pro_orders.vue # 接单中心（大神）

│       ├── wallet/index.vue    # 钱包（余额/充值/提现/流水）

│       ├── room/index.vue      # 语音厅列表

│       ├── room/create.vue     # 创建房间

│       ├── room/voice.vue      # 8麦位语音房间

│       ├── notify/index.vue    # 消息通知中心

│       └── user/profile.vue   # 个人中心

└── mysql/            # SQL 文件

```

---

## 二、各功能模块说明

### 2.1 用户系统

| 接口 | 方法 | 说明 | 是否需要登录 |

|------|------|------|------------|

| /user/login | POST | 账号密码登录 | 否 |

| /user/register | POST | 注册 | 否 |

| /user/profile | GET | 获取个人信息 | 是 |

| /user/profile | POST | 修改昵称/简介 | 是 |

| /user/logout | POST | 退出登录 | 是 |

**测试账号：**

- 普通用户：testuser88 / test123456

- 大神账号：admin / test123456（is_pro=1）

---

### 2.2 首页 & 大神广场

| 接口 | 说明 |

|------|------|

| GET /square/categories | 游戏分类列表 |

| GET /square/proList | 大神列表，支持 game_category_id、sort（hot/new/price）、keyword 筛选 |

| GET /square/proDetail?id=1 | 大神详情（技能/评价/相册/语音） |

**前端页面：**

- 首页（`pages/index/index`）：展示分类横向滚动 + 推荐大神卡片

- 广场（`pages/square/index`）：完整筛选/搜索/排序

---

### 2.3 动态系统

| 接口 | 说明 |

|------|------|

| GET /moment/index | 动态列表（公开，分页） |

| POST /moment/publish | 发布动态（content + images JSON数组） |

| POST /moment/like | 点赞/取消赞（moment_id） |

| POST /moment/del | 删除自己的动态（id） |

**图片上传流程（已修复）：**

1. 选择图片 → 调用 `uni.uploadFile` 上传到 `/api/common/upload`

2. 上传成功后取 `data.fullurl` 作为图片展示地址（若无 fullurl 则拼接站点域名）

3. 发布时将图片 URL 数组 JSON stringify 后一起提交

---

### 2.4 大神入驻申请

| 接口 | 路径 | 说明 |

|------|------|------|

| GET 查询状态 | /pro_apply/info | 返回审核状态/驳回原因 |

| POST 提交申请 | /pro_apply/apply | 上传真实姓名/证件照/段位截图/语音介绍 |

| POST 更新资料 | /pro_apply/update_info | 大神通过后修改语音/段位图 |

**审核流程：**

1. 用户在 `pages/pro/apply` 提交资料

2. 后台管理员在 **管理后台 → 游戏/大神管理** 中审核

3. 审核通过后 `fa_user.is_pro=1, pro_status=2`，用户成为大神

> ⚠️ 注意：后端路由是 `/pro_apply/`（下划线），不是 `/proapply/`

---

### 2.5 技能系统

| 接口 | 方法 | 说明 | 登录 |

|------|------|------|------|

| /skill/index | GET | 技能列表（公开），参数：pro_id, game_category_id | 否 |

| /skill/detail?id= | GET | 技能详情 | 否 |

| /skill/mySkills | GET | 我的技能（仅大神） | 是 |

| /skill/add | POST | 添加技能 | 是（大神） |

| /skill/edit | POST | 编辑技能 | 是（大神） |

| /skill/del | POST | 删除技能 | 是（大神） |

| /skill/toggle | POST | 上架/下架（status=0/1） | 是（大神） |

| /skill/categories | GET | 游戏分类下拉列表 | 否 |

**计价方式：** `hour`=按小时 / `game`=按局 / `package`=套餐

---

### 2.6 订单系统（核心）

#### 订单状态机：

```

10（待接单） → 20（服务中） → 30（待确认） → 40（已完成）

                                      ↘ 50（争议）

任意状态 → 99（已取消，用户取消/未接单前）

```

| 接口 | 方法 | 说明 | 谁调用 |

|------|------|------|--------|

| /order/create | POST | 下单（skill_id, quantity, requirement, pay_type=balance） | 用户 |

| /order/myOrders | GET | 我的订单（status=0全部） | 用户 |

| /order/proOrders | GET | 接单列表 | 大神 |

| /order/detail?id= | GET | 订单详情 | 双方 |

| /order/accept | POST | 接单（order_id） | 大神 |

| /order/finish | POST | 标记完工（order_id） | 大神 |

| /order/confirm | POST | 确认收货 → 自动结算 | 用户 |

| /order/cancel | POST | 取消订单（待接单阶段） | 用户 |

**结算规则：** 用户确认后，平台扣 10% 手续费，剩余 90% 自动入大神余额。

---

### 2.7 钱包系统

| 接口 | 方法 | 说明 |

|------|------|------|

| /wallet/info | GET | 余额/累计收支 |

| /wallet/logs | GET | 流水列表（type=all/income/expense） |

| /wallet/createOrder | POST | 创建易支付充值订单（返回 pay_url） |

| /wallet/payNotify | POST/GET | 易支付异步回调（自动到账） |

| /wallet/payReturn | GET | 支付同步跳转（支付完成跳回钱包页） |

| /wallet/withdraw | POST | 申请提现（支付宝）|

| /wallet/withdrawLogs | GET | 提现记录 |

#### 充值流程（易支付）：

```

用户点击"充值" 

→ 输入金额 → 点"支付宝充值"

→ 前端调 POST /wallet/createOrder

→ 后端创建 fa_recharge_order 记录，生成签名，返回 pay_url

→ 前端跳转到 pay_url（H5: window.location.href）

→ 用户在支付宝完成付款

→ 易支付服务器回调 /wallet/payNotify（验签 → 加余额 → 写流水）

→ 前端跳转回 /pages/wallet/index?pay=success（显示成功提示）

```

#### 配置易支付（必须操作）：

编辑 `houduan/application/extra/yipay.php`：

```php

return [

    ’api_url’    => ’https://你的易支付网关地址/submit.php’,

    ’pid’        => ’你的商户ID’,

    ’key’        => ’你的商户密钥’,

    ’notify_url’ => ’http://ai-dailian.io/index.php/api/wallet/payNotify’,

    ’return_url’ => ’http://ai-dailian.io/index.php/api/wallet/payReturn’,

];

```

#### 提现流程：

```

用户点"提现" → 填写金额/支付宝账号/真实姓名

→ 后端扣余额、写流水、创建提现申请（状态=待审核）

→ 管理员在后台审核并手动打款

→ 后台将提现状态改为"已打款"

```

> 手续费计算：max（0.5, amount × 1%），最-低 0.5 元

---

### 2.8 语音房间

| 接口 | 说明 |

|------|------|

| GET /room/lists | 房间列表 |

| POST /room/create | 创建房间（title, game_id, notice, seat_count=8） |

| GET /room/detail?id= | 房间详情（含8个麦位状态） |

| POST /room/takeSeat | 上麦（room_id, seat_no） |

| POST /room/leaveSeat | 下麦（room_id） |

| POST /room/kickSeat | 房主踢人（room_id, seat_no） |

| POST /room/lockSeat | 锁麦（room_id, seat_no） |

| POST /room/sendMsg | 发消息（room_id, content） |

| GET /room/messages | 轮询消息（room_id, last_id） |

| POST /room/close | 关闭房间（仅房主） |

**麦位说明：** 0号位为房主专属，1-7号为观众可申请麦位。

---

### 2.9 消息通知系统

| 接口 | 说明 |

|------|------|

| GET /notify/unread | 未读消息数量 |

| GET /notify/lists | 通知列表（自动标已读） |

| POST /notify/readAll | 全部标为已读 |

**通知类型：**

| type | 触发时机 |

|------|---------|

| order_new | 用户下单，通知大神 |

| order_accept | 大神接单，通知用户 |

| order_finish | 大神完工，通知用户 |

| order_confirm | 用户确认，通知大神（含结算金额） |

| order_cancel | 取消订单，通知双方 |

| system | 系统通知（充值/提现/手动推送） |

**如何手动推送系统通知（管理员）：**

方式一：通过 FastAdmin 后台数据库直接写入 `fa_notification` 表：

```sql

INSERT INTO fa_notification 

（user_id, sender_id, type, title, content, is_read, createtime）

VALUES

（目标用户ID, 0, ’system’, ’通知标题’, ’通知内容’, 0, UNIX_TIMESTAMP（））;

```

方式二：在后端代码中调用静态方法：

```php

use appapicontrollerNotify;

// 给指定用户推系统通知

Notify::push（$userId, ’system’, ’标题’, ’内容正文’）;

// 关联订单（点击可跳转）

Notify::push（$userId, ’system’, ’标题’, ’内容’, ’orders’, $orderId）;

```

> 目前前端通知页只展示，不支持用户主动发消息（设计定位：单向推送）。

---

## 三、数据库表说明

| 表名 | 说明 |

|------|------|

| fa_user | 用户（含 is_pro/pro_status/money 等字段） |

| fa_user_token | 登录 Token |

| fa_game_category | 游戏分类（王者/英雄联盟等） |

| fa_skills | 大神技能列表 |

| fa_pro_review | 大神评价 |

| fa_pro_album | 大神相册 |

| fa_moment | 用户动态 |

| fa_moment_like | 动态点赞记录 |

| fa_orders | 订单表 |

| fa_wallet_logs | 钱包流水 |

| fa_withdraw | 提现申请 |

| fa_recharge_order | 充值订单（易支付） |

| fa_voice_room | 语音房间 |

| fa_room_seat | 麦位状态 |

| fa_room_message | 房间聊天消息 |

| fa_notification | 消息通知 |

---

## 四、快速启动

### 后端

1. 确保 phpstudy 中 Apache + MySQL 已启动

2. 访问 http://ai-dailian.io 确认后端正常

### 前端

```bash

cd qianduan

npm run dev:h5

# 或在 HBuilderX 中运行到浏览器

```

访问 http://localhost:8080

### 配置易支付（上线必填）

```

houduan/application/extra/yipay.php

→ 填入真实的 api_url / pid / key

→ notify_url 必须为公网可访问地址

```

---

## 五、常见问题

**Q: 图片上传后不显示？**  

A: 已修复。上传接口返回的相对路径统一通过 `cdnUrl（）` 转为完整URL。

**Q: 输入框无法输入？**  

A: uniapp 的 `<input>` 需要明确高度。已修复 room/create 等页面的 `.field-input` 高度。

**Q: profile.vue 导致首页白屏？**  

A: 已修复。原因是 `methods` 块重复声明导致 Babel 语法错误。

**Q: 技能接口 500 错误？**  

A: 已修复。原因1：model 命名空间错误（`appadminmodelgameSkills`）；原因2：`setEagerlyType（0）` 导致 JOIN 字段歧义，改为 `setEagerlyType（1）`。

**Q: 通知显示 total=0？**  

A: 通知在订单生命周期中自动触发。请先完成一次完整订单流程（下单→接单→完工→确认）后查看通知。

**Q: 充值完成但余额没更新？**  

A: 异步回调需要 `notify_url` 公网可访问。本地开发可用 ngrok 做内网穿透：

```bash

ngrok http 80

# 将 https://xxx.ngrok.io 替换 yipay.php 中的 notify_url

```

---

## 六、各角色使用流程

### 普通用户流程

1. 注册/登录

2. 首页浏览大神 → 进入大神主页

3. 选择技能 → 下单（需余额）

4. 查看订单状态（订单列表）

5. 大神完工后 → 确认收货

6. 查看钱包余额/流水

### 大神流程

1. 登录 → 个人中心 → 申请成为大神

2. 等待后台审核通过

3. 进入"我的技能"添加/编辑技能

4. 进入"接单中心"查看待接订单

5. 接单 → 服务中 → 提交完工

6. 用户确认后，收益自动入账

7. 余额达到 10 元可申请提现（支付宝）

### 管理员流程

1. 登录后台：http://ai-dailian.io/index.php/admin

2. 审核大神申请（游戏/大神管理）

3. 管理游戏分类（添加/编辑图标/名称/段位选项）

4. 审核提现申请（手动打款后改状态为"已打款"）

5. 处理争议订单（强制结单 / 强制退款）