From dcc3dd1eed01e0cf2bf1489ba977f29e21a0d69a Mon Sep 17 00:00:00 2001 From: Ryan Moon Date: Fri, 27 Mar 2026 18:38:12 -0500 Subject: [PATCH] Add sales commission planning doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 | 122 +++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 planning/21_Domain_Sales_Commission.md diff --git a/planning/21_Domain_Sales_Commission.md b/planning/21_Domain_Sales_Commission.md new file mode 100644 index 0000000..d964724 --- /dev/null +++ b/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)