我们如何打造一款WordPress发票插件：架构、安全与开发经验全记录

🌐 阅读其他语言版本： English · Español · Deutsch · Français · العربية · Bahasa Melayu · 简体中文 · 日本語

大多数小型代理公司和自由职业者开发票的方式无外乎两种：一种是用电子表格加Word模板，由人手动导出成PDF；另一种是使用按用户、按月、无限期收费的在线开票服务。第一种方式只要有两个人同时操作就会出乱子；第二种方式在您增加一位同事、第二种货币，或者遇到一个有特殊需求的客户之前，都还算好用。

这两个问题我们都遇到过，于是我们自己开发了一款WordPress发票插件：ArtinTech Invoice Manager。它以全屏应用的形式运行在WordPress网站上，可以一键导出PDF格式的专业发票，维护带余额的客户档案，跟踪多币种收款，并提供管理用户的后台。这款插件已在本站上线运行，也是我们现在给自己客户开票所用的工具。

本文是完整的开发记录，涵盖插件的功能、构建方式及其背后的原因、安全模型、我们在客户发现之前就找出的问题，以及为了让代码符合WordPress.org插件目录的要求所做的工作。如果您正在考虑是定制开发开票工具还是使用现成产品，文章的最后几节正是为您而写。

我们为什么要自己开发WordPress发票插件

自己开发一款本可以租用的软件，通常是个错误。所以有必要讲清楚，为什么这次不是。决定性的因素是务实的考量，而不是理念之争。

• 数据应该留在企业自己手里。 发票、客户地址和收款记录是一家公司的财务档案。把它们保存在我们本来就在备份和掌控的WordPress数据库中，比在需要的那天去依赖第三方的导出按钮要简单得多。
• 按用户计费，规模越大越吃亏。 一个人用时很便宜的在线工具，一旦小团队和几位外部合作者都需要自己的账号，就会变成一笔实实在在的开支。而插件的成本不管是一个人用还是二十个人用，都是一样的。
• 一次安装，多个相互独立的账户。 我们需要每个人都拥有自己的发票、客户、Logo、银行信息和编号规则，并且在同一个网站上与其他人完全隔离。
• 我们的发票是面向国际的。 我们给海外客户开票，涉及多种货币。我们需要按币种统计的金额，绝不能被悄悄换算，发票上还要印有用于跨境汇款的银行信息。
• 我们希望能随时修改它。 当我们需要一个“标记为已付款”按钮，或一个隐藏客户Logo的开关时，我们希望当天下午就能实现，而不是等待供应商的产品路线图。

这些并不意味着在线开票软件不好，只是取舍不同。把两者放在一起比较会更直观。

	在线开票服务	自托管的WordPress发票插件
数据存放位置	供应商的服务器	您自己的WordPress数据库
团队扩大后的成本	通常按用户数增加	固定，与用户数量无关
部署工作量	几分钟	安装、启用、创建应用页面
定制能力	取决于设置界面允许的范围	代码能做到的都可以
维护	由供应商负责	由您负责，与其他插件一样
集成	通常提供大量现成的连接器	根据您自己的系统按需开发

如果右边一栏看起来像一堆额外的负担，那么在线工具可能更适合您；如果它看起来像您本来就在为网站做的事，那么插件就开始变得合理了。

使用流程：从安装到发票收款

在深入细节之前，先看一遍完整流程：管理员只需做一次的事情，以及账户用户每次给客户开票时要做的事情。一共九步，每一步都以真实界面展示。

第1步：安装插件并创建应用页面

1. 通过 Plugins → Add New → Upload Plugin 上传插件并启用。
2. 在wp-admin中打开新增的 Invoice Manager 菜单。
3. 点击 Create app page。

这会在 /invoice-manager/ 发布一个页面，这个页面就是应用本身。网站的其他部分不会有任何变化，管理员可以立即开始使用。

第2步：登录，或允许他人注册

对于未登录的访客，应用页面会显示自己的登录界面。用户使用平常的WordPress用户名或邮箱登录，并提供“Remember me”和“Forgot password”链接。

如果启用了公开注册，登录表单下方会出现 Create one 链接，点击即可打开注册界面。如果开启了管理员审核，新账户会一直处于待审核状态，直到管理员批准。

