SA 空间预约：资源处理流水线 (Resource Pipeline)
文档目的：描述后端开发人员如何实现会议室的筛选、排序（召回）以及与飞书/钉钉等平台的最终下单对接。本层专注于物理资源的执行与校验。
IMPORTANT
- 总体调度 (Agent 层)：SA_空间预约_Agent设计
- 时间校验 (Logic 层)：SA_空间预约_时间处理逻辑
1. 标准化输入 (Pipeline Inputs)
Resource Pipeline 接收由前序流程（Agent 或 Time Pipeline）标准化后的参数。
| 参数名称 | 类型 | 说明 | 来源 |
|---|---|---|---|
start_dt | Standard ISO | 归一化后的开始时间戳 | Time Pipeline |
end_dt | Standard ISO | 结合 duration 计算后的结束时间戳 | Time Pipeline |
room_entity | String | 用户输入的会议室名称 (或 null) | Agent (Slot) |
capacity | Integer | 参会人数 (若为 null 则在 Pipeline 内部逻辑默认补全为 2) |
2. 筛选与排序核心 (Screening & Ranking Flow)
3. 详细执行逻辑 (Detailed Logic)
3.1 候选集召回 (Candidate Generation)
- 精准/语义匹配：若
room_entity有值，使用向量数据库检索 Top 10，并强制通过entity_type = SPACE元数据过滤掉非空间实体。 - 容量兜底：若
capacity为空，Pipeline 内部自动赋值为2进行筛选。
3.2 忙闲检查 (Availability Check)
- 批量查询：对候选集并行发起
POST /calendar/v4/freebusy/list。 - 状态同步：仅保留在
[start_dt, end_dt]范围内状态为free的空间，得到available_list。
3.3 结果排序 (Ranking Strategy)
详细算法细节请参考：会议室推荐算法逻辑
- 场景 A (指定房间)：即便有多个相似匹配，原指定的房间（或别名匹配最高者）排在首位（策略 A）。
- 场景 B (未指定房间)：按“容量利用率”排序，优先推荐容量最接近且刚好满足
capacity的房间（策略 B）。
3.4 冲突处理 (Conflict Handler)
详细冲突处理策略请参考：会议室推荐算法逻辑 当 available_list 为空时触发：
- 挪时间：在同一地点寻找前后 1-2 小时内的最近空位。
- 换房间：推荐同一楼层或相邻楼层容量规格一致的可用房间。
4. 平台对接与物联集成
4.1 平台元数据 (Platform Metadata)
| 平台 | 必要元数据字段 | 业务用途 |
|---|---|---|
| 飞书 (Feishu) | calendar_id, resource_id | 查忙闲与下单绑定。 |
| 钉钉 (DingTalk) | target_id | 统一标识 ID 映射。 |
4.2 物联状态回传 (IoT Status)
推荐时触发 GET /hub/v1/spaces/{space_id}/status，在回复中体现：
- 房间名称 + 实时环境状态（如：“火星厅，当前 24℃，适宜开会”）。
5. 结果状态定义 (Return Status Table)
| 状态码 | 含义 | 下游 Agent 行为 |
|---|---|---|
SUCCESS | 找到可用资源 | Agent 展示：前端推荐卡片（Top 3）。 |
CONFLICT | 冲突但在处理中有替代方案 | Agent 引导：告知冲突原因，同时推送替代方案卡片。 |
FAIL | 无房可用且无推荐建议 | Agent 话术：表示歉意，建议用户尝试其他日期。 |