# 会议室预定 — 小鱼易联终端 PRD

> **版本**: v1.0
> **日期**: 2026-07-15
> **作者**: 许清楚 (Xu) · 产品经理
> **状态**: 待评审
> **所属项目**: `wecom_it_smart_desk` — IT智能服务台
> **子系统**: 08-集成生态
> **模块**: 会议室预定

---

## 1. 项目信息

| 字段 | 值 |
|------|-----|
| **项目名称** | `meetingroom_booking` |
| **技术栈** | 终端页面: Vue3 + Tailwind CSS（横屏大屏适配）/ 后端: FastAPI + SQLAlchemy + PostgreSQL + Redis / 企微API: 会议室预定管理 + 会议室管理 / 小鱼易联: 终端管理API + Web SDK |
| **语言** | 中文 |
| **集成范围** | 小鱼易联终端定制页面 + 企微会议室预定API + 小鱼易联终端管理API |
| **UI风格** | 深色主题（适配会议室大屏），大字号触控交互，accent = #07C160（企微绿） |

### 原始需求复述

税友集团IT支持组希望通过小鱼易联终端（安装在会议室的物理大屏设备）实现会议室预定功能。核心诉求：

1. 在小鱼易联终端上定制页面，集成企微自定义应用中的会议室预定能力
2. 员工可通过H5/企微/终端页面多入口自助预定，预定结果同步到小鱼易联终端显示
3. 有小鱼易联API文档+开发者账号，企微侧也有会议室API可对接

### 架构决策（初步方案）

采用**企微会议室API为数据源 + 小鱼易联终端为展示端 + 现有后端为中间层**的架构：

```
┌─────────────────────────────────────────────────────────────────────┐
│                        系统架构概览                                   │
│                                                                     │
│  ┌──────────┐     ┌──────────────┐     ┌──────────────────────┐    │
│  │ 企微H5端  │     │ 企微客户端App │     │ 小鱼易联终端（大屏）   │    │
│  │ (Vant4)  │     │  (会议室入口)  │     │ (Vue3+Tailwind)      │    │
│  └─────┬────┘     └──────┬───────┘     └──────────┬───────────┘    │
│        │                 │                        │                │
│        └────────┬────────┘                        │                │
│                 │                                 │                │
│          ┌──────▼───────────────────────────────▼──────┐          │
│          │        现有后端 (FastAPI + Redis)             │          │
│          │                                          │          │
│          │  ┌─────────────┐  ┌──────────────────┐   │          │
│          │  │ 会议室API   │  │ 终端管理API      │   │          │
│          │  │ (企微对接)  │  │ (小鱼易联对接)   │   │          │
│          │  └──────┬──────┘  └────────┬─────────┘   │          │
│          └─────────┼─────────────────┼─────────────┘          │
│                    │                 │                         │
│          ┌─────────▼─────┐ ┌────────▼──────────┐              │
│          │ 企微会议室API  │ │ 小鱼易联开放平台   │              │
│          │ (get_booking  │ │ (终端管理/SDK)    │              │
│          │  book/cancel) │ │                  │              │
│          └───────────────┘ └──────────────────┘              │
└─────────────────────────────────────────────────────────────────────┘
```

**关键设计决策**：
- 企微会议室API为**唯一数据源**（single source of truth），不在本地维护独立的预定数据
- 后端作为中间层：代理企微API调用（处理鉴权/限流/缓存），同时对接小鱼易联终端管理
- 终端页面通过浏览器/WebView运行，与后端通过REST API + WebSocket通信

---

## 2. 产品定义

### 2.1 产品目标