第3步：一次性填写企业信息

每位账户用户都从 My settings 开始：

• 上传Logo，然后选择个人或公司。
• 填写地址、联系方式和税号。
• 选择默认币种和付款期限。
• 粘贴银行账户信息。
• 设置发票前缀和起始编号，并添加自己的税率。

这里的所有信息都会自动填入新发票，只需填写一次。

第4步：添加客户

在 Clients → Add Client 中，每个客户只需保存一次：Logo、公司名称和联系人、邮箱、电话、地址和税号。客户档案可以搜索，每张卡片都会显示该客户的发票数量和尚未结清的金额。

第5步：创建发票

点击 New invoice。编号、日期、币种、条款和您的信息都已预先填好。

1. 选择客户。
2. 添加明细行，填写数量、价格和税率。
3. 如有需要，设置折扣，并添加自定义字段，例如采购订单号。
4. 选择这张发票上是否显示您的Logo和客户的Logo。
5. 点击 Save。

合计金额会随输入实时重新计算。

第6步：预览并下载PDF

Preview 会按客户将收到的样子完整显示发票。Download PDF 会保存一份A4文件，您可以通过邮件发送、上传到客户门户或直接打印。

共有三种模板，可在编辑器的模板菜单中为每张发票单独设置：

• Blank：简洁的极简布局。
• Modern：带彩色页眉条。
• Classic：衬线字体配分隔线。

第7步：登记收款

款项到账后，点击发票所在行的 Mark paid；如果是部分付款，则点击 $ 图标，填写日期、付款方式和备注。状态会自动变化：

• 分期付款后变为 Partially paid（部分付款）。
• 余额归零后变为 Paid（已付款）。
• 如果到期日已过而发票尚未全额付清，则变为 Overdue（逾期）。

第8步：跟踪未收款项

仪表盘上的汇总金额会即时更新。对于某个具体客户，打开客户档案中的客户页面即可查看：

• 按币种统计的已开票、已收款和未收款金额。
• 您开给该客户的每一张发票。

打电话催款之前，先打开这个页面就对了。

第9步：管理用户

管理员以及被赋予Invoice Manager Admin角色的人员，可以进入 Admin panel → Users，在这里：

• 批准待审核的注册申请，系统会自动发邮件通知用户。
• 停用或重新启用账户。
• 直接添加用户，新用户会收到设置密码的邮件。
• 修改角色和删除账户。

插件能做什么：功能一览

上面的流程展示了主要路径，这一节介绍插件的其他功能。所有功能都在网站的一个页面中运行，界面设计得像一款独立应用，而不是WordPress后台页面。

发票仪表盘

首页回答的正是每位企业主打开开票工具时最关心的问题：谁欠我们多少钱？顶部显示四个数字：已开票、已收款、未收款和逾期金额。每个数字都按币种分别计算；如果账户用户使用多种货币开票，还可以切换币种。下方是以卡片形式展示的最近四张发票，再往下是完整的发票列表。

列表支持按发票编号或客户名称搜索，可按客户、状态、单据类型和日期范围筛选，并可按任意列排序。在每一行中，无需打开发票，就可以登记收款、标记为已付款、下载PDF、复制或删除。

发票编辑器

编辑器的布局与最终发票一致，所见即所得，操作按钮放在右侧面板中。

• 四种单据类型： Invoice（发票）、Quote（报价单）、Proforma（形式发票）和Credit Note（贷项通知单）。
• 自动编号，每位用户可设置自己的前缀，例如AT2623。编号仍可手动修改，重复编号会被拒绝。
• 开票日期和到期日。 到期日根据每个人的默认付款期限自动填写。
• 明细行：数量、单价、描述，以及从用户自己的税率列表中选择的税率。
• 整单折扣、自定义字段（如采购订单号）、附加公司信息和自由文本描述。
• 客户信息：可从客户档案中选择，也可临时输入，并可当场保存为新客户。
• 币种选择：每张发票单独设置，条款文本则从设置中预先填入。

合计金额随输入实时更新。如果您在有未保存更改时试图离开，应用会先询问再丢弃。这个小细节在开票工具里比在其他任何地方都更重要。

收款、状态与“标记为已付款”

