# 场地预约管理 API 文档 ## 文档信息 - **文档名称**: 场地预约管理 API 文档 - **创建时间**: 2025-07-01 - **维护负责人**: 开发团队 - **更新记录**: [详见文档末尾变更记录](#变更记录) ## 概述 场地预约管理模块提供完整的场地信息管理和预约流程 API 接口,支持场地信息的 CRUD 操作、预约申请、审批流程和时间冲突检查等功能。 ### 核心功能 - 场地信息管理(增删改查、状态管理) - 场地预约申请(用户发起预约) - 预约审批管理(管理员审批预约) - 时间冲突检查(防止重复预约) - 我的预约查询(用户查看自己的预约) - 使用统计分析(预约数据统计) --- ## 场地信息管理 API ### 1. 查询场地信息列表 **请求方式**: `GET` **请求路径**: `/venue/info/list` **权限要求**: `hq:venue:list` #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | 示例值 | | ---------------- | ------- | ---- | --------------------------- | ------------ | | venueName | String | 否 | 场地名称(模糊查询) | 会议室 | | venueCode | String | 否 | 场地编码 | ROOM001 | | venueLocation | String | 否 | 场地位置(模糊查询) | 行政楼 | | venueType | String | 否 | 场地类型 | meeting_room | | venueStatus | String | 否 | 场地状态(0-维修中 1-可用) | 1 | | venueManagerName | String | 否 | 管理员姓名(模糊查询) | 张三 | | pageNum | Integer | 否 | 页码 | 1 | | pageSize | Integer | 否 | 每页数量 | 10 | #### 响应示例 ```json { "code": 200, "msg": "操作成功", "rows": [ { "id": 1234567890123456789, "venueName": "第一会议室", "venueCode": "ROOM001", "venueLocation": "行政楼3楼", "venueCapacity": 50, "venueType": "meeting_room", "venueStatus": "1", "venueDescription": "配备投影设备的大型会议室", "venueImages": "/upload/venue/room001.jpg", "venueManagerId": 123456789, "venueManagerName": "张三", "createTime": "2025-07-01 10:00:00" } ], "total": 1 } ``` ### 2. 获取场地详细信息 **请求方式**: `GET` **请求路径**: `/venue/info/{id}` **权限要求**: `hq:venue:query` #### 路径参数 | 参数名 | 类型 | 必填 | 说明 | | ------ | ---- | ---- | ------- | | id | Long | 是 | 场地 ID | #### 响应示例 ```json { "code": 200, "msg": "操作成功", "data": { "id": 1234567890123456789, "venueName": "第一会议室", "venueCode": "ROOM001", "venueLocation": "行政楼3楼", "venueCapacity": 50, "venueType": "meeting_room", "venueStatus": "1", "venueDescription": "配备投影设备的大型会议室", "venueImages": "/upload/venue/room001.jpg", "venueManagerId": 123456789, "venueManagerName": "张三", "createTime": "2025-07-01 10:00:00" } } ``` ### 3. 新增场地信息 **请求方式**: `POST` **请求路径**: `/venue/info` **权限要求**: `hq:venue:add` #### 请求体 ```json { "venueName": "第二会议室", "venueCode": "ROOM002", "venueLocation": "行政楼4楼", "venueCapacity": 30, "venueType": "meeting_room", "venueStatus": "1", "venueDescription": "中型会议室,适合部门会议", "venueImages": "/upload/venue/room002.jpg", "venueManagerId": 123456789, "venueManagerName": "李四" } ``` #### 响应示例 ```json { "code": 200, "msg": "操作成功" } ``` ### 4. 修改场地信息 **请求方式**: `PUT` **请求路径**: `/venue/info` **权限要求**: `hq:venue:edit` #### 请求体 ```json { "id": 1234567890123456789, "venueName": "第二会议室(已更新)", "venueCode": "ROOM002", "venueLocation": "行政楼4楼", "venueCapacity": 35, "venueType": "meeting_room", "venueStatus": "1", "venueDescription": "中型会议室,适合部门会议,已扩容", "venueImages": "/upload/venue/room002_new.jpg", "venueManagerId": 123456789, "venueManagerName": "李四" } ``` ### 5. 删除场地信息 **请求方式**: `DELETE` **请求路径**: `/venue/info/{ids}` **权限要求**: `hq:venue:remove` #### 路径参数 | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ----------------------- | | ids | String | 是 | 场地 ID,多个用逗号分隔 | ### 6. 获取可用场地列表 **请求方式**: `GET` **请求路径**: `/venue/info/available` **权限要求**: `hq:venue:query` #### 响应示例 ```json { "code": 200, "msg": "操作成功", "data": [ { "id": 1234567890123456789, "venueName": "第一会议室", "venueCode": "ROOM001", "venueLocation": "行政楼3楼", "venueCapacity": 50, "venueType": "meeting_room" } ] } ``` --- ## 场地预约管理 API ### 1. 查询场地预约列表 **请求方式**: `GET` **请求路径**: `/venue/reservation/list` **权限要求**: `hq:reservation:list` #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | 示例值 | | ----------------- | ------- | ---- | -------------------------------------- | ------------------- | | venueId | Long | 否 | 场地 ID | 1234567890123456789 | | venueName | String | 否 | 场地名称(模糊查询) | 会议室 | | applicantName | String | 否 | 申请人姓名(模糊查询) | 张三 | | reservationDate | String | 否 | 预约日期 | 2025-07-01 | | reservationStatus | String | 否 | 预约状态(0-待审批 1-已批准 2-已拒绝) | 0 | | pageNum | Integer | 否 | 页码 | 1 | | pageSize | Integer | 否 | 每页数量 | 10 | #### 响应示例 ```json { "code": 200, "msg": "操作成功", "rows": [ { "id": 1234567890123456780, "venueId": 1234567890123456789, "venueName": "第一会议室", "applicantId": 987654321, "applicantName": "张三", "applicantPhone": "13800138000", "reservationDate": "2025-07-02", "startTime": "2025-07-02 09:00:00", "endTime": "2025-07-02 11:00:00", "reservationPurpose": "部门月度会议", "participantCount": 15, "specialRequirements": "需要投影设备", "reservationStatus": "0", "createTime": "2025-07-01 15:30:00" } ], "total": 1 } ``` ### 2. 查询我的预约列表 **请求方式**: `GET` **请求路径**: `/venue/reservation/my` **权限要求**: `hq:reservation:my` #### 请求参数 同场地预约列表查询参数,系统自动过滤当前用户的预约 ### 3. 查询待审批预约列表 **请求方式**: `GET` **请求路径**: `/venue/reservation/pending` **权限要求**: `hq:reservation:approve` #### 请求参数 同场地预约列表查询参数,系统自动过滤待审批状态的预约 ### 4. 新增场地预约 **请求方式**: `POST` **请求路径**: `/venue/reservation` **权限要求**: `hq:reservation:add` #### 请求体 ```json { "venueId": 1234567890123456789, "applicantPhone": "13800138000", "reservationDate": "2025-07-02", "startTime": "2025-07-02 14:00:00", "endTime": "2025-07-02 16:00:00", "reservationPurpose": "产品发布会", "participantCount": 25, "specialRequirements": "需要音响设备和投影仪" } ``` #### 响应示例 ```json { "code": 200, "msg": "预约申请已提交,等待审批" } ``` ### 5. 修改场地预约 **请求方式**: `PUT` **请求路径**: `/venue/reservation` **权限要求**: `hq:reservation:edit` #### 请求体 ```json { "id": 1234567890123456780, "venueId": 1234567890123456789, "applicantPhone": "13800138000", "reservationDate": "2025-07-02", "startTime": "2025-07-02 14:30:00", "endTime": "2025-07-02 16:30:00", "reservationPurpose": "产品发布会(已调整)", "participantCount": 30, "specialRequirements": "需要音响设备、投影仪和无线话筒" } ``` ### 6. 删除场地预约 **请求方式**: `DELETE` **请求路径**: `/venue/reservation/{ids}` **权限要求**: `hq:reservation:remove` #### 路径参数 | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ----------------------- | | ids | String | 是 | 预约 ID,多个用逗号分隔 | ### 7. 检查时间冲突 **请求方式**: `GET` **请求路径**: `/venue/reservation/conflict` **权限要求**: `hq:reservation:query` #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | 示例值 | | --------- | ------ | ---- | --------------------------- | ------------------- | | venueId | Long | 是 | 场地 ID | 1234567890123456789 | | startTime | String | 是 | 开始时间 | 2025-07-02 14:00:00 | | endTime | String | 是 | 结束时间 | 2025-07-02 16:00:00 | | excludeId | Long | 否 | 排除的预约 ID(修改时使用) | 1234567890123456780 | #### 响应示例 ```json { "code": 200, "msg": "操作成功", "data": [ { "id": 1234567890123456781, "venueName": "第一会议室", "applicantName": "王五", "startTime": "2025-07-02 15:00:00", "endTime": "2025-07-02 17:00:00", "reservationPurpose": "培训会议", "reservationStatus": "1" } ] } ``` ### 8. 审批场地预约 **请求方式**: `POST` **请求路径**: `/venue/reservation/approve` **权限要求**: `hq:reservation:approve` #### 请求体 ```json { "id": 1234567890123456780, "reservationStatus": "1", "approveRemark": "审批通过,请按时使用场地" } ``` #### 响应示例 ```json { "code": 200, "msg": "审批完成" } ``` --- ## 预约时间冲突检查接口 ### 1. 检查报告厅预约时间冲突 #### 接口说明 - 接口名称:检查报告厅预约时间是否存在冲突 - 接口地址:`/hq/hallReservation/checkTimeConflict` - 请求方式:POST - 接口说明:根据报告厅ID和预约时间段,检查是否与已批准的预约存在时间冲突 #### 请求参数 ```json { "hallId": "1", // 报告厅ID "startTime": "2025-01-15 09:00:00", // 预约开始时间 "endTime": "2025-01-15 12:00:00", // 预约结束时间 "excludeId": "100" // 排除的预约ID(可选,用于编辑时排除自身) } ``` #### 响应参数 ```json { "code": 200, "msg": "操作成功", "data": { "hasConflict": true, // 是否存在冲突 "conflictList": [ // 冲突的预约列表 { "id": "101", "hallId": "1", "hallName": "第一报告厅", "startTime": "2025-01-15 10:00:00", "endTime": "2025-01-15 13:00:00", "applicantName": "张三", "status": "1", // 预约状态:0-审核中,1-已批准,2-已拒绝 "auditTime": "2025-01-14 15:30:00" } ] } } ``` #### 错误码说明 | 错误码 | 说明 | |--------|------| | 200 | 成功 | | 500 | 系统错误 | | 400 | 参数错误 | #### 请求示例 ```http POST /hq/hallReservation/checkTimeConflict Content-Type: application/json { "hallId": "1", "startTime": "2025-01-15 09:00:00", "endTime": "2025-01-15 12:00:00" } ``` #### 响应示例 ```json { "code": 200, "msg": "操作成功", "data": { "hasConflict": true, "conflictList": [ { "id": "101", "hallId": "1", "hallName": "第一报告厅", "startTime": "2025-01-15 10:00:00", "endTime": "2025-01-15 13:00:00", "applicantName": "张三", "status": "1", "auditTime": "2025-01-14 15:30:00" } ] } } ``` #### 注意事项 1. 时间格式必须为:yyyy-MM-dd HH:mm:ss 2. 只检查与已批准(status=1)的预约是否冲突 3. 时间冲突的判定规则: - 新预约的开始时间在已有预约时间段内 - 新预约的结束时间在已有预约时间段内 - 新预约时间段完全包含已有预约时间段 --- ## 数据字典 ### 场地类型 (hq_venue_type) | 字典值 | 字典标签 | 说明 | | ------------ | -------- | ------------ | | meeting_room | 会议室 | 用于会议讨论 | | classroom | 教室 | 用于教学培训 | | sports_field | 运动场 | 用于体育活动 | | auditorium | 礼堂 | 用于大型活动 | | laboratory | 实验室 | 用于实验研究 | | other | 其他 | 其他类型场地 | ### 场地状态 | 状态值 | 状态名称 | 说明 | | ------ | -------- | -------------- | | 0 | 维修中 | 场地不可预约 | | 1 | 可用 | 场地可正常预约 | ### 预约状态 (hq_reservation_status) | 状态值 | 状态名称 | 说明 | | ------ | -------- | -------------------- | | 0 | 待审批 | 预约已提交,等待审批 | | 1 | 已批准 | 预约已通过审批 | | 2 | 已拒绝 | 预约被拒绝 | --- ## 权限配置 ### 场地管理权限 - `hq:venue:list` - 查看场地列表 - `hq:venue:query` - 查看场地详情 - `hq:venue:add` - 新增场地 - `hq:venue:edit` - 修改场地 - `hq:venue:remove` - 删除场地 - `hq:venue:export` - 导出场地信息 ### 预约管理权限 - `hq:reservation:list` - 查看所有预约列表 - `hq:reservation:my` - 查看我的预约 - `hq:reservation:query` - 查看预约详情 - `hq:reservation:add` - 新增预约 - `hq:reservation:edit` - 修改预约 - `hq:reservation:remove` - 删除预约 - `hq:reservation:approve` - 审批预约 - `hq:reservation:export` - 导出预约信息 --- ## 业务规则 ### 预约规则 1. **时间验证**: 开始时间必须早于结束时间 2. **未来时间**: 预约时间不能是过去时间 3. **场地状态**: 只能预约状态为"可用"的场地 4. **冲突检查**: 系统会检查时间冲突但不阻止提交 5. **权限控制**: 用户只能修改/删除自己的待审批预约 ### 审批规则 1. **审批权限**: 只有场地管理员可以审批对应场地的预约 2. **状态限制**: 只能审批"待审批"状态的预约 3. **审批记录**: 审批时必须记录审批人和审批时间 --- ## 错误码说明 | 错误码 | 错误信息 | 说明 | | ------ | -------------- | -------------------------------- | | 400 | 请求参数错误 | 请求参数格式不正确或缺少必填参数 | | 401 | 未授权访问 | 用户未登录或 token 无效 | | 403 | 权限不足 | 用户没有对应的操作权限 | | 404 | 资源不存在 | 请求的场地或预约不存在 | | 500 | 服务器内部错误 | 系统异常,请联系管理员 | ### 业务错误码 - `场地编码已存在` - 添加场地时编码重复 - `场地不存在` - 预约时指定的场地 ID 无效 - `场地当前不可用` - 预约的场地状态为维修中 - `无权限修改此预约` - 尝试修改他人的预约 - `只能修改待审批状态的预约` - 尝试修改已审批的预约 - `该预约已经审批过了` - 重复审批预约 --- ## 变更记录 ### 2025-07-01 - **[新增]** 初始版本创建 - **[新增]** 场地信息管理完整 API - **[新增]** 场地预约管理完整 API - **[新增]** 时间冲突检查功能 - **[新增]** 预约审批流程 - **[新增]** 权限控制和业务规则定义