| # | 目标 | 衡量标准 |
|---|------|---------|
| G1 | **终端可视化会议室状态**：在会议室物理大屏上实时显示当前会议室的预定状态、即将到来的会议、空闲时段，让路过的人一眼看到是否可用 | 终端页面打开后3秒内显示完整状态；状态更新延迟不超过30秒 |
| G2 | **多入口自助预定闭环**：员工可通过企微H5、企微客户端、终端大屏三个入口完成「查看空闲→预定→取消」全流程，预定结果三端同步 | 任意入口预定后，其他入口在30秒内显示更新；预定操作完成时间不超过15秒 |
| G3 | **与现有IT智能服务台无缝集成**：会议室预定作为IT智能服务台的新功能模块复用现有后端基础设施（鉴权/Redis/企微对接），不引入新的独立服务 | 复用现有Settings配置体系和数据库连接；新增代码以模块化方式集成到`backend/app/`，不破坏现有功能 |

### 2.2 用户故事

| # | 角色 | 用户故事 |
|---|------|---------|
| US-1 | 普通员工 | **As a** 员工, **I want** 在会议室门口的大屏上看到当前会议室是否空闲、下一个会议什么时候开始, **so that** 我不用打开手机就能判断能否临时使用这个会议室 |
| US-2 | 普通员工 | **As a** 员工, **I want** 在终端大屏上直接点击空闲时段完成预定, **so that** 临时开会时不用掏手机操作，30秒内就能预定成功 |
| US-3 | 普通员工 | **As a** 员工, **I want** 在企微H5端或企微客户端查看所有会议室的空闲状态并预定, **so that** 在回到会议室之前就提前预定好，到场直接使用 |
| US-4 | 普通员工 | **As a** 员工, **I want** 预定后能随时取消（通过终端或企微）， **so that** 会议取消后及时释放会议室资源 |
| US-5 | IT管理员 | **As a** IT管理员, **I want** 在管理后台查看所有会议室的预定情况和使用率统计, **so that** 能识别热门/冷门会议室，优化资源配置 |
| US-6 | IT管理员 | **As a** IT管理员, **I want** 将会议室与小鱼易联终端设备绑定（SN映射）， **so that** 终端自动显示对应会议室的状态 |
| US-7 | 访客 | **As a** 访客, **I want** 在终端大屏上看到会议室名称和当前状态（无需登录即可查看）, **so that** 找会议室时能快速确认位置 |

---

## 3. 需求池（P0/P1/P2）

### P0 — 必须实现（Must Have）

#### P0-1 企微会议室API对接 — access_token管理

| 项 | 说明 |
|------|------|
| **需求** | 在现有`WecomService`中新增会议室专用access_token管理。企微会议室API需要独立的"会议室"secret获取access_token（不同于普通应用secret和通讯录secret） |
| **实现** | 在`config.py`中新增`wecom_meetingroom_secret`配置项；在`WecomService`中新增`get_meetingroom_access_token()`方法，复用Redis缓存模式（key: `wecom:meetingroom_access_token`，TTL: 6900秒） |
| **验收** | 能成功获取会议室access_token；token缓存命中时不重复请求企微接口；token过期前自动刷新 |

#### P0-2 会议室列表查询接口

| 项 | 说明 |
|------|------|
| **需求** | 后端新增API：`GET /api/meetingroom/list`，代理调用企微会议室列表接口`POST /cgi-bin/oa/meetingroom/list`，返回会议室列表（ID、名称、容量、位置、设备、是否需要审批） |
| **缓存** | 会议室列表变化频率低，Redis缓存10分钟 |
| **验收** | 返回完整的会议室信息；支持按城市/楼宇/楼层过滤；缓存失效后自动刷新 |

#### P0-3 会议室预定状态查询接口

| 项 | 说明 |
|------|------|
| **需求** | 后端新增API：`GET /api/meetingroom/{meetingroom_id}/booking?date=YYYY-MM-DD`，代理调用企微`POST /cgi-bin/oa/meetingroom/get_booking_info`，返回指定会议室在指定日期的预定情况列表 |
| **限制** | 企微API不支持跨天查询，后端按日期维度封装 |
| **缓存** | 缓存30秒（保证实时性同时减少API调用） |
| **验收** | 返回预定列表（booking_id、start_time、end_time、booker、status）；时间戳转为可读时间格式 |

#### P0-4 预定会议室接口

