lunarfront-app/planning/06_Domain_Repairs.md

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