feat(tax): add Argentina tax pack (official-argentina@1.0.0)

carvalab · carvalab · commit e56310c3445b · 2026-07-31T15:29:19.000-03:00
Scope (approved before this draft): - Merchant: IVA-registered restaurants (Responsable Inscripto), domestic sales of standard supplies. - Tax: one IVA rule at the general rate of 21%, applied across every category (product, addon, packaging, delivery, service_charge, unclassified). - Default pricing is tax-inclusive to match Argentina's consumer- price-display rule (Res. 4/2025); individual products can still be set exclusive per-item for B2B use. Source: Ley de Impuesto al Valor Agregado, texto ordenado en 1997 (Ley 23.349 t.o. Decreto 280/1997, Anexo I), Articulo 28 — 'La alicuota del impuesto sera del veintiuno por ciento (21%)'. Continuously in force since BO 15/04/1997. Cross-references: ARCA biblioteca cuadro legislativo Articulo 28; InfoLeg norma 42701. Intentionally unsupported (do not add to this pack without a scope bump): IIBB (provincial, registration-dependent); reduced 10.5%; incremented 27% (utilities); 2.5% and 0%; Monotributo; withholding and perception regimes; ARCA CAE fiscal-invoice authorization (belongs to the capability-plugin seam #142). Tests added/extended: - tests/tax-engine.test.ts: ARS 100 exclusive -> 21 -> 121; ARS 121 inclusive -> net 100 / IVA 21; all charge kinds apply the rule; unclassified never silently zero. - tests/tax-pack-management.test.ts: installs AR alongside IN/TH and confirms the 24-point activation checklist accepts it (only check #6, signed artifact, fails pre-signing, same as the unsigned IN/TH seeds). - tests/integration-tax.test.ts: AR exclusive order at ARS 1000 produces 210 IVA and 1210 total; 20% discount recomputes to 168 IVA and 968 total; inclusive product keeps IVA inside the displayed price and persists the behavior as inclusive in the snapshot; the bill copies the order tax. Every breakdown is asserted to contain no IIBB or Ingresos Brutos component. Docs: docs/tax-packs.md gains a 'Country pack scopes' section pinning the approved merchant scope, the IVA source, every excluded area, and the upgrade path for provincial IIBB (only after FloCafe models province + activity code + customer registration status). Companion e2e-server fix (unblocks CI for this PR): Commit 3a75876 ('publish country packs separately') moved India and Thailand from BUNDLED_COUNTRY_PACKS to catalog-only delivery, and the e2e-server fixture seeds country='TH' without simulating the post- first-run owner action of installing Thailand from Settings → Tax Configuration. The active pack for country=TH then falls back to the zero-rules generic pack, and the checkout throws 'no tax rules apply to category standard for business type restaurant' → 400. The Playwright spec at prepaid-payment-reconciliation.spec.ts:13/55 times out waiting for 'Tax ฿4.20'. This is the same regression silently failing the most recent two main CI runs before this PR. Fix by inlining the same install-tax-pack SQL helper that the unit and integration tests already use. Only Thailand is installed — it's the only country-specific pack exercised by e2e specs. Verified locally: npm run lint, npm run build, npm run test:tax-engine (12/12), npm test (0 failed across every suite including Integration Tax 114/114 and Tax Pack Management 103/103), git diff --check clean. Publishing (tag, push to upstream, CI sign) is not part of this PR. That step stays gated on maintainer review per the task spec; no signing secret was touched.
diff --git a/docs/tax-packs.md b/docs/tax-packs.md
@@ -29,6 +29,25 @@ It must not embed scripts, call network endpoints, or introduce a second tax-cal
 5. Add test vectors: extend `tests/tax-pack-management.test.ts` (activation validation) and, ideally, `tests/tax-engine.test.ts` / `tests/integration-tax.test.ts` with a scenario proving your rules produce the expected components, totals, and rounding for at least one representative order.
 6. Run `npm run test:tax-engine` and the full `npm test` before opening the PR.
 
