citrus-cms/resources/views/guide/mechanical-overview.md

## Mechanical Controls – Consolidated Guide

### 1. Amaç ve Kapsam
- **Hedef:** BJ/FJ/TH/CJ gibi mekanik eklemler, tüm modüllerde (Weldlog, Weldmap, Repair Log, NDT/Spool/Paint süreçleri, register & cron görevleri) kaynaklı sayımları, SUM/AVG hesaplarını ve senkronizasyonları etkilemesin.
- **Veri Kaynağı:** `weld_logs.type_of_welds` alanı; `JointTypeService` üzerinden `weldedTypes` / `mechanicalTypes` listeleri.
- **Temel Strateji:** Tüm sorguların `apply_welded_filter()` veya `apply_mechanical_filter()` yardımıyla aynı servis katmanına bağlanması + DevExtreme gridlerinde `weldedOnly` özetleri.

### 2. Mimari Özeti
| Katman | Dosyalar | İşlev |
| --- | --- | --- |
| Servis & Helper | `app/Services/JointTypeService.php`, `app/Functions/joint_type_helpers.php`, `database/seeders/MechanicalJointTypesSeeder.php` | Ortak tip listeleri, `filterWelded/Mechanical`, `apply_welded_filter()` ve mekanik joint kayıtlarının seed edilmesi |
| DevExtreme çekirdeği | `app/DevExtreme/AggregateHelper.php`, `app/DevExtreme/DbSet.php`, `app/DevExtreme/SummaryContext.php`, `resources/views/components/table/datagrid*.blade.php` | `weldedOnly` SUM/AVG, `type_of_welds` seçimi, mekanik satır davranışı |
| Uygulama ekranları | `resources/views/admin/type/*`, `resources/views/admin-ajax/*` | Gridler + PDF/Excel üretimleri, tamamı helper’ı kullanır |
| Arka plan işlemleri | `resources/views/cron/*.blade.php`, `app/Services/RegisterCreator/*`, `app/Http/Controllers/SaveTrigger/test_pack_base_statuses.php` | NDE, spool, paint, register senkronizasyonlarında mekanik filtreleme |
| Komutlar & dokümantasyon | `app/Console/Commands/*`, `resources/views/guide/*.md` | Otomatik testler, raporlar ve bu kılavuz |

### 3. Ana Davranışlar
1. **Grid Seviyesi**
   - `$enableMechanicalControls` → mekanik satırlar gri, kaynak alanları `readOnly`.
   - `$excludeMechanicalFromSummaries` → DevExtreme `totalItems` için `selector + weldedOnly`.
   - `type_of_welds` kolonu her istekte seçiliyor; `SummaryContext` parametresi (`excludeMechanicalSummary=1`) backend’e iletiliyor.
2. **Sorgu Seviyesi**
   - Tüm `db("weld_logs")` ve `WeldLog::query()` kullanımları `apply_welded_filter()` ile sarıldı; mekanik senaryolar için `apply_mechanical_filter()` mevcut.
   - Cron/SaveTrigger/Register akışlarında da aynı helper kullanıldığından, veritabanı senkronizasyonları mekanik satırı asla tetiklemiyor.

### 4. Test ve Doğrulama
- **Otomatik SUM/AVG kontrolü:**  
  ```
  php artisan mechanical:verify-summaries --columns=nps_1,nps_2,outside_diameter_1,outside_diameter_2,wall_thickness_1,wall_thickness_2
  ```
  Çıktıdaki “SUM (Mechanical)” değerlerinin 0 olması beklenir; sonuçlar `weldlog-mechanical-summary.md` içinde saklanır.
- **Manuel Grid Kontrolü:**  
  - Weldlog/Weldmap/Base Weldmap: Gri `[MECH]` satırları, kilitli kaynak alanları ve doğru footer değerlerini gözlemleyin.  
  - Repair Log, Spool Release, Manage NDT vs.: Şu an yalnızca `count` özetleri kullanıyor; gelecekte SUM/AVG eklerseniz aynı bayrakları aktifleştirin.
- **Regresyon testi:** `php artisan tinker` veya özel SQL scriptleriyle mekanik toplamları karşılaştırın; fark oluşursa ilgili gridde `weldedOnly` konfigürasyonunu doğrulayın.

### 5. Modül Bazında Durum
| Modül / Süreç | Durum | Not |
| --- | --- | --- |
| **Weldlog / Weldmap / Base Weldmap** | SUM/AVG tamamen kaynaklı veriden geliyor; CLI sonuçları dokümante edildi. |
| **Repair Log** | Veri kümesi sadece kaynaklı kayıtlardan oluşuyor; izleme amaçlı tinker komutu hazır. |
| **Spool & Paint akışları** | `spool-status-changer`, `paint-follow-up-updater`, tüm spool-release AJAX’ları helper kullanıyor; mekanik kayıtlar statü/pint süreçlerine girmez. |
| **NDT / Manage NDT / NDT Order** | Gridler sadece `count` özetlerine sahip; veri kaynakları zaten helper’lı. Gelecekte SUM/AVG eklenirse bayraklar açılmalı. |
| **NDE Matrix** | Mekanik satırlar veri bütünlüğü için korunuyor ancak `showMechanicalNdtPlaceholder` sayesinde test alanları otomatik “N/A – Non-Welded Connection” ile etiketleniyor. |
| **Register Creator (QA/WDB)** | Belge tarama ve satır derleme aşamasında sadece kaynaklı kayıtlar okunuyor; gereksiz dosya taramaları engellendi. |
| **Cron Senkronları** | Line list ↔ NDE ↔ weld log, spool, paint, repair senaryoları helper’a geçti; mekanik satırlar arka planda yok sayılıyor. |

