# swimming-system

**Repository Path**: wyyft/swimming-system

## Basic Information

- **Project Name**: swimming-system
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-16
- **Last Updated**: 2026-03-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🏊 游泳馆预约排课系统

> 游泳馆智能管理平台 - 预约、排课、会员管理一体化解决方案

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-green.svg)](https://nodejs.org/)
[![Vue](https://img.shields.io/badge/vue-3.3+-green.svg)](https://vuejs.org/)

## 📖 项目简介

本系统是一套完整的游泳馆管理平台，包含后台管理系统和会员端 H5 应用。支持课程排期、在线预约、会员管理、教练管理、课时核销等核心功能，帮助游泳馆实现数字化运营。

### 核心功能

- 📅 **智能排课** - 支持批量排课、日历视图、冲突检测
- 📱 **在线预约** - 会员端 H5 预约、取消、查看预约记录
- 👥 **会员管理** - 会员信息、课时管理、消费记录
- 👨‍🏫 **教练管理** - 教练信息、课程安排
- 🏊 **泳道管理** - 泳道配置、使用状态
- ✅ **签到核销** - 预约签到、课时核销
- 💬 **微信通知** - 预约成功、上课提醒等模板消息推送

## 🏗️ 项目结构

```
swimming-system/
├── backend/              # 后端 API (Node.js + Express + Sequelize)
│   ├── src/
│   │   ├── config/       # 数据库配置
│   │   ├── models/       # Sequelize 数据模型
│   │   ├── routes/       # API 路由
│   │   ├── services/     # 业务逻辑服务
│   │   ├── middleware/   # 认证、日志中间件
│   │   └── app.js        # 应用入口
│   ├── scripts/          # 数据库初始化脚本
│   ├── .env.example      # 环境变量模板
│   └── package.json
├── admin/                # 后台管理系统 (Vue3 + Element Plus)
│   ├── src/
│   │   ├── api/          # API 接口
│   │   ├── layouts/      # 布局组件
│   │   ├── router/       # 路由配置
│   │   ├── store/        # 状态管理 (Pinia)
│   │   ├── views/        # 页面组件
│   │   ├── App.vue
│   │   └── main.js
│   ├── dist/             # 构建输出
│   └── package.json
├── h5/                   # 会员端 H5 (Vue3 + Vant)
│   ├── src/
│   │   ├── api/          # API 接口
│   │   ├── router/       # 路由配置
│   │   ├── views/        # 页面组件
│   │   ├── App.vue
│   │   └── main.js
│   └── package.json
├── docker/               # Docker 部署配置
│   ├── docker-compose.yml
│   └── nginx.conf
├── scripts/              # 工具脚本
│   └── test-api.sh       # API 测试脚本
├── start.sh              # 快速启动脚本
└── README.md
```

## 🛠️ 技术栈

### 后端

| 技术 | 版本 | 说明 |
|------|------|------|
| Node.js | >=18.0.0 | 运行环境 |
| Express | 4.18+ | Web 框架 |
| Sequelize | 6.35+ | ORM 框架 |
| SQLite3 | 5.1+ | 数据库 (可切换 MySQL) |
| JWT | 9.0+ | 身份认证 |
| Winston | 3.11+ | 日志记录 |

### 后台前端

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.3+ | 前端框架 |
| Vite | 5.0+ | 构建工具 |
| Element Plus | 2.5+ | UI 组件库 |
| Vue Router | 4.2+ | 路由管理 |
| Pinia | 2.1+ | 状态管理 |
| Axios | 1.6+ | HTTP 客户端 |
| Day.js | 1.11+ | 日期处理 |

### 会员端 H5

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.3+ | 前端框架 |
| Vite | 5.0+ | 构建工具 |
| Vant | 4.8+ | 移动端 UI 组件库 |
| Vue Router | 4.2+ | 路由管理 |
| Pinia | 2.1+ | 状态管理 |
| Axios | 1.6+ | HTTP 客户端 |

## 🚀 快速开始

### 方式一：本地开发

#### 1. 克隆项目

```bash
git clone https://gitee.com/wyyft/swimming-system.git
cd swimming-system
```

#### 2. 启动后端

```bash
cd backend

# 安装依赖
npm install

# 复制环境变量
cp .env.example .env

# 启动服务
npm run dev
# API 运行在 http://localhost:3000
```

#### 3. 启动后台管理系统

```bash
cd admin

# 安装依赖
npm install

# 启动开发服务器
npm run dev
# 访问 http://localhost:5173
```

#### 4. 启动会员端 H5

```bash
cd h5

# 安装依赖
npm install

# 启动开发服务器
npm run dev
# 访问 http://localhost:5174
```

### 方式二：Docker 部署（生产环境推荐）

```bash
# 1. 进入 docker 目录
cd docker

# 2. 启动所有服务
docker-compose up -d

# 3. 查看日志
docker-compose logs -f

# 4. 访问
# 后台管理：http://localhost/admin
# 会员端 H5: http://localhost/h5
# API: http://localhost/api
```

## 🔐 默认账号

**后台管理：**
- 用户名：`admin`
- 密码：`admin123`

⚠️ **生产环境务必修改默认密码！**

## 📡 API 文档

### 认证模块

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/auth/login` | 管理员登录 |

### 会员管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/members/list` | 会员列表 |
| GET | `/api/members/:id` | 会员详情 |
| POST | `/api/members/create` | 创建会员 |
| PUT | `/api/members/:id` | 更新会员 |
| POST | `/api/members/:id/adjust-classes` | 调整课时 |

### 教练管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/coaches/list` | 教练列表 |
| POST | `/api/coaches/create` | 创建教练 |

### 课程管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/courses/list` | 课程列表 |
| POST | `/api/courses/create` | 创建课程 |

### 泳道管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/lanes/list` | 泳道列表 |
| POST | `/api/lanes/create` | 创建泳道 |

### 排课管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/schedules/list` | 排课列表 |
| GET | `/api/schedules/calendar/:date` | 日历视图 |
| POST | `/api/schedules/create` | 创建排课 |
| POST | `/api/schedules/batch` | 批量排课 |

### 预约管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/bookings/list` | 预约列表 |
| GET | `/api/bookings/my` | 我的预约 |
| POST | `/api/bookings/create` | 创建预约 |
| POST | `/api/bookings/:id/cancel` | 取消预约 |
| POST | `/api/bookings/:id/checkin` | 签到 |
| POST | `/api/bookings/:id/checkout` | 签退 |

### 微信模块

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/wechat/callback` | 微信回调验证 |
| POST | `/api/wechat/callback` | 接收微信消息 |
| POST | `/api/wechat/bind` | 绑定微信 OpenID |

## 🔧 配置说明

### 后端环境变量 (.env)

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

# 数据库配置
DB_PATH=./swimming.db

# JWT 配置
JWT_SECRET=your-secret-key-change-in-production
JWT_EXPIRES_IN=7d

# 微信配置 (可选)
WECHAT_APP_ID=
WECHAT_APP_SECRET=
WECHAT_TOKEN=
WECHAT_ENCODING_AES_KEY=
```

### 微信公众号配置

1. 登录微信公众号后台
2. **开发 → 基本配置**
   - 服务器配置 URL: `https://your-domain.com/wechat/callback`
   - Token: 自定义（需与后端配置一致）
   - EncodingAESKey: 自动生成
3. **功能 → 模板消息 → 添加模板**
   - 预约成功通知
   - 取消通知
   - 上课提醒
   - 核销通知
4. 将模板 ID 填入系统配置

## 📝 开发进度

### 已完成 ✅

- [x] 数据库设计与实现
- [x] 后端 API 框架搭建
- [x] 核心数据模型（Member, Schedule, Booking, Coach, Course, Lane）
- [x] JWT 身份认证
- [x] 后台管理系统（Dashboard、会员、教练、课程、泳道、排课、预约、微信配置）
- [x] 会员端 H5（首页、课程列表、课程详情、预约、我的预约、个人中心）
- [x] 微信消息推送（预约成功、取消通知、上课提醒、核销通知）
- [x] 定时任务（上课提醒、课时预警、清理过期预约）
- [x] 数据统计看板（今日数据、课程安排、到期预警、热门课程）
- [x] Docker 部署配置
- [x] API 测试脚本

### 计划中 📋

- [ ] 会员签到积分系统
- [ ] 课程评价功能
- [ ] 财务报表导出
- [ ] 单元测试与集成测试
- [ ] 移动端小程序版本

## 🧪 测试

### API 测试

```bash
# 运行 API 测试脚本
cd scripts
bash test-api.sh
```

### 单元测试

```bash
cd backend
npm test
```

## 📦 部署

### 生产环境部署

1. **修改配置文件**
   - 后端 `.env` 文件中的 `JWT_SECRET`
   - 数据库连接信息
   - 微信相关配置

2. **构建前端**
   ```bash
   cd admin && npm run build
   cd h5 && npm run build
   ```

3. **使用 Docker 部署**
   ```bash
   cd docker
   docker-compose up -d
   ```

4. **配置 Nginx**
   - 参考 `docker/nginx.conf` 配置反向代理
   - 配置 HTTPS 证书（推荐）

### 安全建议

1. ✅ 修改所有默认密码
2. ✅ JWT_SECRET 使用强随机字符串
3. ✅ 启用 HTTPS
4. ✅ 定期备份数据库
5. ✅ 配置防火墙规则
6. ✅ 限制 API 访问频率

## 🤝 参与贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

## 📄 开源协议

MIT License

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 Issue
- 发送邮件至项目维护者

---

**Made with ❤️ by Swimming System Team**