| 项 | 说明 |
|------|------|
| **需求** | 后端新增API：`POST /api/meetingroom/book`，代理调用企微`POST /cgi-bin/oa/meetingroom/book` |
| **参数** | meetingroom_id、subject（会议主题）、start_time、end_time、booker（预定人userid）、attendees（参与人列表，可选） |
| **限制** | 时间自动按30分钟取整；仅可预定无需审批的会议室 |
| **验收** | 预定成功返回booking_id；时间冲突时返回明确错误信息；预定成功后立即清除该会议室的状态缓存 |

#### P0-5 取消预定接口

| 项 | 说明 |
|------|------|
| **需求** | 后端新增API：`DELETE /api/meetingroom/booking/{booking_id}`，代理调用企微`POST /cgi-bin/oa/meetingroom/cancel_book` |
| **参数** | booking_id、meetingroom_id（企微取消接口需要booking_id即可，但查询需要meetingroom_id+booking_id） |
| **验收** | 取消成功返回确认；取消后立即清除缓存；非预定人取消时返回权限错误 |

#### P0-6 终端页面 — 会议室状态展示

| 项 | 说明 |
|------|------|
| **需求** | 新建前端项目（或模块）`frontend-terminal`，使用Vue3 + Tailwind CSS，为小鱼易联终端大屏定制横屏页面 |
| **页面** | 终端状态页：全屏显示当前绑定的会议室名称、当前状态（空闲/使用中）、当前进行中的会议信息、时间轴展示当日预定情况 |
| **适配** | 1920×1080横屏适配；大字号（标题48px+，正文24px+）；深色主题减少大屏眩光 |
| **验收** | 页面在终端浏览器/WebView中正常渲染；3秒内加载完毕；空闲/使用中状态视觉区分明显 |

#### P0-7 终端页面 — 快速预定

| 项 | 说明 |
|------|------|
| **需求** | 终端页面支持点击时间轴上的空闲时段进行快速预定 |
| **交互** | 点击空闲时段→弹出预定面板（输入会议主题、选择时长）→确认预定→显示预定结果→3秒后返回状态页 |
| **鉴权** | 终端预定时需要身份识别：扫码登录（企微扫码）或输入工号+姓名（访客模式仅查看，不可预定） |
| **验收** | 30分钟以内的空闲时段可一键预定；预定结果实时显示在终端页面上 |

#### P0-8 终端-会议室绑定关系管理

| 项 | 说明 |
|------|------|
| **需求** | 后端新增`terminal_room_binding`表，存储小鱼易联终端SN与企微会议室ID的映射关系 |
| **字段** | terminal_sn（终端序列号）、meetingroom_id（企微会议室ID）、terminal_name（终端名称）、location（位置描述）、created_at、updated_at |
| **管理** | 管理后台CRUD接口：`GET/POST/PUT/DELETE /api/admin/terminal-bindings` |
| **验收** | 支持一个终端绑定一个会议室；绑定后终端页面自动加载对应会议室的状态 |

### P1 — 应该实现（Should Have）

#### P1-1 实时状态同步 — WebSocket推送

| 项 | 说明 |
|------|------|
| **需求** | 当会议室预定状态发生变化时（预定/取消），通过WebSocket实时推送到绑定的终端页面 |
| **方案** | 复用现有WebSocket基础设施（`ws.py`），新增终端WS端点`/ws/terminal/{terminal_sn}`。状态变更触发时：①清除Redis缓存 ②向已连接的终端推送状态更新消息 |
| **降级** | WebSocket不可用时，终端页面降级为30秒轮询 |
| **验收** | 一个入口预定后，其他入口的终端在5秒内显示更新；WS断线后自动降级为轮询 |

#### P1-2 企微回调 — 预定变更通知

| 项 | 说明 |
|------|------|
| **需求** | 配置企微事件回调，当会议室预定状态发生变化（企微客户端预定/取消/审批通过）时接收通知，主动刷新缓存并推送WS消息 |
| **回调** | 企微回调URL配置在管理后台，接收事件后调用`get_booking_info`刷新缓存 |
| **验收** | 企微客户端预定后，终端在10秒内收到更新（含回调延迟） |

