Yapay Zekâ ile Sayfa Oluşturma Kılavuzu

Bu kılavuz, Dahili İçerik API'si üzerinden WebBlocks CMS sayfaları oluşturan güvenilir yapay zekâ/operatör araçları için güvenli iş akışını tanımlar. Genel CMS ürün rehberidir. CMS çekirdeğine siteye özgü içe aktarma, senkronizasyon veya kazıma davranışı eklemeyin.

Harici yapay zekâ/operatör araçlarının CMS deposuna veya kurulu paket dokümanlarına yerel dosya sistemi erişimine ihtiyacı yoktur. Canlı API keşif uç noktasıyla başlayın:

GET /webadmin/api

Kurulu pakete özgü sitelerde bu kılavuz Composer paketinin içinde şu konumda da gelir:

vendor/fklavyenet/webblocks-cms/docs/ai-page-building-guide.md

Amaç

Güvenilir yapay zekâ/operatör araçları bir CMS kurulumunu inceleyebilir, yapılandırılmış bir taslak içerik planı oluşturabilir, planı doğrulayabilir, ayrı bir taslak sayfa oluşturabilir, açık kullanıcı onayından sonra mevcut bir taslak sayfada belirli sayfaya ait slotları değiştirebilir veya token content.publish yetkisine sahipse açık yayınlama uç noktalarını çağırabilir. Normal sayfa oluşturma iş akışı taslak öncelikli ve API önceliklidir. İçerik uygulama işlemi içerik yayınlamaz, yayındaki sayfaların üzerine yazmaz, ortak slot destekli slotları temizlemez, uzak web sitelerini getirmez veya medya içe aktarmaz.

Token Kurulumu

API token'larını CMS yönetim panelinden oluşturun:

System -> API Tokens

Düz token yalnızca oluşturulduktan hemen sonra bir kez gösterilir. Onu güvenilir bir operatör gizli anahtar deposunda saklayın ve gerçek bir token'ı asla istemlere, dokümantasyona, günlüklere, ekran görüntülerine, destek kayıtlarına veya sürüm raporlarına yapıştırmayın.

Yerel araç yapılandırmasında API keşif temel URL'sini kullanın:

WEBBLOCKS_CMS_API_URL=https://example.com/webadmin/api
WEBBLOCKS_CMS_API_TOKEN=...

Normal sayfa oluşturma araçları için varsayılan sayfa oluşturma yeteneklerini seçili tutun. Gelişmiş yayınlama veya sayfa silme yeteneklerini yalnızca bunlara açıkça ihtiyaç duyan güvenilir operatör araçlarına verin.

API istekleri şunları kullanır:

Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

İlk Keşif Çağrıları

API keşfiyle başlayın. İlk çağrı şudur:

GET /webadmin/api

Geçerli bir token olmadan bu uç nokta yalnızca herkese açık kullanıma uygun asgari başlangıç JSON'ı döndürür. Geçerli bir Bearer token ile OpenAPI şemasına, yapay zekâ kılavuzuna, içerik sözleşmesine, örneklere, doğrulama/uygulama uç noktalarına, sayfalara, gezinmeye ve ortak slotlara bağlantılar döndürür.

Sonrasında döndürülen bağlantıları izleyin. Token korumalı yaygın uç noktalar /webadmin/api altında bulunur:

GET /webadmin/api/openapi.json
GET /webadmin/api/ai-guide
GET /webadmin/api/examples/contact-page
GET /webadmin/api/sites
GET /webadmin/api/locales
GET /webadmin/api/page-layouts
GET /webadmin/api/block-types
GET /webadmin/api/content-contract
GET /webadmin/api/navigation-menus
GET /webadmin/api/shared-slots
GET /webadmin/api/pages

Yeni bir sayfa önermeden önce mevcut slug'ları, canlı yer tutucu sayfaları veya önceki taslakları denetlemeniz gerektiğinde GET /webadmin/api/pages kullanın.

Blok Tanıtıcılarını Asla Tahmin Etmeyin