### 6. Bakım Kontrol Listesi
1. Yeni bir ekran/cron yazarken `db("weld_logs")` kullanacaksanız ilk satıra `apply_welded_filter()` koyun.
2. DevExtreme gridine SUM/AVG eklerken:
   - `$enableMechanicalControls = true`, `$excludeMechanicalFromSummaries = true`, `$alwaysSelectColumns[] = 'type_of_welds'`.
   - `totalItems` için `selector` + `weldedOnly: true` atamayı unutmayın.
3. Tip listeleri değişirse `php artisan cache:clear` veya `clear_joint_types_cache()` çağrısını tetikleyin; yeni ortam kurulurken `php artisan db:seed --class=MechanicalJointTypesSeeder` çalıştırmayı unutmayın.
4. Rehberleri (bu dosya) güncel tutun; yeni kolonlar/testler eklendikçe tabloya değerleri ekleyin.

> Bu doküman, daha önce yayılan üç ayrı rehberin (DevExtreme davranışları, genel task özeti, SUM/AVG doğrulamaları) birleşik ve sadeleştirilmiş halidir. Tüm mekanik iş mantığına ait tek referans olarak kullanılmalıdır.

### 7. Güncel Dosya Değişiklikleri

| Dosya | Açıklama ve Neden |
| --- | --- |
| `resources/views/components/table/datagrid.blade.php` | DevExtreme gridleri için mekanik satırları gri yapma, kaynak alanlarını `readOnly` tutma ve SUM/AVG hesaplarında `weldedOnly` filtresini uygulama mantığı tek merkezde toplandı. Böylece tüm gridler aynı davranışı otomatik olarak devralıyor. |
| `app/DevExtreme/AggregateHelper.php` & `app/DevExtreme/DbSet.php` | DevExtreme sunucu tarafı sorguları, `weldedOnly` bayrağı geldiğinde mekanik tipleri SQL seviyesinde `CASE WHEN` ile 0/NULL’a çeviriyor. Bu sayede footer SUM/AVG değerleri yalnızca kaynaklı kayıtları kapsıyor. |
| `resources/views/components/table/datagrid/partials/js-data-source.blade.php` & `resources/views/admin/devextreme.php` | Grid isteklerine `excludeMechanicalSummary=1` parametresi eklenip backend’de `SummaryContext` ayarlanıyor; `type_of_welds` kolonunun her sorguda seçilmesi garanti edildi. |
| `resources/views/admin/type/weldlog.blade.php`, `weldmap.blade.php`, `weldmap-fast2.blade.php`, `resources/views/admin/type/weldmap/main.blade.php` | Grid başlatılırken `$alwaysSelectColumns = ['type_of_welds']`, `$excludeMechanicalFromSummaries = true`, `$enableMechanicalControls = true` atandı. Ayrıca `type_of_welds` alanı için dropdown (joint_types + fallback listesi) geri getirildi, böylece mekanik tip seçimi hatasız yapılabiliyor. |
| `resources/views/admin/type/nde-matrix.blade.php` | Mekanik satırlardaki NDT/PWHT kolonları otomatik olarak “N/A – Non-Welded Connection” placeholder’ıyla gösteriliyor; diğer satırlar normal veri taşıyor. |
| `resources/views/admin-ajax/*`, `resources/views/cron/*`, `app/Http/Controllers/SaveTrigger/test_pack_base_statuses.php`, `app/Services/RegisterCreator/*` | Tüm sorgular `apply_welded_filter()` veya `apply_mechanical_filter()` yardımcılarını kullanacak şekilde güncellendi. Böylece mekanik kayıtlar spool, paint, register ve rapor çıktılarında yanlışlıkla hesaplamaya girmiyor. |
| `app/Functions/joint_type_helpers.php`, `app/Services/JointTypeService.php` | Mekanik/kaynaklı tip listeleri cache’lenen servis katmanına taşındı; `apply_welded_filter()` fonksiyonu Eloquent/Query Builder üzerinde aynı mantığı tekrar kullanmamızı sağlıyor. |
| `database/migrations/*`, `database/seeders/MechanicalJointTypesSeeder.php`, `database/seeders/DatabaseSeeder.php` | `joint_types` tablosuna mekanik bayraklar, `weld_logs` tablosuna `fitter_name` alanı eklendi; mekanik tiplerin varlığı garanti altına alındı (lokal ortamlar için seeder). |
| `app/Console/Commands/VerifyMechanicalSummaries.php` | SUM/AVG doğrulaması CLI’dan otomatik çalıştırılabiliyor; rapor çıktıları guide’da saklanıyor. |
| `resources/views/guide/mechanical-overview.md` (bu dosya) | Tüm mimari, test adımları ve değişiklik listesi tek referansta toplandı; sunum/handover sırasında kullanılmak üzere güncel tutuluyor. |

> Yukarıdaki dosyalar dışında listelenen vendor/composer değişiklikleri yeni servis sınıflarını çözümlemek için Composer autoload üretimi sırasında oluştu; ekteki kod yürütmesi için gerekli olup ek müdahale gerektirmiyor.