# softwareProject

**Repository Path**: tmkbk/software-project

## Basic Information

- **Project Name**: softwareProject
- **Description**: 软件工程作业，使用nodejs后端，图书馆包间管理系统
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-03-19
- **Last Updated**: 2025-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: MySQL, Redis, WebSocket, Express, JWT

## README

# 图书馆包间预约系统开发文档

## 项目概述

本项目是一个基于 Node.js + Express + TypeScript 开发的图书馆包间预约系统，提供用户管理、包间管理、座位预约等功能。系统采用 JWT 进行身份认证，使用 Redis 实现令牌黑名单和离线消息存储，并支持 WebSocket 实时通知功能。系统支持管理员批量导入用户、审批预约请求，以及用户自助预约包间座位等功能。

## 技术架构

### 核心技术栈

- **后端框架**：Express.js + TypeScript
- **数据库**：MySQL + Sequelize ORM
- **身份认证**：JWT (JSON Web Token)
- **缓存系统**：Redis
- **实时通信**：WebSocket
- **文件处理**：xlsx（Excel文件处理）
- **密码加密**：bcrypt
- **中文拼音**：pinyin

### 项目结构

```
├── src/
│   ├── config/          # 配置文件
│   │   ├── database.ts  # 数据库配置
│   │   └── redis.ts     # Redis配置
│   ├── controllers/     # 控制器
│   │   ├── userController.ts    # 用户控制器
│   │   ├── roomController.ts    # 包间控制器
│   │   └── notificationController.ts # 通知控制器
│   ├── middleware/      # 中间件
│   │   ├── auth.ts      # 认证中间件
│   │   ├── logger.ts    # 日志中间件
│   │   └── validation.ts # 验证中间件
│   ├── models/          # 数据模型
│   │   ├── user.ts      # 用户模型
│   │   ├── room.ts      # 包间模型
│   │   ├── seat.ts      # 座位模型
│   │   ├── reservation.ts # 预约模型
│   │   └── notification.ts # 通知模型
│   ├── routes/          # 路由定义
│   │   ├── user.ts      # 用户路由
│   │   ├── room.ts      # 包间路由
│   │   └── notification.ts # 通知路由
│   ├── services/        # 服务
│   │   ├── websocket.ts # WebSocket服务
│   │   └── notificationService.ts # 通知服务
│   └── app.ts           # 应用入口
├── logs/                # 日志文件
├── public/              # 公共资源
└── package.json         # 项目依赖
```

## 系统完整性评估与建议

### 已完成功能
1. 完整的用户认证与授权系统
2. 包间和楼层管理功能
3. 预约系统核心逻辑
4. WebSocket实时通知
5. 管理员后台功能

### 待完善功能
1. 预约冲突检测需要增强
2. 预约时间规则需要更灵活配置
3. 缺少预约历史统计功能
4. 系统监控和日志分析功能
5. 前端界面需要优化用户体验

### 改进建议
1. 增加预约规则配置界面
2. 添加系统使用统计报表
3. 优化WebSocket重连机制
4. 增加系统性能监控
5. 完善单元测试覆盖率

## 功能特性

### 用户管理

- 用户登录与注销
- 用户信息管理
- 密码修改
- 管理员批量导入用户

### 包间管理

- 包间创建、修改、删除
- 包间状态管理（可用、维护中）
- 座位管理（创建、修改座位状态）
- 座位状态实时更新

### 预约系统

- 用户预约包间座位
- 预约时间冲突检测
- 预约时间限制（8:00-22:00）
- 预约日期限制（当天和后两天）
- 周四下午闭馆时间限制
- 管理员审批预约
- 预约状态管理（待审批、已批准、已拒绝、已取消）

### 实时通知

- 基于WebSocket的实时通知系统
- 预约请求通知管理员
- 审批结果通知用户
- 离线消息存储与推送

## 数据库设计

### 核心数据模型

1. **用户表(Users)**
   - id: 主键
   - studentId: 学号
   - name: 姓名
   - password: 加密密码
   - isAdmin: 是否管理员
   - createdAt: 创建时间
   - updatedAt: 更新时间

2. **楼层表(Floors)**
   - id: 主键
   - floorNumber: 楼层号
   - description: 描述

3. **包间表(Rooms)**
   - id: 主键
   - roomNumber: 包间号
   - floorId: 所属楼层外键
   - description: 描述
   - status: 状态(available/maintenance)

4. **预约表(Reservations)**
   - id: 主键
   - userId: 用户外键
   - roomId: 包间外键
   - startTime: 开始时间
   - endTime: 结束时间
   - status: 状态(pending/approved/rejected/canceled)
   - reason: 预约原因

5. **通知表(Notifications)**
   - id: 主键
   - userId: 接收用户外键
   - content: 内容
   - isRead: 是否已读
   - type: 通知类型

## API 接口文档

### 用户管理接口

#### 1. 用户登录

- **接口**：`POST /api/users/login`
- **描述**：用户登录接口
- **请求参数**：
  ```json
  {
    "studentId": "string",
    "password": "string"
  }
  ```
