# PPT 文档导入与呈现服务 — 规划设计及实施方案 ## 一、概述 ### 1.1 背景与痛点 PPT（PowerPoint / Keynote / WPS 演示文稿）是企业内外部演讲、培训、方案汇报的核心文档格式。然而在大屏呈现场景中，PPT 面临以下突出痛点： | 痛点 | 说明 | |------|------| | **终端碎片化** | 大屏涵盖智能电视机（Android）、机顶盒（Android）、Windows 各版本、鸿蒙 TV 等，PPT 在不同平台渲染效果差异显著 | | **字体与排版漂移** | 缺少字体导致替代渲染，页面布局错位，精心排版的效果无法还原 | | **演讲者被迫自带 PC** | 为保证呈现一致性，演讲者常常只能连接自己的笔记本电脑，增加准备成本和安全风险 | | **互动能力缺失** | 原生 PPT 演示模式缺乏观众互动（投票、提问、弹幕、反馈）能力 | | **协作效率低** | PPT 通过网盘或邮件传递，缺乏版本管理、多人协作、权限控制 | ### 1.2 目标 基于 [ICT 服务平台](ICT服务平台概要.md) 的统一认证底座（OpenLDAP + Keycloak）和 Git 基础设施（Gitea），构建 **PPT 文档导入与呈现服务平台**，实现： - 在云端将 PPT 转化为 Web 页面，终端以**浏览器**为统一呈现载体 - 覆盖全部泛化终端（Android TV、Android STB、Windows、鸿蒙 TV、iPad 等） - 互动信息（评论、投票、提问、弹幕）与 PPT-Web 每页画面精确绑定 - 基于 Git 管理个人文档与工作组文档，支持多组合协作关系 - 用户界面保持文件目录树方式，符合日常使用习惯 ### 1.3 核心设计原则 - **浏览器即终端**：PPT 转 Web 后，任何支持现代浏览器的设备均可精确呈现，从根本上消除终端差异 - **Git 为唯一真实源**：PPT 原文件及转换产物均存储于 Git 仓库，版本可追溯 - **开源优先，商业增强**：核心链路采用开源方案，高保真转换环节引入商业方案保障效果 - **认证复用**：全部接入 ICT 平台 Keycloak SSO - **自动化驱动**：Git 推送即触发 PPT 转换、发布、同步，零人工干预 ### 1.4 用户角色 | 角色 | 说明 | 典型场景 | |------|------|---------| | 演讲者 (Presenter) | PPT 上传者与现场演讲控制者 | 上传 PPT 到 Git，远程/现场控制翻页 | | 观众 (Audience) | 通过大屏或个人设备观看演示的人员 | 浏览器观看 PPT-Web、扫码参与互动 | | 协作者 (Collaborator) | 参与 PPT 文档协同编辑与版本管理的成员 | 通过 Git 分支协作修改 PPT 资料 | | 管理员 (Admin) | 管理文档空间、权限、转换策略的 IT 人员 | 配置仓库权限与转换规则 | --- ## 二、系统架构 ### 2.1 整体架构图 ```plantuml @startuml skinparam componentStyle rectangle skinparam nodesep 30 skinparam ranksep 40 title PPT 文档导入与呈现服务 - 系统架构 ' ===== 用户层 ===== actor "演讲者" as Presenter actor "观众" as Audience ' ===== 终端层 ===== node "演讲者终端" as PClient { component "VS Code + Qoder" as IDE } node "泛化终端 (浏览器统一呈现)" as AClient { component "Android TV / STB" as TV component "Windows / Mac" as WinMac component "鸿蒙 TV / iPad" as HM } ' ===== 应用服务层 ===== node "互联网应用服务器" as AppServer { component "Nginx + SSL" as Nginx component "Keycloak SSO" as KC package "文档管理" { component "Gitea" as Gitea component "MeiliSearch" as Search } package "PPT 转换引擎" { component "SlideForge" as SF component "ONLYOFFICE" as OO component "LibreOffice" as LO } package "演示与互动" { component "SlidePortal" as Portal component "InteractHub" as Interact } } ' ===== 数据层 ===== node "私有云 [数据后端]" as PCloud { database "PostgreSQL" as DB database "OpenLDAP" as LDAP storage "Git 仓库存储" as Store } ' == 演讲者流 == Presenter -down-> IDE : 上传 PPT IDE -down-> Gitea : git push (SSH) ' == 观众流 == Audience -down-> AClient AClient -down-> Nginx : HTTPS ' == 接入与认证 == Nginx -down-> KC : 认证校验 Nginx -down-> Portal : 演示页面 ' == 转换链 == Gitea -right-> SF : Webhook 触发 SF -down-> OO : PPTX 转 HTML SF -down-> LO : 旧格式转换 SF -right-> Portal : Web 幻灯片 ' == 互动 == Portal -down-> Interact : 互动事件 ' == 数据存储 == KC -down-> LDAP : 用户目录 Gitea -down-> Store : 仓库数据 SF -down-> DB : 转换元数据 Interact -down-> DB : 互动数据 @enduml ``` ### 2.2 核心组件清单 | 组件 | 技术方案 | 用途 | 许可证 | |------|---------|------|--------| | PPT 转换调度 | **自研 SlideForge**（Node.js） | 接收 Webhook，调度转换引擎，管理转换产物 | — | | 反馈引擎 | **FeedbackEngine**（SlideForge 子模块） | 互动数据聚合、反馈报告生成、修订闭环管理 | — | | PPT 转 HTML（主引擎） | **ONLYOFFICE Document Server** | 高保真 PPTX 转 HTML | AGPL v3 | | PPT 转 HTML（兼容引擎） | **LibreOffice Headless** | 旧格式（PPT/ODP）转换 | MPL 2.0 | | PPT 转 HTML（高保真） | **Aspose.Slides Cloud** | 复杂动画与特殊排版的精确还原 | 商业授权 | | Web 幻灯片框架 | **Reveal.js** | 浏览器端幻灯片呈现、翻页、全屏 | MIT | | 实时互动 | **自研 InteractHub**（Socket.io） | 投票、提问、弹幕、遥控翻页 | — | | 演示平台 | **自研 SlidePortal**（Next.js） | 文件管理 UI、演示控制台、观众端 | — | | Git 仓库 | **Gitea**（已有） | PPT 文件存储与版本管理 | MIT | | 全文检索 | **MeiliSearch**（已有） | PPT 标题、标签、内容搜索 | MIT | | 认证中心 | **Keycloak**（已有） | OIDC SSO 统一登录 | Apache 2.0 | | 反向代理 | **Nginx**（已有） | SSL 终止、路由分发、WebSocket 代理 | BSD | --- ## 三、PPT 转 Web 关键技术 ### 3.1 技术路线概览 PPT 转 Web 是本系统的**核心技术环节**，直接决定终端呈现质量。业界存在以下主要技术路线： ``` PPT 原文件 │ ├─ 路线 A：PPT → HTML（直接转换） │ └─ ONLYOFFICE / Aspose.Slides / GroupDocs │ ├─ 路线 B：PPT → PDF → HTML（两步转换） │ └─ LibreOffice → pdf2htmlEX │ ├─ 路线 C：PPT → SVG/PNG + JSON → Reveal.js（解构重建） │ └─ Apache POI / python-pptx → 自定义渲染 │ └─ 路线 D：PPT → 在线编辑器实时渲染 └─ ONLYOFFICE Viewer / Microsoft Graph API ``` ### 3.2 方案详细对比 | 维度 | ONLYOFFICE | LibreOffice | Aspose.Slides | pdf2htmlEX 管线 | POI + Reveal.js | MS Graph API | |------|-----------|-------------|---------------|----------------|-----------------|--------------| | **类型** | 开源 AGPL v3 | 开源 MPL 2.0 | 商业 | 开源 GPL v3 | 开源 Apache 2.0 | 云服务 | | **转换质量** | ★★★★☆ | ★★★☆☆ | ★★★★★ | ★★★★☆ | ★★★☆☆ | ★★★★★ | | **字体保真** | 优 | 中（依赖系统字体） | 优（字体嵌入） | 优（PDF 字体） | 差 | 优 | | **动画支持** | CSS 动画还原 | 不支持 | CSS/JS 动画 | 不支持 | 需自定义 | 原生动画 | | **母版/图表** | 完整支持 | 基本支持 | 完整支持 | 视觉保留 | 需自行解析 | 完整支持 | | **自托管** | Docker 部署 | 原生/Docker | JAR/Docker | 原生/Docker | 纯代码 | 仅云端 | | **旧格式 PPT** | 支持 | 良好 | 支持 | 间接 | 仅 PPTX | 支持 | | **ODP/Keynote** | ODP 支持 | 良好 | 有限 | 间接 | 不支持 | 有限 | | **并发性能** | 中（~5 并发/实例） | 中（进程隔离） | 高 | 中 | 高 | 高（弹性） | | **年成本** | 免费（社区版） | 免费 | ~30K RMB/服务器 | 免费 | 免费 | ~20K RMB/年 | | **集成难度** | 中 | 低（CLI） | 低（REST API） | 中 | 高 | 低（REST） | ### 3.3 推荐方案：三级混合转换引擎 采用**三级转换策略**，在效果与成本之间取得最优平衡： ```plantuml @startuml skinparam componentStyle rectangle title PPT 转 Web 三级混合转换引擎 start :SlideForge 接收 PPT 文件; :解析文件格式与复杂度; note right 检查项： 动画数量/SmartArt/图表 嵌入字体/媒体/母版复杂度 end note if (PPTX 且复杂度 <= 阈值 ?) then (是) :ONLYOFFICE 转换; note right: 开源主引擎, 覆盖约 80% else (否) if (PPT/ODP/旧格式 ?) then (是) :LibreOffice 转换; note right: 旧格式兼容引擎 else (PPTX 高复杂度) :Aspose.Slides 转换; note right: 商业高保真引擎 endif endif :Reveal.js 封装后处理; note right 注入翻页框架 + 互动 SDK 嵌入字体子集(WOFF2) 压缩图片(WebP) + 生成缩略图 end note :存入 Git 仓库 + 注册 PostgreSQL; stop @enduml ``` #### 三级引擎定位 | 引擎 | 定位 | 覆盖场景 | 预计占比 | |------|------|---------|---------| | **ONLYOFFICE** | 主引擎 | 标准 PPTX，中低复杂度 | ~80% | | **LibreOffice** | 兼容引擎 | PPT (旧格式)、ODP、Keynote 导出 | ~10% | | **Aspose.Slides** | 高保真引擎 | 复杂动画、特殊排版、精确还原 | ~10% | ### 3.4 转换后处理：Reveal.js 封装 无论哪个引擎产出 HTML，SlideForge 均进行统一后处理，封装为 **Reveal.js** 格式： ``` 转换引擎产出 │ ├─ 每页幻灯片 →
标签 ├─ 注入 Reveal.js 框架（翻页/全屏/进度条/演讲者视图） ├─ 注入 InteractHub SDK（每页互动面板 + WebSocket） ├─ 字体子集嵌入（fonttools → WOFF2，仅保留使用字符） └─ 图片优化（sharp → WebP 转换 + 响应式多尺寸） ``` ### 3.5 转换质量保障 | 措施 | 说明 | |------|------| | **自动截图对比** | 转换后逐页截图，与 LibreOffice 渲染的参考 PDF 对比相似度（Puppeteer + pixelmatch） | | **人工校验标记** | 演讲者在 SlidePortal 中逐页预览，可标记"需优化"触发高级引擎重试 | | **引擎降级重试** | 转换失败或相似度低于阈值时，自动切换更高级引擎重试 | | **字体白名单** | 维护常用中英文字体库，缺失字体自动提示上传或从字体库补充 | --- ## 四、Git 文档管理体系 ### 4.1 仓库结构 PPT 文档管理复用 ICT 平台的 Gitea 基础设施，按组织层级划分仓库： | 仓库类型 | 命名规范 | 说明 | |---------|---------|------| | **个人文档** | `slides-{username}` | 个人 PPT 资料，私有仓库 | | **工作组文档** | `slides-{group}` | 部门/项目组共享，按组权限 | | **公开演示** | `slides-public` | 对外发布的演示资料 | | **模板库** | `slides-templates` | 企业 PPT 模板，全员可读 | #### 仓库目录结构示例 ``` slides-marketing/ # 市场部工作组仓库 ├── 2026-Q1/ │ ├── 新品发布会.pptx │ ├── 客户方案-ABC公司.pptx │ └── 季度总结.pptx ├── templates/ │ ├── 标准汇报模板.pptx │ └── 产品介绍模板.pptx ├── .slideforge.yml # 转换配置 └── README.md ``` ### 4.2 Git 协作优势（对比网盘） | 维度 | Git 仓库管理 | 网盘管理 | |------|-------------|---------| | **版本管理** | 完整 Git 历史，任意版本可回溯 | 无版本或仅有限快照 | | **协作模式** | 分支 + 合并请求，多人并行不冲突 | 文件锁定或覆盖冲突 | | **权限控制** | 按仓库/分支/路径细粒度控制 | 按文件夹粗粒度控制 | | **自动化** | Webhook 触发转换/发布/通知 | 需人工操作 | | **多组合协作** | Fork 后独立修改，跨组共享，MR 合并 | 复制粘贴，难以追踪来源 | | **审计** | 每次变更有作者、时间、说明 | 无或有限审计 | | **离线使用** | 本地完整仓库，离线可用 | 依赖网络 | ### 4.3 多组合协作关系 Git 的分支与 Fork 机制天然支持跨部门多组合协作： ```plantuml @startuml skinparam componentStyle rectangle title Git 多组合协作模式 package "市场部仓库" as MKT { component "main" as Main component "feature/新品发布" as F1 } package "研发部 Fork" as RD { component "技术内容补充" as RDWork } package "设计部 Fork" as DS { component "视觉优化" as DSWork } actor "市场部成员" as M actor "研发部成员" as R actor "设计部成员" as D M -down-> F1 : 内容编写 R -down-> RDWork : 技术补充 D -down-> DSWork : 视觉优化 RDWork -right-> Main : Merge Request DSWork -right-> Main : Merge Request F1 -down-> Main : 分支合并 @enduml ``` --- ## 五、终端泛化呈现 ### 5.1 目标终端矩阵 | 终端类型 | 操作系统 | 浏览器内核 | 分辨率 | 输入方式 | |---------|---------|-----------|--------|---------| | 智能电视机 | Android TV | Chromium WebView | 1080p / 4K | 遥控器 | | 大屏机顶盒 | Android | Chromium WebView | 1080p / 4K | 遥控器 | | 鸿蒙 TV | HarmonyOS | ArkWeb (Chromium) | 1080p / 4K | 遥控器 | | Windows PC | Windows 10/11 | Chrome / Edge | 多种 | 键鼠 / 翻页笔 | | Mac | macOS | Safari / Chrome | 多种 | 键鼠 / 翻页笔 | | iPad / 平板 | iPadOS / Android | Safari / Chrome | 多种 | 触屏 | | 手机（控制端） | iOS / Android | Safari / Chrome | 多种 | 触屏 | ### 5.2 浏览器统一呈现架构 核心思路：**所有终端均通过浏览器访问 PPT-Web 页面，不安装任何原生 PPT 应用**。 ``` 云端 PPT → Reveal.js Web 幻灯片 │ ├─ Android TV / STB → WebView 全屏打开 ├─ 鸿蒙 TV → ArkWeb 全屏打开 ├─ Windows / Mac → Chrome/Edge/Safari 全屏 ├─ iPad / 平板 → Safari/Chrome 全屏 └─ 手机 → 浏览器打开（演讲者遥控端） ``` ### 5.3 终端适配策略 | 维度 | 策略 | |------|------| | **分辨率** | Reveal.js `width/height` + CSS `scale` 自适应，幻灯片按原始比例等比缩放 | | **字体** | 转换时嵌入字体子集（WOFF2），不依赖终端系统字体 | | **遥控器** | 拦截遥控器方向键 → 映射为 Reveal.js 上/下/左/右翻页 | | **触屏** | Reveal.js 原生支持滑动翻页 | | **翻页笔** | USB 翻页笔发送 Page Up/Down，Reveal.js 原生支持 | | **全屏** | Fullscreen API 自动进入全屏；遥控器返回键退出 | | **弱网** | Service Worker 缓存全部资源，首次加载后离线可翻页 | --- ## 六、互动反馈系统 ### 6.1 互动功能矩阵 互动信息与 PPT-Web **每页画面精确绑定**，每一页幻灯片可独立配置互动组件： | 互动功能 | 说明 | 绑定粒度 | |---------|------|---------| | **实时投票** | 演讲者发起单选/多选投票，观众扫码参与 | 绑定到具体页 | | **在线提问 (Q&A)** | 观众提交问题，可点赞，演讲者选择展示 | 绑定到具体页 | | **弹幕** | 观众发送弹幕，叠加显示在幻灯片上方 | 绑定到具体页 | | **实时反应** | 观众发送表情反应，悬浮动画展示 | 绑定到具体页 | | **标注批注** | 审阅者对具体页面留下文字批注 | 绑定到具体页 | | **演讲者注释** | 仅演讲者可见的备注与提示 | 绑定到具体页 | | **远程遥控** | 演讲者通过手机控制翻页、激光笔 | 全局 | ### 6.2 互动技术架构 ```plantuml @startuml skinparam componentStyle rectangle skinparam nodesep 30 skinparam ranksep 40 title 互动反馈系统架构 node "演讲者手机" as Phone { component "遥控端 (翻页/激光笔)" as Remote } node "观众手机" as APhone { component "互动页面 (投票/提问/弹幕)" as APage } node "互联网应用服务器" as Server { component "InteractHub" as Hub component "Redis (在线状态缓存)" as Redis } node "大屏终端" as Screen { component "Reveal.js 幻灯片 (同步翻页)" as Slides component "互动叠加层 (实时推送)" as Overlay } database "PostgreSQL\n(持久化互动数据)" as DB Remote -down-> Hub : WebSocket APage -down-> Hub : WebSocket Hub -down-> Slides : WebSocket Hub -down-> Overlay : WebSocket Hub -right-> Redis Hub -right-> DB @enduml ``` ### 6.3 观众接入方式 观众通过扫描大屏二维码即时接入互动： ``` 大屏当前页展示会话二维码 → 观众手机扫码 → 打开 https://slide.writech.cn/interact/{session_id} → WebSocket 建立连接 → 实时参与当前页的投票/提问/弹幕 → 翻页时互动面板自动切换到对应新页 ``` ### 6.4 互动数据与页面绑定模型 每条互动数据均绑定 `session_id + slide_index`，确保回放时可精确还原每页互动： ``` Session（演示会话） ├── slide_index: 0 │ ├── votes: [{question, options, results}] │ ├── questions: [{user, content, upvotes}] │ └── reactions: {count_by_type} ├── slide_index: 1 │ ├── danmaku: [{user, content, timestamp}] │ └── annotations: [{user, position, content}] └── slide_index: N └── ... ``` --- ## 七、演示反馈闭环 ### 7.1 闭环流程概述 演示互动数据不仅服务于现场体验，更构成**从演示到修订的完整闭环**：每场演示结束后，系统自动聚合互动数据、生成结构化反馈报告，推送至 PPT 原始编辑者，驱动文档持续优化迭代。 ```plantuml @startuml skinparam componentStyle rectangle title PPT 编辑版本闭环流程 start :编辑者创建/修改 PPT 并推送到 Git; :SlideForge 自动转换为 Web 幻灯片; :演讲者发起演示会话; :观众互动环节; note right 并行采集 ---- 观众提问 观众投票 弹幕 / 表情反应 审阅者批注 end note :InteractHub 采集并持久化互动数据; :演示会话结束; :FeedbackEngine 聚合互动数据; note right 按页聚合 - 每页独立统计 跨场次聚合 - 同一 PPT 多次演示 end note :生成结构化反馈报告; :反馈报告提交至 Git 仓库; :MsgHub 通知原始编辑者; :编辑者审阅反馈报告; if (需要修订 ?) then (是) :创建修订分支, 修改 PPT; :推送新版本, 自动触发转换; note right: 新版本 commit 引用反馈报告 else (否) :标记已审阅, 无需修订; endif stop @enduml ``` ### 7.2 互动数据聚合 FeedbackEngine 在演示结束后从 PostgreSQL 提取互动数据，按两个维度进行聚合： #### 逐页聚合 每页幻灯片独立生成反馈摘要： | 数据维度 | 聚合内容 | 来源 | |---------|---------|------| | **提问** | 问题列表、点赞数排序、是否已回答 | Q&A 模块 | | **投票** | 各选项得票率、参与人数 | 投票模块 | | **弹幕关键词** | 高频词提取、情感倾向 | 弹幕模块 | | **反应统计** | 各表情类型的分布 | 反应模块 | | **批注** | 审阅者标注内容汇总 | 批注模块 | | **停留时长** | 该页展示时长与全文均值的对比 | 翻页事件 | #### 跨场次聚合 同一 PPT 可能被多次演示，FeedbackEngine 支持跨场次合并： | 策略 | 说明 | |------|------| | **累计统计** | 所有场次的提问、投票、反应数据累加 | | **趋势对比** | 对比不同场次同一页的反馈变化 | | **最新优先** | 修订建议以最近一次演示的反馈为主 | | **版本关联** | 每次聚合标注对应的 PPT commit hash | ### 7.3 反馈报告 FeedbackEngine 生成的报告以 **Markdown** 存入 Git 仓库，与 PPT 源文件同目录管理： ``` slides-marketing/ ├── 新品发布会.pptx ├── 新品发布会.feedback/ │ ├── 2026-03-20_会议室A.md # 单次演示反馈 │ ├── 2026-03-25_客户现场.md # 单次演示反馈 │ └── _summary.md # 跨场次汇总报告 └── .slideforge.yml ``` #### 报告内容结构 每份反馈报告包含以下板块： | 板块 | 内容 | |------|------| | **演示概况** | 文件名、版本 hash、演讲者、日期、时长、观众数、互动参与率 | | **逐页反馈** | 每页的提问列表(含赞数排序)、投票结果、弹幕关键词、情感倾向、批注汇总、停留时长异常标记 | | **整体分析** | 全场互动率、情感曲线(逐页正/中/负占比)、高频关键词 Top 10、未回答问题清单 | | **修订建议** | 基于数据的具体改进建议：高频提问对应补充内容、负面情感页优化表述、停留过短页扩充内容 | #### 单次反馈报告示例 ```markdown # 演示反馈报告 ## 演示概况 | 项目 | 内容 | |------|------| | 文件 | 新品发布会.pptx | | 版本 | commit abc1234 | | 演讲者 | 张三 | | 日期 | 2026-03-20 | | 时长 | 45 分钟 | | 观众数 | 32 人 | | 互动参与率 | 78% | ## 逐页反馈 ### 第 3 页 - "产品架构" - 停留时长: 4分12秒 (全文平均 3分) - 提问 (5条): 1. "架构中缓存层用的是什么方案?" (12赞) 2. "支持私有化部署吗?" (8赞) - 投票: "您认为该架构是否满足需求?" 完全满足 45% / 基本满足 40% / 需改进 15% - 情感倾向: 正面 72%, 中性 20%, 负面 8% ## 整体分析 - 观众参与度: 高 (78%) - 第 7-9 页负面情绪上升 - 高频关键词: 价格、部署、兼容性 - 未回答问题: 3 条 ## 修订建议 1. 第 3 页: 补充缓存方案说明 2. 第 7 页: 定价策略引发较多负面反馈, 建议优化表述 3. 第 12 页: 停留时长过短, 考虑扩充内容 ``` ### 7.4 编辑者修订工作流 反馈报告生成后驱动 PPT 编辑者完成修订闭环： | 步骤 | 操作 | 说明 | |------|------|------| | 1 | 接收通知 | MsgHub 推送反馈通知至编辑者 | | 2 | 查看反馈 | 在 SlidePortal 反馈看板中查看报告 | | 3 | 逐页审阅 | 对照 PPT-Web 查看每页的互动数据与建议 | | 4 | 创建分支 | 在 Gitea 中创建 `revision/{date}` 分支 | | 5 | 修订 PPT | 在本地修改 PPT 文件并推送 | | 6 | 自动转换 | SlideForge 自动触发新版本转换 | | 7 | 关闭反馈 | 修订 commit 引用反馈报告，状态自动更新为“已修订” | #### 反馈状态流转 | 状态 | 说明 | |------|------| | **待审阅** | 报告生成后初始状态 | | **审阅中** | 编辑者已打开报告 | | **修订中** | 编辑者已创建修订分支 | | **已修订** | 修订版本已推送并完成转换 | | **已关闭** | 编辑者标记无需修订 | ### 7.5 反馈看板 SlidePortal 为编辑者提供**反馈看板**视图，集中展示所有待处理反馈： ``` +------------------------------------------------------+ | 反馈看板 [全部/待处理] | +------------------------------------------------------+ | 新品发布会.pptx | | [待审阅] 03-25 客户现场 28人 互动率82% 建议4条 | | [已修订] 03-20 会议室A 32人 互动率78% 建议3条 | | [汇总] 2 场演示, 未回答问题 5 条 | | | | 季度总结.pptx | | [待审阅] 03-22 全员大会 156人 互动率45% 建议6条 | +------------------------------------------------------+ ``` ### 7.6 版本关联与追溯 反馈报告与 PPT 版本形成双向可追溯的关联： | 关联关系 | 说明 | |---------|------| | 反馈报告 -> 演示版本 | 报告中记录演示时的 PPT commit hash | | 修订版本 -> 反馈报告 | 修订 commit message 中引用反馈报告文件名 | | 反馈报告 -> 修订版本 | 报告状态更新为“已修订”并记录新 commit hash | | 跨场次汇总 -> 版本区间 | 汇总报告标注所覆盖的版本与场次列表 | 修订提交遵循以下 commit message 格式： ``` fix(slides): 根据反馈优化定价策略页 Feedback-Report: 新品发布会.feedback/2026-03-25_客户现场.md - 第 3 页: 补充缓存方案说明 - 第 7 页: 调整定价策略表述 - 第 12 页: 增加技术细节 ``` ### 7.7 技术实现 FeedbackEngine 作为 SlideForge 的子模块，负责互动数据聚合与报告生成： ``` FeedbackEngine (SlideForge 子模块) ├─ SessionCollector — 从 PostgreSQL 提取会话互动数据 ├─ PageAggregator — 按页聚合提问/投票/反应/批注 ├─ CrossSessionMerger — 跨场次数据合并与趋势分析 ├─ SentimentAnalyzer — 弹幕与反应的情感倾向统计 ├─ ReportGenerator — Markdown 反馈报告生成 ├─ GitCommitter — 报告写入 Git 仓库 └─ MsgHub Client — 通知编辑者 ``` | 触发方式 | 说明 | |---------|------| | **会话结束** | 演示结束 5 分钟后自动生成该场次反馈报告 | | **手动请求** | 编辑者在 SlidePortal 中手动生成跨场次汇总 | | **定时汇总** | 每周一自动生成上周所有演示的汇总报告 | --- ## 八、用户界面 ### 8.1 文件目录树 SlidePortal 以**文件目录树**为核心导航，与本地文件管理器体验一致： ``` +------------------------------------------------------+ | 我的演示文稿 [搜索] | +------------------------------------------------------+ | [+] 个人文档 (slides-zhangsan) | | [+] 2026-Q1 | | [-] 技术方案汇报.pptx 已转换 | | [-] 项目进展周报.pptx 已转换 | | [-] 新功能演示.pptx 转换中... | | [+] 模板 | | | | [+] 工作组文档 | | [+] 市场部 (slides-marketing) | | [-] 新品发布会.pptx 已转换 | | [-] 客户方案-ABC.pptx 已转换 | | [+] 研发部 (slides-rd) | | [+] 公开演示 (slides-public) | | | | [+] 企业模板库 (slides-templates) | +------------------------------------------------------+ ``` ### 8.2 文档操作 选中 PPT 文件后可执行的操作： | 操作 | 说明 | |------|------| | **在线预览** | 浏览器内直接预览转换后的 Web 幻灯片 | | **开始演示** | 创建演示会话，生成观众接入二维码，进入全屏 | | **下载原文件** | 下载 PPT 原始文件（需有权限） | | **查看历史版本** | 查看 Git 提交历史，可回溯任意版本 | | **分享链接** | 生成带权限控制的分享链接 | | **重新转换** | 手动触发重新转换（更换引擎或修复问题） | | **互动数据** | 查看历次演示会话的互动统计 | ### 8.3 演讲者控制台 演讲者启动演示后，手机端显示控制台： ``` +---------------------------+ | 演讲者控制台 | +---------------------------+ | | | < 上一页 3/15 下一页 > | | | | +-------------------+ | | | 当前页缩略图 | | | | | | | +-------------------+ | | | | 演讲者备注： | | "这里强调 Q1 增长..." | | | | 已用时 12:35 | | | | [发起投票] [Q&A面板] | | [激光笔] [结束演示] | +---------------------------+ ``` --- ## 九、转换配置 ### 9.1 仓库级配置 每个 Git 仓库根目录的 `.slideforge.yml` 定义转换策略： ```yaml # .slideforge.yml conversion: default_engine: onlyoffice # 默认转换引擎 fallback_engine: libreoffice # 备用引擎 high_fidelity_engine: aspose # 高保真引擎 complexity_threshold: 5 # 复杂度阈值（超过则用高保真引擎） fonts: embed: true # 嵌入字体子集 fallback_fonts: - "Noto Sans SC" - "Microsoft YaHei" output: format: revealjs image_quality: 85 image_format: webp generate_thumbnail: true generate_pdf: true # 同时生成 PDF 版本 interaction: default_features: [vote, qna, reaction] danmaku: false # 弹幕默认关闭 ``` ### 9.2 文件级配置 单个 PPT 可通过同目录 `.meta.yml` 覆盖仓库配置： ```yaml # 新品发布会.meta.yml conversion: engine: aspose # 强制使用高保真引擎 interaction: danmaku: true # 此演示开启弹幕 vote_slides: [3, 7, 12] # 第 3/7/12 页预设投票 publish: access: login # 需登录观看 share_expires: "2026-06-30" ``` --- ## 十、部署方案 ### 10.1 服务部署清单 全部服务运行于**互联网应用服务器**（腾讯云 / 阿里云），数据后端在私有云： | 服务 | 部署方式 | 运行位置 | 端口 | |------|---------|---------|------| | SlideForge 转换调度 | Docker (Node.js) | 互联网应用服务器 | 3010 | | ONLYOFFICE Document Server | Docker | 互联网应用服务器 | 8000 | | LibreOffice Headless | Docker (gotenberg) | 互联网应用服务器 | 3030 | | SlidePortal 演示平台 | Docker (Next.js) | 互联网应用服务器 | 3011 | | InteractHub 互动中心 | Docker (Node.js) | 互联网应用服务器 | 3012 | | Redis | Docker（已有） | 互联网应用服务器 | 6379 | | PostgreSQL | 原生安装（已有） | 私有云 | 5432 | | Gitea | Docker（已有） | 互联网应用服务器 | 22/443 | | Keycloak | Docker（已有） | 互联网应用服务器 | 8443 | ### 10.2 Nginx 路由规则 ```nginx # SlidePortal 演示平台 location /slides/ { proxy_pass http://127.0.0.1:3011; } # InteractHub WebSocket location /ws/interact/ { proxy_pass http://127.0.0.1:3012; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } # SlideForge Webhook（仅限 Gitea 内部调用） location /hook/slideforge { allow 127.0.0.1; deny all; proxy_pass http://127.0.0.1:3010; } # ONLYOFFICE（仅限 SlideForge 内部调用） location /onlyoffice/ { allow 127.0.0.1; deny all; proxy_pass http://127.0.0.1:8000; } # 转换后的静态幻灯片资源 location /slide-assets/ { alias /var/www/slide-assets/; expires 30d; } ``` --- ## 十一、实施路线图 | 阶段 | 任务 | 预计周期 | |------|------|--------| | **第一阶段：基础转换** | ONLYOFFICE + LibreOffice 部署，SlideForge 调度开发 | 第 1-3 周 | | **第一阶段** | Reveal.js 封装与后处理流水线开发 | 第 2-3 周 | | **第一阶段** | Gitea Webhook 对接，Git 推送自动触发转换 | 第 3 周 | | **第二阶段：演示平台** | SlidePortal MVP（目录树 + 在线预览 + 开始演示） | 第 4-5 周 | | **第二阶段** | 演讲者手机控制台（遥控翻页 + 演讲者备注） | 第 5-6 周 | | **第二阶段** | 终端适配测试（Android TV / 鸿蒙 TV / Windows / iPad） | 第 6-7 周 | | **第三阶段：互动系统** | InteractHub 核心开发（WebSocket + 投票 + Q&A） | 第 7-8 周 | | **第三阶段** | 弹幕与实时反应功能 | 第 8-9 周 | | **第三阶段** | 观众扫码接入 + 互动数据与页面绑定 | 第 9 周 | | **第四阶段：质量优化** | 转换质量自动检测（逐页截图对比） | 第 10 周 | | **第四阶段** | Aspose.Slides 商业引擎集成（高保真场景） | 第 10-11 周 | | **第四阶段** | 字体管理与嵌入优化 | 第 11 周 | | **第五阶段：协作增强** | 多组合协作（Fork / Merge Request 流程） | 第 12 周 | | **第五阶段** | FeedbackEngine 互动数据聚合与反馈报告生成 | 第 12-13 周 | | **第五阶段** | 反馈看板 + 修订工作流 + 版本关联追溯 | 第 13-14 周 | | **第五阶段** | 全链路测试与上线 | 第 14-15 周 |