HIVE ERP / Anna Coffee — TRCP four-decimal item VAT validation hotfix
Date: 2026-10-31
Target: 3rd ERP CodeIgniter 3, WITH the immediately preceding
  AnnaCoffee_Fiscal_VAT_Included_Checkout_CORRECTED_2026-10-31.zip
  AND the Fiscal Print First / Pay Then Clear workflow already installed.

WHY THIS FIX IS NEEDED
TRCP rejected a VAT-inclusive price 1,000.00 item with:
  For line item ... Item.taxAmount expected 130.4348 received 130.43
The previous integration rounded TaxAmount to 2 decimals before sending.
The TRCP ItemList requires item-level VAT precision of 4 decimals for
this API validation. The local bill and customer's payment remain 2 decimals.

EXPECTED NEW INVOICE PAYLOAD (1 unit of each, VAT 15%)
  Avocado Toast    Before VAT 565.2174 + VAT  84.7826 =  650.0000
  Strawberry Mojito Before VAT 869.5652 + VAT 130.4348 = 1000.0000
  Fiscal invoice customer total: 1650.00 ETB
  Fiscal payload summary TaxValue: 215.2174
  No additional VAT is charged on top of the product's saved price.

WHAT IS INCLUDED
  application/libraries/Fiscal_vat_inclusive.php
  application/models/Fiscal_model.php
  NO SQL, no replacement of Cashier.php, Cashier_model.php, waiter order UI.

INSTALLATION
1. BACK UP the application and database.
2. Make sure the previously supplied VAT-inclusive checkout patch is installed.
3. Replace the 2 files above in their exact CodeIgniter application paths.
4. Refresh the browser (Ctrl+F5) and invalidate PHP OPcache if applicable.
5. Confirm in the TRCP test environment that fiscal document #11 is truly FAILED
   with the explicit line-item taxAmount validation error (not a timeout or
   unknown submission outcome). Reconcile its status with TRCP before retry.
6. In Fiscal Documents click Retry on document #11. The code corrects the
   ORIGINAL stored invoice payload from its saved item snapshot, preserving
   its original trnx_id, bill, prices and balance, then submits the same
   document instead of creating a new sale.
7. Confirm TRCP accepts it and the order remains AWAITING PAYMENT until money
   is collected. Do not collect twice. Confirm fiscal receipt can be printed.
8. Create a NEW test order of 650 + 1000 and confirm accepted invoice 1650.

LIMITATIONS / IMPORTANT
- A rejected document with an unknown outcome, an accepted document, or a
  cancelled document must not be silently reissued or overwritten.
- The code only auto-repairs failed INV payloads whose stored error explicitly
  says taxAmount expected. Other errors still require individual review.
- TRCP could report a different validation error after this fix; capture its
  exact error if so. This patch has not been run against the live TRCP API.
- Existing fiscal_document_items has 2-decimal numeric tax columns; the
  transmitted four-decimal values are preserved in fiscal_documents.request_payload
  and request logs. No production schema/data rewrite is necessary.
- Do not change a government-accepted fiscal invoice to address a discrepancy.

VERIFICATION DONE LOCALLY
- PHP lint passed for 2 PHP files (PHP 8.4.24).
- Calculation tests for 100/650/1000, 3 units, 10% discount, 0 VAT passed.
- Mock retry for existing failed invoice #11 passed (same trnx_id).
- No live MariaDB/TRCP submission performed.
