Simon
facc04aa65
本提交为 .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-*/
579 lines
36 KiB
Markdown
579 lines
36 KiB
Markdown
# 会议室预定 — 小鱼易联终端 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按需排期。
|