111

docs/ARCHITECTURE.md

@@ -12,6 +12,7 @@
 | src/core/money.ts | 整数分、金额上限、人民币大写、金额格 |
 | src/core/date.ts | 日期与 Excel 日期制 |
 | src/core/templates.ts | 模板接口、注册器、打印页面组合；与桌面环境解耦 |
+| src/core/preview-samples.ts | 未导入数据时的示例收据，按当前页面容量生成，不分配流水号 |
 | src/main/workbooks.ts | WorkbookReader 接口及 .xlsx 适配器 |
 | src/main/ledger.ts | 持久编号、批次快照及删除记录 |
 | src/main/settings-store.ts | 版本化设置及原子写入 |
@@ -76,6 +77,8 @@ importGroupTree 按三级分组统计有效行、待修改行、选中张数和
 
 A4 预览使用 printPreviewRows 在已选同组收据中定位当前行所在页，并按全局已选顺序展示待分配编号。预览查询不修改流水号。设置页面的实时文件名示例和正式导出使用相同的 receiptFileStem，保持前缀、命名方式和字符替换一致。
 
+工作台预览请求显式传递当前 receiptsPerPage，主进程校验为 1 或 2，并只覆盖本次预览上下文；省略时沿用已保存设置，历史预览继续使用原批次快照。切换每页张数无需先保存设置。未导入时由 createPreviewSamples 提供对应张数的不同示例；导入后始终使用真实勾选数据，不补充示例。界面共用 printPreviewRows 计算本页张数，并展示当前分组、组内已选数量及空白半页原因。
+
 记录列表通过 listBatchPage 传递经校验的学校、年级、项目、文本、页码和每页条数，返回当前页、真实总条数及有效页码。无筛选时使用数据库 COUNT/LIMIT/OFFSET；有筛选时逐批匹配同一张收据，统计所有匹配批次并仅构建当前页摘要，末页删除后自动钳制到有效页。学校、姓名和任意编号查找仍覆盖全库。原 listBatches 继续为已有调用提供最多 200 条摘要，bootstrap 提供全库分类选项和真实总数。
 
 界面默认每页 5 条，可选 5/10/20/50；historyPageSize 在设置校验器中为旧配置补默认值，修改后持久保存。筛选或每页条数变化时回到第一页，刷新保留当前页；使用请求版本号保持最新结果。显式翻页沿用整块加载反馈，自动筛选合并短时间内的输入变化。过滤结果仍对应完整批次，重新导出维持原有批次语义。原收据预览可指定匹配编号，旧批次输出目录经过全库归属检查。

docs/VERIFICATION.md

@@ -110,3 +110,11 @@
 - 类型检查、构建及 46 项测试通过，覆盖默认条数、分页不重复、每页 10/50 条、筛选总数、空结果、页码越界、删除末页、201 条记录的最后一页以及旧配置默认值与条数保存。
 - 新增隔离桌面验证 test:history，使用 13 个测试批次实际验证五条分页、范围和边界按钮、翻页、条数切换、筛选回首页、清空筛选、跨板块/重启记忆、逐条删除末页自动回退，流水号保持不变；截图已检查，无界面脚本异常。完整桌面导入/分组/PDF/PNG/A4/原编号补打/重启验证通过。
 - 验证记录：.qa/history-pagination/result.json、.qa/result.json；截图：.qa/history-pagination/pagination.png。测试使用隔离配置，用户记录未改动；未重新生成安装包。重启本地调试后生效。
