citrus-cms/resources/views/guide/weldlog-weldmap-incoming-popup-implementation.md

# Weldlog/Weldmap Incoming Control Popup Implementation

## Overview
This document describes the file-by-file changes made to implement the Incoming Control popup functionality and file upload enhancements for Weldlog/Weldmap modules.

## File Changes and Their Features

### 1. Database Migrations

#### `database/migrations/2025_11_25_201715_add_fields_to_incoming_controls_for_weldlog.php`
**Purpose:** Adds new fields to `incoming_controls` table for enhanced file tracking and data management.

**Fields Added:**
- `inspection_photo_file` (string, nullable) - Path to inspection photo files
- `email_tq_file` (string, nullable) - Path to Email/TQ agreement files
- `email_tq_number` (string, nullable) - Email/TQ tracking number
- `osd_defect_akt_file` (string, nullable) - Path to OSD Defect AKT files
- `osd_report_date` (date, nullable) - OSD report date
- `drawing_number` (string, nullable) - Drawing number for project tracking

**Feature:** Enables storage of additional file paths and tracking information in Incoming Control records.

---

#### `database/migrations/2025_11_25_201743_add_drawing_number_to_mtos.php`
**Purpose:** Adds `drawing_number` field to `m_t_o_s` table.

**Fields Added:**
- `drawing_number` (string, nullable) - Drawing number for MTO records

**Feature:** Enables drawing number tracking in MTO module, which can be synced to Incoming Control.

---

### 2. AJAX Endpoints

#### `resources/views/admin-ajax/get-incoming-for-weldlog.blade.php`
**Purpose:** AJAX endpoint that fetches Incoming Control records for the popup based on filtering criteria.

**Features:**
- Filters by `component_code` (required parameter)
- Optional filtering by `ru_material_group` (matches material in materials table)
- Sorts by `id DESC` (most recent first), then `rfi_date ASC`
- Adds `highlight` flag to rows where `rfi_date > welding_date` (for visual warning)
- Returns JSON with all relevant Incoming Control fields including new file fields

**Parameters:**
- `component_code` (required) - Element code to filter by
- `ru_group` (optional) - RU material group for additional filtering
- `welding_date` (optional) - Welding date for highlight calculation

**Response Format:**
```json
[
  {
    "id": 1,
    "component_code": "...",
    "rfi_date": "...",
    "certificate_no": "...",
    "heat_number": "...",
    "highlight": true/false,
    ...
  }
]
```

---

### 3. Components

#### `resources/views/components/incoming-control-popup.blade.php`
**Purpose:** DevExtreme Popup component with DataGrid for selecting Incoming Control records.

**Features:**
- **Popup Window:** 1250x720px, resizable, with close button
- **DataGrid:** 
  - CustomStore for dynamic data loading
  - Search panel and filter row
  - Pagination (15 items per page, configurable)
  - Single row selection
  - Row highlighting for records where RFI date > welding date
- **Info Column:** Shows file icons (camera, envelope, file) with links to:
  - Inspection photo file
  - Email/TQ file
  - OSD Defect AKT file
- **Column Display:**
  - Component Code
  - Received/RFI Date (highlighted if > welding date)
  - Zone (project field)
  - Drawing Number
  - Material Descriptions (EN/RU)
  - Certificate No
  - Heat No
  - Received Quantity
  - Certificate Date
  - Constructor/Supplier
  - Email/TQ Number
  - OSD Report Date
- **Selection:** Double-click or single selection to choose record
- **Callback:** Passes selected data to callback function

**Global Functions:**
- `window.showIncomingControlPopup(options)` - Opens popup with parameters
- `window.setupIncomingControlPopupHelpers(dataGrid)` - Attaches magnifier icons to target cells

---

#### `resources/views/components/table/datagrid/file-link.blade.php`
**Purpose:** New component for rendering file links in DataGrid cells (separate from link-search to avoid breaking existing functionality).

