## Calibration Logs Module User Guide

### 1. Purpose

The **Calibration Logs** module is used to track the calibration status of all site instruments and welding / test equipment.  
It provides:

-   Central register of instruments (name, model, serial, quantity)
-   Calibration certificate and user guide PDFs
-   Due date monitoring with color indications
-   Notifications when calibration is due within 20 days
-   Automatic sync from **NAKS Welding Equipments** for welding machines

---

### 2. How to Access

1. Login to the application.
2. From the left menu, navigate to **QA → Calibration Logs**.
3. The page will open with a DevExtreme DataGrid listing all calibration records.

---

### 3. Column Overview

Key columns (left to right):

-   **Certification Document** (`certification_document`):
    -   PDF icon link to the calibration certificate.
    -   Filled automatically by the PDF upload sync script.
-   **User Guide** (`user_guide`):
    -   Optional PDF link for instrument user/operation manual.
-   **Instrument** (`instrument`):
    -   Category selection:
        -   `Civil Works Test Equipment`
        -   `Piping/Mechanical Test Equipment`
        -   `Instrument Test Equipment`
        -   `Painting and Coating Test Equipment`
        -   `Electrical Test Equipment`
        -   `Welding Equipment`
-   **Item No** (`item_no`): Line/item number from the register.
-   **Name** (`equipment_name`): Instrument or equipment name.
-   **Manufacturer** (`manufacturer`), **Model No** (`model_no`), **Serial No** (`serial_no`), **Quantity** (`quantity`)
-   **Passport / Certificate No** (`passport_certificate_no`)
-   **Place of Calibration / Verification** (`place_of_calibration_verification`):
    -   `Laboratory`, `In house verification`, or `In house calibration`.
-   **Calibrated By** (`calibrated_by`)
-   **Calibration Frequency (months)** (`calibration_frequency`):
    -   Integer value in months.
-   **Calibration Certificate No** (`calibration_certificate_no`)
-   **Calibration Date** (`calibration_date`)
-   **Calibration Due Date** (`calibration_due_date`)
-   **Deviation Ratio** (`deviation_ratio`)
-   **Status** (`status`):
    -   `In use`, `Out Of service`, `Repair`, `Calibration-Verification`
-   **Remarks** (`remarks`) and **Comments** (`comments`)

System fields:

-   **source_module**, **source_id**: Link to source modules (e.g. `welding_equipment`).

---

### 4. Row Colors & Due-Date Logic

Rows are color-coded based on `calibration_due_date`:

-   **Expired (red row)**: `calibration_due_date` \< today.
-   **Due Soon (yellow row)**: `calibration_due_date` is between today and today + 20 days.
-   **Normal (white row)**: More than 20 days until due date.

The same due date is used by the notification command:

-   Artisan command: `php artisan notifications:check-calibration-due`
-   Notification code: `notification_calibration_due_soon`

---

### 5. PDF Upload and Sync

Calibration certificates are stored under:

-   Storage path: `storage/documents/004_QA/0020_Calibration`

Usage:

1. Open **QA → Calibration Logs**.
2. Click the **Upload** button (top of the grid).
3. Select table **`calibration_logs`** and drop one or more PDF files.
4. The sync script `cron/pdf-db-calibration-logs-sync.blade.php` tries to match files to rows:
    - First by `calibration_certificate_no`
    - Then by `passport_certificate_no`
    - Finally by `equipment_name`
5. When a match is found, the `certification_document` field is updated with the PDF path and the PDF icon becomes visible in the grid.

> Recommendation: Name files starting with the **Calibration Certificate No** (e.g. `C-12345 ... .pdf`) to ensure reliable matching.

---

### 6. Notifications Configuration

The 20-day notification uses:

-   Command: `notifications:check-calibration-due`
-   Notification code: `notification_calibration_due_soon`

To configure which user levels receive this notification:

1. Go to **Settings → Specific Permissions → Notification Settings**.
2. Find **“Calibration Due Soon”** (`notification_calibration_due_soon`).
3. Select the user levels (e.g. `Admin`, `Quality Staff`, `QC Manager`).
4. Click **Update**.

When the command runs (via scheduler or manually), users in these levels will see **“Calibration Due Soon”** items in the notification bell.

---

### 7. NAKS Welding Equipments Sync

When a record is created or updated in **NAKS Welding Equipments** (`welding_equipment` table):

-   The helper `syncCalibrationFromWeldingEquipment()` is called from `AdminController`.
-   It creates or updates a corresponding `calibration_logs` record with:
    -   `instrument = "Welding Equipment"`
    -   Basic identity fields (name, manufacturer, model, serial)
    -   `passport_certificate_no` from `attestation`
    -   `calibration_date` from `date_of_issue`
    -   `calibration_due_date` from `valid_until`
    -   `status` calculated from due date (`Valid`, `Due Soon`, `Expired`)

This ensures welding machines are automatically visible in the Calibration Logs register without manual re-entry.