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
301 lines
4.7 KiB
Markdown
301 lines
4.7 KiB
Markdown
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 |