#### P1-3 多会议室切换

| 项 | 说明 |
|------|------|
| **需求** | 终端页面支持查看其他会议室的状态（点击侧边栏/下拉选择） |
| **交互** | 顶部会议室名称可点击→弹出会议室选择列表（显示名称+位置+实时状态）→选择后切换显示 |
| **验收** | 切换后3秒内加载目标会议室状态；支持按楼宇/楼层筛选 |

#### P1-4 终端页面 — 会议详情展示

| 项 | 说明 |
|------|------|
| **需求** | 点击时间轴上的已预定时段，展示会议详情（主题、预定人、参与人、时间） |
| **限制** | 终端仅展示预定人姓名（不展示userid），参与人列表最多显示5人 |
| **验收** | 点击后弹出详情面板；信息来源为企微`bookinfo/get`接口 |

#### P1-5 H5端会议室预定页面

| 项 | 说明 |
|------|------|
| **需求** | 在现有H5端（Vue3 + Vant4）新增会议室预定页面，员工可在手机上查看所有会议室状态并预定 |
| **入口** | H5端首页新增「会议室」入口卡片 |
| **功能** | 会议室列表→选择会议室→查看时间轴→选择空闲时段→预定/取消 |
| **验收** | 移动端交互流畅；预定结果同步到终端和企微客户端 |

#### P1-6 小鱼易联终端管理API集成

| 项 | 说明 |
|------|------|
| **需求** | 通过小鱼易联开放平台API实现终端设备管理：根据终端SN查询设备状态、推送自定义页面URL到终端 |
| **接口** | 小鱼易联API基础URL：`https://sdk.xylink.com/api/rest/external/v1/`，使用enterpriseId + token鉴权（支持签名1.0/2.0） |
| **功能** | ① 终端注册时自动上报SN ② 管理后台可远程推送页面URL到指定终端 ③ 查询终端在线状态 |
| **验收** | 能通过API查询终端在线状态；能远程推送页面URL |

### P2 — 可以实现（Nice to Have）

#### P2-1 会议室使用统计报表

| 项 | 说明 |
|------|------|
| **需求** | 管理后台提供会议室使用率统计：按会议室/日期/时段统计预定时长、实际使用时长、空闲率 |
| **数据来源** | 每日定时拉取预定记录存入本地数据库（作为统计快照，非实时数据源） |
| **验收** | 支持按周/月查看统计图表；支持导出Excel |

#### P2-2 会议室维护模式

| 项 | 说明 |
|------|------|
| **需求** | 管理员可将会议室设为"维护中"状态，终端页面显示维护提示，禁止预定 |
| **实现** | 本地维护状态表，终端查询时叠加本地状态判断 |
| **验收** | 维护模式下终端显示维护提示；恢复后自动恢复预定功能 |

#### P2-3 终端页面 — 会议提醒

| 项 | 说明 |
|------|------|
| **需求** | 会议开始前5分钟，终端页面弹出提醒（如有下一个会议即将开始） |
| **验收** | 提醒动画醒目但不影响当前操作；5分钟后自动消失 |

#### P2-4 终端页面 — 二维码预定

| 项 | 说明 |
|------|------|
| **需求** | 终端页面显示企微预定二维码，员工可扫码后在手机上完成预定 |
| **验收** | 二维码指向H5端预定页面（带会议室ID参数）；扫码后自动选中当前会议室 |

#### P2-5 小鱼易联Web SDK — 视频会议集成

| 项 | 说明 |
|------|------|
| **需求** | 预定会议后，可在终端上一键发起小鱼易联视频会议，将会议链接关联到企微预定记录 |
| **SDK** | `@xylink/xy-rtc-sdk`，初始化需要clientId + clientSecret + extId（企业ID） |
| **验收** | 终端可发起视频会议；会议信息关联到企微日程 |

---

## 4. UI设计稿（文字描述）