**Features:**
- **Icon Display:** Shows custom HTML icon (default: PDF icon)
- **Link Generation:** Creates clickable links to files
- **Show Value Option:** Can hide/show file path text (`show_value` parameter)
- **Editable Support:** Can make cells editable with `allowEditing` parameter
- **Placeholder Support:** Custom placeholder text for editable cells
- **Empty String Validation:** Properly handles null, undefined, and empty string values
- **Stop Propagation:** Prevents grid editing when clicking file icon

**Configuration Options:**
- `html` - Custom icon HTML (default: `<i class="fa fa-file-pdf"></i>`)
- `show_value` - Show/hide file path text (default: true)
- `allowEditing` - Enable cell editing (default: false)
- `placeholder` - Placeholder text for editable cells

**Usage:**
```php
'pdf_engineering' => [
    'type' => 'file-link',
    'html' => '<i class="fa fa-pdf"></i>',
    'show_value' => false
]
```

---

### 4. View Files - Incoming Control

#### `resources/views/admin/type/incoming-control.blade.php`
**Purpose:** Main Incoming Control module view with new fields and upload sections.

**Changes:**
1. **Block Groups Updated:**
   - Added `inspection_photo_file`, `email_tq_file`, `osd_defect_akt_file` to 'Files' group
   - Added `drawing_number` to 'Project Info' group
   - Added 'Email / Technical Query Tracking' group with `email_tq_number`
   - Added 'OSD Defect' group with `osd_report_date`

2. **Relation Data:**
   - Added `inspection_photo_file` with `file-link` type, editable, icon-only display
   - Added `email_tq_file` with `file-link` type, editable, icon-only display
   - Added `osd_defect_akt_file` with `file-link` type, editable, icon-only display

3. **Upload Sections:**
   - Added 3rd upload: Inspection Photos (`10004_Incoming_inspection_Photos/`)
   - Added 4th upload: Email/TQ Files (`10005_Material_Agreement/`)
   - Added 5th upload: OSD Defect AKT (`10003_Defect_Akt/`)
   - Configured accepted file types for each upload

4. **Editor Preparing:**
   - Added manual file column handling for new file fields
   - Enables text box editing with placeholder for file path input

5. **MTO Sync:**
   - Added `drawing_number` to sync from MTO to Incoming Control

**Features:**
- File upload for inspection photos, email/TQ files, and OSD defect files
- Editable file path columns with placeholders
- Drawing number synchronization from MTO
- Icon-only display for file columns (cleaner UI)

---

### 5. View Files - Weldmap/Weldlog

#### `resources/views/admin/type/weldmap/main.blade.php`
**Purpose:** Weldmap module main view with PDF columns and popup integration.

**Changes:**
1. **PDF Columns Updated:**
   - Changed `pdf_engineering`, `pdf_spool_iso`, `pdf_as_build` from `link-search` to `file-link`
   - Added `show_value => false` to display only icons (no file path text)

2. **Popup Integration:**
   - Added `@include("components.incoming-control-popup")` before datagrid script

**Features:**
- PDF columns show only icons (cleaner interface)
- Popup component available for certificate/heat number selection

---

#### `resources/views/admin/type/weldmap/datagrid-script.blade.php`
**Purpose:** Weldmap DataGrid JavaScript configuration with popup helper integration.

**Changes:**
1. **Initialized Function:**
   - Added call to `window.setupIncomingControlPopupHelpers(dataGrid)` after WPS guard attachment

**Features:**
- Attaches magnifier icons to `certificate_number_of_1/2` and `heat_number_1/2` cells
- Icons trigger popup when clicked
- Popup filters data based on element code and RU material group
- Selected data auto-fills certificate and heat number fields

---

### 6. View Files - MTO

#### `resources/views/admin/type/mto.blade.php`
**Purpose:** MTO module view with drawing number field.

**Changes:**
1. **Block Groups:**
   - Added `drawing_number` to 'General Information' group

