架构与 crates

一凡OFD 的内核是一个 Cargo workspace，13 个库 crate + 1 个 CLI + 3 个语言绑定工程 + 1 个 npm 包装层。

分层

text

┌───────────────────────────────── 应用出口 ────────────────────────────────┐
│  ofd-wasm (WASM·核心)   ofd-wasm-convert / ofd-wasm-tool (WASM·按需)      │
│  ofd-ffi (C ABI)        ofd-cli    bindings/python                       │
└──────┬───────────────────────┬────────────────────┬─────────────┬────────┘
       │                       │                    │             │
┌──────▼───────────────────────▼────────────────────▼─────────────▼────────┐
│                                领域能力层                                  │
│  ofd-render   ofd-convert   ofd-sign   ofd-crypto                         │
│  ofd-tool     ofd-archive   ofd-font    ofd-jpx                           │
└──────────────────────────────┬───────────────────────────────────────────┘
                               │
┌──────────────────────────────▼───────────────────────────────────┐
│                     ofd-core（数据模型与容器）                      │
│           CT_*/ST_* 类型 · XML 序列化 · ZIP 读写 · 内容提取          │
└──────────────────────────────────────────────────────────────────┘

关键设计

1. Canvas 指令流双后端（ofd-render）

渲染层有两条输出路径：render_page_png（tiny-skia 位图）与 render_page_canvas（平台无关的 Canvas 2D 指令 JSON：{width, height, images, commands[]}）。指令流由各端回放：

浏览器：playCanvasScript(canvas, script, dpr)（npm 包内置播放器）
桌面：原生 CLI / WPF 直接用位图输出

这保证了「网页 = 原生」——同一份渲染代码，两种产物，逐像素一致（0.000% 实测差异）。

2. 渲染坐标系

OFD 国标使用毫米物理坐标、Y 轴向下；渲染时统一完成 mm → px 换算与 Y 翻转，出口拿到的指令流即像素坐标。页面尺寸（mm）可经 pageSize / ofd_page_size 查询，用于按真实纸张大小呈现（如 A4 = 210×297mm ≈ 794×1123px @96DPI）。

3. 回退字体注入

未嵌入字体的文档（电子发票是重灾区）需要回退字体才能显示文字。各出口提供注入接口（WASM：setFallbackFont(bytes)；C ABI：ofd_set_fallback_font），渲染与 PDF 转换共用同一份字体。

4. 验签的三层结论

verifySignatures 返回的每份报告区分三层：签名值（SM2 对 TBS 的校验）、文档摘要（dataHash / References 比对）、证书链（逐跳上级公钥验证 + 有效期按签名时间判定 + CA 约束 + 信任锚命中）。不带信任锚时前两层依然有效，链结论显示「未配置信任锚」。

workspace 一览

成员	职责
`crates/ofd-core`	国标数据模型、XML、ZIP 容器、文本/图像提取
`crates/ofd-font`	字型解析、TrueType 子集化、GBK/CID 映射
`crates/ofd-jpx`	JPX/JPEG2000 解码（vendor openjpeg；转换端与渲染端共用）
`crates/ofd-render`	tiny-skia 位图 + Canvas 指令流双后端
`crates/ofd-convert`	PDF ↔ OFD 双向转换（pdf-rs 解析 + pdf-writer 写出）
`crates/ofd-sign`	签名/验签/电子签章（SM2、SES、X.509 链）
`crates/ofd-crypto`	SM4 内容加密 + SM2 数字信封
`crates/ofd-tool`	合并、水印（文字/图像）、页面操作（抽取/删除/拆分/旋转）、生成 API
`crates/ofd-archive`	OFD-A 合规检查与去技术化
`crates/ofd-ffi`	C ABI 动态库（`include/ofd.h`）
`crates/ofd-wasm`	wasm-bindgen 绑定 · 核心模块（解析/渲染/文本/验签/授权）
`crates/ofd-wasm-convert`	WASM 转换模块（PDF↔OFD，按需加载，独立授权）
`crates/ofd-wasm-tool`	WASM 工具模块（合并/拆分/旋转/水印/生成/注释/OFD/A，按需加载，独立授权）
`cli/`	ofd-cli 命令行
`bindings/python` `bindings/csharp` `bindings/java`	语言绑定
`packages/ofd`	npm 包 `rust-ofd`（.gen 产物 + 播放器 + 类型）

架构与 crates ​

分层 ​

关键设计 ​

1. Canvas 指令流双后端（ofd-render） ​

2. 渲染坐标系 ​

3. 回退字体注入 ​

4. 验签的三层结论 ​

workspace 一览 ​