+## Country pack scopes
+
+This section records the merchant scope, legal source, and intentional exclusions for each official country pack. A pack's JSON only encodes what its scope covers — anything listed under "intentionally unsupported" is *not* a bug, *not* a placeholder for a future update, and *not* something to add to the same pack without a scope bump and a new version.
+
+### Argentina (`official-argentina`)
+
+- **Approved merchant scope:** IVA-registered restaurants operating as *Responsable Inscripto* under the general regime, on domestic sales of standard supplies only. Default pricing is tax-inclusive because Argentina consumer-price-display law (Secretariat of Industry and Commerce Resolution 4/2025) requires the displayed price to be the total and final amount paid by the consumer; individual products can still be marked exclusive per-item for B2B use.
+- **Tax covered:** one IVA rule at the general rate of **21%** applied across every category (`standard`, `packaging`, `delivery`, `service_charge`, `addon`, `unclassified`). Inclusive-of-IVA consumer display is the default; exclusive pricing can be selected per product, per add-on, or per configurable charge.
+- **Legal source:** Ley de Impuesto al Valor Agregado, texto ordenado en 1997 (Ley N° 23.349 t.o. **Decreto N° 280/1997**, Anexo I), **Artículo 28**: *“La alícuota del impuesto será del veintiuno por ciento (21 %).”* Continuously in force since publication in Boletín Oficial 15/04/1997. Cross-references: ARCA / AFIP *Biblioteca* cuadro legislativo de alícuotas de IVA; InfoLeg norma 42701; SAIJ.
+- **Intentional unsupported (do not add to this pack without a scope bump):**
+  - **IIBB (Ingresos Brutos).** Provincial — administered by each *Dirección General de Rentas* — with rates that vary by province, registered activity, and registration status (typical bands: commercial services up to ~4.5%, industry up to ~3%, others up to ~6%). FloCafe does not model province-level merchant activity or customer registration status, so IIBB cannot be calculated correctly from data already on a transaction. No IIBB component is emitted under any breakdown or snapshot. Adding IIBB to this pack without those inputs would silently under- or over-report.
+  - **Reduced-rate IVA (10.5%).** Applies to specific unprocessed goods (meat, fruit, vegetables, agricultural services, transport, housing construction, some medical services, Tierra del Fuego electronics). Requires per-product NCM/activity classification FloCafe does not model.
+  - **Incremented-rate IVA (27%).** Applies only to non-residential metered utilities (gas, electricity, water, telecoms to commercial premises). Out of scope for restaurant supplies.
+  - **2.5% super-reduced (printed newspapers/magazines)** and **0% (exports).** Not applicable to domestic restaurant sales.
+  - **Monotributo.** Simplified-regime merchants issue *Factura C* without itemized IVA and follow a separate monthly unified payment; the pack assumes *Responsable Inscripto*, which issues itemized *Factura A/B*.
+  - **Withholding and perception regimes** (RG 4240 IVA perception, etc.) and **fiscal-invoice authorization (CAE via ARCA)**: both require external authorizations and are part of the executable capability-plugin seam tracked in [#142](https://github.com/FreeOpenSourcePOS/FloCafe/issues/142), not a tax-pack concern.
+- **Upgrade path for provincial IIBB.** A future pack version `official-argentina@1.x.0` (or a successor pack) may add IIBB *only after* FloCafe models the inputs it needs: the merchant's registered province (ARCA jurisdiction), the IIBB activity code(s), and the customer's tax-status (Responsable Inscripto vs Monotributo vs Exento). Until those inputs exist end-to-end, a pack cannot compute IIBB correctly and must not claim to.
+- **Sources checked:** ARCA *Biblioteca* cuadro legislativo (alícuotas Art. 28); InfoLeg norma 42701 with notas Infoleg (Ley 27.702 extension to 2027, Decreto 567/2019 0% canasta); SAIJ texto actualizado; Secretaría de Industria y Comercio Resolución 4/2025 (price display); Avalara Argentina VAT compliance guide.
+
 ## Where packs live, how they get signed, and how they're published
 
 Pack source and release artifacts have separate homes. Reviewable source, signing code, and the release workflow stay in this repository; signed tax-pack artifacts (and future capability-plugin artifacts) are published to [`FreeOpenSourcePOS/FloCafe-Plugins`](https://github.com/FreeOpenSourcePOS/FloCafe-Plugins), keeping FloCafe's Releases tab for application installers.
diff --git a/main/tax-packs/argentina.json b/main/tax-packs/argentina.json
@@ -0,0 +1,50 @@
+{
+  "schemaVersion": 1,
+  "id": "official-argentina",
+  "publisher": "FreeOpenSourcePOS",
+  "version": "1.0.0",
+  "country": "AR",
+  "jurisdiction": "*",
+  "currency": "ARS",
+  "effectiveFrom": "2026-01-01",
+  "publishedAt": "2026-01-01",
+  "minFloVersion": "2.4.0",
+  "taxPoint": "finalized_at",
+  "inclusivePricingDefault": true,
+  "registrationNumberLabel": "CUIT",
+  "categories": [
+    { "id": "standard", "label": "Standard", "ruleIds": ["iva"] },
+    { "id": "packaging", "label": "Packaging", "ruleIds": ["iva"] },
+    { "id": "delivery", "label": "Delivery", "ruleIds": ["iva"] },
+    { "id": "service_charge", "label": "Service charge", "ruleIds": ["iva"] },
+    { "id": "addon", "label": "Add-on", "ruleIds": ["iva"] },
+    { "id": "unclassified", "label": "Unclassified", "ruleIds": ["iva"] }
+  ],
+  "defaultCategories": {
+    "product": "standard",
+    "packaging": "packaging",
+    "delivery": "delivery",
+    "service_charge": "service_charge",
+    "addon": "addon"
+  },
+  "unclassifiedCategoryId": "unclassified",
+  "rules": [
+    {
+      "id": "iva",
+      "label": "IVA",
+      "type": "percent",
+      "categoryIds": ["standard", "packaging", "delivery", "service_charge", "addon", "unclassified"],
+      "rate": "21"
+    }
+  ],
+  "taxRounding": {
+    "scope": "line",
+    "method": "half_up",
+    "decimalPlaces": 2,
+    "remainderAllocation": "largest_remainder"
+  },
+  "payableRounding": {
+    "increment": "0.01",
+    "method": "half_up"
+  }
+}
diff --git a/tests/e2e-server.cjs b/tests/e2e-server.cjs
@@ -16,6 +16,7 @@ Module._load = function (request, parent, isMain) {
 };
 
 const bcrypt = require('bcryptjs');
+const crypto = require('crypto');
 const { initDatabase, getDatabase, closeDatabase, now } = require('../dist/db');
 const { startServer, stopServer } = require('../dist/server');
 const { startKdsServer, stopKdsServer } = require('../dist/kds-server');
@@ -26,6 +27,79 @@ function seedUser(id, email, role) {
   ).run(id, `E2E ${role}`, email, bcrypt.hashSync('E2ePass123!', 10), role, now(), now());
 }
 
+// After commit 3a75876 ("publish country packs separately"), only the generic
+// pack auto-installs on first-run; country packs come from the signed catalog
+// after an owner opt-in. The e2e fixture seeds country=TH but never goes
+// through that owner action, so it has no active TH pack and the checkout
+// throws "no tax rules apply". Mirror the production owner-install action by
+// registering the TH pack directly. This is the same SQL helper that the
+// unit/integration tests use, just inlined here because e2e-server runs from
+// compiled dist/ and cannot import the .ts test helpers.
+function installTaxPackFixture(pack) {
+  const db = getDatabase();
+  const installedAt = now();
+  const versionId = `${pack.id}@${pack.version}`;
+  const packJson = JSON.stringify(pack);
+  const digest = crypto.createHash('sha256').update(packJson).digest('hex');
+
+  db.transaction(() => {
+    db.prepare(`
+      INSERT INTO country_packs (
+        id, publisher, country, jurisdiction, active_version_id, status, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        publisher = excluded.publisher,
+        country = excluded.country,
+        jurisdiction = excluded.jurisdiction,
+        active_version_id = excluded.active_version_id,
+        status = 'active',
+        updated_at = excluded.updated_at
+    `).run(pack.id, pack.publisher, pack.country, pack.jurisdiction, versionId, installedAt, installedAt);
+
+    db.prepare(`
+      INSERT OR REPLACE INTO country_pack_versions (
+        id, pack_id, version, schema_version, manifest_json, pack_json, digest, signature,
+        effective_from, effective_to, min_flo_version, published_at, status, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, 'active', ?)
+    `).run(
+      versionId, pack.id, pack.version, pack.schemaVersion,
+      JSON.stringify({
+        id: pack.id, publisher: pack.publisher, country: pack.country,
+        jurisdiction: pack.jurisdiction, version: pack.version, publishedAt: pack.publishedAt,
+      }),
+      packJson, digest,
+      pack.effectiveFrom, pack.effectiveTo || null, pack.minFloVersion, pack.publishedAt,
+      installedAt,
+    );
+
+    const insertCategory = db.prepare(`
+      INSERT OR REPLACE INTO tax_categories (
+        id, pack_version_id, category_id, label, default_behavior, definition_json, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+    for (const category of pack.categories) {
+      insertCategory.run(
+        `${versionId}:category:${category.id}`, versionId, category.id, category.label,
+        category.defaultBehavior || null, JSON.stringify(category), installedAt,
+      );
+    }
+
+    const insertRule = db.prepare(`
+      INSERT OR REPLACE INTO tax_rules (
+        id, pack_version_id, rule_id, label, calculation_type, rate, amount,
+        applies_per, base_rule_ids, definition_json, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    for (const rule of pack.rules) {
+      insertRule.run(
+        `${versionId}:rule:${rule.id}`, versionId, rule.id, rule.label, rule.type,
+        rule.rate || null, rule.amount || null, rule.appliesPer || null,
+        JSON.stringify(rule.baseRuleIds || []), JSON.stringify(rule), installedAt,
+      );
+    }
+  })();
+}
+
 function seedPosFixture() {
   const db = getDatabase();
   const createdAt = now();
@@ -82,6 +156,7 @@ function stop(exitCode = 0) {
   initDatabase();
   seedUser('e2e-manager', 'manager@flo.local', 'manager');
   seedPosFixture();
+  installTaxPackFixture(require('../main/tax-packs/th.json'));
   await startServer();
   await startKdsServer();
   console.log('[E2E] Main and KDS servers ready');
diff --git a/tests/integration-tax.test.ts b/tests/integration-tax.test.ts
@@ -33,6 +33,7 @@ const { billRoutes } = require('../main/routes/bills');
 const { registerRoutes } = require('../main/routes/index');
 const indiaTaxPack = require('../main/tax-packs/in.json');
 const thailandTaxPack = require('../main/tax-packs/th.json');
+const argentinaTaxPack = require('../main/tax-packs/argentina.json');
 
 async function main() {
   console.log('Integration Test: Tax Correctness');
@@ -46,6 +47,7 @@ async function main() {
   db.prepare("INSERT OR REPLACE INTO settings (key, value, updated_at) VALUES ('state_code', '27', ?)").run(now());
   installAndActivateTestTaxPack(db, indiaTaxPack);
   installAndActivateTestTaxPack(db, thailandTaxPack);
+  installAndActivateTestTaxPack(db, argentinaTaxPack);
 
   // Seed data
   const { authHeader } = seedOwnerUser(db);
@@ -509,6 +511,88 @@ async function main() {
       .run(activeThailandVersion.pack_json, activeThailandVersion.id);
     db.prepare("UPDATE settings SET value = 'IN' WHERE key = 'country'").run();
 
+    // ── Step 11: Argentina standard 21% IVA — exclusive + inclusive + discount — no IIBB ──
+    console.log('\n11. Argentina standard 21% IVA produces no IIBB component and discounts scale correctly');
+    db.prepare("INSERT OR REPLACE INTO settings (key, value, updated_at) VALUES ('country', 'AR', ?)").run(now());
+    db.prepare("INSERT OR REPLACE INTO settings (key, value, updated_at) VALUES ('business_type', 'restaurant', ?)").run(now());
+    db.prepare("INSERT OR REPLACE INTO settings (key, value, updated_at) VALUES ('state_code', '02', ?)").run(now());
+
+    seedProduct(db, 'prod-tax-ar-1', 'cat-tax', 'Argentina Cafe', 1000, {
+      tax_category_id: 'standard',
+      tax_behavior: 'exclusive',
+    });
+    seedProduct(db, 'prod-tax-ar-2', 'cat-tax', 'Argentina Cafe Inclusive', 1210, {
+      tax_category_id: 'standard',
+      tax_behavior: 'inclusive',
+    });
+
+    const arExclusiveRes = await api(baseUrl, '/api/orders', {
+      method: 'POST',
+      body: {
+        type: 'takeaway',
+        items: [{ product_id: 'prod-tax-ar-1', quantity: 1 }],
+      },
+      headers: authHeader,
+    });
+    assertEqual(arExclusiveRes.status, 201, 'Argentina exclusive order created');
+    assertEqual(arExclusiveRes.data.order.subtotal, 1000, 'AR exclusive subtotal = ARS 1000');
+    assertEqual(arExclusiveRes.data.order.tax_amount, 210, 'AR exclusive tax = ARS 210 (21% of ARS 1000)');
+    assertEqual(arExclusiveRes.data.order.total, 1210, 'AR exclusive total = ARS 1210 (1000 + 210)');
+    const arRawBreakdown = arExclusiveRes.data.order.tax_breakdown;
+    const arParsed = typeof arRawBreakdown === 'string' ? JSON.parse(arRawBreakdown) : arRawBreakdown;
+    const arEntries = Array.isArray(arParsed[0]) ? arParsed.flat() : arParsed;
+    const arIva = arEntries.find((b: any) => b.title === 'IVA');
+    assert(!!arIva, 'Argentina breakdown contains an IVA entry');
+    assert(
+      arEntries.every((b: any) => !/IIBB|ingresos/i.test(b.title)),
+      'Argentina breakdown must NOT contain an IIBB/Ingresos Brutos component (provincial, out of scope)',
+    );
+    assertEqual(arIva.rate, 21, 'Argentina IVA component rate is 21');
+
+    // Discount recompute: 20% off ARS 1000 = ARS 800 base; 21% = ARS 168 tax; total ARS 968.
+    const arDiscountRes = await api(baseUrl, `/api/orders/${arExclusiveRes.data.order.id}/discount`, {
+      method: 'PATCH',
+      body: { discount_type: 'percentage', discount_value: 20 },
+      headers: authHeader,
+    });
+    assertEqual(arDiscountRes.status, 200, 'AR discount applied');
+    assertEqual(arDiscountRes.data.order.discount_amount, 200, 'AR discount = ARS 200 (20% of 1000)');
+    assertEqual(arDiscountRes.data.order.tax_amount, 168, 'AR discounted tax = ARS 168 (21% of 800)');
+    assertEqual(arDiscountRes.data.order.total, 968, 'AR discounted total = ARS 968');
+
+    const arInclusiveRes = await api(baseUrl, '/api/orders', {
+      method: 'POST',
+      body: {
+        type: 'takeaway',
+        items: [{ product_id: 'prod-tax-ar-2', quantity: 1 }],
+      },
+      headers: authHeader,
+    });
+    assertEqual(arInclusiveRes.status, 201, 'AR inclusive order created');
+    assertEqual(arInclusiveRes.data.order.tax_amount, 210, 'AR inclusive IVA = ARS 210 (tax inside the displayed price, net of 1000)');
+    assertEqual(arInclusiveRes.data.order.total, 1210, 'AR inclusive total = ARS 1210 (IVA not added again)');
+    assert(!!arInclusiveRes.data.order.items[0].tax_snapshot, 'AR inclusive item carries a tax_snapshot');
+    assertEqual(arInclusiveRes.data.order.items[0].tax_type, 'inclusive', 'AR inclusive behavior persists as inclusive');
+
+    const arBillRes = await api(baseUrl, '/api/bills/generate', {
+      method: 'POST',
+      body: { order_id: arExclusiveRes.data.order.id },
+      headers: authHeader,
+    });
+    assertEqual(arBillRes.status, 201, 'AR bill generated from exclusive order');
+    assertEqual(arBillRes.data.bill.tax_amount, 168, 'AR bill copies discounted IVA = ARS 168');
+    assertEqual(arBillRes.data.bill.total, 968, 'AR bill total matches discounted order');
+    const arBillParsed = typeof arBillRes.data.bill.tax_breakdown === 'string'
+      ? JSON.parse(arBillRes.data.bill.tax_breakdown)
+      : arBillRes.data.bill.tax_breakdown;
+    const arBillEntries = Array.isArray(arBillParsed[0]) ? arBillParsed.flat() : arBillParsed;
+    assert(
+      arBillEntries.every((b: any) => !/IIBB|ingresos/i.test(b.title)),
+      'AR bill breakdown contains no IIBB component',
+    );
+
+    db.prepare("UPDATE settings SET value = 'IN' WHERE key = 'country'").run();
+
   } finally {
     server.close();
     closeDatabase();
diff --git a/tests/tax-engine.test.ts b/tests/tax-engine.test.ts
diff --git a/tests/tax-pack-management.test.ts b/tests/tax-pack-management.test.ts
