# 功能房预约（管理）API 文档（v2）

更新时间：2025-11-07

## 概览
- 架构：管理端 `/manage/facility`，门户端见“门户文档”。
- 能力：
  - 基础资源：楼房/房间增删改查与启禁用；房间时间轴；排行榜。
  - 预约治理：创建/修改/取消；审核（通过/驳回）；进行中提前结束；详情聚合。
  - 策略与风控：预约审核开关与最长时长；用户封禁管理。
- 角色：管理员、学生工作者。
- 依赖表：`tb_facility_building`、`tb_facility_room`、`tb_facility_booking`、`tb_facility_booking_user`、`tb_facility_setting`、`tb_facility_ban`

## 约定与通用
- 鉴权：统一请求头 `Authorization: Bearer <token>`。
- 基础路径：管理 `/manage/facility`。
- 分页：`pageNum`（默1），`pageSize`（默10）；返回 `{ rows, total }`。
- 排序：默认 `start_time desc, id desc`（时间相关）；支持通用 `orderByColumn/isAsc`。
- 时间：`yyyy-MM-dd HH:mm:ss`。
- 响应包：
  - 成功：`{ code:200, msg:'操作成功', data:{...} }` 或 `{ code:200, rows:[...], total:n }`
  - 失败：`{ code:4xx/5xx, msg:'错误说明' }`

## 权限与鉴权
- 楼房：`manage:facility:building:list|get|add|edit|remove`
- 房间：`manage:facility:room:list|get|timeline|add|edit|enable|remove`
- 预约：`manage:facility:booking:add|list|edit|cancel|get`
- 审核：`manage:facility:booking:audit:list|approve|reject`
- 设置：`manage:facility:setting:get|edit`
- 封禁：`manage:facility:ban:list|add|remove`
- 排行榜：`manage:facility:top:room|user`

## 数据模型（Schema）
- Building
```json
{ "id":1, "buildingName":"信息楼", "status":"0", "remark":"" }
```
- Room
```json
{ "id":2, "buildingId":1, "floorNo":2, "roomName":"会议室201", "capacity":20, "equipmentTags":"白板,电视", "status":"0" }
```
- Booking
```json
{
  "id":10001,
  "roomId":2,
  "applicantId":1000,
  "purpose":"会议",
  "startTime":"2025-11-10 09:00:00",
  "endTime":"2025-11-10 12:00:00",
  "durationMinutes":180,
  "status":"0",
  "rejectReason": null
}
```
- BookingUser
```json
{ "id":11, "bookingId":10001, "userId":1002, "isApplicant":"0" }
```
- Setting
```json
{ "auditRequired": true, "maxDurationMinutes": 4320 }
```
- Ban
```json
{ "id":1, "userId":1001, "reason":"多次违约", "status":"0", "expireTime":"2025-12-01 00:00:00" }
```


## 业务规则（关键）
- 预约状态：`0待审`、`1已批准`、`2已驳回`、`3已取消`、`4进行中`、`5已完成`
- 冲突判定：与同房间的 `pending/approved/ongoing` 任一时间段重叠即冲突，阻止创建/修改。
- 使用人：含申请人在内不少于 3 人；全部为有效用户。
- 房间与封禁：房间需启用（`status=0`）；申请人不在封禁列表（有效期内）。
- 审核开关：`auditRequired=true` → 创建为 `pending(0)`，否则直接 `approved(1)`。
- 提前结束：仅 `ongoing(4)` 可缩短 `endTime`（`newEnd >= now > start`）。

## 路由清单

### 楼房管理
- 列表：GET `/manage/facility/building/list` | 权限：`manage:facility:building:list`
- 详情：GET `/manage/facility/building/{id}` | 权限：`manage:facility:building:get`
- 新增：POST `/manage/facility/building` | 权限：`manage:facility:building:add`
- 编辑：PUT `/manage/facility/building` | 权限：`manage:facility:building:edit`
- 删除：DELETE `/manage/facility/building/{ids}` | 权限：`manage:facility:building:remove`
- 字段：`{ id, buildingName, status(0正常/1停用), remark }`

### 房间管理
- 列表：GET `/manage/facility/room/list` | 权限：`manage:facility:room:list`
  - query：`buildingId`(long, 必填), `floorNo`(int, 必填), `status`(string, 可选)
- 详情：GET `/manage/facility/room/{id}` | 权限：`manage:facility:room:get`
- 时间轴：GET `/manage/facility/room/{id}/timeline` | 权限：`manage:facility:room:timeline`
  - query：`from`/`to`（可选）→ 返回 `{ roomId, range:{from,to}, segments:[{start,end,status}] }`
- 新增：POST `/manage/facility/room` | 权限：`manage:facility:room:add`
- 编辑：PUT `/manage/facility/room` | 权限：`manage:facility:room:edit`
- 启禁用：PUT `/manage/facility/room/{id}/enable?enable=true|false` | 权限：`manage:facility:room:enable`
- 删除：DELETE `/manage/facility/room/{ids}` | 权限：`manage:facility:room:remove`
- 字段：`{ id, buildingId, floorNo, roomName, capacity, equipmentTags, status(0启用/1禁用) }`

