citrus-cms/resources/views/guide/PDF-EDITOR-STEP3-ROADMAP.md

PDF Editor Step 3 - Joint Widget & Weldmap Entegrasyonu Roadmap

📋 Görev Özeti

Amaç: PDF çizimlerinde interaktif joint veri girişi sağlamak ve PDF Editor, Base Weldmap ve Weldlog veritabanları arasında iki yönlü entegrasyon kurmak.

Temel Gereksinimler:

1. Veri girişi için interaktif joint widget (popup)
2. Kayıt edilene kadar geçici veri depolama
3. Base Weldmap ve Weldlog ile SQL entegrasyonu
4. İki yönlü veri senkronizasyonu
5. Document Revision entegrasyonu (Spool Iso / As-Build)

---

🎯 Fonksiyonel Gereksinimler Özeti

Senaryo 1: Engineering Iso + Adding Joints

• Kullanıcı PDF üzerine üçgen (Field) veya yuvarlak (Shop) çizer
• Veri girişi için widget otomatik açılır
• Veriler kayıt edilene kadar hafızada tutulur
• Kayıt sırasında: SQL ile Base Weldmap'e ekleme
• Çizimi Document Revision "Spool Iso" kısmına kaydet

Senaryo 2: Spool Iso/Asbuild Iso + Adding Joints & Welder

• Kullanıcı mevcut joint üzerine gelir
• Widget önceden girilmiş verilerle açılır (Welder1-2 boş)
• Welder1-2 dropdown'larında uygun kaynakçıları listele
• PDF görüntüsünü güncelle: joint no (üstte), welder ID (altta), ayırıcı çizgi
• Kayıt sırasında: SQL ile Weldlog'u güncelle
• Çizimi Document Revision "As-Build" kısmına kaydet

Senaryo 3: Veri Var ama Çizim Eksik

• Base Weldmap/Welder verisi var ama çizim eksik mi kontrol et
• Sol paneli aktifleştir: Spool No, Joint No, Welder ID bölümleri
• Kullanıcı Spool No seçer → Joint listesi
• Kullanıcı Joint + F/S şekli seçer → Çizim görünür
• Kullanıcı Joint + Welder + F/S şekli seçer → Welder ile çizim görünür
• Document Revision'a kaydet (Spool Iso veya As-Build)

---

🗺️ Geliştirme Roadmap'i

Faz 1: Temel Yapı & Veri Yapısı (Hafta 1)

1.1 Geçici Veri Depolama Sistemi

Hedef: Kaydedilmemiş joint verileri için hafıza içi veri depolama sistemi oluştur

Görevler:

• Geçici depolama için JointDataManager JavaScript sınıfı oluştur
• Veri yapısını uygula: Map<shapeId, jointData>
• Depolamadan önce veri doğrulama ekle
• Tarayıcı sessionStorage'da veri kalıcılığı (yedek)
• Sayfa kapanışında veri temizleme oluştur

En İyi Uygulamalar:

• O(1) arama performansı için Map kullan
• Çakışma çözümü için veri versiyonlama uygula
• Depolamadan önce veri doğrulama katmanı ekle
• Sayfa yenilemede hayatta kalması için sessionStorage kullan

Oluşturulacak/Değiştirilecek Dosyalar:

• resources/views/admin/type/pdf-editor.blade.php (JointDataManager sınıfı ekle)
• Oluştur: public/js/pdf-editor/joint-data-manager.js (opsiyonel ayrım)

1.2 Widget Modal Geliştirmesi

Hedef: Mevcut joint widget modal'ını tüm gerekli alanlarla geliştir

Görevler:

• joint-widget-modal.blade.php dosyasını gözden geçir ve geliştir
• Edit type'a göre koşullu alan gösterimi ekle
• IC Log member seçimi uygula (Member1, Member2)
• IC Log'dan Material, Dia, NPS, Thickness için otomatik doldurma mantığı ekle
• Yeterliliğe göre welder dropdown filtreleme uygula
• Form doğrulama ekle

En İyi Uygulamalar:

• Dropdown'lar için Select2 kullan (projede mevcut)
• Member seçimi için debounced API çağrıları uygula
• Kademeli dropdown'lar uygula (member → material detayları)
• Asenkron işlemler için yükleme durumları ekle
• Bootstrap 5 form doğrulama kullan

