# 羽动俱乐部 - 羽毛球/网球俱乐部管理系统

一个完整的羽毛球/网球俱乐部会员管理系统，包含微信小程序端和后台管理界面。

## 项目结构

```
yingsha/
├── server/          # Node.js 后端服务
├── admin/           # Vue3 后台管理界面
├── miniprogram/     # 微信小程序
└── README.md
```

## 技术栈

- **后端**: Node.js + Express + Sequelize + MySQL + WebSocket
- **管理后台**: Vue 3 + Element Plus + Pinia + Vite
- **小程序**: 原生微信小程序

## 功能特性

### 小程序端

- 用户自动注册，生成唯一会员码
- 天梯排名系统（按战力值排序，区分男女）
- 挑战赛（扫码发起挑战，实时通知）
- 排位赛（单循环赛制，自动匹配，淘汰赛）
- 积分商城（兑换商品，二维码核销）
- 多门店支持

### 后台管理

- 用户管理（超级管理员）
- 门店管理（多门店）
- 天梯用户管理（等级、战力值）
- 比赛管理（挑战赛、排位赛）
- 积分行为管理（扫码加分）
- 积分商品管理
- 兑换订单管理（扫码核销）
- 系统用户管理（权限控制）

## 快速开始

### 1. 后端服务

```bash
cd server

# 安装依赖
npm install

# 配置环境变量
copy env-template.txt .env    # Windows
# cp env-template.txt .env    # Linux/Mac

# 编辑 .env 文件，填入实际配置

# 初始化数据库（首次运行）
npm run db:init

# 启动服务
npm run dev
```

## 环境变量配置

在 `server` 目录下创建 `.env` 文件，配置以下参数：

### 必需配置

| 参数          | 说明                           | 示例                 |
| ------------- | ------------------------------ | -------------------- |
| `DB_PASSWORD` | MySQL 数据库密码               | `your_password`      |
| `JWT_SECRET`  | JWT 签名密钥（建议 32 位以上） | `a1b2c3d4...`        |
| `WX_APPID`    | 微信小程序 AppID               | `wx1234567890abcdef` |
| `WX_SECRET`   | 微信小程序 AppSecret           | `your_secret_key`    |

### 可选配置

| 参数             | 默认值        | 说明                                   |
| ---------------- | ------------- | -------------------------------------- |
| `NODE_ENV`       | `development` | 运行环境：`development` / `production` |
| `PORT`           | `3000`        | 服务端口                               |
| `DB_HOST`        | `localhost`   | 数据库主机                             |
| `DB_PORT`        | `3306`        | 数据库端口                             |
| `DB_NAME`        | `yingsha`     | 数据库名称                             |
| `DB_USER`        | `root`        | 数据库用户名                           |
| `JWT_EXPIRES_IN` | `7d`          | Token 过期时间                         |

### 生成 JWT 密钥

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

### 完整配置示例

```ini
# 服务器配置
NODE_ENV=development
PORT=3000

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=yingsha
DB_USER=root
DB_PASSWORD=your_password

# JWT 配置
JWT_SECRET=your_32_character_secret_key_here
JWT_EXPIRES_IN=7d

# 微信小程序配置
WX_APPID=wx1234567890abcdef
WX_SECRET=your_wechat_secret_key
```

> ⚠️ **安全提示**：`.env` 文件包含敏感信息，请勿提交到版本控制系统

### 2. 后台管理界面

```bash
cd admin

# 安装依赖
npm install

# 配置环境变量（可选，用于地图功能）
copy env-template.txt .env.local    # Windows
# cp env-template.txt .env.local    # Linux/Mac

# 启动开发服务
npm run dev
```

访问 http://localhost:8080，默认账号：`admin` / `admin123`

#### 管理后台环境变量

在 `admin` 目录下创建 `.env.local` 文件（详细模板见 `admin/env-template.txt`）：

| 参数                      | 必需 | 默认值               | 说明                |
| ------------------------- | ---- | -------------------- | ------------------- |
| `VITE_API_URL`            | 否   | `/api`               | 后端 API 地址       |
| `VITE_AMAP_KEY`           | 是\* | 无                   | 高德地图 JS API Key |
| `VITE_AMAP_SECURITY_CODE` | 是\* | 无                   | 高德地图安全密钥    |
| `VITE_APP_TITLE`          | 否   | `羽动俱乐部管理后台` | 应用标题            |

> \*注：如不使用门店地址定位功能，可不配置高德地图相关参数

**完整配置示例：**

```ini
# 后端 API 地址（使用 Vite 代理时保持默认）
VITE_API_URL=/api

# 高德地图配置（用于门店地址定位）
VITE_AMAP_KEY=your_amap_js_api_key
VITE_AMAP_SECURITY_CODE=your_security_code

# 应用标题
VITE_APP_TITLE=羽动俱乐部管理后台
```

#### 高德地图配置说明

门店管理中的地址定位功能需要配置高德地图 JS API：

1. 访问 [高德开放平台](https://console.amap.com/) 注册账号
2. 进入「应用管理」→「我的应用」→「创建新应用」
3. 添加 Key，选择「Web 端(JS API)」
4. 在应用详情页生成「安全密钥」
5. 将 Key 和安全密钥填入 `admin/.env.local`：
   - `VITE_AMAP_KEY` = 你的 Key
   - `VITE_AMAP_SECURITY_CODE` = 你的安全密钥

> 💡 高德地图提供免费配额，个人开发者每日调用量足够使用

### 3. 微信小程序

1. 使用微信开发者工具打开 `miniprogram` 目录
2. 修改 `app.js` 中的 `baseUrl` 为你的后端服务地址
3. 在 `project.config.json` 中填入你的小程序 AppID

## 数据库

使用 MySQL 数据库，首次运行 `npm run db:init` 会自动创建表结构和初始数据。

### 主要数据表

| 表名           | 说明       |
| -------------- | ---------- |
| users          | 小程序用户 |
| stores         | 门店       |
| ladder_users   | 天梯用户   |
| matches        | 比赛       |
| match_games    | 对局       |
| point_actions  | 积分行为   |
| point_products | 积分商品   |
| point_orders   | 兑换订单   |
| system_users   | 后台用户   |

## 战力值计算规则

- 基础胜场分：+15 分
- 基础负场分：-5 分
- 以下克上：分差 ≥100 时，额外+10%分差奖励
- 新手保护：Lv1-2 前 5 场输分减半
- 单场封顶：±50 分
- 比赛权重：日常 x1.0，挑战赛 x1.5，总决赛 x2.0

## 升降级规则

- 月度排位赛冠亚军：晋升
- 月度排位赛末位：降级
- 每月至少 3 场比赛才计入排名

## 等级说明

| 等级 | 名称 | 描述                         |
| ---- | ---- | ---------------------------- |
| Lv1  | 新锐 | 掌握基础动作，能进行多拍回合 |
| Lv2  | 精锐 | 技术较全面，具备初步战术意识 |
| Lv3  | 高手 | 技术稳定，战术意图清晰       |
| Lv4  | 大师 | 俱乐部顶尖战力               |
| Lv5  | 宗师 | 技术全面，俱乐部标杆         |

## 主题配色

- 主色：`#FF6B35` 活力橙
- 辅助色：`#2EC4B6` 清新青
- 强调色：`#FFBA08` 能量黄
- 深色背景：`#1A1A2E`
- 浅色背景：`#F8F9FA`

## 许可证

MIT License