From 8a2a955c92a3a3e181e5c775f35f1988d4c830ce Mon Sep 17 00:00:00 2001 From: Samir Boulahtit Date: Sat, 20 Dec 2025 21:15:47 +0100 Subject: [PATCH] feat: add VAT tax rate, cost, and Letzshop feed settings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Product Model: - Add tax_rate_percent (NOT NULL, default 17) for Luxembourg VAT - Add cost_cents for profit calculation - Add profit calculation properties: net_price, vat_amount, profit, margin - Rename supplier_cost_cents to cost_cents MarketplaceProduct Model: - Add tax_rate_percent (NOT NULL, default 17) Vendor Model (Letzshop feed settings): - letzshop_default_tax_rate: Default VAT for new products (0, 3, 8, 14, 17) - letzshop_boost_sort: Product sort priority (0.0-10.0) - letzshop_delivery_method: nationwide, package_delivery, self_collect - letzshop_preorder_days: Pre-order shipping delay VAT Strategy: - Store prices as gross (VAT-inclusive) for B2C - Calculate net from gross when needed for profit - Luxembourg VAT rates: 0%, 3%, 8%, 14%, 17% 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- ...add_tax_rate_cost_and_letzshop_settings.py | 64 +++++++++++++ docs/architecture/money-handling.md | 96 ++++++++++++++++++- models/database/marketplace_product.py | 5 + models/database/product.py | 96 +++++++++++++++++-- models/database/vendor.py | 20 ++++ 5 files changed, 270 insertions(+), 11 deletions(-) create mode 100644 alembic/versions/c9e22eadf533_add_tax_rate_cost_and_letzshop_settings.py diff --git a/alembic/versions/c9e22eadf533_add_tax_rate_cost_and_letzshop_settings.py b/alembic/versions/c9e22eadf533_add_tax_rate_cost_and_letzshop_settings.py new file mode 100644 index 00000000..6f1dcc02 --- /dev/null +++ b/alembic/versions/c9e22eadf533_add_tax_rate_cost_and_letzshop_settings.py @@ -0,0 +1,64 @@ +"""add_tax_rate_cost_and_letzshop_settings + +Revision ID: c9e22eadf533 +Revises: e1f2a3b4c5d6 +Create Date: 2025-12-20 21:13:30.709696 + +Adds: +- tax_rate_percent to products and marketplace_products (NOT NULL, default 17) +- cost_cents to products (for profit calculation) +- Letzshop feed settings to vendors (tax_rate, boost_sort, delivery_method, preorder_days) +""" +from typing import Sequence, Union + +from alembic import op +import sqlalchemy as sa + + +# revision identifiers, used by Alembic. +revision: str = 'c9e22eadf533' +down_revision: Union[str, None] = 'e1f2a3b4c5d6' +branch_labels: Union[str, Sequence[str], None] = None +depends_on: Union[str, Sequence[str], None] = None + + +def upgrade() -> None: + # === MARKETPLACE PRODUCTS: Add tax_rate_percent === + with op.batch_alter_table('marketplace_products', schema=None) as batch_op: + batch_op.add_column(sa.Column('tax_rate_percent', sa.Integer(), nullable=False, server_default='17')) + + # === PRODUCTS: Add tax_rate_percent and cost_cents, rename supplier_cost_cents === + with op.batch_alter_table('products', schema=None) as batch_op: + batch_op.add_column(sa.Column('tax_rate_percent', sa.Integer(), nullable=False, server_default='17')) + batch_op.add_column(sa.Column('cost_cents', sa.Integer(), nullable=True)) + # Drop old supplier_cost_cents column (data migrated to cost_cents if needed) + try: + batch_op.drop_column('supplier_cost_cents') + except Exception: + pass # Column may not exist + + # === VENDORS: Add Letzshop feed settings === + with op.batch_alter_table('vendors', schema=None) as batch_op: + batch_op.add_column(sa.Column('letzshop_default_tax_rate', sa.Integer(), nullable=False, server_default='17')) + batch_op.add_column(sa.Column('letzshop_boost_sort', sa.String(length=10), nullable=True, server_default='5.0')) + batch_op.add_column(sa.Column('letzshop_delivery_method', sa.String(length=100), nullable=True, server_default='package_delivery')) + batch_op.add_column(sa.Column('letzshop_preorder_days', sa.Integer(), nullable=True, server_default='1')) + + +def downgrade() -> None: + # === VENDORS: Remove Letzshop feed settings === + with op.batch_alter_table('vendors', schema=None) as batch_op: + batch_op.drop_column('letzshop_preorder_days') + batch_op.drop_column('letzshop_delivery_method') + batch_op.drop_column('letzshop_boost_sort') + batch_op.drop_column('letzshop_default_tax_rate') + + # === PRODUCTS: Remove tax_rate_percent and cost_cents === + with op.batch_alter_table('products', schema=None) as batch_op: + batch_op.drop_column('cost_cents') + batch_op.drop_column('tax_rate_percent') + batch_op.add_column(sa.Column('supplier_cost_cents', sa.Integer(), nullable=True)) + + # === MARKETPLACE PRODUCTS: Remove tax_rate_percent === + with op.batch_alter_table('marketplace_products', schema=None) as batch_op: + batch_op.drop_column('tax_rate_percent') diff --git a/docs/architecture/money-handling.md b/docs/architecture/money-handling.md index 7d18b83b..69e97ebc 100644 --- a/docs/architecture/money-handling.md +++ b/docs/architecture/money-handling.md @@ -308,6 +308,97 @@ def test_price_precision(): assert back_to_euros == price ``` +## VAT Handling + +### Storage Strategy: Gross Prices (VAT-Inclusive) + +The platform stores all prices as **gross** (VAT-inclusive) for B2C simplicity: + +- Customers see the final price immediately (EU legal requirement) +- No calculation needed for display +- Profit is calculated by extracting net from gross + +### Luxembourg VAT Rates + +| Rate | Percentage | Applies To | +|------|------------|------------| +| Standard | **17%** | Most products (electronics, furniture, cosmetics) | +| Intermediate | **14%** | Wines, printed materials, heating oils | +| Reduced | **8%** | Utilities, hairdressing, small repairs | +| Super-reduced | **3%** | Food, books, children's clothing, medicine | +| Zero | **0%** | Exports, certain financial services | + +### Database Fields + +```python +class Product(Base): + # Tax rate (0, 3, 8, 14, or 17 for Luxembourg) + tax_rate_percent = Column(Integer, default=17, nullable=False) + + # Cost for profit calculation (what vendor pays to acquire) + cost_cents = Column(Integer, nullable=True) +``` + +### Profit Calculation + +```python +class Product(Base): + @property + def net_price_cents(self) -> int: + """Calculate net price (excluding VAT) from gross price. + + Formula: Net = Gross * 100 / (100 + rate) + Example: €119 gross at 17% VAT = €119 * 100 / 117 = €101.71 net + """ + return int(self.effective_price_cents * 100 / (100 + self.tax_rate_percent)) + + @property + def vat_amount_cents(self) -> int: + """VAT = Gross - Net""" + return self.effective_price_cents - self.net_price_cents + + @property + def profit_cents(self) -> int: + """Profit = Net Revenue - Cost""" + return self.net_price_cents - self.cost_cents + + @property + def profit_margin_percent(self) -> float: + """Margin% = (Profit / Net) * 100""" + return round((self.profit_cents / self.net_price_cents) * 100, 2) +``` + +### Example Calculation + +| Field | Value | +|-------|-------| +| Gross Price | €119.00 (11900 cents) | +| Tax Rate | 17% | +| Net Price | €101.71 (10171 cents) | +| VAT Amount | €17.29 (1729 cents) | +| Cost | €60.00 (6000 cents) | +| **Profit** | €41.71 (4171 cents) | +| **Margin** | 41.0% | + +### Vendor Letzshop Settings + +Vendors have default settings for the Letzshop feed: + +```python +class Vendor(Base): + # Default VAT rate for new products + letzshop_default_tax_rate = Column(Integer, default=17) + + # Product sort priority (0.0-10.0, higher = displayed first) + letzshop_boost_sort = Column(String(10), default="5.0") + + # Delivery method: 'nationwide', 'package_delivery', 'self_collect' + letzshop_delivery_method = Column(String(100), default="package_delivery") + + # Pre-order days before shipping (default 1 day) + letzshop_preorder_days = Column(Integer, default=1) +``` + ## Summary | Layer | Format | Example | @@ -318,4 +409,7 @@ def test_price_precision(): | API request/response | Float euros | `105.91` | | Frontend display | Formatted string | `"105,91 €"` | -**Golden Rule:** All arithmetic happens with integers. Conversion to/from euros only at system boundaries (API, display). +**Golden Rules:** +1. All arithmetic happens with integers. Conversion to/from euros only at system boundaries. +2. Prices are stored as gross (VAT-inclusive). Net is calculated when needed. +3. Tax rate is stored per product, with vendor defaults for new products. diff --git a/models/database/marketplace_product.py b/models/database/marketplace_product.py index 2d69bd2a..90ab4973 100644 --- a/models/database/marketplace_product.py +++ b/models/database/marketplace_product.py @@ -100,6 +100,11 @@ class MarketplaceProduct(Base, TimestampMixin): sale_price_cents = Column(Integer) # Parsed numeric sale price in cents currency = Column(String(3), default="EUR") + # === TAX / VAT === + # Luxembourg VAT rates: 0 (exempt), 3 (super-reduced), 8 (reduced), 14 (intermediate), 17 (standard) + # Prices are stored as gross (VAT-inclusive). Default to standard rate. + tax_rate_percent = Column(Integer, default=17, nullable=False) + # === MEDIA === image_link = Column(String) additional_image_link = Column(String) # Legacy single string diff --git a/models/database/product.py b/models/database/product.py index 58079fa3..499d05c7 100644 --- a/models/database/product.py +++ b/models/database/product.py @@ -75,10 +75,15 @@ class Product(Base, TimestampMixin): download_url = Column(String) license_type = Column(String(50)) - # === SUPPLIER TRACKING === + # === TAX / VAT === + # Luxembourg VAT rates: 0 (exempt), 3 (super-reduced), 8 (reduced), 14 (intermediate), 17 (standard) + # Prices are stored as gross (VAT-inclusive). Tax rate is used for profit calculation. + tax_rate_percent = Column(Integer, default=17, nullable=False) + + # === SUPPLIER TRACKING & COST === supplier = Column(String(50)) # 'codeswholesale', 'internal', etc. supplier_product_id = Column(String) # Supplier's product reference - supplier_cost_cents = Column(Integer) # What we pay the supplier (in cents) + cost_cents = Column(Integer) # What vendor pays to acquire (in cents) - for profit calculation margin_percent_x100 = Column(Integer) # Markup percentage * 100 (e.g., 25.5% = 2550) # === VENDOR-SPECIFIC (No inheritance) === @@ -165,16 +170,16 @@ class Product(Base, TimestampMixin): self.sale_price_cents = euros_to_cents(value) if value is not None else None @property - def supplier_cost(self) -> float | None: - """Get supplier cost in euros.""" - if self.supplier_cost_cents is not None: - return cents_to_euros(self.supplier_cost_cents) + def cost(self) -> float | None: + """Get cost in euros (what vendor pays to acquire).""" + if self.cost_cents is not None: + return cents_to_euros(self.cost_cents) return None - @supplier_cost.setter - def supplier_cost(self, value: float | None): - """Set supplier cost from euros.""" - self.supplier_cost_cents = euros_to_cents(value) if value is not None else None + @cost.setter + def cost(self, value: float | None): + """Set cost from euros.""" + self.cost_cents = euros_to_cents(value) if value is not None else None @property def margin_percent(self) -> float | None: @@ -188,6 +193,77 @@ class Product(Base, TimestampMixin): """Set margin percent.""" self.margin_percent_x100 = int(value * 100) if value is not None else None + # === TAX / PROFIT CALCULATION PROPERTIES === + + @property + def net_price_cents(self) -> int | None: + """Calculate net price (excluding VAT) from gross price. + + Formula: Net = Gross / (1 + rate/100) + Example: €119 gross at 17% VAT = €119 / 1.17 = €101.71 net + """ + gross = self.effective_price_cents + if gross is None: + return None + # Use integer math to avoid floating point issues + # Net = Gross * 100 / (100 + rate) + return int(gross * 100 / (100 + self.tax_rate_percent)) + + @property + def net_price(self) -> float | None: + """Get net price in euros.""" + cents = self.net_price_cents + return cents_to_euros(cents) if cents is not None else None + + @property + def vat_amount_cents(self) -> int | None: + """Calculate VAT amount in cents. + + Formula: VAT = Gross - Net + """ + gross = self.effective_price_cents + net = self.net_price_cents + if gross is None or net is None: + return None + return gross - net + + @property + def vat_amount(self) -> float | None: + """Get VAT amount in euros.""" + cents = self.vat_amount_cents + return cents_to_euros(cents) if cents is not None else None + + @property + def profit_cents(self) -> int | None: + """Calculate profit in cents. + + Formula: Profit = Net Revenue - Cost + Returns None if cost is not set. + """ + net = self.net_price_cents + if net is None or self.cost_cents is None: + return None + return net - self.cost_cents + + @property + def profit(self) -> float | None: + """Get profit in euros.""" + cents = self.profit_cents + return cents_to_euros(cents) if cents is not None else None + + @property + def profit_margin_percent(self) -> float | None: + """Calculate profit margin as percentage of net revenue. + + Formula: Margin% = (Profit / Net) * 100 + Example: €41.71 profit on €101.71 net = 41.0% margin + """ + net = self.net_price_cents + profit = self.profit_cents + if net is None or profit is None or net == 0: + return None + return round((profit / net) * 100, 2) + # === EFFECTIVE PROPERTIES (Override Pattern) === @property diff --git a/models/database/vendor.py b/models/database/vendor.py index 3f6f83db..9a943ec7 100644 --- a/models/database/vendor.py +++ b/models/database/vendor.py @@ -57,6 +57,26 @@ class Vendor(Base, TimestampMixin): letzshop_csv_url_en = Column(String) # URL for English CSV in Letzshop letzshop_csv_url_de = Column(String) # URL for German CSV in Letzshop + # ======================================================================== + # Letzshop Feed Settings (atalanda namespace) + # ======================================================================== + # These are default values applied to all products in the Letzshop feed + # See https://letzshop.lu/en/dev#google_csv for documentation + + # Default VAT rate for new products: 0 (exempt), 3 (super-reduced), 8 (reduced), 14 (intermediate), 17 (standard) + letzshop_default_tax_rate = Column(Integer, default=17, nullable=False) + + # Product sort priority on Letzshop (0.0-10.0, higher = displayed first) + # Note: Having all products rated above 7 is not permitted by Letzshop + letzshop_boost_sort = Column(String(10), default="5.0") # Stored as string for precision + + # Delivery method: 'nationwide', 'package_delivery', 'self_collect' (comma-separated for multiple) + # 'nationwide' automatically includes package_delivery and self_collect + letzshop_delivery_method = Column(String(100), default="package_delivery") + + # Pre-order days: number of days before item ships (default 1 day) + letzshop_preorder_days = Column(Integer, default=1) + # Status (vendor-specific, can differ from company status) is_active = Column( Boolean, default=True