> ## 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.

# Activity

> ActivityDefinition'dan üretilen hesaplanmış kayıtlar

Activity, bir ActivityDefinition'dan üretilen hesaplanmış kayıttır. Girdi değerleri, hesaplanan sayısal sonuç ve hesaplamaya ait meta verileri içerir. Aktiviteler form/site/yıl/periyot bağlamında saklanır.

## Yaşam Döngüsü

1. ActivityDefinition ile bağlantılı form elementi seçilir
2. UI üzerinden girişler toplanır
3. Sunucuda `calculate` fonksiyonu çalıştırılır
4. Sonuç Activity olarak kaydedilir ve FormElementSubmission ile ilişkilendirilir
5. Görüntüleme, dışa aktarma veya yeniden hesaplama yapılır

## Veri Modeli

Bir Activity şu alanları içerir:

* `definitionId`: kullanılan ActivityDefinition kimliği
* `input`: gönderilen giriş değerleri (JSON)
* `value`: hesaplama sonucu sayısal değer
* `metadata`: hesaplamaya dair detaylar (JSON)
* form submission, form elementi, site, yıl, periyot bağlantıları

Örnek (basitleştirilmiş):

```json theme={null}
{
  "definitionId": "ad_123",
  "input": { "electricityKwh": 1200, "gridRegion": "Türkiye" },
  "value": 432.0,
  "metadata": { "factor": 0.36, "year": 2025 }
}
```

## Aktivitelerle Çalışma

Aktiviteler Activities router üzerinden yönetilir (TRPC prosedürleri ve eşleşen REST uçları).

* `activities.addActivity`
  * Girdi: `{ formId, key, siteId, year, periodUnit, input }`
  * `formId + key` ile elementi bulur, bağlı ActivityDefinition'ı kullanır, hesaplar ve kaydeder.

* `activities.getActivities`
  * Girdi: `{ formId, key, siteIds?, years?, periodUnits?, limit?, offset? }`
  * `limit`: istek başına maksimum sonuç sayısı (varsayılan 100, maksimum 1000)
  * `offset`: atlanacak kayıt sayısı (varsayılan 0)
  * `{ activities, pagination: { total, limit, offset, hasMore } }` döndürür. Aktiviteler parse edilmiş `input`/`metadata` ve bağlamsal alanlar (`siteId`, `siteName`, `year`, `periodUnit`) içerir.

* `activities.importActivities`
  * Toplu içe aktarma; tüm satırların aynı ActivityDefinition'a bağlı elementleri hedeflediğini doğrular; satır bazlı hesaplama ve hata raporlar.

* `activities.exportActivities`
  * CSV/XLSX dışa aktarım; sabit sütun sırası: bağlam alanları, düzleştirilmiş `input_*`, düzleştirilmiş `metadata_*`, ve `value`.

* `activities.removeActivity`
  * Aktivite ve bağlı FormElementSubmission kayıtlarını siler; periyot durumunu iş akışına göre ayarlar.

* `activities.recalculateActivity` / `activities.recalculateActivities`
  * Tekil veya filtrelenmiş bir grup aktiviteyi, güncel ActivityDefinition `calcCode` ile yeniden hesaplar.

Erişim kontrolü: tüm işlemler site düzeyi izinleri uygular; hesaplamadaki dataset/KPI/site yardımcıları mevcut organizasyon için RLS'ye tabidir.

## Dışa Aktarım Formatı

Sütunlar şu sırayla üretilir:

* `activityId`, `site`, `year`, `periodUnit`, `value`
* ActivityDefinition `inputs` listesindeki her giriş (adlarıyla eşleşen sütunlar)
* Her metadata anahtarı için `metadata_*` sütunları

Not: Yalnızca tanım şemasındaki girişler giriş sütunu olarak yer alır. Ek bilgiler dışa aktarımda yer alması için `metadata` içinde döndürülmelidir.

Örnek sütunlar:

* Bağlam: `activityId`, `site`, `year`, `periodUnit`, `value`
* Girdiler: `electricityKwh`, `gridRegion`, ... (tanımdaki girişler)
* Metadata: `metadata_factor`, `metadata_year`, ... (düzleştirilmiş anahtarlar)

## İçe Aktarım Kuralları ve Hatalar

* Tüm satırlar, aynı ActivityDefinition'a bağlı elementleri hedeflemelidir (anahtar üzerinden eşleşir).
* Site erişimi satır bazında doğrulanır.
* Hatalar satır numarası ve bağlam (key/site/yıl/periyot) ile birlikte kullanıcı dostu mesajla döner; örn.: `Satır 3 (energy - siteA 2024 Period 1): electricityKwh sıfırdan büyük eşit olmalıdır`.

