红头公文模板与公章生成

红头公文模板（official-doc.typ）是 endfield-docmaker 内置的官方公文排版模板，其最显著的特性是会在渲染时自动生成一个带有随机偏移与随机旋转的圆形公章（由 tuzhang.typ 圆形公章生成器提供），从而模拟真实公文盖章的效果。

目的与范围（Purpose and Scope）

本页覆盖 endfield-docmaker 中"红头公文"模板能力的整体范围：

模板资产的定位与来源（official-doc.typ 红头文件模板、tuzhang.typ 圆形公章生成器）
模板在应用内的注册与国际化命名（template_official_doc）
公章"随机偏移 + 随机旋转"生成机制的外部行为
与兄弟模板（试卷模板）在产品中的并列关系

不在本页范围内、留给兄弟页面的内容：

试卷模板的分数计算与板块逻辑 — 见 templates.official-testpaper（试卷模板）相关页面
Typst 排版引擎本身的接入与渲染管线 — 见 Typst 引擎/渲染相关页面
应用整体架构、模板选择 UI — 见应用架构相关页面

概述（Overview）

endfield-docmaker 是一个基于 Typst 排版引擎的文档生成器。它将若干预置的 Typst 模板作为静态资产打包，用户选择模板后填写内容，由 Typst 引擎渲染输出最终文档。

红头公文是其中的官方文档模板，对应中文文案 公文。它的两个核心卖点在 README 中被明确列出：

公文模板自动生成带有随机偏移和旋转的圆形公章

Source: README.md

也就是说，用户不需要手动绘制或上传印章图片：模板在渲染阶段自动调用公章生成器，产出一个圆形公章，并施加随机化的位置偏移与角度旋转，使每一次生成的公文都带有一枚"看起来像手工盖上去"的印章，增强拟真度。

另一个产品级特性是内容区域支持 Typst 标记语法（README 同段落说明），用户在公文正文里可以直接使用 Typst 的标记语言进行排版。

关键术语

术语	含义
红头文件	具有红色抬头（发文机关标志）的正式公文格式
公章 / tuzhang	圆形印章；模板内置的公章生成器名称即拼音 `tuzhang`
随机偏移 / 随机旋转	公章生成时叠加的随机平移与随机角度，模拟人工盖章的不可复现性
Typst	模板使用的排版引擎，内容区域支持其标记语法

架构（Architecture）

下面的架构图基于仓库中已验证的事实绘制：模板资产位于 src/lib/assets/typst/，模板名通过 messages/zh.json 中的 template_official_doc 键进行国际化，渲染由 Typst 引擎完成，公章由 tuzhang.typ 生成。

Loading diagram...

图中的依赖关系说明：

official-doc.typ 是公文模板的主体文件，负责红头抬头的版式与正文排版；它在渲染时使用公章能力。
tuzhang.typ 是独立的圆形公章生成器，由红头公文模板消费，产出一个带随机偏移与随机旋转的圆形公章。
messages/zh.json 只负责把模板 ID 映射为用户可见文案，不参与渲染逻辑。
两个 .typ 文件本身是 Typst 源码资产，最终都汇入 Typst 引擎统一编译。

模板资产与文件定位

仓库 README 的目录树把两个文件标注为模板体系的一部分：

text

│       │   └── typst/
│       │       ├── official-doc.typ  # 红头文件模板
│       │       └── tuzhang.typ       # 圆形公章生成器

Source: README.md

需要注意，README 的目录树展示的是概念路径；在当前 main 分支中，红头公文模板实际位于：

text

src/lib/assets/typst/official-doc.typ

Source: official-doc.typ

即它以静态资产（assets）形式随 src/lib 一起打包。tuzhang.typ 与其并列位于同一 Typst 模板目录（README 目录树将其标注为 圆形公章生成器），供公文模板复用。

模板来源与致谢

这两个模板源自社区贡献，README 的致谢部分明确记录了作者：

text

