场地预约管理 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

响应示例

{
    "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

响应示例

{
    "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

请求体

{
    "venueName": "第二会议室",
    "venueCode": "ROOM002",
    "venueLocation": "行政楼4楼",
    "venueCapacity": 30,
    "venueType": "meeting_room",
    "venueStatus": "1",
    "venueDescription": "中型会议室，适合部门会议",
    "venueImages": "/upload/venue/room002.jpg",
    "venueManagerId": 123456789,
    "venueManagerName": "李四"
}

响应示例

{
    "code": 200,
    "msg": "操作成功"
}

4. 修改场地信息

请求方式: PUT
请求路径: /venue/info
权限要求: hq:venue:edit

请求体

{
    "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

响应示例

{
    "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

响应示例

{
    "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

请求体

{
    "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": "需要音响设备和投影仪"
}

响应示例

{
    "code": 200,
    "msg": "预约申请已提交，等待审批"
}

5. 修改场地预约

请求方式: PUT
请求路径: /venue/reservation
权限要求: hq:reservation:edit

请求体

{
    "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

响应示例

{
    "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

请求体

{
    "id": 1234567890123456780,
    "reservationStatus": "1",
    "approveRemark": "审批通过，请按时使用场地"
}

响应示例

{
    "code": 200,
    "msg": "审批完成"
}

预约时间冲突检查接口

1. 检查报告厅预约时间冲突

接口说明

接口名称：检查报告厅预约时间是否存在冲突
接口地址：/hq/hallReservation/checkTimeConflict
请求方式：POST
接口说明：根据报告厅ID和预约时间段，检查是否与已批准的预约存在时间冲突

请求参数

{
  "hallId": "1",              // 报告厅ID
  "startTime": "2025-01-15 09:00:00",  // 预约开始时间
  "endTime": "2025-01-15 12:00:00",    // 预约结束时间
  "excludeId": "100"         // 排除的预约ID（可选，用于编辑时排除自身）
}

响应参数

{
  "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	参数错误

请求示例

POST /hq/hallReservation/checkTimeConflict
Content-Type: application/json

{
  "hallId": "1",
  "startTime": "2025-01-15 09:00:00",
  "endTime": "2025-01-15 12:00:00"
}

响应示例

{
  "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"
      }
    ]
  }
}

注意事项

时间格式必须为：yyyy-MM-dd HH:mm:ss
只检查与已批准（status=1）的预约是否冲突
时间冲突的判定规则：
- 新预约的开始时间在已有预约时间段内
- 新预约的结束时间在已有预约时间段内
- 新预约时间段完全包含已有预约时间段

数据字典

场地类型 (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 - 导出预约信息

业务规则

预约规则

时间验证: 开始时间必须早于结束时间
未来时间: 预约时间不能是过去时间
场地状态: 只能预约状态为"可用"的场地
冲突检查: 系统会检查时间冲突但不阻止提交
权限控制: 用户只能修改/删除自己的待审批预约

审批规则

审批权限: 只有场地管理员可以审批对应场地的预约
状态限制: 只能审批"待审批"状态的预约
审批记录: 审批时必须记录审批人和审批时间

错误码说明

错误码	错误信息	说明
400	请求参数错误	请求参数格式不正确或缺少必填参数
401	未授权访问	用户未登录或 token 无效
403	权限不足	用户没有对应的操作权限
404	资源不存在	请求的场地或预约不存在
500	服务器内部错误	系统异常，请联系管理员

业务错误码

场地编码已存在 - 添加场地时编码重复
场地不存在 - 预约时指定的场地 ID 无效
场地当前不可用 - 预约的场地状态为维修中
无权限修改此预约 - 尝试修改他人的预约
只能修改待审批状态的预约 - 尝试修改已审批的预约
该预约已经审批过了 - 重复审批预约

变更记录

2025-07-01

[新增] 初始版本创建
[新增] 场地信息管理完整 API
[新增] 场地预约管理完整 API
[新增] 时间冲突检查功能
[新增] 预约审批流程
[新增] 权限控制和业务规则定义

场地预约管理API.md 16 KB Histórico Raw

场地预约管理 API 文档

文档信息

概述

核心功能

场地信息管理 API

1. 查询场地信息列表

请求参数

响应示例

2. 获取场地详细信息

路径参数

响应示例

3. 新增场地信息

请求体

响应示例

4. 修改场地信息

请求体

5. 删除场地信息

路径参数

6. 获取可用场地列表

响应示例

场地预约管理 API

1. 查询场地预约列表

请求参数

响应示例

2. 查询我的预约列表

请求参数

3. 查询待审批预约列表

请求参数

4. 新增场地预约

请求体

响应示例

5. 修改场地预约

请求体

6. 删除场地预约

路径参数

7. 检查时间冲突

请求参数

响应示例

8. 审批场地预约

请求体

响应示例

预约时间冲突检查接口

1. 检查报告厅预约时间冲突

接口说明

请求参数

响应参数

错误码说明

请求示例

响应示例

注意事项

数据字典

场地类型 (hq_venue_type)

场地状态

预约状态 (hq_reservation_status)

权限配置

场地管理权限

预约管理权限

业务规则

预约规则

审批规则

错误码说明

业务错误码

变更记录

2025-07-01

场地预约管理API.md 16 KB

Histórico Raw