### 排行榜
- 房间：GET `/manage/facility/top/room?period=7d|30d` | 权限：`manage:facility:top:room`
- 用户：GET `/manage/facility/top/user?period=7d|30d` | 权限：`manage:facility:top:user`

## 预约治理

### 创建预约（管理员自用）
- 方法：POST
- 路径：`/manage/facility/booking`
- 权限：`manage:facility:booking:add`
- 请求体：
```json
{ "roomId": 2, "purpose": "会议", "startTime": "2025-11-10 09:00:00", "endTime": "2025-11-10 12:00:00", "userIdList": [1001,1002,1003] }
```
- 返回：`{ code:200 }`（或抛业务异常见“错误码”）

### 我的预约（管理员视角）
- 方法：GET
- 路径：`/manage/facility/booking/my/list`
- 权限：`manage:facility:booking:list`
- 请求参数（query，可选）：`status`、分页参数
- 返回：`{ code:200, rows:[FacilityBooking], total }`

### 修改预约（开始前）
- 方法：PUT
- 路径：`/manage/facility/booking/{id}`
- 权限：`manage:facility:booking:edit`
- 请求体：`{ "purpose": "...", "startTime": "...", "endTime": "...", "userIdList": [ ... ] }`
- 返回：`{ code:200 }`；同创建校验（冲突/人员/时长等）。
- 备注：仅申请人、仅 `pending/approved/rejected` 且开始前；当前为 `rejected(2)` 时，编辑后根据审核开关进入 `pending(0)` 或 `approved(1)` 并清空 `rejectReason`。

### 提前结束（进行中）
- 方法：PUT
- 路径：`/manage/facility/booking/{id}/end-early`
- 权限：`manage:facility:booking:edit`
- 请求体：`{ "endTime": "2025-11-10 11:00:00" }`
- 返回：`{ code:200 }`
- 备注：已批准或进行中均可调用（需实际已开始）；若传入结束时间早于当前，系统将取当前时间；当新的结束时间不晚于当前，状态置为 `completed(5)`。

### 取消预约（开始前）
- 方法：DELETE
- 路径：`/manage/facility/booking/{id}`
- 权限：`manage:facility:booking:cancel`
- 返回：`{ code:200 }`
- 备注：仅申请人可取消；仅 `pending/approved` 且开始前。

### 审核列表（待审）
- 方法：GET
- 路径：`/manage/facility/booking/audit/list`
- 权限：`manage:facility:booking:audit:list`
- 请求参数（query，可选）：
  - `bookingId`(long)、`buildingId`(long)、`roomId`(long)、`applicantId`(long)、`from`/`to`(datetime)
- 返回：`{ code:200, rows:[FacilityBooking], total }`

### 审核通过/驳回
- 通过：PUT `/manage/facility/booking/{id}/approve` | 权限：`manage:facility:booking:audit:approve`
- 驳回：PUT `/manage/facility/booking/{id}/reject` | 权限：`manage:facility:booking:audit:reject` | Body：`{ "reason":"必填" }`
- 说明：二次冲突校验后变更状态；仅 `pending(0)` 允许。

### 预约详情（含友好信息）
- 方法：GET
- 路径：`/manage/facility/booking/{id}`
- 权限：`manage:facility:booking:get`
- 返回：`{ booking, users[], meta:{ roomName, buildingName, applicantName, statusText } }`

## 策略配置与风控

### 审核与时长设置
- 获取：GET `/manage/facility/setting/audit-required` | 权限：`manage:facility:setting:get`
- 保存：PUT `/manage/facility/setting/audit-required` | 权限：`manage:facility:setting:edit`
- Body：`{ "auditRequired": true|false, "maxDurationMinutes": 4320 }`
- 返回：`{ code:200 }`

### 封禁管理
- 列表：GET `/manage/facility/ban/list` | 权限：`manage:facility:ban:list`
  - query：`status`(0生效/1失效)、`userId`(可选)
- 新增：POST `/manage/facility/ban` | 权限：`manage:facility:ban:add`
  - Body：`{ "userId": 1001, "reason": "多次违约", "expireTime": "2025-12-01 00:00:00" }`
- 解禁：DELETE `/manage/facility/ban/{id}` | 权限：`manage:facility:ban:remove`

## 错误码与语义
- 401 未授权：未登录/过期
- 403 权限不足：缺少对应 `manage:facility:*`
- 404 不存在：预约/房间/楼房不存在
- 409 状态冲突：
  - 审核：仅待审可通过/驳回
  - 取消：仅开始前的 `pending/approved`
  - 提前结束：仅 `ongoing`
- 500 业务失败：时间冲突、被封禁、房间禁用、参与人不达标或用户无效、时长非法、参数不全等；`msg` 明确说明

## Apifox 导入建议
- 分组：功能房预约-管理；环境 `local`；变量：`Authorization`
- 用例建议：
  1) 创建预约（待审模式）→ 审核通过 → 时间轴包含 approved 段
  2) 已批准 → 进行中（可模拟时间或手动设置）→ 提前结束 → 时间轴尾端收缩
  3) 取消预约（开始前）→ 时间轴释放占用
  4) 设置 `auditRequired=false` → 创建即 `approved`，校验冲突拦截
  5) 封禁用户 → 创建/修改失败（被封禁）→ 解禁后恢复