Add planning documents for Forte music store platform

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

planning/06_Domain_Repairs.md

@@ -0,0 +1,435 @@
+Music Store Management Platform
+
+Domain Design: Repairs
+
+Version 1.2  |  Updated: Parts inventory, bulk materials, flat-rate billing, tech metrics
+
+
+
+# 1. Overview
+
+The Repairs domain manages instrument intake, diagnosis, work tracking, parts, labor billing, and customer pickup. It integrates with the repair parts inventory for materials tracking and supports three billing models: per-unit parts billing, flat-rate service billing (e.g. bow rehairs), and shop supply tracking. Repair tickets support both individual customer repairs and bulk school repairs via batch grouping.
+
+
+
+# 2. Repair Ticket Lifecycle
+
+Status
+
+Description
+
+intake
+
+Instrument received, condition documented, intake ticket printed for customer
+
+diagnosing
+
+Technician evaluating — estimate not yet provided
+
+pending_approval
+
+Estimate provided, awaiting customer authorization
+
+approved
+
+Customer approved — work authorized
+
+in_progress
+
+Actively being repaired — parts being logged
+
+pending_parts
+
+Waiting on parts order from supplier
+
+ready
+
+Repair complete — awaiting pickup or delivery
+
+picked_up
+
+Customer collected instrument and paid
+
+delivered
+
+Instrument returned via store delivery event
+
+cancelled
+
+Repair cancelled — instrument returned uncompleted
+
+
+
+# 3. Database Schema
+
+## 3.1 repair_ticket
+
+Column
+
+Type
+
+Notes
+
+id
+
+uuid PK
+
+
+
+company_id
+
+uuid FK
+
+
+
+repair_batch_id
+
+uuid FK
+
+Nullable — null = individual repair
+
+ticket_number
+
+varchar
+
+Human-readable ID
+
+account_id
+
+uuid FK
+
+Nullable — walk-in without account
+
+customer_name
+
+varchar
+
+Denormalized for walk-ins
+
+customer_phone
+
+varchar
+
+Contact for ready notification
+
+inventory_unit_id
+
+uuid FK
+
+Nullable — known instrument
+
+instrument_description
+
+varchar
+
+Free text for unknown instruments
+
+serial_number
+
+varchar
+
+If known
+
+condition_in
+
+enum
+
+excellent|good|fair|poor — at intake
+
+condition_in_notes
+
+text
+
+Detailed condition at intake
+
+problem_description
+
+text
+
+Customer description of issue
+
+technician_notes
+
+text
+
+Internal diagnosis and work notes
+
+status
+
+enum
+
+See lifecycle above
+
+assigned_technician_id
+
+uuid FK
+
+Employee assigned
+
+estimated_cost
+
+numeric(10,2)
+
+Estimate given to customer
+
+actual_cost
+
+numeric(10,2)
+
+Final billed amount
+
+intake_date
+
+date
+
+
+
+promised_date
+
+date
+
+Estimated completion date
+
+completed_date
+
+date
+
+When repair work finished
+
+linked_rental_id
+
+uuid FK
+
+If repair from rental return
+
+legacy_id
+
+varchar
+
+AIM service ticket ID
+
+created_at
+
+timestamptz
+
+
+
+
+
+## 3.2 repair_line_item
+
+Line items on a repair ticket cover three billing types — labor, per-unit parts, and flat-rate services. All three appear on the customer invoice.
+
+Column
+
+Type
+
+Notes
+
+id
+
+uuid PK
+
+
+
+repair_ticket_id
+
+uuid FK
+
+
+
+item_type
+
+enum
+
+labor | part | flat_rate | misc
+
+description
+
+varchar
+
+Customer-facing description
+
+repair_part_usage_id
+
+uuid FK
+
+Nullable — links to parts usage record
+
+qty
+
+numeric(10,3)
+
+Supports fractional for bulk materials
+
+unit_price
+
+numeric(10,2)
+
+Rate per unit
+
+total_price
+
+numeric(10,2)
+
+qty * unit_price
+
+cost
+
+numeric(10,2)
+
+Internal cost — for margin calculation
+
+technician_id
+
+uuid FK
+
+For labor lines — which tech
+
+created_at
+
+timestamptz
+
+
+
+
+
+## 3.3 Billing Type Examples
+
+Type
+
+Description
+
+Qty
+
+Price
+
+Notes
+
+labor
+
+Mechanical overhaul
+
+2.5 hrs
+
+$65/hr
+
+Tech rate x hours
+
+part
+
+Trumpet valve guide
+
+3 each
+
+$2.50 ea
+
+Per-unit billable part
+
+flat_rate
+
+Bow Rehair — Full Size
+
+1
+
+$50.00
+
+Labor + hair bundled
+
+flat_rate
+
+Bow Rehair — Cello
+
+1
+
+$70.00
+
+0.67 hank consumed internally
+
+misc
+
+Expedite fee
+
+1
+
+$15.00
+
+Custom charge
+
+
+
+# 4. Technician Workflow — Parts Logging
+
+When a technician works a repair ticket they log parts as they use them. The interface is optimized for speed — minimal clicks to record common operations.
+
+
+
+Repair Ticket #RT-2024-0042 — Bach Stradivarius TrumpetTechnician: Sarah M.   Status: in_progress[+ Add Labor]  [+ Add Part]  [+ Add Flat Rate Service]Current line items:  Labor    Full mechanical overhaul    2.5 hrs @ $65    $162.50  Part     Trumpet valve guide (x3)    3 @ $2.50         $7.50  Part     Valve spring set (x1)       1 @ $8.00         $8.00  [shop]   Valve oil (shop supply)     recorded, not billed  [shop]   Cleaning patches (x4)       recorded, not billed                                                   ─────────  Subtotal:                                         $178.00  Est. given to customer:                           $180.00
+
+
+
+# 5. Technician Productivity Reporting
+
+Because parts and labor are tracked per technician per ticket, the system can generate detailed productivity and profitability reports that are unavailable in AIM.
+
+
+
+Report
+
+Description
+
+Revenue per technician
+
+Total billed labor and parts per tech per period
+
+Gross margin per ticket
+
+Revenue minus labor cost minus parts cost per ticket
+
+Parts usage by tech
+
+Which parts each technician uses — identifies unusual consumption
+
+Bow rehair analysis
+
+Rehairs completed, hair consumed per size, yield per hank
+
+Shop supply expense
+
+Overhead cost of shop supplies by period and by technician
+
+Average turnaround time
+
+Intake to completion per tech and per repair type
+
+Estimate accuracy
+
+Actual vs estimated cost variance per tech
+
+Flat rate profitability
+
+Margin on flat-rate services — e.g. are rehair rates covering costs
+
+
+
+# 6. Business Rules
+
+- Shop supply parts logged for cost tracking but never appear on customer invoice
+
+- Flat-rate services show as single line item on invoice — hair/material consumption tracked internally
+
+- Parts costs recorded at time of use — historical accuracy preserved if costs change
+
+- Technician cannot log more parts than qty_on_hand — system warns and blocks
+
+- Dual-use parts logged in repair decrease sale inventory qty_on_hand automatically
+
+- Estimate approval required before work begins — waivable with manager override
+
+- Actual cost variance from estimate requires reason code logged in audit trail
+
+- Batch repair approval cascades to all child tickets
+
+- Repair complete status triggers customer notification via preferred channel
+
+- Delivered status set by delivery domain completion — not manually