# Hazır uygulama şablonları: ilk tercih

Kullanıcının istediği iş aşağıdaki kalıplardan birine benziyorsa uygulamayı boş iskeletten değil, **şablondan** üretin.
Şablon; veri modelini, sunucu kurallarını, ekranları (hazır bileşenlerle), Excel aktarımını, Devoplus yapay zekası
araçlarını ve rehberini, testleri, README'yi ve `AGENTS.md`'yi hazır getirir ve yayın kapılarından geçer. Sizin işiniz
kullanıcının ihtiyacına göre **değiştirmektir**; baştan yazmak hem yavaştır hem de şablonun koruduğu kuralları
(eksi stok, sunucuda hesaplanan puan ve tarih, durum akışı, kişisel verinin silinmesi) kaybettirir.

Uygulamayı iskelet üreticiyle (`create-devoplus-one-app`, npm) kendiniz üretin:

```bash
npm create devoplus-one-app -- <dizin> --template <şablon> --slug <kısa-ad> \
  --owner <sahibin e-postası> --name "<Türkçe ad>" --name-en "<İngilizce ad>"
npm create devoplus-one-app -- --list-templates   # şablonlar ve tek cümlelik özetleri
```

`--template` verilmezse boş iskelet (`blank`) üretilir. Komut kararlı sürümü (`latest`) kullanır; `@next` yalnız
test kanalı içindir ([sınırlar](/docs/limits.md)). ⛔ `npx create-one-app` çalıştırmayın: kapsamsız `create-one-app` adı npm'de başkasına aittir
ve başka birinin kodunu çalıştırır. Devoplus'ın paketi `create-devoplus-one-app`'tir.

## Hangi şablon

Şablonlar Devoplus Portal'ın **zaten sunduğu işleri tekrar etmez.** Kullanıcı rezervasyon, anket, onay akışı ya da destek
talebi istiyorsa yeni uygulama yazmadan önce bunu söyleyin: bu işler için Portal'ın Rezervasyon, Anket ve Destek Talep
Formu modülleri ile Devoplus İş Akışı vardır. Kullanıcı yine de ayrı bir uygulama istiyorsa boş iskeletten başlayın.

| Şablon | Kullanıcı şöyle anlatır | İçinde gelenler |
|---|---|---|
| `bakim-takvimi` | "Cihazların bakımını takip edelim", "bakım zamanı gelince sorumluya hatırlatılsın" | Ekipman kaydı (konum, sorumlu, bakım aralığı), bakım kaydı ve fotoğraf/dosya eki, **sunucuda** hesaplanan sıradaki bakım tarihi, gecikenler listesi, yaklaşan ve geciken bakım için sorumluya sabah e-postası (günde bir kez), Excel |
| `saha-denetimi` | "Mağaza denetimi yapalım", "kontrol listesiyle puanlayalım" | Kontrol listesi (bölüm, ağırlık, kritik madde), iş yeri seçimi (organizasyon şemasından), madde başına uygun / uygun değil / uygulanamaz + not + fotoğraf, **sunucuda** hesaplanan ağırlıklı puan (uygun olmayan kritik madde sonucu başarısız yapar), tamamlanınca değişmeyen denetim, yazdırılabilir rapor, yerlere göre pano, Excel |
| `egitim-sertifika` | "Eğitim ve sertifikaların süresini takip edelim", "süresi dolmadan haber versin" | Sertifika türleri (geçerlilik süresi), kişi başına kayıt ve belge eki, **sunucuda** hesaplanan geçerlilik sonu, "Sertifikalarım" ve "Ekibim" (yönetici, organizasyon şemasından), süresi 30 gün içinde dolacaklar için kişiye ve yöneticisine sabah e-postası, Excel |
| `ziyaretci-kaydi` | "Resepsiyonda ziyaretçileri kaydedelim", "ziyaretçi gelince çalışana haber verilsin" | Ziyaretçi kaydı (ad, firma, amaç, ziyaret edilen çalışan), **sunucunun** yazdığı giriş ve çıkış saati, ziyaret edilen çalışana e-posta, "Bugünkü ziyaretçiler" ve "Ziyaretçilerim", günün Excel'i, **90 gün** sonra kişisel bilgileri silen gece işi (telefon ve kimlik numarası toplanmaz) |
| `uygunsuzluk-dof` | "Kalite / iş güvenliği uygunsuzluklarını kaydedelim", "düzeltici faaliyetleri takip edelim" | Uygunsuzluk kaydı (kaynak, önem, dosya), kök neden, sorumlu ve terminli düzeltici faaliyetler, **sunucuda** zorlanan durum akışı (açık, faaliyet planlandı, doğrulama, kapandı; açık faaliyetle kapanmaz), "Faaliyetlerim", geciken faaliyet için sorumluya sabah e-postası, Excel |
| `musteri-ziyaret` | "Saha ekibinin müşteri ziyaretlerini raporlayalım" | Ziyaret kaydı (tür, not, sonuç, sonraki adım ve tarihi), "Ziyaretlerim", "Ekip ziyaretleri" (yönetici, organizasyon şemasından **sunucuda**), yaklaşan sonraki adımlar, Excel; müşteri listesi ERP'den DEXA ile okunur, sorgu bağlanana kadar müşteri elle girilir ve ekran bunu söyler |
| `hedef-takibi` | "Ekip hedeflerini ve ilerlemeyi takip edelim", "çeyreklik hedefler" | Dönemler, hedefler (sorumlu, ağırlık), ölçülebilir sonuçlar ve aksiyonlar, **sunucuda** hesaplanan ilerleme, değer güncellemesinin geçmişi, "Hedeflerim", "Ekip panosu", grafikli dönem panosu, kapanan dönemin salt okunur olması, Excel |
| `envanter` | "Stok / malzeme / demirbaş takibi", "azalınca haber versin" | Kalemler, giriş, çıkış ve sayım hareketleri (stok eksiye düşmez), en az miktar uyarısı (sorumluya e-posta), konuma göre grafik, sabah stok kontrolü |
| `blank` | Hiçbiri uymuyor | Kişisel notlar örnekli en küçük iskelet |