## Yeniden Hesaplama

* Yeniden hesaplama
  * güncel ActivityDefinition `calcCode`,
  * kayıtlı `input`,
  * güncel bağlam (site/yıl/periyot) ve dataset'leri kullanır.
* NaN/Infinity değerleri hem `value` hem de sayısal `metadata` alanlarında `0`'a normalize edilir.

## UI & Spreadsheet

* Aktivite UI'si ActivityDefinition'ın `uiCode`'una göre dinamik render edilir. `onAddActivity(values)` çağrısı `addActivity`'yi tetikler.
* Zengin tablo görünümü; site/yıl/periyot filtreleri, tanımda yer alan “standart” giriş sütunlarını vurgulama, ekstra giriş ve meta sütunlarını gösterme desteği içerir.

## İş Akışı & Durum

* Form veya organizasyon iş akışı onay gerektiriyorsa ilgili periyottaki gönderimler `COMPLETED` olur.
* Aksi durumda gönderimler anında `APPROVED` olur.

## Hata Yönetimi & Kalite

* Hesaplama hatalarında açık ve anlaşılır mesajlar fırlatın; UI bunları kullanıcıya gösterir.
* NaN/Infinity değerleri `value` ve sayısal meta veride `0`'a normalize edilir.
* Girdi alanlarını sade ve anlamlı seçin; `example` değerleri CSV tespiti ve UI ipuçlarını iyileştirir.

## Güvenlik

* Tüm işlemlerde site erişim kuralları uygulanır.
* `$datasets/$kpis/$sites` yardımcıları, organizasyon bağlamına göre RLS ile sınırlandırılır.

## Bkz.

* ActivityDefinition (girdi/UI/hesaplama ve önizleme)
* Activity Calculation Variables (bağlam değişkenleri ve örnekler)
* Dataset Access Examples (uçtan uca kullanım örnekleri)
* API Örnekleri

Hızlı REST örnekleri (`YOUR_TOKEN` ve kimlikleri değiştirin):

Aktivite listeleme (sayfalı)

```bash theme={null}
curl -H "Authorization: Bearer YOUR_TOKEN" \
  --get \
  --data-urlencode "formId=FORM_ID" \
  --data-urlencode "key=energy_usage" \
  --data-urlencode "limit=100" \
  --data-urlencode "offset=0" \
  https://your.api/activities
```

Aktivite ekleme

```bash theme={null}
curl -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -X POST https://your.api/activities \
  -d '{
    "formId": "FORM_ID",
    "key": "energy_usage",
    "siteId": "SITE_ID",
    "year": 2025,
    "periodUnit": 1,
    "input": { "electricityKwh": 1200, "gridRegion": "Türkiye" }
  }'
```

Filtreli yeniden hesaplama

```bash theme={null}
curl -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -X POST https://your.api/activities/recalculate \
  -d '{ "formId": "FORM_ID", "key": "energy_usage", "year": 2025 }'
```

CSV dışa aktarım

```bash theme={null}
curl -H "Authorization: Bearer YOUR_TOKEN" \
  --get \
  --data-urlencode "formId=FORM_ID" \
  --data-urlencode "key=energy_usage" \
  --data-urlencode "format=csv" \
  https://your.api/activities/export
```

## Sorun Giderme

* Ekle/ithal işlemi kullanıcı hatasıyla başarısız → Hesaplama `Error("...")` fırlatmış olabilir; girdi veya mantığı mesaj doğrultusunda düzeltin.
* İthalatta çoklu satır hatası → Hata detaylarındaki satır indeksini ve bağlamı kullanarak veriyi düzeltin.
* Yeniden hesaplama sıfırlar üretiyor → İlgili yıl için dataset değerlerini/anahtarlarını kontrol edin; yedek kullanın.
* Dışa aktarımdan sütun eksik → ActivityDefinition `inputs` şemasında alanın mevcut olduğundan emin olun.

## Performans İpuçları

* Gerekliyse tek seferde `getCoefficients` ile alın ve tekrar kullanın.
* Aktivite başına metadata'yı küçük tutun; dışa aktarım hızlanır.

## Metadata Kuralları

* Açık anahtarlar ve birimleri tercih edin (ör.: `efKgCO2ePerKWh`).
* Analizi kolaylaştırmak için uygun olduğunda `year`, `period` veya `siteId` ekleyin.