Skip to content

The open alternative to Salesforce, designed for AI.

10.8 KB
Raw Blame
---
title: نظرة عامة
description: شكّل البيانات التي يضيفها تطبيقك إلى مساحة العمل — الكائنات والحقول والعلاقات.
---

import { PageBanner } from "/snippets/page-banner.mdx"
import { CardTitle } from "/snippets/card-title.mdx"

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

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

```text
┌──────────────────────────────────────────────────┐
│ 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    │
└──────────────────────────────────────────────────┘
```

## في هذا القسم

<CardGroup cols={2} className="documentation-card-group">
  <Card href="/ar/developers/extend/apps/data/objects" img="/images/user-guide/halftone/card-page-objects.svg">
    <CardTitle>الكائنات</CardTitle>
    `defineObject` - اعلن عن أنواع السجلات الجديدة مع حقول تخصهم.
  </Card>
  <Card href="/ar/developers/extend/apps/data/extending-objects" img="/images/user-guide/halftone/card-page-extending-objects.svg">
    <CardTitle>توسيع الكائنات</CardTitle>
    `defineField` - إضافة حقول إلى الكائنات القياسية أو التطبيقات الأخرى.
  </Card>
  <Card href="/ar/developers/extend/apps/data/relations" img="/images/user-guide/halftone/card-page-relations.svg">
    <CardTitle>العلاقات</CardTitle>
    الاتصالات الثنائية الاتجاه `MANY_TO_ONE` / `ONE_TO_MANY` بين الأشياء.
  </Card>
  <Card href="/ar/developers/extend/apps/data/timeline-activity-types" img="/images/user-guide/halftone/card-page-timeline.svg">
    <CardTitle>النشاط من النوع</CardTitle>
    حدد أحداث المراجعة التلقائية وأحداث التطبيق الصريحة لجداول زمنية للتسجيل.
  </Card>
  <Card href="/ar/developers/extend/apps/data/validation-rules" img="/images/user-guide/halftone/card-page-objects.svg">
    <CardTitle>قواعد التحقق</CardTitle>
    `defineValidationRule` — أعلن الشروط التي يجب أن يستوفيها السجل قبل أن يمكن حفظه.
  </Card>
</CardGroup>

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

| كيان                       | الغرض                                                                                                   | مُعرَّفة باستخدام                       |
| -------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| **الكائن**                 | نوع سجل مخصص جديد (مثل 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` تربط كل شيء معًا عبر عمليات النشر.

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

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

```ts 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 })` مهملة وسيتم إزالتها في إصدار قادم.

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

### قيود أخرى

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

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

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

<Warning>
  مسارات السجلات المرتبطة متاحة في المعاينة: تتزامن مع تطبيقك، لكن أذونات
  السجلات لا تستخدمها بعد. عند فرضها، تتطلب
  **خطة Organization أو أعلى**، مثل
  [الأمان على مستوى الصف](/ar/developers/extend/apps/config/roles#row-level-security).
</Warning>

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

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

```ts 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` للمسارات الأطول. يجب أن تكون كل قفزة علاقة نشطة على الكائن الذي تم الوصول إليه حتى الآن، ولا يمكن لمسار أن يزور الكائن نفسه مرتين، ولا يمكن لمسارين استخدام القفزات نفسها.

<Note>
هل تبحث عن **Application Config** أو **Roles & Permissions**؟ هذه تصف التطبيق نفسه بدلًا من البيانات التي يضيفها — وتوجد ضمن [Config](/ar/developers/extend/apps/config/overview). هل تبحث عن **Connections** (Linear, GitHub, Slack OAuth)؟ هذه وُجِدت ليتم استدعاؤها *من* دوال المنطق وتوجد ضمن [Logic](/ar/developers/extend/apps/logic/connections).
</Note>

<PageBanner illustration="section-apps-data" />