Yapay zekâ araçları blok tanıtıcılarını (handle) uydurmamalı veya tahmin etmemelidir. Kesin tanıtıcılar, bir plan oluşturmadan önce mevcut kurulum için GET /webadmin/api/block-types veya GET /webadmin/api/content-contract üzerinden öğrenilmelidir.

Yaygın olarak var olan ancak yine de çalışma zamanında doğrulanması gereken tanıtıcı örnekleri:

section
container
grid
card
card_body
hero
cta
plain_text
rich-text
button_link
sticky-navbar

Keşif tam olarak bu tanıtıcıları doğrulamadıkça plain-text, rich_text, button, navbar veya navigation_auto gibi benzer yazımları yerine koymayın.

Güvenli İş Akışı

Salt okunur keşfi çalıştırın.
Canlı API bağlantılarından OpenAPI'yi, içerik sözleşmesini ve örnekleri okuyun.
Yalnızca keşfedilen tanıtıcıları ve geçerli site/yerleşim/dili (locale) kullanarak bir içerik planı oluşturun.
POST /webadmin/api/content/validate ile doğrulayın.
Doğrulama hatalarını okuyun ve planı düzeltin.
Kesinleşmiş nihai planı uygulamak için kullanıcıdan açık onay isteyin.
Yalnızca onaydan sonra POST /webadmin/api/content/apply çağırın.
Uygulama yanıtından oluşturulan taslak sayfa kimliğini okuyun.
/webadmin/pages/{page}/preview ile yönetim önizleme URL'sini üretin.
Kullanıcı bir API yayınlama işlemini açıkça onaylamadıkça ve token content.publish yetkisine sahip olmadıkça yayınlamayı insan iş akışına bırakın.

Güvenlik Kuralları

Taslak öncelikli çalışın.
Yalnızca açık kullanıcı onayından sonra uygulayın.
İçerik uygulama üzerinden yayınlamayın.
Sayfa yayınlamanın tüm blokları herkese açık yaptığını varsaymayın; include_page_owned_blocks: true seçeneğini yalnızca açık onaydan sonra kullanın.
İçerik uygulama üzerinden sayfa silmeyin.
Açık replace_existing_draft_page modu dışında mevcut sayfaların veya blokların üzerine yazmayın.
Hedef yol zaten mevcutsa, kullanıcı API'nin desteklediği bir çakışma yönetimi planını açıkça onaylamadıkça uygulamayı çağırmayın.
Mevcut taslak değişimi için expected_path veya expected_updated_at ekleyin ve yalnızca sayfaya ait slotları değiştirin.
page.path değerini kurallı herkese açık URL olarak kabul edin. /p/contact değil, /contact veya /docs/internal-content-api kullanın; /p/... yalnızca eski bir herkese açık yönlendirmedir.
Ortak slot destekli slotları değiştirmeye çalışmayın; ortak üst bilgi/alt bilgi atamalarını olduğu gibi bırakın.
Uzak sayfaları getirmeyin.
API keşfi kullanılabilirken tarayıcı otomasyonu veya yönetim arayüzü tıklamaları kullanmayın.
Medya indirmeyin veya içe aktarmayın.
Kullanıcı açıkça token yönetimi istemedikçe otomasyondan API token'ı oluşturmayın.
Token değerlerini yazdırmayın, günlüğe kaydetmeyin veya raporlamayın.
Yalnızca durum kodlarını ve güvenli özetlenmiş yanıt verilerini raporlayın.
401, 403 ve 422 JSON yanıtlarını API geri bildirimi olarak değerlendirin ve içerdikleri keşif/dokümantasyon bağlantılarını izleyin.

İyi Yapılar

Tek bir büyük içerik yığını yerine yapılandırılmış blokları tercih edin.

Pazarlama ana sayfası:

section -> container -> hero
section -> container -> grid -> card -> card_body
section -> container -> cta

Üst bilgi/gezinme çubuğu:

shared_slot header
sticky-navbar -> container(flow:none) -> cluster -> navbar-brand + cluster -> navbar-navigation + header-actions

