105 lines
8.9 KiB
Plaintext
105 lines
8.9 KiB
Plaintext
---
|
|
title: الهيكلية
|
|
description: كيف تعمل تطبيقات Twenty — العزل، دورة الحياة، واللبنات الأساسية.
|
|
icon: sitemap
|
|
---
|
|
|
|
تطبيقات Twenty هي حزم TypeScript توسّع مساحة عملك بكائنات مخصّصة، ومنطق، ومكوّنات واجهة مستخدم (UI)، وقدرات ذكاء اصطناعي. تعمل على منصة Twenty مع عزل كامل وضوابط الأذونات.
|
|
|
|
## كيف تعمل التطبيقات
|
|
|
|
التطبيق عبارة عن مجموعة من **الكيانات** يتم إعلانها باستخدام دوال `defineEntity()` من حزمة `twenty-sdk`. يكتشف SDK هذه التصريحات عبر تحليل AST وقت البناء وينتج **ملف بيان** — وصفًا كاملًا لما يضيفه تطبيقك إلى مساحة العمل.
|
|
|
|
```
|
|
your-app/
|
|
├── src/
|
|
│ ├── application-config.ts ← defineApplication (required, one per app)
|
|
│ ├── roles/ ← defineRole
|
|
│ ├── objects/ ← defineObject
|
|
│ ├── fields/ ← defineField
|
|
│ ├── logic-functions/ ← defineLogicFunction
|
|
│ ├── front-components/ ← defineFrontComponent
|
|
│ ├── skills/ ← defineSkill
|
|
│ ├── agents/ ← defineAgent
|
|
│ ├── views/ ← defineView
|
|
│ ├── navigation-menu-items/ ← defineNavigationMenuItem
|
|
│ └── page-layouts/ ← definePageLayout
|
|
├── public/ ← Static assets (images, icons)
|
|
└── package.json
|
|
```
|
|
|
|
<Note>
|
|
**تنظيم الملفات متروك لك.** يعتمد اكتشاف الكيانات على AST — يعثر SDK على استدعاءات `export default defineEntity(...)` بغض النظر عن مكان وجود الملف. بنية المجلدات أعلاه هي اصطلاح وليست متطلبًا.
|
|
</Note>
|
|
|
|
## أنواع الكيانات
|
|
|
|
| كيان | الغرض | وثائق |
|
|
| ---------------------- | ------------------------------------------------------ | -------------------------------------------------------------- |
|
|
| **تطبيق** | هوية التطبيق، الأذونات، المتغيرات | [نموذج البيانات](/l/ar/developers/extend/apps/data-model) |
|
|
| **دور** | مجموعات الأذونات للكائنات والحقول | [نموذج البيانات](/l/ar/developers/extend/apps/data-model) |
|
|
| **الكائن** | جداول بيانات مخصّصة مع حقول | [نموذج البيانات](/l/ar/developers/extend/apps/data-model) |
|
|
| **الحقل** | توسيع الكائنات الموجودة، تعريف العلاقات | [نموذج البيانات](/l/ar/developers/extend/apps/data-model) |
|
|
| **دالة منطقية** | TypeScript على جانب الخادم مع مشغّلات | [الوظائف المنطقية](/l/ar/developers/extend/apps/logic-functions) |
|
|
| **مكوّن أمامي** | واجهة مستخدم React معزولة داخل صفحة Twenty. | [المكوّنات الأمامية](/l/ar/developers/extend/apps/front-components) |
|
|
| **مهارة** | تعليمات قابلة لإعادة الاستخدام لوكلاء الذكاء الاصطناعي | [المهارات والوكلاء](/l/ar/developers/extend/apps/skills-and-agents) |
|
|
| **وكيل** | مساعدو الذكاء الاصطناعي بموجهات مخصّصة | [المهارات والوكلاء](/l/ar/developers/extend/apps/skills-and-agents) |
|
|
| **عرض** | عروض قوائم السجلات المكوّنة مسبقًا | [التخطيط](/l/ar/developers/extend/apps/layout) |
|
|
| **عنصر قائمة التنقّل** | عناصر الشريط الجانبي المخصّصة | [التخطيط](/l/ar/developers/extend/apps/layout) |
|
|
| **تخطيط الصفحة** | علامات تبويب وعناصر واجهة مخصّصة لصفحة السجل | [التخطيط](/l/ar/developers/extend/apps/layout) |
|
|
|
|
## العزل
|
|
|
|
* **الدوال المنطقية** تعمل في عمليات Node.js معزولة على الخادم. لا تصل إلى البيانات إلا عبر عميل API مضبوط الأنواع، ومقيَّد بأذونات دور التطبيق.
|
|
* **المكوّنات الأمامية** تعمل ضمن Web Workers باستخدام Remote DOM — معزولة عن الصفحة الرئيسية لكنها تعرض عناصر DOM الأصلية (وليس iframes). تتواصل مع Twenty عبر واجهة API للمضيف تعتمد تمرير الرسائل.
|
|
* **الأذونات** تُطبَّق على مستوى واجهة API. يُشتق رمز وقت التشغيل (`TWENTY_APP_ACCESS_TOKEN`) من الدور المعرَّف في `defineApplication()`.
|
|
|
|
## دورة حياة التطبيق
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Development │
|
|
│ npx create-twenty-app → yarn twenty dev (live sync) │
|
|
├─────────────────────────────────────────────────────────┤
|
|
│ Build & Deploy │
|
|
│ yarn twenty build → yarn twenty deploy │
|
|
├─────────────────────────────────────────────────────────┤
|
|
│ Install flow │
|
|
│ upload → [pre-install] → metadata migration → │
|
|
│ generate SDK → [post-install] │
|
|
├─────────────────────────────────────────────────────────┤
|
|
│ Publish │
|
|
│ npm publish → appears in Twenty marketplace │
|
|
└─────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
* **`yarn twenty dev`** — يراقب ملفات المصدر لديك ويزامن التغييرات مباشرةً إلى خادم Twenty متصل. يُعاد توليد عميل API مضبوط الأنواع تلقائيًا عند تغيّر المخطط.
|
|
* **`yarn twenty build`** — يجمّع TypeScript، ويضمّن الدوال المنطقية والمكوّنات الأمامية باستخدام esbuild، وينتج ملف بيان.
|
|
* **خطّافات ما قبل/ما بعد التثبيت** — دوال منطقية اختيارية تعمل أثناء التثبيت. راجع [الدوال المنطقية](/l/ar/developers/extend/apps/logic-functions) للحصول على التفاصيل.
|
|
|
|
## الخطوات التالية
|
|
|
|
<CardGroup cols={٢}>
|
|
<Card title="نموذج البيانات" icon="database" href="/l/ar/developers/extend/apps/data-model">
|
|
عرّف الكائنات والحقول والأدوار والعلاقات.
|
|
</Card>
|
|
<Card title="الوظائف المنطقية" icon="bolt" href="/l/ar/developers/extend/apps/logic-functions">
|
|
دوال على جانب الخادم مع HTTP وcron ومشغّلات الأحداث.
|
|
</Card>
|
|
<Card title="المكوّنات الأمامية" icon="window-maximize" href="/l/ar/developers/extend/apps/front-components">
|
|
مكوّنات React معزولة داخل واجهة مستخدم Twenty.
|
|
</Card>
|
|
<Card title="التخطيط" icon="table-columns" href="/l/ar/developers/extend/apps/layout">
|
|
العروض، وعناصر التنقّل، وتخطيطات صفحات السجل.
|
|
</Card>
|
|
<Card title="المهارات والوكلاء" icon="robot" href="/l/ar/developers/extend/apps/skills-and-agents">
|
|
مهارات ووكلاء ذكاء اصطناعي بموجهات مخصّصة.
|
|
</Card>
|
|
<Card title="CLI والاختبار" icon="terminal" href="/l/ar/developers/extend/apps/cli-and-testing">
|
|
أوامر CLI، والاختبار، والأصول، والوحدات البعيدة، وCI.
|
|
</Card>
|
|
<Card title="النشر" icon="rocket" href="/l/ar/developers/extend/apps/publishing">
|
|
انشر إلى خادم أو انشر في السوق.
|
|
</Card>
|
|
</CardGroup>
|