Değiştirilecek Dosyalar:

• resources/views/components/modals/joint-widget-modal.blade.php
• resources/views/admin/type/pdf-editor.blade.php (widget entegrasyonu)

Önemli Not: Widget açılışı için double-click kullanılacak. Mevcut double-click silme özelliği kaldırılmalı veya farklı bir tuş kombinasyonu ile değiştirilmelidir.

---

Phase 2: Shape Interaction & Widget Integration (Week 1-2)

2.1 Shape Click/Hover Event Handling

Goal: Open widget when user interacts with joint shapes

Tasks:

• Add click event listener to triangle/circle shapes
• Add hover event listener for existing joints (Scenario 2)
• Position widget near clicked shape
• Load existing data if joint already has data
• Handle shape creation event (Scenario 1)

Best Practices:

• Use Fabric.js event delegation for performance
• Implement debouncing for hover events
• Calculate optimal widget position (avoid screen edges)
• Use requestAnimationFrame for smooth animations
• Add visual feedback (highlight shape on hover)

Implementation:

// Shape click handler
fabricCanvas.on('mouse:down', (e) => {
    if (e.target && (e.target.type === 'triangle' || e.target.type === 'circle')) {
        if (currentEditType === 'adding_joints' || currentEditType === 'adding_joints_welder') {
            openJointWidget(e.target, e.e);
        }
    }
});

// Hover handler for existing joints
fabricCanvas.on('mouse:over', (e) => {
    if (e.target && e.target.shapeId && hasExistingData(e.target.shapeId)) {
        showHoverTooltip(e.target);
    }
});

2.2 Widget Data Binding

Goal: Connect widget form with shape data

Tasks:

• Load shape data into widget form
• Save widget data to temporary storage
• Update shape label display (joint no, welder ID)
• Handle form field changes (real-time updates)
• Implement cancel/close behavior

Best Practices:

• Use two-way data binding pattern
• Implement reactive updates (update shape when form changes)
• Add unsaved changes warning
• Use event-driven architecture

Files to Modify:

• resources/views/admin/type/pdf-editor.blade.php
• resources/views/components/modals/joint-widget-modal.blade.php

---

Phase 3: API Development & Database Integration (Week 2)

3.1 API Endpoints for Joint Data

Goal: Create RESTful API endpoints for joint operations

Tasks:

• Create saveJointData endpoint (already exists, enhance)
• Create getJointData endpoint
• Create checkExistingWeldmapData endpoint (already exists)
• Create getQualifiedWelders endpoint
• Create getICLogMembers endpoint (already exists)
• Create getICLogMemberDetails endpoint (already exists)

Best Practices:

• Use Laravel Resource classes for consistent responses
• Implement proper validation rules
• Add error handling and logging
• Use database transactions for data integrity
• Implement rate limiting for API calls

Files to Create/Modify:

• app/Http/Controllers/Api/AnnotationController.php (enhance existing)
• app/Http/Controllers/Api/PdfEditorLookupController.php (enhance existing)
• routes/web.php (add routes if needed)

3.2 Base Weldmap Integration

Goal: Insert/update joint data in Base Weldmap

Tasks:

• Map widget form data to weld_logs table structure
• Implement insert logic for new joints
• Implement update logic for existing joints
• Handle field mapping (widget → database)
• Add validation for required fields
• Implement batch insert for multiple joints

Database Mapping:

Widget Field → weld_logs Column
- joint_no → no_of_the_joint_as_per_as_built_survey
- type_of_joint → type_of_joint (F/S)
- welding_date → welding_date
- spool_no1 → spool_number_1
- spool_no2 → spool_number_2
- pose_no1 → pose_number_1
- pose_no2 → pose_number_2
- member1 → member_1
- member2 → member_2
- material → material_1, material_2
- dia1 → dia_1
- dia2 → dia_2
- nps1 → nps_1
- nps2 → nps_2
- thickness1 → thickness_1
- thickness2 → thickness_2
- welder_id1 → welder_1
- welder_id2 → welder_2

Best Practices:

• Use Eloquent models for database operations
• Implement database transactions
• Add rollback on error
• Use bulk insert for performance
• Validate data before database operations

Files to Modify:

• app/Http/Controllers/Api/AnnotationController.php
• app/Models/WeldLog.php (if needed)

