@devoplus/one-sdk 0.0.0-stage → 0.2.0-next.112

package/README.md

@@ -1,3 +1,895 @@
-# Temporary Holding Version
+# @devoplus/one-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Devoplus One** uygulamalarının (Devoplus Portal içinde iframe ile gösterilen kullanıcı uygulamaları) platform
+servislerine **ince istemcisi**. SDK sır taşımaz, kiracı seçmez ve
+belirteç üretmez: kimliği platform kapısının yazdığı başlıklardan **okur**, backend'e kullanıcının uygulama
+belirteciyle gider, dosyayı kuruluma bağlı dosya deposuna yazar.
+
+Platformun tamamı: `devoplus/devoplus-one` (mimari `docs/architecture.md`); kararlar
+`devoplus-root/docs/devoplus-one-karar-defteri.md`; örnek uygulama `apps/hello`.
+
+## Kurulum
+
+```bash
+pnpm add @devoplus/one-sdk@next   # ön sürüm (test kanalı)
+pnpm add @devoplus/one-sdk        # kararlı sürüm (latest)
+```
+
+Kararlı sürüm (`latest`) yayımlanana kadar `@next` ile kurun; iki kanal Sürümleme bölümünde anlatılır.
+
+Paket yalnız **ESM** dağıtılır (`dist/index.js` + `dist/index.d.ts`); Node ≥ 22. Çalışma ortamı tipleri (`OneDatabase`,
+`OneFilesBinding`, `OneCacheBinding`, `OneApp` vb.) paketin içindedir; ek bir tip paketi gerekmez. `tsconfig` içinde
+`"lib": ["ES2022", "WebWorker"]` ve `"types": []` yeterlidir (standart Web API'leri `WebWorker` kütüphanesinden gelir).
+
+### Yerel geliştirme: `one` komutu
+
+Paket `one` komutunu da getirir (D-72); uygulamanın kök dizininde çalışır ve `one.manifest.json`'u okur:
+
+| Komut | Ne yapar |
+|---|---|
+| `one dev [--port n] [--api-base url]` | Uygulamayı yerelde çalıştırır. Devoplus servisleri varsayılan olarak test ortamındadır (`ONE_API_BASE` ile değişir). İstekler Portal'dan geçmediği için kimlik başlıklarını (`X-One-*`) elle gönderirsiniz. |
+| `one migrate` | `migrations/` altındaki SQL dosyalarını **yerel** veritabanına uygular (`one dev` aynı veriyi görür). |
+| `one build` | Yükleme provası: kodu paketler, hiçbir yere göndermez (çıktı `.one/dist/`). |
+| `one data generate [--check]` | `one.data.json` veri modelinden yeni migration + `src/data/types.ts` üretir; yalnız ekleyen değişiklik ([Veri modeli](#veri-modeli-ve-kayıt-işlemleri-d-84-️-geliştirici-onayı-bekliyor)). |
+
+Yerel yapılandırma ve veri `.one/` altındadır, depoya girmez ve her komutta manifest'ten yeniden üretilir. Gerçek
+yükleme Devoplus GitLab hattıyla yapılır; geliştirici makinesinden yükleme yoktur. Komutun ekrana yazdığı ayrıntılar
+(araç adı, sürüm satırı) yerel çalışma ortamına aittir ve gizlenmez.
+
+### Erişim talebi: `one login`, `one request`, `one requests` (D-75)
+
+Uygulamanız bir kuruluma, DEXA sorgusuna, uygulama izni atamasına ya da yetki alanına ihtiyaç duyduğunda izni
+yöneticiden komut satırından isteyebilirsiniz. Talep izni kendiliğinden VERMEZ; yönetici Admin Console'da onaylar ve
+sonuç size e-postayla bildirilir.
+
+| Komut | Ne yapar |
+|---|---|
+| `one login [--env test\|uat\|prod]` | Tarayıcıda kod onayıyla giriş (portal orada seçilir). İlk girişte komut bu bilgisayarı kimlik sağlayıcıya kendisi kaydeder (yalnız erişim talebi, yayın ve kullanım panosu yetkisiyle) ve kimliği `~/.config/devoplus-one/clients.json`'da saklar; oturum `~/.config/devoplus-one/session.json`'da, ikisi de yalnız sizin okuyabileceğiniz izinle durur. Sabit bir istemci kullanmak için `--client-id` / `ONE_CLIENT_ID`. |
+| `one request <tür> ...` | Talep gönderir; türler: `registration`, `installation`, `dexa-query`, `dexa-command`, `app-permission`, `scope`, `new-query`. `one request` yazınca türlerin alanlarını listeler. Kısa ad `one.manifest.json`'dan okunur. |
+| `one requests [kimlik]` | Taleplerinizi ve durumlarını listeler. |
+| `one context [--json]` | Oturumdaki portalın adını, kimliğini ve var olan kısa adını (portal anahtarı; yoksa yok der) gösterir. Kurulum talebinde portal anahtarı seçilmez; sunucu onu portalın adından belirler. |
+| `one logout` | Oturumu kimlik sağlayıcıda iptal eder ve dosyayı siler. |
+
+Uygulama içi izinler kayıt talebinde istenir: `one request registration --title "<ad>" --permission
+One.Hello.Manage="Yönetir"` (tekrar edilebilir, en çok 16; İngilizce ad `--permission-en <kod>="<ad>"`). Kayıt talebini
+portalın şirket yöneticisi, yetki alanı talebini platform yöneticisi onaylar. Kayıt talebi dışındaki türleri yalnız uygulamanın sahibi gönderebilir. Vekalet ya da Yerine Görüntüle oturumuyla talep
+gönderilemez. Aynı istemci Devoplus One MCP sunucusunda da kullanılır (`@devoplus/one-sdk/access-request`).
+
+### Yayın ve kullanım panosu: `one publish`, `one promote`, `one rollback`, `one deployments`, `one status` (D-86, D-87)
+
+Kod yine bu bilgisayardan yüklenmez: komut Devoplus'a bir **yayın isteği** bırakır, Devoplus isteği kaydeder ve yayın
+hattını kendisi başlatır; hattın kapılarının hiçbiri atlanmaz. Komutlar `one login` oturumuyla çalışır; uygulamanın
+kısa adı `one.manifest.json`'dan okunur (`--app` ile değişir), `--json` ham yanıtı basar.
+
+| Komut | Ne yapar |
+|---|---|
+| `one publish [--portal <anahtar>]` | Test ortamına yayın. Hat bitince uygulama test Portal'ında açılır; adresi (`https://<kısa-ad>-<anahtar>.test-one.devoplus.dev`) paylaşılabilir önizlemedir. |
+| `one promote [--portal <anahtar>]` | Sürümü bir sonraki ortama taşır (sıra: test, uat, canlı); terfi kapısı bir önceki ortamda doğrulanmamış sürümü durdurur. |
+| `one rollback [--portal <anahtar>] [--to <x.y.z>] --yes` | Önceki sürüme (ya da verilen sürüme) döner. Kod `v<x.y.z>` git etiketinden alınır, bu yüzden yayına giren sürümleri etiketleyin; `--to` yoksa dalın ucundaki sürümden küçük en büyük etiket. Veritabanı da o sürümün yapısına dönmek zorundaysa dönülen noktadan sonra kaydedilen veriler **kaybolur**; komut `--yes` olmadan hiçbir istek göndermez. |
+| `one deployments [--portal <anahtar>]` | Yayın isteklerinizi ve durumlarını listeler. |
+| `one status [--portal <anahtar>] [--days 7]` | Kullanım ve hata özeti: istek ve hata sayısı, işlemci süresi, günlük dağılım, son hata kayıtları (`logError`), başarısız arka plan işleri. Kişisel veri ve ileti gövdesi döndürülmez. |
+
+- Yalnız uygulamanın sahibi ya da o portalın şirket yöneticisi yayın isteyebilir ve panoyu görebilir; kararı sunucu verir.
+- `--portal` verilmezse istek portal anahtarı taşımaz ve kurulumu sunucu seçer. Kısa ad, portal anahtarı, sürüm ve gün
+  sayısı istek gönderilmeden denetlenir; tanınmayan bir seçenek (`--portl`) açık hatadır.
+- Yanıt *"Yayın hattı bu ortamda yapılandırılmamış"* ya da *"Kullanım ve hata panosu bu ortamda yapılandırılmamış"*
+  ise o ortamda bu özellik henüz kullanılamıyor demektir.
+- Aynı istemci Devoplus One MCP sunucusunun `one_publish`, `one_deployments` ve `one_app_health` araçlarında da
+  kullanılır (`@devoplus/one-sdk/app-ops`).
+
+## Hızlı başlangıç
+
+```ts
+import {
+  BackendClient, OneFiles, problemResponse, readContext, requireScope, requireUser, sendMail,
+  type OneApp, type OneDatabase, type OneFilesBinding,
+} from '@devoplus/one-sdk'
+
+interface Env { DB: OneDatabase; FILES: OneFilesBinding; API_BASE: string }
+
+export default {
+  async fetch(request, env): Promise<Response> {
+    try {
+      const ctx = readContext(request.headers)          // platform kapısının yazdığı X-One-* başlıkları
+      const url = new URL(request.url)
+
+      if (url.pathname === '/api/me') {
+        requireUser(ctx)                                 // oturum yoksa 401
+        const api = new BackendClient({ baseUrl: env.API_BASE, authorization: request.headers.get('authorization') })
+        return Response.json(await api.get('Users/me'))
+      }
+
+      if (url.pathname === '/api/notify' && request.method === 'POST') {
+        const user = requireScope(ctx, 'mail.execute')   // scope manifest'te ve belirteçte yoksa 403
+        const api = new BackendClient({ baseUrl: env.API_BASE, authorization: request.headers.get('authorization') })
+        return Response.json(await sendMail(api, { toSubjects: [user.sub], subject: 'Merhaba', text: 'Deneme' }))
+      }
+
+      if (url.pathname === '/api/files' && request.method === 'POST') {
+        requireUser(ctx)
+        const files = new OneFiles(env.FILES)
+        const info = await files.put(`uploads/${crypto.randomUUID()}`, await request.arrayBuffer(), {
+          contentType: request.headers.get('content-type') ?? 'application/octet-stream',
+        })
+        return Response.json(info, { status: 201 })
+      }
+
+      return new Response('Bulunamadı', { status: 404 })
+    } catch (error) {
+      return problemResponse(error)                      // OneError RFC 9457 yanıtına çevrilir; bilinmeyen hata 500
+    }
+  },
+} satisfies OneApp<Env>
+```
+
+## Kimlik bağlamı
+
+| Üye | Açıklama |
+|---|---|
+| `readContext(headers): OneContext` | `X-One-App`, `X-One-Portal-Key`, `X-One-Portal`, (`X-One-Auth=user` ya da kuyruk işinde `job` + `X-One-Sub`, `X-One-Scope`, `X-One-Global-Admin`, `X-One-Permissions`, `X-One-Admin`). Üç kurulum başlığından biri yoksa `ONE-SDK-E-001` (500): istek dispatch üzerinden gelmemiştir. |
+| `OneContext` | `{ app, portalKey, portalId, user: OneUser \| null, actor?: OneActor \| null, mode?, admin?, jobServices? }`. `portalId` kiracıdır (24-hex); veri her zaman buna bağlıdır. `mode`: `'user'` (kullanıcının isteği), `'job'` (kuyruk / zamanlanmış iş), `'agent'` (Devoplus ajanının araç çağrısı). `admin` = `user.admin` (oturumsuzda ve işte `false`). `jobServices`: işte manifest `jobs.services` beyanı, diğer yollarda boş. |
+| `OneActor`, `isActingSession(ctx)` | Vekalet / Yerine Görüntüle oturumu (D-76 U3; `X-One-Actor-Sub` + `X-One-Session-Kind`): `{ sub, kind: 'delegation' \| 'impersonation' }`. `user.sub` adına çalışılan kişidir (veri onundur), `actor.sub` oturumu kullanan kişidir; "kim yaptı" kaydına bu yazılır. Kendi oturumunda `null`. ⛔ Bu oturumlar varsayılan **salt-okunurdur**: platform GET/HEAD dışındaki isteği uygulamaya ulaşmadan **403 `ONE-DSP-E-009`** ile reddeder; uygulama manifest'te `"actingSessions": "write"` beyan ederse yazma isteği geçer. |
+| `OneUser` | `{ sub, scope: readonly string[], globalAdmin, permissions: readonly string[], admin }`. `sub` devoplus-auth kimlik uzayıdır (`UserAccount._id`), Organization Schema `User._id` DEĞİLDİR. `permissions` yalnız bu uygulamanın ad alanındaki (`One.<Uygulama>.*`) izinlerdir (D-49); `admin` = şirket ya da küresel yönetici rolü. |
+| `requireUser(ctx): OneUser` | anonimse `ONE-SDK-E-002` (401). |
+| `requireScope(ctx, scope): OneUser` | belirteçte scope yoksa `ONE-SDK-E-003` (403). Onaya bağlı scope'ta metin kullanıcıya izni nereden vereceğini de söyler. |
+| `requireServiceScope(ctx, scope)` | Devoplus servisinin yerel kapısı, üç yolu ayırır (bkz. "Devoplus servisleri arka plan işinde ve ajan aracında"): kullanıcıda `requireScope`; ajan aracında süreli onay gerektiren scope'lar hiç kullanılamaz; işte kullanıcı gerekmez, scope `jobs.services`'te beyanlı olmalı. İhlal `ONE-SDK-E-003` (403); asıl karar sunucudadır. |
+| `CONSENT_SCOPES`, `awaitsUserConsent(ctx, scope): boolean` | Kullanıcının **ayrıca ve süreli** onay vermesi gereken scope'lar (D-59): `dexa.write`, `mail.execute`, `sms.execute` ve `push.execute`. `awaitsUserConsent` scope onaya bağlıysa ve belirteçte yoksa `true` döner; ilgili düğmeyi kapatıp kullanıcıya "portaldaki İzinleri incele düğmesiyle izin verin" demek için. ⚠️ Manifest'te hiç beyan edilmemiş scope için de `true` döner (beyan uygulamanın bilgisidir). |
+| `hasPermission(ctx, code): boolean` | uygulama izni (D-49): kullanıcıda kod varsa ya da `admin` ise `true` (backend'in yönetici baypasıyla aynı); anonimde `false`. Kod manifest `permission`/`permissions` içinde beyan edilir, atamayı portal yöneticisi Yetki Yönetimi'nde kullanıcı gruplarına (org düğümlerine) yapar. ⚠️ Ad alanı süzgeci bir kolaylıktır, gizlilik sınırı değildir: `Authorization` belirteci kullanıcının bütün izinlerini taşır. |
+| `requirePermission(ctx, code): OneUser` | oturum yoksa 401, izin yoksa `ONE-SDK-E-004` (403). |
+| `OneError` | `status`, `code`, `message` (kullanıcıya görünen Türkçe metin). |
+
+Uygulama kodu `X-One-*` başlıklarını **asla kendisi yazmaz**; dispatch istemciden gelenleri siler ve belirteçten
+yeniden kurar.
+
+**Kullanıcı onayı (D-59, 16.10.2026).** ERP'ye veri yazma (`dexa.write`) ve kullanıcı adına e-posta/SMS/mobil bildirim
+(`mail.execute`, `sms.execute`, `push.execute`) manifest'te beyan edilmiş ve kullanıcının yetkisi olsa bile, kullanıcı bu uygulamaya
+**o portalda** ayrıca onay vermeden belirtece girmez. Onay bir kez verilir, **30 gün** geçerlidir; portal uygulamanın
+üstünde bir uyarı ve "İzinleri incele" düğmesi gösterir, onay devoplus-auth ekranında verilir ve oradaki "Yetkili
+uygulamalarım" sayfasından kaldırılır. Uygulama onay beklerken de açılır ve onay gerektirmeyen işlevleri çalışır; bu
+yüzden bu işleri yapan rotalar `requireScope` ile korunmalı, arayüz `awaitsUserConsent` ile ilgili düğmeyi kapatıp
+yönlendirme yazabilir. Onay kaldırılınca sonraki her belirteç hassas scope'u taşımaz (devoplus-auth onayı güçlü tutarlı
+bir Durable Object'te tutar); daha önce verilmiş belirteç iptal edilmez, en çok ömrü kadar (10 dk) geçerli kalır.
+
+## Portal köprüsü ve görsel dil (D-76)
+
+Uygulama sayfası Portal'da iframe içinde açılır. Sayfa üç dosyayı **kendi** adresinden yükler; satır içi betik
+platformda kapalıdır (`script-src 'self'`) ve `one-ci validate` satır içi ya da harici (`https://...`) betiği yayından önce
+durdurur:
+
+```html
+<link rel="stylesheet" href="/one-ui.css">    <!-- görsel dil -->
+...
+<script src="/one-bridge.js"></script>          <!-- window.one -->
+<script src="/shell.js"></script>               <!-- sayfanın kendi betiği -->
+```
+
+```ts
+import manifest from '../one.manifest.json' with { type: 'json' }
+import { clientAssetResponse, navigationFromManifest, scriptResponse } from '@devoplus/one-sdk'
+
+const NAVIGATION = navigationFromManifest(manifest)          // Portal'ın çizeceği sekmeler
+// fetch içinde:
+const asset = clientAssetResponse(url.pathname)               // /one-bridge.js ve /one-ui.css
+if (asset) return asset
+if (url.pathname === '/shell.js') return scriptResponse(renderShellScript(NAVIGATION))
+```
+
+| Sunucu üyesi | Açıklama |
+|---|---|
+| `clientAssetResponse(pathname): Response \| null` | `/one-bridge.js` (`ONE_BRIDGE_SCRIPT`, `text/javascript`), `/one-components.js` (`ONE_COMPONENTS_SCRIPT`, hazır bileşenler, D-83) ve `/one-ui.css` (`ONE_UI_CSS`, `text/css`); başka yolda `null`. |
+| `scriptResponse(body)` | Sayfa betiği için doğru içerik türüyle yanıt. |
+| `navigationFromManifest(manifest)` | Manifest `navigation` alanı: bozuk/yinelenen öğe atlanır, en çok `NAVIGATION_MAX_ITEMS` (12). Yol kuralı `ROUTE_PATH_RE` / `isRoutePath` (manifest şemasıyla aynı). Sekme izni (`permission`, S10) korunur; biçimi bozuk izinli öğe atlanır. |
+| `visibleNavigation(items, access)` | Kişinin görebildiği sekmeler (`access`: `{ permissions, admin }` ya da `null` = yalnız izinsiz sekmeler); dönen öğeler izin kodu taşımaz. |
+
+Tarayıcıdaki `window.one` (tip: `OneBridge`):
+
+| Üye | İleti | Açıklama |
+|---|---|---|
+| `one.start({ navigation })` | `one:ready` + `one:navigation` | Sayfa hazır olunca **bir kez**; yükseklik bildirimini de başlatır (`one:resize`). Menü sözleşmeye uymuyorsa fırlatır. İzinli sekmeler (`permission`) erişim bildirilene kadar gönderilmez. |
+| `one.setNavigationAccess({ permissions, admin })` | `one:navigation` | Oturumdaki kişinin uygulama izinleri (S10): görebildiği izinli sekmeler menüye eklenir (menü değiştiyse ileti yeniden gönderilir; Portal son iletiyi geçerli sayar). Yönetici her sekmeyi görür. Oturum bilgisini okuyunca çağırın (`GET /api/session`). |
+| `one.token`, `one.onToken(fn)`, `one.fetch(yol, init)` | `one:token` | Belirteç yalnız Portal'dan gelir; `one.fetch` `Authorization: Bearer ...` ekler. |
+| `one.context`, `one.onContext(fn)`, `one.actor` | `one:context` | `{ theme, lang, autoHeight, actor: { kind } \| null, design }`. Köprü `data-theme`'i köke yazar, tasarım değerlerini (`primary`, `primaryContrast`, `fontFamily`, `radius`; biçimi tutmayan değer yazılmaz) `--one-primary` ve benzeri değişkenlere geçirir, `autoHeight` gelince sayfanın kendi dikey taşmasını gizler (yatay taşma kaydırılabilir kalır; yatay kaydırma çubuğu bildirilen yüksekliğe eklenir). `one.actor` yalnız gösterim içindir; yazma kapısı sunucudadır. |
+| `one.onNavigate(fn)`, `one.path` | `one:navigate` | Portal sekmesine tıklandı; görünümü değiştirin. Adres geçmiş kaydı eklenmeden güncellenir; geri bildirim gönderilmez. |
+| `one.setRoute(yol)` | `one:route` | Uygulama kendi içinde görünüm değiştirdi; Portal adresi güncellenir. Yol `/` ile başlar, sorgu/`#` yok. |
+| `one.setTitle(metin \| null)` | `one:title` | Alt sayfa başlığı (en çok `TITLE_MAX_LENGTH` = 120, uzunu kesilir); `null` kaldırır. |
+| `one.toast({ severity, summary, detail? })` | `one:toast` | `success`, `info`, `warn`, `error`; Portal çizer. Düz metin. |
+| `await one.confirm({ message, title?, severity?, acceptLabel?, rejectLabel? })` | `one:confirm`, yanıt `one:confirm-result` | `true`/`false`. `severity`: `danger`, `warn`, `info`. Portal origin'i yoksa `false`. ⚠️ Portal bu iletiyi tanımıyorsa söz çözülmez. |
+| `await one.download({ name, mime, data })` | `one:download` | `data` ArrayBuffer (Uint8Array, Blob ve metin çevrilir); en çok `DOWNLOAD_MAX_BYTES` (25 MB). iframe'de indirme kapalıdır; Portal kaydeder. |
+| `one.openExternal(url)` | `one:open-external` | Yalnız `https://`; Portal kullanıcıya sorup yeni sekmede açar. |
+| `one.setDirty(bool)` | `one:dirty` | Kaydedilmemiş değişiklik; Portal ayrılmadan önce sorar. Yalnız değişince gönderilir. |
+| `one.viewport.current`, `one.viewport.onChange(fn)` | `one:viewport` | iframe'in ekranda görünen kısmı `{ top, height }` (iframe CSS pikseli). Kendi penceresini görünen alana yerleştirmek için kullanılır. |
+
+Bütün iletiler yalnız iframe `src`'sindeki `parent` origin'lerine gönderilir (joker yok); gelen ileti origin ve üst
+pencere doğrulanarak alınır. Portal dışında (yerel geliştirme) ileti gönderilmez: `confirm` tarayıcının kendi sorusuna,
+`download` tarayıcı indirmesine, `openExternal` yeni pencereye, `toast` konsola düşer.
+
+**Görsel dil (`/one-ui.css`):** açık/koyu değişkenler (`--one-bg`, `--one-fg`, `--one-muted`, `--one-surface`,
+`--one-border`, `--one-primary`, `--one-primary-contrast`, `--one-font-family`, `--one-radius`, durum renkleri) ve
+sınıflar: `one-btn` (`-primary`, `-danger`, `-text`), `one-field` + `one-label` + `one-input` / `one-select` /
+`one-textarea`, `one-table` (+ `one-table-wrap`, `one-num`), `one-card`, `one-message` (`-success`, `-info`, `-warn`,
+`-error`), içerik sekmeleri `one-tabs` + `one-tab` (`aria-selected`), `one-row`, `one-stack`, `one-muted`, `one-empty`,
+`one-loading`, `one-sr-only`. ⚠️ `one-tabs` içerik içi gruplama içindir; uygulama menüsünü Portal çizer.
+
+## Hazır arayüz bileşenleri (D-83)
+
+Liste, form, süzgeç, kişi seçimi, dosya yükleme ve grafik için hazır bileşenler `/one-components.js`'tedir. Bileşenler
+bağımlılıksızdır, uygulamanın **kendi** adresinden yüklenir (satır içi betik gerekmez), `/one-ui.css` görsel dilini
+kullanır, Portal'ın tema ve dil değişimini (`one:context`) kendiliğinden izler ve bütün metinleri Türkçe + İngilizce
+taşır. Tarih `gg.aa.yyyy`, sayı ve para `tr-TR` biçimindedir. İstekler yalnız uygulamanın kendi adresine gider ve
+belirteci köprü ekler (`one.fetch`); başka adrese istek gönderilmez.
+
+```html
+<link rel="stylesheet" href="/one-ui.css">
+...
+<one-filter for="talepler"></one-filter>
+<one-table id="talepler" src="/api/requests" export="xlsx csv" selectable clickable caption="Talepler"></one-table>
+...
+<script src="/one-bridge.js"></script>
+<script src="/one-components.js"></script>   <!-- köprüden SONRA -->
+<script src="/shell.js"></script>
+```
+
+```js
+// /shell.js: kolon ve alan tanımları JavaScript özelliğidir (öznitelik değil).
+var table = document.getElementById('talepler')
+table.columns = [
+  { key: 'title', label: { tr: 'Başlık', en: 'Title' } },
+  { key: 'amount', label: { tr: 'Tutar', en: 'Amount' }, type: 'money' },
+  { key: 'createdAt', label: { tr: 'Tarih', en: 'Date' }, type: 'date' },
+  { key: 'status', label: { tr: 'Durum', en: 'Status' }, type: 'choice',
+    options: [{ value: 'open', label: { tr: 'Açık', en: 'Open' } }, { value: 'closed', label: { tr: 'Kapalı', en: 'Closed' } }] },
+]
+document.querySelector('one-filter').fields = [
+  { key: 'q', label: { tr: 'Ara', en: 'Search' }, type: 'text' },
+  { key: 'status', label: { tr: 'Durum', en: 'Status' }, type: 'choice', options: table.columns[3].options },
+  { key: 'createdAt', label: { tr: 'Oluşturma', en: 'Created' }, type: 'dateRange' },
+]
+table.addEventListener('rowclick', function (e) { openRequest(e.detail.row.id) })
+```
+
+Sunucu tarafında bir şey eklemeniz gerekmez: `clientAssetResponse(pathname)` `/one-components.js`'i de döndürür.
+Kişi seçici için `peopleSearchHandler` ucunu sunun (aşağıda).
+
+| Bileşen | Özellikler (JS) | Öznitelikler | Olaylar |
+|---|---|---|---|
+| `<one-table>` | `columns` (`OneTableColumn[]`), `rows` (yerel veri), `filters` (ek sorgu parametreleri), `emptyText`, `selection` (salt okunur), `reload()`, `applyFilter(detail)`, `clearSelection()` | `src` (uzak liste), `page-size` (varsayılan 20, en çok 100), `paging="page"`, `selectable` (`single` ya da çoklu), `clickable`, `export="xlsx csv"`, `export-name`, `caption`, `row-key` (varsayılan `id`), `no-search`, `lang` | `rowclick` `{ row, index }`; `selectionchange` `{ rows, keys }`; `load` `{ items, nextCursor }` |
+| `<one-form>` | `fields` (`OneFormField[]`), `value` (atamak "kaydedilmiş" hal), `submitLabel`, `dirty`, `validate()`, `setErrors(errors, detail?)`, `reset()` | `action` (aynı adres; JSON gönderir), `method` (`POST`/`PUT`/`PATCH`), `no-cancel`, `acting-write`, `lang` | `save` `{ value }` (iptal edilebilir); `saved` `{ value, response }`; `savefailed` `{ status, detail }`; `cancel`; `dirtychange` `{ dirty }` |
+| `<one-filter>` | `fields` (`OneFilterField[]`), `value`, `clear()` | `for` (tablo kimliği), `lang` | `change` `{ values, params }` |
+| `<one-person-picker>` | `value` (`OnePerson` / dizi / `null`), `label` | `src` (varsayılan `/api/one/people`), `multiple`, `required`, `disabled`, `label`, `lang` | `change` `{ value }` |
+| `<one-file-upload>` | `value` (`OneUploadedFile` / dizi / `null`), `label` | `action` (varsayılan `/api/files`), `accept`, `max-size` (bayt, varsayılan 5 MB), `multiple`, `required`, `disabled`, `name-header` (varsayılan `x-file-name`), `label`, `lang` | `uploaded` `{ file }`; `change` `{ value }` |
+| `<one-chart>` | `data` (`{ labels, series: [{ name, values }] }` ya da `[{ label, value }]`), `label` | `type` (`bar`, `line`, `pie`), `label`, `unit`, `lang` | Yok |
+
+**Alan türleri** (`OneFieldType`, veri modeliyle aynı küme): `text`, `longText`, `number`, `money`, `date`,
+`datetime`, `boolean`, `choice`, `person`, `file`. Etiketler ve seçenek adları `{ tr, en }` ya da düz metin olur;
+hepsi DÜZ METİNDİR (HTML yorumlanmaz). Kolonun `format(value, row, lang)` işlevi de düz metin döndürür.
+
+**Uzak liste sözleşmesi** (`<one-table src>`): `GET <src>?limit=&cursor=&sort=&order=asc|desc&q=&<alan>=...` isteğine
+`{ items: [...], nextCursor: "..." | null }` biçiminde yanıt verilir. Sonraki sayfa `nextCursor`'la istenir, önceki sayfaya bileşen kendi
+tuttuğu imleçle döner. `paging="page"` ile istek `page=` taşır ve yanıttaki `total` sayfa sayısını gösterir.
+Süzgeç değerleri `<one-filter>`'dan parametre olarak gelir: metin için `q`, seçim için alan adı, tarih aralığı için
+`<alan>From` / `<alan>To` (başka ad gerekiyorsa alanda `fromParam` / `toParam`). **Dışa aktarma** aynı adresi
+`format=xlsx` ya da `format=csv` ile, sayfalama parametresi OLMADAN çağırır ve gelen dosyayı köprünün
+`one.download`'ıyla indirir (ad `Content-Disposition`'dan, yoksa `export-name`).
+
+**Form:** istemci doğrulaması (zorunlu, en az/en çok karakter, sayı aralığı, biçim, tarih, seçenek) Türkçe ve İngilizce
+iletilerle; hatalı alan `aria-invalid` alır ve odak ilk hataya gider. Sunucu 4xx yanıtındaki RFC 9457 `errors` alanı
+(`{ "alan": "ileti" | ["ileti"] }` ya da `[{ "field" | "pointer": "#/alan", "detail": "..." }]`) alanlara bağlanır;
+eşleşmeyen iletiler ve `detail` formun üstünde gösterilir. Kaydedilmemiş değişiklik köprüye bildirilir
+(`one.setDirty`); Vazgeç değişiklik varsa Portal'da onay sorar. Başkası adına açılmış oturumda (Vekalet / Yerine
+Görüntüle) Kaydet kapalıdır; manifest `actingSessions: "write"` beyan eden uygulama forma `acting-write` yazar.
+
+**Kişi araması:** bileşen uygulamanın kendi ucuna gider; ucu SDK hazırlar:
+
+```ts
+import { PEOPLE_SEARCH_PATH, peopleSearchHandler } from '@devoplus/one-sdk'
+// fetch içinde (manifest scopes: "orgschema.read"):
+if (pathname === PEOPLE_SEARCH_PATH && method === 'GET') return peopleSearchHandler(request, env, ctx)
+```
+
+`GET /api/one/people?q=&lang=` yanıtı `{ items: [{ id, name, title, department }] }` biçimindedir: yalnız aktif kişiler, en az 2 en çok
+100 karakterlik arama, en çok 20 sonuç, Türkçe harf duyarsız. Yanıt **yalnız** ad, unvan ve departman taşır; e-posta,
+telefon, kullanıcı kodu ve fotoğraf DÖNMEZ (veri en azaltma). ⚠️ `id` Organization Schema kimliğidir (`sub` DEĞİL);
+bildirim gönderirken `toOrgUserIds` alanına yazın. Şema her aramada okunur; `options.loadSchema` ile kendi önbelleğinizi
+(`OneCache`) bağlayabilirsiniz.
+
+**Dosya yükleme** iskeletin dosya ucuyla uyumludur (`POST /api/files`, gövde dosyanın kendisi, ad `x-file-name`
+başlığında; başlık yalnız ASCII taşıdığı için Türkçe harfler karşılığına çevrilir). Tür ve boyut sınırı yüklemeden önce
+tarayıcıda denetlenir; sunucu yine kendi sınırını uygular. Kaldır düğmesi yalnız değeri değiştirir, dosyayı silmez.
+
+**Grafik** SVG'dir: `role="img"` + `aria-label`, ekran okuyucu için gizli veri tablosu, renkler `--one-chart-1` ile
+`--one-chart-6` arasındaki değişkenlerden (açık/koyu).
+
+| Sabit | Değer |
+|---|---|
+| `COMPONENTS_SCRIPT_PATH` | `/one-components.js` (`ONE_COMPONENTS_SCRIPT`) |
+| `ONE_COMPONENT_TAGS` | altı etiket adı |
+| `PEOPLE_SEARCH_PATH`, `PEOPLE_SEARCH_MIN_QUERY`, `PEOPLE_SEARCH_MAX_QUERY`, `PEOPLE_SEARCH_MAX_RESULTS` | `/api/one/people`, 2, 100, 20 |
+| `FILE_UPLOAD_DEFAULT_ACTION`, `FILE_UPLOAD_DEFAULT_MAX_BYTES` | `/api/files`, 5 MB |
+| `TABLE_DEFAULT_PAGE_SIZE`, `TABLE_MAX_PAGE_SIZE` | 20, 100 |
+
+Tipler: `OneTableColumn`, `OneTableElement`, `OneListResponse`, `OneFormField`, `OneFormElement`, `OneFormErrors`,
+`OneFilterField`, `OneFilterElement`, `OneFilterChange`, `OnePerson`, `OnePersonPickerElement`, `OneUploadedFile`,
+`OneFileUploadElement`, `OneChartData`, `OneChartSeries`, `OneChartElement`, `OneChoiceOption`, `OneLocalizedText`,
+`OneFieldType`, `OneComponentEventMap`; sunucu: `peopleSearchHandler`, `searchPeople` (saf), `foldPersonText`,
+`PeopleSearchItem`, `PeopleSearchEnv`, `PeopleSearchOptions`.
+
+## Backend istemcisi
+
+`new BackendClient({ baseUrl, authorization })`: `baseUrl` ortamın API tabanıdır (uygulama `vars`'ından gelir ve
+outbound allowlist'inde olmak zorundadır); `authorization` tarayıcıdan gelen `Authorization: Bearer <app_token>`
+başlığıdır ve olduğu gibi iletilir.
+
+| Metot | Davranış |
+|---|---|
+| `request<T>(path, init?)` | `api/v1/<path>`; `accept: application/json`; gövde varsa `content-type: application/json`; `init.headers` olduğu gibi eklenir (outbound yalnız `X-One-*` başlıklarını siler); `204` yanıtında `undefined` döner; `!ok` olursa `OneError(status, problem.code ?? HTTP-<status>, problem.detail ?? title)` fırlatır. Yanıtta `Retry-After` (saniye) ya da gövdede `retryAfterSeconds` varsa `OneError.retryAfterSeconds` olarak taşınır. |
+| `get<T>(path)`, `post<T>(path, body)` | kısayollar. |
+
+Backend "kullanıcı yetkisi ∩ scope" kuralını kendisi uygular; SDK ek bir yetki vermez.
+
+## Dosya servisi
+
+Manifest'te `services.files: true` ise platform kurulum başına bir dosya deposu açar ve `env.FILES`'a bağlar (D-32).
+İzolasyon depo sınırındadır: anahtara `portalId` eklenmez, başka kurulumun deposu görünmez.
+
+| Üye | Açıklama |
+|---|---|
+| `new OneFiles(env.FILES)` | |
+| `put(key, body, { contentType?, maxBytes?, metadata? })` | `FileInfo`; gövde `ArrayBuffer \| ArrayBufferView \| string \| Blob` (akış KABUL EDİLMEZ); tavan `FILE_MAX_BYTES` (25 MiB), aşımda `ONE-SDK-E-014` (413). |
+| `get(key)` | `OneStoredFileBody \| null`; dosyayı uygulamanın kendisi sunar (`writeHttpMetadata(headers)` + `httpEtag`). |
+| `head(key)`, `delete(key)`, `list({ prefix?, limit?, cursor? })` | `limit` 1-1000. |
+| `normalizeFileKey(raw)` | 1-512 karakter **ve** UTF-8 ile en çok 1.024 bayt (depo sınırı, `FILE_KEY_MAX_BYTES`), baştaki `/` atılır; boş / `.` / `..` parçası ve kontrol karakteri reddedilir (`ONE-SDK-E-010...012`). |
+| `sanitizeFileName(raw, maxLength = 120)` | kullanıcı dosya adını tek parçaya indirger (`ONE-SDK-E-013`). |
+| `readBoundedBody(request, maxBytes)` | HTTP isteğinin gövdesini **sınırlı** okur: `Content-Length` varsa tek bayt okunmadan sınanır, yoksa (parçalı aktarım) akış parça parça okunur ve sınır aşıldığı an kesilir (`ONE-SDK-E-014`, 413); bozuk `Content-Length` için hata `ONE-SDK-E-016` (400) olur. `request.arrayBuffer()` gövdenin tamamını belleğe aldıktan SONRA sınar, bu da uygulamanın belleğini taşırabilir; yükleme ucunda bunu kullanın. |
+
+## Önbellek servisi
+
+Manifest'te `services.cache: true` ise platform kurulum başına bir önbellek açar ve `env.CACHE`'e bağlar (D-35). İzolasyon
+önbellek sınırındadır. Bu bir **önbellektir**: nihai tutarlıdır (yazma başka bölgelerde 60 sn'ye kadar gecikebilir).
+Sayaç, kilit ya da kalıcı kayıt için kullanılmaz; kalıcı veri veritabanındadır.
+
+| Üye | Açıklama |
+|---|---|
+| `new OneCache(env.CACHE)` | |
+| `get<T>(key)` | `T \| null`; değer yazıldığı JSON şeklinde döner (bozuk kayıt fırlatmaz, `null`). |
+| `put(key, value, { ttlSeconds })` | TTL **zorunlu**, tam sayı, `CACHE_MIN_TTL_SECONDS` (60) ile `CACHE_MAX_TTL_SECONDS` (30 gün) arasında; sınır dışı değer `ONE-SDK-E-022`, sessizce kırpılmaz. Değer `JSON.stringify` ile yazılır; `undefined`, üst düzey `null` (okumada "anahtar yok" ile ayırt edilemezdi) ve çevrilemeyen değer `ONE-SDK-E-023`; `CACHE_VALUE_MAX_BYTES` (1 MiB) üstü `ONE-SDK-E-024` (413). |
+| `delete(key)` | |
+| `normalizeCacheKey(raw)` | kırpılır; boş / 512 bayttan uzun / tam olarak `.` ya da `..` (önbelleğin ayırdığı anahtarlar; `ONE-SDK-E-020`) ya da kontrol karakterli (`ONE-SDK-E-021`) anahtar reddedilir. |
+
+## İletişim servisi (e-posta / SMS / mobil bildirim)
+
+`sendMail(api, { toSubjects, subject, text })` `POST One/services/mail` ucunu, `sendSms(api, { toSubjects, text })`
+`POST One/services/sms` ucunu, `sendPush(api, { toSubjects, title, text })` `POST One/services/push` ucunu çağırır (aşağıda). Alıcılar devoplus-auth `sub` değerleridir; adres/telefon **sunucuda** ve yalnız aynı portalın
+aktif üyeleri için çözülür; serbest adres/numara kabul edilmez. Scope `mail.execute` / `sms.execute` hem kimlik
+sağlayıcı kaydında hem platform kayıt defterinde tanımlı olmalıdır. Yanıt `NotifyResult { queued, skipped[{ sub,
+reason }] }`; `reason` değerleri: `invalid-subject`, `not-in-portal`, `inactive`, `no-address`, `no-phone`,
+`preference`, `rate-limited`, `invalid-org-user`, `not-deliverable` (yalnız push). Kurulum başına saatlik tavan vardır (varsayılan e-posta 50, SMS 20, push 100). Backend **429**
+yalnız hiçbir ileti kuyruğa girmez **ve** atlananların tamamı `rate-limited` ise döner; başka gerekçeyle hiç kuyruğa
+girmeyen istek **200** + `queued: 0` alır. Sonucu `skipped[].reason` ile denetleyin (backend `OneServiceHandlers`,
+okundu 15.10.2026).
+
+**Org kimliğiyle alıcı (D-47):** `toOrgUserIds` alanı org şemasındaki kullanıcı kimliğini (legacy `User._id`, 24-hex) kabul eder. Yönetici zinciri ve grup üyeleri bu uzayda geldiği için onlara `sub` bulmadan bildirim gönderilebilir. `toSubjects` ile birlikte verilebilir; toplam alıcı en çok 50'dir, aynı kişi iki kez sayılmaz. Biçimi bozuk org kimliği `invalid-org-user`, portalın aktif kullanıcısı olmayan kimlik `not-in-portal` ile atlanır. ⛔ İki kimlik uzayını karıştırmayın: `ctx.user.sub` org kimliği DEĞİLDİR (ikisi de 24-hex; karışırsa hata vermez, kişi `not-in-portal` ile sessizce atlanır).
+
+### Mobil bildirim (D-55; ⚠️ geliştirici onayı bekliyor)
+
+`sendPush(api, { toSubjects, toOrgUserIds?, title, text })`, `POST One/services/push` ucunu çağırır; scope `push.execute`. Devoplus
+Portal mobil uygulamasına **yalnız başlık + metin** gider (başlık 1-100, metin 1-300 karakter; bu sınırı sunucu uygular, SDK
+`sendPush` istemci denetimi yapmaz, hazır senaryolar `toPush` ile kırpar). Derin bağlantı ya da veri yükü **yoktur**
+(mobil uygulamanın okuduğu veri anahtarı ölçülmedi). Alıcı kuralları e-posta/SMS ile aynıdır; yeni atlama gerekçesi
+`not-deliverable` = kişinin bildirim tercihi kapalı **ya da** mobil kimliği çözülemedi (sunucu ikisini ayırt edemez).
+⚠️ Push bugün **hiçbir ortamda açık değildir**: uç kuyruğa almadan `OneError` `ONE-APP-E-029` ile reddeder (kapalı
+kanal sessiz başarı gibi görünmesin). Kodunuz bu hatada çalışmayı sürdürmeli; `notify` kanalları bağımsız gönderir.
+
+### Hazır bildirim senaryoları (D-47)
+
+`approvalRequest`, `approvalResult`, `reminder`, `systemNotice`, `operationResult`, `verificationCode` aynı girdiden e-posta konusu + gövdesi ve SMS metni üretir (`ScenarioMessage { subject, text, smsText }`; Türkçe resmi "siz" ya da `lang: 'en'`). Metinler backend sınırlarına göre kırpılır (konu ≤ 200, SMS ≤ 300; e-posta gövdesi 10.000'i aşarsa `ONE-SDK-E-062`). Bağlantı yalnız `https` olabilir ve kullanıcı adı/parola taşıyamaz (`normalizeLink`, `ONE-SDK-E-061`). `notify(api, message, { toSubjects?, toOrgUserIds?, channels })` kanalları (`mail`, `sms`, `push`) **bağımsız** gönderir: SMS ya da push düşse de e-posta gider; sonuç kanal adıyla döner, düşen kanal `{ error }` taşır. `toPush(message, to)` başlığı e-posta konusundan (≤ 100, `PUSH_TITLE_MAX_LENGTH`), metni SMS metninden (≤ 300, `PUSH_TEXT_MAX_LENGTH`) kurar; kırpma bir emojiyi ortasından bölmez.
+
+```ts
+import { approvalChain, approvalRequest, getMyOrgContext, getOrgUsersWithManagers, notify } from '@devoplus/one-sdk'
+
+const me = await getMyOrgContext(api)            // null: kişinin bu portalda org kaydı yok
+if (me) {
+  const users = await getOrgUsersWithManagers(api, { includeInactive: true })   // pasifler de gelsin ki atlanabilsin
+  const [first] = approvalChain(users, me.orgUserId)   // işlevsel yönetici zinciri, pasifler atlanır
+  if (first) {
+    const message = approvalRequest({ appName: 'İzin Talepleri', item: '3 günlük yıllık izin', requester: me.fullName ?? '', link })
+    await notify(api, message, { toOrgUserIds: [first], channels: ['mail'] })
+  }
+}
+```
+
+### Doğrulama kodu (D-47)
+
+`generateVerificationCode(digits = 6)` (4-10 hane, yanlılıksız); `generateSalt()`; `hashVerificationCode({ code, salt, purpose, sub })`; `verificationCodeMatches({ ..., hash })` (sabit süreli karşılaştırma). Özet **amaca ve kişiye** bağlıdır: başka bir işlem ya da başka bir kişi için üretilmiş kod kabul edilmez. Kodun kendisini değil `salt + hash + son kullanma + deneme sayısı`nı uygulamanın **veritabanında** saklayın (önbellek nihai tutarlıdır; deneme sayacı ve tek kullanım orada güvenilir değildir). Süreyi ve deneme tavanını (ör. 5) uygulama uygular; doğru koddan sonra kaydı silin.
+
+## Organizasyon şeması (D-47)
+
+Scope `orgschema.read` (salt okuma) + kullanıcının kendi `Portal.Generic.Read` izni. Veri aktif portalın aktif kayıtlarıdır.
+
+| İşlev | Uç | Not |
+|---|---|---|
+| `getOrgSchema(api)` | `GET OrganizationManagement/organization-schema` | şirket, iş yeri, departman, pozisyon, ünvan, çalışan türü, kullanıcı grubu, kullanıcı |
+| `getOrgUsersWithManagers(api, { includeInactive? })` | `GET OrganizationManagement/users` (`includeInactive` karşılığı `?hideInactiveDocuments=false`) | yönetici alanlarını (`functionalManager` / `operationalManager`) taşıyan TEK uç; boş metin = yönetici yok. Uç varsayılan olarak yalnız aktifleri döner; onay zinciri kurarken `includeInactive: true` verin, yoksa zincir pasif yöneticide kesilir. ⚠️ Yanıt iletişim bilgisi de taşır, saklamayın |
+| `getMyOrgContext(api)` | `GET Users/me` | oturumdaki kişinin org kimliği (`orgUserId`); org kaydı yoksa `null` |
+| `getUserGroupMembers(api, groupId)` | `GET OrganizationManagement/user-groups/{id}/users` | üyelik SUNUCUDA çözülür (yedi boyutun VEYA'sı + iç içe gruplar); istemcide türetmeyin |
+| `getUserGroupsOfUser(api, orgUserId)` | `GET OrganizationManagement/users/{id}/user-groups` | |
+
+Saf yardımcılar (ağ yok): `managerOf(users, orgUserId, kind?)`; `approvalChain(users, orgUserId, { kind?, maxDepth?, skipInactive? })` (döngüye ve kendine yöneticiye karşı güvenli; pasif yönetici varsayılan olarak atlanır ve zincir onun yöneticisinden sürer; derinlik varsayılan 5, en çok 20); `approvalChainReport(...)` (aynı zincir ve durma nedeni: `top`, `depth`, `unknown` ya da `cycle`; boş zinciri "onaycı yok" diye okumadan önce bakın); `orgUsersMatching(schema, criteria)` (verilen boyutların hepsine uyan aktif kullanıcılar; ölçütsüz çağrı `ONE-SDK-E-051`); `localizedText(text, lang?)`. Şemada departman/pozisyon hiyerarşisi alanı **yoktur**; zincir yalnız kişi kayıtlarındaki yönetici alanlarından kurulur.
+
+## DEXA (ERP okuma) servisi
+
+`queryDexa(api, key, parameters?)`, `POST One/services/dexa/query` ucunu çağırır. Uygulama ERP verisini **yalnız önceden tanımlı
+QueryStore anahtarlarıyla** okur (D-09; uç D-42, ⚠️ geliştirici onayı bekliyor): serbest SQL, ERP'ye yazan anahtar ya
+da desteklenmeyen sorgu türü çalıştırılamaz. Hangi anahtarın çalışabileceğinin **tek kaynağı platform kayıt
+defteridir**: anahtarları Admin Console'da uygulamanın kaydına yönetici ekler; kayıtta olmayan anahtar 403
+`ONE-APP-E-024` alır. Manifest `services.dexa.queryKeys` yalnız **beyandır** (çalışma anında okunmaz) ve `scopes`
+içinde `dexa.read` ile birlikte yazılır; biri eksikse manifest doğrulaması düşer. Belirteçte `dexa.read` yoksa
+backend 403 `ONE-APP-E-017` döner.
+
+```ts
+import { BackendClient, queryDexa, requireScope } from '@devoplus/one-sdk'
+
+requireScope(ctx, 'dexa.read')
+const api = new BackendClient({ baseUrl: env.API_BASE, authorization: request.headers.get('authorization') })
+// Anahtar ve parametre adları sorgu tanımından (QueryStore) gelir; buradakiler yalnız örnektir.
+const result = await queryDexa(api, 'Ornek.Rapor', { StartDate: '2026-10-01' })
+
+if (result.unavailable) {
+  // Sorgu ÇALIŞAMADI (DEXA tüneli kurulmamış / ERP'ye ulaşılamıyor / sorgu düştü): boş liste "kayıt yok" DEĞİLDİR.
+  return Response.json({ status: 'unavailable', message: 'Veriler şu anda getirilemiyor; lütfen daha sonra deneyin.' }, { status: 503 })
+}
+return Response.json({
+  columns: result.columns,
+  rows: result.rows,                           // boşsa gerçekten kayıt yoktur
+  truncated: result.truncated,                 // true: sunucu sonucu 5.000 satırda kesti, süzgeci daraltın
+})
+```
+
+| Alan | Anlam |
+|---|---|
+| `columns: string[]` | Kolon adları (sıra korunur). |
+| `rows: Array<Record<string, unknown>>` | Satırlar (kolon adı: değer). |
+| `unavailable: boolean` | `true` = sorgu çalışamadı; kullanıcıya "şu anda getirilemiyor" gösterin, "kayıt yok" değil. Sunucu **200** döner, SDK **fırlatmaz**. Yanıt gövdesi hiç nesne değilse (boş/bozuk) SDK da `true` sayar. |
+| `truncated: boolean` | `true` = sunucu sonucu 5.000 satırda kesti; liste eksiktir. |
+
+Eksik dizi `[]`, eksik bayrak `false` olarak okunur (`normalizeDexaQueryResult`). İstemci tarafı kurallar sunucuyla
+birebirdir ve istek **gönderilmeden** fırlatır (`buildDexaQueryRequest`; programlama hatası):
+
+| Kural | Sabit | Hata |
+|---|---|---|
+| Anahtar `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`, harf duyarlı | `DEXA_KEY_RE` | `ONE-SDK-E-040` |
+| Parametreler `{ ad: metin }` nesnesi, en çok 32 | `DEXA_MAX_PARAMETERS` | `ONE-SDK-E-041` |
+| Ad `^[A-Za-z_][A-Za-z0-9_]{0,63}$` | `DEXA_PARAMETER_NAME_RE` | `ONE-SDK-E-042` |
+| `LangCode` gönderilemez: platformun bağlam parametresidir, sunucu doldurur; denetim **harf duyarsızdır** (`langcode` da reddedilir) | `DEXA_RESERVED_PARAMETERS` | `ONE-SDK-E-043` |
+| `UserCode`, `CompanyCode` ve `CostCenterCode` gönderilebilir ama **boş olamaz** (boş dize ya da yalnız boşluk; ad harf duyarsız tanınır) | `DEXA_APP_CONTEXT_PARAMETERS` | `ONE-SDK-E-140` |
+| Değer metin, en çok 2.000 karakter (sayı/tarih `String(...)` ile) | `DEXA_PARAMETER_VALUE_MAX_LENGTH` | `ONE-SDK-E-044` |
+
+Sunucu hataları `OneError.code` ile taşınır: 403 `ONE-APP-E-011...017` (kapı; `-017` = `dexa.read` yok); 403
+`ONE-APP-E-024` (anahtar kayıt defterinde yok); 400 `ONE-APP-E-025` (anahtar çalıştırılamaz: katalogda yok / ERP'ye
+yazan anahtar / desteklenmeyen sorgu türü); 400 `ONE-APP-E-026` (parametre izinli değil: sorgu tanımlamıyor,
+`LangCode`, ya da kurulumda onay yokken gönderilen bağlam kodu); 403 `ONE-APP-E-027` (sorgu kişiye bağlı bir bağlam,
+`UserCode` ya da `CompanyCode`, istiyor ve oturumdaki kişiden çözülemedi; sorgu ÇALIŞTIRILMAZ, boş değerle "tüm
+kayıtlar"a dönmez; oturumdan çözülen bağlam değeri boş kaldığında da bu kod döner); 429 `ONE-APP-E-018` (kurulum
+başına saatte 600 sorgu); 400 `ONE-APP-E-076` (gönderilen bağlam kodu geçersiz: boş, 64 karakterden uzun ya da kontrol
+karakteri içeriyor); 403 `ONE-APP-E-077` (gönderilen `UserCode` ya da `CompanyCode` kurulumun portalında tanımlı değil);
+400 `ONE-APP-E-078` (arka plan işinde sorgu bir bağlam kodu istiyor ve uygulama onu göndermedi).
+
+### Bağlam kodları: `UserCode`, `CompanyCode`, `CostCenterCode` (C7)
+
+Sorgu bu kodlardan birini bildiriyorsa değer şu sırayla belirlenir:
+
+| Durum | Uygulama kodu gönderdi | Uygulama kodu göndermedi |
+|---|---|---|
+| Kurulumda yönetici **"kodları uygulama belirler"** onayını vermedi | 400 `ONE-APP-E-026` ile reddedilir | kişi / ajan kipinde oturumdaki kişiden çözülür; arka plan işinde reddedilir |
+| Onay verildi, kişi (Portal) ya da ajan kipi | sunucu doğrular, gönderilen kullanılır | oturumdaki kişiden çözülür |
+| Onay verildi, arka plan işi | sunucu doğrular, gönderilen kullanılır | çözülecek oturum olmadığı için **reddedilir** |
+
+- **Portal doğrulaması:** `UserCode` kurulumun portalındaki **aktif** bir kişinin kodu, `CompanyCode` aynı portaldaki bir
+  şirketin kodu olmalıdır; değilse sorgu ERP'ye gitmeden reddedilir (`ONE-APP-E-077`). `CostCenterCode` için portalda
+  karşılaştırılacak bir kayıt yoktur: yalnız biçimi denetlenir (boş değil, en çok 64 karakter, kontrol karakteri yok). Uygulamanın gönderdiği kodla yapılan her çağrı
+  denetim günlüğüne yazılır.
+- **Boş değer ERP'ye gitmez:** gönderilen ya da oturumdan çözülen değer boşsa sorgu çalışmaz. SDK boş dizeyi ve yalnız
+  boşluğu istek göndermeden reddeder (`ONE-SDK-E-140`). Kodu bilmiyorsanız parametreyi **hiç göndermeyin**.
+- **`CostCenterCode` artık açıktır:** onu bildiren sorgular çalışır. Uygulama göndermezse değeri sunucu kişiden çözer;
+  çözülemezse sorgu reddedilir.
+- **`LangCode` platformundur:** uygulama hiçbir kipte gönderemez (`ONE-SDK-E-043`).
+
+```ts
+// Arka plan işinde (oturum yok) kişiye bağlı bir sorgu: kodu uygulama verir. Kurulumda onay yoksa sunucu reddeder.
+const stock = await queryDexa(api, 'Ornek.MagazaStok', { CompanyCode: '01', StoreCode: storeCode })
+```
+
+## DEXA işlemleri: ERP'ye veri yazma (D-56; ⚠️ geliştirici onayı bekliyor)
+
+`runDexaCommand(api, key, parameters, { idempotencyKey })`, `POST One/services/dexa/command` ucunu `Idempotency-Key`
+başlığıyla çağırır; `getDexaCommandStatus(api, idempotencyKey)` ise `GET One/services/dexa/command/{anahtar}` ucunu. Scope **`dexa.write`**.
+Okuma sorgularından (`queryDexa`) ayrıdır: bu uç ERP'ye **VERİ YAZAR**. Çalışması dört kapının kesişimidir:
+
+1. Belirteçte `dexa.write` (yoksa 403 `ONE-APP-E-017`).
+2. Anahtar uygulamanın kayıt defterindeki işlem izin listesinde (`dexaCommandKeys`, Admin Console; yoksa 403 `ONE-APP-E-030`).
+3. Anahtar koddaki ERP komut kataloğunda **One uygulamalarına açık** (yoksa 404 `ERPCMD-APP-E-006`; açmak backend kod
+   değişikliğidir; ⚠️ bugün açık hiçbir işlem yoktur).
+4. Kullanıcının o işleme özgü izni (yoksa 403 `ERPCMD-APP-E-0xx`).
+
+Manifest `services.dexa.commandKeys` yalnız **beyandır** ve `scopes` içinde `dexa.write` ile birlikte yazılır.
+
+⛔ **Idempotency (kod yazmadan önce okuyun):**
+
+| Durum | Ne yapılır |
+|---|---|
+| Yeni kullanıcı eylemi ("Kaydet"e basış) | `newIdempotencyKey()` ile anahtar üretin ve isteği göndermeden ÖNCE veritabanına yazın |
+| Ağ hatası / zaman aşımı | AYNI anahtarla tekrar deneyin ya da `getDexaCommandStatus` ile okuyun; ERP'ye ikinci kez yazılmaz (`replayed: true`) |
+| 409 `ERPCMD-APP-E-016` (aynı işlem sürüyor) | `error.retryAfterSeconds` kadar bekleyin, durumu okuyun ya da AYNI anahtarla deneyin. Hatayı `problemResponse(error)` ile tarayıcıya döndürürseniz yanıt bu süreyi `Retry-After` başlığında ve gövdedeki `retryAfterSeconds` alanında taşır (yalnız pozitif tam sayıysa) |
+| 424 `ERPCMD-APP-E-013` (ERP bağlantısı kurulamadı) | hiçbir şey gönderilmedi; AYNI anahtarla tekrar denenebilir |
+| 409 `ERPCMD-APP-E-015` (anahtar farklı içerikle kullanılmış) | programlama hatası: anahtar başka bir eylemle karışmış |
+| 200 `outcome: 'succeeded'` | ERP kaydı oluştu (`erp.headerId` / `erp.documentNumber`) |
+| 200 `outcome: 'rejected'` | ERP reddetti (`erp.exceptionMessage`); aynı içerikle tekrar yine reddedilir |
+| 200 `outcome: 'inDoubt'` | ERP'ye gidip gitmediği **BİLİNMİYOR**: YENİ anahtarla **ASLA** yeniden göndermeyin (çift kayıt); durumu okuyun, kullanıcıya "sonuç doğrulanamadı" deyin |
+
+```ts
+import { BackendClient, getDexaCommandStatus, newIdempotencyKey, requireScope, runDexaCommand } from '@devoplus/one-sdk'
+
+requireScope(ctx, 'dexa.write')
+const api = new BackendClient({ baseUrl: env.API_BASE, authorization: request.headers.get('authorization') })
+// Anahtar eylem başına BİR KEZ üretilir ve göndermeden önce saklanır (tablo ve sütun adları örnektir).
+const idempotencyKey = newIdempotencyKey()
+await env.DB.prepare('INSERT INTO erp_ops (id, sub, state) VALUES (?, ?, ?)').bind(idempotencyKey, user.sub, 'sent').run()
+// İşlem anahtarı ve parametre adları QueryStore tanımından gelir; buradakiler yalnız örnektir.
+const result = await runDexaCommand(api, 'Ornek.Islem', { Body: JSON.stringify(model) }, { idempotencyKey })
+if (result.outcome === 'inDoubt') {
+  // Yeni anahtarla TEKRAR GÖNDERMEYİN. Durum daha sonra getDexaCommandStatus(api, idempotencyKey) ile okunur.
+}
+```
+
+`DexaCommandResult` alanları backend `ErpCommandResponse` ile birebirdir: `queryStoreKey`, `idempotencyKey` (sunucunun
+küçük harf biçimi), `replayed`, `outcome`, `correlationId`, `erp { shape, isSuccessful, headerId, documentNumber,
+exceptionMessage, lines, raw }`. SDK sözleşmeye uymayan her 200 yanıtını **`inDoubt`** sayar: nesne olmayan gövde,
+bilinmeyen `outcome`, backend kaydında nullable olmayan bir alanın eksik olması ya da herhangi bir alanın yanlış tipte
+olması, **gönderilenden farklı `idempotencyKey`** ya da farklı `queryStoreKey` (yalnız ASCII büyük/küçük harf farkı
+aynı anahtardır: backend katalogdaki yazımı döner). O durumda gövdeden hiçbir alan sonuca taşınmaz (anahtarlar
+gönderilenlerdir, `correlationId: null`, `erp.shape: 'unrecognized'`); doğru sonuç AYNI anahtarla durum sorgusundan
+okunur.
+`getDexaCommandStatus` backend `ErpCommandStatusResponse`'u döner (`outcome` ayrıca `pending` ya da `notSent` olabilir;
+`attemptCount`, `createdAtUtc`, `completedAtUtc`, `erp`, `steps`, `kind`, `warnings`) ya da kayıt yoksa
+(`404 ERPCMD-APP-E-017`) **`null`** döner; o anahtarla hiçbir şey kaydedilmemiştir ve AYNI anahtarla gönderilebilir. Durum
+yanıtı da aynı kuralla doğrulanır (komut anahtarı istekte olmadığı için `queryStoreKey` yalnız tipiyle); ayrıca
+`succeeded`/`rejected` `erp` görünümü olmadan kabul edilmez.
+
+İstemci tarafı kurallar istek **gönderilmeden** fırlatır (`buildDexaCommandRequest` / `normalizeIdempotencyKey`):
+
+| Kural | Sabit | Hata |
+|---|---|---|
+| Anahtar `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`, harf duyarlı | `DEXA_KEY_RE` | `ONE-SDK-E-045` |
+| Parametreler `{ ad: metin }` nesnesi, en çok 32 | `DEXA_MAX_PARAMETERS` | `ONE-SDK-E-046` |
+| Ad `^[A-Za-z_][A-Za-z0-9_]{0,63}$` | `DEXA_PARAMETER_NAME_RE` | `ONE-SDK-E-047` |
+| Değer metin (null olamaz), en çok 65.536 karakter (`Body` model JSON'u taşır) | `DEXA_COMMAND_PARAMETER_VALUE_MAX_LENGTH` | `ONE-SDK-E-048` |
+| `Idempotency-Key` kanonik UUID (8-4-4-4-12), boş UUID değil; SDK küçük harfe çevirir | `IDEMPOTENCY_KEY_RE` | `ONE-SDK-E-049` |
+
+Sorgulardaki ayrılmış bağlam parametresi yasağı (`LangCode` vb.) işlemlerde **yoktur**, çünkü sunucu böyle bir kural
+uygulamıyor. 4xx yanıtların hepsi ERP'ye **hiçbir şey gönderilmediği** anlamına gelir; ayrıca 429 `ONE-APP-E-018`
+(kurulum başına saatte 300 işlem).
+
+## Zamanlanmış görev ve kuyruk (D-80)
+
+Uygulama işi manifest `jobs` ile **beyan eder** ve işleyicisini yazar; işi platform tetikler. Ayrıntı ve örnek:
+ajan belgesi `/docs/jobs.md`; manifest kuralları `docs/manifest.md` içindeki `jobs` bölümünde.
+
+| Üye | Açıklama |
+|---|---|
+| `defineJobs({ schedules?, queues? }): OneJobsDefinition` | İşleyicileri ada göre tanımlar; ad manifest beyanıyla aynı olmalı (`JOB_NAME_RE`; geçersiz ad hemen `ONE-SDK-E-070`). Son tanım `handleJobRequest`'in varsayılanıdır. |
+| `OneJobHandler` | `(job: OneJob, env, ctx: OneContext, execution) => unknown`; `ctx` platform bağlamıdır (`readContext`). |
+| `OneJob` | `{ id, name, kind: 'schedule' \| 'queue', attempt, body, scheduledTime?, enqueuedAt? }`. `id` her denemede AYNIDIR (tekrar eleme anahtarı); `attempt` 1'den başlar; tarih alanları ISO 8601 (UTC). |
+| `handleJobRequest(request, env, execution, definition?): Promise<Response> \| null` | Yol `/__one/jobs/...` değilse `null` (uygulama kendi yönlendirmesine geçer). Bu yolda yalnız platform işaretli (`X-One-Auth: job`) `POST` işlenir, başka her şey `404 ONE-SDK-E-075`. İşleyici dönerse 200; 4xx `OneError` fırlatırsa o durum (kalıcı hata, yeniden denenmez); başka hata 500 (platform geri çekilmeyle yeniden dener). |
+| `enqueue(name, body, { delaySeconds? }): Promise<{ id }>` | Kuyruğa ileti bırakır. Ad manifest `jobs.queues` içinde beyanlı olmalı (yoksa platform 404 `ONE-OUT-E-011`); gövde JSON ≤ 64 KiB (`JOB_BODY_MAX_BYTES`), gecikme 0-86.400 sn (`JOB_DELAY_MAX_SECONDS`). Kimlik istekten damgalanır; Vekalet / Yerine Görüntüle oturumunda, uygulama yazmaya açık değilse 403 `ONE-OUT-E-015`. |
+
+⛔ Aynı iş birden çok kez gelebilir: kalıcı yazımı `job.id` ile tekrarsız yapın (birincil anahtar + `INSERT OR IGNORE`).
+Kuyruk işi iletiyi bırakanın `sub`'unu bilgi olarak taşır (`ctx.user`); uygulama izinleri ve yönetici bilgisi işe
+taşınmaz. Zamanlanmış iş kullanıcısızdır (`ctx.user` null). İkisinde de Devoplus servisleri **uygulamanın kimliğiyle**
+çağrılır (bkz. aşağıdaki bölüm). `/__one/` yolu platforma ayrılmıştır ve internetten kapalıdır. Yerelde (`one dev`) zamanlama
+tetiklenmez ve `enqueue` 503 döner.
+
+## Devoplus servisleri arka plan işinde ve ajan aracında (C6)
+
+İşte ve ajan aracında tarayıcıdan gelen bir belirteç yoktur; servis istemcileri (`BackendClient`) yine de çağrı yapar:
+platform çıkış katmanı isteği doğru kimlikle Devoplus'a taşır (`new BackendClient({ baseUrl, authorization: null })` ya
+da `request.headers.get('authorization')`, ikisi de olur). Uygulamanın yazdığı `Authorization` başlığı bu iki yolda
+Devoplus'a **iletilmez**.
+
+| Yol | Kimin adına | Kullanılabilen servisler |
+|---|---|---|
+| Kuyruk / zamanlanmış iş (`ctx.mode === 'job'`) | **Uygulamanın** kendi kimliği; kişi yoktur | Yalnız manifest `jobs.services` ile beyan edilip **kurulumda portal yöneticisinin onayladığı** servisler: `mail.execute`, `sms.execute`, `push.execute`, `dexa.read`, `ai.use` (her biri manifest `scopes`'ta da olmalı). Onaysız servis 403 alır. ⛔ DEXA'ya yazma (`dexa.write`) bu yolla **açılmaz**. "Kendime gönder" yoktur: alıcıyı açıkça verin. Denetim kaydında aktör uygulamadır. |
+| Ajan aracı (`ctx.mode === 'agent'`) | Aracı çağıran **kişi** | Kişinin bu uygulamada yapabildikleri; süreli onay gerektiren scope'lar (`CONSENT_SCOPES`: e-posta, SMS, mobil bildirim ve DEXA'ya yazma) bu yolda **kullanılamaz** (kişi onay ekranını göremez). `ctx.admin`: kişi kurulumun portalının şirket yöneticisi; `ctx.actor`: Vekalet / Yerine Görüntüle oturumunda işlemi yapan kişi. |
+
+```jsonc
+// one.manifest.json
+"scopes": ["ai.use", "mail.execute"],
+"jobs": { "schedules": [{ "name": "weekly-summary", "cron": "0 8 * * 1" }], "services": ["ai.use", "mail.execute"] }
+```
+
+## Günlük
+
+`logEvent(ctx, level, message, data?)` sistem/çalışma zamanı olayı; `logError(ctx, message, error, data?)` beklenmeyen
+hata (ad, ileti ve en çok 4.000 karakterlik yığın; `OneError` kodu ve durumu korunur); `logAudit(ctx, action, target?,
+data?)` kritik kullanıcı işlemi; aktör zorunludur (anonim bağlamda fırlatır). Hepsi tek satır JSON olarak yazılır ve
+**platform günlüğünde saklanır**: platform her kurulumda günlüğü açar (D-45), örnekleme manifest
+`observability.headSamplingRate` (varsayılan 1). Satırları platform ekibi kurulum (uygulama × portal) süzgeciyle
+görür; uygulama geliştiricisine açık bir görüntüleme ekranı bu sürümde yoktur.
+
+Koruma: `data` içinde adı parola, token, secret, authorization, cookie, API anahtarı, private key, credential ya da
+parola/şifre geçen alanların değeri `"[gizli]"` olur (her derinlikte, girdi değişmez; `redact`); JSON'u 8 KiB'ı aşan
+`data` yerine `{ truncated, bytes }` yazılır (platform günlüğü çağrı başına en çok 256 KB tutar, aşan kısım düşer;
+`safeData`); ileti 1.000 karakterde kırpılır. Maskeleme bir emniyet ağıdır, izin değildir: kişisel veri ve sır yazmayın.
+`problemResponse(error, ctx?)` bilinmeyen hatayı bu kayda (`ctx` verilirse bağlamıyla) düşer; yanıtta yalnız sabit
+metin döner.
+
+## Denetim günlüğü (kalıcı)
+
+`recordAudit(api, ctx, action, target?, data?)`, `logAudit` izini yazar **ve** `POST One/services/audit` ile
+Devoplus denetim günlüğüne kaydeder (scope `audit.write`; D-36). Kayıt Admin Console Denetim Günlüğü'nde "Devoplus
+One uygulaması" türüyle, `reason = {slug}:{action}`, `targetLabel = target`, `details = data` olarak görünür; aktör
+ve portal istekle gönderilmez, backend doğrulanmış bağlamdan alır. Kurallar sunucuyla birebir: `action`
+`^[a-z0-9][a-z0-9._:-]*$` ≤ 64, `target` ≤ 200, `data` JSON nesnesi ≤ 4 KiB (`buildAuditRequest`; ihlal
+`ONE-SDK-E-030...032` ile FIRLATIR, çünkü programlama hatasıdır). Uzak yazma **best-effort**: ağ/kapı hatası
+`{ recorded: false }` + uyarı olayı döner, isteğiniz düşmez. ⛔ `target`/`data`ya kişisel veri ya da sır yazmayın
+(365 gün saklanır).
+
+## Yapay zeka servisi (D-88 a; ⚠️ öneri, geliştirici onayı bekliyor)
+
+`completeAi(api, ctx, istek)` (eşdeğeri `ai.complete`), `POST One/services/ai` ucunu çağırır (scope `ai.use`; kullanıcıdan ayrıca
+onay istenmez). Diğer `One/services/*` uçlarıyla aynı kapıdan geçer; kullanıcı, portal ve uygulama istekle GÖNDERİLMEZ.
+
+```ts
+const { output } = await completeAi(api, ctx, { task: 'summarize', input: metin, instructions: 'üç madde', lang: 'tr' })
+const { label } = await completeAi(api, ctx, { task: 'classify', input: talep, labels: ['acil', 'normal'] })
+const { json } = await completeAi(api, ctx, { task: 'extract', input: fatura, schema: { type: 'object', properties: { tutar: { type: 'number' } } } })
+```
+
+| Alan | Kural (istemcide de denetlenir; ihlal istek gönderilmeden FIRLATIR) |
+|---|---|
+| `task` | `summarize`, `classify`, `extract`, `generate`, `chat` (`ONE-SDK-E-080`) |
+| `input` | 1-24.000 karakter (`ONE-SDK-E-081`) |
+| `instructions`, `lang` | ≤ 4.000 karakter; `tr` / `en` (`ONE-SDK-E-082`) |
+| `labels` | yalnız `classify`; 2-50 tekil etiket, her biri ≤ 100 karakter (`ONE-SDK-E-083`) |
+| `schema` | yalnız `extract`; JSON nesnesi ≤ 8 KiB (`ONE-SDK-E-084`) |
+| `messages` | yalnız `chat`; ≤ 20 ileti, `role` = `user` ya da `assistant`, `content` dolu metin (`ONE-SDK-E-085`) |
+
+Yanıt `OneAiResult`: `output` (metin), `json?` (alan çıkarma), `label?` (sınıflandırma), `model`, `usage`
+(`inputTokens`, `outputTokens`). Tanınmayan yanıt `ONE-SDK-E-086` fırlatır. Model, kota ve portalda yapay zekanın açık
+olup olmadığı Devoplus'tadır: kapalı/yapılandırılmamış portalda 503, kota dolunca 429 (`OneError`). ⛔ Model **sayı
+hesaplamaz** ve **kayıt yazmaz**: tutar/toplam/tarih farkı kodda hesaplanıp `input`'a hazır verilir; çıktı bir öneridir,
+veritabanına yazmadan önce kod doğrular. `input`'a sır ya da işin gerektirmediği kişisel veri konmaz.
+
+## Devoplus yapay zekasına açılan araçlar (D-88 b; ⚠️ öneri, geliştirici onayı bekliyor)
+
+Devoplus yapay zekası, kullanıcı Devoplus'ta bir soru sorduğunda uygulamanın verisine ve işlemlerine yalnız manifest
+`agent.tools[]` ile beyan edilen **araçlarla**, kullanıcının kendi kimliğiyle ulaşır. Her araç üç yerde durur: manifest
+beyanı (ad, TR/EN başlık + açıklama, `readOnly`, `permission?`, `input` şeması) + işleyici + `AGENT_GUIDE.md`.
+
+```ts
+import guide from '../AGENT_GUIDE.md' with { type: 'text' } // derlemede metin olarak gömülür
+import manifest from '../one.manifest.json' with { type: 'json' }
+
+const tools = defineAgentTools<Env>({
+  'list-notes': { handler: async ({ input, ctx, env }) => ({ notes: await notlariGetir(env, ctx.user!.sub, input.limit) }) },
+})
+
+export default {
+  async fetch(request, env) {
+    const agent = (await handleAgentRequest(request, env, tools, manifest)) ?? agentManifestResponse(request, manifest, guide)
+    if (agent) return agent
+    // ... uygulamanın kendi yönlendirmesi
+  },
+} satisfies OneApp<Env>
+```
+
+`handleAgentRequest` yalnız `POST /__one/agent/<ad>` için yanıt üretir (başka yolda `null`). Kapılar sırasıyla:
+`X-One-Invoked-By: devoplus-agent` (yalnız platformun imzalı çağrısı yazar; tarayıcıdan gelen 404); araç manifest'te
+VE `defineAgentTools`'ta (beyansız 404 `ONE-SDK-E-091`, işleyicisiz 501 `ONE-SDK-E-092`); oturum; `readOnly: false`
+araç Vekalet / Yerine Görüntüle oturumunda 403 (`ONE-SDK-E-095`); `permission` varsa `hasPermission` (403
+`ONE-SDK-E-004`); gövde JSON ve ≤ 256 KiB (`ONE-SDK-E-093`); girdi şemaya uygun (400 `ONE-SDK-E-094` + `errors:
+[{ path, message }]`). İşleyici `{ input, ctx, env }` alır, JSON'a çevrilebilir bir değer döndürür; fırlattığı `OneError`
+ProblemDetails olur. `ctx.admin` çağıran kişinin kurulumun portalının şirket yöneticisi olduğunu, `ctx.actor` Vekalet /
+Yerine Görüntüle oturumunu bildirir. İşleyici Devoplus servislerini kişi adına çağırabilir; süreli onay gerektiren
+scope'lar (e-posta, SMS, mobil bildirim ve DEXA'ya yazma) bu yolda kullanılamaz.
+
+Girdi şeması JSON Schema'nın dar bir alt kümesidir: `type` (`object`, `string`, `number`, `integer`, `boolean`,
+`array`), `properties`, `required`, `enum`, `minimum`, `maximum`, `minLength`, `maxLength`, `items`,
+`description` (`AGENT_INPUT_KEYWORDS`). ⛔ Nesneler kapalıdır: şemada olmayan alan reddedilir. Doğrulayıcı
+`validateAgentInput(şema, girdi)` olarak da dışa açıktır.
+
+`agentManifestResponse(request, manifest, guide)` oturum istemeden `GET /.well-known/one-agent.json` (yalnız
+`app: { slug, name }` + `agent`) ve `GET /.well-known/one-agent.md` (`AGENT_GUIDE.md`, ≤ 256 KiB) sunar; manifest'te
+`agent` yoksa 404. Rehbere kullanıcı verisi, sır ya da iç adres yazılmaz.
+
+## Veri modeli ve kayıt işlemleri (D-84; ⚠️ geliştirici onayı bekliyor)
+
+Kayıt tutan uygulamada tabloyu, tipleri ve uçları elle yazmak yerine `one.data.json`'da **varlıkları ve alanları**
+tanımlayın; gerisini `one data generate` ve `createCrudHandler` yapar.
+
+```json
+{
+  "version": 1,
+  "entities": {
+    "talepler": {
+      "title": { "tr": "Talepler", "en": "Requests" },
+      "fields": {
+        "baslik": { "type": "text", "title": { "tr": "Başlık", "en": "Title" }, "required": true, "maxLength": 120 },
+        "tutar":  { "type": "money", "title": { "tr": "Tutar", "en": "Amount" }, "min": 0 },
+        "durum":  { "type": "choice", "title": { "tr": "Durum", "en": "Status" }, "required": true, "default": "acik", "index": true,
+                    "choices": [ { "value": "acik", "title": { "tr": "Açık", "en": "Open" } },
+                                 { "value": "kapali", "title": { "tr": "Kapalı", "en": "Closed" } } ] },
+        "sorumlu": { "type": "person", "title": { "tr": "Sorumlu", "en": "Owner" } }
+      }
+    }
+  }
+}
+```
+
+| Tür | Saklanan | API'de | Kural |
+|---|---|---|---|
+| `text` / `longText` | metin | metin | `maxLength` (varsayılan 200 / 10.000; en çok 1.000 / 50.000); `text` tek satır |
+| `number` | ondalıklı sayı | sayı | `min` / `max` |
+| `money` | **kuruş, tam sayı**; kolon `<ad>_minor` | `"1234.50"` (metin) | en çok iki ondalık; **yuvarlanmaz, reddedilir**; binlik ayırıcı yok; `min` / `max` lira |
+| `date` | `YYYY-AA-GG` | aynı | gerçek takvim günü |
+| `datetime` | UTC ISO (`...Z`) | aynı | gönderilirken saat dilimi zorunlu (`+03:00` ya da `Z`) |
+| `boolean` | 0/1 | `true`/`false` | |
+| `choice` | `value` kodu (kısıtsız; seçenek denetimi kayıt işlemlerinde) | kod | kod `^[a-z0-9][a-z0-9_-]{0,39}$`; görünen ad `title`; yeni değer migration'sız eklenir |
+| `person` | kullanıcı kimliği (`sub`) | aynı | |
+| `file` | dosya anahtarı (`OneFiles`) | aynı | |
+
+Her alan: `required`, `unique` (silinmemiş kayıtlar arasında), `index`, `default`. Ad kuralı `^[a-z][a-z0-9_]{0,39}$`
+(çift alt çizgi, sondaki alt çizgi, `_minor` / `_fold` ekleri ve `order`, `group`, `not` gibi SQL anahtar sözcükleri
+reddedilir); otomatik kolonlar `id` (uuid), `created_at`, `created_by`, `updated_at`, `updated_by`, `deleted_at` alan
+adı olamaz. En çok 30 varlık, varlık başına 60 alan ve tabloda en çok 100 kolon (her metin alanının bir arama kolonu
+`<alan>_fold` vardır, aşağıya bakın). `softDelete` varsayılan `true`.
+
+**`one data generate`** şunları üretir: `migrations/NNNN_one_data.sql` (bir sonraki numara) + `src/data/types.ts` (`<Varlık>Record`,
+`<Varlık>Input`, `dataModel`) + `migrations/.one-data-snapshot.json` (bir sonraki farkın tabanı; elle düzenlenmez).
+`--check` hiçbir şey yazmaz, dosyalar güncel değilse 1 ile çıkar. **Yalnız ekleyen** değişiklik üretilir: yeni varlık,
+yeni alan (zorunluysa `default` şart), yeni dizin. Seçim alanına **yeni değer eklemek** migration gerektirmez (yalnız
+tipler ve anlık görüntü yenilenir); seçim değeri **kaldırmak** reddedilir (var olan kayıtlar o değeri taşıyabilir).
+Alan/varlık silme, ad değiştirme, tür değiştirme, zorunluluk değişikliği, tekillik değişikliği ve dizin kaldırma
+algılanırsa komut hiçbir dosya yazmadan nedenini söyleyip durur (görünen adlar serbesttir). Üretilmiş migration
+uygulandıktan sonra değiştirilmez. ⚠️ Bu kurallardan önceki bir SDK ile kurulmuş tablolarda seçim değerleri veritabanında
+sabitlenmiştir (anlık görüntüde `choiceChecks`); o alanlara değer eklemek yine reddedilir. Eski anlık görüntüyle ilk
+üretim metin alanlarına arama kolonlarını ekleyen yeni bir migration yazar.
+
+```ts
+import { createCrudHandler, problemResponse, readContext } from '@devoplus/one-sdk'
+import { dataModel } from './data/types.ts'
+
+const talepler = createCrudHandler({ model: dataModel, entity: 'talepler', records: 'shared', canWrite: 'One.Talep.Write' })
+// fetch içinde:  const res = await talepler.handle(request, env.DB); if (res) return res
+```
+
+| Yöntem | Yol | İş |
+|---|---|---|
+| GET | `/api/<varlık>` | `{ items, page, pageSize, total }` döner; parametreler `_page`, `_size` (≤ 200), `_sort=alan` / `-alan`, `alan=değer`, `alan.contains=metin` (metin alanları), `alan.from` / `alan.to` (sayı, para, tarih; dahil); en çok 20 süzgeç |
+| POST | `/api/<varlık>` | 201 + kayıt |
+| GET | `/api/<varlık>/<id>` | kayıt |
+| PATCH | `/api/<varlık>/<id>` | gönderilen alanlar |
+| DELETE | `/api/<varlık>/<id>` | 204 (yumuşak silme) |
+| GET | `/api/<varlık>/export.csv`, `export.xlsx`, `report.html` | aynı süzgeçlerle dışa aktarma / yazdırma sayfası (`_lang=tr|en`) |
+
+**Hazır liste bileşeniyle doğrudan bağlanır** (`<one-table src="/api/<varlık>" paging="page" export="xlsx csv">`): uçlar
+bileşenin sorgu lehçesini de kabul eder: `limit` (= `_size`), `page` (= `_page`), `cursor` (sayfa numarası; yanıttaki
+`nextCursor`, son sayfada `null`), `sort` + `order=asc|desc` (= `_sort`), `q` (metin alanlarının **herhangi birinde**
+içerir), `<alan>From` / `<alan>To` (= `.from` / `.to`; `<one-filter>` tarih aralığının varsayılan adları), `lang`
+(= `_lang`), `format=xlsx|csv` (listeyle aynı adreste dışa aktarma). Lehçe adı modeldeki bir alanın adıysa (ör. alan
+`page`) o parametre alan süzgecidir.
+
+Seçenekler: `records` (**zorunlu**: `shared` ile herkes görür, `own` ile herkes yalnız kendi oluşturduğunu), `canRead` /
+`canWrite` (uygulama izni kodu ya da `(ctx) => boolean`), `actingSessions` (`read` varsayılan; `write` Vekalet / Yerine
+Görüntüle'de yazmayı açar; manifest'te de `actingSessions: "write"` gerekir), `basePath`, `pageSize`, `exportLimit`
+(varsayılan 10.000), `timeZone`. Okuma ve yazma oturum ister. Gövde yalnız `application/json`, ≤ 1 MB; sistem alanı
+gönderilemez (`created_by` oturumdan yazılır). Hata gövdesi RFC 9457 + `errors: [{ field, message }]` (Türkçe,
+kullanıcıya gösterilebilir). Değerler SQL'e her zaman bağlı parametre olarak gider; sıralama ve süzgeç adları yalnız
+modelden seçilir.
+
+**Arama Türkçe katlanmıştır:** `alan.contains` ve `q` büyük/küçük harfe ve Türkçe harflere duyarsızdır ("istanbul"
+"İSTANBUL"u, "cay" "Çay"ı bulur; İ ı I i aynı sayılır). Her metin alanının yanında `<alan>_fold` arama kolonu durur;
+`createCrudHandler` onu yazar, API yanıtında görünmez. Kolonu boş olan kayıt (eski kayıt ya da elle yazılmış SQL) da
+bulunur. ⚠️ Bir metin alanını **elle yazdığınız SQL ile güncelliyorsanız** arama kolonunu da yazın
+(`"<alan>_fold" = ?` + `foldSearchText(değer)`) ya da `NULL` yapın; yoksa arama eski metne göre bulur.
+
+## Rapor ve dışa aktarma (D-85; ⚠️ geliştirici onayı bekliyor)
+
+`toCsv(rows, columns, { lang, delimiter, timeZone })`; `toXlsx(rows, columns, { lang, sheetName, timeZone })`;
+`exportResponse(içerik, { fileName, format: 'csv' | 'xlsx' | 'html' })`; `renderPrintableReport({ title, subtitle,
+columns, rows, totals, lang })`. Sütun: `{ key, title: { tr, en }, type?: 'text' | 'number' | 'money' | 'date' |
+'datetime' | 'boolean', labels?, width? }`.
+
+- **CSV:** UTF-8 + BOM (Excel Türkçe karakteri bozmasın), Türkçede `;` ayırıcı ve `1.234,50` sayı (Türkçe bölge ayarlı
+  Excel'in liste ayırıcısı `;`'dir), İngilizcede `,`. `=`, `+`, `-`, `@` ile başlayan metin hücresine `'` eklenir
+  (formül enjeksiyonu).
+- **XLSX:** bağımlılıksız; sayı/para/tarih hücreleri sayı olarak yazılır ve biçim alır (Excel'de toplanabilir), metin
+  hücresi formül olarak çalışmaz; ilk satır sabitlenir. En çok 50.000 satır, 100 sütun.
+- **İndirme:** arayüz dosyayı belirteçli istekle alır ve `one.download({ name, mime, data })` ile Portal'a verir (en çok
+  25 MB). Dosya adı `Content-Disposition`'dadır (`filename*`, Türkçe karakterli; `downloadFileName(header)`).
+- **PDF:** ayrı motor yok. `renderPrintableReport` betiksiz bir yazdırma sayfası üretir; arayüz onu gizli bir
+  çerçevede açıp `print()` çağırır, kullanıcı "PDF olarak kaydet"i seçer.
+
+## Hata kodları
+
+| Kod | Durum | Anlam |
+|---|---|---|
+| `ONE-SDK-E-001` | 500 | Platform bağlamı eksik (dispatch dışından çağrı) |
+| `ONE-SDK-E-002` | 401 | Oturum gerekli |
+| `ONE-SDK-E-003` | 403 | Scope yok (onaya bağlı scope'ta kullanıcı henüz izin vermemiş olabilir, D-59) |
+| `ONE-SDK-E-004` | 403 | Uygulama izni yok (`requirePermission`, D-49) |
+| `ONE-SDK-E-010...013` | 400 | Dosya anahtarı / adı geçersiz |
+| `ONE-SDK-E-014` | 413 | Dosya boyut tavanı (`put` ve `readBoundedBody`) |
+| `ONE-SDK-E-015` | 500 | Dosya yazılamadı |
+| `ONE-SDK-E-016` | 400 | `Content-Length` başlığı geçersiz |
+| `ONE-SDK-E-020...021` | 400 | Önbellek anahtarı geçersiz |
+| `ONE-SDK-E-022` | 400 | Önbellek TTL sınır dışı ya da eksik |
+| `ONE-SDK-E-023` | 400 | Önbellek değeri JSON'a çevrilemiyor |
+| `ONE-SDK-E-024` | 413 | Önbellek değeri 1 MiB tavanı |
+| `ONE-SDK-E-040` | 400 | DEXA sorgu anahtarı geçersiz |
+| `ONE-SDK-E-041` | 400 | DEXA parametre kümesi nesne değil ya da 32'den fazla |
+| `ONE-SDK-E-042` | 400 | DEXA parametre adı geçersiz |
+| `ONE-SDK-E-043` | 400 | DEXA `LangCode` gönderilemez; platformun bağlam parametresidir (harf duyarsız) |
+| `ONE-SDK-E-044` | 400 | DEXA parametre değeri metin değil ya da 2.000 karakteri aşıyor |
+| `ONE-SDK-E-045` | 400 | DEXA işlem anahtarı geçersiz |
+| `ONE-SDK-E-046` | 400 | DEXA işlem parametre kümesi nesne değil ya da 32'den fazla |
+| `ONE-SDK-E-047` | 400 | DEXA işlem parametre adı geçersiz |
+| `ONE-SDK-E-048` | 400 | DEXA işlem parametre değeri metin değil ya da 65.536 karakteri aşıyor |
+| `ONE-SDK-E-049` | 400 | `Idempotency-Key` kanonik UUID değil ya da boş UUID |
+| `ONE-SDK-E-050` | 400 | Org kimliği 24 karakterlik onaltılık değil (istek gönderilmez) |
+| `ONE-SDK-E-051` | 400 | `orgUsersMatching` ölçütsüz çağrıldı |
+| `ONE-SDK-E-060` | 400 | Bildirim senaryosu alanı boş / tanınmayan sonuç / geçersiz doğrulama kodu ya da süresi |
+| `ONE-SDK-E-061` | 400 | Bildirim bağlantısı https değil ya da kimlik bilgisi taşıyor |
+| `ONE-SDK-E-062` | 400 | Bildirim metni backend sınırını aşıyor |
+| `ONE-SDK-E-063` | 400 | Alıcı ya da kanal verilmedi |
+| `ONE-SDK-E-070` | 400 | İş / kuyruk adı geçersiz |
+| `ONE-SDK-E-071` | 400 | Kuyruk iletisi gövdesi JSON'a çevrilemiyor |
+| `ONE-SDK-E-072` | 413 | Kuyruk iletisi gövdesi 64 KiB tavanı |
+| `ONE-SDK-E-073` | 400 | `delaySeconds` 0-86.400 tam sayı değil |
+| `ONE-SDK-E-074` | 503 | İleti kuyruğa bırakılamadı (ağ hatası ya da beklenmeyen yanıt) |
+| `ONE-SDK-E-075` | 404 | İş bulunamadı (`handleJobRequest`: bilinmeyen tür/ad ya da platform dışı çağrı) |
+| `ONE-SDK-E-076` | 400 | İş çağrısının gövdesi JSON değil |
+| `ONE-SDK-E-080...085` | 400 / 413 | Yapay zeka isteği geçersiz (iş, metin, talimat/dil, etiketler, şema, sohbet) |
+| `ONE-SDK-E-086` | 502 | Yapay zeka yanıtı tanınmadı |
+| `ONE-SDK-E-090` | 500 | `defineAgentTools`: araç adı geçersiz ya da işleyici yok |
+| `ONE-SDK-E-091` | 404 | Araç yok / bu yoldan çağrılamaz (beyansız araç, imzasız çağrı, yanlış yöntem) |
+| `ONE-SDK-E-092` | 501 | Araç manifest'te beyanlı ama işleyicisi tanımlanmamış |
+| `ONE-SDK-E-093` | 400 / 413 | Araç girdisi geçerli JSON değil ya da 256 KiB'ı aşıyor |
+| `ONE-SDK-E-094` | 400 | Araç girdisi şemaya uymuyor (`errors` alan listesi) |
+| `ONE-SDK-E-095` | 403 | Değiştiren araç Vekalet / Yerine Görüntüle oturumunda çağrılamaz |
+| `ONE-SDK-E-096` | 500 | Ajan rehberi 256 KiB'ı aşıyor |
+| `ONE-SDK-E-100` | 500 | Veri modeli ya da `createCrudHandler` yapılandırması geçersiz (`one data generate` ile düzeltin) |
+| `ONE-SDK-E-101` | 400 | Kayıt doğrulanamadı (`errors: [{ field, message }]`) |
+| `ONE-SDK-E-102` | 404 | Kayıt bulunamadı (silinmiş ya da başkasının, `records: 'own'`) |
+| `ONE-SDK-E-103` | 409 | Tekil alan değeri başka bir kayıtta kullanılıyor |
+| `ONE-SDK-E-104` | 400 | Liste sorgu parametresi geçersiz (bilinmeyen alan, uygunsuz süzgeç, sayfa boyu) |
+| `ONE-SDK-E-105` | 405 | Bu adreste bu yöntem kullanılamaz |
+| `ONE-SDK-E-106` | 403 | Vekalet / Yerine Görüntüle oturumunda kayıt değiştirilemez |
+| `ONE-SDK-E-107` | 403 | `canRead` / `canWrite` izni yok |
+| `ONE-SDK-E-108` | 413 | Kayıt gövdesi 1 MB'ı aşıyor |
+| `ONE-SDK-E-109` | 415 | Kayıt gövdesi `application/json` değil |
+| `ONE-SDK-E-110` | 400 | Dışa aktarılacak kayıt sayısı sınırı aşıyor (süzgeci daraltın) |
+| `ONE-SDK-E-120` | 400 | Dışa aktarma sütunu / saat dilimi / toplam sütunu geçersiz |
+| `ONE-SDK-E-121` | 400 | Dışa aktarma satır sınırı (50.000) ya da 25 MB indirme sınırı aşıldı |
+| `ONE-SDK-E-130` | 400 | Kişi araması 2-100 karakter olmalı (`peopleSearchHandler`) |
+| `ONE-SDK-E-131` | 405 | Kişi araması yalnız `GET` |
+| `ONE-SDK-E-140` | 400 | DEXA bağlam kodu (`UserCode`, `CompanyCode`, `CostCenterCode`) boş ya da yalnız boşluk (istek gönderilmez) |
+| `ONE-SDK-E-999` | 500 | Beklenmeyen hata (`problemResponse`) |
+
+Backend'den dönen kodlar (`ONE-APP-E-*`, `USRDIR-*` vb.) `OneError.code` ile olduğu gibi taşınır.
+
+## Sürümleme
+
+SemVer; `0.x` boyunca küçük sürüm artışı kırıcı olabilir; `CHANGELOG.md` **Kırıcı** başlığına bakın. Paket iki
+kanaldan otomatik yayımlanır (`Publish SDK (npm)` iş akışı, D-60 ve D-94):
+
+| Kanal | Ne zaman | Sürüm | npm etiketi |
+|---|---|---|---|
+| Ön sürüm | Platform deposunun `test` dalına birleşmede | `<package.json sürümü>-next.<n>` (ör. `0.2.0-next.512`) | `next` |
+| Kararlı | `main` dalına birleşmede | `package.json` sürümü | `latest` |
+
+Sürüm npm'de zaten varsa hiçbir şey yapılmaz; etiketi geriye çekecek sürüm (npm'dekilerden düşük) reddedilir. Sürüm
+SemVer 2.0'dır; derleme üstverisi (`+...`) karşılaştırmada sayılmaz. Yayımlanan her zaman dalın ucundaki sürümdür. Ön sürüm
+numarası `n` dalın ucundaki commit sayısıdır, dolayısıyla her yeni ön sürüm bir öncekinden büyüktür. Bir sürüm kararlı
+olarak çıktıktan sonra `test`'teki `package.json` sürümü yükseltilir; aksi halde ön sürüm kanalı durur.
+
+⚠️ `^0.2.0` aralığı ön sürümleri KAPSAMAZ (SemVer kuralı). Ön sürüm de kurulsun isteniyorsa aralık `^0.2.0-next.0`
+yazılır: bu aralık `0.2.0-next.*` ve `0.2.x` kararlı sürümlerini kapsar, `0.3.0`'ı kapsamaz.