73 lines
6.3 KiB
Markdown
73 lines
6.3 KiB
Markdown
# 收据工坊
|
||
|
||
面向 Windows 10 x64 的本地收据工具。安装后无需登录或联网，无需安装 Excel。
|
||
|
||
## 发给用户使用
|
||
|
||
当前交付版本为 1.0.2。将 `release/收据工坊-1.0.2-Windows64位.zip` 发给用户，完整解压后双击其中的 `ReceiptStudio-1.0.2-win-x64-setup.exe` 安装，再从桌面快捷方式打开。压缩包附有中文使用说明；安装包不包含开发机的收据、印章、设置或测试数据。首次配置导出目录、印章文件夹及常用姓名，多台电脑使用不同编号前缀。
|
||
|
||
用户操作说明见 [用户使用说明](docs/用户使用说明.txt)。交付前运行 `npm run package` 生成安装包，`npm run test:package` 用独立数据验证打包后的程序；安装包不需要与源码或 node_modules 一起发送。当前未配置代码签名证书，部分电脑可能提示未知发布者。交付后请在实际打印机上试打一页。
|
||
|
||
## 使用
|
||
|
||
1. 打开“偏好设置”，选择导出目录和印章文件夹，填写默认出纳、复核人。
|
||
2. 在“印章管理”选择本批印章；也可以明确选择不使用印章。
|
||
3. 在工作台下载 Excel 模板，每行填写一条收费项目，再导入；“按分组核对收据”默认收起，点击标题展开后，可按学校、年级、收费项目整组勾选，核对张数、金额和待修改条数。
|
||
4. 核对错误行、选中数据与右侧预览，选择 PDF、PNG、A4 打印版后生成。A4 预览按已选分组显示对应页，不跨组混排。
|
||
5. 补打请到“生成记录”，按学校、年级、收费项目，或输入姓名、任意收据编号查找，预览匹配的原收据。重新导出沿用原编号、数据和印章，导出该批全部收据。
|
||
6. 生成记录支持逐批删除，确认后移除批次数据；已导出的文件保留，流水号继续递增。删除后不能在列表中补打该批次。
|
||
|
||
生成记录默认每页 5 条，可切换为每页 10、20 或 50 条，并记住上次选择。列表底部显示总条数、当前范围和页码，可使用首页、上一页、页码、下一页和末页翻页。改变筛选条件或每页条数会回到第一页；删除末页最后一条记录后自动回到有效页。分页覆盖全部生成记录。
|
||
|
||
A4 打印版默认上下两张，奇数张时最后半页留空，也可选每页一张。单张 PDF/PNG 页面为 190 × 140 mm；收据主体为 180 × 120 mm。打印 A4 文件时使用 A4、实际大小或 100% 比例。首批请在实际打印机上试打一页。
|
||
|
||
未导入 Excel 时，A4 示例按当前“每页张数”显示一张或两张不同的样张；切换张数立即更新预览。导入后只预览已勾选的同组收据，预览上方显示分组、组内已选张数和本页张数。当前分组仅选一张或最后一页剩一张时，会说明下半页留白的原因。
|
||
|
||
每次导出自动建立独立批次文件夹，生成成功后自动打开输出目录，这两项行为无需设置。批次保留原有命名，内部按“学校 → 年级 → 收费项目”分层。单张 PDF、PNG 以及该组的 A4 打印版放在同一个项目文件夹；每组独立排版，组内保持 Excel 顺序，每页两张时奇数张的最后半页留空。生成清单保留在批次根目录，记录文件的相对路径。历史记录缺少学校或年级时，使用“未分类学校”“未分类年级”目录。文件名在“偏好设置 → 文件与常用选择 → 导出的文件叫什么名字”中调整，修改后立即显示文件名示例。
|
||
|
||
```text
|
||
原有批次文件夹/
|
||
巴南中学/
|
||
高2028届/
|
||
秋季学期服务费/
|
||
SJ00000001_巴南中学 高2028届 张三.pdf
|
||
SJ00000001_巴南中学 高2028届 张三.png
|
||
A4打印版_每页2张.pdf
|
||
生成清单.json
|
||
```
|
||
|
||
Excel 必填列：收款日期、学校、年级、姓名、收费项目、金额。收据上的客户名称自动按“学校 年级 姓名”拼接，三列去除首尾空白后用一个空格分隔。选填列：出纳、复核。金额为正数，最多两位小数，上限 9,999,999.99 元。单次最多 5000 条，仅支持 .xlsx。印章支持 PNG/JPG/WebP，每张不超过 8 MB，列表最多加载 100 张；建议透明 PNG。
|
||
|
||
## 编号与本地数据
|
||
|
||
默认编号 SJ00000001，按前缀独立递增。预览不占号，正式生成前先持久保存编号；失败、取消和重启后可从生成记录按原编号重试。重复导入相同文件会提示；只有明确继续才会生成新编号。
|
||
|
||
设置文件和 SQLite 记录保存在 Windows 用户数据目录。开发数据在 .local-data/app，自动测试数据在 .qa/profile，生产数据与二者隔离。升级及默认卸载保留用户数据。
|
||
|
||
多台电脑离线使用时，给每台设置不同编号前缀。
|
||
|
||
## 开发
|
||
|
||
本地调试无需安装程序，双击项目根目录的“启动本地调试.cmd”即可。入口优先使用这台电脑已有的兼容 Node 运行环境，不改变系统默认 Node 版本。
|
||
|
||
请在启动后自动弹出的“收据工坊”独立桌面窗口中调试。桌面窗口按 F12 打开调试工具；界面修改会自动更新。浏览器直接打开 127.0.0.1:5173 只会加载前端资源，完整的导入、印章和导出功能需要桌面程序。修改 src/main、src/core 或 src/shared 中影响主进程的代码后，关闭窗口并重新启动。开发设置和编号保存在 .local-data/app。
|
||
|
||
常规命令需要 Node.js 24 LTS（最低 22.13）、npm，以及 Windows 10 x64。
|
||
|
||
- npm install
|
||
- npm run dev：桌面开发环境
|
||
- npm test：核心行为测试
|
||
- npm run build：类型检查和构建
|
||
- npm run test:desktop：真实 Electron 集成验证（隐藏窗口，产物在 .qa）
|
||
- npm run test:loading：加载时机、持续旋转及取消选择验证（隔离测试数据）
|
||
- npm run test:history：记录分页、每页条数记忆、筛选和删除末页验证（隔离测试数据）
|
||
- npm run test:print：较大印章批量打印、错误提示和原编号重试验证（独立测试数据）
|
||
- npm run package：生成 Windows x64 安装程序
|
||
- npm run package:dir：生成免安装应用目录
|
||
|
||
依赖版本由 package-lock.json 锁定。应用、字体回退、PDF 渲染资源均使用本地资源。开发依赖下载需要网络，已安装的应用运行不依赖网络。
|
||
|
||
## 扩展
|
||
|
||
详细模块边界与扩展方法见 [架构说明](docs/ARCHITECTURE.md)。
|