### 4.1 终端状态页（主页面）

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  📍 18F-会议室A                  2026-07-15 周三                    14:32   │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│                                                                             │
│                              ┌──────────────┐                              │
│                              │              │                              │
│                              │    空闲中    │    ← 当前状态（大字 96px）    │
│                              │              │                              │
│                              └──────────────┘                              │
│                                                                             │
│  距下一个会议：28分钟                                                        │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  今日日程                                              14:32 ▮      │   │
│  │  ┌─────────┐  ┌──────────────┐  ┌──────────────────┐  ┌──────────┐ │   │
│  │  │ 09:00   │  │ 10:00        │  │ 14:00            │  │ 15:00    │ │   │
│  │  │ ~ 10:00 │  │ ~ 11:30      │  │ ~ 15:00 ← 进行中  │  │ ~ 16:00  │ │   │
│  │  │ 周度例会 │  │ 产品评审      │  │ 技术方案讨论      │  │ 空闲可预定│ │   │
│  │  │ 张三     │  │ 李四         │  │ 王五              │  │  点击预定 │ │   │
│  │  └─────────┘  └──────────────┘  └──────────────────┘  └──────────┘ │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  [ 📱 扫码预定 ]              [ 🔄 切换会议室 ]    [ ❓ 使用帮助 ]   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
```

**设计要点**：
- **深色主题**：背景 `#1a1a2e`，卡片 `#16213e`，减少大屏眩光
- **状态色**：空闲 = `#07C160`（企微绿），使用中 = `#FF6B6B`（红色），即将开始 = `#FFA502`（橙色）
- **字体**：当前状态 96px，会议室名称 36px，时间轴 20px，操作按钮 24px
- **时间轴**：横向滚动，每个时段卡片宽度固定，当前时间用竖线标记
- **空闲时段**：显示「点击预定」提示，可点击
- **已预定时段**：显示会议主题和预定人，不可点击（仅查看）

### 4.2 快速预定弹窗

```
┌───────────────────────────────────┐
│  📅 预定会议室                      │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│                                   │
│  会议室：18F-会议室A               │
│  时段：15:00 ~ 15:30               │
│                                   │
│  会议主题：                         │
│  ┌─────────────────────────────┐  │
│  │ 请输入会议主题               │  │
│  └─────────────────────────────┘  │
│                                   │
│  时长：                            │
│  [ 30分钟 ] [ 60分钟 ] [ 90分钟 ] │
│  [ 自定义 ]                        │
│                                   │
│  预定人：张三（扫码登录）           │
│                                   │
│  ┌─────────────┐ ┌──────────────┐ │
│  │    取消      │ │   确认预定    │ │
│  └─────────────┘ └──────────────┘ │
└───────────────────────────────────┘
```

### 4.3 交互流程

```
终端页面加载
  │
  ├── 读取终端SN → 查询绑定关系 → 获取meetingroom_id
  │     └── 无绑定 → 显示「请联系IT管理员绑定会议室」提示页
  │
  ├── 获取会议室信息 + 当日预定状态
  │     └── 加载失败 → 显示错误页面 + 重试按钮
  │
  ├── 渲染状态页
  │     ├── 空闲 → 显示「空闲中」+ 时间轴空闲时段可点击
  │     └── 使用中 → 显示「使用中」+ 当前会议信息
  │
  ├── 用户点击空闲时段
  │     ├── 未登录 → 弹出企微扫码登录二维码
  │     │     └── 扫码成功 → 获取userid → 进入预定弹窗
  │     └── 已登录 → 直接进入预定弹窗
  │
  ├── 确认预定
  │     ├── 调用后端API → 企微book接口
  │     ├── 成功 → 显示「预定成功」动画 → 3秒后返回状态页（状态已更新）
  │     └── 失败 → 显示错误原因（冲突/权限/网络） → 返回预定弹窗
  │
  └── 实时更新
        ├── WebSocket连接 → 收到状态变更 → 刷新页面
        └── WebSocket断线 → 降级为30秒轮询
```

### 4.4 H5端预定页面

