sozsoft-platform/configs/seeds/docs/modules/HrWorkCalendar.md

<!-- module-doc: claims=App.Hr.Shift -->
# İK › Çalışma Takvimi ve Vardiyalar (`App.Hr.WorkCalendar`, `App.Hr.Shift`)

Çalışma zamanının iki temel tanımı: resmi tatil / yarım gün takvimi (yıllık tekrarlı ya da tek
seferlik) ve vardiya tanımları (saat aralığı, mola, gece vardiyası). Diğer modüller bu tanımları
lookup olarak kullanır. Tamamı konfigürasyondur (Wizard + seed); vardiya ayrıca kullanıcı kaydına
bağlanır.

> Bu doküman modülün tek "nasıl çalışır" kaynağıdır. Modülde yapılan her değişiklik aynı commit'te
> buraya yansır (`lowcode.instructions.md` §0.13).

---

## 1. Amaç ve kapsam

| Persona | Ne yapar | Ekran |
| --- | --- | --- |
| İK | Yılın tatil ve yarım günlerini girer, takvim görünümünden kontrol eder | Çalışma Takvimi |
| İK / üretim planlama | Vardiya tanımlarını yönetir, çalışanı vardiyaya bağlar | Vardiyalar · Kimlik › Kullanıcılar |

Kapsam: kiracı (`IsTenant`). Şube kırılımı yoktur — takvim kiracının tamamı için geçerlidir.

---

## 2. Analiz ve kararlar

> Modüller §0.13 kuralından önce üretildi; keşif turu kaydı yoktur. Kararlar artefaktlardan
> (wizard, seed, commit `130e23bc` "Disiplin Dosyaları, Çalışma Takvimi") okunmuştur.