没有人手动设置发票状态。状态由登记在发票上的收款推算得出，因此永远不会与实际资金对不上。

已登记的收款	显示的状态
无	Unpaid（未付款）
少于总额	Partially paid（部分付款）
等于或超过总额	Paid（已付款）
未全额付清且已过到期日	Overdue（逾期）
单据类型为报价单	Quote（永远不计入收入）

每笔收款都包含日期、金额、付款方式和可选备注，因此分期付款和因银行手续费造成的差额都能被准确记录。对于最常见的情况，也就是客户直接全额付款，有一个一键操作的 Mark as paid 按钮，它会以今天的日期登记一笔等于剩余余额的收款。

PDF导出与模板

每张发票都可以预览，并以三种模板之一下载为A4格式的PDF：简洁的Blank布局、带彩色页眉条的Modern布局，以及衬线字体配分隔线的Classic布局。

PDF中包含：

• 开票方和客户的Logo，每张发票都可以单独关闭任意一个。
• 双方地址。
• 明细行、折扣、税额和合计。
• 已收款项、应付余额、银行信息和条款。

客户档案

客户只需保存一次即可反复使用。每个客户都有Logo、公司名称和联系人、地址、税号和备注。

客户列表会显示每个客户尚欠的金额，客户页面则显示：

• 按币种统计的已开票、已收款和未收款金额。
• 完整的发票历史。
• 一个按钮，可直接新建一张已填好该客户信息的发票。

每位账户用户的个人设置

每位用户都有自己的：

• Logo，以及选择以个人或公司身份开票。
• 地址和带国际区号的电话号码。
• 税务登记号和网站。
• 默认币种和以天数计的付款期限。
• 银行信息、发票编号前缀和下一个编号。
• 默认条款文本和一组命名的税率。

因此，同一个网站上的两个人可以开出看起来来自两家不同企业的发票，因为事实上正是如此。

注册、审核与管理后台

应用在前台有自己的登录和注册界面，账户用户完全不需要进入wp-admin。公开注册是可选的；启用后，可以要求新账户经管理员批准后才能使用，每次有人注册，管理员都会收到邮件。

在应用内部，管理员可以使用包含四个部分的 Admin panel：

• Overview： 所有用户的账户数量和开票总量。
• Users： 批准、停用、重新启用、添加或删除账户，以及修改角色。
• Sign-up settings： 注册设置。
• Messages： 通过应用内“Contact us”表单发来的消息。

架构：WordPress发票插件应该如何存储数据

一款插件的长期质量，很大程度上取决于它的数据模型，因为一旦有了真实发票，数据模型就是最难改动的部分。我们很早就做了四个决定，事实证明四个都经得起考验。

使用自定义文章类型，而不是自建数据表

发票、客户和联系消息都是私有的自定义文章类型（Custom Post Types）。每条记录归创建它的WordPress用户所有，结构化数据保存在一条post meta中。个人设置保存在user meta中，插件全局选项则使用Options API。

自建数据库表在数据量极大时可能会稍快一些，但作为交换，文章类型免费带来了很多好处：

• WordPress常规的备份和迁移会自动包含这些数据。
• 导出工具本身就能识别它们。
• 对象缓存无需额外代码即可生效。
• 删除用户时可以连同其记录一起删除，无需编写任何清理代码。

一个企业开票工具，每个人的发票数量很少会超过几千张。在这种规模下，使用WordPress原生方式才是正确选择。

这些文章类型被注册为完全私有：不公开、不可查询、不参与搜索，并且对REST API和站点地图隐藏。发票不可能意外出现在主题的搜索结果或SEO插件的站点地图中。

快照：为什么发票要复制开票方和客户信息

发票是某个时间点的法律记录。如果您明年搬了办公室，去年的发票仍然必须显示去年的地址。因此，创建发票时，插件会把开票方信息复制进发票，客户信息也一样。

修改您的设置或客户地址，永远不会改写历史。如果您确实希望一份旧草稿使用新的信息，编辑器提供了一个明确的操作“Use my latest settings”，而不是在后台悄悄替换。

发票还会保留与客户记录的关联，客户余额正是据此计算的。删除客户时，关联会被清除，但快照依然保留。发票仍能正确显示，只是不再计入一个已经不存在的客户。

