# Test Scenario Guide: Standardized Numbering Sequences

### 1. Scenario Introduction 📋
The **Standardized Numbering Sequences** feature implements a unified, automated numbering system across all key entities in the Maintenance Management module. The goal is to provide a consistent, human-readable, and audit-friendly reference format (`PREFIX-YYYY-NNNN`) that resets annually. This replaces several disparate manual sequence services with a centralized logic embedded in the `BaseModel`, ensuring data integrity and simplifying the creation of new entities.

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

The standardization involves adding a new `code` field to multiple database tables and exposing it through API Resources. The generation is handled automatically during the model's `creating` event via `BaseModel`.

#### Database Migration
*   **Tables Affected:**
    *   `mod_maintenance_price_offers` (Quotations)
    *   `mod_maintenance_projects` (Projects)
    *   `mod_maintenance_visits` (Visits)
    *   `mod_maintenance_visit_reports` (Visit Reports)
    *   `sup_supply_orders` (Purchase Orders / Supply Orders)
    *   `sup_purchase_orders` (Supplier Purchase Orders)
*   **Column Added:** `code` (String, Unique, Nullable)

#### API Response Changes
The following API Resources now include the `code` field in their JSON output:

*   **Resources:** 
    *   `MaintenancePriceOfferResource`
    *   `ProjectResource` / `ProjectDetailsResource`
    *   `MaintenanceVisitResource` / `DetailedMaintenanceVisitResource`
    *   `MaintenanceVisitReportResource`
    *   `SupplyOrderResource`
    *   `PurchaseOrderResource`
*   **Field Change:** Added `code` key to the response.
    *   *Example:* `"code": "QT-2026-0001"`

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

| Aspect | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **Logic** | Multiple manual `SequenceServices` and custom `booted` logic in each model. | Centralized `withGenerateCode` logic in `BaseModel`. | Reduced code duplication & easier maintenance. |
| **Format** | Inconsistent (e.g., `PO-Timestamp-Random`, `VISIT-YYYY-NNNNN`). | Unified `PREFIX-YYYY-NNNN`. | Better readability and professional appearance. |
| **Reset Logic** | Manual or missing yearly reset. | Automated yearly reset based on `{year}` placeholder in prefix. | Accurate annual tracking and reporting. |
| **Data Field** | Used entity-specific fields like `offer_number` or `visit_number`. | Uses a standardized `code` field across all models. | Uniformity for global search and audit modules. |

### 4. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| **Quotations** | `/api/maintenance/price-offers` | `GET` | Lists quotations with the new `code` format. |
| **Projects** | `/api/maintenance/projects` | `GET` | Lists projects including the `code` field. |
| **Visits** | `/api/maintenance/visits` | `GET` | Lists maintenance visits with standardized codes. |
| **Reports** | `/api/maintenance/visit-reports` | `GET` | Lists visit reports showing the `RPT-` sequence. |
| **Supply Orders** | `/api/supply/orders` | `GET` | Lists supply orders with the `PO-` prefix. |

### 5. Test Cases 🧪

#### [Case 1] The Happy Path: New Record Creation
1.  **Action:** Create a new **Maintenance Price Offer** via the API or UI.
2.  **Expected Result:** The system automatically generates a code in the format `QT-2026-XXXX`.
3.  **Validation:** Query the database or check the API response for the `code` field. The sequence should increment by 1 from the last record of the same year.

#### [Case 2] Yearly Reset Verification
1.  **Action:** Set the system date to January 1st of the next year (e.g., 2027) in a test environment.
2.  **Action:** Create a new **Maintenance Visit**.
3.  **Expected Result:** The system generates `VIS-2027-0001`, even if `VIS-2026-0500` existed.
4.  **Validation:** Ensure the numbering restarts at `0001` for the new year prefix.

#### [Case 3] Backward Compatibility & Backfill
1.  **Action:** Run the command `php artisan maintenance:fix-numbering`.
2.  **Expected Result:** All existing records that have a `null` or empty `code` field are populated with a generated code following the new format.
3.  **Validation:** Legacy fields (like `offer_number` or `contract_number`) remain untouched and visible in the API, ensuring no breaking changes for older frontend versions.

#### [Case 4] Company Scoping
1.  **Action:** Create a record in **Company A** and another in **Company B**.
2.  **Expected Result:** If `generateCodeWithCompanies` is enabled, both companies should start their own sequences (e.g., both could have a `QT-2026-0001` if they are isolated).
3.  **Validation:** Ensure sequences are isolated per company to avoid skipping numbers or collisions in multi-tenant views.