Keşif görüşmesindeki cevaplardan seçin ([keşif görüşmesi](/docs/discovery.md)):

- **Bir şeyin belli aralıklarla yapılması** (bakım, kontrol, yenileme) gerekiyorsa `bakim-takvimi`; süresi dolan bir
  belge kişiye bağlıysa `egitim-sertifika`.
- **Bir yeri bir listeye göre kontrol edip puanlamak** için `saha-denetimi`; bulunan bir sorunun **çözülmesini
  izlemek** için `uygunsuzluk-dof`. İkisi birlikte isteniyorsa (denetimde çıkan sorun faaliyete dönüşsün) baskın olanı
  seçin ve ötekinin kuralını şablona ekleyin.
- **Kurum dışından gelen kişiyi kaydetmek** için `ziyaretci-kaydi`.
- **Müşteriyle yapılan görüşmeyi kaydetmek** için `musteri-ziyaret`.
- **Hedef, ölçü ve ilerleme** konuşuluyorsa `hedef-takibi`.
- **Sayı/miktar tutup azalıp çoğalanı izlemek** için `envanter`.
- **Birinin onayı** gerekiyorsa uygulamaya onay akışı yazmayın: onay Devoplus İş Akışı'nın işidir. Uygulama yalnız
  kaydı tutar; onay gerekiyorsa kullanıcıya İş Akışı'nı önerin.
- Şüphedeyseniz kullanıcıya şablonun ne yaptığını iş diliyle anlatıp "buna yakın mı?" diye sorun.

Kullanıcıya şablon adı, dosya ya da kod göstermeyin; "bakım takvimi uygulamasıyla başlayıp sizin alanlarınızı
ekleyeceğim" gibi anlatın.

## Üretimden sonra ilk iş

1. Üretilen `AGENTS.md`'yi okuyun: en üstte **şablona özgü bölüm** (dosya haritası + bozulmaması gereken kurallar)
   vardır.
