نظرة عامة

ما تغطيه طبقة البيانات

طبقة البيانات في تطبيق Twenty هي البيانات التي يضيفها تطبيقك إلى مساحة العمل — أنواع السجلات الجديدة التي يصرّح عنها، والأعمدة التي يضيفها إلى الكائنات الموجودة، وكيف ترتبط هذه السجلات ببعضها البعض.

┌──────────────────────────────────────────────────┐
│ Object — a record type, e.g. PostCard            │
│    ├─ Field     (name, type, label)              │
│    ├─ Field                                      │
│    └─ Relation  (link to another object)         │
└──────────────────────────────────────────────────┘
            │
            ├── lives in your app, OR
            │
            ▼
┌──────────────────────────────────────────────────┐
│ Standard / other apps' objects                   │
│    └─ Field added by your app via defineField    │
└──────────────────────────────────────────────────┘

في هذا القسم

الكائنات

defineObject - اعلن عن أنواع السجلات الجديدة مع حقول تخصهم.

توسيع الكائنات

defineField - إضافة حقول إلى الكائنات القياسية أو التطبيقات الأخرى.

العلاقات

الاتصالات الثنائية الاتجاه MANY_TO_ONE / ONE_TO_MANY بين الأشياء.

النشاط من النوع

حدد أحداث المراجعة التلقائية وأحداث التطبيق الصريحة لجداول زمنية للتسجيل.

قواعد التحقق

defineValidationRule — أعلن الشروط التي يجب أن يستوفيها السجل قبل أن يمكن حفظه.

الكيانات بنظرة سريعة

كيان	الغرض	مُعرَّفة باستخدام
الكائن	نوع سجل مخصص جديد (مثل PostCard أو Invoice) مع حقوله الخاصة	`defineObject()`
الحقل	عمود على كائن. يمكن للحقول المستقلة توسيع الكائنات التي لم تنشئها (مثل إضافة `loyaltyTier` إلى Company)	`defineField()`
علاقة	ارتباط ثنائي الاتجاه بين كائنين — يُصرّح عن كلا الجانبين كحقول	`defineField()` مع `FieldType.RELATION`
الفهرس	فهرس قاعدة بيانات لتسريع استعلام متكرر على أحد الكائنات لديك	`defineIndex()`
نوع نشاط الجدول الزمني	حدث تدقيق تلقائي أو حدث مجال صريح يظهر في المخططات الزمنية للسجلات	`defineTimelineActivityType()`
مسار السجل المرتبط	سلسلة تضم ما يصل إلى ثلاث علاقات يمتد عبرها الوصول إلى سجل ليشمل سجلاته المرتبطة	`defineRelatedRecordPath()`
قاعدة التحقق	شرط يجب أن يستوفيه السجل قبل أن يمكن حفظه	`defineValidationRule()`

تكتشف واجهة سطر الأوامر هذه العناصر عبر تحليل AST أثناء وقت البناء، لذا فإن تنظيم الملفات يعود إليك — القاعدة المتّبعة هي src/objects/ و src/validation-rules/ و src/fields/ و src/indexes/ و src/timeline-activity-types/ و src/related-record-paths/. معرّفات UUID ثابتة من نوع universalIdentifier تربط كل شيء معًا عبر عمليات النشر.

الفهارس (اختياري)

يمكن للتطبيقات إرفاق الفهارس مع الكائنات الخاصة بها للحفاظ على سرعة الاستعلامات المتكررة. أكثر الحالات شيوعًا هي عمود حالة أو مفتاح أجنبي تقوم بقراءته بشكل متكرر.

src/indexes/post-card-status.index.ts

import { defineIndex } from 'twenty-sdk/define';

import {
  POST_CARD_UNIVERSAL_IDENTIFIER,
  STATUS_FIELD_UNIVERSAL_IDENTIFIER,
} from '../objects/post-card.object';

export default defineIndex({
  universalIdentifier: 'b6e9d2a1-5a4c-46ca-9d52-42c8f02d1ff0',
  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
  fields: [
    {
      universalIdentifier: 'b6e9d2a1-5a4c-46ca-9d52-42c8f02d1ff1',
      fieldUniversalIdentifier: STATUS_FIELD_UNIVERSAL_IDENTIFIER,
    },
  ],
});

الفهارس الفريدة

تقبل defineIndex الخيار isUnique: true لكلٍّ من التفرد على عمود واحد أو على عدّة أعمدة. هذه هي البنية الموصى بها — إن defineField({ isUnique: true }) مهملة وسيتم إزالتها في إصدار قادم.

