> ## Documentation Index
> Fetch the complete documentation index at: https://docs.azalt.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Form

> Form yapısını, davranışını ve dağıtımını tanımlar

Formlar; hangi verinin toplanacağını, nasıl doğrulanıp gösterileceğini ve nerede (site) hangi yılda toplanacağını tanımlar. Elementler (alanlar), ayarlar ve meta veriler içerir; site/yıl bazında dağıtılır.

## Form Mimarisi

Formlar birbirine bağlı beş bileşenden oluşur:

* **Form** = Meta veriler, görünürlük ayarları ve dağıtım yapılandırması içeren konteyner
* **FormElement** = Form içindeki bireysel alanlar ve UI bileşenleri
* **FormSite** = Formları belirli site ve yıllara bağlayan dağıtım bağlantıları
* **FormSubmission** = Kullanıcı gönderim oturumu konteyneri
* **FormElementSubmission** = Bireysel alan değerleri ve veri depolama

## Form Ayarları

Her form, `updateForm` çağrısında doğrulanan bir `settings` objesi taşır. Alanların tamamı opsiyoneldir; göndermediğiniz değerler organizasyon varsayılanına veya formdaki mevcut değere geri döner.

### Halka açık gönderim seçenekleri

* `allowPublicSubmissionEdits`: `true` olduğunda halka açık katılımcılar mevcut gönderimlerini (veya taslaklarını) tekrar açıp düzenleyebilir; göndermezseniz platformun varsayılan düzenleme politikası uygulanır.
* `allowPublicSubmissionSupportingDocuments`: Halka açık gönderimlerde destekleyici doküman çekmecesini açar ve kullanıcıların kanıt dosyası yüklemesine izin verir. Tanımsız bırakmak varsayılan belge politikasını korur.

İki alan da opsiyonel boolean değerlerdir; yalnızca payload’a eklendiğinde davranışı değiştirir.

### İş akışı geçersiz kılma

`workflowOverride`, tek bir `type` anahtarına sahip opsiyonel bir objedir. Desteklenen değerler `DIRECT_APPROVAL` ve `REQUIRE_APPROVAL` (aşağıda açıklanan iş akışlarıyla aynı). Nesneyi göndermemek veya `null` iletmek formun organizasyon düzeyindeki varsayılan iş akışını kullanmasını sağlar.

### Planlama ve hatırlatmalar

Farklı periyot türleri için veri girişi ve onay fazlarındaki son tarihleri ve hatırlatma davranışını yapılandırmak üzere `defaultSchedules` kullanın.

#### Form düzeyinde varsayılan planlar

`defaultSchedules` objesi periyot türüne (`MONTHLY`, `QUARTERLY`, `YEARLY`) göre anahtarlanır ve her iş akışı fazı için planlar içerir:

* `dataEntry`: Katılımcı son tarihlerini kontrol eder
* `approval`: Onaylayıcı son tarihlerini kontrol eder

Her plan şunları içerir:

* `dueDate`: Esnek bir son tarih belirtimi (aşağıdaki türlere bakın)
* `reminders`: Opsiyonel hatırlatma yapılandırma bloğu:
  * `enabled`: Hatırlatmaları etkinleştirmek/devre dışı bırakmak için boolean değer
  * `offsets`: Son tarihten kaç gün önce hatırlatma gönderileceğini belirten `{ type: "days-before"; days: number }` nesneleri dizisi. `days` değeri 1-30 aralığında olmalıdır. `enabled` `true` olduğunda zorunludur; `enabled` `false` olduğunda göz ardı edilir.

#### Son tarih belirtim türleri

`dueDate` alanı altı esnek format destekler:

| Tür                  | Açıklama                                                         | Örnek                                                                        |
| -------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `fixed-day`          | Periyodun belirli bir günü (1-31, ay uzunluğuna göre sınırlanır) | `{ type: "fixed-day", day: 15 }`                                             |
| `weekday-occurrence` | Periyodun N. hafta günü (weekday: 0=Paz - 6=Cmt)                 | `{ type: "weekday-occurrence", weekday: 1, occurrence: 2 }` (2. Pazartesi)   |
| `last-weekday`       | Periyottaki bir hafta gününün son tekrarı                        | `{ type: "last-weekday", weekday: 5 }` (son Cuma)                            |
| `relative-days`      | Periyot bitiminden N gün sonra (0-60)                            | `{ type: "relative-days", daysAfterPeriodEnd: 15 }`                          |
| `relative-weekday`   | Periyot bitiminden sonraki N. hafta günü                         | `{ type: "relative-weekday", weekday: 5, occurrence: 1 }` (sonraki ilk Cuma) |
| `specific-date`      | Sabit takvim tarihi (yalnızca YEARLY)                            | `{ type: "specific-date", month: 4, day: 15 }` (15 Nisan)                    |

**Notlar**:

* `specific-date` yalnızca YEARLY periyotlarla kullanılabilir. `month` değeri 1-12 aralığındadır (1 = Ocak). Ay uzunluğunu aşan günler (örn. Şubat'ta 31. gün) otomatik olarak son geçerli güne sınırlanır.
* `relative-days` için `daysAfterPeriodEnd` değeri 0-60 aralığındadır (0 = dönem bitişi günü).
* Son tarih ve hatırlatma hesaplamaları tutarlılık için UTC kullanır.

#### Element düzeyinde plan geçersiz kılma

Bireysel form elementleri, `FormElement.schedule` sütununda bir plan depolayarak form düzeyindeki varsayılanları geçersiz kılabilir. Bu, formun geri kalanı varsayılan planı kullanırken belirli alanlar için farklı son tarihler belirlemenize olanak tanır.

```ts theme={null}
// updateForm isteğine gönderilebilecek örnek payload
{
  settings: {
    allowPublicSubmissionSupportingDocuments: true,
    workflowOverride: { type: "REQUIRE_APPROVAL" },
    defaultSchedules: {
      MONTHLY: {
        dataEntry: {
          dueDate: { type: "fixed-day", day: 15 },
          reminders: { enabled: true, offsets: [{ type: "days-before", days: 3 }, { type: "days-before", days: 7 }] }
        },
        approval: {
          dueDate: { type: "last-weekday", weekday: 5 }, // Son Cuma
          reminders: { enabled: true, offsets: [{ type: "days-before", days: 1 }] }
        }
      },
      QUARTERLY: {
        dataEntry: {
          dueDate: { type: "relative-days", daysAfterPeriodEnd: 15 }, // Çeyrek bitiminden 15 gün sonra
          reminders: { enabled: true, offsets: [{ type: "days-before", days: 7 }] }
        }
        // approval alanı opsiyoneldir, çeyreklik dönemler için onay takvimi gerekmediğinde atlanabilir
      },
      YEARLY: {
        dataEntry: {
          dueDate: { type: "specific-date", month: 3, day: 31 }, // 31 Mart
          reminders: { enabled: true, offsets: [{ type: "days-before", days: 14 }] }
        }
        // approval alanı opsiyoneldir, yıllık dönemler için onay takvimi gerekmediğinde atlanabilir
      }
    }
  }
}
```

## Form Türleri ve Dağıtım

**İç formlar (özel)**

* Ekip üyeleri verileri doğrudan platformda girer
* CSV toplu içe/dışa aktarma yetenekleri
* Otomatik veri gönderimi için API entegrasyonu
* Silinmemiş durumdayken her FormSite için tek gönderim
* Otomatik kaydetme UX’i görünüme göre değişebilir

**Dış formlar (halka açık)**

* Her FormSite için benzersiz bir public URL
* Site/yıl başına birden çok gönderim
* Alan bazında onay (iş akışına göre)
* Marka başlığı (logo/renk) meta verileriyle

## Akıllı Form Özellikleri

**Koşullu Mantık**: Kullanıcı yanıtlarına dayalı dinamik form davranışı

```javascript theme={null}
// Örnek: Yenilenebilir enerji seçilirse enerji kaynağı detaylarını göster
{
  type: "CONDITION",
  field: "energy-type",
  operator: "equals",
  value: "renewable",
  action: "show"
}
```

**Zaman periyodu yapılandırması**

* **YEARLY**: Tek periyot birimi (1)
* **MONTHLY**: 12 periyot birimi (1–12)
* **QUARTERLY**: 4 periyot birimi (1–4)
* **TIMESTAMP**: Zaman damgalı giriş; `recordedAt` zorunlu, periyot birimi ay’dan türetilir

**Dağıtım modu (NUMBER)**

* **total**: Zaman içinde toplanabilen toplam değerler (ör. emisyon)
* **snapshot**: Zaman noktasındaki değerler (ör. faktör), dağıtılmaz

**Birimler**: Alanlara ölçü birimi bağlayarak etiketleme ve doğrulama sağlar

## Gelişmiş Form Oluşturucu

**Görsel editör**: Form yapısı için sürükle-bırak arayüzü

* Oluştururken gerçek zamanlı önizleme
* Element yeniden sıralama ve iç içe geçirme
* Formlar arasında copy/paste
* CSV’den oluşturma veya mevcut formu kopyalama

**Form oluşturma yöntemleri**

* CSV içe aktarma (toplu)
* Kopyala & özelleştir
* Manuel oluşturucu

**Koşullu Mantık Oluşturucu**: Karmaşık dallanma için görsel arayüz

* Sürükle-bırak koşul oluşturma
* Birden fazla koşul türü (eşittir, içerir, büyüktür, vb.)
* AND/OR mantığı ile iç içe koşul grupları
* Gerçek zamanlı doğrulama ve önizleme

## Veri Toplama İş Akışı

**1. Form Tasarımı**: Elementler ve mantıkla form yapısı oluşturun

**2. Dağıtım**: Belirli site ve yıllara atayın

```
Üretim Tesisi A - 2024
Bölge Ofisi B - 2024, 2025
Tedarikçi Ağı - 2024 (Dış)
```

**3. Veri toplama**: Birden fazla giriş yöntemi

* Doğrudan platform girişi
* Doğrulama ile CSV içe aktarma
* API entegrasyonu
* Halka açık form gönderimleri (açıksa)

**4. Doğrulama**: Gerçek zamanlı ve toplu doğrulama

* Gerekli alan zorunluluğu
* Veri türü ve format doğrulaması
* Çapraz alan doğrulama kuralları
* Birim uyumluluğu kontrolleri

**5. Dışa aktarma ve analiz**

* CSV/XLSX dışa aktarma
* API uç noktaları
* Dashboard entegrasyonu
* Özet istatistikler

## İş Akışı ve Onaylar

Formlar organizasyonun varsayılan iş akışını devralır; form bazında ayarlarla (workflowOverride) değiştirilebilir:

* **DIRECT\_APPROVAL**: Yeni değerler APPROVED olarak kaydedilir
* **REQUIRE\_APPROVAL**: Yeni değerler COMPLETED olarak kaydedilir ve onay bekler

Durum (COMPLETED, APPROVED, REJECTED) FormElementSubmission düzeyinde tutulur. `REQUIRE_APPROVAL` modunda gönderim arayüzünde şu ek kontroller yer alır:

* **Satır içi onay kontrolleri**: Her dönem satırı için Anında Onayla / Reddet / Geri Al düğmeleri ve canlı durum rozetleri bulunur. Reddedilen değerler, kullanıcı yeni veri girdiğinde otomatik olarak tekrar COMPLETED durumuna döner.
* **Toplu işlemler**: Aylık veya çeyreklik NUMBER / SINGLE\_CHOICE / MULTIPLE\_CHOICE / LONG\_TEXT / SHORT\_TEXT alanlarında tüm dolu dönemleri tek tıkla onaylayıp reddetmek mümkündür. ACTIVITY alanları da aynı dönem içindeki tüm satırlar için toplu onaya devam eder.
* **Durum eşitlemesi**: Durum değişiklikleri kullanıcı arayüzünde anında görünür ve raporlara gecikmesiz aktarılır.

Form `DIRECT_APPROVAL` modundaysa bu düğmeler gizlenir, yeni kayıtlar otomatik olarak APPROVED durumuna alınır.

## Destekleyici Dokümanlar

Her element satırından açılabilen bir destekleyici doküman çekmecesi vardır:

* **Özel gönderimler**: Dosyalar doğrudan ilgili FormElementSubmission kaydına eklenir. Yetkili kullanıcılar yeni dosya yükleyebilir, var olanları indirebilir ve silebilir.
* **Halka açık gönderimler**: Çekmece açıldığında, oturum açmadan dosya yükleyebilmek için taslak bir gönderim oluşturulur veya mevcut taslak kullanılır. Çekmece daha önce yüklenen dosyaları listeler; silme işlemleri yalnızca yetkili iç ekip tarafından yapılır.
* **Sayaçlar ve göstergeler**: Ataş simgesi, bağlı dosya sayısını rozet şeklinde gösterir; yükleme ve silme işlemleri anında yenilenir.

Dosyalar, element/periyot (ve gerekiyorsa zaman damgası) ile bağlanarak denetlenebilirlik sağlar.

## Geliştirici Modu

Geliştirici modu açıkken gönderim ekranında **cURL kopyala** eylemi görünür. Bu buton, ilgili element kimliği, site, yıl, periyot birimi ve mevcut değeri içeren çalıştırmaya hazır bir `curl` komutunu panoya kopyalar. Böylece ekipler REST entegrasyonlarını hızlıca başlatabilir veya manuel payload hazırlamadan test edebilir.

## Görev İlerlemesi Takibi

Kullanıcılar veri girişi yaparken arayüz iyimser (optimistic) ilerleme metrikleri üretir:

* **Veri girişi ilerlemesi**: İçinde bulunulan aya kadar olan doldurulmuş/doldurulması gereken alan sayısını hesaplar; hatırlatma günlerine göre geciken ayları vurgular.
* **Onay ilerlemesi**: Onay gerektiren formlarda, sıradaki onaylanması gereken değerlerin kalan/toplam sayısı ve gecikmedeki dönemler gösterilir.

Bu geri bildirimler dashboard bileşenleri veya özel sayfalar tarafından dinlenerek canlı tamamlanma yüzdeleri, gecikme rozetleri ya da iş akışı özetleri olarak sunulabilir.

## Halka Açık Form Ayarları

* `allowPublicSubmissionEdits`
* `allowPublicSubmissionSupportingDocuments`

## Notlar

* FormElement anahtarları bir form içinde benzersizdir
* ACTIVITY elementleri TIMESTAMP periyodunu kullanamaz
* Özel formlarda her FormSite için tek (silinmemiş) FormSubmission bulunur

## Gerçek Dünya Örnekleri

**Enerji Takip Formu**:

* Aylık elektrik tüketimi (kWh birimi ile NUMBER)
* Enerji kaynağı seçimi (SINGLE\_CHOICE: Şebeke/Güneş/Rüzgar)
* Koşullu yenilenebilir detayları (sadece yenilenebilir seçilirse gösterilir)
* Destekleyici dokümantasyon yüklemesi (FILE\_UPLOAD)

**Atık Yönetimi Formu**:

* Çeyreklik atık akışları (birden fazla NUMBER alanı ile GROUP)
* Atık işleme yöntemi (MULTIPLE\_CHOICE)
* Yönlendirme oranı hesaplaması (özel formülle ACTIVITY)
* Site-özel imha prosedürleri (LONG\_TEXT)

**Tedarikçi Değerlendirme Formu** (Dış):

* Şirket bilgileri (SHORT\_TEXT alanları)
* Kapsam 1, 2, 3 emisyonları (tCO2e birimleri ile NUMBER)
* Aktivite tabanlı hesaplamalar (karmaşık emisyonlar için ACTIVITY)
* Aylık veri toplama (MONTHLY periyot ayarı)

## Operasyonel Faydalar

* **Tutarlılık**: Tüm site ve zaman periyotları boyunca aynı form yapısı
* **Verimlilik**: Otomatik kaydetme, toplu işlemler ve şablon yeniden kullanımı
* **Uyumluluk**: Yerleşik doğrulama ve denetim izleri
* **Ölçeklenebilirlik**: Yüzlerce site ve binlerce gönderimi işleyin
* **Esneklik**: Geçmiş verileri kaybetmeden formları uyarlayın