feat: add VAT tax rate, cost, and Letzshop feed settings
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 <noreply@anthropic.com>
This commit is contained in:
@@ -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')
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user