3.3 Weldlog Integration

Goal: Update welder assignments in Weldlog

Tasks:

• Implement welder assignment update logic
• Handle real_welder_1 and real_welder_2 fields
• Update joint display on PDF after assignment
• Validate welder qualifications before assignment

Best Practices:

• Use updateOrCreate for idempotent operations
• Implement soft validation (warnings, not errors)
• Add audit trail for welder changes
• Use database transactions

Files to Modify:

• app/Http/Controllers/Api/AnnotationController.php
• app/Models/WeldLog.php

---

Phase 4: Two-Way Data Synchronization (Week 2-3)

4.1 Data Existence Check

Goal: Check if Base Weldmap/Welder data exists but drawing is missing

Tasks:

• Create API endpoint to check data existence
• Implement left panel activation logic
• Create Spool No dropdown population
• Create Joint No dropdown (filtered by Spool)
• Create Welder ID dropdown (filtered by Joint)

API Endpoint:

GET /api/pdf-editor/check-existing-weldmap
Query: drawing_number
Response: {
    has_data: true/false,
    spools: [...],
    joints: [...],
    welders: [...]
}

Best Practices:

• Cache API responses for performance
• Implement pagination for large datasets
• Use eager loading for relationships
• Add loading states in UI

Files to Create/Modify:

• app/Http/Controllers/Api/PdfEditorLookupController.php
• resources/views/admin/type/pdf-editor.blade.php (left panel)

4.2 Drawing Generation from Data

Goal: Generate PDF drawing shapes from existing database data

Tasks:

• Implement shape creation from joint data
• Position shapes based on joint relationships
• Add welder labels if welder data exists
• Handle F/S shape selection
• Update annotation storage

Best Practices:

• Use Fabric.js for shape creation
• Implement smart positioning algorithm
• Add collision detection
• Use canvas grouping for related shapes

Files to Modify:

• resources/views/admin/type/pdf-editor.blade.php

---

Phase 5: Document Revision Integration (Week 3)

5.1 Save to Spool Iso

Goal: Save annotated PDF to Document Revision "Spool Iso"

Tasks:

• Implement PDF export with annotations
• Save to Document Revision pdf_spool_iso column
• Update revision metadata
• Handle versioning

Best Practices:

• Use existing PDF export functionality
• Implement async save operation
• Add progress indicator
• Handle save errors gracefully

Files to Modify:

• app/Http/Controllers/Api/AnnotationController.php
• app/Http/Controllers/Api/PdfEditorLookupController.php (updateDocumentStage)

5.2 Save to As-Build

Goal: Save annotated PDF to Document Revision "As-Build"

Tasks:

• Similar to Spool Iso but for pdf_as_build column
• Include welder information in saved PDF
• Update revision metadata

Files to Modify:

• Same as 5.1

---

Phase 6: Welder Qualification Filtering (Week 3)

6.1 Welder Qualification System

Goal: Filter welders based on qualifications and validity

Tasks:

• Integrate with existing Welder Assignment system
• Implement qualification filtering logic
• Check welder expiry dates
• Filter by material compatibility
• Filter by welding method

Best Practices:

• Reuse existing welder assignment logic
• Cache qualification data
• Implement client-side filtering for performance
• Add server-side validation

Files to Modify:

• app/Http/Controllers/Api/PdfEditorLookupController.php
• app/Http/Controllers/AutoCompleteType/welder-assignment/welder_1.php (reference)

---

🔧 Technical Architecture

Frontend Architecture

PDF Editor Canvas (Fabric.js)
    ↓
Shape Event Handlers
    ↓
Joint Data Manager (Temporary Storage)
    ↓
Widget Modal (Form)
    ↓
API Calls (AJAX)
    ↓
Backend Controllers
    ↓
Database (weld_logs, annotations, document_revisions)

Data Flow

Scenario 1: New Joint Creation

User draws shape → Widget opens → User fills form → 
Data stored in memory → User clicks Save → 
Batch insert to weld_logs → Save PDF to Document Revision

Scenario 2: Welder Assignment

User hovers joint → Widget opens (pre-filled) → 
User selects welders → Update memory → 
User clicks Save → Update weld_logs → 
Update PDF display → Save PDF to Document Revision

Scenario 3: Drawing from Data

