# MoonBit 黑客松项目申请书

## 1、项目名称

**FoldLedger：MoonBit 小册子双面打印拼版规划器**

## 2、项目简介

FoldLedger 是一个使用 MoonBit 编写的小册子拼版规划库和命令行工具，面向讲义、复习资料、培训手册及活动手册的双面打印准备环节。

将连续页面打印后对折装订，并不能直接按原稿顺序逐页排版。使用者需要计算每张纸正反面的左右页码、补足空白页，并在资料较厚时分成若干独立折叠的册。选取原稿部分章节、改变装订方向或双面翻转设置后，手工计算更容易出现页序错乱、遗漏和重复。

FoldLedger 接收原稿页数、页码选择、每册容量、装订方向和双面翻转边，生成确定性的拼版计划。计划明确记录每张纸正反面对应的原稿页码、补白位置和背面旋转角度，同时提供 JSON、文本清单及 SVG 预览，便于人工核对或由下游程序接入。

项目核心由 MoonBit 实现，包括页码解析、输入验证、分册算法、补白计算、装订转换和结果序列化。Node.js 适配层读取 PDF 并消费 MoonBit 计划，生成双面拼版 PDF；输出面向数字文档处理，不控制外部设备。

## 3、项目方向，通用性说明

**项目方向：应用开发与内容处理，具体为文档印前处理及可复用的拼版规划组件。**

项目面向具有连续页面和折叠装订需求的文档，不依赖某个学校、课程、企业或内容主题。教师讲义、学生复习资料、企业培训材料、社团手册等均可使用同一套数据模型和规则。

通用性体现在以下方面：

- **与内容格式解耦。** 核心仅处理原稿页码与纸面槽位，不要求读取 PDF、Word 或图片内容。不同文档生成系统可以在获得页数后调用规划库，再根据输出映射原始页面。
- **与上层应用解耦。** 既提供可直接运行的 CLI，也公开 MoonBit API，便于被教学材料生成器、文档处理服务和印前工作流调用。
- **与输出消费者解耦。** JSON 供后续页面合成程序读取，文本清单供人工核对，SVG 供可视化审阅。三种结果来自同一个规划模型。
- **可重复、可验证。** 相同输入产生相同计划，页码与补白均可追踪，适合在文档更新或参数调整后进行自动化回归检查。
- **支持多种排版参数。** 提供页码子集选择、分册容量、左右装订以及横向纸张的长边/短边双面翻转配置。

本项目不绑定特定硬件或驱动；旋转和页槽信息通过 JSON、SVG 与 PDF 页面元数据表达。

## 4、至少 3 个完整的预期使用场景

### 场景一：教师制作分册课堂讲义

**使用者与问题：** 教师准备了一份 20 页讲义，希望按每册最多 16 页组织成可折叠的小册子。直接按普通双面页序打印会造成折叠后的页码顺序错误，手工排页又容易漏掉末册。

**输入与操作：** 教师输入原稿 20 页、每册 16 页、左侧装订和短边翻转，运行：

```bash
npm run impose -- --input lesson.pdf --output lesson-booklet.pdf --signature 16
```

**项目输出：** 生成 2 册、5 张双面纸、0 个补白页的计划。第一册包含原稿第 1–16 页，第二册包含第 17–20 页；第一张纸正面为 `[16, 1]`、背面为 `[2, 15]`，末张纸正面为 `[20, 17]`、背面为 `[18, 19]`。

**后续使用与价值：** 教师先查看 SVG 确认册序，再用生成的 PDF 和 JSON 交给后续数字文档流程。项目输出的页码映射可被其他排版工具消费。

### 场景二：学生从复习资料中抽取章节制作便携小册

**使用者与问题：** 学生有一份 40 页复习资料，仅需要第 1–8 页与第 21–30 页，共 18 页。抽取后既要保持所选章节顺序，又要知道补白应放在哪里，避免把原稿页码与抽取后的逻辑页码混淆。

**输入与操作：** 学生使用页码选择表达式指定内容：

```bash
npm run impose -- --input study.pdf --output study-booklet.pdf --select "1-8,21-30" --signature 16
```