```
┌─────────────────────────┐
│  ← 会议室预定            │
│  ━━━━━━━━━━━━━━━━━━━━━ │
│                         │
│  📍 选择会议室           │
│  ┌───────────────────┐  │
│  │ 18F-会议室A  10人  │  │
│  │ ● 空闲            │  │
│  └───────────────────┘  │
│  ┌───────────────────┐  │
│  │ 18F-会议室B  20人  │  │
│  │ ● 使用中          │  │
│  └───────────────────┘  │
│                         │
│  📅 2026-07-15          │
│  ┌───────────────────┐  │
│  │  时间轴（纵向）     │  │
│  │  09:00 ████████   │  │
│  │  10:00 ████████   │  │
│  │  11:00 ░░░░░░░░   │  │
│  │  14:00 ████████   │  │
│  │  15:00 ░░░░░░░░   │  │
│  │  16:00 ░░░░░░░░   │  │
│  └───────────────────┘  │
│                         │
│  [ + 预定空闲时段 ]      │
└─────────────────────────┘
```

### 4.5 管理后台 — 终端绑定管理

```
┌─────────────────────────────────────────────────────────────┐
│  会议室管理 > 终端绑定                                       │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│                                                             │
│  [+ 新增绑定]                          [搜索: ___________]  │
│                                                             │
│  ┌────────┬──────────┬──────────┬──────────┬────────────┐  │
│  │ 终端SN  │ 终端名称  │ 会议室    │ 位置      │ 操作        │  │
│  ├────────┼──────────┼──────────┼──────────┼────────────┤  │
│  │ XY001  │ 大屏A    │ 18F-会议室A│ 18F东区  │ 编辑 删除   │  │
│  │ XY002  │ 大屏B    │ 18F-会议室B│ 18F西区  │ 编辑 删除   │  │
│  │ XY003  │ 大屏C    │ 19F-会议室C│ 19F东区  │ 编辑 删除   │  │
│  └────────┴──────────┴──────────┴──────────┴────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

---

## 5. 技术规范

### 5.1 企微会议室API对接

| API | 企微接口 | 方法 | 说明 |
|-----|---------|------|------|
| 会议室列表 | `POST /cgi-bin/oa/meetingroom/list` | `WecomService.get_meetingroom_list()` | 缓存10分钟 |
| 预定状态查询 | `POST /cgi-bin/oa/meetingroom/get_booking_info` | `WecomService.get_booking_info()` | 缓存30秒 |
| 预定会议室 | `POST /cgi-bin/oa/meetingroom/book` | `WecomService.book_meetingroom()` | 成功后清缓存 |
| 取消预定 | `POST /cgi-bin/oa/meetingroom/cancel_book` | `WecomService.cancel_booking()` | 成功后清缓存 |
| 预定详情 | `POST /cgi-bin/oa/meetingroom/bookinfo/get` | `WecomService.get_booking_detail()` | 缓存5分钟 |

**access_token管理**：
- 企微会议室API需要独立的"会议室"secret获取access_token
- 在`config.py`新增`wecom_meetingroom_secret`配置项
- 在`WecomService`中新增`get_meetingroom_access_token()`方法
- Redis缓存key: `wecom:meetingroom_access_token`，TTL: 6900秒（提前300秒刷新）
- 参考现有`get_access_token()`和`_contact_token_cache`的实现模式

**企微API限制**：
- 预定时间自动按30分钟取整（15:15→15:00，15:45→16:00）
- 仅可预定无需审批的会议室（`need_approval=0`）
- `get_booking_info`不支持跨天查询，后端按日期维度封装
- 当前时间超过预定开始时间15分钟后不允许预定
- 会议室设备类型：1=电视, 2=电话, 3=投影, 4=白板, 5=视频

**官方文档**：
- 会议室管理：https://developer.work.weixin.qq.com/document/path/93619
- 会议室预定管理：https://developer.work.weixin.qq.com/document/path/93620

### 5.2 小鱼易联终端管理API对接

| 能力 | 接口 | 说明 |
|------|------|------|
| 鉴权 | enterpriseId + token | 支持1.0（signature）和2.0两种签名方式 |
| 终端管理 | `https://sdk.xylink.com/api/rest/external/v1/` | 根据SN或终端号管理设备配置 |
| 终端状态查询 | 终端管理API | 查询终端在线状态 |
| Web SDK | `@xylink/xy-rtc-sdk` | 初始化需要clientId + clientSecret + extId（企业ID） |

