Evergreen farms (pos)

Tax Engine Issue - Root Cause Analysis & Resolution Summary¶

1. Problem Statement & Root Cause
- Investigated issues where POS tax calculations were returning $0.00 or taxAmount: null.
- Identified 3 core technical root causes: * Redis/MongoDB Cache Corruption: Stale cache records stored combinedTaxRate: undefined or 0 in Redis RAM and taxengine MongoDB DB (taxcaches collection). * Flat Order Discount Division: Cart discounts were split equally (dto.discount / itemCount) instead of proportionally, reducing low-cost items' taxable amount to $0. * Products List Page Tax Badge Bug: Product list page was checking dollar taxAmount from past sales history instead of percentage combinedTaxRate. 100% coupon sales falsely marked taxable items as "No Tax".

2. Fixes & Architecture Enhancements Implemented
- Self-Healing Cache Guard (tax.service.ts): Added a cache validation guard in NestJS tax microservice. Corrupted undefined or null cache records are evicted and TaxJar API is queried for the official product_tax_code rate. Genuine 0% tax-exempt codes (gift cards, labor) are preserved.
- Restored Proportional Discount Allocation (tax.service.ts): Updated cart discount distribution to use proportional ratios (itemTotal / totalAmount * discount) per US tax compliance rules.
- Remote Microservice Fallback Circuit Breaker (tax-engine.service.js): Added fallback logic in evergreen_pos_be. If remote microservice (tax.evergreenfarmsusa.com) returns null/undefined or fails, POS auto-applies 7% store fallback rate to prevent register downtime or $0 tax loss.
- Fixed Products Page Badge Aggregation (product.service.js): Updated aggregation to check percentage combinedTaxRate instead of dollar taxAmount.
- Auto Product Taxability DB Update (tax.js & tax-engine.service.js): Successfully calculated 7% rates now automatically set nonTaxable: false on the product MongoDB document, rendering "Taxable" on UI.
- DB Clean-up: Cleared/updated 28 corrupted taxcache records in taxengine MongoDB database to combinedTaxRate: 0.07.¶

3. Verification
- Verified calculation logic across single and combined cart items.
- Verified proportional discount ratio distribution.
- Confirmed non-taxable products/exempt codes remain 0% tax while general merchandise items get 7% tax.¶