# 功能房预约模块 API 文档（v1, 已拆分）

概览
- 本文档为旧版总览，已拆分为两份更清晰的文档，请优先参考：
  - 门户侧：docs/api/功能房预约-门户.md
  - 管理侧：docs/api/功能房预约-管理.md
- 业务：按楼房/楼层浏览功能房；查看时间轴；提交/取消/修改预约；审核（可开关）；封禁申请人；排行榜。
- 角色权限：普通用户、学生工作者、管理员/超级管理员。
- 依赖表：tb_facility_building/tb_facility_room/tb_facility_booking/tb_facility_booking_user/tb_facility_setting/tb_facility_ban。
- 状态：pending/approved/rejected/cancelled/ongoing/completed（编码见 SQL 注释）。

通用说明（保留参考）
- baseURL: `http://localhost:8080`
- 认证：请求头携带 `Authorization: Bearer <token>`
- 分页：遵循 RuoYi 通用分页参数（`pageNum`、`pageSize`、`orderByColumn`、`isAsc`）。

## 路由清单（过时，已拆分至两份文档）

1) 楼房与房间（用户/管理员）
- GET `/manage/facility/building/list`（权限：`manage:facility:building:list`）
  - query：`status` 可选（0正常 1停用）
  - 返回：`[{ id, buildingName, status, remark }]`

- GET `/manage/facility/room/list`（权限：`manage:facility:room:list`）
  - query：`buildingId`（必填），`floorNo`（必填），`status`（可选，默认仅返回启用）
  - 返回：`[{ id, buildingId, floorNo, roomName, capacity, equipmentTags, status }]`

- GET `/manage/facility/room/{id}`（权限：`manage:facility:room:get`）
  - 返回：房间详情

- GET `/manage/facility/room/{id}/timeline`（权限：`manage:facility:room:timeline`）
  - query：`from`、`to`（ISO 或 `yyyy-MM-dd HH:mm:ss`；缺省默认近 30 天）
  - 返回：`{ roomId, range:{from,to}, segments:[{start,end,status}] }`
  - 说明：segments 仅包含 pending/approved/ongoing/completed；取消/驳回不返回，但会驱动时间轴同步更新

（管理员）
- 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`）
- POST `/manage/facility/room`（`manage:facility:room:add`）
- PUT `/manage/facility/room`（`manage:facility:room:edit`）
- PUT `/manage/facility/room/{id}/enable`（`manage:facility:room:enable`，启/禁用）
- DELETE `/manage/facility/room/{ids}`（`manage:facility:room:remove`）

2) 预约（用户：门户接口 /portal）
- POST `/portal/facility/booking`（认证：`isAuthenticated()`）
  - body：
    ```json
    {
      "roomId": 2,
      "purpose": "课程讨论会",
      "startTime": "2025-11-10 09:00:00",
      "endTime": "2025-11-10 12:00:00",
      "userIdList": [1001,1002,1003]  // 含申请人在内不少于3人
    }
    ```
  - 响应：`{ code, msg, data:{ id, status } }`
  - 规则：
    - 0<时长≤maxDurationMinutes（默认72小时）；
    - 与 pending/approved/ongoing 区间重叠即 400 TIME_CONFLICT；
    - 申请人被封禁→ 400 APPLICANT_BANNED；房间禁用→ 400 ROOM_DISABLED。

- GET `/portal/facility/booking/my/list`（认证：`isAuthenticated()`）
  - query：`status` 可选，默认全部；分页参数同上
  - 返回：`{ total, rows:[{id, roomId, purpose, startTime, endTime, status}...] }`

- PUT `/portal/facility/booking/{id}`（认证：`isAuthenticated()`）
  - 用途：开始前允许修改（时间/使用人/目的），需再次冲突校验；被驳回可修改后重提（受审核开关控制）
  - body：同创建，字段按需

- PUT `/portal/facility/booking/{id}/end-early`（认证：`isAuthenticated()`）
  - 用途：进行中允许“提前结束”，仅可缩短结束时间；需保证结束时间≥当前时间且>开始时间
  - body：`{ "endTime": "2025-11-10 11:00:00" }`

- DELETE `/portal/facility/booking/{id}`（认证：`isAuthenticated()`）
  - 用途：开始前允许取消（pending/approved）；取消后释放时间段

3) 审核（学生工作者/管理员）
- GET `/manage/facility/booking/audit/list`（`manage:facility:booking:audit:list`）
  - query：`buildingId/roomId/applicant/时间范围`（可选）
- PUT `/manage/facility/booking/{id}/approve`（`manage:facility:booking:audit:approve`）
  - 说明：二次冲突校验后转为 approved
- PUT `/manage/facility/booking/{id}/reject`（`manage:facility:booking:audit:reject`）
  - body：`{ "reason":"理由必填" }`

4) 模块设置（管理员）
- GET `/manage/facility/setting/audit-required`（`manage:facility:setting:get`）
  - 返回：`{ auditRequired: true, maxDurationMinutes: 4320 }`
- PUT `/manage/facility/setting/audit-required`（`manage:facility:setting:edit`）
  - body：`{ "auditRequired": true, "maxDurationMinutes": 4320 }`

5) 封禁（学生工作者/管理员）
- 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`）

