# 预约管理系统 (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 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 ``` #### 更新用户信息 ```http PUT /api/users/profile Authorization: Bearer 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 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 Content-Type: application/json { "time_slot_id": 1, "people_count": 2, "notes": "预约备注" } ``` #### 获取预约列表 ```http GET /api/appointments Authorization: Bearer # 可选参数: ?status=pending&date=2026-02-10 ``` #### 获取单个预约 ```http GET /api/appointments/{id} Authorization: Bearer ``` #### 取消预约 ```http DELETE /api/appointments/{id} Authorization: Bearer ``` #### 更新预约状态 (管理员) ```http PUT /api/admin/appointments/{id}/status Authorization: Bearer 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)