**项目输出：** 按列举顺序选取 18 个原稿页面，生成 2 册、5 张双面纸。第一册包含所选的前 16 页；第二册包含原稿第 29、30 页，并在末尾补 2 个空白页。计划中的非零页码始终指向原稿页码，0 明确表示空白。

**后续使用与价值：** 学生根据预览核对章节和末册补白，再将页码计划用于排版。若输入重复页码、倒序范围或超出 40 页的页码，工具会在输出文件前报错，避免错误选择进入后续制作流程。

### 场景三：社团制作右侧装订的活动手册

**使用者与问题：** 社团准备一份 12 页活动手册，设计要求右侧装订，所用打印流程采用横向纸张长边翻转。工作人员需要确认左右页序和背面朝向，避免照搬左装订模板。

**输入与操作：** 工作人员明确设置装订方向与翻转边：

```bash
npm run impose -- --input event.pdf --output event-booklet.pdf --signature 16 --binding right --duplex long
```

**项目输出：** 生成 1 册、3 张纸、0 个补白页的计划。右装订会交换每面左右页槽；第一张纸旋转前的正面逻辑页槽为 `[1, 12]`、背面为 `[11, 2]`，背面整体旋转角度标记为 180°。SVG 展示对应的页码与旋转效果。

**后续使用与价值：** 排版人员查看 JSON/SVG 并使用生成的 PDF 进行数字审阅，再将计划交给下游文档处理流程。

### 场景四：文档平台集成自动拼版规划

**使用者与问题：** 一个使用 MoonBit 的培训资料生成系统，需要为不同课程输出一致、可审查的装订计划。课程页数经常变化，人工重算页码和补白耗时且难以追溯。

**输入与操作：** 平台在文档生成后取得页数，调用 `parse_selection` 与 `make_plan`，传入章节页序、每册容量、装订方向和翻转配置；再使用 `plan_to_json` 保存完整计划，使用 `plan_to_svg` 生成人工复核图。

**项目输出：** 每次生成均得到包含原稿页序、总纸张数、分册数量、补白数量及逐张纸正反面映射的结构化结果。配置或页数改变时，可比较计划并检查每个选中原页是否恰好出现一次。

**后续使用与价值：** 平台将 JSON 交给自行实现的 PDF 页面合成器，并在部署前运行规划测试。FoldLedger 提供的是可复用的纯规划层，使平台无需把文件处理、打印驱动与页码算法耦合在一起；该场景中的平台和 PDF 合成器属于预期集成方，不是仓库内已实现的产品。

## 5、拟实现的核心功能

本项目围绕“输入文件—输入验证—拼版规划—可交付输出”构建以下核心功能。下列第一至第六项已形成可运行实现，第七项为后续扩展计划。

### （1）页码选择与严格输入验证

- 支持原稿页数 1–10,000 页。
- 支持单页、连续范围及混合表达式，如 `1-8,21-30`，保留列举顺序。
- 拒绝重复页码、越界页码、倒序范围、空选择及整数溢出。
- 每册容量为 4–64 页且必须是 4 的倍数。

### （2）分册、补白与正反面布局

- 按每册容量拆分选中页面，分别计算各册外层到内层的纸张页序。
- 末册仅补到最近的 4 页倍数，不强制补满每册容量。
- 输出原稿页码到纸张正反面左右槽位的映射；使用 0 表示补白。
- 支持左右装订；记录长边/短边双面翻转所需的背面整体旋转角度。

### （3）可审阅的结果输出

- 输出包含分册、纸张、原页映射、补白和旋转信息的完整 JSON 计划。
- 输出便于终端阅读的文本清单。
- 生成含标题、说明、折线和页码的 SVG 拼版预览。
- 大计划的 SVG 最多显示前 24 张纸并标明总量；JSON 始终保留完整结果。

### （4）MoonBit 库与 CLI 集成

- 提供 `Config`、`Plan`、`Sheet` 等公开数据模型及规划、序列化接口。
- 核心不访问网络或文件，便于嵌入其他 MoonBit 应用。
- CLI 在写文件前完成输入验证，拒绝覆盖已有文件，并提供明确错误信息与退出码。
- 采用 MIT License，提供使用文档、示例计划和可复现验收脚本。