状态是计算出来的，而不是存储的

“逾期”取决于今天的日期，如果把它存起来，到明天就可能是错的。插件只存储事实：明细、折扣、收款和到期日，每次读取发票时再计算状态。在商业软件中，存储状态字段是“仪表盘显示已付款、银行却说没有”这类问题最常见的根源之一。

经得起会计审查的金额计算

• 折扣在税前扣除。 10%的折扣会同时降低小计和对应的税额，这符合大多数税制的要求。
• 按行计税。 每一行都有自己的税率，因此一张发票可以同时包含应税和免税项目。
• 贷项通知单在所有合计中按负数计算，报价单则完全不计入。
• 绝不换算货币。 合计金额按币种分别保存。以某个汇率悄悄换算，得出的数字既对不上发票，也对不上银行流水。
• 保存发票时在服务器端重新计算合计，依据是各明细行。浏览器中的计算只用于显示，被篡改的请求无法保存一个对不上的合计金额。

每次请求都校验归属权的REST API

前端通过专用的REST命名空间与WordPress通信。每个路由都经过同一套权限检查：请求必须来自已登录、拥有插件专属权限且账户状态为有效的用户，并且必须携带有效的WordPress nonce。

此外，每个涉及发票或客户的请求，都会检查该记录是否属于当前用户。如果不属于，API返回的是not found（未找到），而不是forbidden（禁止访问）。这种区分是有意为之：“禁止访问”等于承认该ID的记录存在，而“未找到”则不透露任何信息。我们专门做过测试：用一个账户登录，去请求另一个账户的发票。

每个传入字段都会被清理并限制长度：

• 日期必须符合严格的格式。
• 币种必须是三个字母。
• 单据类型和模板必须来自固定列表。
• Logo只接受已上传到本站媒体库中的图片。

上传的图片在进入媒体库之前会被解码，并检查是否为真正的PNG、JPEG、GIF或WebP文件。SVG会被拒绝，因为SVG文件可能携带脚本。

有一个实用细节为我们省去了将来的技术支持工单。一些共享主机和防火墙规则会直接拦截HTTP PUT 和 DELETE 请求。因此，应用将每个写操作都以 POST 发送，并附带WordPress标准的method-override请求头，REST API原生支持这种方式。路由依然符合REST规范，而请求在限制严格的主机上也能正常工作。

账户、角色与审核

插件新增了两个角色和一套权限模型。除了给管理员授予访问权限外，它不会改动WordPress自带的角色。

角色	可使用应用	可管理账户用户	可管理发票管理员和角色
Administrator（管理员）	是	是	是
Invoice Manager Admin	是	是	否
Invoice Account Holder	是	否	否

中间这个角色的存在，是为了让办公室经理可以审核和支持用户，而无需拿到整个网站的钥匙。在应用内无法停用或删除管理员，任何人也不能在那里删除自己的账户，因为这恰恰是会把人锁在自己网站门外的错误。

公开注册默认关闭，需要管理员手动开启。开启后，注册表单有四重保护：

• nonce。
• 隐藏的蜜罐（honeypot）字段：机器人会填写，而真人不会。
• 每个网络地址每小时最多注册五次。
• 密码最短长度限制。

启用审核后，新账户可以登录，但在管理员批准之前只能看到“等待审核”的页面，批准时用户会收到邮件。停用某个用户会通过销毁其WordPress会话，立即让他在所有设备上退出登录，而不是等Cookie过期。

主题无法破坏的全屏应用

开票应用必须在它安装的每一个网站上都保持相同的外观和行为。主题的按钮样式、页面构建器的样式重置、缓存插件的脚本优化器，都可能以不易察觉的方式破坏应用式界面。因此，插件完全接管了自己页面的渲染。

访客打开应用页面时，插件会使用自己的精简模板，而不是网站主题。该模板只通过WordPress标准的样式和脚本函数输出插件自己的样式表和脚本，不包含任何来自主题或其他插件的内容。该页面还会告知缓存不要存储、告知搜索引擎不要收录，因为它是应用，而不是内容。

