5f8726ee4e
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
4.7 KiB
Music Store Management Platform
Domain Design: Batch Repairs
1. Overview
The Batch Repairs domain handles bulk instrument repair jobs from schools and institutions. This workflow replaces the current spreadsheet-based tracking system. A batch groups multiple individual repair tickets under one job — one approval, one invoice, one delivery event — while still tracking each instrument individually.
2. Batch Lifecycle
Status
Description
scheduled
Pickup from school scheduled — instruments not yet received
picked_up
Store has collected all instruments from school
intake_complete
All instruments assessed, individual tickets created, estimates compiled
pending_approval
Batch estimate sent to school contact — awaiting authorization
approved
School approved — all child tickets authorized to proceed
in_progress
Work underway — child tickets at various stages
ready
All child tickets resolved — batch ready for delivery
delivered
All instruments returned to school, invoice sent
invoiced
Invoice sent to school — awaiting payment
paid
Payment received in full
closed
Batch complete and reconciled
3. Database Schema
3.1 repair_batch
Column
Type
Notes
id
uuid PK
company_id
uuid FK
batch_number
varchar
Human-readable batch ID e.g. BATCH-2024-0042
account_id
uuid FK
School/institution account
contact_name
varchar
School contact person for this batch
contact_phone
varchar
contact_email
varchar
Where to send estimates and invoices
school_po_number
varchar
School's purchase order number if applicable
status
enum
See lifecycle above
scheduled_pickup_date
date
When store plans to collect instruments
actual_pickup_date
date
When store actually collected
promised_return_date
date
Committed return date to school
actual_return_date
date
When instruments actually returned
instrument_count
integer
Expected number of instruments
received_count
integer
Actual count received at pickup
total_estimated
numeric(10,2)
Sum of all child ticket estimates
total_actual
numeric(10,2)
Sum of all child ticket actual costs
approval_date
date
When school approved the estimate
approved_by
varchar
Name/signature of school approver
notes
text
Internal notes
legacy_id
varchar
Reference to source spreadsheet row/ID if migrated
created_at
timestamptz
updated_at
timestamptz
4. Batch Business Rules
-
Batch status auto-advances to 'ready' when all child repair_ticket records reach 'ready' or 'cancelled'
-
Batch approval cascades to all child tickets — sets each to 'approved' status
-
Individual tickets within a batch can still be worked and tracked independently
-
Total estimated and total actual are computed from child tickets — not manually entered
-
School contact can differ from account primary contact — stored per batch
-
School PO number is stored for institutional billing requirements
-
Cancelled child tickets excluded from invoice total but noted on batch summary
-
Instrument count vs received count discrepancy flagged at pickup — requires staff acknowledgement
5. Batch Workflow
5.1 Creating a Batch
-
Staff creates batch record — links to school account, sets contact, expected count, scheduled pickup date
-
Batch number auto-generated in sequence
-
Delivery event created simultaneously for the pickup leg (see Delivery domain)
5.2 Pickup & Intake
-
Driver collects instruments from school — delivery event records condition of each at pickup
-
Back at store, staff creates individual repair_ticket for each instrument
-
Each ticket linked to repair_batch_id
-
Technician assesses each instrument — sets estimated_cost per ticket
-
Once all tickets have estimates, batch status moves to 'pending_approval'
-
Batch estimate report generated — itemized list of all instruments and estimated costs
5.3 Approval
-
Estimate sent to school contact via email (PDF attachment)
-
School approves — approval date and approver name recorded on batch
-
All child tickets set to 'approved' — work begins
-
School may reject specific instruments — those tickets set to 'cancelled', excluded from work
5.4 Invoicing
-
Batch invoice generated when status reaches 'delivered'
-
Invoice shows each instrument, work performed, parts, labor — itemized
-
Total compared to estimate — any variance noted
-
Invoice sent to school contact email and available in customer portal
-
School PO number printed on invoice if provided
6. Reporting
-
Batch repair revenue by school/account
-
Average turnaround time per batch
-
Estimate vs actual variance report
-
Instruments per batch — count and breakdown by work type
-
Outstanding batch invoices (accounts receivable)
-
Technician productivity across batch and individual repairs