使用发票和费用数据库中的 Claude Code 构建 VAT 退货系统

简短易读的伴侣。有关代码、提示、架构、HMRC MTD 演练和边缘案例的完整约 5,000 字的深入研究，请阅读 长篇文章.

季度 VAT 是我这个月最糟糕的部分

每个季度，英国小企业必须生成 VAT 报表：九个框的数字（销售、采购、VAT 到期、VAT 可回收、欧盟商品（如果您在北爱尔兰）、总计、净额），并通过 HMRC Making Tax Digital (MTD) 提交。多年来，我的流程是这样的：在 Postgres 中打开发票表，导出 CSV，将其粘贴到 Excel 中，手动对几百行进行分类，运行公式，将九个数字复制到第三方 MTD 桥中，单击“提交”，希望如此。

它有效，但速度慢且有损耗。收据不见了。季度中期的利率变化打破了公式。 VAT 分类中的一个拼写错误可能会移动 Box 5 数百英镑。审计跟踪是“相信我，我有一个电子表格”。

今年，我将整个项目重建为一个小型 Claude Code 项目，该项目读取我的发票 + 费用数据库，对每一行进行分类，计算九个框，试运行 PDF，然后才通过人工审批门提交给 HMRC MTD。该博客是简短版本。这篇长文章包含提示、Python、HMRC OAuth 流程和陷阱。

观看演练

针对真实（匿名）发票 + 费用数据库端到端运行的 VAT 返回管道的简短演练。

五步管道

1. 连接。 Claude Code 获得 只读 与我的发票和费用表的数据库连接。它永远没有对源数据的写访问权限。来自 Stripe、Wise、Revolut 和一些银行提要的 CSV 被放入 ./imports/.
2. 正常化。 Claude 生成并运行一个小型 Python 脚本，将每个源模式映射到一个规范视图： id, date, supplier_or_customer, gross, net, vat_amount, vat_rate, vat_treatment, country_code, currency, source, run_key。外币使用 HMRC 月汇率转换为 GBP。整个时期以幂等为关键 run_key 所以重新运行是安全的。
3. 分类+协调。 Claude 将每条线分为 VAT 待遇 - 标准 20%、降低 5%、零、豁免、范围外、反向收费、欧盟商品、欧盟服务、推迟进口 VAT - 使用小型 vat-rules.md 我保留在回购协议中。它还可以根据付款核对发票并标记异常情况（负净额、缺少供应商 VAT 编号、国家/地区代码不匹配、未注册 VAT 的供应商）。
4. 计算。 纯函数 Python 模块 - 数学中没有 LLM - 读取分类行并生成 Box 1 到 Box 9，以及 Markdown 中的试运行报告。统一费率方案、现金会计和年度会计分支是明确的代码路径，而不是提示指令。
5. 提交。 只有在我（或我的会计师）签署试运行后，管道才会调用 HMRC MTD API。 OAuth2 代币。防欺诈标头。 GET obligations 找到开放时间。 POST returns 和 finalised: true。然后 GET liabilities 确认我欠什么以及何时欠。

为什么选择 Claude Code 而不是 Xero / QuickBooks / FreeAgent

老实说，对于大多数小型企业来说，打包的会计师 SaaS 是正确的答案。他们拥有 HMRC 认证、支持团队，并且您的会计师已经了解他们。那么我为什么要这样做呢？

• 我已经每天使用 Claude Code 用于软件工作。使用它来组装 VAT 管道的边际成本也很小。
• 我的数据是本地的。 发票数据库永远不会离开我的机器。分类器在行上运行；数学是本地Python；只有最后九个数字进入 HMRC。没有 SaaS 租户，没有第三方。
• 我想要完全控制分类规则。 我的一些供应商组合很尴尬（欧盟服务、推迟进口 VAT、一些零税率的边缘情况）。将这些规则编码为 vat-rules.md + 对我来说，Python 模块比配置 SaaS 更快。
• 审计线索是我的。 每个克劳德提示和每个差异都会与签名的周期快照一起提交到仅附加日志中。如果 HMRC 提出要求，我可以在几秒钟内完成精确的计算。

如果您还没有使用 Claude Code 或者您不喜欢在午夜阅读 Python，请使用 Xero / QuickBooks / FreeAgent。这并不是建议您部署自己的 VAT 系统。这是一个关于当你这样做时一切皆有可能的故事。

LLM 在哪里和不在哪里

这是我想大声说出来的部分。 克劳德不在 VAT 算术中。 Claude 对线条进行分类，提出协调建议，并生成和编辑执行数学运算的确定性 Python 模块。 Box 1 到 Box 9 的实际计算是带有单元测试的纯函数。 HMRC 提交需要人工审批。试运行报告是签字的事实来源。如果我无法通过查看代码和分类行来解释为什么某个数字是这样的，我不会提交。

这是一条硬性规则，因为金融受到监管，而“人工智能做到了”并不是 MTD 下的辩护理由。这 长文章 更详细地介绍如何在您自己的实现中绘制这条线。

我的建造成本和运营成本

构建时间大约是一周的晚上——主要花在模式规范化、分类器规则和为引擎编写测试上。 HMRC MTD OAuth 舞蹈是最慢的部分；首先在沙箱中运行是值得的。

为了运行，每个季度我的费用大约是：我的 Claude Code 订阅（已经为其他工作付费）加上分类器的几美分代币使用量。 HMRC API 本身是免费的。 VAT 引擎和审核日志在我的 Mac 上本地运行。

重要免责声明

我是一名工程师，不是特许会计师。 本文不是税务建议。 在针对您的真实 HMRC 帐户运行此类操作之前，请让一位英国注册会计师对您的第一份报表进行端到端审核。使用 HMRC MTD 沙箱 直到你和你的会计师都满意为止。糟糕的 VAT 提交的成本远高于会计师一小时时间的成本。

阅读长版本

如果您想要了解完整情况 - 确切的 CREATE TABLE 模式、Claude Code 提示、带有单元测试的确定性 Python 引擎、HMRC MTD OAuth 流程、欺诈预防标头以及有关边缘情况的完整部分（Brexit / NI 协议、反向收费、部分豁免、统一费率方案、季度中期费率变化、多币种发票、贷方票据、存款） - 请阅读 长文章。这是我在开始之前就想阅读的版本。

观看 YouTube 演练，订阅后续教程（自动导入银行数据、收据 OCR、预定 cron + Slack 批准），并记住：不是税务建议，需要会计师签字。