5f8726ee4e
17 domain design docs covering architecture, accounts, inventory, rentals, lessons, repairs, POS, payments, batch repairs, delivery, billing, accounting, deployment, licensing, installer, and backend tech architecture. Plus implementation roadmap (doc 18) and personnel management (doc 19). Key design decisions documented: - company/location model (multi-tenant + multi-location) - member entity (renamed from student to support multiple adults) - Stripe vs Global Payments billing ownership differences - User/location/terminal licensing model - Valkey 8 instead of Redis
231 lines
3.0 KiB
Markdown
231 lines
3.0 KiB
Markdown
Music Store Management Platform
|
|
|
|
Domain Design: Sales & Point of Sale
|
|
|
|
|
|
|
|
# 1. Overview
|
|
|
|
The Sales & POS domain handles all in-person and counter transactions — retail sales, deposits, repair payments, rental fees, and account charges. It integrates with Stripe Terminal for card-present payments and Stripe Elements for keyed entry.
|
|
|
|
|
|
|
|
# 2. Transaction Types
|
|
|
|
Type
|
|
|
|
Description
|
|
|
|
sale
|
|
|
|
Retail sale of product — instruments, accessories, supplies
|
|
|
|
repair_payment
|
|
|
|
Payment collected at repair ticket pickup
|
|
|
|
rental_deposit
|
|
|
|
Security deposit collected at rental start
|
|
|
|
account_payment
|
|
|
|
Payment against outstanding account balance
|
|
|
|
refund
|
|
|
|
Return of payment — full or partial
|
|
|
|
|
|
|
|
# 3. Database Schema
|
|
|
|
## 3.1 transaction
|
|
|
|
Column
|
|
|
|
Type
|
|
|
|
Notes
|
|
|
|
id
|
|
|
|
uuid PK
|
|
|
|
|
|
|
|
company_id
|
|
|
|
uuid FK
|
|
|
|
Tenant scoping
|
|
|
|
location_id
|
|
|
|
uuid FK
|
|
|
|
Physical location where transaction occurred
|
|
|
|
transaction_number
|
|
|
|
varchar
|
|
|
|
Human-readable ID
|
|
|
|
account_id
|
|
|
|
uuid FK
|
|
|
|
Nullable for anonymous cash sales
|
|
|
|
transaction_type
|
|
|
|
enum
|
|
|
|
sale|repair_payment|rental_deposit|account_payment|refund
|
|
|
|
status
|
|
|
|
enum
|
|
|
|
pending|completed|voided|refunded
|
|
|
|
subtotal
|
|
|
|
numeric(10,2)
|
|
|
|
Before tax and discounts
|
|
|
|
discount_total
|
|
|
|
numeric(10,2)
|
|
|
|
Total discounts applied
|
|
|
|
tax_total
|
|
|
|
numeric(10,2)
|
|
|
|
|
|
|
|
total
|
|
|
|
numeric(10,2)
|
|
|
|
Final amount charged
|
|
|
|
payment_method
|
|
|
|
enum
|
|
|
|
card_present|card_keyed|cash|check|account_charge
|
|
|
|
stripe_payment_intent_id
|
|
|
|
varchar
|
|
|
|
For card transactions
|
|
|
|
stripe_terminal_reader_id
|
|
|
|
varchar
|
|
|
|
Which reader was used
|
|
|
|
processed_by
|
|
|
|
uuid FK
|
|
|
|
Employee who processed
|
|
|
|
notes
|
|
|
|
text
|
|
|
|
|
|
|
|
created_at
|
|
|
|
timestamptz
|
|
|
|
|
|
|
|
|
|
|
|
## 3.2 transaction_line_item
|
|
|
|
id, transaction_id, product_id (nullable), inventory_unit_id (nullable),description, qty, unit_price, discount_amount, discount_reason,tax_rate, line_total, created_at
|
|
|
|
|
|
|
|
## 3.3 discount
|
|
|
|
id, company_id, location_id, name, discount_type (percent|fixed),discount_value, applies_to (order|line_item|category),requires_approval_above (threshold amount), is_active,valid_from, valid_until, created_at
|
|
|
|
|
|
|
|
## 3.4 discount_audit
|
|
|
|
id, transaction_id, transaction_line_item_id, discount_id,applied_by (employee_id), approved_by (employee_id, nullable),original_amount, discounted_amount, reason, created_at
|
|
|
|
|
|
|
|
# 4. Discount & Adjustment Rules
|
|
|
|
- Discounts are applied at line item or order level
|
|
|
|
- Discounts exceeding manager threshold require approval — logged in discount_audit
|
|
|
|
- Manual price overrides treated as discounts — require reason code
|
|
|
|
- Promotional codes validated against discount table before application
|
|
|
|
- All discounts appear as line items on invoice — original price shown
|
|
|
|
- Discount audit records are immutable — no deletion permitted
|
|
|
|
|
|
|
|
# 5. Payment Methods
|
|
|
|
Method
|
|
|
|
Integration
|
|
|
|
Notes
|
|
|
|
Card present
|
|
|
|
Stripe Terminal WiFi
|
|
|
|
Desktop — WisePOS E reader
|
|
|
|
Card present (BT)
|
|
|
|
Stripe Terminal BT
|
|
|
|
iOS — Bluetooth reader at conventions
|
|
|
|
Card keyed
|
|
|
|
Stripe Elements
|
|
|
|
Desktop — PCI safe, card data never touches app
|
|
|
|
Cash
|
|
|
|
Manual entry
|
|
|
|
Change calculated, drawer tracked
|
|
|
|
Check
|
|
|
|
Manual entry
|
|
|
|
Check number recorded
|
|
|
|
Account charge
|
|
|
|
Internal
|
|
|
|
Charges to account balance — billed later |