- [ParaN3xus](https://github.com/ParaN3xus) — 红头公文模板 (`official-doc.typ`)
- [Lonyou](https://github.com/Vkango) — 圆形公章模板 (`tuzhang.typ`)

Source: README.md

这一点解释了为什么公章能力是独立文件而不是内联在公文模板里：两个模板由不同作者编写，docmaker 将它们组合成"红头公文 + 自动盖章"的整体能力。实现细节未能从源码读取：本次文档生成时未能读取 official-doc.typ 与 tuzhang.typ 的具体 Typst 源码内容（随机偏移/旋转的参数范围、函数签名、可配置项等），上文的组合方式依据 README 与目录结构推断，如需精确参数请直接查阅上述源文件。

模板注册与国际化命名

用户在界面上看到的模板名称由 i18n 文案文件提供。中文文案中将该模板命名为"公文"：

json

"template_official_doc": "公文",

Source: zh.json

从上下文可见同一命名空间下并列注册了试卷模板（template_testpaper: "试卷"），说明 docmaker 的模板以 template_* 前缀的键统一登记，红头公文是其中之一。

Loading diagram...

核心流程（Core Flow）

以"用户生成一份带公章的红头公文"为主线，整体流程如下：

Loading diagram...

流程要点：

模板选择在前：用户先通过 UI 选定"公文"模板，文案来自 template_official_doc 键。
正文即 Typst：用户内容区域支持 Typst 标记语法，正文与模板在同一个编译管线中处理。
公章生成在渲染阶段：tuzhang.typ 产出的公章叠加随机偏移与旋转，因此每次输出文档中的印章位置和角度都不同——这是刻意设计，目的是模拟人工盖章的随机性，而不是缺陷。
统一编译：红头版式、用户正文、公章图形最终都交给 Typst 引擎一次性排版输出。

配置选项

基于当前可验证的源码证据，该模板的用户可配置项信息有限：

选项	类型	默认值	说明
正文内容	Typst 标记语法字符串	空	内容区域支持 Typst 标记语法（README 声明），与模板一同编译
模板选择	模板 ID（`official-doc`）	—	通过模板选择 UI 指定，文案键为 `template_official_doc`
公章偏移 / 旋转	—	随机	由 `tuzhang.typ` 在生成时随机化，不可由用户固定（依据 README 特性描述）

注意：official-doc.typ 与 tuzhang.typ 的内部参数（如红头文字、字号、公章文字内容、随机数范围等）未能在本次文档生成中从源码读取，上表仅覆盖产品层面可确认的行为。模板内部的详细参数请直接查看 official-doc.typ 与 tuzhang.typ。

API / 接口参考

本页主题是 Typst 模板资产而非 TypeScript 服务，因此没有传统意义上的服务方法签名。可验证的"接口"是资产与文案两个接触点：

模板资产路径

src/lib/assets/typst/official-doc.typ — 红头公文模板主体（红色抬头版式 + 正文排版 + 公章调用）
typst/ 同目录下的 tuzhang.typ — 圆形公章生成器（随机偏移与旋转）

i18n 文案键

键： template_official_doc 值（中文）： 公文 位置： messages/zh.json 第 83 行 用途： 在模板选择 UI 中展示该模板的用户可见名称

失败模式、边界情况与并发

依据当前已验证的源码证据（README 与 i18n 文件），可确认的行为与边界：

随机性即行为：公章的偏移与旋转是每次渲染随机生成的。这意味着同一份内容重复导出会得到不同的印章位置/角度。任何依赖"盖章结果可复现"的自动化流程（如快照测试、内容寻址缓存）都会因此失效——需要在设计流水线时将公章区域排除在精确比对之外。
随机源依赖：若随机化在 Typst 侧完成，则可复现性还取决于 Typst 编译的随机种子机制；此细节未能在源码中核实（tuzhang.typ 内容未能读取）。
字体依赖：红头公文与圆形公章通常需要中文字体支持。若部署环境缺少相应字体，可能出现字形回退或渲染异常。具体字体要求需查阅模板源码（未能从源码核实）。
内容语法错误：正文区域接受 Typst 标记语法，因此非法 Typst 标记会导致编译失败。这是"正文即 Typst"设计的固有代价：换取强排版表达力，同时把语法错误的可能暴露给最终用户。
并发：模板资产是只读静态文件，多用户/多任务并发渲染时不会发生模板层面的写冲突；随机公章的生成是每次渲染独立进行的。

性能与运行注意事项

资产加载：模板作为 src/lib/assets/ 下的静态资产打包，随应用分发，无网络请求开销。
渲染成本：最终渲染由 Typst 引擎承担，公章只是文档中的一个图形元素，理论上不构成主要性能瓶颈；真正的开销通常来自中文排版与字体子集化。
输出可变性：由于公章随机化，任何基于输出内容哈希的去重/缓存策略都需要考虑到"同一输入产生不同输出"这一事实。

扩展点

新增模板：仿照 official-doc.typ 的方式，把新的 .typ 文件放入 src/lib/assets/typst/，并在 messages/zh.json 中以 template_* 前缀注册文案键，即可与既有模板（公文、试卷）并列暴露给用户。
复用公章生成器：tuzhang.typ 是独立的公章生成器，不绑定于公文模板；其他需要盖章效果的模板可以直接复用它，并获得同样的随机偏移/旋转效果。
自定义印章样式：如需固定印章位置/角度或更换印章文字，需要修改 tuzhang.typ 的生成逻辑（具体可配置面未能在源码中核实）。

测试

在本次文档生成过程中未发现针对红头公文模板或公章生成的测试文件证据（Implementation details not found in source）。特别提醒：如前文所述，公章的随机性会直接影响快照类测试的稳定性，若仓库后续补充测试，应关注这一点。

红头公文模板与公章生成

目的与范围（Purpose and Scope）

概述（Overview）

关键术语

架构（Architecture）

模板资产与文件定位

模板来源与致谢

模板注册与国际化命名

核心流程（Core Flow）

配置选项

API / 接口参考

模板资产路径

i18n 文案键

失败模式、边界情况与并发

性能与运行注意事项

扩展点

测试

相关链接