Add planning docs for trade-ins, returns, tax exemptions, cycle counts, POs, bundles, backorders, barcode labels, instrument sizing, warranties, maintenance schedules, gift cards, layaway, rental agreements, and in-home trials

planning/06_Domain_Repairs.md

@@ -432,4 +432,124 @@ Margin on flat-rate services — e.g. are rehair rates covering costs
 
 - Repair complete status triggers customer notification via preferred channel
 
-- Delivered status set by delivery domain completion — not manually
+- 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