orion/app/modules/orders/docs/oms-features.md

OMS Feature Implementation Plan

Overview

Transform Orion into a "Lightweight OMS for Letzshop Sellers" by building the missing features that justify the tier pricing structure.

Goal: Ship Essential tier quickly, then build Professional differentiators, then Business features.

Design Decisions (Confirmed)

Decision	Choice
Phase 1 scope	Invoicing + Tier Limits together
PDF library	WeasyPrint (HTML/CSS to PDF)
Invoice style	Simple & Clean (minimal design)

---

Current State Summary

Already Production-Ready

• Multi-tenant architecture (Merchant → Store hierarchy)
• Letzshop order sync, confirmation, tracking
• Inventory management with locations and reservations
• Unified Order model (direct + marketplace)
• Customer model with pre-calculated stats (total_orders, total_spent)
• Team management + RBAC
• CSV export patterns (products)

Needs to be Built

Feature	Tier Impact	Priority
Basic LU Invoice (PDF)	Essential	P0
Tier limits enforcement	Essential	P0
Store VAT Settings	Professional	P1
EU VAT Invoice	Professional	P1
Incoming Stock / PO	Professional	P1
Customer CSV Export	Professional	P1
Multi-store view	Business	P2
Accounting export	Business	P2

---

Phase 1: Essential Tier (Target: 1 week)

Goal: Launch Essential (€49) with basic invoicing and tier enforcement.

Step 1.1: Store Invoice Settings (1 day)

Create model for store billing details:

models/database/store_invoice_settings.py

Fields:

• store_id (FK, unique - one-to-one)
• merchant_name (legal name for invoices)
• merchant_address, merchant_city, merchant_postal_code, merchant_country
• vat_number (e.g., "LU12345678")
• invoice_prefix (default "INV")
• invoice_next_number (auto-increment)
• payment_terms (optional text)
• bank_details (optional IBAN etc.)
• footer_text (optional)

Pattern to follow: models/database/letzshop.py (StoreLetzshopCredentials)

Files to create/modify:

• models/database/store_invoice_settings.py (new)
• models/database/__init__.py (add import)
• models/database/store.py (add relationship)
• models/schema/invoice.py (new - Pydantic schemas)
• alembic/versions/xxx_add_store_invoice_settings.py (migration)

---

Step 1.2: Basic Invoice Model (0.5 day)

Create invoice storage:

models/database/invoice.py

Fields:

• id, store_id (FK)
• order_id (FK, nullable - for manual invoices later)
• invoice_number (unique per store)
• invoice_date
• seller_details (JSONB snapshot)
• buyer_details (JSONB snapshot)
• line_items (JSONB snapshot)
• subtotal_cents, vat_rate, vat_amount_cents, total_cents
• currency (default EUR)
• status (draft, issued, paid, cancelled)
• pdf_generated_at, pdf_path (optional)

Files to create/modify:

• models/database/invoice.py (new)
• models/database/__init__.py (add import)
• alembic/versions/xxx_add_invoices_table.py (migration)

---

Step 1.3: Invoice Service - Basic LU Only (1 day)

Create service for invoice generation:

app/services/invoice_service.py

Methods:

• create_invoice_from_order(order_id, store_id) - Generate invoice from order
• get_invoice(invoice_id, store_id) - Retrieve invoice
• list_invoices(store_id, skip, limit) - List store invoices
• _generate_invoice_number(settings) - Auto-increment number
• _snapshot_seller(settings) - Capture store details
• _snapshot_buyer(order) - Capture customer details
• _calculate_totals(order) - Calculate with LU VAT (17%)

For Essential tier: Fixed 17% Luxembourg VAT only. EU VAT comes in Professional.

Files to create:

• app/services/invoice_service.py (new)

---

Step 1.4: PDF Generation (1.5 days)

Add WeasyPrint dependency and create PDF service:

app/services/invoice_pdf_service.py

Methods:

• generate_pdf(invoice) - Returns PDF bytes
• _render_html(invoice) - Jinja2 template rendering

Template:

app/templates/invoices/invoice.html

Simple, clean invoice layout:

• Seller details (top left)
• Buyer details (top right)
• Invoice number + date
• Line items table
• Totals with VAT breakdown
• Footer (payment terms, bank details)

Files to create/modify:

• requirements.txt (add weasyprint)
• app/services/invoice_pdf_service.py (new)
• app/templates/invoices/invoice.html (new)
• app/templates/invoices/invoice.css (new, optional)

---

Step 1.5: Invoice API Endpoints (0.5 day)

Create store invoice endpoints:

app/api/v1/store/invoices.py

Endpoints:

• POST /orders/{order_id}/invoice - Generate invoice for order
• GET /invoices - List invoices
• GET /invoices/{invoice_id} - Get invoice details
• GET /invoices/{invoice_id}/pdf - Download PDF

Files to create/modify:

• app/api/v1/store/invoices.py (new)
• app/api/v1/store/__init__.py (add router)

---

Step 1.6: Invoice Settings UI (0.5 day)

Add invoice settings to store settings page:

Modify existing store settings template to add "Invoice Settings" section:

• Merchant name, address fields
• VAT number
• Invoice prefix
• Payment terms
• Bank details

Files to modify:

• app/templates/store/settings.html (add section)
• static/store/js/settings.js (add handlers)
• app/api/v1/store/settings.py (add endpoints if needed)

---

Step 1.7: Order Detail - Invoice Button (0.5 day)

Add "Generate Invoice" / "Download Invoice" button to order detail:

• If no invoice: Show "Generate Invoice" button
• If invoice exists: Show "Download Invoice" link

Files to modify:

• app/templates/store/order-detail.html (add button)
• static/store/js/order-detail.js (add handler)

---

Step 1.8: Tier Limits Enforcement (1 day)

Create tier/subscription model:

models/database/store_subscription.py

Fields:

• store_id (FK, unique)
• tier (essential, professional, business)
• orders_this_month (counter, reset monthly)
• period_start, period_end
• is_active

Create limits service:

app/services/tier_limits_service.py

Methods:

• check_order_limit(store_id) - Returns (allowed: bool, remaining: int)
• increment_order_count(store_id) - Called when order synced
• get_tier_limits(tier) - Returns limit config
• reset_monthly_counters() - Cron job

Tier limits:

Tier	Orders/month	Products
Essential	100	200
Professional	500	Unlimited
Business	Unlimited	Unlimited

Integration points:

• order_service.py - Check limit before creating order
• Letzshop sync - Check limit before importing

Files to create/modify:

• models/database/store_subscription.py (new)
• app/services/tier_limits_service.py (new)
• app/services/order_service.py (add limit check)
• app/services/letzshop/order_service.py (add limit check)

---

Phase 2: Professional Tier (Target: 2 weeks)

Goal: Build the differentiating features that justify €99/month.

Step 2.1: EU VAT Rates Table (0.5 day)

Create VAT rates reference table:

models/database/eu_vat_rates.py

Fields:

• country_code (LU, DE, FR, etc.)
• country_name
• standard_rate (decimal)
• reduced_rate_1, reduced_rate_2 (optional)
• effective_from, effective_until

Seed with current EU rates (27 countries).

Files to create:

• models/database/eu_vat_rates.py (new)
• alembic/versions/xxx_add_eu_vat_rates.py (migration + seed)

---

Step 2.2: Enhanced Store VAT Settings (0.5 day)

Add OSS fields to StoreInvoiceSettings:

• is_oss_registered (boolean)
• oss_registration_country (if different from merchant country)

Files to modify:

• models/database/store_invoice_settings.py (add fields)
• alembic/versions/xxx_add_oss_fields.py (migration)

---

Step 2.3: VAT Service (1 day)

Create VAT calculation service:

app/services/vat_service.py

Methods:

• get_vat_rate(country_code, as_of_date) - Lookup rate
• determine_vat_regime(seller_country, buyer_country, buyer_vat_number, is_oss) - Returns (regime, rate)
• validate_vat_number(vat_number) - Format check (VIES integration later)

VAT Decision Logic:

1. B2B with valid VAT number → Reverse charge (0%)
2. Domestic sale → Domestic VAT
3. Cross-border + OSS registered → Destination VAT
4. Cross-border + under threshold → Origin VAT

