# library-nest

**Repository Path**: FlowerTip/library-nest

## Basic Information

- **Project Name**: library-nest
- **Description**: 这是一个基于 NestJS + TypeORM + MySQL 开发的签到管理系统，包含用户管理、个人信息维护和签到功能。系统采用 JWT 进行身份验证和授权，支持用户注册、登录、个人信息管理、签到记录查询和统计等功能。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-01
- **Last Updated**: 2026-04-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 签到系统 API 文档

## 项目简介

这是一个基于 NestJS + TypeORM + MySQL 开发的签到管理系统，包含用户管理、个人信息维护和签到功能。系统采用 JWT 进行身份验证和授权，支持用户注册、登录、个人信息管理、签到记录查询和统计等功能。

## 技术栈

- **后端框架**: NestJS 11.0
- **数据库ORM**: TypeORM 0.3
- **数据库**: MySQL 8.0+
- **语言**: TypeScript 5.7
- **包管理器**: pnpm

## 环境配置

1. 创建 `.env` 文件：
```env
# 项目启动端口
PORT=3000

# 数据库配置
DB_TYPE=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=123456
DB_NAME=library
DB_LOGGING=true # 是否打印SQL日志

# JWT 配置
JWT_SECRET=your-super-secret-key-change-this-in-production
JWT_EXPIRES_IN=7d

# 图片预览地址
IMG_PREFIX=http://127.0.0.1:3000/uploads
# 图片预览前端前缀
IMG_PREFIX_FRONT=/uploads
```

2. 确保 MySQL 数据库已启动并创建数据库：
```sql
CREATE DATABASE library;
```

## API 接口文档