**Features:**
- Drawing number can be entered in MTO
- Synced to Incoming Control during MTO sync operation

---

### 7. Upload Components

#### `resources/views/admin/type/document/upload.blade.php`
**Purpose:** Document upload modal with multiple upload sections.

**Changes:**
1. **Upload Sections:**
   - Added support for 4th and 5th upload sections (conditional display)
   - Added `acceptedFiles` configuration for each upload section
   - Added `data-upload-label` attribute to forms

2. **Dropzone Configuration:**
   - Dynamic Dropzone initialization based on available upload sections
   - Configurable accepted file types per section
   - Success callback with SweetAlert showing uploaded file path

3. **SweetAlert Integration:**
   - Shows uploaded file path in textarea (selectable)
   - "Copy to clipboard" button for easy path copying
   - Prevents accidental modal closure

**Features:**
- Up to 5 upload sections (configurable per module)
- Different accepted file types per section
- User-friendly path display and copying
- Archive previous versions when replacing files

---

#### `resources/views/admin-ajax/document-upload.blade.php`
**Purpose:** Backend endpoint for handling file uploads.

**Changes:**
1. **Path Normalization:**
   - Changed path construction to use `trim()` for folder cleaning
   - Returns path in format: `storage/documents/{folder}/{filename}`

**Features:**
- Consistent path format for all uploaded files
- Archive functionality for replaced files
- Document history tracking
- Normalized paths work correctly with file-link component

---

## Feature Summary

### 1. Incoming Control Popup
- **Trigger:** Magnifier icon in certificate/heat number cells
- **Filtering:** By component code and RU material group
- **Highlighting:** Rows where RFI date > welding date
- **Selection:** Auto-fills certificate and heat number fields
- **Files Display:** Shows icons for inspection photos, email/TQ, and OSD files

### 2. File Upload Enhancements
- **Multiple Sections:** Up to 5 upload sections per module
- **File Types:** Configurable accepted file types per section
- **Path Display:** SweetAlert with copy-to-clipboard functionality
- **Path Format:** Normalized `storage/documents/...` format

### 3. New File Fields
- **Inspection Photos:** Photo upload with dedicated folder
- **Email/TQ Tracking:** File and number tracking
- **OSD Defect:** File upload and report date
- **Drawing Number:** Added to both MTO and Incoming Control

### 4. File Display Component
- **file-link Component:** New component for file columns
- **Icon-Only Mode:** Can hide file path text
- **Editable Support:** Can make file paths editable
- **Backward Compatible:** Doesn't affect existing link-search usage

### 5. Data Synchronization
- **MTO to Incoming Control:** Drawing number syncs automatically
- **File Paths:** Normalized format ensures consistency

---

## Testing Checklist

- [ ] Incoming Control popup opens from weldmap/weldlog certificate/heat number cells
- [ ] Popup filters correctly by component code
- [ ] Highlighting works for RFI date > welding date
- [ ] Selected data fills certificate and heat number fields
- [ ] File upload sections work (3rd, 4th, 5th)
- [ ] Uploaded file paths display in SweetAlert
- [ ] Copy-to-clipboard button works
- [ ] PDF icons display in weldmap (no file path text)
- [ ] File icons display in incoming control (no file path text)
- [ ] Drawing number syncs from MTO to Incoming Control
- [ ] File paths are normalized correctly
- [ ] Editable file columns work with placeholders

---

## Technical Notes

1. **Component Separation:** `file-link` was created as a new component to avoid breaking existing `link-search` functionality used in other modules.

2. **Path Normalization:** All file paths are normalized to `storage/documents/{folder}/{file}` format to ensure consistent access.

3. **Popup State Management:** Uses global `popupState` object to manage popup instance, data source, and callback functions.

4. **Highlighting Logic:** RFI date comparison is done server-side to reduce client-side processing.

5. **Backward Compatibility:** All changes are additive - existing functionality remains unchanged.