Çoğu herkese açık sayfa için hero ve cta gibi geniş tanıtım bloklarını section -> container içine yerleştirin. main altında doğrudan tam genişlikte hero veya cta blokları, varsayılan değil, bilinçli kenardan kenara tasarım tercihleri olmalıdır.

İletişim sayfası:

section -> hero + contact_form

Keşif, tanıtıcının kullanılabilir olduğunu doğruladıktan sonra iletişim sayfaları için yerel contact_form blokunu kullanın. Görünen metinleri title, content, submit_label ve success_message ile çevrilir; ortak ayarları recipient_email, send_email_notification ve store_submissions alanlarıdır. Renderer; yerel CSRF korumalı herkese açık formu, CMS'e ait gizli, otomatik oluşturulan istenmeyen ileti denetim alanını ve /contact-messages gönderim uç noktasını üretir. Yapay zekâ/operatör araçları denetim alanını elle oluşturmamalı ve yerine Trusted HTML, ham formlar veya mailto: kullanmamalıdır.

Kötü Yapılar

Tam bir sayfayı tek bir rich-text blokuna koymayın.
Yapılandırılmış bloklar temsil edebiliyorken tam bir sayfayı tek bir güvenilir html blokuna koymayın.
contact_form kullanılabilirken iletişim formlarını Trusted HTML, ham form işaretlemesi veya mailto: bağlantılarıyla oluşturmayın.
Tanıtıcıları tahmin etmeyin.
Yayındaki içeriğin üzerine yazmayın.
Yeni ayrı bir taslak sayfa daha güvenliyken mevcut canlı bir sayfayı değiştirmeyin.
Token'ları istemlere veya raporlara yapıştırmayın.

Asgari Taslak Planı Örneği

Bu örnek, keşfin section, container, hero, grid, card, card_body, plain_text, button_link ve cta tanıtıcılarını doğruladığını varsayar.