界面本身使用原生JavaScript模块编写，不依赖任何框架，并打包成一个可读的文件。导航使用基于hash的路由，因此在发票、客户和设置之间切换时页面不会重新加载，浏览器的返回按钮依然可用。所用字体DM Sans随插件一同打包，而不是从字体服务加载，因此应用不会向任何第三方服务器发送请求。

布局从一开始就是为手机设计的。在小屏幕上：

• 侧边栏变为滑出式菜单。
• 数据表格变为堆叠卡片，每个数值都带有标签。
• 发票编辑器重新排列为单列。

客户说已经付款时，人们常常会用手机查看发票。

在浏览器中生成PDF发票

用PHP在服务器端生成PDF，通常意味着笨重的库、服务器上的字体、内存限制，以及在不同主机上差异很大的输出效果。因此，我们改为在用户的浏览器中生成PDF：

1. 发票被渲染为A4尺寸的HTML文档。
2. 该文档被转换为图像。
3. 使用开源库html2pdf.js，将图像放入PDF文件。

这样做有三个好处：

• PDF与屏幕上的预览完全一致，因为它就是那个预览。
• 在任何主机上都能运行。
• 发票数据不会被发送到任何地方进行转换。

代价是，PDF中的文字是图像，而不是可选中的文本。对于用来阅读、打印和归档的发票来说，为了在任何地方都得到一致的输出，这个代价是可以接受的。

我们在客户之前发现的问题

以下每个问题都真实出现在屏幕上。它们值得一一说明，因为每一个都代表了一类在其他项目中同样会出现的问题。

半个像素导致的空白第二页

单页发票下载后变成了两页PDF，而第二页是空白的。原因是：为了让预览看起来像一整张纸，屏幕上的文档设置了1123像素的最小高度，而A4纸在96 DPI下的高度是1122.5像素。多出的这半个像素，就足以让PDF库新开一页。

修复方案是只在导出时移除最小高度，因此预览看起来仍然像一张纸。我们通过统计生成PDF的页数来验证：修复前两页，修复后一页。一张有45行明细的发票，依然会正确延续到有内容的第二页。

自我转义的退出登录链接

WordPress生成退出登录URL的函数，返回的是已经针对HTML转义过的URL，其中的&符号被写成了 &。这在HTML属性中是正确的，但在JavaScript中就是错的：被转义的符号破坏了安全令牌，导致无法退出登录。修复方法是在把URL交给应用之前先解码一次。这是个小问题，但很典型，常常出现在PHP模板与JavaScript的交界处。

从未出现在发票上的客户Logo

客户Logo可以上传，也保存成功了，却从来没有出现在发票上。原因很简单：复制到每张发票中的快照根本没有包含它。修复分两部分：

• 新发票现在会把Logo包含在快照中。
• 早先保存的发票在读取时，会回退使用关联客户当前的Logo，而不改写已存储的数据。

修复显示问题时不动已存储的数据，这是一个值得坚持的好习惯。

与表格不一致的仪表盘卡片

在列表中把一张发票标记为已付款后，表格那一行变绿了，但上方“最近发票”卡片在刷新页面之前仍显示Unpaid。同一份数据的两个视图不再同步。现在，任何修改发票的操作都会用最新数据重新渲染整个页面，因此页面上的所有数字始终一致。

添加Logo后的对齐问题

客户Logo放在地址上方时，“To”区块比“From”区块起始位置更低，发票看起来不平衡。把Logo移到地址右侧后问题解决了：两个区块从同一行开始，Logo与上方的发票编号对齐。随后，我们又把客户栏稍微加宽，让一个典型的瑞士街道地址能保持在一行内。经验是：用真实的客户数据测试发票排版，因为占位名称总是短得恰到好处。

为WordPress.org插件目录做准备

在自己网站上能运行的代码，与能通过WordPress.org审核的代码，并不是一回事。插件目录有自己的具体规则，在提交之前，我们做了多处修改来满足这些要求。