+
+## 本地调试版：A4 示例张数及实时排版预览（2026-10-19）
+
+- 未导入数据时，示例按当前每页张数提供一张或两张不同收据，单张预览仍只显示一张；示例不会分配编号或写入记录。
+- 修复工作台切换每页张数后，主进程仍沿用已保存张数的问题。预览请求显式传递当前值，主进程校验后仅用于本次预览；历史预览继续使用原批次设置。
+- A4 预览新增当前分组、已选张数和本页张数。分组只有一张或奇数张末页时，明确说明下半页留白原因，继续按学校、年级、收费项目分别排版。
+- 类型检查、构建及 46 项原有测试通过。隔离 Electron 验证已保存每页一张时切换为两张立即显示两张示例、单张/A4 切换、同组非连续行配对、学校与年级隔离、奇数末页说明、取消勾选后重新配对、清空选择及编号与历史总数保持不变；无界面脚本异常，截图已检查。
+- 验证记录：.qa/a4-preview-1792381053561/result.json；截图：同目录 sample-two.png、group-two.png。测试使用隔离配置和 Excel 数据，用户数据未改动；未重新生成安装包。关闭程序后重新启动本地调试生效。

docs/用户使用说明.txt

@@ -0,0 +1,40 @@
+收据工坊 使用说明
+适用系统：Windows 10，64 位
+
+一、安装与打开
+1. 先将收到的压缩包完整解压到一个文件夹。
+2. 双击 ReceiptStudio-1.0.2-win-x64-setup.exe，按照提示选择安装位置并完成安装。
+3. 之后双击桌面上的“收据工坊”打开软件。
+4. 软件无需登录，安装后可离线使用，无需安装开发环境。
+
+二、首次设置
+1. 打开“偏好设置”，选择生成文件的保存位置。
+2. 将印章图片放在电脑上的固定文件夹，然后绑定印章文件夹；推荐使用透明背景的 PNG 图片。
+3. 填写常用的出纳、复核姓名，保存设置。
+4. 多台电脑分别开收据时，请给每台设置不同的编号前缀，例如 CW01、CW02。
+5. 到“印章管理”选择需要使用的印章，也可以选择不使用印章。
+
+三、导入与生成收据
+1. 在“收据工作台”点击“下载模板”，使用 Excel 或 WPS 填写数据，保存为 .xlsx 文件。
+2. 保留第一行表头，将示例行替换成真实数据。每行对应一张收据、一条收费项目。
+3. 必填列：收款日期、学校、年级、姓名、收费项目、金额。出纳、复核可以留空，留空时使用偏好设置中的姓名。
+4. 点击“导入 Excel”，核对金额、姓名、收费项目和勾选张数；需要修改的数据请在 Excel 中改好后重新导入。
+5. “按分组核对收据”默认收起，点击标题可展开，按学校、年级、收费项目整组选择。
+6. 选择单张 PDF、单张 PNG 或 A4 打印版，点击“生成收据”。成功后会自动打开保存文件夹。
+
+四、文件与打印
+1. 每次生成会建立一个独立批次文件夹，内部按“学校 → 年级 → 收费项目”保存文件。
+2. 单张 PDF、PNG 每张收据单独一个文件；A4 打印版会将同一分组的收据合并成打印 PDF。
+3. A4 默认每页上下两张，也可选择每页一张。不同分组单独排版，组内最后一页只有一张时，下半页留白。
+4. 点击左侧不同数据，可查看它所在分组的打印页。预览不占用正式编号。
+5. 打印时打开生成的 A4 打印版 PDF，选择 A4 纸和“实际大小”或 100% 比例。首次使用请先试打一页，核对印章、边距和裁切位置。
+
+五、查找与补打
+1. 在“生成记录”中可按学校、年级、收费项目、姓名或收据编号查找。
+2. 点击“重新导出”会使用原编号、原数据和原印章，导出该批全部收据。
+3. 删除生成记录只删除软件中的批次记录，已导出文件仍保留；删除后不能在列表中补打该批次，收据编号继续递增。
+
+六、更新与提示
+1. 后续收到新版安装包时，先关闭软件，再运行新版安装包更新；同一 Windows 用户下的原设置和生成记录会保留。
+2. 本安装包未配置数字签名，部分电脑可能提示“未知发布者”。请核对安装包来源；单位电脑有安装限制时，请由管理员按单位规定安装。
+3. 设置和生成记录保存在当前 Windows 用户的数据目录中。不同电脑、不同 Windows 用户的数据各自独立。