所有 API 响应格式统一为：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}
```

### 1. 认证接口（公开）

#### 1.1 用户注册
- **URL**: `POST /register`
- **权限**: 公开接口
- **请求参数**:
```json
{
  "userName": "string",  // 用户名（3-20字符）
  "password": "string",  // 密码（6-20字符）
  "grade": 22           // 年级（整数，最小22）
}
```
- **响应示例**:
```json
{
  "code": 200,
  "msg": "注册成功",
  "data": {
    "id": 1,
    "userName": "testuser",
    "grade": 22,
    "role": "user",
    "createdAt": "2023-01-01 12:00:00",
    "updatedAt": "2023-01-01 12:00:00"
  }
}
```

#### 1.2 用户登录
- **URL**: `POST /login`
- **权限**: 公开接口
- **请求参数**:
```json
{
  "userName": "string",  // 用户名
  "password": "string"   // 密码
}
```
- **响应示例**:
```json
{
  "code": 200,
  "msg": "登录成功",
  "data": {
    "id": 1,
    "userName": "testuser",
    "grade": 22,
    "role": "user",
    "createdAt": "2023-01-01 12:00:00",
    "updatedAt": "2023-01-01 12:00:00",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

#### 1.3 重置密码
- **URL**: `PUT /reset-password`
- **权限**: 公开接口
- **请求参数**:
```json
{
  "userName": "string",  // 用户名
  "newPassword": "string" // 新密码
}
```
- **响应示例**:
```json
{
  "code": 200,
  "msg": "密码重置成功",
  "data": {
    "id": 1,
    "userName": "testuser",
    "grade": 22,
    "role": "user",
    "createdAt": "2023-01-01 12:00:00",
    "updatedAt": "2023-01-01 12:00:00"
  }
}
```

### 2. 用户管理接口（需要 JWT）

#### 2.1 修改密码
- **URL**: `PUT /change-password`
- **权限**: 需要 JWT 认证
- **Headers**: 
  - Authorization: Bearer `<token>`
- **请求参数**:
```json
{
  "currentPassword": "string",  // 当前密码
  "newPassword": "string",      // 新密码
  "confirmPassword": "string"   // 确认新密码
}
```
- **响应示例**:
```json
{
  "code": 200,
  "msg": "修改密码成功",
  "data": {
    "id": 1,
    "userName": "testuser",
    "grade": 22,
    "role": "user",
    "createdAt": "2023-01-01 12:00:00",
    "updatedAt": "2023-01-01 12:00:00"
  }
}
```

#### 2.2 获取用户列表
- **URL**: `GET /users`
- **权限**: 需要 JWT 认证
- **Headers**: 
  - Authorization: Bearer `<token>`
- **请求参数**:
  - page: 页码（默认1）
  - size: 每页数量（默认10，最大100）
- **响应示例**:
```json
{
  "code": 200,
  "msg": "获取用户列表成功",
  "data": {
    "list": [
      {
        "id": 1,
        "userName": "testuser",
        "grade": 22,
        "role": "user",
        "createdAt": "2023-01-01 12:00:00",
        "updatedAt": "2023-01-01 12:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 10,
    "totalPages": 1
  }
}
```

### 3. 个人信息接口（需要 JWT）

#### 3.1 获取用户个人信息
- **URL**: `GET /person/getUserProfile`
- **权限**: 需要 JWT 认证
- **Headers**: 
  - Authorization: Bearer `<token>`
- **请求参数**:
  - userName: 用户名（可选，不传则获取当前用户信息）
- **响应示例**:
```json
{
  "code": 200,
  "msg": "获取个人信息成功",
  "data": {
    "id": 1,
    "userName": "testuser",
    "gender": "保密",
    "age": 0,
    "realName": "张三",
    "avatarUrl": "",
    "bio": "",
    "phone": "",
    "email": "",
    "birthday": null,
    "grade": 22,
    "role": "user"
  }
}
```

#### 3.2 更新用户个人信息
- **URL**: `POST /person/updateUserProfile`
- **权限**: 需要 JWT 认证
- **Headers**: 
  - Authorization: Bearer `<token>`
- **请求参数**:
```json
{
  "userName": "string",   // 账号
  "gender": "string",     // 性别（男/女/保密）
  "age": 0,              // 年龄（0-100）
  "realName": "string",   // 真实姓名
  "bio": "string",        // 个性签名
  "avatarUrl": "string",  // 头像URL
  "phone": "string",      // 手机号码
  "email": "string",      // 电子邮箱
  "birthday": "string"    // 出生年月日（格式：YYYY-MM-DD）
}
```
- **响应示例**:
```json
{
  "code": 200,
  "msg": "更新个人信息成功",
  "data": {
    "id": 1,
    "userName": "testuser",
    "gender": "男",
    "age": 25,
    "realName": "张三",
    "avatarUrl": "http://example.com/avatar.jpg",
    "bio": "这是我的个性签名",
    "phone": "13800138000",
    "email": "test@example.com",
    "birthday": "1998-01-01"
  }
}
```

### 4. 签到接口（需要 JWT）

#### 4.1 开始签到
- **URL**: `POST /sign/start-checkin`
- **权限**: 需要 JWT 认证
- **Headers**: 
  - Authorization: Bearer `<token>`
- **请求参数**: 无
- **响应示例**:
```json
{
  "code": 200,
  "msg": "开始签到成功",
  "data": {
    "id": 1,
    "userName": "testuser",
    "startTime": "2023-01-01 12:00:00",
    "endTime": null,
    "duration": 0,
    "content": null
  }
}
```

#### 4.2 结束签到
- **URL**: `POST /sign/end-checkin`
- **权限**: 需要 JWT 认证
- **Headers**: 
  - Authorization: Bearer `<token>`
- **请求参数**:
```json
{
  "content": "string"  // 签到内容
}
```
- **响应示例**:
```json
{
  "code": 200,
  "msg": "结束签到成功",
  "data": {
    "id": 1,
    "userName": "testuser",
    "startTime": "2023-01-01 12:00:00",
    "endTime": "2023-01-01 13:00:00",
    "duration": 60,  // 分钟
    "content": "学习了NestJS框架"
  }
}
```

#### 4.3 获取当前签到
- **URL**: `GET /sign/get-current-checkin`
- **权限**: 需要 JWT 认证
- **Headers**: 
  - Authorization: Bearer `<token>`
- **请求参数**: 无
- **响应示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "id": 1,
    "userName": "testuser",
    "startTime": "2023-01-01 12:00:00",
    "endTime": null,
    "duration": 0,
    "content": null
  }
}
```

#### 4.4 获取当日签到记录
- **URL**: `GET /sign/get-checkin-record`
- **权限**: 需要 JWT 认证
- **Headers**: 
  - Authorization: Bearer `<token>`
- **请求参数**: 无
- **响应示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "id": 1,
      "userName": "testuser",
      "startTime": "2023-01-01 12:00:00",
      "endTime": "2023-01-01 13:00:00",
      "duration": 60,
      "content": "学习了NestJS框架"
    }
  ]
}
```

#### 4.5 获取本周签到记录
- **URL**: `GET /sign/get-week-checkin-record`
- **权限**: 需要 JWT 认证
- **Headers**: 
  - Authorization: Bearer `<token>`
