@appaflytech/zeyrek-ai-mcp 0.0.36 → 0.0.40

package/dist/resources/guides/bpm.md

@@ -0,0 +1,691 @@
+# Süreç Rehberi — Hibrit BPM
+
+İnsanı bekleyen, durumlu iş süreçleri: tanım, yürütme, görev kutusu, bölge olayları. Süreç
+**workflow değildir**: workflow tek istekte biten sunucu akışıdır (`platform_guide('workflow')`);
+süreç günlerce insan görevlerinde, zamanlayıcılarda ve dış olaylarda bekler, her adımı hash zincirli
+bir defterde tutar. Bir süreç düğümü gerektiğinde workflow'u `service` düğümüyle çağırır.
+
+## Başlangıç
+
+Sıra her zaman aynıdır:
+
+1. **İş nesnesi** — sürecin konusu olan entity (`gorevler`, `satinalma_talepleri`). Süreç o satırın
+   üstünde koşar: ifadelerde `row`, `writeBack` ile satıra yazar.
+2. **Tanım** — `process_definition_create`. Önce altın örneği okuyun:
+   `ngapps://examples/bpm-gorev-kontrol` (satır olayı → görev → onay → iade),
+   `ngapps://examples/bpm-satinalma` (seviye servisi → sıralı yönetici zinciri → paralel kontrol),
+   `ngapps://examples/bpm-iso-dokuman` (onay birimi → okuma turu → düzenleme isteği bölge olayı).
+3. **Önizleme** — `process_definition_preview` ile önce `definition` gövdesiyle doğrulama, kayıttan
+   sonra `id` + `subjectRowId` ile kuru koşu: her insan adımında kimin görev alacağını görürsünüz.
+4. **Yayın** — `process_definition_publish`. Taslak aktif olur; production'a yayın yoktur (BPM-001).
+5. **Yürütme** — `process_execute(slug, subjectRowId, vars, asUser)`; görevler `process_task_list(tab,
+   asUser)` kutusunda, eylemler `process_task_update(id, action, version, asUser)`, defter
+   `process_instance_get(id, view: 'timeline')`.
+
+Tanımı düzeltirken tam gövdeyi yeniden göndermeyin: `process_definition_get` (outline) →
+`process_definition_patch` (`/nodes[id=<düğüm>]/…` seçicileriyle).
+
+## Tanım modeli
+
+```jsonc
+{
+  "slug": "gorev-kontrol",                     // kebab-case, uygulamada benzersiz; yayından sonra değişmez
+  "name": "Görev kontrol",                     // tek dil düz metin; çok dilli nesne gelirse gateway düz metne çevirir
+  "description": "…",                          // ZORUNLU (BPM-002), tek dil düz metin
+  "analysis": { "purpose": { "en": "…", "tr": "…" }, "summary": { "en": "…", "tr": "…" } }, // ZORUNLU (BPM-023) — § Analiz dokümanı
+  "subject": { "entity": "gorevler" },         // entity slug ya da id
+  "singleton": "per-subject",                  // aynı satırda açık örnek varsa yeni başlatma mevcut örneği döner
+  "withdrawPolicy": "before-first-decision",   // never | before-first-decision | anytime
+  "history": "full",                           // full | audit | minimal — defter ayrıntısı
+  "sod": ["not-initiator"],                    // başlatan kendi onayını veremez
+  "params": { "esikTutar": { "default": 50000, "type": "number", "editable": "params" } },
+  "emailActions": false,                       // true: onay e-postasına tek kullanımlık onay/ret bağlantısı
+  "nodes": [ … ],
+  "edges": [ ["baslangic", "bildir"], { "from": "karar", "to": "red", "condition": "!vars.uygun" } ],
+  "on": [ … ]                                  // süreç düzeyi olay işleyicileri
+}
+```
+
+Kurallar:
+
+- **Her düğüm ve tanımın kendisi `description` taşır** (BPM-002, block). Kutuda ve tasarımcıda
+  görevin ne istediğini anlatır; mekanizmayı değil niyeti yazın. Gerçek bir tuzak varsa `caution`.
+- **Tanım ve her düğüm iki dilli `analysis` taşır** (BPM-023, block): Studio'nun Analiz dokümanı
+  sekmesi onu gösterir. Biçim ve yazım kuralı § Analiz dokümanı.
+- Düğüm `id`'leri kebab-case ve tanım içinde benzersizdir; kenarlar ve `back-to:` bu id'lerle bağlanır.
+- **Adımın okunabilir adı (`resultKey`) snake_case'dir, kebab-case DEĞİL.** `id` kenarların anahtarıdır,
+  ifadede okunmaz; ifade sonucu adıyla ve noktayla okur: `vars.tasks.ik_kaydi.action`,
+  `vars.approvals.yonetici_onayi.outcome`. Her `user-task` ve `approval` düğümüne id'nin snake_case'ini
+  `resultKey` olarak yazın (`"id": "ik-kaydi"` → `"resultKey": "ik_kaydi"`). Köşeli parantezle kebab
+  anahtar okumayın — `vars.tasks?.['ik-kaydi']?.action` yazmayın; Studio kartı ve ifade tamamlaması
+  adı snake_case gösterir, kebab anahtar yalnız eski ifadeler bozulmasın diye yazılır.
+- Tam bir `start` üst düzeydedir; bölgenin içinde `start` yoktur.
+- İfadeler Jint'tir: `vars` (süreç değişkenleri), `row` (iş satırı), `previousRow` (satır olayında),
+  `initiator` (başlatan kullanıcı id). `{{…}}` yer tutucu yalnız şablon metinlerinde ve `chain` argümanında.
+- Kısa biçimler gateway'de tam biçime çevrilir ve yanıtta `gatewayNormalized` ile bildirilir:
+  `"sla": "P2D"` → `[{ "duration": "P2D" }]`, `"assignee": "unit-manager of initiator"` → nesne,
+  `[from, to]` → `{ from, to }`.
+- Parametre (`params`) varsayılanları başlatmada `vars`'a yazılır; başlatma girdisi üstüne biner.
+- `history` defterin ayrıntısıdır: `full` her olayı, `audit` kararları, görev yaşam döngüsünü (açılma,
+  üstlenme, bilgi isteme), SLA ihlallerini ve yorumları, `minimal` yalnız başlangıç/bitiş, kararlar,
+  tamamlanan görevler ve satıra yazmaları tutar — `minimal`de raporun ret döngüsü ve SLA ihlali boş kalır.
+
+## Analiz dokümanı
+
+Studio'da süreç tasarımcısının alt bilgi çubuğundaki **Analysis document** paneli, süreci hiç görmemiş bir iş
+kullanıcısına her adımda ne olduğunu anlatır. Kullanıcının çizdiği süreçte metin şablonla üretilir;
+**AI'ın yazdığı süreçte metni siz yazarsınız** ve gateway zorunlu tutar (BPM-023, block —
+create, update ve patch'in sonucu denetlenir).
+
+```jsonc
+"analysis": {                                  // tanım düzeyi
+  "purpose": { "en": "…", "tr": "…" },         // bu süreç neden var, hangi ihtiyacı karşılıyor
+  "summary": { "en": "…", "tr": "…" }          // baştan sona ne oluyor, 2-3 cümle
+}
+"analysis": {                                  // her düğüm, bölge içindekiler dahil
+  "what": { "en": "…", "tr": "…" },            // bu adımda ne yapılıyor, kim yapıyor
+  "data": { "en": "…", "tr": "…" },            // hangi değerleri kullanıyor, nereden geliyor, ne yazıyor
+  "why":  { "en": "…", "tr": "…" },            // bu adım neden gerekli; olmasa ne ters gider
+  "example": { "en": "…", "tr": "…" }          // gerçek hayattan küçük bir örnek: bu adım bir vakada ne yapar
+}
+```
+
+Yazım kuralı — sekmeyi okuyan kişi teknik değildir:
+
+- **İş diliyle, 1-3 kısa cümle.** Alan ve id yerine etiketini yazın: "talebin tutarı", `row.tutar`
+  değil; "birim yöneticisi", `unit-manager of initiator` değil. İfade ya da JSON yazmayın.
+- **`what` eylemi ve eylemi yapanı söyler**, mekanizmayı değil: "Finans ekibinden biri bütçeyi kontrol
+  eder ve onaylar ya da reddeder."
+- **`data` somut değerleri sayar**: okunan alanlar, dal koşulunun baktığı değer, yazılan sonuç. Değer
+  kullanmayan adımda bunu söyleyin: "Değer kullanmaz; yalnız süreci bitirir."
+- **`why` gerekçeyi verir**: kural, risk, denetim ihtiyacı — `description`'ın tekrarı değil.
+- **`example` bu adımı somut bir vakayla gösterir**: adı, tutarı olan bir kişi ve talep ("Ayşe'nin
+  yöneticisi Mehmet, 25.000 TL'lik dizüstü talebini kutusunda görür ve onaylar"). Bütün adımlarda aynı
+  vakayı sürdürün ki okuyan akışı tek hikâye gibi izlesin; dal ya da ret yolundaki adımda vakanın o
+  yola nasıl düştüğünü söyleyin ("tutar 60.000 TL olsaydı talep CFO onayına giderdi").
+- **İki dil aynı şeyi söyler**; biri diğerinin çevirisidir, `en` kısaltılmış değildir.
+- Var olan bir sürecin analizi yoksa her yazma BPM-023'e takılır: aynı çağrıda eksikleri ekleyin
+  (`process_definition_patch` ile `add /nodes[id=x]/analysis`).
+
+Örnek — satın alma onayındaki bir `approval` düğümü:
+
+```json
+"analysis": {
+  "what": { "en": "The requester's unit manager reviews the request and approves or rejects it.", "tr": "Talep sahibinin birim yöneticisi talebi inceler; onaylar ya da reddeder." },
+  "data": { "en": "Reads the title, category and amount of the request. A rejection ends the process.", "tr": "Talebin başlığını, kategorisini ve tutarını okur. Ret süreci bitirir." },
+  "why": { "en": "No money is spent without the manager knowing about it.", "tr": "Yöneticinin haberi olmadan harcama yapılmasın diye." },
+  "example": { "en": "Ayşe's manager Mehmet sees her 25,000 TL laptop request in his inbox and approves it the same day.", "tr": "Ayşe'nin yöneticisi Mehmet, 25.000 TL'lik dizüstü talebini kutusunda görür ve aynı gün onaylar." }
+}
+```
+
+## Düğümler
+
+Her türün alanları ve örneği: `process_step_schema(type)`. Özet:
+
+**start** — `trigger: row-event | manual | api | schedule | sub-process | message | signal`, `entity`, `operation`,
+`condition`. `row-event` bağlıdır (ölçüldü 2026-09-18): aktif sürümün konu entity'sine
+(`subject.entity`; start düğümündeki `entity` eşleşmeye BAKILMAZ) ilk start düğümünün `operation`'ı
+(boşsa `create`; `delete` hiç başlatmaz) yazılıp `condition` sağlanınca örnek kendiliğinden açılır —
+yetki denetimi bastırılır, başlatan satırı yazan kullanıcıdır. Yayından önce yazılmış satırlar
+başlatmaz. Aynı olaya workflow `process` adımıyla ikinci başlatma eklemeyin — iki örnek açılır.
+Kendiliğinden başlatan yalnız `row-event` ve `message`tır; `manual`, `api`, `schedule`, `sub-process` ve
+`signal` belgeleyicidir — örnek açık bir başlatmayla açılır (`process_execute`, uygulamanın Süreçler sayfası,
+`Page.bpm.start`, üst sürecin `sub-process` düğümü, bitiş düğümünün `schedule`'ı). Sinyal bugün yalnız bekleyen
+örneği ilerletir, yeni örnek açmaz.
+
+**user-task** — insan görevi. `assignee` zorunlu. `mode: claim` (varsayılan) adaylardan birinin
+üstlenmesini bekler; `mode: individual` her kişiye ayrı görev açar ve `join: all | any | force-complete`
+ile birleşir. `actions[]` özel eylemler: `completes: true` görevi bitirir (`evidence: read-proof`
+defterde okuma kanıtı bırakır), `completes: false` görevi açık bırakıp `emits: signal:<ad>` yayar.
+`completeOn { trigger: row-event, operation: update, condition }` görevi satır değişince bitirir.
+`requestInfo: true` başlatandan bilgi isteme; `allowReassign`, `external: true` (dış kullanıcı görevi,
+yalnız atanan görür), `revisionBound: true` (bölge yeniden başlarsa eski görev `superseded`),
+`undoWindow: "PT5M"` (karar geri alma). Tamamlanan görevin sonucu
+`vars.tasks.<resultKey>` altına `{ outcome, action, completedBy, payload }` olarak yazılır.
+`resultKey` yoksa anahtar id'nin snake_case hâlidir (`teslimat-kontrol` → `vars.tasks.teslimat_kontrol`);
+eski ifadeler bozulmasın diye sonuç kebab-case id altına da yazılır, ama ifadeyi hep snake_case
+ve noktayla yazın — slug değil, `vars.tasks?.['teslimat-kontrol']` gibi köşeli parantezli kebab değil. **Süreç kurarken her `user-task` ve `approval` düğümüne snake_case bir
+`resultKey` verin** — id kebab-case kalır: `{ "id": "teslimat-kontrol", "resultKey": "teslimat_kontrol" }`
+ve geçitte `vars.tasks.teslimat_kontrol.action === 'sorunlu'`. Ad harf, rakam ve `_`'dır; tire yok,
+aynı tipte benzersiz (başka adımın id'si ve snake_case'i de dolu sayılır). Yazılmamış bir adı okumak
+(`vars.tasks.teslimatKontrol` — camelCase, ne ad ne id) `undefined` verir ve geçit hiç o dala gitmez.
+
+**approval** — onay görevi + politika:
+`policy: sequential | all | any | quorum(n) | majority | weighted(0.6)`,
+`rejectPolicy: any-reject | quorum(n) | majority`, `onReject: end | back-to:<düğüm> | restart`,
+`commentRequired: true | "outcome === 'rejected'"`, `selfApproval: escalate | skip | allow`,
+`weights: { "position:P-SATIS": 2, "role:yk-baskani": 3 }`, `veto: ["user:…"]`, `abstain: true`,
+`countAs: "vars.onaySayisi"`. `sequential` sonraki halkayı **karar anında** çözer (geç bağlama).
+`rejectPolicy` yazılmazsa: sequential/all ilk retle, any herkes reddedince, quorum/majority eşiğe
+ulaşılamaz olunca reddeder. Karar `vars.approvals.<resultKey>` altına yazılır; `resultKey` yoksa
+anahtar id'nin snake_case hâlidir (`grup-onayi` → `vars.approvals.grup_onayi`; kebab-case id altına
+da yazılır) — yine de açık bir snake_case ad verin (`"resultKey": "grup_onayi"`).
+**`back-to:` bir SIÇRAMADIR ve düğümün `writeBack`'ini ÇALIŞTIRMAZ** (yalnız onaylanan dal ve bitiş
+düğümü geri yazar). "Ret satıra durum yazsın" isteyen tasarım, ret hedefini geri yazmayı yapan bir
+`script` düğümü yapar ve oradan asıl hedefe bir kenar çeker (ölçüldü 2026-09-21, S-6 CAPA).
+
+**service** — workflow çağrısı: `workflowId` (zorunlu; yalnız `workflowSlug` yazılan düğüm önizlemede ve yayında
+`DefinitionInvalid` alır — slug değişebilir, bağ kimlikle tutulur; yanıt ikisini birlikte döner), `input: { ad: "<Jint>" }`, `output: "vars.x"`,
+`retry: { count }`. Başarısızlık `retry.count` (varsayılan 3) sonra örneği `faulted` yapar.
+`runAs: system` gerekçesi `caution`'da durur (BPM-005). `input` anahtarları workflow'un **parametre DTO
+alanlarının `slug`'larıdır** (`dto_get` → `children[].slug`); platform onları alan kimliğine bağlar. DTO'da
+olmayan anahtar kayıtta, önizlemede ve yayında `ServiceInputUnknown` verir (mesaj geçerli parametreleri sayar).
+DTO alanı yeniden adlandırılınca tanım yeni adı gösterir, yayındaki sürüm de doğru anahtarla çağırır. Süreçte
+kullanılan alan `dto_update` ile silinemez (422 `ReferencedByProcess`). Parametre DTO'su olmayan workflow'un
+girdisi denetlenmez. Workflow gövdesindeki `input.x` adları elle güncellenir.
+
+**notify** — `to` (atama sözlüğü), `channels: ["inbox", "email"]`, `template { subject, body }`
+(`{{row.baslik}}`), `ackRequired`. Kutu bildirimi satırı aynı transaction'da yazılır.
+
+**gateway** — `kind: exclusive` (ilk doğru kenar, yoksa `default`), `parallel` (çatallanır;
+birleşmede gelen kenar sayısı kadar varış bekler), `inclusive` (koşulu tutan **her** kenar, hiçbiri
+tutmazsa `default`; birleşmede o gateway'e hâlâ ulaşabilecek token kalmayınca devam eder) ya da
+`event-based` (yalnız `wait`/`timer` düğümlerine gider; ilk gelen olay kazanır, diğer bekleyişler
+iptal edilir, defterde `event-gateway-resolved`).
+
+**timer** — `duration` (ISO) ya da `until` (Jint). `duration` **düz metindir, ifade
+değerlendirilmez**; beklemeyi bir parametreye bağlamanın tek yolu `until`'dır
+(`until: "new Date(Date.now() + vars.beklemeGunu * 86400000).toISOString()"`). **wait** — `message { name, correlationKey }` +
+`output: "vars.x"` (mesaj gövdesi), `signal: "<ad>"` (`process_trigger kind signal` ile gelir) ya da
+`link: "<ad>"` (yakalama noktası; gelen kenarı olmaz).
+
+**send** — `message { name, correlationKey: "<Jint>" }` + `input` (gövde) mesajı kuyruktan atar;
+alıcı yoksa `timeout: "PT10M"` (en çok `P1D`) boyunca tamponda bekler ve sonra açılan `wait` hemen
+tüketir. `link: "<ad>"` verilirse aynı kapsamdaki `wait { link }` düğümüne sıçrar. BPMN karşılığı
+*intermediate throw event*'tir (message ya da link) — bildirim değildir ve **e-posta göndermez**; mesaj kuyruktan
+aynı adla bekleyen `wait`'e ya da mesajla başlayan sürece gider, e-posta `notify { channels: ["email"] }` işidir.
+Studio adımı kipine göre adlandırır: `message` → **Mesaj gönder** (sinyal anteni), `link` → **Bağlantıya atla** (ok); yakalayan
+`wait { link }` → **Bağlantı noktası** (ok); palette kutucuğu **Mesaj**. Kullanıcıya bu adlarla anlat.
+**manual** — sistem dışı iş; görev satırı açmaz, `process_instance_update { operation: skip }` ile geçilir.
+Süre dolunca: `sla[]` ya da `deadline` (Jint tarih) ile `skipOnDeadline: true` adımı geçer, `onTimeout: "end:<sonuç>"`
+örneği o sonuçla bitirir; ikisi de yoksa adım yöneticiyi bekler.
+**script** — `code` Jint (2 sn, dosya/HTTP/CLR yok); `vars.x = …` yazar, son ifade `output` yoluna. Globaller
+`vars`, `row`, `previousRow`, `initiator`.
+**case** — `caseSlug` (aktif sürümü olan vaka tanımı; yayında denetlenir, yoksa `CaseUnknown`),
+`input { vakaDosyasıÖğesi: "<Jint>" }` (tanımsız öğe düşer), `output: "vars.x"` (vaka kimliği). Vakayı iş satırı
+üzerinde, örneği başlatan adına açar ve **beklemez**; defterde `case-started`.
+**document** — şablondan belge üretir ve beklemez; alanları § Bağlayıcı ve belge'de. `output` → `{ fileId, name }`.
+
+**sub-process** — ayrı örnek başlatır ve bekler: `processSlug`, `subject { rowId: "<Jint>" }` (farklı iş
+nesnesi), `input`, `output`, `binding: latest (varsayılan) | deployed | v:<n>` (`latest` ve `deployed` bugün ikisi de
+aktif sürümü okur; sabitlemek için `v:<n>`), `forEach { entity, where: "item.aktif === true",
+batch }` (partili başlatma, hepsi bitince devam). Alt örnek kuyruktan başlar; üst örnek
+`sub-process-completed` ile ilerler.
+`v:<n>` yayında **o sürümün kimliğine** bağlanır; numara ortamın yerel sayacıdır ve merge/promote
+ara sürümleri taşımaz. Aktarım bağı hedefte **aynı içerikli** sürüme yeniden yazar (numara değişebilir,
+ör. development `v:3` → production `v:2`); hedefte o içerik yoksa promote 422
+`SubProcessBindingNotCarried` ile durur — önce çağrılan sürümü taşıyın ya da bağı değiştirin.
+
+**region** — uyarlanabilir blok ve olay kapsamı: `nodes`, `edges`, `limits { maxSteps, nodeTypes,
+assigneeRules }`, `on[]`. Girişler iç kenarlarda hedef olmayan düğümlerdir; iç tokenlar bitince dış
+kenardan devam eder.
+
+**end** — `outcome`, `writeBack`, `reopenWindow: "P30D"`. Bölge içindeki `end` yalnız o kolu kapatır.
+`kind: terminate` bütün dalları iptal eder, `onCancel` workflow'unu koşar ve `terminated` sonucuyla
+biter (bölge içinde yalnız o bölgeyi kapatır). `kind: error` + `code` en yakın bölgenin
+`on: [{ event: "error:<code>", afterHandlers: "exit-region:<hedef>" }]` işleyicisine sıçrar; yoksa süreç
+`error:<code>` sonucuyla biter ve üst sürecin `sub-process` düğümündeki aynı biçimli `on[]` yakalar
+(yakalamazsa üst örnek `faulted`).
+
+`writeBack { alan: "<Jint>" }` her düğümde düğüm çıkışında iş satırına yazar; satır otomasyonları bu
+yazmada tetiklenmez (sonsuz döngü koruması).
+
+## Atama sözlüğü
+
+`assignee` nesnesi `{ rule, arg, of, unit, fallback, selfApproval, dedupe, sod, expand, items }` ya da
+kısa biçim `"rule:arg of <referans>@unit:<kod>"`. Referans (`of`): `initiator` (varsayılan),
+`subject-field:<alan>`, `user:<id>`, `vars.<yol>`.
+
+| Kural | Çözüm |
+|---|---|
+| `initiator` | başlatan |
+| `subject-field:<alan>` | iş satırındaki kullanıcı id'si |
+| `user:<id>` | sabit kişi |
+| `unit-manager` | referansın birincil pozisyonunun birimi → `manager_position_id` → aktif sahip (vekil `acting` önce). Referans birimin yöneticisiyse bir üst birimin yöneticisi. Pozisyon boşsa üst birime tırmanır (`source: escalation`) |
+| `parent-unit-manager` | birincil birimin üst biriminin yöneticisi |
+| `ancestor-manager:<tip>` | en yakın ata birim; `unit_type`, `function_code` ya da `code` eşleşir (`mudurluk`) |
+| `chain:<n>` · `chain:{{vars.seviye}}` | referanstan yukarı n yönetici, sıralı; `dedupe: true` aynı kişiyi atlar |
+| `role:<slug>` | rol adayı + rolün pozisyon sahipleri ve kullanıcıları; `mode: claim` ile grup görevi |
+| `unit-members:<kod>` | birimin (`includeDescendants`) pozisyon sahipleri; aday grup |
+| `position:<kod>` | pozisyonun aktif sahibi; boşsa üst pozisyon (`strategy: functional` işlevsel hat) |
+| `list` | `items[]` ya da `of` — **`of` burada REFERANS DEĞİL Jint İFADESİDİR** (`vars.liste`, `row.birimler.split(",")`); `subject-field:x` yazmak motoru 500 JavaScriptException ile düşürür. Değerler `["user:…", "unit:satis", "position:P-X", "role:…"]`, `expand: members` |
+| `expression` | Jint → id ya da id dizisi (sıra korunur) |
+| `previous-approver-manager` | Görev sayacının ihlalinde (`onBreach`) atanmış görevin asıl sahibinin yöneticisi — zincirde bir üst halka, kökte `admin-queue`; düğüm/süreç sayacında, grup görevinde ve ihlal dışında son onaylayanın yöneticisi |
+| `chain-until-authority` | `{ rule: 'chain', arg: 'until-authority', category, amount: 'vars.tutar' }` — yukarı yönetici zinciri, limiti (`process_authority_limit_*`; pozisyon limiti kişiyi ezer) tutarı karşılayan ilk halkada durur; hiçbiri yetmezse tüm zincir + uyarı |
+| `partner:<kod>` | kabul edilmiş partner ilişkisinin (Organization.API `organizations/{id}/partners`) karşı kurumu aday olur (`candidates: partner`); ilişki etkin değilse ya da süreç izinli listede yoksa çözülmez (fallback). Doğrulama `PartnerUnknown`; partner kullanıcısının görevi açması henüz yok |
+| `pool:<kod>` | havuz (`process_pool_*`) stratejisi: `round-robin` · `least-loaded` (açık görev / haftalık kapasite — saat, yalnız ağırlık: 20 saatlik kişi 40 saatlik kişinin yarısı kadar iş alır) · `skill-match` (`skills: ["vars.dil"]` + havuz becerileri) · `manual` (havuzda bekler). İş yükü kaydında `maxOpenTasks` doluysa açık görevi o sayıya ulaşan kişi manual dışı stratejilerde seçilmez; boşsa tavan yoktur. Havuzu kullanan süreçler `process_pool_list` çıktısında `usedBy`; kullanılan havuz silinemez (`process_pool_update { id, remove: true }` → 422 `ReferencedByProcess`) |
+
+Çözüm sırası: strateji → SoD (`not-initiator`) → `selfApproval` → pasif kullanıcı süzgeci (kullanıcı
+tablosunda olmayan kişi seçilmez; bitişi geçmiş pozisyon ataması sayılmaz) → **vekalet** (aktif
+vekaleti olan kişinin yerine vekil; görevde `principalUserId` asıl, zincir izlenmez, SoD vekile de uygulanır) → `dedupe`
+(vekil ikameden SONRA: vekil zincirde zaten varsa tek adım alır — asıl kişinin seviyesi vekilin kararıyla kapanır ve
+zincir bir halka kısalır; `chain:2`'de Murat→Selin vekaletiyle tek karar yeter) → `fallback`
+(`escalate` referansın yöneticisi, `role:<slug>`, varsayılan `admin-queue` havuzu). Kimse çıkmazsa görev
+`admin-queue` havuzuna düşer; süreç yöneticisi görür. Kim çıkacağını yayından önce
+`process_definition_preview(id, subjectRowId)` gösterir.
+
+## Yaşam döngüsü ve işletim
+
+**SLA ve takvim.** `sla: "PT8H"` ya da `[{ name, duration, calendar, stopOn: state-change, reminders: [0.5], onBreach: [{ notify | escalate | reassign+ | priority }] }]`;
+süreler iş takvimiyle (`process_calendar_*`; kod → birim → `default` → Pzt–Cum 08–18) hesaplanır. Tatil `{ date, name, workEnd }`: `workEnd` yoksa gün tam tatil, varsa yarım gündür ve süre o saate kadar sayılır (arife `workEnd: '13:00'`); `P1D` yarım güne düşer ve saat `workEnd`'i geçerse vade o günün `workEnd`'idir. Kullanılan takvim silinemez (`process_calendar_update { id, remove: true }` → 422); `default` ya da birim takvimi silinince zincirin sonraki halkası kullanılır — yani **`P5D` beş İŞ GÜNÜDÜR**, takvimde 7+ gün eder; senaryoda sayacı ihlal etmek için saati ona göre ilerletin (`{ clock: 'P10D' }`). **Sayaç yalnız `duration` ile kurulur:** `deadline` alanı platformun SLA şemasında YOKTUR (sessizce düşer) ve `duration`suz sayaç 422 `DefinitionInvalid` verir — vadeyi iş satırındaki bir tarihe bağlamanın yolu bugün yok (ölçüldü 2026-09-22, S-9 ECN). Görev `dueAt` ilk sayaçtır; kutu `priority DESC, dueAt ASC` sıralar, görevde `slaRatio`. Son sayaç ihlalinde
+`onTimeout: approve | reject | end:<sonuç>`, `join: force-complete`, alt süreçte `skipOnDeadline`. `reassign+` görevi asıl
+sahibinde bırakıp çözülen kişiyi aday ekler; doğrudan atanmış görevde ilk karar veren kapatır. Devralma yalnız
+`reassign+`'ın eklediği kişiye açıktır — kural adayı, gruptan üstlenilmiş ya da yeniden atanmış görevi devralamaz. Süreç düzeyi `sla`
+ihlali örneği `critical` yapar; `priorityRule` başlangıç önceliği. Askıya alma ve bilgi isteme sayacı durdurur.
+Timer'lar 15 sn'de bir taranır (Tenant.API job'u).
+
+**Servis hatası.** Servis düğümü başarısız olursa `retry { count, backoff: fixed | exponential, delay }` timer'la yeniden
+dener; son denemede örnek `faulted`. Müdahale `process_instance_update`: `retry` (yalnız faulted), `skip` / `jump`
+(`reason` zorunlu, defterde kırmızı satır, atlanan görevler iptal). Tanım düzeyi `onCancel` (servis düğümü biçimi:
+`workflowId`/`connector`/`ai`/`externalEngine` ve/veya `writeBack`; yalnız `workflowSlug` canlıda çözülmez) iptalde, geri çekmede ve `terminate` bitişinde telafi koşar; `writeBack` ifadesi
+`cancel.cause`'u (`cancelled` · `withdrawn` · `terminated`) okur — geri çekilen talebin durumunu iş satırına böyle
+yazın: `"onCancel": { "writeBack": { "durum": "cancel.cause === 'withdrawn' ? 'geri-cekildi' : 'iptal'" } }`.
+Terminate bitişinde bu `writeBack` önce, bitiş düğümününki sonra koşar. Telafi başarısızsa örnek kapanmaz, `faulted` kalır.
+
+**Vekalet ve devir.** `process_delegation_create { toUserId, startsAt, endsAt, processSlugs, onBehalfOf }` —
+başkası adına açmak birim/üst birim yöneticiliği ya da `process.manage` ister; vekilin kesişen tarih ve süreçte bitmemiş
+vekaleti varsa BPM-008.
+Ayrılan kullanıcı: önce `process_handover_preview(userId)`, sonra `process_handover_create { decisions[], force }`
+(`force`: kararsız assigned-tasks yöneticiye ya da admin-queue'ya, candidate-tasks gruba);
+açık görevi olan birim kapatılamaz (`OpenTasksExist` 422). Yönetici değişince `rebindOnManagerChange: true`
+tanımlarında üstlenilmemiş yönetici görevleri yeni yöneticiye taşınır; üyelik değişince aday görevler yeniden hesaplanır.
+Servis adımı yerine workflow `process` adımı `processOperation: delegate` ile izin süreci vekalet yazar.
+
+**Toplu işlem.** `process_batch_execute`: `start` (100.000 satır, arka planda) · `reassign` · `extend-due` · `cancel`
+(en çok 500 görev) → `process_batch_get`; `process_batch_update { operation: undo }` yalnız reassign/extend-due.
+
+**Bildirim.** Bildirimler outbox'tan (15 sn) kanallara gider: `inbox` (hub `/hubs/process-notifications`),
+`socket` (`task-changed`), `email`; kanal hatasında 1/5/25/125 dk sonra yeniden, 5 denemede bırakılır. Aynı
+`dedupeKey` ile okunmamış bildirim tazelenir. Tercih `process_preference_update` (`immediate | digest | sla-only`,
+sessiz saat, özet saati). `process_instance_update { operation: watch }` karar/kapanış bildirimlerini izletir;
+görev yorumunda `@<kullanıcı-id>` bahsetme bildirimi üretir.
+
+**Tetikleyiciler.** `process_trigger { kind: message, name, correlationKey }` bekleyen `wait` düğümünü ilerletir ya da
+mesaj başlangıçlı tanımı başlatır; anahtarsız mesaj yalnız anahtarsız bekleyen örneklere gider ve `broadcast: true` ister.
+Dış sistemden gelen webhook `POST bpm/webhooks/{slug}`: `X-Zeyrek-Signature: sha256=HMAC(sır, "{timestamp}.{slug}.{gövde}")`,
+`X-Zeyrek-Timestamp` (±300 sn) ve `X-Zeyrek-Delivery` zorunlu; sır proje + ortam + slug başına türetilir ve
+`GET bpm/webhooks/{slug}/secret` (`process.manage`) ile alınır. Giden olaylar için `process_webhook_subscription_create` (HMAC imzalı CloudEvents).
+
+## Bölge olayları
+
+```jsonc
+"on": [ { "event": "signal:duzenleme-istegi",      // signal:<ad> | membership-added | subject-changed
+          "interrupt": false,                      // true: bölge tokenları ve görevleri askıya alınır
+          "handler": { "type": "sub-process", "processSlug": "dokuman-duzenleme", "input": { "istek": "event.form" } },
+          "afterHandlers": "restart-region",       // continue | restart-region | exit-region:<düğüm> | append
+          "restartWhen": "no-open-handlers",       // | each
+          "restartIf": "handler.outcome === 'approved'",
+          "restartScope": "all",                   // | pending-only
+          "cancelStale": "superseded" } ]          // | cancelled
+```
+
+- Olay en içteki açık bölgenin `on[]` listesinde aranır, yoksa `process.on[]`'da.
+- `handler.type`: `sub-process` (kuyruktan başlar, sayaç artar), `notify` (hemen), `append-task`
+  (bölgenin bekleyen bireysel görevine olaydaki kişi için tek görev ekler — `membership-added` ile).
+- `restart-region`: revizyon artar, açık görevler `cancelStale` ile kapanır, liste yeniden açılır;
+  tamamlanmış görevler ve `read-proof` satırları kanıt olarak kalır. Üç düzenleme isteği gelse de
+  `no-open-handlers` ile tek yeniden başlatma olur; reddedilen istek (`restartIf` yanlış) başlatmaz.
+- Olay tetiklemek: görevin `completes: false` eylemi (`emits`) ya da `POST bpm/signals
+  { instanceId, name, payload }`. `withdraw` ve `reopen` adları yerleşiktir.
+
+## Uyarlama
+
+`editable` dereceleri: `locked` (varsayılan), `params` (`editableParams` listesindeki alanlar),
+`open` (yalnız `region` — BPM-003). `open` bölgede eklenen düğümün atama kuralı
+`limits.assigneeRules` içinden seçilir (BPM-004, platform 422 `RuleNotAllowed`), düğüm türü
+`limits.nodeTypes`, adım sayısı `limits.maxSteps` ile sınırlıdır. Tanım yazarken dereceyi bilinçli
+seçin — dışarıdan değişmesi riskli adımı `locked` bırakın.
+
+**Uyarlama katmanı.** Uygulama yöneticisi aktif sürümün üstüne ortam başına bir JSON Patch yazar
+(tenant iş verisi; deployment ile taşınmaz). Okuma `process_override_get` (`editableScopes` hangi
+düğümün hangi derecede açık olduğunu, `outline` etkin tanımı gösterir; `view: 'studio'` salt okunur).
+Uygulama ekranı aynısını `process.override.*` sistem işlemleriyle yapar; `process.manage` ister, modül kurulumu vermez.
+Yazma `process_override_update` — yönetici adına (BPM-013; Studio jetonu 403): development'ta parolasız `asUserId` (users satır id'si) ya da `asUser` (uygulama jetonu):
+
+| Yol | İzin |
+|---|---|
+| `/params/<ad>/default` | parametre `editable: params` ya da `open` ise |
+| `/nodes[id=<düğüm>]/<alan>` (üst düzey) · `/nodes[id=<bölge>]/nodes[id=<adım>]/<alan>` (bölge çocuğu — seçici yalnız doğrudan çocukları bulur) | düğüm `params` ise yalnız `editableParams`; açık bölgenin derecesiz çocuğunda her alan. `id/type/editable/editableParams/limits`, `nodes` ve `edges` `editableParams`'ta yazsa da kilitli |
+| `/nodes[id=<bölge>]/nodes/-` (add) | bölge `open`; eklenen adım `editable`, `editableParams`, `limits`, `nodes` taşımaz, `region` değildir |
+| `/nodes[id=<bölge>]/nodes[id=<adım>]` | bölge `open` ve adımın kendi derecesi yok: `remove` ya da aynı `id`/`type` ile düz adım `replace` |
+| `/nodes[id=<bölge>]/edges…` | bölge `open` |
+| `move` · `copy`, bölgenin bütün `nodes` dizisi, diğer her yol | kilitli (BPM-010, 422 `RegionLocked` / `ParamNotEditable`) |
+
+Gateway yazmadan önce patch'i temel modele uygular ve istek gitmeden durdurur: kilitli yol BPM-010,
+bölgenin izin vermediği atama kuralı BPM-011 (liste atamasında kalemlerin kuralı), adım sayısı ya da düğüm türü sınırı BPM-012; bilinçli istisnada `policyOverride: true`. Platform ayrıca etkin tanımın referanslarını denetler (`RoleUnknown`, `WorkflowUnknown`).
+`mode: 'append'` (varsayılan) mevcut uyarlamanın sonuna ekler; iyimser kilit aktif sürüm +
+`overrideRevision`'dır (409 → `process_override_get`).
+
+**Yeni örnek, açık örnek.** Kayıttan sonra başlayan örnek uyarlamayla koşar; açık örnek eski
+zincirle biter. `operation: 'migrate-open'` açık örnekleri güncel uyarlamaya bağlar — açık düğümü
+(ya da açık bölgesi) etkin tanımda olmayan örnek atlanır ve `skipped` listesinde döner.
+`operation: 'reset'` varsayılana döner (yeni örnekler için).
+
+**Yeni sürüm yayını (üç yönlü birleştirme).** Geliştirici yeni sürüm yayınlayınca uyarlama yeni modele
+yeniden uygulanır: tüm yollar hâlâ izinliyse yeni revizyon açılır; bölge kaldırıldıysa ya da
+kilitlendiyse uyarlama `conflictState: conflicted` olur, `conflictDetail` hangi yolun neden
+düştüğünü söyler, tanım sahibine ve uyarlamayı yazana gelen kutusu bildirimi gider ve yeni örnekler
+varsayılanla başlar — sessiz ezme yoktur. Çözüm: `process_override_get` → patch'i yeni sürüme göre
+kurup `mode: 'replace'` ile yazın. `process_definition_preview(id)` kuru koşusu kayıtlı uyarlamayı içerir.
+
+## Yürütme ve kutu
+
+- Süreç sayfaları hazır gelir: projede ilk tanım (create, BPMN içe aktarma, klon) `bpm-management`
+  sistem şablonunu tanımın uygulamasına öneksiz kurar (sayfa slug'ı doluysa kurmaz) — `gorevlerim`, `gorev-detayi` (`?task=` /
+  `?instance=`), `surecler`, `surec-izleme`, `vekaletler`, `bildirimler`. Kompleks projede sayfalar
+  **Yetki kabuğuna** bağlanır ve `MENÜ` / `YÖNETİM` grupları Yetki kabuğu menüsüne eklenir (ikinci layout
+  doğmaz); Yetki kabuğu olmayan uygulamada kendi `Süreç kabuğu` layout'uyla gelir.
+  Proje başına bir kez kurulur, production'a dağıtılmaz. Sayfalar süreçten bağımsızdır (ad, form alanı,
+  özel eylem sunucudan gelir): yeni süreç ya da sürüm için sayfa YAZMAYIN, önce `page_list`.
+- Başlatma: `process_execute { slug, subjectRowId, vars, asUser }` (REST `POST bpm/processes/{slug}/start`)
+  → yeni örnek; tekil (`singleton`) tanımda aynı satırda açık örnek varsa mevcut örnek döner. Yetki
+  `process.start` (`process:<tanımId>`). production'a yürütme yok (BPM-001).
+- Örnek: `process_instance_get { id, view: 'timeline' }` (defter, güncel ve sonraki düğümler,
+  `isLedgerValid`); `process_instance_list`; müdahale `process_instance_update { operation: cancel |
+  suspend (reason zorunlu) | resume | withdraw (withdrawPolicy) | reopen (reopenWindow içinde) }`.
+- Olay: `process_trigger { instanceId, name, payload, eventId }` — bölge işleyicisi, `completeOn`,
+  `membership-added`.
+- Kutu: `process_task_list { tab: mine | group | delegated | started | done | all, asUser }`.
+  Görünürlük: atanan, aday (rol/birim/pozisyon/kişi), başlatan; `all` sekmesi `process.view-all` ya da
+  `process.manage` ister. `process_task_get` eylem listesini ve `version`'ı verir.
+- Görev eylemleri tek kapıdan: `process_task_update { action, actionId, payload, comment, version,
+  asUser }` — `claim` (sürüm denetimli; ikinci üstlenme 409 `TaskAlreadyClaimed`, bayat `version` 409 `AggregateVersionConflictException` — ikisinde de görevi yeniden okuyun),
+  `unclaim`, `complete` (özel eylem `actionId`), `approve`, `reject`, `request-info { question }` →
+  başlatana `provide-info` görevi, `provide-info { answer }`, `reassign { targetUserId, reason }`, `undo`.
+  kimlik zorunludur (BPM-006): development'ta parolasız `asUserId` — `/bpm/*` uçları platform şemasıyla `[Authorize]` edildiği için uygulama jetonu orada 401 alır — ya da `asUser`; yetki `task.complete` (`task:<tanımId>`); Studio jetonu görev eylemi
+  yapamaz.
+- Görev durumları: `open`, `claimed`, `waiting-info`, `suspended`, `unassigned`, `completed`,
+  `superseded`, `cancelled`, `expired`.
+- E-postadan karar: `emailActions: true` süreçte atanan kişiye onay/ret bağlantısı üretilir; bağlantı
+  tek kullanımlıktır, 72 saat geçerlidir, ikinci kullanım 410 döner.
+- Sayfadan: süreç çalışma zamanına **sistem mikroservisiyle** gidilir (BPM-022, warn).
+  `microservice_system_operation_list` `process.*` işlemlerini verir — kutu `process.task.list`, görev
+  `process.task.get/claim/unclaim/complete/request-info/provide-info/reassign/sign/assessment.start`, örnek
+  `process.instance.*`, `process.batch.*`, `process.delegation.*`, `process.handover.*`,
+  `process.notification(-preference).*`, `process.report.get`, uyarlama `process.override.*`, seçici listeleri
+  `process.definition.list/user.list/directory.get`. `microservice_create { source: 'system', systemOperation }`
+  ucu kurar; akışta `microservice` adımı çağırır, sonraki `code` adımı `Steps.<adım>.data`'yı okur, hatada
+  `Steps.<adım>.error` doludur (`Conflict`, gövde `.data`'da). Hata dalı kurmayın: ilk hatada akışı keser;
+  kayıt başına çağrı `condition` → `microservice` → `code` çevrimiyle yazılır. Yanıt REST `bpm/*` ile aynı alan
+  adlarındadır, listeler düz dizidir (`meta` yok). İzin boş işlemde kararı servis verir, `process.override.*`
+  `process.manage` ister. Hazır süreç sayfaları (`bpm-management` 1.1.0) bu desenle kuruludur; yeni ekran onların
+  akışını örnek alır.
+- Sistem işlemi olmayan işler eski yolda kalır ve BPM-022 onlarda uyarmaz: başlatma **Süreç** adımıyla
+  (`type: 'bpm'`; argüman `value` sütununda JSON METNİ — `args: { value: '{"operation":"start","processSlug":"satin-alma","subjectRowId":"Page.queryParams.id"}' }`,
+  düz `args.operation` DÜŞER; hata `fail` dalına) ya da `Page.bpm.start(slug, { subjectRowId, vars })`; vaka
+  `Page.bpm.cases.*`, belge `documents.print/generate`, `analytics`, `exportLog`, çevrimdışı kuyruk `offline.*`.
+  `start` slug tek uygulamadaysa tanımı bulur, iki uygulamada varsa `applicationId` ister. Sinyal adı
+  `signal:<ad>`; `completeOn` bekleyen görev yalnız `completeOn.trigger` adındaki sinyalle kapanır.
+
+## Simülasyon ve test
+
+`process_definition_preview` **yan etkisizdir**: transaction açmaz, satır/görev/bildirim yazmaz.
+
+- `definition` ile: platform doğrulayıcısı — bulgular `{ code, path, message }` (`path`:
+  `/nodes[id=onay]/assignee`).
+- `id` ile: doğrulama + kuru koşu. Kuru koşu başlangıçtan yürür; exclusive gateway `vars` ile karar
+  verir, paralel dallar ve bölge girişleri açılır, her `user-task`/`approval`/`notify` için atanan
+  kişiler (ad soyad) ve adaylar döner. `vars` servis çıktılarını taklit eder (`{ "seviye": 3 }`);
+  servis düğümü çalıştırılmaz. `send { link }` motor gibi yakalayan `wait { link }`'e sıçrar (not
+  `→ <id>`). Kuru koşu her adımı bir kez yürür: geri dönen bir döngü (düzeltme → yeniden kontrol) tekrar
+  yürünmez, dönülen adım rotanın sonunda `walked before; the dry run does not repeat it` notuyla yer alır.
+
+Yayından önce: `findings` boş, `steps` beklenen kişileri gösteriyor, her `back-to:` hedefi mevcut.
+
+### Senaryo test paketi
+
+Kuru koşu "kim yapar"ı söyler; **senaryo** bütün yolu gerçek motorla oynatır ve beklenenle karşılaştırır.
+
+- `process_scenario_create { fromInstanceId, name }` gerçek örneğin defterinden kaydeder: insan kararları,
+  zaman atlamaları, sinyal/mesaj/alt süreç sonuçları adım; servis çıktıları `stubs`; girilen düğümler,
+  atananlar, sonuç beklenen olur. Elle: `{ definitionId, name, given, stubs, steps, expect }`.
+- Adım başına **tek eylem**: `{ task: 'onay', as: 'user:<id>', action: 'approve' | 'reject' | 'complete', form }`
+  (görev verisi `form`'dadır, `payload` görev adımında okunmaz) · `action: 'sign'` — `signature` taşıyan düğümde
+  **zorunludur**: `approve`/`complete` adımı canlı uçtaki gibi 422 `SignatureRequired` alır ve senaryo kırmızı düşer
+  (ret ve çekimser imzasız geçer). Senaryo parola istemez ve `SignatureRecord` yazmaz; defterine düğümün
+  `meaning`/`level`'ıyla bir `TaskSigned` satırı düşer (ölçüldü 2026-09-22, S-7 sözleşme) ·
+  `action: 'request-info'` (`comment` soru; görev
+  `waiting-info`, SLA durur) ve başlatanın `action: 'provide-info'` (`comment` yanıt; aynı görev yeniden açılır) ·
+  `{ clock: 'P3D' }` (vadesi gelen zamanlayıcılar sırayla ateşlenir, sonrakiler senaryo saatinden kurulur) ·
+  `{ signal }` (`{ signal: 'withdraw', as: 'user:<başlatan>' }` `withdrawPolicy`'ye göre geri çeker) ·
+  `{ message, correlationKey }` · `{ subProcess: '<düğüm>', outcome }` (çocuk örnek açılmaz).
+- `expect`: `path` (girilen düğüm dizisi birebir), `assignees` (düğüm → kullanıcılar, alt küme), `outcome`,
+  `state`, `vars` (nokta yolu), `writeBack`. Yazılmayan alan denetlenmez.
+- `process_scenario_execute { definitionId | id, version? }` yan etkisizdir: writeBack satıra yazılmaz,
+  bildirim/webhook/e-posta jetonu gitmez, `service` düğümü workflow çağırmaz (stub anahtarı
+  `workflowSlug → workflowId → düğüm id`; `workflowSlug` yalnız düğümde yazılıysa eşleşir — `workflowId`'li
+  düğümde düğüm id'sini kullanın; stub yoksa örnek `faulted`). Yalnız son koşu sonucu kaydedilir.
+  `version` yoksa taslak — v3 senaryolarını v4 taslağında koşmak sürüm regresyonudur.
+- Sonuç: ilk sapma `divergence { kind: step | error | path | assignee | outcome | state | vars | write-back,
+  nodeId, stepIndex, expected, actual, message }` ve `coverage`; `process_scenario_list { view: 'coverage' }`
+  `untestedEdgeKeys` ('from->to') hiç test edilmeyen dalları listeler.
+- Senaryo düzenlenince son koşu silinir. Senaryolar ortam verisidir; deployment/merge taşımaz.
+
+## Yayın ve taşıma
+
+- `process_definition_publish`: taslak → `active`; önceki aktif `retiring` olur, açık örnekler kendi
+  sürümünde biter. Yayın doğrulamadan geçmezse 422 `DefinitionInvalid` döner, liste `errors[]`'dadır.
+- Yayınlanmış tanımda slug değişmez; değişiklik yeni taslak sürümdür (`process_definition_update`
+  ya da `patch` taslağı yazar).
+- production'a yayın ve yürütme gateway'de durur (BPM-001); production'a taşıma insan onaylı
+  deployment işidir.
+- **Diff:** `process_definition_diff { id, from?, to? }` anlamsal satırlar (`node-added`, `assignee-changed`,
+  `editable-changed`, `param-type-changed` …); `isOverrideRisk` yöneticinin uyarlamasını bozabilecek değişikliktir. Yayından önce okuyun.
+- **Dört göz:** aktif sürüm ya da taslak `publishPolicy: four-eyes` ve ortamda `process-publish` (bpm-management modülü)
+  kuruluysa `process_definition_publish` gerekçesiz 403 `PublishApprovalRequired` alır — taslakta politikayı `direct` yapmak
+  kapıyı açmaz. `{ reason }` ile istek açılır: `isPublished: false`, `request.instanceId`; onay görevi tanım sahibine düşer.
+  Yalnız isteyenden farklı bir kullanıcının onay kararı yayınlar; yönetici atlaması onay sayılmaz. Onay gerekmiyorsa aynı
+  çağrı doğrudan yayınlar.
+- **Yayın kapısı:** aktif sürüm ya da taslakta `requireGreenScenarios: true` iken her senaryo taslak sağlamasında yeşil
+  koşmuş olmalı, yoksa 422 `ScenarioFailed` — doğrudan yayında da `{ reason }` ile istek açarken de (istek açılmaz).
+  Onaydan sonra kapıya takılan istek `rejected` olur. Gateway kapı kapalıyken de uyarır (BPM-015): önce `process_scenario_execute`.
+- **SOP ve yorum:** `process_documentation_get` HTML (kulvar, RACI, SLA, diyagram); tasarım notları
+  `process_comment_list/create/update { resolved }`.
+- **Sahiplik ve portföy:** tanımın sahibi (kullanıcı kimliği) dört göz onay görevini alır; RACI rolleri
+  (`responsible`, `accountable`, `consulted`, `informed`) atama kurallarıdır ve SOP'ta görünür
+  (`PUT bpm/definitions/{id}/governance`, bugün yalnız Studio'da). Studio'daki süreç portföyü
+  (`GET bpm/definitions/portfolio`) uygulamanın tanımlarını sahip, RACI, aktif/taslak sürüm, açık/kapalı
+  örnek, SLA ve son yayınla listeler; yayın onayı bekleyenler üstte.
+- **Taşınan / taşınmayan (K-26):** deployment, dal açma, merge ve şablon tanımı ve iş takvimini taşır;
+  uyarlama, örnek, görev, timer, defter, bildirim, yorum, vekalet, havuz ve yetki limiti taşınmaz.
+- **Hedefte ne olur:** tanım `(slug, applicationId)` ile eşleşir. Yeni tanım gelen kimlik ve sürümlerle
+  kurulur. Var olan tanımda aktif modelin sağlaması farklıysa hedefte **yeni sürüm olarak yayınlanır**
+  (production'da gelişte aktif) ve hedefin uyarlaması korunur ya da çatışma bildirimi gelir. Taslak
+  yalnız dal açma ve merge'de taşınır. Hedefte workflow/entity/rol eksikse taşıma `DefinitionInvalid` ile
+  düşer. Kaynakta olmayan tanım silinir; açık örneği varsa emekliye ayrılır.
+- **Şablon:** `template_items(module: 'process-definition')` yalnız aktif sürümü taşır; kurulum yeni
+  kimlik verir, uygulama/workflow/sayfa/DTO kimliklerini yeniden eşler.
+- **Merge planı:** tanım farkı `versions[…].model.nodes[<düğüm id>]…` yolunda görünür.
+- **Silme kapısı:** kullanan tanım varken entity ve workflow silinmez (422 `ReferencedByProcess`,
+  mesajda tanım slug'ları); kimin kullandığını `dependency_graph(module: 'process-definition' | 'entity' | 'workflow')` gösterir.
+- **Modül paketleri:** `module_list` katalog + kurulum; `module_update { operation: install | upgrade | detach, module, applicationId }`.
+  Katalogdaki tek süreç modülü `bpm-management`'tır (süreç sayfaları ve tr-mesai takvimi); `requires`
+  taşıyan bir modül, gerektirdiği modül aynı application'a kurulmadan 409 `ModuleRequiresModule` döner.
+  Kurulum tabloları (yoksa), takvimi ve süreçleri getirir; güncelleme değişen
+  süreci yeni sürümle yayınlar, uyarlamayı ve tablo verisini korur; ayırma içeriği bırakır. production'a kurulum
+  gateway'de durur (BPM-014).
+
+## BPMN 2.0
+
+- **Dışa:** `process_bpmn_get { id, version?, outPath? }` — düğüm ve süreç alanları `zeyrek:` uzantısında,
+  saklı diyagram korunur. 256 KB üstü için `outPath`.
+- **İçe:** yeni tanım `process_definition_create { bpmn }`; var olan tanımın taslağı
+  `process_bpmn_update { id, xml | filePath }` (≤ 5 MB). `zeyrek:` uzantılı XML kayıpsız döner.
+- **Başka modelleyiciden (uzantısız):** düğüm öğe türünden türetilir (`userTask` → `user-task`,
+  `exclusiveGateway` → `gateway`, `callActivity` → `sub-process`, `subProcess` → `region` …), kimlikler
+  kebab-case olur, **derece `locked`**, insan adımı ve bildirimin ataması **yer tutucu `initiator`**, SLA/politika boş
+  (BPM-016 uyarısı). İçe aktardıktan sonra `process_definition_get { view: 'outline' }` → atamaları
+  `process_definition_patch` ile düzelt → `process_definition_preview`. Bağlama isteyen öğe (`serviceTask` workflow'suz,
+  `callActivity` süreçsiz) için yer tutucu yoktur: içe aktarım 422 `DefinitionInvalid` döner.
+- Şerit, havuz, not, veri nesnesi gibi yürütülmeyen öğeler kaybolmaz (alt süreç içindekiler dahil); içlerindeki kimlik
+  başvuruları normalize kimliklere çevrilir ve dışa aktarımda yerine yazılır. DTD/dış varlık içeren XML 400.
+
+## Bağlayıcı ve belge
+
+**Karar düğümü** `decision { decisionSlug, binding, input, output }` eşik ve seviye kurallarını DMN tablosundan
+okur — tablo yazımı, FEEL ve DRD `platform_guide('decision')`.
+
+**Bağlayıcı:** `connector_list` kataloğu (salesforce, sap-odata, microsoft-graph, google-workspace, jira, uipath, imap,
+netgsm, twilio, teams-webhook, slack, camunda8, camunda7, flowable) her satırda `category` (ai · process-engine ·
+productivity · messaging · business-app · rpa) taşır ve `category` ile süzülür; `connector_get { name }` işlem girdi şemaları.
+Kimlik önce kasaya: `connector_credential_create { name, connectorName, kind, … sırlar }` →
+`connector_credential_update { id, operation: 'test' }`. Sırlar şifreli saklanır, hiçbir yanıtta dönmez (BPM-017).
+Düğümde:
+
+```jsonc
+{ "id": "lead", "type": "service", "description": "Satış fırsatı açar", "output": "vars.lead",
+  "connector": { "name": "salesforce", "operation": "create", "credentialRef": "sf-sandbox",
+    "input": { "sobject": "'Lead'", "fields": "({ LastName: vars.soyad, Company: row.firma })" } } }
+```
+
+`input` değerleri Jint ifadesidir (metin sabiti tek tırnakla). Hata `502 ConnectorFailed` ve `retry` politikası workflow
+servis düğümüyle aynıdır.
+
+**Dış motor:** Camunda/Flowable'da koşan süreci başlatıp sonucunu bekleyin:
+
+```jsonc
+{ "id": "camunda", "type": "service", "description": "Dış siparişi başlatır", "output": "vars.dis",
+  "externalEngine": { "engine": "camunda8", "processKey": "siparis", "credentialRef": "c8", "input": { "tutar": "vars.tutar" } } },
+{ "id": "dis-bitti", "type": "wait", "description": "Dış süreç biter",
+  "message": { "name": "external-engine.done", "correlationKey": "vars.dis.zeyrekInstanceId" } }
+```
+
+Dış süreç değişkeninde `zeyrekInstanceId` gelir; bitişte `POST bpm/messages { name: "external-engine.done",
+correlationKey: <zeyrekInstanceId>, payload }` çağırması gerekir (MCP'den deneme: `process_trigger { kind: 'message' }`).
+
+**Olay ve e-posta kaynağı:** `process_event_source_create { name, kind: 'http', messageName, correlationKey:
+'payload.siparisNo' }` dış olayı mesaja çevirir, olay `process_trigger { kind: 'event-source', name, eventId, payload }`.
+`process_mail_source_create { kind: imap | graph, credentialRef, rules[{ subjectPattern, messageName, correlationKey }] }`
+e-postayı mesaja çevirir (ekler files'a); yoklama `process_trigger { kind: 'mail-source', sourceId }`. `credentialRef` kasadaki
+kaydın adıdır: olmayan ad kayıtta 404 döner, kasa kaydı yeniden adlandırılırsa kaynak yeni adı gösterir, kaynağın kullandığı
+kasa kaydı silinemez. Mesajı bekleyen
+`wait` düğümü ya da message start'lı tanım yoksa olay kaybolur — `bufferSeconds` verin.
+
+**Belge:** süreçte `type: 'document'` düğümü `document { templateFileId, format: docx | pdf | html, fileName, folderId,
+data: { alan: '<Jint>' }, stamp { revision, state, watermark, note } }` ve `output`; tek başına
+`process_document_execute { operation: generate | stamp | print }`. Şablon DOCX ya da HTML, yer tutucu `{{alan}}`: DOCX
+şablon `docx | pdf`, HTML şablon `html | pdf` üretir, başka biçim hata verir. `fileName` şablon metnidir, uzantısı biçime
+uyar; `folderId` boşsa şablonun klasörü. Damga HTML çıktıya basılmaz.
+
+**İmza:** `user-task`/`approval` düğümünde `signature { meaning, level: SES }` varsa görev imzasız tamamlanamaz
+(422 `SignatureRequired`); `process_task_update { action: 'sign', password, meaning?, email?, fileId?, version, asUser }`.
+Parola zorunlu (BPM-018; yalnız `signature.reauth: false` düğümde değil), gateway günlüğüne maskeli yazılır. `meaning` verilmezse düğümünki. İmzalanan dosya kilitlenir (409 `FileLocked`).
+
+**Kanallar:** `notify` `channels` `inbox | email | socket | sms | teams | slack`. `sms` kullanıcının tercihindeki numaraya
+(`process_preference_update { phone }`) `notification-sms` kasa kimliğiyle (bağlayıcı netgsm ya da twilio); `teams` ve
+`slack` kullanıcının e-postasıyla `notification-teams` / `notification-slack` kimlikleriyle gider. Kimlik yoksa kanal sessizce
+atlanır. `push` henüz yok.
+
+## Doküman kontrolü ve AI
+
+**Değerlendirme (okuma sınavı):** `user-task`'ta `assessment { questionBank { entity, where, questionField, optionsField,
+answerField }, count, passScore, attempts, random, completeAction }`. Akış: `process_task_update { action: 'start-assessment' }`
+(sorular cevapsız döner) → `{ action: 'submit-assessment', answers: { soruId: cevap } }`. **Submit'te `version` gönderme:**
+sınavı açmak görevi üstlenir ve sürümünü ilerletir, elindeki sürüm bayattır (409). Başlatma yanıtı `{ id, taskId, number,
+passScore, questions, startedAt, attempts, lastScore, isPassed }`: `attempts` adımın izin verdiği hak, `lastScore`/`isPassed`
+**bu kullanıcının** son gönderilmiş denemesinin sonucudur (ilk denemede null). Denemeler **kullanıcı başına** sayılır (defterdeki
+`number` örnek genelinde artar) ve sınavı yalnız görevin atandığı kişi açıp gönderebilir — başkası 403 `TaskComplete`.
+Görev ayrıntısı (`process_task_get`) sınav isteyen adımda `assessment { count, passScore, attempts }` kuralını taşır; deneme
+açılmadan önce paneli o kural açar. Soru bankası ve konu satırı okuyucunun alan izinlerine bakılmadan okunur; `passScore`
+gerçekten sorulan soru sayısına kırpılır (banka `count`'tan az soru döndürürse geçme notu o sayıya iner). Cevap anahtarı boş
+ya da yalnız boşluk olan soru **hiçbir cevapla doğru sayılmaz**. Geçen deneme görevi `completeAction` (yoksa düğümün okuma
+kanıtı eylemi, o da yoksa `complete`) ile kapatır; kalan deneme hak varsa görevi açık bırakır, hak bitince sonuç
+`assessment-failed` (geçide yönlendirin). Sınavsız okuma kanıtı 422. `passScore` 1..`count` (BPM-020).
+
+**Yürürlük tarihi:** `end` düğümünde `effectiveAt: "<Jint tarih>"` + `revision { stateField, groupField, effectiveValue,
+supersededValue, numberField }`; tarihte satır `effective`, aynı gruptaki önceki `superseded` olur. Grup satırları alan
+filtresiyle okunur (10.000 satır sınırı yok). `numberField` verilirse sıra **numaraya** göre kurulur: yürürlüğe giren revizyon
+numarası yürürlükteki bir satırdan küçükse **gelen satır** `superseded` olur, yürürlükteki yerinde kalır — geç işlenen eski bir
+revizyon yeniyi düşürmez. `numberField` yoksa gelen satır her zaman yürürlüğe girer. **Check-out:** dosya
+`POST files/{id}/checkout { taskId }` ile kilitlenir, başkası yazarsa 409 `FileCheckedOut`; görev **hangi yolla kapanırsa
+kapansın** (eylem, imza, e-posta jetonu, zaman aşımı) kilit bırakılır. Kilitli ya da check-out'lu dosya barındıran klasör
+silinemez.
+
+**B2B:** `process_partner_create` ilişki önerir, karşı organizasyon `process_partner_update { operation: 'accept' }` ile
+açar; tanımda `assignee: "partner:<kod>"` yalnız `active` ve süreci izinli ilişkiyle yayınlanır (`PartnerUnknown`).
+
+**AI önerisi (service düğümü):**
+
+```jsonc
+{ "id": "oneri", "type": "service", "description": "Karar önerir", "output": "vars.oneri",
+  "ai": { "operation": "suggest-decision", "labels": ["approve", "reject"], "input": { "talep": "vars.talep" } } }
+```
+
+`operation`: `summarize` → `{ summary }` · `classify` (`labels`) → `{ label }` · `extract` (`schema.properties`,
+`files` PDF/görsel) → `{ fields }` · `suggest-assignee` (`input.candidates`) → `{ userId }` · `suggest-decision`
+(`labels`) → `{ outcome }`; liste/şema dışı değer `null`. AI **karar vermez**: çıktı yalnız `output` yoluna yazılır,
+sonraki onay görevi açık kalır; geçitte kullanacaksanız kişi onaylasın. Korumalı alanlar modele `***` gider. Her öneri
+defterde `ai-suggestion { promptHash }`. `autonomy: act-in-adhoc` yalnız `adHoc` süreçte (BPM-019) ve bugün öneriyle aynı.
+Model ve kasa kimliği ortam ayarıdır (`Bpm:AiModel`, `Bpm:AiCredentialRef`); yoksa 400.
+
+**Görev yardımcısı:** `process_task_get { view: 'assistant' }` özet ve önerilen eylem, `question` ile soru-cevap döner
+(`aiSuggestion` rozetiyle; `outcome` yoktur). `process_task_list { q: 'bu ay geciken satınalmalar' }` süzgeci
+`appliedFilter` ile döner. Kullanıcı başına dakikalık sınır 429 `AiRateLimited`.
+
+## Operasyon
+
+- **Rapor:** `process_report_get { slug, from, to }` — defterden türer, arşivlenmiş örneği saymaz. Çevrim
+  `instance-started` → `instance-completed`; SLA içinde % son termine (uzatma dahil) göre; `rejectLoops` ardından yeni
+  görev açılan retler; `units[]` başlatanın birincil birimi. Pencere en çok 366 gün; `isTruncated` 5000 örneği aştığını
+  söyler — pencereyi daraltın. Yetki `process.view-all`.
+- **Madencilik:** `process_export_get { format: xes | ocel, definition, from, to, outPath }` IEEE XES (iz = örnek, olay =
+  defter satırı, `org:resource` eylemci, vekalette `zeyrek:principal`) ya da OCEL 2.0 JSON (örnek, görev, konu, belge
+  nesneleri, dosya `.json`) indirir; gateway dosyayı yapısal denetler (`validated`, `problems`) — resmî XSD değil;
+  `isTruncated: true` 5000 örnek tavanıdır, pencereyi bölün. ProM/Celonis için
+  `outPath`. `process_analytics_get { definition, view: variants | heatmap | conformance | prediction, from, to }`: yol
+  varyantları (pay % yolu olan örneklere göre), insan görevi düğümü başına süre, tanım dışı geçişler (sıçrama, atlama, göç), açık örnekte kalan süre
+  medyanı. Pencere ve 5000 örnek tavanı rapor ile aynı; `history: minimal` tanımda yol eksik kalır.
+- **Defter:** `process_instance_get { view: 'events' }` CSV (en çok 256 KB satır içi), `view: 'verify'`
+  `{ isValid, brokenAtSequence }`. `isValid: false` defterin sonradan değiştirildiğini gösterir; kırık satırı
+  zaman çizelgesinde bulun, örneği düzeltmeye çalışmayın — denetim kaydıdır.
+- **Saklama ve yasal bekletme:** tanımda `retention` (ör. `P5Y`) doluysa kapanmış örnek saatlik işte arşive taşınır,
+  30 gün sonra silinir. `process_legal_hold_create { scope: process | instance | user, scopeKey, reason }` taşımayı ve
+  silmeyi durdurur; `process_legal_hold_delete` kaldırır (kayıt kalır). İkisi de production'a gitmez (BPM-001).
+- **Sağlık:** `process_health_get` — `timerLagSeconds` 60 sn'yi aşarsa `degraded`, 600 sn'yi aşarsa `unhealthy`
+  (timer işi durmuş ya da geride); `notificationLagSeconds` 300 sn üstü ve 10'dan çok `faulted` örnek de `degraded`.
+  `faulted` örnek için `process_instance_list { state: 'faulted' }` → `process_instance_update { operation: 'retry' }`.
+- **Yarı yolda örnek:** `process_execute { slug, subjectRowId, vars, importAt: { nodeId, assigneeUserId, startedAt } }`
+  kâğıttan ya da eski sistemden gelen işi o düğümde açar; defterin ilk satırı `instance-imported`, rapordaki çevrim
+  `startedAt`'tan sayılır. Düğüm başlangıç, bitiş ya da bölge içi olamaz; yetki `process.manage`.
+- **Tanım yedeği:** `process_definition_list { view: 'export' }` bütün tanımları (sürümler, taslak, RACI) ve takvimleri
+  verir; `process_definition_create { restore: <export data> }` geri yükler (takvim üzerine yazılır, değişen aktif sürüm
+  yayınlanır, yedekte olmayan tanım silinmez). Ortamlar arası taşıma için yedek değil deployment kullanılır.
+
+## Hata sözlüğü
+
+| Kod | HTTP | Anlam ve çözüm |
+|---|---|---|
+| `DefinitionInvalid` | 422 | Yapı: tek start, ulaşılamayan düğüm, tanımsız kenar, açıklama. `errors[]` satırlarını düzeltin |
+| `RuleNotAllowed` · `RegionLocked` · `ParamNotEditable` · `MaxStepsExceeded` · `NodeTypeNotAllowed` | 422 | Bölge ya da uyarlama sınırı ihlali — §Uyarlama yol tablosu |
+| `ExpressionInvalid` | 422 | Jint ifadesi derlenmiyor |
+| `SubjectEntityUnknown` · `WorkflowUnknown` · `RoleUnknown` | 422 | Referans çözülmedi |
+| `ServiceInputUnknown` | 422 | Servis düğümünün `input` anahtarı workflow'un parametre DTO'sunda yok — `dto_get` ile alan slug'larını okuyun |
+| `TaskAlreadyClaimed` | 409 | Görev başkasında — görevi yeniden okuyun |
+| `AggregateVersionConflictException` | 409 | `version` bayat (görev ya da tanım siz okuduktan sonra değişti) — `process_task_get` / `process_definition_get` ile yeniden okuyun |
+| `TaskStateTransitionNotAllowed` | 422 | Görev bu durumda bu eylemi almaz (ör. `waiting-info` iken onay) |
+| `TaskCommentRequired` | 422 | `commentRequired` koşulu yorum ister |
+| `InstanceStateTransitionNotAllowed` | 409 | Örnek bu durumda değişmez (tamamlanmış örneği askıya alma) |
+| `WithdrawNotAllowed` | 422 | `withdrawPolicy` geri çekmeye izin vermiyor |
+| `UndoWindowClosed` | 409 | Geri alma penceresi geçti ya da sonraki insan görevi açıldı |
+| `TaskActionTokenInvalid` | 410 | E-posta bağlantısı kullanılmış ya da süresi dolmuş |
+| `OpenTasksExist` | 422 | Kullanıcının ya da birimin açık görevi var — önce `process_handover_preview` / `process_handover_create` |
+| `HandoverIncomplete` | 422 | Kararı olmayan görev grubu var — karar verin ya da `force: true` |
+| `DelegationOverlap` | 409 | Asıl kişinin kesişen vekaleti var |
+| `DelegationChainNotAllowed` | 422 | Vekil aynı aralıkta kendi görevlerini devretmiş |
+| `BatchOperationNotUndoable` | 422 | Yalnız tamamlanmış reassign / extend-due bir kez geri alınır |
+| `PublishApprovalRequired` | 403 | Dört göz tanımı — `process_definition_publish { reason }` ile yayın isteği açın |
+| `ScenarioFailed` | 422 | `requireGreenScenarios` ve senaryo bu taslakta yeşil değil — `process_scenario_execute` |
+
+## Sık tuzaklar
+
+- **Süreç ≠ workflow.** Tek istekte biten iş için workflow yazın; bekleme, insan kararı, SLA varsa süreç.
+- **`description` eksik düğüm** gateway'de durur (BPM-002); her düğüme niyet cümlesi yazın.
+- **İki dilli `analysis` eksik tanım ya da düğüm** gateway'de durur (BPM-023); § Analiz dokümanı.
+- **`editable: open` bölge dışında** geçersizdir (BPM-003).
+- **Sıralı zincirin uzunluğu `vars`'tan geliyorsa** önceki `service` düğümü `output: vars.seviye` yazmalı;
+  kuru koşuda aynı değeri `vars` ile verin.
+- **`back-to:` bölge dışına** dönebilir; bölge koşusu `exited` olur ve içindeki açık görevler iptal edilir.
+- **Paralel birleşme** gelen kenar sayısını bekler; birleşmeye koşullu olarak gelmeyen bir kol süreci
+  asılı bırakır — koşullu dalları önce exclusive gateway'de toplayın.
+- **Görev eylemi app kullanıcısı adına yapılır**; Studio jetonuyla `complete` 403 alır.
+- **production** hedefine yayın/yürütme gönderilmez (BPM-001).