go-yu/README.md

# 预约管理系统 (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)