# 金溪棋牌 - Webman 后端

基于 [Webman](https://www.workerman.net/doc/webman/) 的高性能 PHP HTTP 服务，对接 uni-app 客户端。

## 环境要求

- PHP >= 7.2（推荐 8.0+）
- MySQL 8.0+
- 扩展：pdo_mysql、json、mbstring

Windows 需安装 `composer` 并启用相应 PHP 扩展。

## 快速开始

### 1. 安装依赖

```bash
cd backend
composer install
```

### 2. 配置环境

```bash
copy .env.example .env
```

编辑 `.env` 填写数据库账号。

### 3. 初始化数据库

```bash
mysql -u root -p < database/schema.sql
```

### 4. 启动服务

**Windows：**

```bash
php windows.php
```

**Linux / macOS：**

```bash
php start.php start
```

默认地址：`http://127.0.0.1:8787`（HTTP API）  
WebSocket：`ws://127.0.0.1:9501`  
Channel：`127.0.0.1:2206`（进程间推送，无需对外暴露）

### 5. 客户端联调

修改 `client/utils/constants.js`：

```js
export const API_BASE_URL = 'http://127.0.0.1:8787/api'
```

## 演示登录

`.env` 中 `SMS_MOCK=true` 时，验证码固定为 **123456**。

```
POST /api/auth/sms/send   {"phone":"13800138000"}
POST /api/auth/login      {"phone":"13800138000","code":"123456"}
```

## 目录结构

```
backend/
├── app/
│   ├── controller/     # 控制器
│   ├── service/        # 业务逻辑
│   ├── middleware/     # 中间件（CORS、JWT）
│   ├── support/        # Database / Jwt / Cache
│   └── functions.php   # 公共函数
├── config/
│   ├── route.php       # API 路由
│   └── middleware.php
├── database/schema.sql
├── start.php           # Linux 启动
└── windows.php         # Windows 启动
```

## API 路由

| 方法 | 路径 | 鉴权 |
|------|------|------|
| POST | /api/auth/sms/send | 否 |
| POST | /api/auth/login | 否 |
| POST | /api/auth/logout | 是 |
| GET | /api/user/profile | 是 |
| POST | /api/group/create | 是 |
| POST | /api/group/join | 是 |
| GET | /api/group/list | 是 |
| GET | /api/group/{id} | 是 |
| POST | /api/room/create | 是 |
| GET | /api/room/list | 是 |
| POST | /api/room/{id}/join | 是 |
| POST | /api/room/{id}/ready | 是 |
| POST | /api/room/{id}/start | 是 |
| GET | /api/score/member | 是 |
| GET | /api/alliance/info | 是 |

## 核心业务

- 群积分 `< 0` → 群状态禁玩，不可开房/进房
- 入房门槛校验成员积分
- 联盟淘汰分（默认 -300）以下不可游戏

## WebSocket 实时推送

| 进程 | 端口 | 说明 |
|------|------|------|
| webman | 8787 | HTTP API |
| channel | 2206 | 进程间推送（内部） |
| websocket | 9501 | 客户端 WS |

**客户端 → 服务端：** `join_lobby` / `leave_lobby` / `join_room` / `leave_room` / `ping`

**服务端 → 客户端：** `room_update`（大厅） / `room_detail`（等待房） / `game_start`

连接：`ws://127.0.0.1:9501?token=JWT`

## 下一步

- 游戏内出牌同步（game_action）
- 游戏结算写积分

---

## 后台管理 Admin

访问：`http://127.0.0.1:8787/admin`

默认账号：**admin / admin123**（部署后请修改）

### 功能

- 用户列表搜索（手机号 / 昵称 / ID）
- **设置好牌率**（0-100，用户端不可见，游戏发牌逻辑调用 `UserService::getGoodCardRate()`）
- **群房卡**：每个群有房卡余额；开局按玩法+局数扣卡
- **联盟房费**：后台「房卡与房费」配置；整场结束后从总获利最高的群扣群积分；群积分低于淘汰分禁玩
- **手动调积分**：群监控 →「调成员分」/「调群积分」；群主客户端可调成员积分
- **联盟管理**：创建/编辑/解散联盟，配置四种玩法底分与入房门槛、淘汰分、积分缩减规则
- **入盟审核**：群主申请加入联盟，后台通过/拒绝
- **修改密码**：右上角「修改密码」，需验证原密码
- **数据统计**：用户/群/房间/对局概览，近 7/14/30 日趋势，玩法分布与活跃群排行
- **群房监控**：群列表（积分、禁玩状态）、房间列表（状态筛选、座位详情、非游戏中可强制关闭）
- **手动调积分**：群监控 →「调成员分」加减成员积分；「调群积分」独立加减群积分（流水仅后台可见）；群主客户端可调成员积分，个人中心可看成员积分变动；群主个人中心显示群积分（不显示群积分操作记录）
- **一人一群**：每个用户同时只能加入一个群，需先退出当前群才能加入/创建其它群（群主不可退出）
- **报表导出**：用户/群/房间/积分流水/对局/概览 CSV，支持日期与群 ID 筛选

### 数据库迁移

```bash
mysql -u root -p jinxi_majiang < database/migrations/002_admin_good_card_rate.sql
mysql -u root -p jinxi_majiang < database/migrations/003_alliance_applications.sql
mysql -u root -p jinxi_majiang < database/migrations/004_group_room_cards.sql
mysql -u root -p jinxi_majiang < database/migrations/005_one_group_and_score_ops.sql
mysql -u root -p jinxi_majiang < database/migrations/006_group_score_independent.sql
mysql -u root -p jinxi_majiang < database/migrations/007_alliance_room_fees.sql
mysql -u root -p jinxi_majiang < database/migrations/008_alliance_rooms.sql
```