Files to create:

• app/services/vat_service.py (new)

---

Step 2.4: Enhanced Invoice Service (1 day)

Upgrade invoice service for EU VAT:

• Add vat_regime field to invoice (domestic, oss, reverse_charge, origin)
• Add destination_country field
• Use VATService to calculate correct rate
• Update invoice template for regime-specific text

Files to modify:

• models/database/invoice.py (add fields)
• app/services/invoice_service.py (use VATService)
• app/templates/invoices/invoice.html (add regime text)
• alembic/versions/xxx_add_vat_regime_to_invoices.py

---

Step 2.5: Purchase Order Model (1 day)

Create purchase order tracking:

models/database/purchase_order.py

PurchaseOrder:

• id, store_id (FK)
• po_number (auto-generated)
• supplier_name (free text for now)
• status (draft, ordered, partial, received, cancelled)
• order_date, expected_date
• notes

PurchaseOrderItem:

• purchase_order_id (FK)
• product_id (FK)
• quantity_ordered
• quantity_received
• unit_cost_cents (optional)

Files to create:

• models/database/purchase_order.py (new)
• models/database/__init__.py (add import)
• models/schema/purchase_order.py (new)
• alembic/versions/xxx_add_purchase_orders.py

---

Step 2.6: Purchase Order Service (1 day)

Create PO management service:

app/services/purchase_order_service.py

Methods:

• create_purchase_order(store_id, data) - Create PO
• add_item(po_id, product_id, quantity) - Add line item
• receive_items(po_id, items) - Mark items received, update inventory
• get_incoming_stock(store_id) - Summary of pending stock
• list_purchase_orders(store_id, status, skip, limit)

Integration: When items received → call inventory_service.adjust_inventory()

Files to create:

• app/services/purchase_order_service.py (new)

---

Step 2.7: Purchase Order UI (1.5 days)

Create PO management page:

app/templates/store/purchase-orders.html

Features:

• List POs with status
• Create new PO (select products, quantities, expected date)
• Receive items (partial or full)
• View incoming stock summary

Inventory page enhancement:

• Show "On Order" column in inventory list
• Query: SUM of quantity_ordered - quantity_received for pending POs

Files to create/modify:

• app/templates/store/purchase-orders.html (new)
• static/store/js/purchase-orders.js (new)
• app/api/v1/store/purchase_orders.py (new endpoints)
• app/routes/store_pages.py (add route)
• app/templates/store/partials/sidebar.html (add menu item)
• app/templates/store/inventory.html (add On Order column)

---

Step 2.8: Customer Export Service (1 day)

Create customer export functionality:

app/services/customer_export_service.py

Methods:

• export_customers_csv(store_id, filters) - Returns CSV string

CSV Columns:

• email, first_name, last_name, phone
• customer_number
• total_orders, total_spent, avg_order_value
• first_order_date, last_order_date
• preferred_language
• marketing_consent
• tags (if we add tagging)

Files to create:

• app/services/customer_export_service.py (new)

---

Step 2.9: Customer Export API + UI (0.5 day)

Add export endpoint:

GET /api/v1/store/customers/export?format=csv

Add export button to customers page:

• "Export to CSV" button
• Downloads file directly

Files to modify:

• app/api/v1/store/customers.py (add export endpoint)
• app/templates/store/customers.html (add button)

---

Phase 3: Business Tier (Target: 1-2 weeks)

Goal: Build features for teams and high-volume operations.

Step 3.1: Multi-Store Consolidated View (2 days)

For merchants with multiple Letzshop accounts:

New page:

app/templates/store/multi-store-dashboard.html

Features:

• See all store accounts under same merchant
• Consolidated order count, revenue
• Switch between store contexts
• Unified reporting

Requires: Merchant-level authentication context (already exists via Merchant → Store relationship)

Files to create/modify:

• app/templates/store/multi-store-dashboard.html (new)
• app/services/multi_store_service.py (new)
• app/api/v1/store/multi_store.py (new)

---

Step 3.2: Accounting Export (1 day)

Export invoices in accounting-friendly formats:

app/services/accounting_export_service.py

Methods:

