555 lines
12 KiB
Markdown
555 lines
12 KiB
Markdown
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 |