# Maintenance Visit Report - API Changes Summary

## Overview
This document outlines the changes made to the Maintenance Visit Report system, including new endpoints, validation updates, and new fields.

---

## 2. Dynamic Questions Feature

### New Endpoints

#### Add Dynamic Question to Visit
- **Endpoint**: `POST /api/maintenance/visits/{visitId}/dynamic-questions`
- **Method**: POST
- **Request Body**:
```json
{
  "maintenance_asset_id": 123,  // Optional: link to specific asset
  "question_text": "Custom question text",
  "question_type": "text|checkbox|yes_no|number",
  "response_value": "Answer here",  // Optional: can be set immediately
  "is_required": false,
  "order_position": 0
}
```

#### Get Dynamic Questions for Visit
- **Endpoint**: `GET /api/maintenance/visits/{visitId}/dynamic-questions`
- **Method**: GET
- **Permission**: `maintenance.visits.view`
- **Response**: Array of dynamic questions with visit, asset, and creator relationships

#### Update Dynamic Question
- **Endpoint**: `PUT /api/maintenance/visits/dynamic-questions/{questionId}`
- **Method**: PUT
- **Permission**: `maintenance.visits.edit`
- **Request Body**: Same fields as create (all optional with `sometimes`)

#### Delete Dynamic Question
- **Endpoint**: `DELETE /api/maintenance/visits/dynamic-questions/{questionId}`
- **Method**: DELETE
- **Permission**: `maintenance.visits.delete`

## 3. Spare Parts - "For Next Visit" Flag

### Updated Endpoints
**Note**: Spare parts endpoints may vary based on your route configuration. Common patterns:
- **POST** `/api/maintenance/spare-parts` - Create spare part (includes `maintenance_visit_id` in request body)
- **PUT** `/api/maintenance/spare-parts/{id}` - Update spare part
- **GET** `/api/maintenance/spare-parts/visit/{visitId}` or `/api/maintenance/visits/{visitId}/spare-parts` - Get spare parts by visit

**Important**: The `is_for_next_visit` field is now available in all spare part create/update requests.

### New Field
- **Field Name**: `is_for_next_visit`
- **Type**: `boolean`
- **Default**: `false`
- **Required**: No (nullable)

### Request Body Example
```json
{
  "part_name": "Filter",
  "quantity": 2,
  "is_for_next_visit": true  // NEW: Mark as needed for next visit
}
```

### Response Format
Spare part resources now include:
```json
{
  "id": 1,
  "part_name": "Filter",
  "quantity": 2,
  "is_for_next_visit": true,  // NEW field
  ...
}
```

### New Service Method
- **Method**: `getSparePartsForNextVisit($visitId)`
- **Usage**: Filter spare parts marked for next visit

---

## 4. Report Attachments - Categorization & Asset Linking

### Updated Endpoints
**Note**: Attachment endpoints may vary based on your route configuration. Common patterns:
- **POST** `/api/maintenance/attachments` - Create attachment (includes `maintenance_visit_report_id` in request body)
- **PUT** `/api/maintenance/attachments/{id}` - Update attachment
- **GET** `/api/maintenance/attachments/report/{reportId}` or `/api/maintenance/reports/{reportId}/attachments` - Get attachments by report

**Important**: The `attachment_type` and `maintenance_asset_id` fields are now available in all attachment create/update requests.

### New Fields

#### `attachment_type`
- **Type**: `enum`
- **Values**: `general`, `before_maintenance`, `after_maintenance`
- **Default**: `general`
- **Required**: No (nullable)

#### `maintenance_asset_id`
- **Type**: `integer` (foreign key)
- **Required**: No (nullable)
- **Purpose**: Link attachment to specific asset

### Request Body Example
```json
{
  "file_name": "asset_photo.jpg",
  "file_path": "/uploads/...",
  "mime_type": "image/jpeg",
  "file_size": 1024000,
  "attachment_type": "after_maintenance",  // NEW: Categorize image
  "maintenance_asset_id": 123  // NEW: Link to specific asset
}
```

### Response Format
Attachment resources now include:
```json
{
  "id": 1,
  "file_name": "asset_photo.jpg",
  "attachment_type": "after_maintenance",  // NEW field
  "maintenance_asset_id": 123,  // NEW field
  "asset": {...},  // NEW: Asset relationship when loaded
  ...
}
```

### New Service Methods
- `getAttachmentsByType($reportId, $type)` - Filter by attachment type
- `getAttachmentsByAsset($reportId, $assetId)` - Filter by asset

---

## Validation Rules Summary

### Checklist Items
- `question_type`: Now accepts `yes_no`, `text`, `number`, `rating`, **`checkbox`**

### Dynamic Questions
- `question_type`: Accepts `text`, `checkbox`, `yes_no`, `number`
- `maintenance_asset_id`: Optional, must exist in `mod_maintenance_assets` if provided
- `response_value`: Optional string

### Spare Parts
- `is_for_next_visit`: Optional boolean

### Report Attachments
- `attachment_type`: Optional, must be one of: `general`, `before_maintenance`, `after_maintenance`
- `maintenance_asset_id`: Optional, must exist in `mod_maintenance_assets` if provided

---

## Database Migrations Required

Before deploying, run these migrations:
1. `2026_01_26_063402_add_checkbox_to_question_type_in_checklist_items.php`
2. `2026_01_26_063511_add_is_for_next_visit_to_spare_parts.php`
3. `2026_01_26_063610_add_attachment_type_and_asset_id_to_report_attachments.php`
4. `2026_01_26_063706_create_maintenance_visit_dynamic_questions_table.php`

---

## Breaking Changes
**None** - All changes are backward compatible. New fields are optional with sensible defaults.

---

## Notes for Frontend

1. **Checkbox Questions**: When displaying checklist items, handle `checkbox` type similar to `yes_no` but allow multiple selections if needed.

2. **Dynamic Questions**: These are visit-specific questions added on-the-fly. They should be displayed alongside template checklist questions but clearly distinguished.

3. **Spare Parts Filtering**: Use `is_for_next_visit` to create separate sections or filters for "Current Visit" vs "Next Visit" spare parts.

4. **Attachment Categories**: Use `attachment_type` to organize images in the UI (e.g., tabs or sections for "Before", "After", "General").

5. **Asset-Specific Data**: Both dynamic questions and attachments can be linked to specific assets. When a visit has multiple assets, use `maintenance_asset_id` to group/filter accordingly.