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

Bu sayfa, ne yapılacağı netleştikten ve planı onayladıktan sonraki adımları anlatır (yapay zeka aracınız sizinle nasıl çalışır). Adımlar sırayla ilerler; yöneticinin onayını bekleyen bir adım varken geliştirme sürebilir. Adımların çoğunu yapay zeka aracınız sizin adınıza yapar; burada her adımın ne olduğunu ve size düşen kısmı bulursunuz.

1. Uygulama kaydı

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

Kısa ad kayıtlı değilse kayıt talebi gönderilir: Türkçe ad zorunlu, İngilizce ad isteğe bağlıdır. Talebi portalınızın şirket yöneticisi onaylar. Uygulamanın içinde rol gerekiyorsa (ör. yalnız onaylayanlar) bu izinler aynı talepte istenir; 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 ve diğer bütün talepleri yalnız sahip gönderebilir.

Talebi yapay zeka aracınız gönderebilir; komut satırından one request registration --title "<ad>" ile siz de gönderebilirsiniz (erişim talebi).

2. Proje dosyaları

Uygulamanın iskeleti iskelet üreticiyle üretilir: npm create devoplus-one-app -- <dizin> --slug <kısa ad> --owner <sahibin e-postası>. Komutu yapay zeka aracınız da çalıştırabilir. İlk tercih hazır şablondur (bakim-takvimi, saha-denetimi, egitim-sertifika, ziyaretci-kaydi, uygunsuzluk-dof, musteri-ziyaret, hedef-takibi, envanter): ihtiyaç bir şablona benziyorsa ondan üretilir ve değiştirilir (hazır şablonlar). Hiçbiri uymuyorsa boş iskelet üretilir. Boş iskeletin dosyaları:

Şablondan üretilen uygulamada bunlara ek olarak one.data.json (veri modeli), src/app.ts (uçlar), şablonun 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.

Üretici seçenekleri: --template <şablon>, --slug, --owner <sahibin e-postası> (zorunlu), --name ve --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). ⛔ Adı benzeyen ama Devoplus'a ait olmayan paketler vardır; yalnız create-devoplus-one-app'i kullanın.

3. Yerelde çalıştırma

SDK (@devoplus/one-sdk) genel paket deposundadır; kararlı sürüm latest, test kanalındaki ön sürüm next etiketindedir. İskelet üretici SDK'nın güncel sürümünü paket deposundan okur, package.json'a tam sürümü ve one.manifest.json'a sdkVersion'ı yazar; depoya ulaşamazsa bunu söyler ve kurulumdan sonra npx one upgrade çalıştırmanızı ister. İskeletten gelmeyen bir projeye eklemek için pnpm add @devoplus/one-sdk@latest, ardından npx one upgrade.

SDK'yı güncel tutun. one komutu, kurulu SDK kanalındaki en yeni sürümden eskiyse her komutta "Devoplus One SDK'nın daha yeni bir sürümü var" uyarısını ve güncelleme komutunu yazar; komut yine çalışır. Var olan bir uygulamada çalışmaya başlamadan önce kurulu sürüme (pnpm list @devoplus/one-sdk) ve en yeni sürüme (npm view @devoplus/one-sdk dist-tags) bakın. Güncellemek için 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). Denetimin ne zaman ağa çıktığı ve nasıl kapatıldığı SDK başvurusundaki "Güncelleme uyarısı" bölümündedir.

Platformun uygulamalardan beklediği kurallar AGENTS.md'nin sonundaki "Platform kuralları" bölümündedir; bölümü npx one agents sync yazar, elle düzenlenmez. Uygulamanın bu kurallara uyup uymadığını npx one doctor gösterir (zorunlu bulguda çıkış kodu 1); ayrıntı Yayın sayfasında.

pnpm install
pnpm migrate   # one migrate: migrations/ dosyalarını 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: tarayıcıda http://127.0.0.1:8787/ adresini açtığınızda uygulama Portal'daki gibi bir çerçevede görünür; menü sekmeleri, bildirim, onay penceresi, tema ve dil Portal'daki gibi çalışır. Kimlik başlıklarını elle yazmanız gerekmez: oturumu açan kişiyi --as <kişi> ile ya da sayfadaki listeden seçersiniz ve uygulama, platformda göreceği kimlik bağlamının aynısını alır (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 açılmış oturumda yazma platformdaki gibi reddedilir.

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

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:

{
  "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" } }
  }
}

Bütün alanlar SDK başvurusundadır. DEXA örnek verisine portalda gerçekten açılmış anahtarları ve parametreleri yazın (one dexa queries listesi). 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). "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.

4. Geliştirme

• Kod SDK başvurusuna ve uygulama kurallarına göre yazılır. Uç adı, alan adı ve sorgu anahtarı uydurulmaz: belgede yoksa yöneticiden yeni sorgu talebi açılır.
• 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 arayüz bileşenleri kullanılır.
• Kullanıcıya görünen her metin Türkçe ve İngilizce yazılır, resmi "siz" diliyle.
• Gereken her yetki alanı manifest scopes içine yazılır; yetki alanı kayıtlı değilse yetki alanı talebi açılır.
• Zorunlu adım: uygulamanın verisi ve işlemleri Devoplus yapay zekasına araçlarla açılır ve AGENT_GUIDE.md yazılır; her yeni özellikte üçü (manifest agent.tools, src/agent.ts, rehber) birlikte güncellenir (yapay zeka). Araç beyan edip rehberi olmayan uygulama yayına giremez.

5. Yayın ve kurulum

1. Kod one publish ile Devoplus'a yüklenir (yapay zeka aracınız da yükleyebilir); GitLab'a girmeniz gerekmez (yayın).
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 bir önizlemedir. Hat durursa one pipeline nedenini gösterir. Test'ten uat'a terfi one promote ile, canlıya terfiyi uygulamanın sahibi Portal'daki Devoplus One Uygulamalarım ekranından, şirket yöneticisi Devoplus Console'dan yapar.
3. Uygulamanın portalınızda görünmesi için kurulum talebi gönderilir. Portal anahtarını sunucu portalın adından belirler; elle seçilmez. Portalın adını ve var olan anahtarını one context gösterir.
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 bir rolün bir kullanıcı grubuna atanması için izin ataması talebi açılır; kod uygulamanın kaydında tanımlı olmalıdır (kayıt talebinde istenmemiş izin için talep reddedilir).
5. Uygulamayı Portal'da açıp deneyin; geri bildiriminize göre yeni bir tur yapılır.
6. Bir sorun çıktığında önce kullanım ve hata panosuna bakın.