2. Keşif özetine göre değiştirin:
   - **Alanlar ve seçenekler:** `one.data.json`, sonra `pnpm data:generate` (migration ve tipler elle yazılmaz;
     bkz. [veri modeli](/docs/data-model.md)). İlk yayından önce seçenek listelerini netleştirin.
   - **Kurallar** (süre, eşik, puan, durum akışı, saklama süresi): şablonun saf kural dosyası (`schedule.ts`,
     `score.ts`, `certificate.ts`, `visitor.ts`, `capa.ts`, `visit.ts`, `progress.ts` ya da `stock.ts`) ve yanındaki test.
   - **Ekran metinleri:** `src/shell.ts` (Türkçe + İngilizce birlikte).
   - **Devoplus yapay zekası:** manifest `agent.tools` + `src/agent.ts` + `AGENT_GUIDE.md` üçü birlikte
     ([yapay zeka](/docs/ai.md)).
   - **README:** teknik olmayan kullanıcı için; şablonun "Neleri değiştirebilirsiniz" bölümünü uygulamaya göre
     güncelleyin.
3. Gereken izinleri isteyin ([erişim talebi](/docs/access-requests.md)): kayıt, kurulum, şablonun beyan ettiği yetki
   alanları (`orgschema.read`, `mail.execute`; ziyaretçi kaydında `push.execute`) ve uygulama içi rol (`One.<Uygulama>.Manage`)
   için `app-permission` ataması. Sabah e-postası gönderen şablonlarda kurulumda **arka plan işi servisi** olarak
   e-postanın da onaylanması gerekir ([zamanlanmış görev](/docs/jobs.md) §4).
4. `pnpm test`, `pnpm type-check` ve `pnpm build`'i koşturun; sonra [yayın](/docs/publishing.md).

## Bilinmesi gerekenler

- Zamanlanmış işler **kullanıcısızdır** ve Devoplus servislerini uygulamanın kimliğiyle çağırır. Sabah e-postası
  gönderen şablonlar (`bakim-takvimi`, `egitim-sertifika`, `uygunsuzluk-dof`) e-postayı manifestte `jobs.services`
  içinde beyan eder; kurulumda portal yöneticisi onaylamadıysa iş e-postayı göndermez, "onay gerekiyor" diye kaydeder
  ve ertesi gün yeniden dener ([zamanlanmış görev](/docs/jobs.md)). Bir çağrıda gönderilen e-posta sayısı sınırlıdır;
  şablonlar kişi başına tek e-postayı birkaç kişiyle sınırlar, kalanlar ertesi güne kalır.
- Hatırlatmalar **günde bir kez** gider: şablon önce damga koyar, gönderim düşerse damgayı geri alır.
- Şablonlar bir şeyi yazmadan önce denetliyorsa (kaydın durumu, kişinin sorumluluğu, üst kaydın silinmemiş olması) o
  denetim yazımla aynı veritabanı ifadesinde de durur. Uygulamayı genişletirken bu kuralı koruyun: yeni yazımı
  `src/lib/record.ts` ile yapın (`AGENTS.md` "Yazım kuralı"); "önce oku, sonra yaz"a çevirmeyin.
- Listeler sessizce kesilmez: görünürlük ve sayım kesik bir listeden hesaplanmaz, kısaltılan gösterim kesildiğini söyler.
  Ekranda açılır liste ve süzgeç seçeneklerini tek sayfalık istekle değil `loadAll` ile bütün sayfalardan kurun; hazır
  liste uçları sayfa başına en çok 200 kayıt verir (`AGENTS.md` "Liste kuralı").
- `musteri-ziyaret` ERP sorgu anahtarını **içermez**; anahtarı ve kolon adlarını `one_dexa_queries` (ya da
  `one dexa queries`) listesinden alın, uygun sorgu yoksa `new-query` gönderin; sonra `AGENTS.md`'deki adımlarla bağlayın (manifest `dexa.read`, `services.dexa.queryKeys`, sorgu erişim talebi).
  Anahtarı tahmin etmeyin.
- Devoplus yapay zekası araçları yalnız uygulamanın kendi veritabanını okur; kayıt açan, onaylayan ya da silen araç
  şablonlarda bilinçli olarak yoktur.
- Menü sekmeleri herkese görünür; yetkisi olmayan kişi yönetim sekmelerinde bir bilgi notu görür, asıl kapı her uçta
  sunucudadır.
- E-posta, kullanıcının Portal'daki **"İzinleri incele"** onayına bağlıdır; izin yoksa işlem yapılır, e-posta gitmez
  ve ekran bunu söyler.