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.¶
