SA 会议系统：第三方日历集成 — 配置与交互
文档状态：V4.2 编写日期：2026-07-16（V4.2 更新：2026-08-04） 定位：第三方日历集成的管理后台配置页面设计，涵盖入口页面与三步向导的交互细节。
0. V4.1 变更点
| # | 变更 | 说明 |
|---|---|---|
| 1 | 向导保持 3 步 | 「选择范围」不独立成步；第 3 步「导入会议室」顶部为拉取范围条（飞书建筑筛选 building_id，切换重拉并清空勾选），下方为筛选栏（搜索，本地过滤不清勾选） |
| 2 | 选区模型 | 导入改为「过滤 → 分页 → 勾选/全选 → 只导入勾选房间」，取消勾选即移出 |
| 3 | 空间关联移出向导 | 导入时持久化第三方路径（provider_path），关联动作统一放到「会议室管理」页 |
| 4 | 导入语义 | 按 provider_room_id upsert，保留已存在房间的人工配置 |
| 5 | 只导入启用房间 | 拉取时过滤 is_disabled=false，停用房间不展示、不导入；无状态筛选/状态列 |
| 6 | 容量目标 | 支持 200+ 间（项目楼 19 层）乃至上千间（飞书全集团）的拉取与导入 |
| 7 | 去掉名称编辑列 | 第 3 步表格移除「名称」可编辑列，导入直接采用平台会议室名称 |
| 8 | 设备数据字典移出导入向导 | 移除第 3 步「设备数据字典」预览区（飞书无设备字典接口）；改为导入时校验：解析所选会议室涉及的设备类型，若未在数据字典登记则报错并引导先创建，MVP 阶段不再自动生成 |
接口能力与选型依据见《第三方日历集成_接口调研》。
1. 页面入口
页面入口位于管理后台左侧 app-nav 图标栏。
此页面配置的是会议系统与第三方日历的集成，逻辑上应放在会议 App 导航中（与会议预约/我的会议/会议室管理同级）。app-nav 中仅为原型演示方便。
2. 入口页面：集成总开关
首次进入页面时，展示集成状态总览，决定是否启用三方日历集成。
2.1 未启用状态（首次进入）
+----------------------------------------------------+
| 第三方日历集成 |
| |
| 当前状态：未启用 |
| |
| 启用后，会议 App 的预定/查询/取消等操作将自动 |
| 同步至第三方日历（飞书或钉钉） |
| |
| [开启集成] |
+----------------------------------------------------+- "开启集成"→ 进入三步向导
2.2 已启用状态（配置完成后）
+----------------------------------------------------+
| 第三方日历集成 |
| |
| 当前状态：已启用 |
| 已对接平台：飞书-生产环境 |
| 最近导入：2026-08-04 10:30（200 间会议室） |
| 已导入会议室：200 间（空间未关联 35 间） |
| |
| [重新配置] [停用集成] |
+----------------------------------------------------+- "重新配置"→ 进入三步向导，回填已有数据
- "停用集成"→ 关闭三方同步，保留配置数据
- "已导入会议室"行：展示导入总量与空间未关联数，提示后续到会议室管理页处理
3. 三步设置向导
顶部步骤条指示当前进度，底部"上一步/下一步"按钮控制流转。
+----------------------------------------------------------+
| 首页 / 第三方日历集成 |
| |
| +--------+ +--------+ +----------+ |
| | 1.选择 |->| 2.认证 |->| 3.导入 | |
| | 平台 | | 配置 | | 会议室 | |
| +--------+ +--------+ +----------+ |
| |
| +----------------------------------------------------+ |
| | 各步骤内容区域 | |
| +----------------------------------------------------+ |
| |
| [上一步] [下一步 ->] |
+----------------------------------------------------------+已完成/当前步骤可回退修改，未到步骤不可跳转。每个步骤的数据在本步骤确认后持久化。第 3 步「导入会议室」进入时自动拉取（飞书按所选建筑过滤），顶部拉取范围条换建筑（重新拉取），下方筛选栏搜索（本地过滤）。
4. 步骤一：选择平台
单选，互斥。选择后"下一步"按钮启用。
+----------------------------------------------------+
| 1. 选择平台 |
| |
| +------------------------------------------------+ |
| | O 飞书 (Feishu) | |
| | 认证：AppID + AppSecret | |
| | 返回：会议室名、容量、设备、楼宇/楼层路径 | |
| +------------------------------------------------+ |
| +------------------------------------------------+ |
| | O 钉钉 (DingTalk) | |
| | 认证：AppKey + AppSecret | |
| | 返回：会议室名、容量、设备标签 | |
| +------------------------------------------------+ |
| |
| [取消] [下一步 ->] |
+----------------------------------------------------+5. 步骤二：认证配置
根据上一步选择的平台，动态显示对应的认证表单。
+----------------------------------------------------+
| 2. 认证配置 - 飞书 |
| |
| -- 认证凭据 -- |
| App ID * [cli_a7f8e2________________] |
| App Secret * [********____________________] |
| |
| [测试连接] |
| -------------------------------------------------|
| + 连接成功！可查询到 210 间会议室资源（全集团） |
| |
| [上一步] [下一步 ->] |
+----------------------------------------------------+- 飞书显示 AppID + AppSecret，钉钉显示 AppKey + AppSecret
- "测试连接"成功后显示绿色提示，并展示全集团可查询总量
- "下一步"进入导入会议室（自动触发拉取）
6. 步骤三：导入会议室
6.1 拉取中状态
进入本步自动拉取，按分页循环执行（page_token / nextToken 直到 has_more=false），实时显示进度。
+--------------------------------------------------------------+
| 3. 导入会议室 - 飞书（总部大楼·项目楼） |
| |
| @ 正在从 飞书-生产环境（总部大楼·项目楼） |
| 拉取会议室数据... |
| 已拉取 120 / 190 间（第 2 页，共 10 页） |
| |
| [上一步] [取消] |
+--------------------------------------------------------------+6.2 预览与编辑
拉取范围条（决定"从哪拉"，仅飞书，服务端范围）：
+--------------------------------------------------------------------+
| 📍 拉取范围 [总部大楼·项目楼(约190间) v] 切换建筑会重新拉取并清空勾选 |
+--------------------------------------------------------------------+- 来源
meeting_room/building/list，显示建筑名（label）、携带 building_id - 切换建筑 → 按新 building_id 重新拉取，并清空已勾选（范围条保留可见，仅表格区转圈）
- 钉钉无此条（接口不支持按楼宇过滤），改为一行提示："钉钉接口不支持按楼宇过滤，已全量拉取全部会议室，可用搜索 / 勾选圈定导入范围"
筛选栏（决定"看哪些"，两平台通用，本地过滤）：
+--------------------------------------------------------------+
| [搜索名称/路径...________] 已选 0 / 共 190 间 |
+--------------------------------------------------------------+- 搜索框：名称 / 路径本地模糊过滤（不清勾选）
- 实时计数：
已选 N / 共 M 间（N = 当前筛选结果中已勾选数，跨页累计；M = 筛选结果数）
会议室表格（只显示启用状态房间，is_disabled=false）：
[] | 平台会议室 | 路径/位置 | 人数 | 设备(飞书)
[x]| F5-01 金朵云| 总部大楼>5F | 20 | 投影·电话
[ ]| F5-02 路演厅| 总部大楼>5F | 20 | 电视
...（每页 20 条）
< 1 2 3 ... 10 >- checkbox 列：表头全选/全不选（作用于当前筛选结果）；跨页勾选保留（勾选集合独立于分页）
- 路径/位置列：飞书显示 建筑>楼层；钉钉显示
roomLocation文本位置 - 名称直接采用平台会议室名称（无编辑列，导入即用）
- 不提供状态列/状态筛选——只从第三方拉取启用房间，停用房间不进入列表（来源
is_disabled过滤）
分页：20 条/页，上一页/下一页 + 页码
导入按钮：文案随勾选数变化，如「导入勾选的 80 间」；未勾选时禁用
设备数据字典（导入时校验）：
- 移除第 3 步「设备数据字典」预览区——飞书/钉钉均无设备字典接口，无法在拉取阶段获取设备类型清单
- 改为点击「导入」时校验：自动解析所选会议室涉及的设备类型，与会议系统数据字典比对
- 全部已登记 → 正常进入导入确认
- 存在未登记类型 → 拦截报错，列出缺失类型，提示先到「数据字典」登记后再导入：
+------------------------------+ | (!) 设备类型未登记 | +------------------------------+ | 所选会议室涉及 2 种设备类型 | | 尚未登记： [视频设备][电话] | | 请先到「数据字典」登记后 | | 再回来导入。 | | | | [取消导入] [去创建数据字典] | +------------------------------+ - MVP 策略（对齐开发反馈）：缺失时先人工创建数据字典再导入，报错提示仅引导用户去登记，不涉及标识符规则
- 后续迭代：自动生成数据字典（解析所选会议室设备、按
device_xxx规则自动生成 identifier 落库），不在 MVP 范围内
6.3 平台差异
| 能力 | 飞书 | 钉钉 |
|---|---|---|
| 拉取范围条 | 建筑下拉（building_id 过滤），切换重拉并清勾选 | 无（接口不支持），全量拉取 + 提示 |
| 设备数据字典 | 无接口，导入时校验（同上） | 无接口，导入时校验（同上） |
| 路径/位置列 | 结构化 建筑>楼层 | 自由文本 roomLocation |
6.4 导入确认
仅当存在「勾选中、但本地已存在 provider_room_id」的房间时，提示 upsert 影响（见 §7）：
+------------------------------+
| (!) 确认导入 |
+------------------------------+
| 将导入 80 间： |
| 新增 55 间 / 更新 25 间 |
| （已存在房间将保留人工配置） |
| |
| [取消] [确认导入] |
+------------------------------+导入完成后回到入口页面，显示"已启用"状态及未关联提示。
7. 导入语义
默认规则：按 provider_room_id upsert。
| 情形 | 处理 |
|---|---|
| provider_room_id 不存在 | 插入新房间（写入名称/容量/设备/provider_path/状态） |
| provider_room_id 已存在 | 更新基础字段（名称/容量/设备/状态/path），保留人工配置（如空间关联、设备 identifier 调整） |
| 源端已下架、本地仍保留 | 默认保留，并在导入结果中提示「本地多出 N 间（源端已下架）」；不勾选不处理 |
导入为"增量同步"模型，不提供"清空后重导"（会丢失人工配置）。如确需全量重建，需人工在会议室管理页处理后另行操作。
8. 空间关联（变更：移出导入向导）
8.1 决策
V3.0 在导入预览中逐行做空间关联（级联选择器）。V4.x 起移除，原因：
- 200+ 间逐行操作不可用；
- 空间关联是持续维护动作，不是一次性导入动作，更适合常态维护的「会议室管理」页。
8.2 路径持久化
飞书路径只在导入时能获取（building/floor 来自接口），故导入时持久化为 provider_path 字段：
- 仅三方来源房间有值，自建房间为空（不污染通用房间表）
- 管理页不展示该字段，它只作为后续「空间关联」的匹配输入（楼层名匹配的原料）
8.3 关联落点：会议室管理页
空间关联统一在「会议室管理」页完成：
+--------------------------------------------------------------+
| 会议室管理 - 空间关联 |
| |
| [未关联: 35] [已关联: 165] [搜索...] |
| |
| [智能关联]（大模型一键匹配） [按楼层批量关联] |
| |
| [ ] | 会议室 | 楼层/路径 | 空间位置 | 操作 |
| [x] | F5-01 金朵云| 总部大楼>5F | 总部大楼>5F>501 | ✓ |
| [ ] | F5-02 路演厅| 总部大楼>5F | 未关联 | [选择] |
| ... |
| |
| [确认写入 N 条关联] |
+--------------------------------------------------------------+- 未关联筛选：一键只看未关联房间
- 按楼层批量关联：
provider_path楼层 → 空间树楼层节点批量映射 - 智能关联：大模型输入（房间名 + 楼层）匹配空间树节点，输出建议，确认后批量写入；匹配率低的标出人工兜底
- 手动单间关联：保留级联选择器作兜底
8.4 导入完成提示
导入完成回到入口页时，若存在未关联房间，明确提示后续动作：
导入完成！共导入 200 间会议室
35 间尚未关联空间位置，可到「会议室管理」页处理。9. 平台差异汇总
| 能力 | 飞书 | 钉钉 |
|---|---|---|
| 拉取范围条（Step 3 顶部） | 建筑下拉（building_id 结构化过滤），切换重拉并清勾选 | 无（接口不支持），全量拉取 + 提示 |
| 设备数据字典 | 无接口，导入时校验缺失类型并引导登记 | 无接口，导入时校验缺失类型并引导登记 |
| 路径/位置列 | 结构化 建筑>楼层 | 自由文本 roomLocation |
| 认证维度 | AppID+AppSecret（企业 token） | AppKey+AppSecret + 需 unionId |
| 分页 | page_token ≤1000（meeting_room-v1） | nextToken ≤100 |
| 权限 | calendar:room:readonly / vc:room:readonly | 视频会议信息读权限 |