lingxiao/go-yu
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

13

Browse Source
This commit is contained in:
lingxiao865
2026-02-10 09:30:37 +08:00
commit 13d1175057
15 changed files with 1728 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

394
README.md Normal file
View File

@@ -0,0 +1,394 @@
# 预约管理系统 (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)