### （5）PDF MVP 适配器

- 读取 1–10,000 页、页面尺寸一致的输入 PDF。
- 调用 MoonBit 规划器生成每张纸的正面和背面，并输出两页合一的拼版 PDF。
- 同时保存 JSON 计划和 SVG 预览；拒绝覆盖已有文件，并在失败时清理已创建的输出。
- 支持页码选择、分册容量、左右装订和长边/短边双面设置。
- 输入 PDF 页面尺寸必须一致；页面内容会被嵌入输出，注释、表单和交互元数据不保证保留。

### （6）工程验证

- 核心测试涵盖已知 8 页布局、跨册边界、原页映射、补白、左右装订和旋转设置。
- 遍历 2,580 种组合，验证原页不丢失、不重复、补白数量和折页配对关系。
- CLI/PDF 测试覆盖 10,000 页输入、JSON 解析、文件保护、参数错误、两页合一 PDF 和背面旋转。
- 当前 7 个 MoonBit 测试、12 个 CLI/PDF 集成测试已通过；已在本地 MoonBit JS 路径执行完整验证。
- 验收入口：`node scripts/verify.mjs`，覆盖 MoonBit 核心、CLI、PDF 生成和数字渲染产物。

### （7）后续扩展计划

- 根据数字文档处理需求探索裁切线、出血和爬移参数的结构化输出。
- 在完整标准库产物可用时验证 WASM 后端。

上述扩展尚未实现，不作为当前版本已完成功能申报。

## 6、是否为原创项目、移植项目或参考已有开源项目

**项目类型：原创实现，非移植项目；参考已有文档印前工具的使用场景与产品边界。**

FoldLedger 的 MoonBit 数据模型、页码解析、分册规划、输入验证、JSON/SVG 输出、CLI 和测试由本项目独立实现，未复制其他拼版工具的源码，也未将已有项目简单更名或拆分作为新项目。

小册子拼版的页序公式属于已有领域知识，本项目不将其宣称为新发明。项目贡献在于把这些规则落实为 MoonBit 原生、可复用、可验证的规划接口，并提供原稿页码追踪、末册补白、装订与旋转约定及可视化审阅工作流。

与此前的 MoonLayout Audit 相比，两者的输入、业务算法和成果不同：前者审计图形节点与连线坐标，FoldLedger 规划文档页码与物理纸面映射，没有复用前者的业务实现。

选题阶段对公开 GitHub 仓库进行了 MoonBit 小册子、拼版等关键词检索，未检出同方向结果；检索范围和记录见 `docs/RESEARCH.md`。这不构成全球唯一性声明，也不能覆盖未公开的报名项目，最终仍以赛事审核为准。

开发中使用 AI 辅助接口设计、实现、测试和文档整理。参赛者需理解拼版公式、数据契约及验证边界，并对提交成果负责。

## 7、如为移植项目，需说明参考项目名称、来源链接和许可证

**移植项目说明：不适用。FoldLedger 不属于移植项目，没有被移植的上游代码、规则文件或运行时，因此不存在被移植项目的许可证继承关系。**

为完整披露参考来源，列出用于了解已有工作流和明确项目边界的资料：

| 参考名称 | 来源链接 | 参考范围与代码使用情况 |
| --- | --- | --- |
| pdfbook2 | https://ctan.org/pkg/pdfbook2 | 参考小册子制作工具的产品用途；未复制、修改、链接或分发其源码，也不调用其 TeX 运行时 |
| Adobe Acrobat 小册子打印说明 | https://helpx.adobe.com/acrobat/using/print-booklets-pdf-portfolios.html | 参考用户的双面打印与小册子工作流；属于商业产品使用说明，并非本项目移植的开源代码 |

PDF MVP 适配层使用 `pdf-lib` 1.17.1 进行 PDF 页面读取和写出，依赖版本锁定在 `package-lock.json`；该库使用 MIT License，未复制其源码。其余拼版规则、MoonBit API 和测试由本项目实现。

**FoldLedger 自身许可证：MIT License，完整文本见仓库根目录 `LICENSE`。**