# 功能房预约模块 需求草案（v1）

> 目标：在现有平台内提供“功能房”按时间段的预约能力，支持按楼房/楼层浏览、时间轴查看占用、在线提交预约、审核（可开关）、封禁违规申请人，以及排行榜统计。本文为需求对齐草案，确认后进入建表与 API 设计。

## 1. 业务范围与术语
- 功能房（Room）：可预约的物理空间，如会议室、多媒体教室、活动室等。
- 楼房（Building）/楼层（Floor）：功能房的空间层级。楼层以整型数字表示（可含负数代表地下一层）。
- 预约（Booking）：对某个功能房在指定时间段的使用申请，包含申请人、使用人列表（含申请人在内不少于 3 人）、使用目的与时长限制（≤72 小时）。
- 审核开关：全局配置，控制预约是否需审核。关闭时用户自治，只要不冲突即成功；开启时由“学生工作者”审核通过后生效。
- 封禁（Ban）：对违规申请人进行封禁，被封禁者无法作为预约申请人提交预约。

## 2. 角色与权限（初稿）
- 普通用户（user）
  - 浏览：楼房/楼层/功能房列表、功能房详情与时间轴
  - 动作：提交预约、查看/取消“我的预约”、修改被驳回的预约并再次提交
- 学生工作者（staff）
  - 审核：查看预约申请、通过/驳回（必填驳回理由）
  - 封禁：对违规申请人封禁/解封
- 管理员（admin）/超级管理员（super_admin）
  - 功能房管理：增删改查、启用/禁用（禁用后不可新预约）
  - 配置：设置全局“审核开关”
  - 统计：查看排行榜

权限标识约定（示例，最终以实现为准）：
- manage:facility:building:list/add/edit/remove
- manage:facility:room:list/get/add/edit/remove/enable
- manage:facility:booking:list/get/add/edit/remove/cancel
- manage:facility:booking:audit:list/approve/reject
- manage:facility:setting:get/edit
- manage:facility:ban:list/add/remove
- manage:facility:top:room/user

## 3. 页面与功能清单（用户侧）
1) 功能房浏览
- 选择楼房 → 选择楼层 → 显示该楼层的功能房列表（支持状态/容量/设备标签等基础筛选，MVP 可先不做高级筛选）。
- 点击某功能房查看详情页：含基础信息与“时间轴”。

2) 时间轴
- 显示该功能房历史与未来的占用情况：
  - 已批准（Approved）与进行中/已完成：实线段
  - 待审核（Pending）：虚线段（用于提示冲突）
  - 已取消/已驳回：默认不在公共时间轴中显示；仅在“我的预约”中展示（待确认）
- 支持时间范围缩放（近 7 天/近 30 天/自定义），MVP 至少展示“近 30 天”。

3) 提交预约
- 入口：功能房详情页“预约”按钮（自动填充房间）。
- 表单字段（必填）：
  - 预约房间：从详情页带入
  - 预约申请人：当前登录用户
  - 使用人列表：不少于 3 人（含申请人），校验用户唯一性与存在性
  - 使用目的：文本（1~200 字）
  - 开始时间：不得早于当前时间
  - 使用时长：>0 且 ≤ 72 小时（不限制最小时间粒度）
- 冲突校验：提交时必须检查与已批准/待审核的时间段是否重叠，若重叠则提示用户查看时间轴并调整。
- 成功规则：
  - 审核开关=关闭：直接进入“已批准”
  - 审核开关=开启：进入“待审核”

4) 我的预约
- 列表：显示作为“预约申请人”的全部记录（历史+未来），含状态过滤。
- 取消：当状态为“已批准/待审核”，且开始时间未到，可取消；取消后时间轴同步释放。
- 修改并重提：当被“驳回”时，可修改并重新提交（重新进入待审核或直接批准，取决于开关）。

5) 排行榜
- 房间被预约总时长榜：统计周期（近 7 天 / 近 30 天），按累计被预约时长排序（仅计入已批准与进行中/已完成，不含已取消/已驳回）。
- 用户累计预约总时长榜：同上（以申请人为统计主体）。
- 性能：结果使用 Redis 缓存（如 app:facility:rank:room:7d），定时刷新或基于事件增量更新，MVP 可采用定时重算。

