Raporlama ve Dışa Aktarım

Bu bölüm, Mikrofab ölçüm ve analiz yazılımının ürettiği rapor ve dışa aktarım (export) çıktılarının tamamını kapsar: bir ölçümün nasıl izlenebilir, makine-okunur ve kurcalama-belirtili (tamper-evident) bir kayda dönüştüğünü, bu kayıttan hangi sunum biçimlerinin (HTML/PDF) türetildiğini, hangi tablo biçimlerinin (CSV/TXT/XLSX/JSON) yazıldığını ve dosyaların nasıl adlandırıldığını ayrıntılarıyla anlatır.

1. Genel Bakış: Üç Rapor Yolu

Yazılım, üç ayrı yerden rapor/çıktı üretir. Hepsi aynı disiplini (künye + sha256 bütünlük + "eksik != sıfır" + belirlenimci çıktı) paylaşır ama farklı amaçlara hizmet eder.

Mimari olarak akış şudur:

                          +- write_json  (kanonik, makine-okunur, checksum kaynağı)
   rapor sözlüğü ---------+- write_csv   (tablo)              -- VERİ biçimi
   (build_report / compose)
                          +- build_report_html (kaçışlı/escaped) -- SUNUM (veriden türetilir)
                                                                    PDF: Qt QTextDocument

Rapor motoru bu deponun içinde, app/reporting/ altında yaşar; paylaşılan harici bir reporting paketi yoktur. Çekirdek dosyalar:

