Backend Change Doc

Backend değişikliklerini frontend veya mobil ekipteki bir developer’ın hızlıca tarayıp anlayabileceği kısa bir Markdown dökümanına dönüştür. Uzun açıklamalardan kaçın; madde işaretleri ve kod blokları kullan.

Kullanım Senaryoları

Kullanıcı backend’de yaptığı değişiklikleri frontend/mobil ekibe iletmek istediğinde. Genelde şu bağlamlarda:

• Sprint sonunda release notes
• PR açıklaması / paylaşım notu
• “Şunları yaptım, frontend tarafında bunlara göre güncelleme lazım” diyen bir duyuru

Ne Üretilir?

• Eklenen, güncellenen ve silinen endpointlerin kısa özeti
• Request ve response DTO tanımları
• Değişen enum değerleri
• Breaking change ve migration notları
• Frontend veya mobil ekibin uygulaması gereken değişiklikler

---
name: backend-change-doc
description: "Backend (ASP.NET Core / C#) tarafında yapılan API ve model değişikliklerini frontend veya mobil ekiplere duyurmak için kısa, developer dostu bir değişiklik dökümanı (Markdown) üretir. Kullan — 'yaptığım backend değişikliklerini frontend/mobil ekibe anlat', 'sprint sonunda API değişiklik dökümanı hazırla', 'yeni endpoint eklendi/güncellendi/silindi dökümanı', 'release notes for backend changes', 'controller/DTO/enum değişiklik özeti'. Commit/diff/PR üzerinden ya da kullanıcı anlatımıyla tetiklenebilir. Sadece backend-frontend iletişimi için değişiklik dökümanı istendiğinde kullan, genel teknik dökümantasyon için kullanma."
---

# Backend Change Doc

Backend değişikliklerini frontend veya mobil ekipteki bir developer'ın hızlıca tarayıp anlayabileceği kısa bir Markdown dökümanına dönüştür. Uzun açıklamalardan kaçın; madde işaretleri ve kod blokları kullan.

## Kullanım Senaryoları

Kullanıcı backend'de yaptığı değişiklikleri frontend/mobil ekibe iletmek istediğinde. Genelde şu bağlamlarda:
- Sprint sonunda release notes
- PR açıklaması / paylaşım notu
- "Şunları yaptım, frontend tarafında bunlara göre güncelleme lazım" diyen bir duyuru

## Ne Üretilir?

- Eklenen, güncellenen ve silinen endpointlerin kısa özeti
- Request ve response DTO tanımları
- Değişen enum değerleri
- Breaking change ve migration notları
- Frontend veya mobil ekibin uygulaması gereken değişiklikler

## Bilgi toplama

Yazmadan önce gerekli malzemeyi topla. Sırayla şunlara bak:
1. Kullanıcının mesajındaki anlatım (en güvenilir kaynak — onun söylediği gerçektir)
2. Varsa `git diff`, `git log`, açılan PR linkleri — controller, DTO, Enum dosyalarına odaklan
3. Controller dosyaları: `*Controller.cs` — route, method, `[HttpGet/Post/Put/Delete]`, `[Authorize]`, parametre tipleri
4. DTO/Model klasörleri: request/response sınıfları, property tipleri ve isimleri
5. Enum dosyaları: yeni enum değerleri veya eski değerlerin kaldırılması

Bir endpoint hakkında eksik bilgi varsa (örn. auth gerekiyor mu, başarı durumunda ne döner) önce koda bak; yine de emin olamıyorsan kullanıcıya tek soruda topluca sor — her alan için ayrı ayrı değil.

## Döküman kuralları

Developer okuyacak. Hedef: bir göz atışta ne değiştiğini kavrayabilsin.

- Kısa tut. Giriş paragrafı yok, "Merhaba ekip" tarzı selamlama yok.
- Başlığı şu formatta ver: `# Backend Değişiklikleri — YYYY-MM-DD` (tarih için bash'ten `date +%Y-%m-%d` al).
- 3 ana kategori şu sırayla: **Yeni Eklenenler**, **Güncellenenler**, **Silinenler**. Boş kategoriyi de ekle ve altına `_Yok_` yaz — developer eksik sanmasın.
- Üst bölümde sadece endpoint listesi + tek cümlelik değişim özeti. Detaylar dökümanın en altında.
- Request/Response/DTO/Enum tanımları **dökümanın en altında** ayrı bölümlerde. Üstteki endpoint listesi bunlara DTO adıyla metin olarak referans versin — anchor link kullanma.

### Endpoint bilgileri için zorunlu alanlar

Her endpoint satırında şunlar olmalı:

- **HTTP method** ve **path (controller ile birlikte)** — örn. `POST /api/auth/login` ve parantez içinde `(AuthController.Login)`
- **Request** — body varsa DTO adı (düz metin, link yok), yoksa query/path params listesi
- **Success response** — HTTP status + dönen DTO adı
- **Error status'ları** — 400/401/403/404/409 gibi anlamlı olanlar (hepsi değil, endpoint'e özel olanlar)

### "Güncellenenler" bölümü için özel kural

Sadece endpoint'i listelemek yetmez — **ne değişti** anlaşılmalı. Her güncelleme maddesinde "Değişiklik:" etiketi altında kısa liste ver. Örnek:

```
- `PUT /api/users/{id}` (UsersController.Update)
  - **Değişiklik:**
    - `phoneNumber` alanı artık zorunlu (önce opsiyoneldi)
    - Response'a `updatedAt` eklendi
    - 409 status'ü artık telefon numarası çakışmasında dönüyor
```

Breaking change varsa başına `⚠️ BREAKING:` yaz — bu tek istisna olarak emoji kullanmak faydalı, çünkü frontend'in dikkatini oraya çekmesi gerek.

### "Silinenler" bölümü için özel kural

Silinen her endpoint için **migration notu** ekle: yerine ne kullanılacak veya neden kaldırıldı.

```
- `GET /api/legacy/profile` (LegacyController.GetProfile) — Yerine: `GET /api/users/me` kullan
```

### DTO / Model / Enum tanımları

Döküman sonunda her DTO için tablo kullan. Kolonlar: **Property**, **Tip**, **Açıklama**, **Zorunlu Mu?**

- **Açıklama** kısa ama bağlamsal bir cümle olsun — sadece kelime değil, o field'ın sistemdeki rolünü anlat.
- **Zorunlu Mu?** kolonu: zorunlu alanlar için `Evet`, opsiyonel alanlar için `Hayır`.

```
### LoginRequest

| Property | Tip | Açıklama | Zorunlu Mu? |
|---|---|---|---|
| patientId | string | Hasta doğrulaması ve yeni kayıtta `ReportNumber` üretimi bu hastaya göre yapılır. | Evet |
| email | string | Kullanıcının sisteme kayıtlı e-posta adresi; kullanıcı tanımlamada unique olarak kullanılır. | Evet |
| deviceId | string? | İsteği gönderen mobil cihazı tanımlar; bildirim yönlendirmesi için kullanılır. | Hayır |
```

Enum'larda da aynı yapı:

```
### OrderStatus

| Değer | Sayısal | Açıklama |
|---|---|---|
| Pending | 0 | Sipariş alındı, ödeme bekleniyor |
| Paid | 1 | Ödeme tamamlandı, hazırlanacak |
| Shipped | 2 | Kargoya verildi |
| Cancelled | 3 | İptal edildi (kullanıcı veya sistem) |
```

Sadece **yeni eklenen veya değişen** DTO/Enum'ları yaz. Mevcutları tekrar yazma — döküman şişmesin. Değişen bir DTO'da sadece değişen property'leri göstermek yerine tüm DTO'yu yaz (developer'ın kafa karışıklığı olmasın), ama üstüne "Değişen alanlar: `phoneNumber`, `updatedAt`" notunu düş.

## Format şablonu

Her zaman bu iskeleti kullan:

```markdown
# Backend Değişiklikleri — YYYY-MM-DD

> Kapsam: <Sprint X / Release Y.Z / PR #NNN> — <tek cümle özet>

## Yeni Eklenenler

- `<METHOD> <path>` (ControllerName.ActionName)
  - Request: DTOAdı _veya_ Query: `param1: tip, param2: tip`
  - Response: `200 OK` → DTOAdı
  - Errors: `400`, `404`

## Güncellenenler

- `<METHOD> <path>` (ControllerName.ActionName)
  - **Değişiklik:**
    - <madde 1>
    - <madde 2>
  - Request: DTOAdı
  - Response: `200 OK` → DTOAdı

## Silinenler

- `<METHOD> <path>` (ControllerName.ActionName) — Yerine: `<yeni endpoint veya açıklama>`

---

## DTO'lar

### DTOAdı

| Property | Tip | Açıklama | Zorunlu Mu? |
|---|---|---|---|
| ... | ... | ... | Evet / Hayır |

## Enum'lar

### EnumAdı
...tablo...
```

Kategorilerden biri boşsa başlığı bırak, altına `_Yok_` yaz.

## Yazım ipuçları

- Yapay genişletme yapma. "Bu değişiklik X'i iyileştirir" gibi cümleler ekleme — developer koda bakar zaten.
- Path'te placeholder varsa curly brace ile yaz: `/api/users/{id}`.
- Nullable C# tipini Markdown'da `?` ile göster: `string?`, `int?`, `Guid?`.
- Koleksiyonları `List<Foo>` veya `Foo[]` olarak yaz, `IEnumerable<Foo>` kullanma — frontend tarafı için karışık.
- `DateTime` alanlarını tabloda `string (ISO8601)` olarak belirt, çünkü JSON'da string olarak gider.
- Enum property'lerini tabloda `string (EnumAdı)` olarak belirt ve Enum bölümüne anchor ver.

## Örnek ve şablon dosyaları

- Boş iskelet kopyalanıp doldurulacaksa: `references/template.md`
- Tamamlanmış gerçekçi bir örnek için: `references/example.md`

Her yeni döküman üretirken önce `references/example.md`'ye göz at — ton ve detay seviyesi oradaki gibi olsun.

## Çıktıyı kaydetme

Dosya adı: `YYYY-MM-DD-backend-changes.md` (kullanıcının CLAUDE.md kuralı).

Kullanıcı farklı bir yer söylemediyse, kullanıcının seçili workspace klasörüne yaz. Dosyayı yazdıktan sonra kısa bir özet ver: kaç endpoint eklendi/güncellendi/silindi ve varsa breaking change sayısı.