Check data exists → Activate left panel → 
User selects Spool → Joints list → 
User selects Joint + Shape → Create shape on PDF → 
Save PDF to Document Revision

---

📚 Best Practices & Recommendations

1. Temporary Data Storage

Option A: In-Memory (Recommended)

• Use JavaScript Map/Object for fast access
• Store in component state
• Clear on page unload
• Pros: Fast, no persistence needed
• Cons: Lost on page refresh

Option B: SessionStorage

• Use browser sessionStorage API
• Survives page refresh
• Auto-clears on tab close
• Pros: Persistence
• Cons: Limited size, string serialization

Recommendation: Use in-memory storage with sessionStorage backup

class JointDataManager {
    constructor() {
        this.data = new Map();
        this.loadFromSession();
    }
    
    save(shapeId, jointData) {
        this.data.set(shapeId, jointData);
        this.saveToSession();
    }
    
    saveToSession() {
        const data = Object.fromEntries(this.data);
        sessionStorage.setItem('jointData', JSON.stringify(data));
    }
    
    loadFromSession() {
        const stored = sessionStorage.getItem('jointData');
        if (stored) {
            const data = JSON.parse(stored);
            this.data = new Map(Object.entries(data));
        }
    }
}

2. Widget Positioning

Option A: Fixed Position (Current)

• Modal in center of screen
• Pros: Simple, consistent
• Cons: May cover important content

Option B: Dynamic Positioning (Recommended)

• Position near clicked shape
• Calculate based on shape coordinates
• Pros: Better UX, doesn't cover content
• Cons: More complex

Recommendation: Use dynamic positioning with fallback to center

function calculateWidgetPosition(shape, canvas) {
    const shapeBounds = shape.getBoundingRect();
    const canvasOffset = canvas.getElement().getBoundingClientRect();
    
    const x = canvasOffset.left + shapeBounds.left + shapeBounds.width;
    const y = canvasOffset.top + shapeBounds.top;
    
    // Check if fits on screen
    const windowWidth = window.innerWidth;
    const windowHeight = window.innerHeight;
    const widgetWidth = 600; // Modal width
    const widgetHeight = 500; // Estimated modal height
    
    let finalX = x;
    let finalY = y;
    
    if (x + widgetWidth > windowWidth) {
        finalX = x - widgetWidth - 20; // Position to left
    }
    
    if (y + widgetHeight > windowHeight) {
        finalY = windowHeight - widgetHeight - 20;
    }
    
    return { x: finalX, y: finalY };
}

3. API Design

RESTful Endpoints:

POST   /api/pdf-editor/joint-data          - Save joint data
GET    /api/pdf-editor/joint-data/{id}     - Get joint data
PUT    /api/pdf-editor/joint-data/{id}     - Update joint data
DELETE /api/pdf-editor/joint-data/{id}     - Delete joint data
GET    /api/pdf-editor/qualified-welders   - Get qualified welders
GET    /api/pdf-editor/check-weldmap        - Check existing weldmap data

Request/Response Format:

// POST /api/pdf-editor/joint-data
{
    "drawing_number": "CW-800-AH01JL-FA00.001",
    "joints": [
        {
            "shape_id": "J-001",
            "joint_no": "53A",
            "type_of_joint": "F",
            "welding_date": "2025-01-15",
            "spool_no1": "SP01",
            "spool_no2": "SP02",
            // ... other fields
        }
    ]
}

// Response
{
    "success": true,
    "message": "Joint data saved successfully",
    "data": {
        "saved_count": 1,
        "joints": [...]
    }
}

4. Database Transactions

Best Practice: Use database transactions for data integrity

public function saveJointData(Request $request): JsonResponse
{
    DB::beginTransaction();
    
    try {
        foreach ($request->joints as $jointData) {
            WeldLog::updateOrCreate(
                [
                    'iso_number' => $request->drawing_number,
                    'no_of_the_joint_as_per_as_built_survey' => $jointData['joint_no'],
                ],
                [
                    // ... field mappings
                ]
            );
        }
        
        DB::commit();
        return response()->json(['success' => true]);
    } catch (\Exception $e) {
        DB::rollBack();
        Log::error('Failed to save joint data', ['error' => $e->getMessage()]);
        return response()->json(['success' => false, 'message' => $e->getMessage()], 500);
    }
}