• app/reporting/report_model.py — kanonik ölçüm raporu modeli + JSON/CSV yazıcılar.
• app/reporting/report_builder.py — saf HTML üretici (build_report_html).
• app/reporting/analysis_report.py — analiz raporu (künye + payload, aynı mühür disiplini).
• app/reporting/report_compose.py — birden çok kaynağı birleştiren Rapor Oluşturucu motoru.
• app/reporting/report_index.py — üretilmiş raporları tarayıp listeleyen indeks (DB'siz).
• app/storage/data_writer.py — ölçüm sırasında/sonunda ham + rapor dosyalarını yazan katman.
• app/gui/analyze/exporters.py — Analiz çalışma alanı dışa aktarım yazıcıları.

2. Ölçüm Raporu (Otomatik, Her Kayıtta)

Bir ölçüm tamamlandığında DataWriter.save(...) çağrılır ve tek koşu için tüm dosyalar o koşuya ait alt klasöre yazılır. Bu, yazılımın "varsayılan" rapor üreticisidir: kullanıcı ekstra bir düğmeye basmadan, her ölçüm izlenebilir bir kayıt olarak diske düşer.

2.1 Koşu klasörü ve dosya adlandırma

Her ölçüm koşusu, çıktı klasörü altında kendi alt klasörüne yazılır. Klasör adı run_folder_name(...) ile üretilir:

<çıktı_klasörü>/YYYY-MM-DD-<Gün>-<Tür>-<HHMMSS>/
örnek: measurements/2026-06-12-Wed-PV-103045/

Klasör içindeki dosyaların temel adı (base_name) şudur:

<önek>_<TFT>_<MOD>_<YYYYMMDD_HHMMSS>_<sonek>

Önek (filename_prefix) ve sonek (filename_suffix) boş ise atlanır; yasak dosya karakterleri (<>:"/\|?* ve kontrol karakterleri) sanitize_token ile temizlenir.

2.2 Yazılan dosyalar

DataWriter.save varsayılan olarak şu biçimleri yazar (export_formats ile ayarlanır; öntanımlı ("csv", "txt", "xlsx") + her zaman rapor + metadata):

Ham veri CSV/TXT/XLSX şu 13 sütunu (CSV_COLUMNS) taşır:

timestamp, measurement_mode, tft_id, sweep_direction, step_index,
vds_set, vgs_set, vds_measured, vgs_measured, ids, igs, compliance_hit, elapsed_s

2.3 Kanonik rapor (*_report.json) — Künye / İzlenebilirlik

Kanonik rapor, report_model.build_report(...) ile üretilir ve üç-seviyeli izlenebilirlik künyesini (künye = traceability header) taşır. Aşağıdaki tablo, raporun üst düzeyindeki alanları ve kaynağını gösterir.

2.4 Kolon aileleri — ölçüme göre doğru şema

Önemli bir tasarım kararı: rapor tablosunun kolonları ölçüm ailesine göre seçilir. Eski sürümlerde tek sabit şema TFT-şekilliydi (Vds/Vgs/Ids/Igs); bir güneş hücresi raporu bu yüzden "transistör raporu" gibi görünür, Vgs/Igs hep 0 çıkardı. Artık her aile kendi kolonlarını seçer; tüm yazıcılar (JSON/CSV/HDF5) report["columns"]'u kullandığından otomatik olarak doğru şema biner.

Tüm ailelerde ortak baş/kuyruk kolonları: point (tam sayı), step_index, sweep_direction, elapsed_s (s), status. Birim ve tip kolon tanımında durur, satırda tekrarlanmaz (tek kaynak); etiket yereli label_key üzerinden i18n'den gelir.

Türetilmiş kolon formülleri:

2.5 Satırlar ve durum (status) — "Eksik != sıfır"

_point_to_row(...) her MeasurementPoint'i bir satıra çevirir. Sayısal olmayan / NaN / Inf değerler null'a (asla 0'a değil) eşlenir. Her satırın status alanı:

"rows": [
  { "point": 1, "vds_set": 0.0, "ids": 1.2e-6, "igs": 1e-9, "status": "ok"   },
  { "point": 2, "vds_set": 0.1, "ids": null,   "igs": null, "status": "na"   },  // eksik != 0
  { "point": 3, "vds_set": 0.2, "ids": 2.0e-3, "igs": 1e-9, "status": "fail" }   // compliance
]

2.6 Bütünlük (integrity / checksum)

Her kanonik rapor bir sha256 özeti taşır; böylece dosya sonradan değiştirilirse anlaşılır (kurcalama-belirtili).

girdi  : rapor sözlüğü (integrity.value = "" yapılmış hâli)
formül : sha256( kanonik_json(rapor) )   // sort_keys=True, ensure_ascii=False, kompakt
çıktı  : integrity = { "algo": "sha256", "value": "<64-hex>" }

write_json, dosyayı yazmadan önce seal_integrity(...) çağırır; bu yüzden diskteki JSON mühürlü değeri taşır. Checksum, kendine referans olmadan hesaplanır (önce value boş bırakılır). Aynı rapor → bayt-aynı çıktı → aynı checksum.

3. Ölçüm Raporu — HTML ve PDF Sunumu ("Rapor Oluştur")

Kanonik JSON/CSV makine içindir; insana yönelik tek parça HTML rapor (ve mümkünse PDF) ölçüm sonucu ekranında "Rapor oluştur" düğmesiyle üretilir (_generate_report). Bu sunum, kanonik nesnenin görünür hâlidir.

3.1 Rapor yapısı (bölümler)

Üretilen HTML/PDF şu sırayla bölümlerden oluşur (build_report_html):

1. Başlık bloğu — Rapor başlığı (ör. "TFT Ölçüm Raporu"), alt başlık (<TFT> — <Mod>) ve üretim zamanı (generated_at).
2. Grafik — Mevcut ölçüm grafiği PNG olarak gömülür (işaretçiler dahil). HTML'de base64 data: URI; PDF'te QTextDocument.addResource ile plot.png kaynağı olarak.
3. Ölçüm Koşulları tablosu — Mod, TFT kimliği, cihaz IDN, VISA kaynağı, kanallar (drain/gate), röle durumu, nokta sayısı, yazılım sürümü; ardından sweep parametreleri ve (varsa) açık-hava ortam satırları.
4. Çıkarılan Parametreler tablosu — Mod-bilen cilalı etiketler (Voc/Isc/FF/PCE, Vth, Ion/Ioff…). Özel üretici yoksa ham özet (summary) dökümüne düşülür. Bu tablo, Sonuç sayfasıyla tek kaynak (summary_format) kullanır; raporda gördüğünüz sayılar ekrandaki sayılarla birebir aynıdır.
5. Kullanıcı Notu — user_comment varsa serbest metin kutusu.
6. Alt bilgi — Yazılım sürümü damgası.

3.2 Çıktı dosyaları ve adlandırma

"Rapor oluştur" iki dosya yazar (çıktı klasörüne doğrudan, koşu alt klasörüne değil):

<TFT>_<MOD>_<YYYYMMDD_HHMMSS>_report.html
<TFT>_<MOD>_<YYYYMMDD_HHMMSS>_report.pdf

• HTML: Grafik base64 gömülü olduğundan tek dosya taşınabilir, tarayıcıda açılır.
• PDF: Qt QTextDocument → QPrinter ile üretilir; ek bağımlılık yoktur. Grafik plot.png kaynağı olarak gömülür.

4. Analiz Raporu (Analiz Çalışma Alanı — "Dışa Aktar" Menüsü)

Analiz çalışma alanında bir analiz çözüldükten sonra, üst çubuktaki "Dışa Aktar" (analyze2.header.export) düğmesi bir menü açar. Menü içeriği, aktif analiz modülünün tanımlayıcısının (descriptor) desteklediği biçimlerle uygulanan biçimlerin kesişimidir.

4.1 Dışa aktarım menüsü seçenekleri

4.2 Analiz raporu (report_json / report_pdf) yapısı

Analiz raporu build_analysis_report(...) ile üretilir; ölçüm raporuyla aynı künye disiplinini taşır ve report_model'in mühür/checksum/write_json işlevlerini yeniden kullanır (yani JSON bayt-kararlı ve bütünlük mühürlüdür). Üst düzey alanlar:

analysis payload'ı (Qt'siz, dile-bağımsız; etiketler i18n anahtarı olarak tutulur):

• descriptor — Analiz modülü kimliği, sürümü, kategori, başlık/özet anahtarları, motor.
• metrics[] — Her metrik için ham GUM alanları + biçimlenmiş gösterim: {key, label_key, unit, value, u_std, k, n, r2, display, primary}. Değer yoksa value=null, display="—".
• method — {description_key, equations[], conventions[], fit_method}. Denklemler düz-metin (plain) + not olarak taşınır; konvansiyonlar i18n anahtarıdır.
• standards[] — Atıf yapılan standartlar: {id, designation, title, edition, scope} (registry'den çözülür).
• reliability — Kalite hükmü: ✓ Güvenilir (reliable) / ✕ Güvenilir değil (unreliable) / ⚠ STC dışı (non_stc).
• provenance — Köken/iz zarfı: {data_file, file_hash, column_mapping, parameters, software_version, timestamp_utc}.
• narrative, notes[], conditions[] — Anlatı, notlar ve descriptor'ın gerektirdiği koşul jetonları.

4.3 Belirsizlik gösterimi (Quantity / GUM)

Analiz metrikleri, GUM (Ölçüm Belirsizliğinin İfadesi Kılavuzu) çizgisinde bir Quantity nesnesi üzerinden biçimlenir (format_quantity). Gösterim kuralları:

• Genişletilmiş belirsizlik: U = k · u_std (k = kapsam çarpanı / coverage factor).
• Veri dosyalarında (JSON/Excel) ham alanlar (value, u_std, k, n) ayrı ayrı tutulur; biçimlenmiş display yalnız kolaylık içindir.

4.4 Excel dışa aktarımı (write_metrics_xlsx)

Analiz Excel çıktısı iki sayfa içerir:

1. "Metrics" — Sütunlar: metric, value, unit, u_std, n, display, reliability. Her descriptor metriği için bir satır; Quantity yoksa değer boş, display="—".
2. "Provenance" — Köken zarfı anahtar/değer: data_file, file_hash, software_version, timestamp_utc, ayrıca JSON olarak column_mapping ve parameters.

5. Birleştirme Raporu (Veri ve Raporlar Çalışma Alanı)

Tekil ölçüm/analiz raporlarının ötesinde, Veri ve Raporlar çalışma alanı (workspace) birden çok kaynağı tek bir profesyonel rapora birleştiren bir Rapor Oluşturucu sunar. Motor report_compose.py'dir: saf, Qt'siz; yukarıdaki yazıcıların üzerine yeni bir yazıcı eklemez.

5.1 Çalışma alanı sekmeleri

5.2 Rapor Oluşturucu — üç sütunlu akış

Rapor Oluşturucu üç sütundan oluşur (sürükle-bırak alan kuyusu yoktur; kolon aileleri belirlenimcidir):

Sütun 1 — Kurulum:

Sütun 2 — İçerik: Seçili kaynağa göre ya seçili ölçüm onay-kutu listesi ya da Lab Defteri numune seçici (üretim adımları + bağlı ölçümler). Altında bölüm onay-kutuları.

Sütun 3 — Canlı önizleme: Seçimler değiştikçe report_compose.compose(...) ile üretilen HTML anında önizlenir (önizleme asla çökmez; hata olursa kırmızı mesaj gösterir).

5.3 Rapor bölümleri

5.4 Lab Defteri köprüsü (şema değişikliği olmadan bağlama)

Rapor Oluşturucu, ölçümleri Lab Defteri numuneleriyle yeni bir tablo eklemeden bağlar. Bağlantı alanları: samples.sample_id == measurements.tft_id ve sample_steps.linked_measurement_id. Üç-sıçramalı köprü:

1. get_sample(sample_db_id) → sample_id.
2. Geniş havuz: measurement_db.query(tft_id=sample_id).
3. "Çağrılan" küme: adımların linked_measurement_id değerleri (birleşim, id'ye göre tekil).

5.5 Çıktı dosyaları ve kanonik JSON

"Oluştur" → report_compose.write(...) seçili biçimlerde yazar. Dosya kök adı: <numune_id veya şablon>_rapor (yasak karakterler temizli).

Kanonik JSON ek olarak şu izlenebilirlik alanlarını taşır: report_type="composed", source (type, sample_id, measurement_ids, step_ids), source_sha256 ve measurements_sha256 (bayatlık alt-özeti), sections[], özetlenmiş sample ve measurements. Belirlenimci: sabit created_at + report_id → bayt-aynı çıktı.

5.6 Raporlar kitaplığı ve "bayatlık" (stale)

"Raporlar" sekmesi, çıktı klasörünü veritabanısız tarar: report_index.list_reports(...) her *_rapor.json'i (yalnız report_type=="composed") okuyup künye + üretilmiş kardeş biçimleri (pdf/html/csv) listeler. Bir satıra çift-tıklamak veya "Aç", raporu varsayılan uygulamada açar (öncelik sırası: PDF > HTML > JSON).

5.7 İstatistik sekmesi (topluluştırma)

"Veritabanı / İstatistik" sekmesi, seçili bir numunenin (tft_id) tüm ölçümlerinde çıkarılan parametreleri topluluştırır (benchtop SPC/dağılım karşılığı):

Ort (mean) = Σxᵢ / n
σ (örnek std, n-1) = sqrt( Σ(xᵢ − Ort)² / (n − 1) )   // n>1; n=1 ise σ=0
min, max, n

None/NaN değerler hariç tutulur; n=0 ise tüm istatistikler — (eksik != 0). "Seçimden rapor" düğmesi, o numuneyle Rapor Oluşturucu'yu açar.

6. Dışa Aktarım Biçimleri (Referans)

Bu bölüm, tüm biçimleri tek yerde toplar.

6.1 Kanonik CSV (makine biçimi)

Yerelden bağımsız, tek ve belgeli biçim (report_model.write_csv / exporters.write_dataset_csv):

• Kodlama UTF-8 + BOM (utf-8-sig — Excel'in doğru açması için), nokta ondalık, virgül ayraç, satır sonu \n.
• Başlıklar kararlı key + birim (ör. ids_A, vds_set_V), asla yerelleştirilmez.
• Eksik nokta → boş hücre (""); 0 asla yazılmaz. na/fail/ok ayrımı status sütununda durur.
• CSV yalnız tabloyu taşır; künye + checksum yoldaş JSON dosyasında durur.

point,step_index,sweep_direction,vds_set_V,vgs_set_V,vds_measured_V,vgs_measured_V,ids_A,igs_A,elapsed_s_s,status
1,0,Forward,0.0,0.0,0.0,0.0,1.2e-6,1e-09,0.01,ok
2,0,Forward,0.1,0.0,,,,,0.02,na

6.2 Excel-uyumlu CSV (kolaylık kopyası)

write_dataset_csv_excel — Türkçe/Avrupa yerelli Excel için:

6.3 TXT (sekme ayraçlı)

<base>.txt — ham ölçüm tablosunun sekme (tab) ayraçlı sürümü; aynı 13 sütun, UTF-8. Gnuplot/Origin gibi araçlara hızlı yapıştırma için pratiktir.

6.4 XLSX (Excel çalışma kitabı)

İki yol vardır:

• Ham ölçüm (DataWriter._write_xlsx): "measurement" sayfası (13 sütun) + mod-bilen "Özet" sayfası (etiket/değer). openpyxl yoksa, bağımlılıksız minimal bir XLSX (doğrudan zip + XML) yazılır (_write_minimal_xlsx) — yani Excel çıktısı her ortamda üretilir.
• Analiz metriği (write_metrics_xlsx): "Metrics" + "Provenance" sayfaları (Bölüm 4.4).

6.5 JSON metadata vs kanonik JSON

İki farklı JSON karıştırılmamalıdır:

metadata.json şu alanları içerir: device_identity (IDN/VISA/switch_port), relay_enabled, selected_tft, sweep_parameters, date_time, started_at, user_comment, software_version, smu_mapping (drain/gate), point_count, planned_point_count, stopped_early, compliance_hit ve (varsa) <mod>_summary.

6.6 PNG (grafik görüntüsü)

Grafikler PNG olarak dışarı verilir:

• Ölçüm raporu: Grafik 150 DPI'de PNG'ye render edilir ve HTML'e base64, PDF'e plot.png kaynağı olarak gömülür.
• Analiz: "Dışa Aktar → PNG" ile aktif grafik doğrudan PNG dosyasına yazılır (plot_canvas.export_png).

Üretilen rapor dosyaları, kaynağı belli olacak biçimde adlandırılır: ölçüm raporları <TFT>_<MOD>_<tarih>_<saat>_report.json / _report.csv, birleştirme raporları ise *_rapor.json kalıbını izler. Böylece her çıktı, hangi ölçüm veya oturumdan türediğini adından okutur.

6.7 Dosya adlandırma sözleşmesi — özet

7. Belirlenimcilik, Yerel Tuzağı ve Seviyeler

7.1 Belirlenimcilik (her yazıcının uyduğu kural)

• Aynı girdi → bayt-aynı çıktı. _canonical_json, sort_keys=True, ensure_ascii=False ve kompakt ayraçlar kullanır; payload'da gizli duvar-saati yoktur — created_at çağırandan gelir. Bit-aynı çıktı isteyen bir çağıran sabit created_at + sabit report_id geçirir.
• Yerelden bağımsız veri. JSON/CSV sayıları sayı tipindedir, nokta-ondalık kullanır. Yalnız HTML/PDF insan gösterimi yerelleştirilir.
• Kaçışlı HTML. build_report_html her dinamik değeri html.escape'ten geçirir.

7.2 Seviye → zorunlu alan eşlemesi

7.3 Şu an PLANLANAN olanlar

Aşağıdakiler sözleşmede tanımlı ancak henüz uygulanmamıştır; rapor bunları iddia etmez:

• Yerli .xlsx rapor yazıcısı ve arşivlik PDF/A profili (şu an PDF, HTML'den Qt yoluyla üretilir).
• Ölçüm metrikleri için GUM Tip-B belirsizlik kolonu (ölçüm DB'si çıplak skaler taşır; belirsizlik analiz-kit Quantity yolunda yaşar).
• Seviye-2 belirsizlik bütçesi, kalibrasyon sertifikası ve imza zinciri (ör. PDF için PAdES); calibration ve signoff şu an stub.
• Büyük/toplu raporlar için arka-plan iş parçacığı üretimi.

8. Standart Atıfları

Bu bölümdeki davranışlar repo-içi sözleşme ve standartlara dayanır:

• docs/standards/06-reporting.md — Raporlama standardı (belirlenimcilik, checksum, üç-seviyeli künye, yerel tuzağı, "eksik != sıfır", otomatik-iletim yasağı).
• docs/guides/reporting-guide.md — Somut sözleşme: kanonik JSON iskeleti, kolon tanımları, CSV konvansiyonu, yazıcı sözleşmesi, birleştirme raporu (report_compose).
• docs/standards/03-measurement-and-analysis.md — Sonuç + R² + belirsizlik.
• docs/standards/05-data-and-database.md — Saklanan veri / NULL disiplini.
• docs/standards/12-i18n-l10n.md — Yerel/dil ayrımı.
• Analiz standartları (atıf): Analiz raporları, modül tanımlayıcısındaki standards[] üzerinden ilgili ölçüm standardını (designation/title/edition/scope) taşır.

9. Hızlı Başvuru ve Sık Sorulanlar

Bir ölçümün resmî kaydı hangi dosyadır?

<base>_report.json (kanonik, sha256 mühürlü). İnsana yönelik sunum bundan türetilir.

Excel dosyam virgüllü sayıları bozuk gösteriyor, ne yapmalıyım?

"CSV (Excel uyumlu)" varyantını kullanın (Bölüm 6.2) veya XLSX'i tercih edin. Arşiv için daima kanonik CSV (nokta-ondalık) saklayın.

Raporda bir değer neden boş/— görünüyor?

O nokta ölçülemedi (status="na") veya metrik hesaplanamadı. Yazılım asla eksik değeri 0 ile doldurmaz (eksik != sıfır).

"bayat" rozeti ne anlama gelir?

Rapor üretildikten sonra kaynak ölçümler değişmiş/silinmiştir. Güncel sayılar için raporu yeniden üretin; mevcut rapor mühürlü bir anlık görüntü olarak kalır.

İki dosyanın aynı ölçümden geldiğini nasıl doğrularım?

integrity.value (sha256) ile. Aynı rapor sözlüğü daima aynı özeti verir; dosya değiştiyse özet tutmaz.

PDF neden bazen üretilmiyor?

PDF, Qt (QTextDocument → QPrinter) ile üretilir; Qt yoksa veya yazma hatası olursa yazıcı sessizce atlar ve en azından HTML/JSON korunur (sağlam üretim ilkesi).