Repair Requests — Feature List

1. Feature Overview

The Repair Requests module allows customers to submit laptop repair requests, track status through a multi-stage lifecycle, and receive push notifications at each stage.

Key properties:

Repair is free of charge — no payment integration
Supports N devices per ticket
Brands can be selected from the platform brand catalog or entered as a custom name
Admin drives the full status lifecycle; customers may only self-cancel at request_received
Collection method (pickup / dropoff) is admin-controlled and can be changed at any time
Admin notes are internal and never exposed in customer-facing responses

2. Route Ownership

Surface	Route prefix	Module
Customer API	`/api/repair-requests`	`RepairCustomerModule`
Admin API	`/api/admin/repair-requests`	`RepairAdminModule`

Swagger tags:

Repair Requests (Customer)
Repair Requests (Admin)

3. Customer Feature Matrix

Capability	Endpoint	Auth
Submit repair request	`POST /api/repair-requests`	JWT customer
List own repair requests	`GET /api/repair-requests`	JWT customer
View repair request detail	`GET /api/repair-requests/:publicId`	JWT customer (owner only)
Cancel repair request	`PATCH /api/repair-requests/:publicId/cancel`	JWT customer (owner only, status must be `request_received`)

4. Admin Feature Matrix

Capability	Endpoint	Permission
List all repair requests	`GET /api/admin/repair-requests`	`RepairRequests_READ`
View repair request detail	`GET /api/admin/repair-requests/:id`	`RepairRequests_READ`
Update status	`PATCH /api/admin/repair-requests/:id/status`	`RepairRequests_UPDATE`
Update collection method	`PATCH /api/admin/repair-requests/:id/collection-method`	`RepairRequests_UPDATE`
Update admin notes	`PATCH /api/admin/repair-requests/:id/notes`	`RepairRequests_UPDATE`

5. Status Lifecycle

Status	Meaning	Who sets it
`request_received`	Initial state on ticket creation	System (auto on create)
`picked_up`	Laptop collected from customer	Admin
`under_repair`	Repair work started	Admin
`repaired`	Repair complete	Admin
`packed`	Laptop packed for return	Admin
`delivered`	Laptop returned to customer	Admin
`cancelled`	Request cancelled	Customer (from `request_received` only) or Admin (from any non-terminal status)

delivered and cancelled are terminal — no further transitions are possible.

6. Notification Triggers

Push notifications are sent to the customer's registered devices at each admin status change.

Status	Notification Title
`request_received`	"Repair Request Received" (on ticket creation)
`picked_up`	"Laptop Picked Up"
`under_repair`	"Repair In Progress"
`repaired`	"Repair Completed"
`packed`	"Out for Delivery Soon"
`delivered`	"Laptop Delivered"
`cancelled`	"Repair Cancelled"

All notifications use type: "transactional" and priority: "high" and are fire-and-forget (never block the API response).

7. Device Configuration

Each repair ticket may contain one or more devices. Per device:

brandId — select from the platform brands catalog, OR
customBrandName — enter a brand not in the catalog
Exactly one of brandId or customBrandName is required (DB-level CHECK constraint enforces this)
laptopModel — free-text laptop model name (required)
problemDescription — optional per-device description
orderItemId — optional link to an order line item

If all devices share the same issue, use sharedDescription at the ticket level instead of per-device descriptions.

8. Business Rules

Minimum 1 device per repair request.
No limit on the number of devices per ticket.
No duplicate ticket prevention — multiple tickets for the same device are allowed.
orderId is optional — repair does not need to be linked to a purchase.
order_item_id must belong to the linked order_id when both are provided.
Guest users: form state is saved in localStorage; after login the user is redirected with pre-filled data (no backend session carryover).
adminNotes is excluded from all customer-facing responses.
Collection method defaults to pickup and can be changed by admin at any time regardless of status.

9. Data Tables

Table	Purpose
`repair_ticket`	One row per repair request
`repair_ticket_device`	One row per device per ticket (1..N)
`repair_ticket_status_history`	Append-only status change log per ticket

Repair Requests Feature List