394 lines
8.1 KiB
Markdown
394 lines
8.1 KiB
Markdown
# 预约管理系统 (Appointment Management System)
|
||
|
||
基于 Go 语言开发的现代化预约管理系统，采用 Fiber 框架和 MySQL 数据库，支持用户预约、时间管理、权限控制等功能。
|
||
|
||
## 🚀 项目特性
|
||
|
||
- **RESTful API 设计** - 清晰的接口规范，易于集成
|
||
- **JWT 身份认证** - 安全的用户身份验证机制
|
||
- **多角色权限控制** - 用户和管理员分级权限管理
|
||
- **预约时间管理** - 灵活的时间槽配置和预约控制
|
||
- **Docker 容器化部署** - 支持容器化部署和快速启动
|
||
- **数据库迁移** - 自动化的数据库结构管理
|
||
|
||
## 🏗️ 技术架构
|
||
|
||
### 核心技术栈
|
||
- **后端框架**: [Fiber v2](https://gofiber.io/) - 高性能 Go Web 框架
|
||
- **数据库**: MySQL 8.0+
|
||
- **ORM**: [GORM](https://gorm.io/) - 强大的 Go ORM 库
|
||
- **认证**: JWT (JSON Web Tokens)
|
||
- **部署**: Docker + Docker Compose
|
||
|
||
### 项目结构
|
||
```
|
||
yuyue/
|
||
├── config/ # 配置管理
|
||
│ └── config.go # 环境配置加载
|
||
├── database/ # 数据库连接
|
||
│ └── database.go # 数据库初始化
|
||
├── handlers/ # API 处理器
|
||
│ ├── auth.go # 认证相关接口
|
||
│ ├── appointment.go # 预约管理接口
|
||
│ └── timeslot.go # 时间槽管理接口
|
||
├── middleware/ # 中间件
|
||
│ ├── auth.go # 认证中间件
|
||
│ └── jwt.go # JWT 工具函数
|
||
├── models/ # 数据模型
|
||
│ └── models.go # 数据库模型定义
|
||
├── utils/ # 工具函数
|
||
│ ├── response.go # 统一响应格式
|
||
│ └── timeslot_generator.go # 时间槽生成工具
|
||
├── Dockerfile # Docker 构建文件
|
||
├── go.mod # Go 模块依赖
|
||
└── main.go # 应用入口
|
||
```
|
||
|
||
## 🔧 环境要求
|
||
|
||
- Go 1.25+
|
||
- MySQL 8.0+
|
||
- Docker (可选，用于容器化部署)
|
||
|
||
## 📦 快速开始
|
||
|
||
### 1. 克隆项目
|
||
```bash
|
||
git clone <repository-url>
|
||
cd yuyue
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
复制 `.env.example` 为 `.env` 并修改配置：
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env` 文件：
|
||
```env
|
||
# 数据库配置
|
||
DB_HOST=localhost
|
||
DB_PORT=3306
|
||
DB_USER=root
|
||
DB_PASSWORD=your_password
|
||
DB_NAME=appointment_db
|
||
|
||
# JWT 密钥 (生产环境请修改)
|
||
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
|
||
|
||
# 服务器端口
|
||
SERVER_PORT=6555
|
||
```
|
||
|
||
### 3. 数据库准备
|
||
创建数据库：
|
||
```sql
|
||
CREATE DATABASE appointment_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||
```
|
||
|
||
### 4. 运行应用
|
||
|
||
#### 方式一：直接运行
|
||
```bash
|
||
# 安装依赖
|
||
go mod tidy
|
||
|
||
# 运行应用
|
||
go run main.go
|
||
```
|
||
|
||
#### 方式二：编译运行
|
||
```bash
|
||
# 编译
|
||
go build -o appointment.exe .
|
||
|
||
# 运行
|
||
./appointment.exe
|
||
```
|
||
|
||
#### 方式三：Docker 运行
|
||
```bash
|
||
# 构建镜像
|
||
docker build -t appointment-system .
|
||
|
||
# 运行容器
|
||
docker run -p 6555:6555 appointment-system
|
||
```
|
||
|
||
## 📚 API 接口文档
|
||
|
||
### 认证相关接口
|
||
|
||
#### 用户注册
|
||
```http
|
||
POST /api/auth/register
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"phone": "+8613800138000",
|
||
"nickname": "张三"
|
||
}
|
||
```
|
||
|
||
#### 发送验证码
|
||
```http
|
||
POST /api/auth/send-code
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"phone": "+8613800138000"
|
||
}
|
||
```
|
||
|
||
#### 验证码登录
|
||
```http
|
||
POST /api/auth/verification-login
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"phone": "+8613800138000",
|
||
"code": "123456"
|
||
}
|
||
```
|
||
|
||
#### 一键登录
|
||
```http
|
||
POST /api/auth/one-click-login
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"phone": "+8613800138000"
|
||
}
|
||
```
|
||
|
||
### 用户管理接口
|
||
|
||
#### 获取用户信息
|
||
```http
|
||
GET /api/users/profile
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
#### 更新用户信息
|
||
```http
|
||
PUT /api/users/profile
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"nickname": "新昵称"
|
||
}
|
||
```
|
||
|
||
### 时间槽管理接口
|
||
|
||
#### 获取时间槽列表
|
||
```http
|
||
GET /api/timeslots
|
||
# 可选参数: ?date=2026-02-10
|
||
```
|
||
|
||
#### 获取单个时间槽
|
||
```http
|
||
GET /api/timeslots/{id}
|
||
```
|
||
|
||
#### 创建时间槽 (管理员)
|
||
```http
|
||
POST /api/admin/timeslots
|
||
Authorization: Bearer <admin_token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"date": "2026-02-15",
|
||
"start_time": "09:00",
|
||
"end_time": "10:00",
|
||
"max_people": 5,
|
||
"is_active": true
|
||
}
|
||
```
|
||
|
||
### 预约管理接口
|
||
|
||
#### 创建预约
|
||
```http
|
||
POST /api/appointments
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"time_slot_id": 1,
|
||
"people_count": 2,
|
||
"notes": "预约备注"
|
||
}
|
||
```
|
||
|
||
#### 获取预约列表
|
||
```http
|
||
GET /api/appointments
|
||
Authorization: Bearer <token>
|
||
# 可选参数: ?status=pending&date=2026-02-10
|
||
```
|
||
|
||
#### 获取单个预约
|
||
```http
|
||
GET /api/appointments/{id}
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
#### 取消预约
|
||
```http
|
||
DELETE /api/appointments/{id}
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
#### 更新预约状态 (管理员)
|
||
```http
|
||
PUT /api/admin/appointments/{id}/status
|
||
Authorization: Bearer <admin_token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"status": "confirmed" // pending, confirmed, cancelled, completed
|
||
}
|
||
```
|
||
|
||
## 🔐 权限说明
|
||
|
||
系统包含两种用户角色：
|
||
|
||
- **普通用户 (user)**: 可以查看时间槽、创建和管理自己的预约
|
||
- **管理员 (admin)**: 拥有所有权限，包括管理时间槽和审核预约
|
||
|
||
## 🛠️ 开发指南
|
||
|
||
### 项目构建
|
||
```bash
|
||
# 构建可执行文件
|
||
go build -o appointment.exe .
|
||
|
||
# 运行测试
|
||
go test -v ./...
|
||
```
|
||
|
||
### 代码规范
|
||
- 使用 `gofmt` 格式化代码
|
||
- 遵循 RESTful API 设计原则
|
||
- 统一的错误处理和响应格式
|
||
|
||
### 数据库迁移
|
||
项目使用 GORM 的 AutoMigrate 功能自动创建和更新数据库表结构。
|
||
|
||
## 🐳 Docker 部署
|
||
|
||
### 构建镜像
|
||
```bash
|
||
docker build -t appointment-system .
|
||
```
|
||
|
||
### 运行容器
|
||
```bash
|
||
docker run -d \
|
||
--name appointment-app \
|
||
-p 6555:6555 \
|
||
-e DB_HOST=your_db_host \
|
||
-e DB_PASSWORD=your_db_password \
|
||
appointment-system
|
||
```
|
||
|
||
### Docker Compose (推荐)
|
||
```yaml
|
||
version: '3.8'
|
||
services:
|
||
app:
|
||
build: .
|
||
ports:
|
||
- "6555:6555"
|
||
environment:
|
||
- DB_HOST=db
|
||
- DB_PASSWORD=your_password
|
||
depends_on:
|
||
- db
|
||
|
||
db:
|
||
image: mysql:8.0
|
||
environment:
|
||
MYSQL_ROOT_PASSWORD: your_password
|
||
MYSQL_DATABASE: appointment_db
|
||
volumes:
|
||
- mysql_data:/var/lib/mysql
|
||
|
||
volumes:
|
||
mysql_data:
|
||
```
|
||
|
||
## 📊 数据模型
|
||
|
||
### 用户表 (users)
|
||
```go
|
||
type User struct {
|
||
ID uint `gorm:"primaryKey"`
|
||
Phone string `gorm:"size:20;uniqueIndex"`
|
||
Nickname string `gorm:"size:100"`
|
||
Role string `gorm:"size:20;default:user"` // user, admin
|
||
CreatedAt time.Time
|
||
UpdatedAt time.Time
|
||
}
|
||
```
|
||
|
||
### 时间槽表 (time_slots)
|
||
```go
|
||
type TimeSlot struct {
|
||
ID uint `gorm:"primaryKey"`
|
||
Date time.Time `gorm:"not null;index"`
|
||
StartTime time.Time `gorm:"not null"`
|
||
EndTime time.Time `gorm:"not null"`
|
||
MaxPeople int `gorm:"not null;default:1"`
|
||
CurrentPeople int `gorm:"not null;default:0"`
|
||
IsActive bool `gorm:"default:true"`
|
||
CreatedAt time.Time
|
||
UpdatedAt time.Time
|
||
}
|
||
```
|
||
|
||
### 预约表 (appointments)
|
||
```go
|
||
type Appointment struct {
|
||
ID uint `gorm:"primaryKey"`
|
||
UserID uint `gorm:"not null"`
|
||
TimeSlotID uint `gorm:"not null"`
|
||
PeopleCount int `gorm:"not null;default:1"`
|
||
Status string `gorm:"size:20;default:pending"` // pending, confirmed, cancelled, completed
|
||
Notes string `gorm:"size:500"`
|
||
CreatedAt time.Time
|
||
UpdatedAt time.Time
|
||
}
|
||
```
|
||
|
||
## 🤝 贡献指南
|
||
|
||
欢迎提交 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](LICENSE) 文件了解详情。
|
||
|
||
## 📞 联系方式
|
||
|
||
如有问题或建议，请通过以下方式联系：
|
||
|
||
- 提交 Issue
|
||
- 发送邮件至: [your-email@example.com]
|
||
|
||
## 🙏 致谢
|
||
|
||
感谢以下开源项目的支持：
|
||
- [Fiber](https://gofiber.io/)
|
||
- [GORM](https://gorm.io/)
|
||
- [JWT](https://github.com/golang-jwt/jwt) |