| Konu | Karar |
| --- | --- |
| Tatil tekrarı | Sabit tarihli resmi tatiller `RecurrenceRule = FREQ=YEARLY` ile **bir kez** girilir, her yıl tekrarlar; dini bayramlar ay takvimine bağlı olduğu için **her yıl ayrı** satırdır (tekrar kuralı boş) |
| Gün türü | `Holiday` (tam gün tatil) / `HalfDay` (arife, yarım gün) |
| Görünüm | Liste görünümlerine ek olarak **Scheduler** (takvim) görünümü; `AllDay` her zaman `true` |
| Vardiya saatleri | `StartTime` / `EndTime` `SS:dd` metin; çalışma süresi elle girilir (otomatik hesap yok) |
| Gece vardiyası | Bayrak (`IsNightShift`) — sağlık kartındaki "gece çalışabilir" sonucuyla birlikte değerlendirilir, otomatik kontrol yoktur |
| Vardiya bağı | Kullanıcı kaydında `ShiftId` alanı (`LookupQueryValues.TenantShiftValues`: "Ad (başlangıç-bitiş)") |
| Menü yeri | Çalışma Takvimi `İnsan Kaynakları` kökünde; Vardiyalar bir tanım olduğu için `İnsan Kaynakları › Tanımlamalar` altında (yetkisi de `App.Hr.Definitions`'ın altındadır) |

---

## 3. Menü ve ekranlar

| Menü (TR / EN) | `ListFormCode` | Yer | Görünümler | Widget'lar |
| --- | --- | --- | --- | --- |
| Çalışma Takvimi / Work Calendar | `App.Hr.WorkCalendar` | `İnsan Kaynakları` (sıra 4, `FcCalendar`) | Grid, Card, Pivot, Chart, **Scheduler** | Toplam · Tatil · Yarım Gün |
| Vardiyalar / Shifts | `App.Hr.Shift` | `İnsan Kaynakları › Tanımlar` (sıra 11, `FcClock`) | Grid, Card, Pivot, Chart | Toplam · Aktif · Pasif |

Scheduler eşlemesi: metin `Name`, başlangıç `StartDate`, bitiş `EndDate`, tüm gün `AllDay`,
tekrar `RecurrenceRule`.

Seed verisi:
- Çalışma takvimi, 16 satır (`data/App.Hr.WorkCalendar.json`):
  - Yıllık tekrarlı tatiller: Yılbaşı, 23 Nisan, 1 Mayıs, 19 Mayıs, 15 Temmuz, 30 Ağustos, 29 Ekim.
  - Yıllık tekrarlı yarım gün: 28 Ekim arifesi.
  - Yıla özel satırlar: 2026 ve 2027 Ramazan/Kurban bayramları ve arifeleri.
- Vardiyalar, 3 satır (`data/App.Hr.Shift.json`): Sabah 08:00–16:00, Akşam 16:00–00:00, Gece 00:00–08:00 (gece vardiyası).

---

## 4. Veri modeli

| Tablo | Kolonlar |
| --- | --- |
| `Hr_T_WorkCalendar` | `Name`, `StartDate`, `EndDate`, `DayType` (Holiday/HalfDay), `RecurrenceRule` (boş / `FREQ=YEARLY`), `AllDay`, `IsActive` |
| `Hr_T_Shift` | `Name`, `StartTime`, `EndTime`, `BreakMinutes`, `LateToleranceMinutes`, `EarlyLeaveToleranceMinutes`, `WorkingHours`, `IsNightShift`, `IsActive` |
| `AbpUsers.ShiftId` | Çalışanın vardiyası (genişletme kolonu) |

Entity yoktur (wizard tabloları); `sql/object/Hr_T_{WorkCalendar,Shift}.sql`.

---

## 5. İş kuralları

| Yer | Kural |
| --- | --- |
| Takvim — yeni kayıt | Gün türü `Holiday`, tekrar `FREQ=YEARLY`, tüm gün, aktif |
| Takvim — çok günlü tatil | Başlangıç–bitiş aralığı olarak tek satırda girilebilir |
| Vardiya — yeni kayıt | Gece vardiyası hayır, aktif |

| Vardiya — toleranslar | Geç kalma / erken çıkış toleransı (dk); boşsa Ayarlar › İnsan Kaynakları › Puantaj'daki genel değer |

Takvim İzin Yönetimi'nin gün sayısını (`HrLeave.md`), takvim ve vardiya Puantaj ve Devam Takibi'nin
gün tipini, vardiya saatini, molasını ve toleransını (`HrAttendance.md`) besler.

---

## 6. Yetki ve görünürlük

İzin grubu `App.Hr`, modül `Sas|Hr`. Her ekranın kökü + `.Create/.Update/.Delete/.Export/.Import/.Note`.
Hiçbir yetki role otomatik atanmaz. Takvimin okunması tüm çalışanlara açılabilir; düzenleme İK'da kalmalıdır.

---

## 7. Entegrasyonlar

| Kullanan | Nasıl |
| --- | --- |
| Kimlik › Kullanıcılar | `ShiftId` alanı vardiya lookup'ı |
| Olay Günlüğü (`App.Hr.EventLog`) | Olay kaydında vardiya seçimi |
| Sağlık Kartları | Vardiyalı / gece çalışabilir sonucu (bilgi; vardiya tanımıyla otomatik eşleşmez) |
| İzin Yönetimi | Takvim tatilleri izin gününden düşülür (`Hr_F_LeaveWorkDays`). Takvim satırı eklenince/değişince/silinince denk gelen izinlerin gün sayısı yeniden hesaplanır (`Hr_S_WorkCalendarAfterSave`) |
| Puantaj ve Devam Takibi | Tatil → Resmî tatil, arife → yarım vardiya (`Hr_F_WorkCalendarDayType`); vardiya saat/mola/tolerans → `Hr_V_AttendanceShift`. Takvim kaydı ilgili günleri hemen yeniden hesaplar (kapalı ay hariç); vardiya değişikliği gece işinde ya da Puantaj Dönemleri kaydında yansır |

---

## 8. Akış örneği

1. Yıl başında İK **Çalışma Takvimi**'nde o yılın dini bayram satırlarını ekler (sabit tatiller zaten yıllık tekrarlıdır) ve Scheduler görünümünde yılı kontrol eder.
2. Üretim için **Vardiyalar**'a "Hafta Sonu 08:00–20:00, mola 60 dk, çalışma 11 saat" eklenir.
3. Kullanıcı ekranında çalışanların **Vardiya** alanı güncellenir; Olay Günlüğü kayıtlarında da bu vardiyalar seçilir.

---

## 9. Sık sorulanlar ve bilinen sınırlar

**Ramazan Bayramı gelecek yıl görünmüyor.** Dini bayramlar yıla özeldir; her yıl yeni satır girilir.

**Çalışma süresi neden hesaplanmıyor?** Vardiya saatleri metindir, süre elle girilir.

**Takvim izin/puantaj hesabını etkiliyor mu?** Evet: izin gün sayısından tatiller düşülür, puantajda tatil
günü Resmî tatil, arife yarım gün sayılır. Takvim satırı kaydedilince denk gelen günlerin izin gün sayısı ve
puantajı hemen yeniden hesaplanır (yıllık tekrarlı satırda bu yıl ve gelecek yıl; kapalı puantaj ayı yazılmaz).
Bir satırın tarihi değiştirildiğinde eski tarihlerin puantajı gece işinde ya da Puantaj Dönemleri kaydında düzelir.

**Vardiyalar nerede?** `İnsan Kaynakları › Tanımlamalar` altında (sıra 11); menü satırı, wizard dosyası ve
yetki ağacı aynı yeri gösterir.

---

## 10. Dosyalar ve geri alma

| Dosya | İçerik |
| --- | --- |
| `configs/seeds/sql/object/Hr_T_{WorkCalendar,Shift}.sql` | Tablolar |
| `configs/seeds/wizard/{WorkCalendar,Shift}.json` | 2 wizard |
| `configs/seeds/data/App.Hr.{WorkCalendar,Shift}.json` | Takvim ve vardiya verisi (ekran kayıtları dosyaya aynalanır) |
| `api/src/Sozsoft.Platform.Application.Contracts/LookUpQueryValues.cs` (`TenantShiftValues`) | Kullanıcı ekranındaki vardiya lookup'ı |

Geri alma: Wizard Manager'dan silinir; vardiya tablosu kullanıcı ekranının lookup'ı tarafından okunduğu için düşürülmemelidir.

<!-- module-doc:auto:begin -->
## Ek — Ekran envanteri (otomatik)

> Wizard dosyalarından üretilir; deploy, silme, tasarımcı kaydı ve import'ta yenilenir. Elle düzenleme bir sonraki yenilemede kaybolur.

### Çalışma Takvimi — `App.Hr.WorkCalendar`

| Özellik | Değer |
| --- | --- |
| Wizard | `wizard/WorkCalendar.json` |
| Yol | Liste (Wizard) |
| Menü | `App.Hr` › `App.Hr.WorkCalendar` (sıra 4) |
| Yetki | `App.Hr.WorkCalendar` + `.Create`, `.Update`, `.Delete`, `.Export`, `.Import`, `.Note` |
| Açıklama | Çalışma Takvimi — resmi tatiller, arife (yarım gün) ve çalışılmayan günler. |
| Kaynak | `Hr_T_WorkCalendar` · filtre `"IsDeleted" = 'false'` |
| Görünümler | Grid, Card, Pivot, Chart, Scheduler (açılış grid) |
| Düzenleme | ekle ✓ · düzenle ✓ · sil ✓ · popup |
| Kapsam | Kiracı |
| Widget'lar | `App.Widget.Total`, `App.Hr.WorkCalendar.DayType.Holiday`, `App.Hr.WorkCalendar.DayType.HalfDay` |
| Komutlar | InsertAfter: `Hr_S_WorkCalendarAfterSave` · UpdateAfter: `Hr_S_WorkCalendarAfterSave` · DeleteAfter: `Hr_S_WorkCalendarAfterSave` |
| Form varsayılanları | DayType=Holiday, RecurrenceRule=FREQ=YEARLY, AllDay=true, IsActive=true |
| Veri aynası | `data/App.Hr.WorkCalendar.json` |

| Alan | Başlık | Editör | Zorunlu | Formda | Kaynak |
| --- | --- | --- | --- | --- | --- |
| `Name` | Adı | dxTextBox | ✓ | ✓ |  |
| `StartDate` | Başlangıç Tarihi | dxDateBox | ✓ | ✓ |  |
| `EndDate` | Bitiş Tarihi | dxDateBox | ✓ | ✓ |  |
| `DayType` | Gün Türü | dxSelectBox | ✓ | ✓ | liste: Holiday, HalfDay |
| `RecurrenceRule` | Tekrarlama Kuralı | dxSelectBox |  | ✓ | liste: FREQ=YEARLY |
| `AllDay` | Tüm Gün | dxCheckBox |  |  |  |
| `IsActive` | Aktif | dxCheckBox | ✓ | ✓ |  |

### Vardiyalar — `App.Hr.Shift`

| Özellik | Değer |
| --- | --- |
| Wizard | `wizard/Shift.json` |
| Yol | Liste (Wizard) |
| Menü | `App.Hr.Definitions` › `App.Hr.Shift` (sıra 11) |
| Yetki | `App.Hr.Shift` + `.Create`, `.Update`, `.Delete`, `.Export`, `.Import`, `.Note` |
| Açıklama | Vardiyalar — çalışma vardiyalarının tanımı (sabah, akşam, gece…). |
| Geliştirme talebi | Human Resources -> Olay Günlüğü |
| Kaynak | `Hr_T_Shift` · filtre `"IsDeleted" = 'false'` |
| Görünümler | Grid, Card, Pivot, Chart (açılış grid) |
| Düzenleme | ekle ✓ · düzenle ✓ · sil ✓ · popup |
| Kapsam | Kiracı |
| Widget'lar | `App.Widget.Total`, `App.Widget.Active`, `App.Widget.Passive` |
| Form varsayılanları | IsNightShift=false, IsActive=true |
| Veri aynası | `data/App.Hr.Shift.json` |

| Alan | Başlık | Editör | Zorunlu | Formda | Kaynak |
| --- | --- | --- | --- | --- | --- |
| `Name` | Vardiya Adı | dxTextBox | ✓ | ✓ |  |
| `StartTime` | Başlangıç Saati | dxTextBox |  | ✓ |  |
| `EndTime` | Bitiş Saati | dxTextBox |  | ✓ |  |
| `BreakMinutes` | Mola (dk) | dxNumberBox |  | ✓ |  |
| `LateToleranceMinutes` | Geç Kalma Toleransı (dk) | dxNumberBox |  | ✓ |  |
| `EarlyLeaveToleranceMinutes` | Erken Çıkış Toleransı (dk) | dxNumberBox |  | ✓ |  |
| `WorkingHours` | Çalışma Süresi (Saat) | dxNumberBox |  | ✓ |  |
| `IsNightShift` | Gece Vardiyası | dxCheckBox | ✓ | ✓ |  |
| `IsActive` | Aktif | dxCheckBox | ✓ | ✓ |  |

<!-- module-doc:auto:end -->