## 4. 管理端功能（管理员/学生工作者）
1) 功能房管理
- 建筑管理：增删改查楼房；
- 房间管理：房间增删改查、启用/禁用（禁用状态不可新增预约；已存在未来预约不强制取消，维持有效，待确认）。

2) 审核管理（需审核开关=开启）
- 审核列表：待审核预约，支持按楼房/房间/申请人/时间范围筛选。
- 审核详情：查看预约信息（目的、时间段、使用人列表等）。
- 审核动作：通过/驳回；驳回需填写必填理由。通过后进入“已批准”；驳回后进入“已驳回”。

3) 审核开关
- 全局单开关（系统设置）。关闭：所有新预约跳过审核直接成功；开启：新预约进入待审。

4) 封禁管理
- 对违规申请人执行封禁/解封。
- 被封禁用户不可作为“预约申请人”提交预约（是否允许其作为“使用人”参与，见“待确认”）。

5) 统计与排行榜
- 查看房间与用户两个维度的排行榜，支持周期切换（7/30 天）。

## 5. 状态机与流转
- 草案状态集合：
  - pending（待审核）
  - approved（已批准）
  - rejected（已驳回）
  - cancelled（已取消）
  - ongoing（进行中）
  - completed（已完成）

- 状态流转规则：
  - 审核开关=关闭：submit → approved
  - 审核开关=开启：submit → pending → {approve → approved | reject → rejected}
  - 时间到达：
    - approved 在开始时间达成 → ongoing
    - ongoing 在结束时间达成 → completed
  - 用户取消：
    - {pending, approved} 且未开始 → cancelled（释放占用）
  - 被驳回修改：rejected → submit（修改后重新提交，走开关逻辑）

备注：时间轴应展示 pending/approved/ongoing/completed；cancelled/rejected 默认不展示（仅“我的预约”可见），以降低噪音。

## 6. 关键业务校验与约束
- 预约时间：
  - 结束时间 = 开始时间 + 时长，要求 0 < 时长 ≤ 72 小时；
  - 开始时间须晚于当前时间；
- 冲突检测（同一房间）：
  - 与 {approved, pending} 的区间有重叠即视为冲突；
  - 区间判定采用半开区间：[start, end)。
- 人员约束：
  - 使用人列表包含申请人在内不少于 3 人；
  - 人员去重且均为有效系统用户；
  - 申请人若被封禁，禁止提交预约；
  - 是否允许“被封禁者作为使用人参与”需确认（默认允许，仅限制其担任申请人）。
- 房间禁用：
  - 禁用中的房间不可新建预约；
  - 既有未来预约是否强制失效或保留，建议保留并由管理员沟通处理（待确认）。
- 修改/取消规则：
  - pending/approved 可在开始前取消；
  - rejected 可修改后重提；
  - ongoing/completed 不可修改或取消。
- 并发与事务：
  - 提交时先做区间冲突查询，配合数据库层唯一/排它逻辑与事务，避免竞态下的“脏批准”。
  - 可引入幂等键（roomId+start+end+applicantId+hash(people)）。
- 审计与日志：
  - 记录创建/更新人、时间、请求来源 IP；
  - 审核操作记录审核人与意见。

## 7. 数据模型草案（仅为对齐概念，非最终DDL）
- Building（楼房）：id、name、status、remark、审计字段
- Room（功能房）：id、building_id、floor_no、name、capacity、tags、status（enable/disable）、remark、审计字段
- Booking（预约）：id、room_id、applicant_id、purpose、start_time、end_time、duration_hours、status、reject_reason、审计字段
- BookingUser（使用人关联）：id、booking_id、user_id、is_applicant（Y/N）
- Setting（配置）：id、audit_required（Y/N）、remark、审计字段
- Ban（封禁）：id、user_id、reason、status（active/inactive）、expire_time（可选）、审计字段

说明：正式 DDL 将按 `tb_` 前缀与审计字段规范输出到 `book-mis.sql` 草案尾部，待确认后再执行建表。