defineIndex({
  universalIdentifier: '…',
  objectUniversalIdentifier: PERSON_UNIVERSAL_IDENTIFIER,
  isUnique: true,
  fields: [{ universalIdentifier: '…', fieldUniversalIdentifier: EMAIL_FIELD_UNIVERSAL_IDENTIFIER }],
});

قيود أخرى

تظل عبارات WHERE الجزئية تحت تحكم المشرف — لا يمكن للتطبيقات التصريح بها.
يتم تقييد كل كائن بعدد 10 فهارس مخصصة (لا تُحتسب فهارس الإطار نفسه).

رتّب مصفوفة fields بالطريقة التي ينبغي على Postgres استخدامها — العمود في أقصى اليسار أولًا، مثل دليل الهاتف. الفهارس ليست مجانية: كل عملية كتابة في الجدول تقوم بتحديثها. أضِف واحدًا فقط عندما يكون لديك استعلام يحتاج إليه.

مسارات السجلات المرتبطة (اختياري)

مسارات السجلات المرتبطة متاحة في المعاينة: تتزامن مع تطبيقك، لكن أذونات السجلات لا تستخدمها بعد. عند فرضها، تتطلب خطة Organization أو أعلى، مثل الأمان على مستوى الصف.

يبدأ مسار سجل مرتبط على كائن ويتبع ما يصل إلى ثلاثة حقول علاقة، يكون كل منها على الكائن الذي وصل إليه الحقل السابق. تستخدم أذونات السجلات هذه المسارات لتوسيع الوصول من سجل إلى سجلاته المرتبطة.

يُطبَّق المسار المتأصل (isInherent: true) كلما كان السجل الابتدائي قابلاً للقراءة، مهما كانت طريقة منح ذلك الوصول. استخدمه للسجلات التي تنتمي إلى أصلها، مثل مرفقات بطاقة منشور.
يُطبَّق المسار العادي فقط عندما يأتي الوصول إلى السجل الابتدائي مباشرةً من دور، بحيث تختار مساحات العمل المسارات التي تعتمد عليها.

src/related-record-paths/post-card-attachments.related-record-path.ts

import { defineRelatedRecordPath } from 'twenty-sdk/define';

import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
import { ATTACHMENTS_ON_POST_CARD_UNIVERSAL_IDENTIFIER } from '../fields/attachments-on-post-card.field';

export default defineRelatedRecordPath({
  universalIdentifier: 'c1b8f0d2-7e4a-4b6c-9a1d-3f5e2b7c8d90',
  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
  firstFieldMetadataUniversalIdentifier:
    ATTACHMENTS_ON_POST_CARD_UNIVERSAL_IDENTIFIER,
  isInherent: true,
});

أضف secondFieldMetadataUniversalIdentifier وthirdFieldMetadataUniversalIdentifier للمسارات الأطول. يجب أن تكون كل قفزة علاقة نشطة على الكائن الذي تم الوصول إليه حتى الآن، ولا يمكن لمسار أن يزور الكائن نفسه مرتين، ولا يمكن لمسارين استخدام القفزات نفسها.

هل تبحث عن Application Config أو Roles & Permissions؟ هذه تصف التطبيق نفسه بدلًا من البيانات التي يضيفها — وتوجد ضمن Config. هل تبحث عن Connections (Linear, GitHub, Slack OAuth)؟ هذه وُجِدت ليتم استدعاؤها من دوال المنطق وتوجد ضمن Logic.

المطورون

التطبيقات

واجهة برمجة التطبيقات

الاستضافة الذاتية

المساهمة

مكتبة واجهة المستخدم

ما تغطيه طبقة البيانات

في هذا القسم

الكيانات بنظرة سريعة

الفهارس (اختياري)

الفهارس الفريدة

قيود أخرى

مسارات السجلات المرتبطة (اختياري)

​ما تغطيه طبقة البيانات

​في هذا القسم

​الكيانات بنظرة سريعة

​الفهارس (اختياري)

​الفهارس الفريدة

​قيود أخرى

​مسارات السجلات المرتبطة (اختياري)

ما تغطيه طبقة البيانات

في هذا القسم

الكيانات بنظرة سريعة

الفهارس (اختياري)

الفهارس الفريدة

قيود أخرى

مسارات السجلات المرتبطة (اختياري)