# 预约限制功能API文档

## 1. 概述

预约限制功能用于管理学生的未到访记录和预约限制，当学生30天内累计三次未到访时，将自动限制其7天内无法再预约。本文档详细说明了预约限制功能相关的API接口。

## 2. 基础信息

- **基础路径**: `/api/xljk/consultation/no-show`
- **权限前缀**: `xljk:consultation:noshow`
- **数据格式**: 所有请求和响应均使用JSON格式
- **认证方式**: Bearer Token

## 3. API接口列表

### 3.1 查询未到访记录列表

#### 接口信息
- **路径**: `/api/xljk/consultation/no-show/list`
- **方法**: GET
- **权限**: `xljk:consultation:noshow:list`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| pageNum | int | 否 | 页码，默认1 |
| pageSize | int | 否 | 每页记录数，默认10 |
| studentName | string | 否 | 学生姓名，模糊查询 |
| studentNo | string | 否 | 学号，模糊查询 |
| status | string | 否 | 状态（0生效中 1已过期 2已解除） |
| beginNoShowDate | string | 否 | 未到访日期范围开始 |
| endNoShowDate | string | 否 | 未到访日期范围结束 |

#### 响应结果
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 10,
    "rows": [
      {
        "id": "1234567890",
        "studentId": "1234567890",
        "studentName": "张三",
        "studentNo": "2023001",
        "collegeName": "信息工程学院",
        "majorName": "计算机科学与技术",
        "className": "计科2301",
        "appointmentId": "9876543210",
        "noShowDate": "2025-07-25",
        "expireDate": "2025-08-01",
        "status": "0"
      }
    ]
  }
}
```

### 3.2 获取未到访记录详情

#### 接口信息
- **路径**: `/api/xljk/consultation/no-show/{id}`
- **方法**: GET
- **权限**: `xljk:consultation:noshow:query`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| id | string | 是 | 未到访记录ID |

#### 响应结果
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "1234567890",
    "studentId": "1234567890",
    "studentName": "张三",
    "studentNo": "2023001",
    "collegeName": "信息工程学院",
    "majorName": "计算机科学与技术",
    "className": "计科2301",
    "appointmentId": "9876543210",
    "appointmentDate": "2025-07-25",
    "appointmentTime": "09:00-09:30",
    "counselorName": "李四",
    "noShowDate": "2025-07-25",
    "expireDate": "2025-08-01",
    "status": "0",
    "createTime": "2025-07-25 10:00:00",
    "updateTime": "2025-07-25 10:00:00"
  }
}
```

### 3.3 解除预约限制

#### 接口信息
- **路径**: `/api/xljk/consultation/no-show/{id}/release`
- **方法**: PUT
- **权限**: `xljk:consultation:noshow:release`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| id | string | 是 | 未到访记录ID |

#### 响应结果
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": true
}
```

### 3.4 检查学生是否被限制预约

#### 接口信息
- **路径**: `/api/xljk/consultation/no-show/check-limitation`
- **方法**: GET
- **权限**: 无需特殊权限，学生可调用

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| studentId | string | 是 | 学生ID |

#### 响应结果
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "limited": true,
    "expireDate": "2025-08-01",
    "expireDateStr": "2025-08-01"
  }
}
```

## 4. 状态码说明

| 状态码 | 说明 |
|-------|------|
| 200 | 成功 |
| 401 | 未认证 |
| 403 | 无权限 |
| 500 | 服务器错误 |

## 5. 错误响应示例

```json
{
  "code": 500,
  "msg": "系统内部错误",
  "data": null
}
```

## 6. 业务规则

1. **未到访记录创建**：
   - 当咨询师记录学生未到访时，系统自动创建未到访记录
   - 同时检查30天内未到访次数，达到3次则设置限制

2. **限制规则**：
   - 限制期为7天（从最后一次未到访日期算起，不含当天）
   - 限制期间学生无法提交预约申请

3. **限制解除**：
   - 自动解除：限制期满7天后自动解除
   - 手动解除：管理员可手动解除限制

## 7. 注意事项

1. 所有日期格式均为`yyyy-MM-dd`
2. 所有日期时间格式均为`yyyy-MM-dd HH:mm:ss`
3. 状态值说明：
   - `0`: 生效中
   - `1`: 已过期
   - `2`: 已解除
   - `null`: 未达到限制条件的未到访记录