# Başlangıç: kayıttan ilk sürüme

Bu sayfa, [keşif görüşmesi](/docs/discovery.md) bittikten ve kullanıcı planı onayladıktan sonraki adımları anlatır.
Adımlar sırayla yapılır; yöneticinin onayını bekleyen bir adım varken geliştirmeye devam edebilirsiniz.

## 1. Uygulama kaydı

Her uygulamanın bir **kısa adı** vardır (manifest `app.slug`): küçük harf/rakam, parçalar tek tireyle ayrılır, harfle
başlar, en çok 24 karakter (ör. `izin-talepleri`). Kısa adı kullanıcıyla birlikte, uygulamanın Türkçe adından seçin.

Kısa ad kayıtlı değilse **kayıt** isteyin (`registration`, Türkçe ad zorunlu, İngilizce ad isteğe bağlı); talebi
portalın şirket yöneticisi onaylar. Uygulamanın içinde rol gerekiyorsa izinleri (`additionalPermissions`) **aynı
talepte** isteyin: kayıttan sonra izni ancak ana portalın şirket yöneticisi Devoplus Console'dan ekleyebilir (ana portalı belirlenemeyen uygulamada platform yöneticisi). Kayıt onaylanınca talebi gönderen kişi
uygulamanın **sahibi** olur; diğer bütün talepleri yalnız sahip gönderebilir. Talebi MCP aracı `one_request_access`
ya da `one request registration --title "<ad>"` ile gönderin ([erişim talebi](/docs/access-requests.md)).

## 2. Proje dosyaları

Uygulamanın iskeleti iskelet üreticiyle üretilir: `npm create devoplus-one-app -- <dizin> --slug <kısa-ad> --owner <e-posta>`. **İlk tercih hazır şablondur** (`--template bakim-takvimi`,
`saha-denetimi`, `egitim-sertifika`, `ziyaretci-kaydi`, `uygunsuzluk-dof`, `musteri-ziyaret`, `hedef-takibi`, `envanter`): ihtiyaç bir şablona benziyorsa ondan üretin ve kullanıcının
isteğine göre değiştirin ([hazır şablonlar](/docs/templates.md)). Hiçbiri uymuyorsa boş iskelet üretilir
(`--template` verilmez). Boş iskeletin dosyaları:

| Dosya | Ne işe yarar |
|---|---|
| `one.manifest.json` | Uygulamanın beyanı: ad, sürüm, servisler, yetki alanları, menü, izinler ([manifest](/docs/manifest.md)) |
| `package.json` | Bağımlılıklar ve `one dev`, `one migrate` ve `one build` komutları |
| `src/index.ts` | Sunucu tarafı: istekleri karşılar, SDK ile servislere bağlanır |
| `src/shell.ts` | Sayfa: Portal köprüsü, açık/koyu tema, Türkçe/İngilizce |
| `migrations/0001_init.sql` | Veritabanı tabloları; şema yalnız yeni numaralı dosyayla ilerler |
| `AGENTS.md` | Bu uygulamayı yazan yapay zeka için bağlayıcı kurallar ([uygulama kuralları](/docs/app-rules.md)) |
| `src/agent.ts`, `AGENT_GUIDE.md` | Devoplus yapay zekasının çağırabileceği araçlar ve onları nasıl kullanacağını anlatan rehber ([yapay zeka](/docs/ai.md)) |
| `README.md` | Uygulamanın kısa tanıtımı |

Şablondan üretilen uygulamada bunlara ek olarak `one.data.json` (veri modeli), `src/app.ts` (uçlar), şablonun saf
kural dosyası ve testi, `src/lib/` (şablonların ortak parçaları) ve gerekiyorsa `src/jobs.ts` (zamanlanmış iş) bulunur;
tablolar `migrations/` altındaki üretilmiş dosyadadır.

Seçenekler: `--template <şablon>`, `--slug`, `--owner <sahibin e-postası>` (zorunlu, uydurulmaz; kullanıcıya sorun),
`--name` / `--name-en`, `--services database,files,cache`, `--scopes <liste>`. İskelet üretici
(`create-devoplus-one-app`) kararlı kanaldan (`latest`) çalıştırılır; `@next` yalnız test kanalı içindir ([sınırlar](/docs/limits.md)).
⛔ `npx create-one-app` çalıştırmayın: kapsamsız ad npm'de başkasına aittir. SDK
(`@devoplus/one-sdk`) npm'dedir; iskeletin `package.json`'ı onu kendisi kurar (üreticinin kanalı: `latest`).

**Bu dosyaları açtıktan sonra ilk iş `AGENTS.md`'yi okuyun**; kurallar bağlayıcıdır.

