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 # 7. Warranty Tracking Warranties are tracked per inventory unit — both manufacturer warranties and store-offered extended warranties. Warranty status is surfaced during repair intake to determine billing responsibility. ## 7.1 warranty Column | Type | Notes id | uuid PK | company_id | uuid FK | Tenant scoping inventory_unit_id | uuid FK | The specific instrument covered account_id | uuid FK | Account that owns the warranty warranty_type | enum | manufacturer | extended | store provider | varchar | Warranty provider name (e.g. "Yamaha", "Store Protection Plan") coverage_description | text | What's covered — free text or template start_date | date | When coverage begins end_date | date | When coverage expires purchase_price | numeric(10,2) | Nullable — price paid for extended warranty (0 for manufacturer) transaction_id | uuid FK | Nullable — sale transaction where warranty was purchased status | enum | active | expired | claimed | voided max_claims | integer | Nullable — max number of claims allowed (null = unlimited) claims_used | integer | Default 0 notes | text | created_at | timestamptz | updated_at | timestamptz | ## 7.2 warranty_claim Column | Type | Notes id | uuid PK | warranty_id | uuid FK | repair_ticket_id | uuid FK | The repair covered by this claim claim_date | date | issue_description | text | What went wrong resolution | text | How it was resolved claim_amount | numeric(10,2) | Cost covered by warranty status | enum | submitted | approved | denied | completed denied_reason | text | Nullable — why claim was denied processed_by | uuid FK | Employee who processed created_at | timestamptz | ## 7.3 Warranty Flow 1. **At sale**: staff optionally adds extended warranty to transaction — warranty record created linked to inventory_unit 2. **Manufacturer warranty**: auto-created when new serialized item is sold, using manufacturer's standard warranty period 3. **At repair intake**: system checks if instrument has active warranty — surfaces to staff 4. **If under warranty**: repair ticket linked to warranty claim — customer not billed (or reduced billing) 5. **Claim processing**: store submits claim to manufacturer for reimbursement if applicable 6. **Expiry**: system tracks end_date — warranty status auto-updated to "expired" ## 7.4 Business Rules - Warranty checked automatically during repair intake — staff sees "UNDER WARRANTY" or "WARRANTY EXPIRED" - Extended warranties are sold as a line item on the original sale transaction - Manufacturer warranty periods are configurable per brand (e.g. Yamaha = 5 years, generic = 1 year) - Warranty claims reduce repair ticket billing — covered amount shown on invoice as "warranty credit" - Voided warranties (e.g. customer damage outside coverage) require reason code and manager approval - Warranty report: active warranties by expiry date, claim history, claim approval rate # 8. Maintenance Schedules Preventive maintenance recommendations and reminders per instrument. Helps stores build recurring service revenue and keeps customer instruments in good condition. ## 8.1 maintenance_schedule_template Company-configurable templates define recommended maintenance intervals by instrument type. Column | Type | Notes id | uuid PK | company_id | uuid FK | Tenant scoping instrument_type | varchar | e.g. "violin", "trumpet", "clarinet", "flute" service_name | varchar | e.g. "Bow Rehair", "Valve Oil & Cleaning", "Pad Replacement Check" interval_months | integer | Recommended interval between services description | text | Customer-facing description of what the service includes estimated_cost | numeric(10,2) | Typical cost — for customer expectation setting sort_order | integer | Display order is_active | boolean | created_at | timestamptz | ## 8.2 maintenance_reminder Tracks scheduled reminders for specific instruments owned by customers. Column | Type | Notes id | uuid PK | company_id | uuid FK | account_id | uuid FK | member_id | uuid FK | Nullable — specific member inventory_unit_id | uuid FK | Nullable — specific instrument if tracked template_id | uuid FK | Which maintenance template this follows instrument_description | varchar | Fallback description if no inventory_unit linked last_service_date | date | When this service was last performed next_due_date | date | Computed: last_service_date + interval_months status | enum | upcoming | due | overdue | completed | dismissed notification_sent | boolean | Whether customer has been notified repair_ticket_id | uuid FK | Nullable — linked to repair ticket when service is scheduled created_at | timestamptz | updated_at | timestamptz | ## 8.3 Maintenance Workflow 1. When a repair is completed, system suggests creating maintenance reminders based on instrument type 2. Reminders auto-calculated: next_due_date = completed_date + template.interval_months 3. Daily job checks for due/overdue reminders — generates notification queue 4. Customer notified via preferred channel (email, SMS, portal notification) 5. When customer brings instrument in, staff sees pending maintenance recommendations 6. Completed service updates the reminder: last_service_date = today, next recalculated ## 8.4 Business Rules - Maintenance reminders are suggestions, not obligations — customer can dismiss - Templates are seeded with common defaults, fully customizable per store - Reminders auto-created for rental fleet instruments — store maintains own fleet on schedule - Overdue reminders escalate: due → 30 days overdue (second notice) → 90 days (final notice, then dismissed) - Maintenance history visible on customer account and instrument record - Revenue report: maintenance service revenue, conversion rate from reminder to repair ticket