Invoice Generator

核心用法

Invoice Generator 是一款将结构化 JSON 数据转换为专业 PDF 发票的命令行工具。用户可通过管道输入 JSON、指定完整文件路径或调用预存配置模板三种方式生成发票。输出自动保存至指定目录，支持智能版本递增避免覆盖。

显著优点

• 标准化流程：严格的 JSON Schema 校验确保数据完整性，避免手工制单的格式错误
• 模板复用：支持将常用客户配置保存至 configs/ 目录，实现一键复用
• 专业输出：基于 WeasyPrint 生成打印级 PDF，适合直接发送客户或存档
• 自动化友好：纯命令行设计，易于集成 CI/CD 或财务自动化脚本

潜在局限

• 学习门槛：需理解 JSON 结构及环境变量配置，非技术用户上手困难
• 样式固定：模板定制化能力有限，难以满足高度品牌化需求
• 依赖链长：需 Node.js + WeasyPrint + jq 等二进制依赖，跨平台部署复杂
• 无内置校验：JSON 字段错误仅返回退出码，缺乏交互式修正提示

适合人群

• 开发者、自由职业者及小型技术团队
• 已有自动化财务流程的企业
• 需要批量生成发票的 SaaS 或电商平台

常规风险

• 路径遍历风险：若 INVOICE_DIR 配置不当，可能暴露敏感目录
• 数据注入：未对输入字段做 HTML/脚本转义，恶意描述字段可能影响 PDF 渲染
• 版本冲突：自动递增命名可能导致发票编号与实际业务系统不一致
• 依赖安全：WeasyPrint 等外部工具需单独维护更新

核心用法

invoice-generator 是一款基于本地运行的发票生成工具，专为需要快速创建专业 PDF 账单的用户设计。用户只需提供结构化的 JSON 数据，即可生成包含公司信息、客户详情、服务项目和付款条款的完整发票文档。

使用流程：
1. 配置 INVOICE_DIR 环境变量指定发票存储目录
2. 准备包含公司、客户、发票项目等信息的 JSON 文件
3. 通过 generate.sh 脚本执行生成，支持 stdin 输入、完整路径或模板配置三种模式
4. 自动输出版本化的 PDF 文件到指定目录

显著优点

• 完全离线运行：零外部网络请求，商业敏感数据不出本地环境
• 极简依赖：仅依赖 handlebars@4.7.8 模板引擎，无已知安全漏洞
• 灵活输入方式：支持即时 JSON 流、文件路径或预存模板三种调用模式
• 自动版本管理：同名发票自动追加版本号，避免覆盖风险
• 专业输出：基于 weasyprint 生成高质量 PDF，适合正式商务场景

潜在局限

• 环境依赖：需预装 Node.js、jq 和 weasyprint，部署门槛略高于纯 CLI 工具
• 无内置校验：JSON 字段长度、数值范围等边界校验需用户自行保证
• 单一输出格式：仅支持 PDF 输出，无 Excel/Word 等替代格式
• 模板固定：Handlebars 模板需手动修改源码调整样式，无动态主题切换

适合人群

• 自由职业者、小型工作室需要快速生成规范发票
• 注重数据隐私、拒绝云端 SaaS invoicing 的企业
• 需要将发票生成集成到自动化工作流的开发者
• 已有 Node.js 技术栈的技术团队

常规风险

• 输入污染风险：未对 JSON 字段长度做限制，极端数据可能导致渲染异常
• 文件权限问题：生成文件使用默认权限，多用户环境建议手动设置 644
• weasyprint 依赖：该工具本身有系统级依赖（如 GTK），跨平台部署可能遇到兼容问题