# Test Scenario Guide: Client Satisfaction Rating on Completion Certificate

### 1. Scenario Introduction 🌟
This feature introduces a **Client Satisfaction Rating** system for the maintenance module. When a corrective visit is completed, the technician captures a mandatory **1-5 star rating** and an optional **comment** from the client during the signature process. This data is critical for **Technician Performance Tracking** and **Service Quality Assurance**. System-wide alerts are triggered for low ratings (1-2) to ensure rapid managerial follow-up.

### 2. Technical Schema Changes (Detailed) 🔍

#### Endpoint: `POST /api/v1/maintenance/visits/{visit}/completion-certificate`
*   **Validation Changes:**
    *   `client_rating`: Added as **required**, **integer**, and constrained to `between:1,5`.
    *   `client_rating_comment`: Added as **nullable**, **string**, with a maximum length of **500** characters.
*   **Database Constraints:**
    *   Table `mod_maintenance_completion_certificates`: Added `client_rating` (tinyInteger) and `client_rating_comment` (text).
    *   Added DB-level check constraint: `CHECK (client_rating BETWEEN 1 AND 5)`.

#### API Response Changes (`CompletionCertificateResource`):
*   Added `client_rating`: (int) The numeric rating.
*   Added `client_rating_comment`: (string) The client's feedback.
*   Added `rating_label`: A dictionary mapping numeric values to descriptive strings (e.g., `1 => "Poor"`, `5 => "Excellent"`).

### 3. Why the Update? (Change Log) 🔄

| Metric | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **Client Feedback** | No rating captured at visit completion. | Mandatory 1-5 rating + optional comment. | Direct feedback loop from client. |
| **Quality Control** | Low-quality service required manual discovery. | **Automatic alert** to Technical Manager for ratings ≤ 2. | Proactive issue resolution. |
| **Data Integrity** | No validation on client satisfaction. | DB-level and Request-level constraints on rating values. | Reliable data for reporting. |
| **Reporting** | No average rating metrics available. | Statistical method added for average ratings. | Improved technician performance analysis. |

### 4. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| Submit Certificate | `/api/v1/maintenance/visits/{visit}/completion-certificate` | `POST` | Records signature, rating, and comment. |
| Get Certificate Data | `/api/v1/maintenance/visits/{visit}/completion-certificate` | `GET` | Retrieves certificate details including rating. |
| Performance Stats | `/api/v1/maintenance/statistics/average-rating` | `GET` | Retrieves average client rating based on filters. |

### 5. Test Cases 🧪

*   **[Case 1] The Happy Path (Excellent Service):**
    *   Submit a certificate with `client_rating = 5` and a valid comment.
    *   **Expectation:** Status code 201. Record created in DB. No low-rating alert triggered. Average rating in stats increases.
*   **[Case 2] Backward Compatibility:**
    *   View an old visit without a completion certificate.
    *   **Expectation:** `client_rating` returns `null` or 0 in API, but doesn't crash the UI or reports.
*   **[Case 3] Low Rating Alert (The "Poor" Path):**
    *   Submit a certificate with `client_rating = 2`.
    *   **Expectation:** Technical Manager receives an automatic notification titled: *"تقييم منخفض — [Client] | Low Rating — [Technician] — [Visit #]"*.
*   **[Case 4] Validation Constraints:**
    *   Attempt to submit `client_rating = 6` or `client_rating = 0`.
    *   **Expectation:** Validation error (422) for rating range.
    *   Attempt to submit without a rating.
    *   **Expectation:** Validation error (422) as rating is now **required**.