# 报告厅预约审核 API 文档 ## 文档信息 - **文档名称**: 报告厅预约审核 API 文档 - **创建时间**: 2025-01-09 - **维护负责人**: 开发团队 - **最后更新**: 2025-01-09 16:30:00 ## 概述 报告厅预约审核模块提供专门的报告厅预约审核功能 API 接口，包括审核建议生成、时间冲突检查、批量审核等核心功能。该模块主要面向管理员用户，用于对用户提交的报告厅预约申请进行审核处理。 ### 核心功能 - 📋 **预约列表查询**：查询待审核和已审核的报告厅预约申请 - 🔍 **时间冲突检查**：智能检测预约时间是否与已批准的预约冲突 - 💡 **审核建议生成**：基于时间冲突检查结果自动生成审核建议 - ✅ **批量审核处理**：支持批准/拒绝单个或多个预约申请 - 📊 **审核记录管理**：记录审核人、审核时间、审核备注等详细信息 ### 技术特点 - **智能冲突检测**：精确的时间重叠算法，避免预约冲突 - **批量操作支持**：高效处理多个预约的审核操作 - **权限控制严格**：完整的权限验证机制 - **日志记录完整**：详细的操作日志和审核轨迹 --- ## 🔐 基础规范 ### 请求头规范 所有需要认证的接口都必须在请求头中携带： ```json { "Authorization": "Bearer {access_token}", "clientid": "e5cd7e4891bf95d1d19206ce24a7b32e", "Content-Type": "application/json;charset=utf-8", "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8", "referer": "http://localhost/login?redirect=%252Findex" } ``` ### 响应格式规范 - **分页列表**: TableDataInfo 格式 (total, rows, code, msg) - **非分页接口**: R 类型格式 (code, msg, data) - **错误响应**: 统一错误格式 详细规范请参考：[API文档基础规范](./API文档基础规范.md) --- ## 📋 报告厅预约查询 API ### 1. 查询报告厅预约列表 **接口描述**: 查询报告厅预约申请列表，支持多种条件筛选 **请求方式**: `GET` **请求路径**: `/hq/hallReservation/list` **权限要求**: `hq:hallReservation:list` #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | 示例值 | | ------------- | ------- | ---- | ---------------------------------- | ---------------- | | hallName | String | 否 | 报告厅名称（模糊查询） | 第一报告厅 | | startTime | String | 否 | 预约开始时间（查询该时间之后的） | 2025-01-10 | | endTime | String | 否 | 预约结束时间（查询该时间之前的） | 2025-01-15 | | applicantName | String | 否 | 申请人姓名（模糊查询） | 张三 | | status | String | 否 | 预约状态（0-审核中 1-已批准 2-已拒绝） | 0 | | pageNum | Integer | 否 | 页码，默认1 | 1 | | pageSize | Integer | 否 | 每页数量，默认10 | 10 | #### 响应示例 ```json { "total": 5, "rows": [ { "id": 1234567890123456789, "hallId": 1, "hallName": "第一报告厅", "applicantId": 987654321, "applicantName": "张三", "applicantPhone": "13800138000", "startTime": "2025-01-15 09:00:00", "endTime": "2025-01-15 12:00:00", "reservationPurpose": "学术讲座 - 人工智能发展趋势", "status": "0", "auditBy": null, "auditName": null, "auditTime": null, "auditRemark": null, "createTime": "2025-01-09 14:30:00" } ], "code": 200, "msg": "查询成功" } ``` ### 2. 获取报告厅预约详情 **接口描述**: 获取指定预约申请的详细信息 **请求方式**: `GET` **请求路径**: `/hq/hallReservation/{id}` **权限要求**: `hq:hallReservation:query` #### 路径参数 | 参数名 | 类型 | 必填 | 说明 | 示例值 | | ------ | ---- | ---- | ------- | ----------------- | | id | Long | 是 | 预约 ID | 1234567890123456789 | #### 响应示例 ```json { "code": 200, "msg": "操作成功", "data": { "id": 1234567890123456789, "hallId": 1, "hallName": "第一报告厅", "applicantId": 987654321, "applicantName": "张三", "applicantPhone": "13800138000", "startTime": "2025-01-15 09:00:00", "endTime": "2025-01-15 12:00:00", "reservationPurpose": "学术讲座 - 人工智能发展趋势", "status": "0", "auditBy": null, "auditName": null, "auditTime": null, "auditRemark": null, "createTime": "2025-01-09 14:30:00" } } ``` --- ## 🔍 时间冲突检查 API ### 检查报告厅预约时间冲突 **接口描述**: 检查指定报告厅在指定时间段内是否存在已批准的预约冲突 **请求方式**: `POST` **请求路径**: `/hq/hallReservation/checkTimeConflict` **权限要求**: `hq:hallReservation:query` #### 请求体 ```json { "hallId": 1, "startTime": "2025-01-15 09:00:00", "endTime": "2025-01-15 12:00:00", "excludeId": 1234567890123456789 } ``` #### 请求参数说明 | 参数名 | 类型 | 必填 | 说明 | 示例值 | | --------- | ---- | ---- | --------------------------------------- | --------------------- | | hallId | Long | 是 | 报告厅ID | 1 | | startTime | Date | 是 | 预约开始时间（格式：yyyy-MM-dd HH:mm:ss） | 2025-01-15 09:00:00 | | endTime | Date | 是 | 预约结束时间（格式：yyyy-MM-dd HH:mm:ss） | 2025-01-15 12:00:00 | | excludeId | Long | 否 | 排除的预约ID（编辑时排除自己） | 1234567890123456789 | #### 响应示例 **无冲突时：** ```json { "code": 200, "msg": "操作成功", "data": { "hasConflict": false, "conflictList": [], "conflictMessage": "无时间冲突" } } ``` **有冲突时：** ```json { "code": 200, "msg": "操作成功", "data": { "hasConflict": true, "conflictList": [ { "id": 1234567890123456790, "hallId": 1, "hallName": "第一报告厅", "applicantName": "李四", "applicantPhone": "13900139000", "startTime": "2025-01-15 10:00:00", "endTime": "2025-01-15 13:00:00", "reservationPurpose": "企业宣讲会", "status": "1", "auditName": "管理员", "auditTime": "2025-01-14 15:30:00" } ], "conflictMessage": "发现 1 个时间冲突的已批准预约" } } ``` #### 时间冲突判定规则 两个时间段存在冲突的条件： 1. 新预约开始时间 < 已存在预约结束时间 2. 新预约结束时间 > 已存在预约开始时间 即：`startTime < existingEndTime AND endTime > existingStartTime` #### 冲突检查逻辑 1. **同一报告厅**：只检查相同报告厅ID的预约 2. **已批准状态**：只检查状态为"1"（已批准）的预约 3. **排除自身**：修改预约时可以通过excludeId排除自身 4. **精确匹配**：使用数据库时间比较，确保检查准确性 --- ## ✅ 报告厅预约审核 API ### 批量审核报告厅预约 **接口描述**: 批量批准或拒绝报告厅预约申请 **请求方式**: `PUT` **请求路径**: `/hq/hallReservation/audit` **权限要求**: `hq:hallReservation:audit` #### 请求体 ```json { "ids": [1234567890123456789, 1234567890123456790], "status": "1", "auditRemark": "审核通过，请按时使用报告厅" } ``` #### 请求参数说明 | 参数名 | 类型 | 必填 | 说明 | 示例值 | | ----------- | ---------- | ---- | ------------------------------ | ----------------------------------------------- | | ids | Long[] | 是 | 要审核的预约ID数组 | [1234567890123456789, 1234567890123456790] | | status | String | 是 | 审核状态（1-批准 2-拒绝） | 1 | | auditRemark | String | 否 | 审核备注（拒绝时建议填写原因） | 审核通过，请按时使用报告厅 | #### 响应示例 **成功时：** ```json { "code": 200, "msg": "操作成功" } ``` **失败时：** ```json { "code": 500, "msg": "审核失败，请稍后重试" } ``` #### 审核业务逻辑 1. **状态检查**：只有状态为"0"（审核中）的预约可以被审核 2. **权限验证**：必须具有`hq:hallReservation:audit`权限 3. **审核信息记录**： - auditBy：当前登录用户ID - auditName：当前登录用户姓名 - auditTime：当前系统时间 - auditRemark：审核备注 4. **批量操作**：支持一次审核多个预约，保证操作的原子性 #### 审核状态说明 | 状态值 | 状态名称 | 说明 | | ------ | -------- | ---------------------- | | 0 | 审核中 | 用户提交，等待审核 | | 1 | 已批准 | 管理员审核通过 | | 2 | 已拒绝 | 管理员审核拒绝 | --- ## 📊 数据字典 ### 预约状态 (hall_reserv_status) | 字典值 | 字典标签 | 说明 | 颜色标识 | | ------ | -------- | ------------ | -------- | | 0 | 审核中 | 待管理员审核 | 橙色 | | 1 | 已批准 | 审核通过 | 绿色 | | 2 | 已拒绝 | 审核拒绝 | 红色 | --- ## 🔒 权限配置 ### 接口权限要求 | 接口 | 权限标识 | 说明 | | ----------------------------- | --------------------------- | -------------- | | 查询报告厅预约列表 | hq:hallReservation:list | 列表查询权限 | | 获取报告厅预约详情 | hq:hallReservation:query | 详情查询权限 | | 检查报告厅预约时间冲突 | hq:hallReservation:query | 详情查询权限 | | 批量审核报告厅预约 | hq:hallReservation:audit | 审核操作权限 | ### 权限配置SQL 参考文件：`docs/设计文档/database/hall-audit-permission.sql` --- ## 💡 开发建议 ### 前端集成建议 1. **审核建议显示**： - 调用时间冲突检查接口 - 根据返回结果显示审核建议 - 冲突时显示警告图标和冲突详情 2. **批量操作优化**： - 支持全选/反选功能 - 批量操作前进行确认提示 - 操作结果统一反馈 3. **用户体验优化**： - 实时冲突检查 - 操作loading状态 - 详细的错误提示 ### 后端开发注意事项 1. **时间处理**： - 统一使用数据库时间进行比较 - 注意时区处理 - 精确到秒级别 2. **并发控制**： - 审核操作加锁机制 - 防止重复审核 - 事务一致性保证 3. **日志记录**： - 详细的操作日志 - 异常情况记录 - 性能监控 --- ## 🐛 常见问题 ### Q1: 时间冲突检查不准确怎么办？ **A**: 检查以下几点： 1. 确认时间格式是否正确（yyyy-MM-dd HH:mm:ss） 2. 检查数据库中的时间数据是否准确 3. 确认冲突检查的SQL逻辑是否正确 4. 检查是否正确排除了指定的预约ID ### Q2: 批量审核部分失败怎么处理？ **A**: 1. 后端使用事务确保原子性 2. 如果部分失败，整个操作回滚 3. 返回具体的失败原因 4. 前端提示用户重新操作 ### Q3: 审核权限验证失败？ **A**: 1. 检查用户是否具有`hq:hallReservation:audit`权限 2. 确认权限配置SQL是否正确执行 3. 检查角色权限分配是否正确 4. 确认Token是否有效 --- ## 📝 版本记录 ### v1.0.0 (2025-01-09) **新增功能**： - ✨ 报告厅预约时间冲突检查接口 - ✨ 智能审核建议生成功能 - ✨ 批量审核处理功能 - ✨ 完整的权限控制机制 - ✨ 详细的审核记录管理 **技术特点**： - 🔍 精确的时间重叠检测算法 - 📊 批量操作支持 - 🔒 严格的权限验证 - 📝 完整的操作日志 **API接口**： - GET `/hq/hallReservation/list` - 查询预约列表 - GET `/hq/hallReservation/{id}` - 获取预约详情 - POST `/hq/hallReservation/checkTimeConflict` - 检查时间冲突 - PUT `/hq/hallReservation/audit` - 批量审核预约 --- **📝 维护人**: 开发团队 **🔄 最后更新**: 2025-01-09 16:30:00 **📁 文件位置**: `docs/开发文档/API/报告厅预约审核API.md` **🎯 相关文档**: [API文档基础规范](./API文档基础规范.md) | [API文档总览](./API文档总览.md)