# FINEART SHOP PARTNERSHIP SYSTEM - SPECIFICATION # Complete Reference Document for Development # Version 1.0 - February 12, 2026 ================================================================================ EXECUTIVE SUMMARY ================================================================================ FINEART is implementing a consignment-based retail partnership program with physical shops on the Côte d'Azur. The system manages inventory tracking, sales reporting, commission calculations, damage handling, and invoicing through a custom WordPress plugin. ================================================================================ 1. BUSINESS MODEL ================================================================================ Partnership Structure: - Type: Consignment only (shops don't purchase upfront) - Commission Split: 50% to shop / 50% to FINEART - Commission is negotiable per shop (set in admin) Product Offering: - Formats: SMALL and MEDIUM unframed prints only - Packaging: Premium - crystal sleeve, matboard with artist signature + edition number, COA attached to back - Display Strategy: * Top wall: 5-6 framed prints for display only (FINEART owns, never sold) * Bottom shelves: Unframed prints in sleeves for purchase * Installation: Hole-free using Command strips (2-hour setup) Pricing (Tax Included): - SMALL: €69 TTC (€57.50 HT) - MEDIUM: €129 TTC (€107.50 HT) Artist Commission (Shop Sales) - FIXED RATES (tax excluded): - SMALL: €10 - MEDIUM: €20 - Online sales maintain existing MultiVendorX rates: €20/€40/€80/€200 Financial Breakdown Example (MEDIUM at full price): - Sale: €129 TTC (€107.50 HT) - Shop commission (50%): €53.75 - FINEART receives (50%): €53.75 - Production cost: €13.40 - Artist commission: €20 - YOUR PROFIT: €20.35 ================================================================================ 2. DISCOUNT POLICY ================================================================================ Rules: - Shop can apply 0-20% discount at their discretion - No approval workflow required - All parties share loss proportionally EXCEPT artist (fixed €10/€20 unchanged) - Commission calculated on actual discounted sale price HT Implementation: - Discount applied via dropdown in "Declare Sale" modal - Options: 5%, 10%, 15%, 20% - Real-time commission calculation display - No manual price input (prevents errors) Example: MEDIUM with 15% discount - Original: €129 TTC → Discounted: €109.65 TTC (€91.38 HT) - Shop commission: €45.69 - FINEART receives: €45.69 - Artist: €20 (unchanged) - YOUR PROFIT: €12.29 (vs €20.35 at full price) ================================================================================ 3. SALES DECLARATION SYSTEM - THREE ENTRY POINTS ================================================================================ A) QR Code Scan - Each print has unique QR code on back - Format: FA-[ShopCode]-[ArtworkID]-[Size]-[SerialNumber] - Example: FA-MON01-PORSCHE911-M-003 - Redirects to: fineart.gallery/shop-sale/[UNIQUE-CODE] - Shows confirmation modal B) "Declare Sale" Button (Stock Table) - Click button next to each artwork/size - Opens same modal as QR scan C) "Declare Multiple Sales" (Batch Entry) - Monthly stock reconciliation option - Table interface to enter quantities sold per item - Submit all at once "Declare Sale" Modal Interface: ┌──────────────────────────────────────────────────┐ │ Confirm Sale │ ├──────────────────────────────────────────────────┤ │ Artwork: Porsche 911 Turbo │ │ Size: MEDIUM │ │ │ │ Retail Price: €129 │ │ │ │ ○ Full Price (€129) │ │ ○ Discounted Price │ │ └─→ [5%] [10%] [15%] [20%] │ │ Sale Price: €109.65 │ │ │ │ Current Stock: 3 → After Sale: 2 │ │ │ │ ┌────────────────────────────────────────┐ │ │ │ Your Commission: €46.44 │ │ │ │ FINEART Commission: €46.44 │ │ │ └────────────────────────────────────────┘ │ │ │ │ [ ✓ CONFIRM SALE ] [ CANCEL ] │ └──────────────────────────────────────────────────┘ Sale Processing: - Deducts from shop inventory - Calculates commission (50% of actual sale price HT) - Logs artist payment (fixed €10 or €20) - Adds to shop's "Commission Due" running total - Creates WooCommerce order with meta: sale_type = 'shop' - No email notifications to shop (silent processing) ================================================================================ 4. DAMAGE/LOSS POLICY ================================================================================ Flat Replacement Fee Structure: - SMALL: €12 per print - MEDIUM: €18 per print - Covers production (€8-13.40) + shipping (~€2-3) + admin buffer (€2) - NO DISTINCTION BY CAUSE (shop negligence, customer theft, accidents - all same fee) - No artist commission on damaged prints (never sold) "Report Damage/Loss" Modal: ┌──────────────────────────────────────────────────┐ │ Report Damaged or Lost Item │ ├──────────────────────────────────────────────────┤ │ Artwork: Porsche 911 Turbo │ │ Size: MEDIUM │ │ │ │ Incident Type: │ │ ( ) Damaged │ │ ( ) Lost/Stolen │ │ │ │ Brief Description (optional): │ │ [Text area] │ │ │ │ Replacement Fee: €18 │ │ (Added to next invoice) │ │ │ │ Current Stock: 3 → After Report: 2 │ │ │ │ [ SUBMIT REPORT ] [ CANCEL ] │ └──────────────────────────────────────────────────┘ Processing: - Deducts from inventory - Adds fee to next invoice - Creates damage record in database - Notifies admin for review - No artist commission calculated Pattern Monitoring: - Yellow Warning: 2-3 damages in 6 months (monitor) - Red Alert: 4+ damages in 6 months (review required) - Critical: 6+ damages in 6 months (partnership review/termination) ================================================================================ 5. RESTOCK WORKFLOW - WooCommerce €0 Checkout ================================================================================ Shop Process: 1. Special "Shop Restock" product category (only visible to shop_partner role) 2. Products listed: Your 5-6 curated artworks in SMALL/MEDIUM 3. Price shown: €0.00 4. Add to cart → Standard WC checkout 5. Payment step bypassed (€0 order) 6. Order status: "Pending Fulfillment" Admin Process: 1. Receive WC order notification: "Shop Monaco #1 - Restock Request" 2. See items: Quantities per artwork/size 3. Prepare prints, ship to shop 4. Mark order as "Fulfilled" 5. Shop inventory updated Restrictions: - Shop can only restock artworks they currently carry - Cannot add new artworks via cart (must contact FINEART for approval) - Quantity limits: Max 5 per size per order ================================================================================ 6. INVOICE & PAYMENT SYSTEM ================================================================================ Invoice Generation: - Trigger: MANUAL (you click "Generate Invoice" in admin when ready) - NOT automatic (gives you control to review before sending) - Covers sales + damage fees for a period (typically monthly) Invoice Structure Example: ┌────────────────────────────────────────────────────────┐ │ INVOICE #INV-MON01-202502 │ │ Monaco Shop #1 │ │ Period: February 1-28, 2025 │ ├────────────────────────────────────────────────────────┤ │ SALES (3 prints sold) │ │ Total Sales (HT): €322.50 │ │ Your Commission (50%): €161.25 │ │ │ │ DAMAGED/LOST ITEMS │ │ 1x Porsche 911 Turbo - MEDIUM €18.00 │ │ 1x Ferrari 250 GTO - SMALL €12.00 │ │ Subtotal Damage Fees: €30.00 │ │ │ ├────────────────────────────────────────────────────────┤ │ TOTAL DUE TO FINEART: €191.25 │ │ │ │ Payment Due: March 15, 2025 (Net 30) │ └────────────────────────────────────────────────────────┘ Payment Process - 3 STATES: 1. UNPAID (Red) - Invoice generated, awaiting payment - Shop sees: [Make Payment] button 2. PENDING VALIDATION (Orange) - Shop clicked "I have completed the transfer" - Includes unique payment reference (e.g., INV-MON01-202502) - Waiting for you to verify in bank account - Shop sees: "Payment submitted, awaiting confirmation" 3. PAID (Green) - You confirmed payment received in admin - Invoice PDF updated with "PAID" stamp - Shop sees: "Paid on [date]" Payment Terms: - Default: Net 30 (customizable per shop in admin) - Overdue: Invoice passes due date + 7 days → Status becomes OVERDUE (dark red) ================================================================================ 7. SHOP DASHBOARD (FRONTEND PORTAL) ================================================================================ User Role: shop_partner - Custom WordPress role - Access to frontend dashboard only (not WP admin) - Can only see their own shop data Dashboard Sections: A) Shop Profile & Status (Read-Only) - Partnership type, commission %, payment terms - FINEART contact info - Shop addresses, contact person, tax ID B) Exhibition Display Inventory (Framed Prints - Not for Sale) - Table showing which framed prints FINEART loaned for display - Shop can report damage via button - View only (shop cannot add/remove) C) Stock Management (Prints for Sale) - Table: Artwork | Size | Current Stock | Actions - Actions: [Declare Sale] [Report Damage/Loss] [Order More] D) Damage/Loss History - Table: Date | Artwork | Size | Type | Fee | Status E) Financial Dashboard - Top banner: Next Payment Due with amount, due date, period - [Make Payment] [Download Invoice] buttons - Invoice History Table with status colors ================================================================================ 8. ADMIN PLUGIN: "FINEART SHOP MANAGER" ================================================================================ Custom Post Type: shop_partner - Each shop is a post - Custom fields: All profile data, addresses, commission %, payment terms - Relationship to WP user (the shop_partner login) Admin Menu Pages: 1. All Shops (List View) - Columns: Shop name, Location, Commission %, Status, Commission Owed, Last Sale - Filters: Active/Inactive, Overdue payments, High damage rate 2. Shop Detail Page - TABS: - Profile: Edit all shop info, partnership terms, contact, contract upload - Display Inventory: Manage framed prints on display - Sales Inventory: Current stock, manually adjust if needed - Sales History: All sales with dates, prices, discounts - Damage Reports: All incidents, pattern tracking - Financials: Commission owed, generate invoice, payment history - Restock Requests: Pending WC orders, fulfillment tracking 3. Financial Overview (All Shops) - PRIORITY ALERTS: * Payments pending validation (ORANGE) * Overdue payments (RED) - Total commission owed - Total shops (active count) 4. Damage Reports Overview - Last 30 days summary - Shops with alerts - All damage reports table 5. Artist Payments (Separate from MultiVendorX) - Shop sales: Fixed €10/€20 - Online sales: Existing MultiVendorX rates - Pending payments, export CSV, mark as paid ================================================================================ 9. DATABASE SCHEMA ================================================================================ Table: wp_fineart_shop_inventory - id, unique_code, shop_id, product_id, size - status (in_stock/sold/damaged/returned) - qr_code_url, date_stocked, date_sold - sale_price, discount_percent Table: wp_fineart_shop_sales - id, shop_id, inventory_id, order_id, product_id, size - sale_price_ht, discount_percent - shop_commission, fineart_commission, artist_commission - date_sold, invoice_id Table: wp_fineart_shop_damages - id, shop_id, inventory_id, product_id, size - incident_type (damaged/lost/stolen) - description, fee_amount - date_reported, invoice_id, status Table: wp_fineart_shop_invoices - id, shop_id, invoice_number - period_start, period_end - sales_total, shop_commission, fineart_commission, damage_fees, total_due - status (unpaid/pending/paid/overdue) - payment_reference, due_date, payment_date, pdf_url Table: wp_fineart_artist_payments - id, artist_id, sale_id, order_id, product_id - sale_type (shop/online) - amount, status (pending/paid), payment_date ================================================================================ 10. SHOP META FIELDS (Custom Fields for shop_partner Post Type) ================================================================================ CRITICAL: These are the custom meta fields that need to be created via meta boxes Partnership Details: - _shop_commission_percent (default: 50) - _shop_payment_terms (default: "Net 30") - _shop_contract_start_date - _shop_status (active/inactive/suspended) Contact Information: - _shop_contact_name - _shop_contact_email - _shop_contact_phone - _fineart_contact_name (your name) - _fineart_contact_email - _fineart_contact_phone Addresses: - _shop_delivery_address_street - _shop_delivery_address_city - _shop_delivery_address_postal - _shop_delivery_address_country - _shop_invoicing_address_street - _shop_invoicing_address_city - _shop_invoicing_address_postal - _shop_invoicing_address_country Business Info: - _shop_tax_id - _shop_business_registration System: - _shop_user_id (linked WordPress user) - _shop_code (e.g., "MON01" for Monaco Shop #1) ================================================================================ 11. FEATURES EXPLICITLY EXCLUDED (NOT BUILDING) ================================================================================ - Automatic monthly invoice generation (manual trigger instead) - Email notifications for every action (only critical alerts) - Audit log / activity history (manual notes for now) - Multi-user per shop (one login per shop) - Photo inventory verification - Advanced analytics/reporting (focus on essential: payments, damages) - Integration with shop POS systems - Shop filter/search in stock table - Per-item sales history view ================================================================================ 12. DEVELOPMENT PRIORITY ================================================================================ PHASE 1: BASE FOUNDATION ✅ COMPLETE - Database tables created - Custom role and post type - Admin menu structure - Basic dashboard with stats PHASE 2: SHOP MANAGEMENT (NEXT - BUILD THIS) - Meta boxes for shop editing - Save/validate shop data - Create shop user automatically - Generate shop code PHASE 3: SALES & INVENTORY - Sales declaration system (3 entry points) - Discount handling - Inventory updates - Artist payment logging PHASE 4: DAMAGES & INVOICES - Damage reporting - Invoice generation - PDF creation - Payment tracking (3 states) PHASE 5: FRONTEND DASHBOARD - Shop login/dashboard page - Stock management interface - Sales modals - Financial overview PHASE 6: QR CODES & ADVANCED - QR code generation (requires chillerlan/php-qrcode) - Batch operations - Email notifications ================================================================================ END OF SPECIFICATION ================================================================================ This document contains all decisions and requirements for the FINEART Shop Partnership System. Reference it when building any feature.