Add sales commission planning doc

Commission is default for most products. Simple model: employee
rate × sale price. Override table for exceptions (consignment at 0%,
category-level adjustments). Commission snapshotted at time of sale.

planning/21_Domain_Sales_Commission.md

@@ -0,0 +1,122 @@
+Forte — Music Store Management Platform
+
+Domain Design: Sales Commission
+
+Version 1.0  |  Draft
+
+
+
+# 1. Overview
+
+Sales commission tracks what employees earn on sales they process. Commission is the default for instrument sales — most products are commissionable. The system supports per-employee rates with product and category overrides for exceptions.
+
+
+
+# 2. Commission Rate Hierarchy
+
+When a sale is completed, the commission rate is resolved in this order (most specific wins):
+
+Priority | Source | Example
+1 | Product-specific override | Consignment items at 0%, specific high-margin items at higher rate
+2 | Category override | Accessories at 5% instead of default 10%
+3 | Employee's personal rate | Senior staff at 12%, new staff at 8%
+4 | Company default | Fallback rate for all commissionable sales (e.g. 10%)
+
+If a product has `is_commissionable = false` at any level, no commission is calculated regardless of employee rate.
+
+
+
+# 3. Database Schema
+
+## 3.1 Company Settings (additions)
+
+Column | Type | Notes
+default_commission_percent | numeric(5,2) | Company-wide default (e.g. 10.00)
+commission_enabled | boolean | Master switch — disables all commission tracking
+
+## 3.2 Employee (additions to personnel table)
+
+Column | Type | Notes
+commission_rate | numeric(5,2) | Nullable — employee's personal rate. If null, uses company default.
+
+## 3.3 commission_override
+
+Exceptions to the default commission rate — by product or category.
+
+Column | Type | Notes
+id | uuid PK |
+company_id | uuid FK |
+product_id | uuid FK | Nullable — if set, applies to this specific product
+category_id | uuid FK | Nullable — if set, applies to all products in this category
+commission_percent | numeric(5,2) | Override rate — 0 means no commission on this item
+is_commissionable | boolean | False = no commission regardless of rate
+reason | text | Why this override exists
+created_by | uuid FK |
+is_active | boolean |
+created_at | timestamptz |
+
+Only one of product_id or category_id should be set per record. Product-level overrides take priority over category-level.
+
+## 3.4 sales_commission
+
+Records the actual commission earned per employee per transaction. Created when a transaction is completed at POS.
+
+Column | Type | Notes
+id | uuid PK |
+company_id | uuid FK |
+transaction_id | uuid FK → transaction |
+transaction_line_item_id | uuid FK | Nullable — if tracked per line item
+employee_id | uuid FK | The employee who made the sale (transaction.processed_by)
+sale_amount | numeric(10,2) | The sale amount commission is calculated on (after discounts)
+commission_rate | numeric(5,2) | Rate applied (snapshot at time of sale)
+commission_amount | numeric(10,2) | Actual commission earned
+rate_source | enum | company_default, employee_rate, category_override, product_override
+created_at | timestamptz |
+
+The `rate_source` field records where the rate came from — useful for auditing and commission disputes.
+
+
+
+# 4. POS Integration
+
+- When a transaction is completed, the system resolves commission for each commissionable line item
+- Commission calculated on the sale price after discounts (not list price)
+- If the employee has a personal rate, it is used. Otherwise, company default.
+- Product and category overrides cap or modify the rate for specific items
+- Commission records created automatically — no manual entry
+- Staff can see their commission on the transaction receipt (optional, configurable)
+
+
+
+# 5. Settlement and Payroll
+
+- Commission is tracked per transaction and per employee
+- Commission totals included in payroll export (from Personnel domain)
+- Pay period commission report: employee, total sales, total commission, average rate
+- Commission can be paid as part of regular payroll or as a separate payout
+- The platform tracks commission — it does not run payroll. Commission totals are exported for the external payroll service.
+
+
+
+# 6. Reporting
+
+Report | Description
+Commission by employee | Total commission earned per employee per period
+Commission by product/category | Which products generate the most commission
+Commission rate analysis | Average effective rate by employee — identifies rate discrepancies
+Top sellers | Employees ranked by sales volume and commission earned
+Override impact | How much commission is saved/changed by product and category overrides
+Commission vs revenue | Commission as a percentage of total revenue — cost analysis
+Consignment vs regular commission | Separate tracking since consignment items may have different rules
+
+
+
+# 7. Business Rules
+
+- Commission is calculated on sale price after discounts, not list price
+- Refunds reverse the associated commission record
+- Voided transactions delete uncommitted commission records
+- Commission rate is snapshotted at time of sale — later rate changes do not affect historical commissions
+- Only the employee on transaction.processed_by earns commission (no split commission in v1)
+- Consignment items default to is_commissionable = false unless explicitly overridden
+- Commission on rental deposits and repair payments: configurable per company (default: no commission on these)