• 不调用外部服务器。 字体最初是从字体服务加载的，这会把每位访客的IP地址发送给第三方。现在，字体已在其开源字体许可下随插件一同打包。
• 脚本和样式通过WordPress自身的函数加载。 手写的script和link标签被替换为已注册、带版本号的资源，运行时配置通过标准的内联脚本机制注入。
• 可读的源代码。 插件目录不接受没有源码的压缩代码。应用包以未压缩形式发布，附带原始模块，readme中也说明了如何重新构建。
• 注明第三方许可。 PDF库和字体在readme中列出了各自的许可和源码链接，许可文件也随插件一同发布。
• 插件不触发核心钩子。 早期版本在注册后会触发WordPress自带的登录动作，现在改为通过插件自己的代码记录登录。
• 卸载时由用户决定是否删除数据。 除非管理员明确要求删除数据，否则删除插件不会移除任何内容。发票是商业记录，因为一次误点击而丢失是不可接受的。
• 完整的readme，包括简短说明、安装步骤、常见问题、隐私说明和更新日志。代码结构也便于官方的Plugin Check工具顺利审查。

这些规则没有一条让插件变得更差，反而有好几条让它变得更好。例如，把字体打包进插件，彻底消除了一个隐私问题。

应该定制开发WordPress发票插件，还是使用现成产品？

坦白说，大多数企业并不需要定制开发开票工具。如果只有一个人，每月用一种货币开几张发票，现成产品就足以胜任，而且比任何定制开发都便宜。当以下几条中有多条符合时，定制开发才会成为更好的选择：

• 多人需要在同一系统中各自独立、相互隔离地开票，而按用户计费开始让人吃不消。
• 开票需要与您业务特有的系统对接，例如预约系统、项目管理工具、ERP或客户门户。
• 您使用多种货币开票，需要绝不在背后被悄悄换算的合计金额。
• 您的发票需要现成工具不支持的规则，例如定制审批步骤、单据类型或编号规则。
• 您希望财务数据保存在自己拥有、自己备份、自己掌控的基础设施中。

如果只符合其中一条，建议先更仔细地比较现成产品。如果符合三条或以上，像这样一款专注的插件，在两三年内的总成本通常低于它所替代的订阅费用和各种变通办法，而且能完全满足您的需求。

无论您选择哪条路，都可以用本文讨论过的几点来衡量任何开票工具：

• 它是否为每张发票保存固定记录，使之后对您或客户信息的修改不会改写旧发票？
• 它是根据收款计算状态，还是直接存储状态？
• 它是否把不同货币分开？
• 它是否把不同用户相互隔离？
• 您能否把自己的数据导出来？

常见问题

WordPress发票插件可以支持多个用户吗？

可以，前提是它就是为此设计的。在ArtinTech Invoice Manager中，每张发票和每个客户都归创建它们的账户用户所有，API在每次请求时都会校验归属权。每位用户都有自己的设置、Logo、编号规则和银行信息，无法看到其他人的数据。

它会把发票数据发送给第三方服务吗？

不会。所有数据都保存在网站自己的WordPress数据库中。PDF在用户的浏览器中生成，字体随插件一同打包。唯一对外发出的消息是普通的WordPress邮件，例如注册和审核通知。

它可以用不同货币开票吗？

可以。每张发票都有自己的币种，仪表盘和客户页面会按币种分别显示合计。不做任何换算，因此数字始终与您实际开出的发票一致。

它与我的主题或页面构建器兼容吗？

兼容。应用页面使用插件自己的模板和资源渲染，因此主题、Elementor或任何其他构建器都无法改变它的外观和行为。网站的其他部分完全不受影响。

这款插件可以在WordPress.org上下载吗？

我们已经为WordPress.org插件目录做好了准备，通过审核后就会在那里上架。在此之前，如果您想使用它，或希望获得根据您的工作流程定制的版本，欢迎联系我们。

你们可以为我的企业开发定制版本吗？

可以。定制发票版式、增加单据类型、对接预约或项目系统、客户门户和审批流程，都是在同一基础上合理的扩展。请参阅我们的WordPress插件开发服务，了解我们如何界定这类工作的范围。

开发这样的WordPress工具是我们的核心业务之一。有些是小修复，比如我们追查到与nonce有效期相关的缓存导致的403错误；有些则是像这样的完整应用，通过我们的WordPress开发和定制CMS与ERP开发服务交付。如果您正在评估开票工具，或者您的企业一直在迁就某款软件，欢迎与我们聊聊。我们会给出坦诚的评估，即使答案是现成产品就已足够。