- **请求参数**: 无
- **响应示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "id": 1,
      "userName": "testuser",
      "startTime": "2023-01-01 12:00:00",
      "endTime": "2023-01-01 13:00:00",
      "duration": 60,
      "content": "学习了NestJS框架"
    }
  ]
}
```

#### 4.6 获取所有签到记录（分页）
- **URL**: `GET /sign/get-all-checkin-record`
- **权限**: 需要 JWT 认证
- **Headers**: 
  - Authorization: Bearer `<token>`
- **请求参数**:
  - userName: 用户名（可选，不传则获取当前用户记录）
  - page: 页码（默认1）
  - size: 每页数量（默认10，最大100）
- **响应示例**:
```json
{
  "code": 200,
  "msg": "查询用户 testuser 的签到记录成功",
  "data": {
    "list": [
      {
        "id": 1,
        "userName": "testuser",
        "startTime": "2023-01-01 12:00:00",
        "endTime": "2023-01-01 13:00:00",
        "duration": 60,
        "content": "学习了NestJS框架"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 10,
    "totalPages": 1
  }
}
```

#### 4.7 获取签到统计
- **URL**: `GET /sign/get-checkin-statistics`
- **权限**: 需要 JWT 认证（管理员功能）
- **Headers**: 
  - Authorization: Bearer `<token>`
- **请求参数**:
  - startDate: 开始时间（格式：YYYY-MM-DD）
  - endDate: 结束时间（格式：YYYY-MM-DD）
- **响应示例**:
```json
{
  "code": 200,
  "msg": "查询时间段签到统计成功",
  "data": {
    "timeRange": {
      "startDate": "2023-01-01 00:00:00",
      "endDate": "2023-01-31 23:59:59"
    },
    "totalUsers": 1,
    "totalCheckins": 10,
    "userStatistics": [
      {
        "userName": "testuser",
        "totalDuration": 600,  // 总时长（分钟）
        "checkinCount": 10,    // 签到次数
        "records": [...],      // 签到记录
        "totalDurationHours": 10,
        "totalDurationMinutes": 0,
        "totalDurationFormatted": "10小时0分钟"
      }
    ]
  }
}
```

#### 4.8 补签
- **URL**: `POST /sign/makeup-checkin`
- **权限**: 需要 JWT 认证（管理员功能）
- **Headers**: 
  - Authorization: Bearer `<token>`
- **请求参数**:
```json
{
  "userName": "string",     // 用户名
  "startTime": "string",    // 开始时间（格式：YYYY-MM-DD HH:mm:ss）
  "endTime": "string",      // 结束时间（格式：YYYY-MM-DD HH:mm:ss）
  "content": "string"       // 学习内容
}
```
- **响应示例**:
```json
{
  "code": 200,
  "msg": "补签成功",
  "data": {
    "id": 2,
    "userName": "testuser",
    "startTime": "2023-01-01 10:00:00",
    "endTime": "2023-01-01 11:00:00",
    "duration": 60,
    "content": "【补签】学习了TypeScript"
  }
}
```

### 5. 文件上传接口（需要 JWT）

#### 5.1 上传图片
- **URL**: `POST /upload/image`
- **权限**: 需要 JWT 认证
- **Headers**: 
  - Authorization: Bearer `<token>`
- **请求参数**:
  - image: 文件（支持 jpg, jpeg, png, gif, webp 格式，最大10MB）
- **响应示例**:
```json
{
  "code": 200,
  "msg": "图片上传成功",
  "data": {
    "url": "http://127.0.0.1:3000/uploads/image-1234567890123-123456789.png",
    "filename": "image-1234567890123-123456789.png",
    "originalname": "avatar.png",
    "size": 123456,
    "mimetype": "image/png"
  }
}
```

## 错误响应格式

所有错误响应格式统一为：
```json
{
  "code": 400,
  "msg": "错误消息"
}
```

常见的错误码：
- 200: 成功
- 400: 请求参数错误
- 401: 未授权或认证失败
- 403: 无权访问
- 404: 资源不存在
- 500: 服务器内部错误

## 运行项目

### 开发模式
```bash
pnpm run start:dev
```

### 生产模式
```bash
pnpm run build
pnpm run start:prod
```

## 测试

```bash
# 单元测试
pnpm run test

# 端到端测试
pnpm run test:e2e

# 测试覆盖率
pnpm run test:cov
```