Files

T

Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交）

本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交
（5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。

一、docs 结构整改（整改 #14）
根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入，
随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录
树并存于 docs/，共 791 文件、双分类体系冲突。

修复动作：
- b2 同名异主题文件改名迁移保全 9 个
- C 类 39 个孤立文件按主题正确归类
- A/B1 类 222 个重复文件删除（新结构已有内容副本）
- 9 个旧独有空目录删除
- 270 处内部引用按 verified 映射改写
- 整改记录 #14 登记于 04-运维文档/部署运维

结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。
残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。

二、compose 双目录对齐（消除踩坑 A）
- docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist
  改为 src/frontend-*/dist（h5 / agent / admin / terminal）
- docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/
- 效果：本地 docker compose up 不再把根目录 stale dist 挂回，
  与线上一致，分叉隐患消除（已 docker compose config 校验通过）

防复发铁律：
- 重构须提交；仓库修复须 git stash -u 或先 commit
- 新结构须 git add 并提交，避免再次 untracked 复活
- H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/

2026-08-07 22:31:32 +08:00

36 KiB

Raw Blame History

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

版本: v1.0 日期: 2026-07-15 作者: 许清楚 (Xu) · 产品经理状态: 待评审 所属项目: wecom_it_smart_desk — IT智能服务台

1. 项目信息

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

原始需求复述

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

在小鱼易联终端上定制页面，集成企微自定义应用中的会议室预定能力
员工可通过H5/企微/终端页面多入口自助预定，预定结果同步到小鱼易联终端显示
有小鱼易联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按需排期。

36 KiB Raw Blame History Unescape Escape