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