**配置项**（新增到`config.py`）：
- `xylink_enterprise_id`：小鱼易联企业ID
- `xylink_client_id`：SDK客户端ID
- `xylink_client_secret`：SDK客户端密钥
- `xylink_api_base`：API基础URL（默认`https://sdk.xylink.com/api/rest/external/v1/`）

**官方文档**：https://openapi.xylink.com/

### 5.3 后端新增文件结构

```
backend/app/
├── api/
│   ├── meetingroom.py          # 会议室预定API路由
│   └── admin/
│       └── terminal_binding.py # 终端绑定管理（管理后台）
├── services/
│   ├── meetingroom_service.py  # 会议室预定业务逻辑
│   └── xylink_service.py       # 小鱼易联终端管理服务
├── models/
│   └── terminal_room_binding.py # 终端-会议室绑定模型
└── config.py                   # 新增配置项
```

### 5.4 前端新增项目

```
frontend-terminal/              # 小鱼易联终端页面（新建）
├── src/
│   ├── views/
│   │   ├── StatusView.vue     # 终端状态页（主页面）
│   │   └── BookingView.vue     # 快速预定弹窗
│   ├── components/
│   │   ├── Timeline.vue        # 时间轴组件
│   │   ├── StatusBadge.vue     # 状态标识
│   │   └── QrLogin.vue         # 扫码登录组件
│   ├── api/
│   │   └── meetingroom.ts     # API调用
│   └── App.vue
├── tailwind.config.js          # 横屏大屏适配配置
└── vite.config.ts
```

### 5.5 实时同步方案

| 方案 | 机制 | 延迟 | 适用场景 |
|------|------|------|---------|
| WebSocket（P1） | 终端建立WS连接，后端状态变更时推送 | <5秒 | 终端在线时的实时同步 |
| 轮询（P0降级） | 终端每30秒请求一次状态 | <30秒 | WS不可用时的降级方案 |
| 企微回调（P1） | 企微预定变更时回调后端，触发缓存刷新+WS推送 | <10秒 | 企微客户端预定的同步 |

**P0阶段**：终端页面使用30秒轮询保证基本实时性。
**P1阶段**：升级为WebSocket + 企微回调，实现5秒内同步。

### 5.6 终端页面部署方案

| 方案 | 说明 | 优劣 |
|------|------|------|
| **方案A（推荐）** | 终端通过浏览器/WebView访问后端提供的URL | 灵活度高，更新无需触达终端；但依赖网络稳定 |
| 方案B | 通过小鱼易联终端管理API推送自定义页面URL | 更深度集成；但需要小鱼易联API支持自定义页面推送 |
| 方案C | 使用小鱼易联Web SDK在终端原生渲染 | 最深度集成；但开发成本高，P2阶段考虑 |

**P0推荐方案A**：终端浏览器全屏访问 `https://itsupport.servyou.com.cn/terminal/{sn}`，后端根据SN返回对应会议室的状态页面。

---

## 6. 数据模型

### 6.1 终端-会议室绑定表 `terminal_room_binding`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer (PK) | 自增主键 |
| terminal_sn | String(64) | 小鱼易联终端序列号（唯一） |
| terminal_name | String(100) | 终端名称（如"18F东区大屏"） |
| meetingroom_id | Integer | 企微会议室ID |
| meetingroom_name | String(100) | 会议室名称（冗余字段，便于展示） |
| location | String(200) | 位置描述（如"18F东区"） |
| is_active | Boolean | 是否启用（默认True） |
| created_at | DateTime | 创建时间 |
| updated_at | DateTime | 更新时间 |