- **响应示例**：
  ```json
  {
    "success": true,
    "data": {
      "studentId": "string",
      "name": "string",
      "isAdmin": boolean,
      "token": "string"
    }
  }
  ```

#### 2. 创建用户（管理员）

- **接口**：`POST /api/users`
- **描述**：创建新用户（需要管理员权限）
- **请求参数**：
  ```json
  {
    "studentId": "string",
    "name": "string"
  }
  ```
- **响应示例**：
  ```json
  {
    "success": true,
    "data": {
      "studentId": "string",
      "name": "string",
      "isAdmin": false,
      "initialPassword": "string"
    }
  }
  ```

#### 3. 批量导入用户（管理员）

- **接口**：`POST /api/users/import`
- **描述**：通过Excel文件批量导入用户
- **请求**：multipart/form-data
- **响应示例**：
  ```json
  {
    "success": true,
    "data": {
      "successCount": number,
      "errorCount": number,
      "results": array,
      "errors": array
    }
  }
  ```

### 包间管理接口

#### 1. 创建包间
- **接口**：`POST /api/rooms/createRoom`
- **描述**：创建新包间(需要管理员权限)
- **请求参数**：
  ```json
  {
    "roomNumber": "string",
    "floorId": number,
    "description": "string",
    "capacity": number
  }
  ```
- **响应示例**：
  ```json
  {
    "success": true,
    "data": {
      "id": number,
      "roomNumber": "string",
      "floorId": number,
      "description": "string",
      "capacity": number,
      "status": "available"
    }
  }
  ```

#### 2. 获取所有包间
- **接口**：`GET /api/rooms/getAllRooms`
- **描述**：获取所有包间信息(支持分页)
- **查询参数**：
  - page: 页码
  - pageSize: 每页数量
- **响应示例**：
  ```json
  {
    "success": true,
    "data": {
      "total": number,
      "items": [
        {
          "id": number,
          "roomNumber": "string",
          "floor": {
            "id": number,
            "floorNumber": "string"
          },
          "description": "string",
          "capacity": number,
          "status": "string"
        }
      ]
    }
  }
  ```

- **接口**：`POST /api/rooms`
- **描述**：创建新包间（需要管理员权限）
- **请求参数**：
  ```json
  {
    "roomNumber": "string",
    "description": "string",
    "defaultSeats": number
  }
  ```
- **响应示例**：
  ```json
  {
    "success": true,
    "data": {
      "id": number,
      "roomNumber": "string",
      "description": "string",
      "status": "available",
      "seats": [{
        "id": number,
        "seatNumber": number,
        "status": "available"
      }]
    }
  }
  ```

#### 2. 获取所有包间

- **接口**：`GET /api/rooms`
- **描述**：获取所有包间信息（支持分页、搜索和排序）
- **查询参数**：
  - page: 页码
  - pageSize: 每页数量
  - search: 搜索关键词
  - status: 包间状态
  - sortBy: 排序字段
  - order: 排序方向
- **响应示例**：
  ```json
  {
    "success": true,
    "data": {
      "rooms": [{
        "id": number,
        "roomNumber": "string",
        "description": "string",
        "status": "string",
        "seats": array,
        "availableSeats": number
      }],
      "pagination": {
        "total": number,
        "currentPage": number,
        "totalPages": number,
        "pageSize": number
      }
    }
  }
  ```

### 预约管理接口

#### 1. 创建预约

- **接口**：`POST /api/reservations`
- **描述**：创建座位预约
- **请求参数**：
  ```json
  {
    "roomId": number,
    "seatId": number,
    "startTime": "datetime",
    "endTime": "datetime",
    "purpose": "string"
  }
  ```
- **响应示例**：
  ```json
  {
    "success": true,
    "data": {
      "id": number,
      "studentId": "string",
      "roomId": number,
      "seatId": number,
      "startTime": "datetime",
      "endTime": "datetime",
      "purpose": "string",
      "status": "pending"
    }
  }
  ```

#### 2. 审批预约

- **接口**：`PUT /api/reservations/:id/approve`
- **描述**：审批预约请求（需要管理员权限）
- **请求参数**：
  ```json
  {
    "status": "approved" | "rejected",
    "rejectReason": "string"
  }
  ```
- **响应示例**：
  ```json
  {
    "success": true,
    "data": {
      "id": number,
      "studentId": "string",
      "roomId": number,
      "seatId": number,
      "startTime": "datetime",
      "endTime": "datetime",
      "purpose": "string",
      "status": "string",
      "rejectReason": "string"
    }
  }
  ```

#### 3. 取消预约

- **接口**：`PUT /api/reservations/:id/cancel`
- **描述**：取消预约（用户或管理员）
- **响应示例**：
  ```json
  {
    "success": true,
    "message": "预约已取消"
  }
  ```

## 数据库设计

### User 表

| 字段名    | 类型    | 描述     | 约束           |
|-----------|---------|----------|----------------|
| studentId | STRING  | 学号     | 主键           |
| name      | STRING  | 姓名     | 非空           |
| password  | STRING  | 密码     | 非空           |
| isAdmin   | BOOLEAN | 管理权限 | 默认false      |
| createdAt | DATE    | 创建时间 | 自动生成       |
| updatedAt | DATE    | 更新时间 | 自动生成       |