**Var olan bir uygulamada çalışmaya başlamadan önce SDK sürümünü denetleyin.** Kurulu sürümü `pnpm list
@devoplus/one-sdk`, kanaldaki en yeni sürümü `npm view @devoplus/one-sdk dist-tags` gösterir (ön sürüm kuruluysa `next`
etiketine bakın). `one` komutu da kurulu SDK eskiyse hata akışına "Devoplus One SDK'nın daha yeni bir sürümü var"
uyarısını ve güncelleme komutunu yazar; komut durmaz. Uyarıyı görürseniz başka bir işe geçmeden SDK'yı güncelleyin
(`pnpm add @devoplus/one-sdk@latest` (kurulu SDK ön sürümse `@next`), ardından `npx one upgrade` (sürümü tam sabitler, `one.manifest.json` `sdkVersion` alanını ve `AGENTS.md`'nin platform kuralları bölümünü yazar)), testleri ve `pnpm build`'i çalıştırın, `package.json`,
`pnpm-lock.yaml`, `one.manifest.json`, `one.platform-state.json` ve `AGENTS.md`'yi kodla birlikte yükleyin. Kullanıcıya yalnız sonucu söyleyin ("Devoplus bileşenini güncel sürüme yükselttim").

**Platform kuralları `AGENTS.md`'nin sonundadır.** "Platform kuralları" bölümü yeni uygulamada iskelet üretici yazar, sonra `npx one agents sync` yeniler (`npx one upgrade` bu komutu kendisi çalıştırır); her kuralın kimliği, düzeyi ve düzeltmesi oradadır. Bölümü elle düzenlemeyin, bir sonraki eşitlemede yeniden yazılır; uygulamaya özgü notları bölümün dışına yazın. Commit'ten önce `npx one doctor` çalıştırın: uygulamayı bu kurallara karşı tarar, zorunlu bulguda çıkış kodu 1'dir. SDK'yı yükselttikten sonra `one_platform_updates` aracıyla neyin değiştiğini okuyun; adımlar [Yayın](/docs/publishing.md) belgesindeki "Güncelleme döngüsü"ndedir.

## 3. Yerelde çalıştırma

```bash
pnpm install
pnpm migrate   # one migrate: migrations/'ı yerel veritabanına uygular (ilk çalıştırmada ve her yeni dosyada)
pnpm dev       # one dev: uygulamayı yerel Portal içinde açar (--as <kişi>, --port, --api-base)
pnpm test      # testler
pnpm build     # one build: yükleme provası; hiçbir yere göndermez
```

`one dev` uygulamayı **yerel Portal** içinde açar: `http://127.0.0.1:8787/` adresindeki sayfa uygulamayı Portal gibi
iframe'de gösterir; menü sekmeleri, bildirim, onay penceresi, tema ve dil Portal'daki gibi çalışır. Kimlik başlıklarını
elle yazmazsınız: oturumu açan kişi `--as <kişi>` ile ya da sayfadaki listeden seçilir ve platformun ürettiği kimlik
bağlamı aynen üretilir (izinler, yönetici, Vekalet ve Yerine Görüntüle oturumu dahil). Uygulamanın kendi adresi bir
sonraki porttadır (`http://127.0.0.1:8788/`); orada da belirteçsiz yazma, `/__one/` yolu ve başkası adına oturumda
yazma platformdaki gibi reddedilir.

Devoplus servisleri yerelde **taklit edilir**; hiçbir şey gerçekten gönderilmez ve ERP'ye yazılmaz:

| Servis | Yerelde |
|---|---|
| E-posta, SMS, mobil bildirim | Yerel posta kutusuna yazılır (`http://127.0.0.1:8787/__one-dev/posta-kutusu`, dosya `.one/mailbox/`) ve konsola bir satır düşer. Mobil bildirim varsayılan olarak kapalıdır (`ONE-APP-E-029`, aşağıda). Alıcı kuralları, boyut sınırları ve hata kodları platformla aynıdır |
| DEXA sorgu ve işlemi | `one.dev.json` içindeki örnek yanıttan gelir. Tanımlı olmayan anahtar platformdaki gibi reddedilir: sorgu `ONE-APP-E-024`, işlem `ONE-APP-E-030` |
| Organizasyon şeması ve onay zinciri | `one.dev.json` kişilerinden (unvan, departman, yönetici, kullanıcı grubu) |
| Devoplus yapay zekası | Yerelde yoktur; `ONE-APP-E-050` döner |

Kişiler ve örnek veri uygulamanın kökündeki `one.dev.json` dosyasındadır. Dosya yoksa iki örnek kişiyle (`gelistirici`
ve yöneticisi `mudur`) açılır. Dosya sır taşımaz, depoya eklenebilir:

```json
{
  "defaultPerson": "ayse",
  "people": {
    "ayse": { "name": "Ayşe Yılmaz", "email": "ayse@ornek.test", "phone": "+905550000010", "title": "Uzman", "department": "Satış", "manager": "mehmet" },
    "mehmet": { "name": "Mehmet Demir", "email": "mehmet@ornek.test", "title": "Müdür", "permissions": ["One.IzinTalepleri.Approve"] }
  },
  "groups": { "onay": { "name": "Satış Onay", "members": ["ayse", "mehmet"] } },
  "dexa": {
    "queries": { "IMS.Siparisler": { "parameters": ["Yil"], "rows": [{ "No": "1", "Tutar": 10 }] } },
    "commands": { "OMS.SiparisYaz": { "outcome": "succeeded" } }
  }
}
```

Kişi alanlarının tamamı [SDK başvurusundadır](/docs/sdk.md). DEXA anahtarlarını uydurmayın: örnek veriye yalnız
`one_dexa_queries` listesindeki (ya da kullanıcıyla kararlaştırılan) anahtarları ve parametreleri yazın. E-posta, SMS ya
da bildirim gönderen bir özelliği denedikten sonra posta kutusuna bakın. Mobil bildirim yerelde de platformun varsayılanı
gibi kapalıdır (`ONE-APP-E-029`); açık kanalı denemek için `"channels": { "push": "open" }` yazın, ileti posta kutusuna
düşer. SMS yerelde posta kutusuna yazılır; platformda uç iletiyi kuyruğa alır, gerçekten gönderilip gönderilmediği
ortamın ayarına bağlıdır ([sınırlar](/docs/limits.md)). `"channels": { "sms": "closed" }` SMS sağlayıcısı tanımlı
olmayan portalın yanıtını (`ONE-APP-E-021`) verir.

Komut satırından denemek için oturum belirtecini yerel Portal'dan alın
(`http://127.0.0.1:8787/__one-dev/session?as=ayse` yanıtındaki `token`) ve uygulamaya `Authorization: Bearer <token>`
ile gönderin. `--api-base` verilirse servis taklidi kapanır; yerel belirteç gerçek Devoplus servislerinde geçmez. Arka
plan işinin Devoplus servis çağrıları yerelde taklit edilmez.

Kullanıcıya terminal komutu yazdırmayın; komutları siz çalıştırın ve sonucu sade dille anlatın.

## 4. Geliştirme

- Kodu [SDK başvurusu](/docs/sdk.md) ve [uygulama kuralları](/docs/app-rules.md)'na göre yazın. Uç adı, alan adı,
  sorgu anahtarı **uydurulmaz**: DEXA sorgusunu `one_dexa_queries` listesinden alın; belgede ya da listede yoksa
  kullanıcıya iş diliyle sorun ya da `new-query` talebi açın.
- Arayüz Devoplus görsel dilindedir: `/one-ui.css`, Portal köprüsü `window.one`, menü yerine `navigation` sekmeleri,
  bildirim ve onay pencereleri Portal'da (`one.toast`, `one.confirm`).
- Liste, form, süzgeç, kişi seçici, dosya yükleme ve grafik için hazır bileşenleri kullanın
  ([Arayüz bileşenleri](/docs/ui-components.md)); elle tablo ya da form yazmayın.
- Her kullanıcıya görünen metin Türkçe + İngilizce ve resmi "siz".
- İhtiyaç duyduğunuz her yetki alanını manifest `scopes` içine yazın; yetki alanı kayıtlı değilse `scope` talebi açın.
- **Zorunlu adım:** uygulamanın verisini ve işlemlerini Devoplus yapay zekasına araçlarla açın ve `AGENT_GUIDE.md`'yi
  yazın; her yeni özellikte üçünü (manifest `agent.tools`, `src/agent.ts`, rehber) birlikte güncelleyin
  ([yapay zeka](/docs/ai.md)). Araç beyan edip rehberi unutan uygulama yayına giremez.

## 5. Yayın ve kurulum

1. Kodu Devoplus API'si üzerinden yükleyin: komut satırında uygulamanın kök dizininde `one publish`, dosya sisteminiz
   yoksa `one_source_upload`. GitLab'a erişmeniz gerekmez ve kullanıcıdan da istemezsiniz ([yayın](/docs/publishing.md)).
2. Yükleme test ortamına yayını da başlatır; hat kapılardan geçince uygulama test ortamına dağıtılır ve adres
   paylaşılabilir önizlemedir. Hat düşerse nedenini `one_pipeline_status` gösterir. Test'ten uat'a terfi `one_publish`
   ile yapılır; canlıya terfiyi uygulamanın sahibi Portal'daki **Devoplus One Uygulamalarım** ekranından, şirket yöneticisi
   Devoplus Console'dan yapar.
3. Uygulamanın kullanıcının portalında görünmesi için **kurulum** isteyin (`installation`). Portal anahtarını
   sunucu portalın adından belirler; elle seçilmez, kullanıcıya sorulmaz ve uydurulmaz. Portalın adı ve var olan
   anahtarı `one_portal_context` (ya da `one context`) ile okunur.
4. Menü öğesini görmek için kullanıcıların `One.<Uygulama>.Use` iznine ihtiyacı vardır; portal yöneticisi bunu
   Yetki Yönetimi'nden atar. Uygulama içi rolün bir gruba atanması için `app-permission` talebi açın; kod
   uygulamanın kaydında tanımlı olmalıdır (kayıt talebinde istenmemiş izin için talep reddedilir).
5. Kullanıcıya Portal'da nereye bakacağını söyleyin ve denemesini isteyin; geri bildirimine göre yeni bir tur yapın.
6. Kullanıcı bir sorun bildirdiğinde önce [kullanım ve hata panosuna](/docs/health.md) bakın (`one_app_health`).