بناء نظام إرجاع VAT باستخدام Claude Code من قاعدة بيانات الفواتير والنفقات الخاصة بك

رفيق قصير وقابل للقراءة. للاطلاع على التعمق الكامل الذي يصل إلى 5000 كلمة تقريبًا مع التعليمات البرمجية والمطالبات والمخطط وإرشادات HMRC MTD وحالات الحافة، اقرأ المقال الطويل.

كان 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 يحصل على للقراءة فقط اتصال قاعدة البيانات بفواتيري وجداول النفقات. لم يكن لديه حق الوصول للكتابة إلى البيانات المصدر. يتم إدراج ملفات CSV من Stripe وWise وRevolut واثنين من خلاصات البنوك ./imports/.
2. تطبيع. يقوم كلود بإنشاء وتشغيل نص بايثون صغير يقوم بتعيين كل مخطط مصدر في عرض أساسي واحد: id, date, supplier_or_customer, gross, net, vat_amount, vat_rate, vat_treatment, country_code, currency, source, run_key. يتم تحويل العملة الأجنبية إلى GBP باستخدام المعدل الشهري HMRC. الفترة بأكملها مرتبطة بشخص عاجز run_key لذا فإن إعادة التشغيل آمنة.
3. تصنيف + التوفيق. يصنف كلود كل سطر إلى معالجة VAT - قياسي 20%، مخفض 5%، صفر، معفى، خارج النطاق، رسوم عكسية، سلع الاتحاد الأوروبي، خدمات الاتحاد الأوروبي، الاستيراد المؤجل VAT - باستخدام علامة صغيرة vat-rules.md وأظل في الريبو. كما أنه يقوم أيضًا بتسوية الفواتير مع المدفوعات ووضع علامات على الحالات الشاذة (المبالغ الصافية السلبية، وأرقام الموردين VAT المفقودة، وعدم تطابق رمز البلد، والموردين غير المسجلين في VAT).
4. حساب. وحدة بايثون ذات الوظيفة النقية - لا يوجد 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 صغيرة.
• بياناتي محلية. الفواتير DB لا تترك جهازي أبدًا. يعمل المصنف على الصفوف؛ الرياضيات هي لغة بايثون المحلية؛ فقط الأرقام التسعة الأخيرة تذهب إلى HMRC. لا يوجد مستأجر SaaS ولا يوجد طرف ثالث.
• أردت السيطرة الكاملة على قواعد التصنيف. بعض مزيج الموردين الخاص بي غير مريح (خدمات الاتحاد الأوروبي، والاستيراد المؤجل VAT، وزوج من حالات الحافة ذات التصنيف الصفري). ترميز تلك القواعد في vat-rules.md + وحدة Python أسرع بالنسبة لي من تكوين SaaS.
• مسار التدقيق هو لي. يتم الالتزام بكل مطالبة Claude وكل فرق في سجل الإلحاق فقط جنبًا إلى جنب مع لقطة الفترة الموقعة. إذا طلب منك HMRC ذلك، فيمكنني إجراء الحساب الدقيق في ثوانٍ.

إذا كنت لا تستخدم Claude Code بالفعل أو لن تستمتع بقراءة لغة Python في منتصف الليل، فيرجى استخدام Xero / QuickBooks / FreeAgent. هذه ليست توصية لتشغيل نظام VAT الخاص بك. إنها قصة ما هو ممكن عندما تفعل ذلك.

أين يوجد LLM وأين لا يوجد

هذا هو الجزء الذي أريد أن أتحدث عنه بصوت عالٍ. كلود ليس في حساب VAT. يقوم كلود بتصنيف الخطوط واقتراح التسويات وإنشاء وتحرير وحدات بايثون الحتمية التي تقوم بالرياضيات. الحساب الفعلي لـ 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، والشحن العكسي، والإعفاء الجزئي، ونظام السعر الثابت، وتغييرات سعر منتصف الربع، والفواتير متعددة العملات، وإشعارات الائتمان، والودائع) - اقرأ مقالة طويلة. إنها النسخة التي كنت أرغب في قراءتها قبل أن أبدأ.

شاهد تجول يوتيوب، اشترك للحصول على دروس المتابعة (خلاصات بنك الاستيراد التلقائي، التعرف الضوئي على الحروف للإيصالات، cron المجدول + موافقة Slack)، وتذكر: ليست المشورة الضريبية، يلزم تسجيل خروج المحاسب.