### Room 表

| 字段名      | 类型    | 描述       | 约束                                    |
|-------------|---------|------------|----------------------------------------|
| id          | INTEGER | 包间ID     | 主键，自增                             |
| roomNumber  | STRING  | 包间编号   | 非空，唯一                             |
| status      | ENUM    | 包间状态   | 非空，可选值：available/maintenance    |
| description | STRING  | 包间描述   | 可空                                   |
| createdAt   | DATE    | 创建时间   | 自动生成                               |
| updatedAt   | DATE    | 更新时间   | 自动生成                               |

### Seat 表

| 字段名      | 类型    | 描述       | 约束                                    |
|-------------|---------|------------|----------------------------------------|
| id          | INTEGER | 座位ID     | 主键，自增                             |
| roomId      | INTEGER | 包间ID     | 非空，外键关联Room表                    |
| seatNumber  | INTEGER | 座位编号   | 非空                                   |
| status      | ENUM    | 座位状态   | 非空，可选值：available/occupied/maintenance |
| createdAt   | DATE    | 创建时间   | 自动生成                               |
| updatedAt   | DATE    | 更新时间   | 自动生成                               |

### Reservation 表

| 字段名       | 类型    | 描述       | 约束                                       |
|--------------|---------|------------|-------------------------------------------|
| id           | INTEGER | 预约ID     | 主键，自增                                |
| studentId    | STRING  | 学生ID     | 非空，外键关联User表                       |
| roomId       | INTEGER | 包间ID     | 非空，外键关联Room表                       |
| seatId       | INTEGER | 座位ID     | 非空，外键关联Seat表                       |
| startTime    | DATE    | 开始时间   | 非空                                      |
| endTime      | DATE    | 结束时间   | 非空                                      |
| status       | ENUM    | 预约状态   | 非空，可选值：pending/approved/rejected/cancelled |
| purpose      | STRING  | 预约用途   | 非空                                      |
| rejectReason | STRING  | 拒绝原因   | 可空                                      |
| createdAt    | DATE    | 创建时间   | 自动生成                                  |
| updatedAt    | DATE    | 更新时间   | 自动生成                                  |

### Notification 表

| 字段名    | 类型    | 描述       | 约束                                    |
|-----------|---------|------------|----------------------------------------|
| id        | INTEGER | 通知ID     | 主键，自增                             |
| userId    | STRING  | 用户ID     | 非空，外键关联User表                    |
| type      | ENUM    | 通知类型   | 非空，可选值：reservation/approval/system |
| message   | STRING  | 通知内容   | 非空                                   |
| isRead    | BOOLEAN | 是否已读   | 非空，默认false                        |
| createdAt | DATE    | 创建时间   | 自动生成                               |
| updatedAt | DATE    | 更新时间   | 自动生成                               |

## 实时通知系统

系统使用WebSocket实现实时通知功能，主要特性包括：

- 用户预约座位后，系统自动通知管理员进行审批
- 管理员审批预约后，系统自动通知用户审批结果
- 支持离线消息存储，用户上线后自动推送未读消息
- 使用Redis存储离线消息，确保消息不丢失
- 支持管理员广播通知功能

## 安全机制

### 密码处理

- 使用 bcrypt 进行密码加密存储
- 初始密码生成规则：姓氏拼音首字母（大写）+ 名字拼音（小写）+ @ + 学号

### 身份认证

- 使用 JWT 进行身份验证
- Token 有效期为 24 小时
- 使用 Redis 实现令牌黑名单，支持令牌失效

## 部署说明

### 环境要求

- **Node.js**: v14.0 或以上
- **MySQL**: v8.0 或以上
- **Redis**: v6.0 或以上

### 安装步骤

1. 克隆项目代码
2. 安装依赖：`npm install`
3. 配置环境变量：复制 `.env.example` 为 `.env` 并填写配置
4. 初始化数据库：运行数据库迁移脚本
5. 启动服务：`npm run dev`（开发环境）或 `npm run start`（生产环境）

### 环境变量配置

```env
PORT=3000
DB_HOST=localhost
DB_PORT=3306
DB_NAME=library_reservation
DB_USER=root
DB_PASSWORD=your_password
REDIS_HOST=localhost
REDIS_PORT=6379
JWT_SECRET=your_jwt_secret
```

## 使用说明

### 管理员功能

1. 用户管理
   - 批量导入用户：使用提供的Excel模板
   - 重置用户密码
   - 管理用户权限

2. 包间管理
   - 创建新包间并设置座位数量
   - 修改包间状态（可用/维护中）
   - 查看包间使用情况

3. 预约管理
   - 审批预约申请
   - 查看预约历史
   - 取消预约

### 用户功能

1. 账户管理
   - 修改个人信息
   - 修改密码
   - 查看通知

2. 预约功能
   - 查看包间和座位状态
   - 预约座位
   - 取消预约
   - 查看预约历史