## 8. 接口概览（预告，API 文档将在下一步输出）
- 用户侧
  - GET /manage/facility/building/list
  - GET /manage/facility/room/list?buildingId=&floorNo=
  - GET /manage/facility/room/{id}
  - GET /manage/facility/room/{id}/timeline?range=7d|30d
  - POST /manage/facility/booking
  - GET /manage/facility/booking/my/list
  - DELETE /manage/facility/booking/{id}（取消）
  - PUT /manage/facility/booking/{id}（仅驳回后允许修改字段）
- 管理端
  - CRUD：/manage/facility/building, /manage/facility/room
  - 审核：GET /manage/facility/booking/audit/list, PUT /manage/facility/booking/{id}/approve, PUT /manage/facility/booking/{id}/reject
  - 设置：GET/PUT /manage/facility/setting/audit-required
  - 封禁：GET/POST/DELETE /manage/facility/ban
  - 排行榜：GET /manage/facility/top/room?period=7d|30d, GET /manage/facility/top/user?period=7d|30d

## 9. 非功能需求
- 性能：
  - 时间轴查询按房间+时间窗索引优化；
  - 排行榜采用 Redis 缓存（app:facility:rank:*），定时刷新；
  - 列表默认分页。
- 安全：
  - 所有写入接口需鉴权；
  - 权限按 `manage:<module>:<op>` 严格校验；
  - 不在代码库中保存任何敏感凭据。
- 可靠性：
  - 写操作加事务；
  - 冲突检测与写入之间避免竞态（必要时行级锁或重查验证）。
- 可观测性：
  - 审核与封禁操作均写操作日志；
  - 关键错误具备明确的业务提示（如“时间段冲突，请查看时间轴”）。

## 10. 边界与异常场景
- 同一申请人重复提交完全相同时段与房间：以幂等键拦截为“重复提交”。
- 时间边界：开始==当前时间或结束==开始，按规则拒绝（需 >0 时长且开始>当前）。
- 跨日/跨周与节假日：不限制，但后续可引入“开放时间策略”（非 MVP）。
- 房间禁用期间的既有预约：默认保留（待确认）；如需强制取消需另行通知与日志。
- 被封禁用户的已有未来预约：默认不影响已批准记录（待确认）。
- 使用人中包含被封禁者：默认允许（待确认）。
- 大量并发预约同一热门房间：通过事务+二次校验避免“幽灵批准”。

## 11. MVP 范围（本期上线）
- 用户：楼房/楼层浏览、功能房详情与时间轴；提交预约；我的预约（取消/查看）；被驳回后修改并重提。
- 管理员：功能房 CRUD 与启用/禁用；全局审核开关；审核（通过/驳回、必填理由）；封禁/解封申请人。
- 统计：房间/用户两个排行榜（7/30 天），Redis 简单缓存，定时重算。
- 不纳入本期：开放时间策略、节假日规则、通知推送、重复性预约、导出、外部日历订阅。

## 12. 与现有系统的对齐
- 统一遵循 RuoYi 权限风格与审计字段（create_by/create_time/update_by/update_time/del_flag）。
- 统一响应结构与分页协议；
- Redis Key 统一前缀：`app:facility:*`；
- OSS 暂无直接依赖；如后续需要“房间图片”，走通用上传接口。

## 13. 已确认决策（v1）
- 不限制预约时间粒度（由前端时间选择器决定）。
- 时间轴：同步取消/驳回后的变化，但默认不显示取消/驳回记录；“我的预约”显示完整历史。
- 禁用房间：仅停止新增预约；已存在的未来预约保留。
- 封禁：被封禁用户允许作为“使用人”；仅限制其担任“申请人”。
- 封禁后影响：被封禁用户已批准的未来预约不受影响。
- 取消/修改：
  - 开始前：申请人可取消或修改预约（需再次通过时间冲突校验）。
  - 使用中：允许“提前结束”（仅可修改结束时间，并需保证不违反业务约束）。
  - 使用后：不可修改或取消。
- 排行榜：提供最简实现（房间/用户两个榜，周期 7/30 天，Redis 缓存）。
- 最长使用时间：为“全局配置”，用于所有房间（后期可扩展房间级覆盖）。
- 审核开关：存于模块内配置表，并在模块的“审核管理页面”中设置。
- 前端时间轴：采用 ECharts 实现（已安装 echarts）。

---

以上决策已并入本需求文档。下一步将提交 DDL 与 API 文档草案。