• export_invoices_csv(store_id, date_from, date_to) - Simple CSV
• export_invoices_xml(store_id, date_from, date_to) - For accounting software

CSV format for accountants:

• invoice_number, invoice_date
• customer_name, customer_vat
• subtotal, vat_rate, vat_amount, total
• currency, status

Files to create:

• app/services/accounting_export_service.py (new)
• app/api/v1/store/accounting.py (new endpoints)

---

Step 3.3: API Access Documentation (1 day)

If not already documented, create API documentation page:

• Document existing store API endpoints
• Add rate limiting for API tier
• Generate API keys for stores

Files to create/modify:

• docs/api/store-api.md (documentation)
• app/services/api_key_service.py (if needed)

---

Implementation Order Summary

Week 1: Essential Tier

Day	Task	Deliverable
1	Step 1.1	Store Invoice Settings model
1	Step 1.2	Invoice model
2	Step 1.3	Invoice Service (LU only)
3-4	Step 1.4	PDF Generation
4	Step 1.5	Invoice API
5	Step 1.6	Invoice Settings UI
5	Step 1.7	Order Detail button

Week 2: Tier Limits + EU VAT Start

Day	Task	Deliverable
1	Step 1.8	Tier limits enforcement
2	Step 2.1	EU VAT rates table
2	Step 2.2	OSS fields
3	Step 2.3	VAT Service
4	Step 2.4	Enhanced Invoice Service
5	Testing	End-to-end invoice testing

Week 3: Purchase Orders + Customer Export

Day	Task	Deliverable
1	Step 2.5	Purchase Order model
2	Step 2.6	Purchase Order service
3-4	Step 2.7	Purchase Order UI
5	Step 2.8-2.9	Customer Export

Week 4: Business Tier

Day	Task	Deliverable
1-2	Step 3.1	Multi-store view
3	Step 3.2	Accounting export
4	Step 3.3	API documentation
5	Testing + Polish	Full testing

---

Key Files Reference

Models to Create

• models/database/store_invoice_settings.py
• models/database/invoice.py
• models/database/eu_vat_rates.py
• models/database/store_subscription.py
• models/database/purchase_order.py

Services to Create

• app/services/invoice_service.py
• app/services/invoice_pdf_service.py
• app/services/vat_service.py
• app/services/tier_limits_service.py
• app/services/purchase_order_service.py
• app/services/customer_export_service.py
• app/services/accounting_export_service.py

Templates to Create

• app/templates/invoices/invoice.html
• app/templates/store/purchase-orders.html

Existing Files to Modify

• models/database/__init__.py
• models/database/store.py
• app/services/order_service.py
• app/templates/store/settings.html
• app/templates/store/order-detail.html
• app/templates/store/inventory.html
• app/templates/store/customers.html
• requirements.txt

---

Dependencies to Add

# requirements.txt
weasyprint>=60.0

Note: WeasyPrint requires system dependencies:

• libpango-1.0-0
• libpangocairo-1.0-0
• libgdk-pixbuf2.0-0

Add to Dockerfile if deploying via Docker.

---

Testing Strategy

Unit Tests

• tests/unit/services/test_invoice_service.py
• tests/unit/services/test_vat_service.py
• tests/unit/services/test_tier_limits_service.py
• tests/unit/services/test_purchase_order_service.py

Integration Tests

• tests/integration/api/v1/store/test_invoices.py
• tests/integration/api/v1/store/test_purchase_orders.py

Manual Testing

• Generate invoice for LU customer
• Generate invoice for DE customer (OSS)
• Generate invoice for B2B with VAT number (reverse charge)
• Create PO, receive items, verify inventory update
• Export customers CSV, import to Mailchimp

---

Success Criteria

Essential Tier Ready When:

• Can generate PDF invoice from order (LU VAT)
• Invoice settings page works
• Order detail shows invoice button
• Tier limits enforced on order sync

Professional Tier Ready When:

• EU VAT calculated correctly by destination
• OSS regime supported
• Reverse charge for B2B supported
• Purchase orders can be created and received
• Incoming stock shows in inventory
• Customer export to CSV works

Business Tier Ready When:

• Multi-store dashboard works
• Accounting export works
• API access documented