# Apifox 指南｜功能房预约模块（v1，已拆分）

> 提示：本指南为早期合并版，现已拆分为两份更清晰的集合，请优先使用：
> - 门户端：docs/apifox/功能房预约-门户.md
> - 管理端：docs/apifox/功能房预约-管理.md

- baseURL: `http://localhost:8080`
- 认证：所有请求添加 Header `Authorization: Bearer {{token}}`
- Token 获取：
  - POST `/login`（按现有 RuoYi 登录接口），保存响应中的 `token` 为环境变量 `token`

## 环境
- 环境：`local`
- 变量：`token`

## 测试步骤（建议用例）

1) 登录并设置 token（必做）
- POST /login
- Body: `{ "username": "admin", "password": "admin123" }`
- 断言：`code == 200 && data.token 存在`
- 设置环境变量：`token = data.token`

2) 新增楼房（管理员）
- POST /manage/facility/building
- Headers: Authorization
- Body: `{ "buildingName":"综合楼A", "status":"0" }`  // 若未传，后端将默认设置为 "0"
- 断言：`code == 200`

3) 新增功能房（管理员）
- POST /manage/facility/room
- Body:
```json
{ "buildingId": 1, "floorNo": 2, "roomName": "会议室201", "capacity": 20, "status": "0" }
```
- 断言：`code == 200`

- 4) 查看楼房与房间列表（用户-门户）
- GET /portal/facility/building/list
- GET /portal/facility/room/list?buildingId=1&floorNo=2
- 断言：`code == 200 && rows[0].roomName == '会议室201'`

5) 设置审核开关（管理员）
- PUT /manage/facility/setting/audit-required
- Body: `{ "auditRequired": true, "maxDurationMinutes": 4320 }`
- 断言：`code == 200`

6) 创建预约（用户-门户）
- POST /portal/facility/booking
- Body:
```json
{
  "roomId": 1,
  "purpose": "课程讨论会",
  "startTime": "2025-11-10 09:00:00",
  "endTime": "2025-11-10 12:00:00",
  "userIdList": [1001,1002,1003]
}
```
- 断言：`code == 200 && data.status in ['0','1']`
- 备注：审核开关=开启→返回待审（0）；关闭→返回已批准（1）

7) 时间冲突用例（用户）
- 再次提交相同时间段
- 断言：`code == 400 && msg 包含 '冲突'`

8) 审核通过（审核开启时，学生工作者）
- GET /manage/facility/booking/audit/list
- 取到待审 ID
- PUT /manage/facility/booking/{id}/approve
- 断言：`code == 200`

9) 取消预约（开始前，用户-门户）
- DELETE /portal/facility/booking/{id}
- 断言：`code == 200`
- 检查时间轴：GET /manage/facility/room/{roomId}/timeline → 取消记录不显示，占用已释放

10) 进行中提前结束（构造进行中数据后，用户-门户）
- PUT /portal/facility/booking/{id}/end-early
- Body: `{ "endTime": "2025-11-10 11:00:00" }`
- 断言：`code == 200`

11) 封禁申请人（学生工作者/管理员）
- POST /manage/facility/ban
- Body: `{ "userId": 1001, "reason": "多次违约" }`
- 断言：`code == 200`
- 再次尝试以 1001 为申请人提交预约
- 断言：`code == 400 && msg 包含 '封禁'`

12) 排行榜（管理员/学生工作者）
- GET /manage/facility/top/room?period=7d
- GET /manage/facility/top/user?period=30d
- 断言：`code == 200 && data 数组存在`

13) 取消后同时间段再次预约（用户-门户）
- 前置：完成步骤 6 创建预约 → 步骤 9 取消预约
- 再次创建：POST /portal/facility/booking（同一 roomId/startTime/endTime）
- 断言：`code == 200`
- 备注：若数据库仍存在旧唯一索引导致 500 Duplicate entry，请执行 book-mis.sql 最新“预约唯一索引调整”中的 ALTER 语句更新索引。

## 常见失败与排查
- 401：未携带 Authorization 头或 token 失效 → 重新登录并设置 token。
- 400 TIME_CONFLICT：调整时间段使其与时间轴不重叠。
- 400 DURATION_INVALID：确保时长>0 且 ≤maxDurationMinutes。
- 400 ROOM_DISABLED：管理员启用了房间禁用；切换房间或联系管理员。
- 400 APPLICANT_BANNED：申请人处于封禁；等待解封或更换申请人。

## 断言建议
- 响应结构统一：`code === 200`；错误用例校验 `code === 400/401/403` 与错误消息包含关键字。
- 时间轴接口：校验 segments 中时间区间不重叠、边界采用半开区间（end == 其他 start 不算冲突）。