主题 ：借助 PDF 渲染库（如 zpdf）实现通用文档界面，支撑建筑 EPC 项目全生命周期协同管理
背景：建筑 EPC 单位需要将 PDF 渲染能力作为平台的"通用文档显示驱动"，整合 CAD、Office、图片、扫描件等各类文档，实现统一查看、统一交互、统一归档。
1. 核心设计理念：PDF First
1.1 基本定位
PDF 渲染器不是"一个功能"，而是整个平台的"通用文档显示驱动"。
- 统一入口：所有文档（CAD/DWG、Office、图片、扫描件、系统报告）点开即阅，渲染引擎只有一套
- 统一体验：缩放、搜索、打印、水印、标注等交互完全一致
- 统一存储：所有正式交付物、审批件、归档文件均为 PDF/A 格式
- 统一接口：上层业务模块（通讯录、消息、工作流、计划等）无需关心底层格式差异
1.2 架构分层
┌─────────────────────────────────────────────────────────────┐
│ 业务模块层 │
│ 通讯录 | 消息 | 工作流 | 项目计划 | 文档管理 | AI设计 │
└────────────────────────┬────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 统一文档网关 │
│ - 所有文件入库 → 自动转换/归档为 PDF │
│ - 所有文件出库 → 以 PDF 视图呈现 │
│ - 所有版本追溯 → 以 PDF 对比视图展示 │
└────────────────────────┬────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ PDF 渲染引擎（基于 zpdf 深度定制） │
│ - 原生 PDF 渲染 - 扫描件 OCR 叠加 - 动态水印/权限 │
│ - 注释/标注层 - 全文搜索高亮 - 双栏对比视图 │
└─────────────────────────────────────────────────────────────┘
2. 各类文档的 PDF 化流转
| 文档类型 |
入库动作 |
存储形式 |
用户看到的 |
| 原生 PDF |
直接入库 |
PDF + 索引 |
原样渲染 |
| CAD (DWG/DXF) |
自动转换为矢量 PDF |
PDF + 源文件 |
矢量 PDF（无限缩放） |
| Office (DOCX/XLSX) |
自动转换为 PDF |
PDF + 源文件 |
带文本层的 PDF |
| 图片 (PNG/JPG/TIFF) |
自动包装为 PDF |
PDF + 原图 |
图片型 PDF（多页） |
| 扫描件 |
直接入库 + OCR |
PDF/A + OCR 文字层 |
可搜索、可复制的扫描 PDF |
| 系统报告/计算书 |
原生生成 PDF |
PDF |
结构化、带书签的 PDF |
| 聊天/工作流附件 |
自动转换 |
PDF + 源文件 |
渲染后的 PDF 视图 |
关键点：所有文档在入库时均转换为 PDF（或直接以 PDF 存储），用户侧看到的是统一的 PDF 视图。
3. 技术底座：PDF 渲染引擎 zpdf 的深度定制
3.1 选择 zpdf 的理由
| 维度 |
说明 |
| 纯 Rust 实现 |
零 C/C++ 依赖，安全可控，编译便捷 |
| 双渲染引擎 |
CPU (tiny-skia) + GPU (wgpu)，性能与画质兼得 |
| 跨平台 |
原生支持 Windows / macOS / Linux |
| MIT 许可证 |
商业友好，可闭源集成 |
| 高鲁棒性 |
对格式损坏的 PDF 文件有强容错能力 |
3.2 需封装的定制功能
| 功能 |
实现方式 |
| 快速首屏加载 |
流式解析 + 渐进式渲染，先显示第一页 |
| 大图纸流畅缩放 |
zpdf 的 DisplayList 缓存 + 异步分块渲染 |
| 扫描件清晰显示 |
保持原始分辨率，不做压缩 |
| 文字选择/复制 |
基于 PDF 文本层 + OCR 层提供选区高亮与复制 |
| 全文搜索 |
全文索引 + 实时高亮（覆盖原生文本和 OCR 层） |
| 标注/批注 |
在渲染层之上叠加用户标注（不修改原 PDF） |
| 动态水印/权限 |
渲染时叠加"仅供预览/保密/版本"等信息 |
| 打印/导出 |
调用 PDF 渲染引擎打印，保证所见即所得 |
| 双栏对比 |
同时渲染两个 PDF，高亮差异 |
3.3 统一渲染接口（示意）
/// 所有文档视图的统一渲染接口
trait DocumentView {
fn render(&self, page: u32, zoom: f32) -> RenderedImage;
fn select_text(&self, page: u32, rect: Rect) -> String;
fn search(&self, query: &str) -> Vec<SearchResult>;
fn annotate(&mut self, page: u32, annotation: Annotation);
fn add_watermark(&mut self, text: &str, opacity: f32);
fn export_pdf(&self, path: &Path) -> Result<()>;
}
4. 文档存储层的演进：PDF 是思想来源，而非格式束缚
4.1 演进路径
| 阶段 |
存储格式 |
加密 |
版本控制 |
索引 |
| 第一阶段 |
PDF + 自定义扩展元数据 |
PDF 标准加密 |
文件级 |
外部数据库 |
| 第二阶段 |
私有格式（CBOR/Protobuf） |
对象级 AES-256 |
原生支持 |
内嵌倒排索引 |
| 第三阶段 |
完全自主格式 |
默认全程加密 |
版本树 |
全文+语义索引 |
4.2 私有格式的骨架设计（以 PDF 对象模型为蓝本）
struct DocumentObject {
id: Uuid,
kind: ObjectKind, // Page / Metadata / Font / Annotation / EmbeddedFile / Version
data: EncryptedData, // 内容加密存储
references: Vec<Uuid>, // 对象间引用
permissions: PermissionSet,// 访问控制
created_at: DateTime,
modified_by: ContactId,
}
// 存储引擎：Append-Only Log
// - 每次修改追加新对象，不覆盖旧数据
// - 天然支持版本回溯与审计
4.3 加密策略
- 文档级加密：整体 AES-256-GCM，持有密钥方可打开
- 对象级加密 ：每页/每文件独立加密，不同角色持有不同密钥
- 项目经理 → 全部页面
- 结构工程师 → 仅结构图纸页
- 甲方 → 仅预览版（带水印）
- 版本独立密钥：每个版本用独立密钥，历史版本泄露不影响当前
4.4 "三条腿走路"的存储哲学
- PDF → 对外呈现与归档（兼容性）
- 私有格式 → 内部存储与协同（性能与可控性）
- 源文件 → 离线编辑备查（原始格式备份）
5. 全生命周期集成：PDF 作为"共同语言"
5.1 在各模块中的角色
| 模块 |
PDF 的作用 |
| 通讯录 |
导出组织架构图/项目通讯录为 PDF |
| 消息通信 |
消息引用 PDF 图纸，点开即阅 |
| 工作流 |
审批单、修改建议、变更记录 → 自动生成带时间戳的 PDF 审计单 |
| 项目计划 |
阶段性成果自动汇总为 PDF 报告 |
| 文档网络化 |
总图等核心文档，点开即阅（默认只读），修改建议以 PDF 对比形式提交 |
5.2 核心闭环场景：文档修改与确认
非所有者修改图纸
↓
生成修改建议（修改前/后 PDF 对比视图）
↓
消息推送给所有者（带 PDF 差异高亮预览）
↓
所有者确认（采纳/拒绝）
↓
采纳 → 新版本自动生成 → 所有关注者收到通知
拒绝 → 附理由退回 → 提议人收到反馈
↓
全流程自动归档为 PDF 审批单（含签名+时间戳）
6. 总结
| 维度 |
核心结论 |
| 统一呈现 |
所有文档类型（CAD/Office/图片/扫描件）统一走 PDF 渲染管道，用户看到的是同一个界面、同一套交互 |
| 技术底座 |
zpdf 作为 PDF 渲染引擎，MIT 协议、纯 Rust、双渲染引擎，是当前最优选 |
| 存储演进 |
以 PDF 的对象化结构为思想来源，逐步构建私有格式，实现天然加密、版本控制、全文索引 |
| 全生命周期 |
PDF 是贯穿通信、工作流、计划、文档管理的"共同语言"，也是最终归档的法定格式 |
一句话：PDF 渲染器是平台的"通用文档显示驱动"，所有文档在入库时转化为 PDF，所有用户在任何模块看到的是统一的 PDF 视图，所有成果最终归档为 PDF/A。