241 lines
6.9 KiB
Markdown
241 lines
6.9 KiB
Markdown
# 羽动俱乐部 - 羽毛球/网球俱乐部管理系统
|
||
|
||
一个完整的羽毛球/网球俱乐部会员管理系统，包含微信小程序端和后台管理界面。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
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
|