### 6.2 会议室预定快照表 `meetingroom_booking_snapshot`（P2）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer (PK) | 自增主键 |
| meetingroom_id | Integer | 企微会议室ID |
| booking_id | String(64) | 企微预定ID |
| subject | String(200) | 会议主题 |
| booker | String(64) | 预定人userid |
| start_time | DateTime | 开始时间 |
| end_time | DateTime | 结束时间 |
| status | Integer | 预定状态（0=已预定, 1=已取消） |
| snapshot_date | Date | 快照日期 |
| created_at | DateTime | 记录创建时间 |

---

## 7. 待确认问题

| # | 问题 | 影响范围 | 建议 |
|---|------|---------|------|
| Q1 | **企微"会议室"secret是否已申请？** 会议室API需要独立的secret获取access_token，不同于现有应用secret和通讯录secret。需要在企微管理后台「应用管理 > 会议室 > 可调用接口的应用」中配置。 | P0核心前置条件 | 请IT支持组确认是否已有会议室secret，或协助申请 |
| Q2 | **企微会议室是否已在管理后台创建？** 需要先在企微管理后台创建会议室（设置名称、容量、位置、设备等），API只能查询和预定已创建的会议室。 | P0核心前置条件 | 请确认企微后台已创建公司所有会议室 |
| Q3 | **小鱼易联终端的具体型号和运行环境？** 需要确认终端是通过内置浏览器/WebView运行页面，还是有其他自定义页面机制。不同型号可能支持的页面渲染能力不同。 | 影响前端技术选型 | 请提供终端型号，或确认是否支持浏览器全屏访问 |
| Q4 | **小鱼易联开发者账号的具体权限？** 需要确认开发者账号是否有终端管理API的调用权限，以及Web SDK的使用授权。 | P1小鱼易联API集成 | 请确认开发者账号的API权限范围 |
| Q5 | **终端身份识别方案？** 终端是公共设备，员工预定时需要身份识别。方案一：企微扫码登录（推荐，与现有系统一致）；方案二：输入工号+短信验证码；方案三：企微NFC碰一碰。 | P0预定功能 | 建议方案一（企微扫码），与现有H5端登录方式一致 |
| Q6 | **是否需要支持访客预定？** 访客通常没有企微账号，无法通过企微API预定。如需支持，需要额外的访客登记流程。 | P0-P1 | 建议P0阶段仅支持企微员工预定，访客仅查看状态 |
| Q7 | **会议室是否需要与小鱼易联视频会议联动？** 即预定会议室后，是否需要自动在终端上发起小鱼易联视频会议？ | P2功能 | 建议P0阶段仅做预定，P2阶段考虑视频会议联动 |
| Q8 | **终端页面部署在哪个域名下？** 是复用现有`itsupport.servyou.com.cn`域名（新增`/terminal/`路径），还是使用独立域名？ | 影响部署和Nginx配置 | 建议复用现有域名，新增`/terminal/`路由 |
| Q9 | **与现有IT智能服务台的关系？** 会议室预定是作为独立功能模块（仅在终端和H5端提供入口），还是也需要集成到坐席端（如坐席帮员工预定）？ | 影响功能范围 | 建议P0阶段聚焦终端+H5端，坐席端集成放到P1 |
| Q10 | **企微回调URL是否已配置？** 企微会议室预定状态变更回调需要配置回调URL，且需要企微后台配置可信域名。 | P1企微回调 | 请确认企微后台是否支持会议室事件回调配置 |

---

## 8. 里程碑建议

| 阶段 | 内容 | 预估工期 | 依赖 |
|------|------|---------|------|
| **M1** | 企微会议室API对接（token管理+CRUD接口）+ 终端状态页 | 1周 | Q1/Q2确认 |
| **M2** | 终端快速预定功能 + 终端-会议室绑定管理 | 1周 | M1完成 |
| **M3** | WebSocket实时同步 + 企微回调 + H5端预定页面 | 1.5周 | M2完成 |
| **M4** | 小鱼易联终端管理API集成 + 多会议室切换 | 1周 | Q3/Q4确认 |
| **M5** | 统计报表 + 维护模式 + P2功能 | 按需 | M4完成 |

**总预估**：4-5周（P0+P1），P2按需排期。