6) 排行榜（管理员/学生工作者）
- GET `/manage/facility/top/room?period=7d|30d`（`manage:facility:top:room`）
  - 返回：`[{ roomId, roomName, buildingName, totalMinutes }]`
- GET `/manage/facility/top/user?period=7d|30d`（`manage:facility:top:user`）
  - 返回：`[{ userId, nickName, totalMinutes }]`

## 示例

接口：列表房间
- 方法：GET
- 路径：/manage/facility/room/list
- 权限：manage:facility:room:list
- 请求参数（query）：buildingId=1&floorNo=2
- 返回示例：
```json
{
  "code": 200,
  "msg": "成功",
  "rows": [
    {
      "id": 2,
      "buildingId": 1,
      "floorNo": 2,
      "roomName": "会议室201",
      "capacity": 20,
      "equipmentTags": "白板,电视",
      "status": "0"
    }
  ],
  "total": 1
}
```

接口：创建预约
- 方法：POST
- 路径：/manage/facility/booking
- 权限：manage:facility:booking:add
- 请求体：见上文 body
- 常见错误码：
  - 400 TIME_CONFLICT：时间段与其他预约重叠
  - 400 APPLICANT_BANNED：申请人被封禁
  - 400 ROOM_DISABLED：房间禁用
  - 400 DURATION_INVALID：时长非法（≤0 或超过上限）
  - 400 PARTICIPANTS_INVALID：参与人数不足 3 或用户不存在

接口：时间轴
- 方法：GET
- 路径：/manage/facility/room/{id}/timeline
- 返回示例：
```json
{
  "code": 200,
  "msg": "成功",
  "data": {
    "roomId": 2,
    "range": { "from": "2025-11-01 00:00:00", "to": "2025-12-01 00:00:00" },
    "segments": [
      { "start": "2025-11-10 09:00:00", "end": "2025-11-10 12:00:00", "status": "approved" },
      { "start": "2025-11-12 14:00:00", "end": "2025-11-12 16:00:00", "status": "pending" }
    ]
  }
}
```

备注与约定
- 半开区间判定：[start, end)，避免边界重复。
- 取消/驳回记录不在公共时间轴返回，但时间轴会同步更新（例如取消释放占用段）。
- 进行中允许提前结束：更新 endTime 并转 completed（不限制最小粒度）。
- 排行榜为最简实现：统计 approved/ongoing/completed 的总时长，使用 Redis 短期缓存。
- 门户（用户）房间与时间轴（只读）
  - GET `/portal/facility/building/list`
  - GET `/portal/facility/room/list?buildingId=&floorNo=`
  - GET `/portal/facility/room/{id}`
  - GET `/portal/facility/room/{id}/timeline`