yourpart3/backend/README_TAX.md

Falukant Tax Migration & Configuration

This project now supports a per-region sales tax (tax_percent) for Falukant.

Migration

• A SQL migration was added: backend/migrations/20260101000000-add-tax-percent-to-region.cjs.
• It adds tax_percent numeric NOT NULL DEFAULT 7 to falukant_data.region.

Runtime configuration

• If you want taxes to be forwarded to a treasury account, set environment variable TREASURY_FALUKANT_USER_ID to a valid falukant_user.id.
• If TREASURY_FALUKANT_USER_ID is not set, taxes will be calculated and currently not forwarded to any account.

Implementation notes

• Backend service sellProduct and sellAllProducts now compute tax per-region and credit net to seller and tax to treasury (if configured).
• Tax arithmetic uses rounding to 2 decimals. The current implementation performs two separate DB calls (seller, treasury). For strict ledger atomicity consider implementing DB-side booking.

Cumulative tax behavior

• The system now sums tax_percent from the sale region and all ancestor regions (recursive up the region tree). This allows defining different tax rates on up to 6 region levels and summing them for final tax percent.
• To avoid reducing seller net by taxes, sale prices are inflated by factor = 1 / (1 - cumulativeTax/100). This way the seller receives the original net and the tax is collected separately.

Testing

• After running the migration, test with a small sale and verify falukant_log.moneyflow entries for seller and treasury.