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	意图时间块/搜索窗口的截止点	Time Pipeline
duration	Float	归一化后的会议时长（默认 1.0）	Time Pipeline
room_entity	String	用户输入的会议室名称 (或 null)	Agent (Slot)
capacity	Integer	参会人数 (默认 0)	Agent (Slot)
facilities	String[]	用户要求的设施名称列表 (默认 [])	Agent (Slot)

---

2. 筛选与排序核心 (Screening & Ranking Flow)

---

3. 详细执行逻辑 (Detailed Logic)

3.1 候选集召回 (Candidate Generation)

• 精准/语义匹配：若 room_entity 有值，对向量数据库发起检索处理。
  • 语义置信度 (Semantic Confidence)：衡量用户输入（如“305”）与空间别名语义相似度的分值。系统强制要求 $Score>0.7$ 以过滤低相关脏数据。
  • 能力过滤：强制通过 entity_type = SPACE 元数据过滤非空间意图（如规避掉名为“305”的某个传感器）。
• 容量初步过滤：若为模糊预约（未指定房间），则基于 room_capacity >= capacity 粗筛出符合条件的办公空间集合。

3.2 综合排序 (Ranking Strategy)

在发起忙闲查询前，根据用户需求类型（指定 vs. 模糊）执行差异化预排序。详细算法定义与公式参考：会议室推荐算法逻辑

• 核心评估指标 (Metric Index)：
  • 语义置信度 (Confidence)：指代“这间房是不是用户想要的”，仅在指定场景下参与评分。
  • 容量适配度 (Fit)：指代“这间房大房小用是否严重”，仅在模糊推荐场景下参与评分。
  • 业务权重 (Weight)：指代“这间房在管理侧的重要性（如 VIP 优先）”，为辅助加权项。
• 差异化排序路径：
  • 场景 A (指定房间)：主要基于 语义置信度。通过 0.9 的超高权重保障用户意图不被业务权重“劫持”。
  • 场景 B (模糊推荐)：主要基于 容量适配度。追求空间资源的最优利用率，优先推荐规格最契合的项目。

3.3 业务接口调用模式 (Execution Modes)

根据 Agent 传入的指令类型，流水线进入不同的执行分支。容量（capacity）与设施（facilities）作为并行筛选条件一并传入业务接口，由后端统一处理，Pipeline 不做先后区分。

• 模式 A：固定时间搜索 (Fixed Range Search)
  • 适用场景：NOW 或 数字时间。
  • 接口逻辑：调用业务系统标准查询接口。输入 [start_dt, end_dt] + capacity + facilities，接口返回在该全时间段内均为空闲且满足条件的会议室列表。
• 模式 B：尽快寻优搜索 (ASAP Greedy Search)
  • 适用场景：ASAP 语义标签。
  • 接口逻辑：调用业务系统 ASAP 专用接口（或由流水线对业务接口执行多次轮询）。输入搜索窗口 [start_dt, end_dt] 和会议时长 duration，接口返回该窗口内最早的一个可用空档及其对应的会议室。

3.4 结果截断与 IoT 增强 (Output Truncation)

• Top 3 截断：从 available_list 中取前 3 个最优项作为推荐。

3.5 会议室匹配与推荐 (Room Matching & Recommendation)

详细策略参考：会议室推荐算法逻辑

当用户指定会议室时，系统通过向量搜索匹配会议室，并根据匹配度判断是否"找到"或"推荐"：

1. 调用后端接口：阈值设为0，返回前N个结果（默认N=3）
2. Workflow判断：是否有 score > 前端判断阈值（默认0.5）的？
   • 有 → "找到了"，展示高分会议室
   • 没有 → "未找到，但推荐了这些"

关键参数（可配置）：

• 后端接口阈值：0
• 前端判断阈值：0.5
• 返回数量：3

---

4. 平台对接

4.1 平台元数据 (Platform Metadata)

平台	必要元数据字段	业务用途
飞书 (Feishu)	calendar_id, resource_id	查忙闲与下单绑定。
钉钉 (DingTalk)	target_id	统一标识 ID 映射。

---

5. 资源异常场景穷举 (Resource Edge Cases)

本模块承接原决策矩阵中关于“空间/资源”侧的冲突拦截逻辑：

场景	触发条件	预期 Status	Agent 预期话术
容量溢出	capacity 大于办公区所有会议室的最大上限	ERROR (OVERCAP)	"抱歉，目前最大的会议室也无法容纳 {n} 人。"
指定会议室找到了	用户指定了会议室，且有 score > 前端判断阈值的匹配结果	SUCCESS (FOUND)	"已找到符合要求的会议室如下"
指定会议室未找到但推荐	用户指定了会议室，但所有匹配结果 score < 前端判断阈值	CONFLICT (NOT_FOUND_BUT_RECOMMEND)	"抱歉，未找到您指定的会议室，为您推荐了以下会议室"
指名设施不满足	用户指定了 A 房间，但 A 房间不具备所需设施	CONFLICT (FACILITY_MISMATCH)	"抱歉，{房间名}没有{设施名}，暂不支持预订"
全域满容	搜索窗口内所有符合容量+设施要求的房间均被占用	FAIL (ALL_BUSY)	"抱歉，该时段所有会议室均已约满，建议您换个时间。"
设施全量无房	满足设施要求的房间在该时段全忙	FAIL (FACILITY_NA)	"当前时段满足{设施名}的会议室暂无可约"

容量溢出 目前接口不支持。 暂时需求优先级不高

---

6. 结果状态定义 (Return Status Table)

状态码	含义	下游 Agent 行为
SUCCESS	找到可用资源	Agent 展示：前端推荐卡片（Top 3）。
CONFLICT	指定资源冲突但有替补	Agent 引导：解释指名冲突原因，同时推送替代方案。
ERROR	硬性条件不符（如人数超限）	Agent 报错：告知资源瓶颈，引导修正需求（如减少人数）。
FAIL	时段内资源确实枯竭	Agent 话术：表示歉意，引导用户尝试其他日期。