Invoicerr 是一款开源、可自托管的发票管理应用，支持发票创建、PDF 生成、邮件发送与收款跟踪。本文将从零基础出发，带你用 Invoicerr 在 5 分钟内开出一张可下载、可发送的专业发票，并了解其背后的编号规则、PDF 渲染机制和邮件模板配置。

一、开始前的快速准备

开票前，先花一分钟补全公司资料——这些信息会打印在每张 Invoicerr 发票上：

这些都在Settings → Company中配置，详见 company-branding.md。

二、发票创建：四步向导快速开出一张发票

进入左侧菜单Invoices，点击右上角New Invoice，会打开四步向导：Details → Lines → Options → Summary。

1. Details：选择客户（可当场新建）、填写开票日期与到期日（到期日会按你的付款条款自动推算）、选择货币。
2. Lines：逐行填写名称、数量、单价、VAT 税率和折扣。输入商品名称时，系统会实时联想你的Articles商品目录，选中即可自动带出价格。
3. Options：关联源单据（如已签署的报价单）、填写客户参考号 / PO 号、备注。
4. Summary：核对总额后保存。

💡小技巧：草稿（Draft）状态可以随时编辑甚至删除；一旦验证（Validate）或发送，发票就被分配正式编号并锁定，此后只能开具红字发票（Credit note）来更正。

前端创建向导的实现位于 document-create-dialog.tsx，发票列表页逻辑见 documents 页面/documents/[typeId]/index.tsx)。

三、PDF 生成：一份合法编号的发票如何变成文件

保存发票后，Invoicerr 会按所在国家的法定格式自动分配编号，例如法德意波均为INVOICE-2026-0001这样的年度序列，编号一经发放永不复用。

3.1 渲染机制

PDF 由后端文档渲染模块生成：先按固定布局拼出 HTML（公司抬头、双方地址与法定标识符、明细行、合计、SEPA 付款二维码与支付方式），再交给内置 Chromium 渲染为 PDF。核心代码在 render-pdf.ts，HTML 拼装逻辑在 render-html.ts。

3.2 品牌化定制

在Settings → Branding中上传 Logo、选择强调色与字体（Classic、Modern、Minimal、Bold 四套预设一键生效），右侧预览即使用与真实发票完全相同的渲染器生成，所见即所得。

3.3 下载多种格式

编号后除了普通 PDF，还可下载各国电子发票 XML：CII、UBL、Factur-X、FatturaPA（意大利 SdI）、FA(3)（波兰 KSeF）、Peppol BIS Billing 3.0、XRechnung，完整列表见 invoices.md。

四、邮件发送：从发送到收款的一站式闭环

4.1 一键 Send

在发票行或详情页点击Send，Invoicerr 会将 PDF 作为附件通过邮件发给客户；已连接电子发票通道的国家（如波兰 KSeF、意大利 SdI、法国 PDP）会同时走国家通道投递。

4.2 自定义邮件模板

进入Settings → Email Templates，可为每种单据类型（发票、报价单、红字发票等）独立编辑主题与正文，支持{displayNameNumber}、{companyName}等占位符。注意：自定义模板按你写的内容原样发送，不做逐收件人翻译；内置默认模板才会跟随文档语言自动切换。

更多规则见 communication.md 与 document-language.md。

4.3 邮件服务商配置

邮件投递通过 SMTP 或 Resend 完成，在 docker-installation.md 中配置SMTP_HOST、SMTP_USER、SMTP_FROM、RESEND_API_KEY等环境变量即可，每个公司也可在Settings → Mail中单独指定自己的发信服务器。

五、发送之后：收款跟踪让发票闭环

发送不是终点。发票状态从Sent变为Unpaid → Partially paid → Settled，全程在列表页一眼可见：

• Record payment：手工登记到款（金额、日期、方式），支持分次付款；
• Bank Reconciliation：导入银行对账单自动匹配到款；
• Payment Methods：开启的收款方式（银行转账 IBAN、PayPal 等）会自动打印在发票上，配置方式见 payment-methods.md。

六、上手检查清单 📋

• 公司资料（名称、税号、地址）已补全
• 至少开启一种支付方式
• 客户信息完整（地址与法定标识符）
• 发票草稿核对无误后 Validate / Send
• 到款后及时登记，发票变为 Settled

从注册客户到把一张带 SEPA 二维码的 PDF 发票发到对方邮箱，Invoicerr 只需几步点击。更多功能（报价单电子签名、周期性发票、多币种）可参考 README.md 与 用户指南 继续探索。