{
  "plan": {
    "site": "default",
    "locale": "en",
    "layout": "default",
    "page": {
      "title": "Example Homepage Draft",
      "path": "/example-homepage-draft",
      "status": "draft"
    },
    "slots": {
      "main": [
        {
          "type": "section",
          "settings": {
            "spacing": "lg"
          },
          "children": [
            {
              "type": "container",
              "children": [
                {
                  "type": "hero",
                  "translations": {
                    "title": "Build useful pages faster",
                    "subtitle": "A structured CMS workflow for practical content teams.",
                    "content": "Create focused draft pages from reusable blocks, then review them safely before publishing."
                  },
                  "children": [
                    {
                      "type": "button_link",
                      "translations": {
                        "title": "Start building"
                      },
                      "settings": {
                        "url": "/get-started",
                        "variant": "primary"
                      }
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "type": "section",
          "settings": {
            "spacing": "lg"
          },
          "children": [
            {
              "type": "container",
              "children": [
                {
                  "type": "grid",
                  "children": [
                    {
                      "type": "card",
                      "children": [
                        {
                          "type": "card_body",
                          "children": [
                            {
                              "type": "plain_text",
                              "translations": {
                                "content": "Create drafts from structured content plans."
                              }
                            }
                          ]
                        }
                      ]
                    },
                    {
                      "type": "card",
                      "children": [
                        {
                          "type": "card_body",
                          "children": [
                            {
                              "type": "plain_text",
                              "translations": {
                                "content": "Review safely through authenticated admin preview."
                              }
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "type": "section",
          "settings": {
            "spacing": "lg"
          },
          "children": [
            {
              "type": "container",
              "children": [
                {
                  "type": "cta",
                  "translations": {
                    "title": "Ready for review?",
                    "content": "Validate the plan, apply only after approval, then open the admin preview."
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Önce doğrulayın:

POST /webadmin/api/content/validate

Yalnızca açık onaydan sonra uygulayın:

POST /webadmin/api/content/apply

Ardından önizleyin:

/webadmin/pages/{page}/preview

Önizleme URL'si bir tarayıcı/yönetim rotasıdır. Kimliği doğrulanmış bir yönetici tarayıcı oturumu gerektirir ve CMS API Bearer token'ıyla erişilemez. Tarayıcı duman testi bir giriş sayfasına düşerse, yönetici tarayıcı oturumunun eksik olduğunu raporlayın; bunu bir JSON API token hatası olarak değerlendirmeyin.

Mevcut Taslak Slot Değişimi

Bu modu yalnızca kullanıcı yeni bir taslak oluşturmak yerine mevcut bir taslak sayfayı güncellemeyi açıkça istediğinde kullanın. Önce doğrulayın, sonra yalnızca onaydan sonra uygulayın:

{
  "plan": {
    "mode": "replace_existing_draft_page",
    "site": "default",
    "locale": "en",
    "page": {
      "id": 9,
      "expected_path": "/contact",
      "status": "draft"
    },
    "replace_slots": {
      "main": [
        {
          "type": "plain_text",
          "translations": {
            "content": "Updated draft page copy."
          }
        }
      ]
    }
  }
}

Doğrulayın:

POST /webadmin/api/content/validate

Uygulayın:

POST /webadmin/api/content/apply

CMS, eski sayfaya ait blokları yalnızca belirtilen slotlardan kaldırır ve yeni blok ağacını tek bir işlemde (transaction) yazar. Ortak slot destekli slotlar bu mod tarafından reddedilir; bu nedenle ortak üst bilgi/alt bilgi atamaları, ayrı ve desteklenen bir API işlemi onları değiştirmedikçe olduğu gibi kalır.

Açık Yayınlama

Yayınlama, doğrulama/uygulamanın parçası değildir. content.publish yetkili güvenilir operatör araçları şunu çağırabilir:

POST /webadmin/api/pages/{page}/publish
POST /webadmin/api/pages/{page}/publish-page-owned-blocks

POST /webadmin/api/pages/{page}/publish varsayılan olarak şuna ayarlıdır:

{
  "include_page_owned_blocks": false
}

Varsayılan ayarla uç nokta yalnızca sayfa kaydını yayınlar. Taslak veya incelemedeki blokları yayınlamaz. include_page_owned_blocks: true değerini yalnızca kullanıcı, o sayfanın yayınlanmamış tüm sayfaya ait bloklarının da yayınlanmasını açıkça istediğinde ayarlayın. Kademeli yayınlama, sayfaya ait slotlar altındaki iç içe alt blokları kapsar ve ortak slot destekli slotları hariç tutar.

POST /webadmin/api/pages/{page}/publish-page-owned-blocks, sayfa iş akışı durumunu değiştirmeden sayfaya ait taslak veya incelemedeki blokları yayınlar.

Sayfa yayınlama uç noktalarından asla ortak slot kademeli yayınlaması istemeyin. Ortak slot içeriği dahil edilmez ve ayrıca incelenip yayınlanmalıdır.

Gerçek Site Revizyonları

Gerçek siteler için önce mevcut sayfaları ve var olan taslakları inceleyin. Zaten bir taslak varsa, yeni iş önermeden önce onu önizleyin. replace_existing_draft_page modunu yalnızca açık, taslakla sınırlı sayfaya ait slot değişimi için kullanın. Aksi halde, mevcut taslağın veya yayındaki canlı ana sayfanın üzerine yazmak yerine yeni ayrı bir taslak sayfa oluşturun.

QuizTem tarzı ana sayfa revizyonlarında, kullanıcı desteklenen bir güncelleme akışını açıkça onaylamadıkça mevcut taslağı yalnızca referans malzemesi olarak kullanın. Yeni işler için güvenli varsayılan şudur:

Mevcut taslağı önizleyin.
Keşfedilen blok tanıtıcılarıyla daha iyi yapılandırılmış bir plan oluşturun.
Planı doğrulayın.
Uygulama için açık onay isteyin.
Yeni ayrı bir taslak sayfa oluşturun.
İnsan incelemesi için /webadmin/pages/{page}/preview adresini açın.