5. Welder Qualification Filtering

Integration with Existing System:

• Reuse welder_1.php autocomplete logic
• Filter by material compatibility (MaterialGroupMap)
• Filter by welding method
• Check expiry dates
• Filter by qualification status

Implementation:

public function getQualifiedWelders(Request $request): JsonResponse
{
    $request->validate([
        'material_1' => 'required|string',
        'material_2' => 'required|string',
        'welding_method' => 'required|string',
        'joint_type' => 'nullable|string',
    ]);
    
    // Use existing welder assignment logic
    $qualifiedWelders = $this->filterQualifiedWelders(
        $request->material_1,
        $request->material_2,
        $request->welding_method
    );
    
    return response()->json([
        'success' => true,
        'data' => $qualifiedWelders
    ]);
}

6. Performance Optimization

Client-Side:

• Debounce API calls (300ms)
• Cache API responses
• Use virtual scrolling for large lists
• Lazy load widget modal
• Use requestAnimationFrame for animations

Server-Side:

• Use database indexes
• Implement query caching
• Use eager loading for relationships
• Implement pagination
• Use database transactions efficiently

7. Error Handling

Client-Side:

async function saveJointData(jointData) {
    try {
        const response = await fetch('/api/pdf-editor/joint-data', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'X-CSRF-TOKEN': csrfToken
            },
            body: JSON.stringify(jointData)
        });
        
        const result = await response.json();
        
        if (!result.success) {
            throw new Error(result.message || 'Failed to save joint data');
        }
        
        return result;
    } catch (error) {
        console.error('Error saving joint data:', error);
        Swal.fire('Error', error.message, 'error');
        throw error;
    }
}

Server-Side:

try {
    // ... operation
} catch (ValidationException $e) {
    return response()->json([
        'success' => false,
        'message' => 'Validation failed',
        'errors' => $e->errors()
    ], 422);
} catch (\Exception $e) {
    Log::error('Joint data save failed', [
        'error' => $e->getMessage(),
        'trace' => $e->getTraceAsString()
    ]);
    
    return response()->json([
        'success' => false,
        'message' => 'An error occurred while saving joint data'
    ], 500);
}

---

🧪 Testing Strategy

Unit Tests

• JointDataManager class methods
• API endpoint validation
• Database operations
• Data mapping functions

Integration Tests

• Widget open/close flow
• Data save/load cycle
• API endpoint integration
• Database transaction rollback

E2E Tests

• Complete joint creation flow
• Welder assignment flow
• Drawing generation from data
• Document Revision save

---

📝 Implementation Checklist

Phase 1: Foundation

• Create JointDataManager class
• Enhance joint widget modal
• Add IC Log member selection
• Implement auto-fill logic

Phase 2: Integration

• Add shape click handlers
• Implement widget positioning
• Connect widget to data manager
• Update shape labels

Phase 3: Backend

• Enhance saveJointData endpoint
• Create getQualifiedWelders endpoint
• Implement Base Weldmap integration
• Implement Weldlog integration

Phase 4: Two-Way Sync

• Create check-existing-weldmap endpoint
• Implement left panel activation
• Create drawing from data
• Handle welder display

Phase 5: Document Revision

• Implement Spool Iso save
• Implement As-Build save
• Add versioning support

Phase 6: Welder Filtering

• Integrate qualification system
• Implement material filtering
• Add expiry date checking

---

🚀 Next Steps

1. Review and approve roadmap
2. Set up development branch: feature/pdf-editor-step3-joint-widget
3. Start with Phase 1: Foundation & Data Structure
4. Iterative development: Test each phase before moving to next
5. Code review: After each phase completion

---

📖 References

• Existing Code:

  • app/Http/Controllers/Api/AnnotationController.php
  • app/Http/Controllers/Api/PdfEditorLookupController.php
  • resources/views/components/modals/joint-widget-modal.blade.php
  • app/Http/Controllers/AutoCompleteType/welder-assignment/welder_1.php

• Database Tables:

  • weld_logs - Main joint and welder data
  • annotations - PDF shape data
  • document_revisions - PDF file storage
  • incoming_control - IC Log member data
  • material_group_map - Material compatibility
  • welder_tests - Welder qualifications

---

Document Version: 1.0
Last Updated: 2025-01-XX
Author: Development Team