Repair Checklists

Repair Checklists

Repair Checklists provide a structured way to ensure every repair follows a consistent, auditable process. Each repair can have one checklist containing multiple items that technicians tick off as they work. Checklists can be created from scratch or applied from predefined templates.

RepairChecklist data fields

Field	Description
repair_id	UUID of the parent repair
template_id	UUID of the ChecklistTemplate used (null if custom)
name	Checklist name (e.g. "Electrical Safety Check")
description	Optional description of the checklist scope
is_required	Boolean — if true, repair cannot be completed until the checklist is finished

The model provides two key methods: getCompletionPercentage() returns an integer from 0 to 100, and isCompleted() returns true only when every item is ticked off.

RepairChecklistItem data fields

Field	Description
checklist_id	UUID of the parent checklist
description	Task description for the technician
is_completed	Boolean completion status
completed_by	UUID of the user who completed this item
completed_at	Timestamp of completion
notes	Optional notes added during completion
requires_photo	Boolean — if true, a photo_url must be provided before marking complete
photo_url	URL of the evidence photo
sort_order	Integer controlling display order (items are sorted ascending)

The markCompleted() method sets is_completed, completed_by, and completed_at in a single operation. isMissingRequiredPhoto() returns true when requires_photo is set but photo_url is empty.

Creating a checklist

RepairChecklistService::createChecklistForRepair creates a new checklist with its items. The system enforces a one-checklist-per-repair rule — if a checklist already exists for the repair, the operation is rejected with an error to prevent duplicates.

To create from a template, use RepairChecklistService::createFromTemplate, which loads the ChecklistTemplate by UUID and populates the checklist name, description, and items from its template_items array.

Completing checklist items

RepairChecklistService::completeChecklistItem validates the completion request. If the item has requires_photo set to true and no photo_url is provided, the request is rejected. Once an item is marked complete, the service automatically updates the repair's checklist_completed flag by checking whether all items are finished.

Items can also be unchecked, which clears the completed_by and completed_at fields and recalculates the checklist status.

Predefined templates

NexusRMS ships with three system templates stored in the checklist_templates table:

• Basic Service — 4 tasks: Visual inspection, Clean unit, Check connections, Functional test
• Electrical Safety — 5 tasks: Check cables for damage, Test earth continuity, Measure insulation resistance, Visual inspection, Apply PAT label
• Deep Clean — 4 tasks: Remove internal dust, Clean external surfaces, Clean ventilation ports, Polish exterior

Templates can be scoped to a specific equipment_category_id or repair_type, or left generic to apply across all equipment. You can create custom templates and mark them as active or inactive using the is_active flag.

Repair completion blocking

When a required checklist has incomplete items, the repair cannot be moved to the completed status. The checklist status endpoint returns a can_complete_repair flag that is only true when is_completed is true and missing_required_photos is zero. This ensures that every required step and its evidence are captured before sign-off.

User interface

The checklist section on the repair detail page displays a progress bar showing the completion percentage. Each item appears as a row with a checkbox, description, photo requirement toggle, and optional notes field. Items support drag-and-drop reordering to adjust the sort_order. A timeline below the checklist shows each completion event with the user name, timestamp, and any notes.

The interface supports two modes: Edit mode for technicians actively working through the list, and Display mode for read-only viewing with completion history.

API routes

Method	Endpoint	Action
POST	/repairs/{repairId}/checklist	Create a checklist (with items array or template_id)
GET	/repairs/{repairId}/checklist	Retrieve checklist with all items and completion data
PUT	/repairs/{repairId}/checklist/{itemId}	Mark an item as completed or uncompleted
GET	/repairs/{repairId}/checklist/status	Get completion summary (total, completed, remaining, percentage)

Tips and best practices

• Use templates for recurring repair types — create templates for your most common repair categories to ensure consistency across technicians.
• Enable photo requirements for critical steps — set requires_photo on items where visual evidence is needed for compliance or quality assurance.
• Keep checklists focused — shorter checklists with clear, actionable items are completed more reliably than long generic lists.
• Review completion timelines — use the status endpoint to monitor how quickly checklists are being completed and identify bottlenecks.

Next steps

Continue to the next article to learn about Photos & Documentation, where you can capture visual evidence at every stage of the repair process.