twenty-sdk package provides defineEntity functions to declare your app’s data model. SDK’nin varlıklarınızı algılayabilmesi için export default defineEntity({...}) kullanmanız gerekir. Bu fonksiyonlar, derleme zamanında yapılandırmanızı doğrular ve IDE otomatik tamamlama ile tür güvenliği sağlar.
Dosya organizasyonu size kalmış.
Varlık algılama AST tabanlıdır — dosyanın nerede bulunduğundan bağımsız olarak SDK
export default defineEntity(...) çağrılarını bulur. Dosyaları türe göre gruplamak (örn. logic-functions/, roles/) bir gereklilik değil, yalnızca bir gelenektir.defineRole
Rol izinlerini ve nesne erişimini yapılandırın
defineRole
Rol izinlerini ve nesne erişimini yapılandırın
Roller, çalışma alanınızdaki nesneler ve eylemler üzerindeki izinleri kapsar.
restricted-company-role.ts
defineApplication
Uygulama meta verilerini yapılandırın (zorunlu, uygulama başına bir adet)
defineApplication
Uygulama meta verilerini yapılandırın (zorunlu, uygulama başına bir adet)
Her uygulamanın, şunları tanımlayan tam olarak bir adet Notlar:
Bu rolün
defineApplication çağrısı olmalıdır:- Kimlik: tanımlayıcılar, görünen ad ve açıklama.
- İzinler: işlevlerinin ve ön bileşenlerinin hangi rolü kullandığı.
- (İsteğe bağlı) Değişkenler: fonksiyonlarınıza ortam değişkenleri olarak sunulan anahtar–değer çiftleri.
- (İsteğe bağlı) Kurulum öncesi / kurulum sonrası fonksiyonlar: kurulumdan önce veya sonra çalışan mantık fonksiyonları.
src/application-config.ts
universalIdentifieralanları, size ait deterministik kimliklerdir. Bunları bir kez oluşturun ve senkronizasyonlar boyunca kararlı tutun.applicationVariables, fonksiyonlarınız ve ön bileşenleriniz için ortam değişkenlerine dönüşür (örn.DEFAULT_RECIPIENT_NAME,process.env.DEFAULT_RECIPIENT_NAMEolarak kullanılabilir).defaultRoleUniversalIdentifier,defineRole()ile tanımlanmış bir role referans vermelidir (yukarıya bakın).- Kurulum öncesi ve kurulum sonrası fonksiyonlar manifest derlemesi sırasında otomatik olarak algılanır — bunlara
defineApplication()içinde referans vermeniz gerekmez.
Pazaryeri meta verileri
Eğer uygulamanızı yayımlamayı planlıyorsanız, bu isteğe bağlı alanlar uygulamanızın pazaryerinde nasıl görüneceğini kontrol eder:| Alan | Açıklama |
|---|---|
author | Yazar veya şirket adı |
category | Pazaryerinde filtreleme için uygulama kategorisi |
logoUrl | Uygulamanızın logosuna giden yol (örn. public/logo.png) |
screenshots | Ekran görüntüsü yollarının dizisi (örn. public/screenshot-1.png) |
aboutDescription | ”Hakkında” sekmesi için daha uzun bir markdown açıklaması. Belirtilmezse, pazaryeri npm’deki paketin README.md dosyasını kullanır |
websiteUrl | Web sitenize bağlantı |
termsUrl | Hizmet Koşulları’na bağlantı |
emailSupport | Destek e-posta adresi |
issueReportUrl | Sorun izleyicisine bağlantı |
Roller ve izinler
application-config.ts içindeki defaultRoleUniversalIdentifier, uygulamanızın mantık fonksiyonları ve ön bileşenleri tarafından kullanılan varsayılan rolü belirtir. Ayrıntılar için yukarıdaki defineRole bölümüne bakın.TWENTY_APP_ACCESS_TOKENolarak enjekte edilen çalışma zamanı belirteci bu rolden türetilir.- Türlendirilmiş istemci, o role tanınan izinlerle sınırlandırılır.
- En az ayrıcalık ilkesini izleyin: Yalnızca fonksiyonlarınızın ihtiyaç duyduğu izinlere sahip özel bir rol oluşturun.
Varsayılan fonksiyon rolü
Yeni bir uygulama iskeleti oluşturduğunuzda, CLI varsayılan bir rol dosyası oluşturur:src/roles/default-role.ts
universalIdentifier değeri, application-config.ts içinde defaultRoleUniversalIdentifier olarak referans verilir:- *.role.ts, bir rolün neler yapabileceğini tanımlar.
- application-config.ts, fonksiyonlarınızın izinlerini devralması için bu role işaret eder.
- Oluşturulan rolden başlayın ve en az ayrıcalık ilkesini izleyerek bunu aşamalı olarak kısıtlayın.
objectPermissionsvefieldPermissionsdeğerlerini, fonksiyonlarınızın ihtiyaç duyduğu nesneler ve alanlarla değiştirin.permissionFlags, platform düzeyindeki yeteneklere erişimi kontrol eder. Bunları asgari düzeyde tutun.- Çalışan bir örnek için bkz.:
hello-world/src/roles/function-role.ts.
defineObject
Alanlara sahip özel nesneler tanımlayın
defineObject
Alanlara sahip özel nesneler tanımlayın
Özel nesneler, çalışma alanınızdaki kayıtlar için hem şemayı hem de davranışı tanımlar. Yerleşik doğrulamayla nesneler tanımlamak için Önemli noktalar:
defineObject() kullanın:postCard.object.ts
- Yerleşik doğrulama ve daha iyi IDE desteği için
defineObject()kullanın. universalIdentifierdağıtımlar arasında benzersiz ve kararlı olmalıdır.- Her alan bir
name,type,labelve kendi kararlıuniversalIdentifierdeğerini gerektirir. fieldsdizisi isteğe bağlıdır — özel alanlar olmadan da nesneler tanımlayabilirsiniz.yarn twenty addkullanarak, adlandırma, alanlar ve ilişkiler konusunda sizi yönlendirerek yeni nesneler oluşturabilirsiniz.
Temel alanlar otomatik olarak oluşturulur. Özel bir nesne tanımladığınızda Twenty, standart alanları otomatik olarak ekler
örneğin
id, name, createdAt, updatedAt, createdBy, updatedBy ve deletedAt.
Bunları fields dizinizde tanımlamanız gerekmez — yalnızca özel alanlarınızı ekleyin.
fields dizinizde aynı ada sahip bir alan tanımlayarak varsayılan alanları geçersiz kılabilirsiniz,
ancak bu önerilmez.defineField — Standart alanlar
Mevcut nesneleri ek alanlarla genişletin
defineField — Standart alanlar
Mevcut nesneleri ek alanlarla genişletin
Sahibi olmadığınız nesnelere alan eklemek için Önemli noktalar:
defineField() kullanın — standart Twenty nesneleri (Person, Company, vb.) gibi. veya diğer uygulamalardaki nesneler. defineObject() içindeki satır içi alanların aksine, bağımsız alanlar hangi nesneyi genişlettiklerini belirtmek için bir objectUniversalIdentifier gerektirir:src/fields/company-loyalty-tier.field.ts
objectUniversalIdentifierhedef nesneyi tanımlar. Standart nesneler için,twenty-sdk’den dışa aktarılanSTANDARD_OBJECT_UNIVERSAL_IDENTIFIERS’ı kullanın.- Alanları
defineObject()içinde satır içi tanımlarken,objectUniversalIdentifier’a ihtiyacınız yoktur — üst nesneden devralınır. defineField(),defineObject()ile oluşturmadığınız nesnelere alan eklemenin tek yoludur.
defineField — İlişki alanları
Nesneleri çift yönlü ilişkilerle birbirine bağlayın
defineField — İlişki alanları
Nesneleri çift yönlü ilişkilerle birbirine bağlayın
İlişkiler nesneleri birbirine bağlar. Twenty’de ilişkiler her zaman çift yönlüdür — her iki tarafı da tanımlarsınız ve her taraf diğerine başvurur.İki ilişki türü vardır:
Adım 2: PostCardRecipient üzerinde MANY_TO_ONE tarafını tanımlayın (“çok” taraf — yabancı anahtarı tutar):
| İlişki türü | Açıklama | Yabancı anahtar var mı? |
|---|---|---|
MANY_TO_ONE | Bu nesnenin birçok kaydı, hedefin bir kaydını işaret eder | Evet (joinColumnName) |
ONE_TO_MANY | Bu nesnenin bir kaydı, hedefin birçok kaydına sahiptir | Hayır (ters taraf) |
İlişkiler nasıl çalışır
Her ilişki, birbirine referans veren iki alan gerektirir:- MANY_TO_ONE tarafı — yabancı anahtarı tutan nesne üzerinde bulunur
- ONE_TO_MANY tarafı — koleksiyona sahip olan nesne üzerinde bulunur
FieldType.RELATION kullanır ve relationTargetFieldMetadataUniversalIdentifier aracılığıyla birbirine karşılıklı referans verir.Örnek: Posta Kartı’nın birçok Alıcısı vardır
BirPostCard’ın birçok PostCardRecipient kaydına gönderilebildiğini varsayalım. Her alıcı tam olarak bir posta kartına aittir.Adım 1: PostCard üzerinde ONE_TO_MANY tarafını tanımlayın (“bir” taraf):src/fields/post-card-recipients-on-post-card.field.ts
src/fields/post-card-on-post-card-recipient.field.ts
Döngüsel içe aktarmalar: Her iki ilişki alanı da birbirlerinin
universalIdentifier değerine referans verir. Döngüsel içe aktarma sorunlarından kaçınmak için, alan kimliklerinizi her dosyadan adlandırılmış sabitler olarak dışa aktarın ve diğer dosyada içe aktarın. Derleme sistemi bunları derleme zamanında çözer.Standart nesnelerle ilişkilendirme
Yerleşik bir Twenty nesnesiyle (Person, Company, vb.) ilişki oluşturmak içinSTANDARD_OBJECT_UNIVERSAL_IDENTIFIERS kullanın:src/fields/person-on-self-hosting-user.field.ts
İlişki alanı özellikleri
| Özellik | Zorunlu | Açıklama |
|---|---|---|
type | Evet | FieldType.RELATION olmalıdır |
relationTargetObjectMetadataUniversalIdentifier | Evet | Hedef nesnenin universalIdentifier değeri |
relationTargetFieldMetadataUniversalIdentifier | Evet | Hedef nesnedeki eşleşen alanın universalIdentifier değeri |
universalSettings.relationType | Evet | RelationType.MANY_TO_ONE veya RelationType.ONE_TO_MANY |
universalSettings.onDelete | Yalnızca MANY_TO_ONE | Başvurulan kayıt silindiğinde ne olacağı: CASCADE, SET_NULL, RESTRICT veya NO_ACTION |
universalSettings.joinColumnName | Yalnızca MANY_TO_ONE | Yabancı anahtar için veritabanı sütun adı (örn. postCardId) |
defineObject içinde satır içi ilişki alanları
İlişki alanlarını doğrudandefineObject() içinde de tanımlayabilirsiniz. Bu durumda, objectUniversalIdentifier’ı atlayın — üst nesneden devralınır:yarn twenty add ile varlıklar için iskelet oluşturma
Varlık dosyalarını elle oluşturmak yerine etkileşimli iskelet oluşturucuyu kullanabilirsiniz:
universalIdentifier ve doğru defineEntity() çağrısıyla kullanıma hazır bir dosya üretir.
İlk istemi atlamak için varlık türünü doğrudan da geçebilirsiniz:
Kullanılabilir varlık türleri
| Varlık türü | Komut | Oluşturulan dosya |
|---|---|---|
| Nesne | yarn twenty add object | src/objects/\<name>.ts |
| Alan | yarn twenty add field | src/fields/\<name>.ts |
| Mantık işlevi | yarn twenty add logicFunction | src/logic-functions/\<name>.ts |
| Ön uç bileşeni | yarn twenty add frontComponent | src/front-components/\<name>.tsx |
| Rol | yarn twenty add role | src/roles/\<name>.ts |
| Beceri | yarn twenty add skill | src/skills/\<name>.ts |
| Temsilci | yarn twenty add agent | src/agents/\<name>.ts |
| Görünüm | yarn twenty add view | src/views/\<name>.ts |
| Gezinme menüsü öğesi | yarn twenty add navigationMenuItem | src/navigation-menu-items/\<name>.ts |
| Sayfa düzeni | yarn twenty add pageLayout | src/page-layouts/\<name>.ts |
İskelet oluşturucunun ürettikleri
Her varlık türünün kendi şablonu vardır. Örneğin,yarn twenty add object şunları sorar:
- Ad (tekil) — ör.
invoice - Ad (çoğul) — ör.
invoices - Etiket (tekil) — adından otomatik doldurulur (ör.
Invoice) - Etiket (çoğul) — otomatik doldurulur (ör.
Invoices) - Bir görünüm ve gezinme öğesi oluşturulsun mu? — evet derseniz, iskelet oluşturucu yeni nesne için eşleşen bir görünüm ve kenar çubuğu bağlantısı da üretir.
field varlık türü daha ayrıntılıdır: alan adını, etiketi, türü (TEXT, NUMBER, SELECT, RELATION vb. gibi mevcut tüm alan türlerinin listesinden) ve hedef nesnenin universalIdentifier değerini sorar.
Özel çıktı yolu
--path bayrağını kullanarak oluşturulan dosyayı özel bir konuma yerleştirin: