lingxiao/go-yu

Fork 0

Files

lingxiao865 13d1175057 13

2026-02-10 09:30:37 +08:00

8.1 KiB

Raw Permalink Blame History

预约管理系统 (Appointment Management System)

基于 Go 语言开发的现代化预约管理系统，采用 Fiber 框架和 MySQL 数据库，支持用户预约、时间管理、权限控制等功能。

🚀 项目特性

RESTful API 设计 - 清晰的接口规范，易于集成
JWT 身份认证 - 安全的用户身份验证机制
多角色权限控制 - 用户和管理员分级权限管理
预约时间管理 - 灵活的时间槽配置和预约控制
Docker 容器化部署 - 支持容器化部署和快速启动
数据库迁移 - 自动化的数据库结构管理

🏗️ 技术架构

核心技术栈

后端框架: Fiber v2 - 高性能 Go Web 框架
数据库: MySQL 8.0+
ORM: GORM - 强大的 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. 克隆项目

git clone <repository-url>
cd yuyue

2. 配置环境变量

复制 .env.example 为 .env 并修改配置：

cp .env.example .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. 数据库准备

创建数据库：

CREATE DATABASE appointment_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

4. 运行应用

方式一：直接运行

# 安装依赖
go mod tidy

# 运行应用
go run main.go

方式二：编译运行

# 编译
go build -o appointment.exe .

# 运行
./appointment.exe

方式三：Docker 运行

# 构建镜像
docker build -t appointment-system .

# 运行容器
docker run -p 6555:6555 appointment-system

📚 API 接口文档

认证相关接口

用户注册

POST /api/auth/register
Content-Type: application/json

{
  "phone": "+8613800138000",
  "nickname": "张三"
}

发送验证码

POST /api/auth/send-code
Content-Type: application/json

{
  "phone": "+8613800138000"
}

验证码登录

POST /api/auth/verification-login
Content-Type: application/json

{
  "phone": "+8613800138000",
  "code": "123456"
}

一键登录

POST /api/auth/one-click-login
Content-Type: application/json

{
  "phone": "+8613800138000"
}

用户管理接口

获取用户信息

GET /api/users/profile
Authorization: Bearer <token>

更新用户信息

PUT /api/users/profile
Authorization: Bearer <token>
Content-Type: application/json

{
  "nickname": "新昵称"
}

时间槽管理接口

获取时间槽列表

GET /api/timeslots
# 可选参数: ?date=2026-02-10

获取单个时间槽

GET /api/timeslots/{id}

创建时间槽 (管理员)

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
}

预约管理接口

创建预约

POST /api/appointments
Authorization: Bearer <token>
Content-Type: application/json

{
  "time_slot_id": 1,
  "people_count": 2,
  "notes": "预约备注"
}

获取预约列表

GET /api/appointments
Authorization: Bearer <token>
# 可选参数: ?status=pending&date=2026-02-10

获取单个预约

GET /api/appointments/{id}
Authorization: Bearer <token>

取消预约

DELETE /api/appointments/{id}
Authorization: Bearer <token>

更新预约状态 (管理员)

PUT /api/admin/appointments/{id}/status
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "status": "confirmed"  // pending, confirmed, cancelled, completed
}

🔐 权限说明

系统包含两种用户角色：

普通用户 (user): 可以查看时间槽、创建和管理自己的预约
管理员 (admin): 拥有所有权限，包括管理时间槽和审核预约

🛠️ 开发指南

项目构建

# 构建可执行文件
go build -o appointment.exe .

# 运行测试
go test -v ./...

代码规范

使用 gofmt 格式化代码
遵循 RESTful API 设计原则
统一的错误处理和响应格式

数据库迁移

项目使用 GORM 的 AutoMigrate 功能自动创建和更新数据库表结构。

🐳 Docker 部署

构建镜像

docker build -t appointment-system .

运行容器

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 (推荐)

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)

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)

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)

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！

Fork 项目
创建功能分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

📝 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

📞 联系方式

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

提交 Issue
发送邮件至: [your-email@example.com]

🙏 致谢

感谢以下开源项目的支持：

8.1 KiB Raw Permalink Blame History Unescape Escape