cykj/hzdyjs

0 Fork 0

Files

T

zlwu 210313e9ba feat: add time conflict check bo/vo and update docs

2025-07-10 08:30:09 +08:00

13 KiB

Raw Blame History

报告厅预约审核 API 文档

文档信息

文档名称: 报告厅预约审核 API 文档
创建时间: 2025-01-09
维护负责人: 开发团队
最后更新: 2025-01-09 16:30:00

概述

报告厅预约审核模块提供专门的报告厅预约审核功能 API 接口，包括审核建议生成、时间冲突检查、批量审核等核心功能。该模块主要面向管理员用户，用于对用户提交的报告厅预约申请进行审核处理。

核心功能

📋 预约列表查询：查询待审核和已审核的报告厅预约申请
🔍 时间冲突检查：智能检测预约时间是否与已批准的预约冲突
💡 审核建议生成：基于时间冲突检查结果自动生成审核建议
✅ 批量审核处理：支持批准/拒绝单个或多个预约申请
📊 审核记录管理：记录审核人、审核时间、审核备注等详细信息

技术特点

智能冲突检测：精确的时间重叠算法，避免预约冲突
批量操作支持：高效处理多个预约的审核操作
权限控制严格：完整的权限验证机制
日志记录完整：详细的操作日志和审核轨迹

🔐 基础规范

请求头规范

所有需要认证的接口都必须在请求头中携带：

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

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

响应示例

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

响应示例

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

请求体

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

响应示例

无冲突时：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "hasConflict": false,
        "conflictList": [],
        "conflictMessage": "无时间冲突"
    }
}

有冲突时：

{
    "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 个时间冲突的已批准预约"
    }
}

时间冲突判定规则

两个时间段存在冲突的条件：

新预约开始时间 < 已存在预约结束时间
新预约结束时间 > 已存在预约开始时间

即：startTime < existingEndTime AND endTime > existingStartTime

冲突检查逻辑

同一报告厅：只检查相同报告厅ID的预约
已批准状态：只检查状态为"1"（已批准）的预约
排除自身：修改预约时可以通过excludeId排除自身
精确匹配：使用数据库时间比较，确保检查准确性