المفاهيم

تطبيقات 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

تنظيم الملفات متروك لك. يعتمد اكتشاف الكيانات على AST — يعثر SDK على استدعاءات export default defineEntity(...) بغض النظر عن مكان وجود الملف. بنية المجلدات أعلاه هي اصطلاح وليست متطلبًا.

أنواع الكيانات

كيان	الغرض	وثائق
تطبيق	هوية التطبيق، الدور الافتراضي، والمتغيرات	تهيئة التطبيق
دور	مجموعات الأذونات للكائنات والحقول	الأدوار والأذونات
الكائن	أنواع سجلات مخصّصة مع حقول	الكائنات
الحقل	إضافة حقول إلى الكائنات من تطبيقات أخرى	توسيع الكائنات
علاقة	روابط ثنائية الاتجاه بين الكائنات	العلاقات
دالة منطقية	TypeScript على جانب الخادم مع مشغّلات	الوظائف المنطقية
مهارة	تعليمات قابلة لإعادة الاستخدام لوكلاء الذكاء الاصطناعي	المهارات والوكلاء
وكيل	مساعدو الذكاء الاصطناعي بموجهات مخصّصة	المهارات والوكلاء
موفر الاتصال	بيانات اعتماد OAuth لواجهات برمجة التطبيقات التابعة لجهات خارجية	الاتصالات
عرض	عروض قوائم السجلات المكوّنة مسبقًا	العروض
عنصر قائمة التنقّل	عناصر الشريط الجانبي المخصّصة	عناصر قائمة التنقّل
تخطيط الصفحة	علامات التبويب وعناصر الواجهة في صفحة تفاصيل السجل	تخطيطات الصفحات
مكوّن أمامي	واجهة مستخدم React معزولة داخل Twenty	المكوّنات الأمامية
عنصر قائمة الأوامر	إجراءات سريعة ومدخلات Cmd+K	عناصر قائمة الأوامر

العزل

الدوال المنطقية تعمل في عمليات 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 dev:build → yarn twenty app:publish        │
├─────────────────────────────────────────────────────────┤
│ Install flow                                            │
│   upload → [pre-install] → metadata migration →         │
│   generate SDK → [post-install] → … → [uninstall]       │
├─────────────────────────────────────────────────────────┤
│ Publish                                                 │
│   npm publish → appears in Twenty marketplace           │
└─────────────────────────────────────────────────────────┘

yarn twenty dev — يراقب ملفات المصدر لديك ويزامن التغييرات مباشرةً إلى خادم Twenty متصل. يُعاد توليد عميل API مضبوط الأنواع تلقائيًا عند تغيّر المخطط.
yarn twenty dev:build — يجمّع TypeScript، ويضمّن الدوال المنطقية والمكوّنات الأمامية باستخدام esbuild، وينتج ملف بيان.
خطّافات ما قبل/ما بعد التثبيت وإلغاء التثبيت — دوال اختيارية تعمل أثناء التثبيت أو مباشرة قبل الإزالة. راجع خطّافات التثبيت للتفاصيل.

الخطوات التالية

التهيئة

هوية التطبيق، الدور الافتراضي، وخطّافات التثبيت وإلغاء التثبيت.

بيانات

الكائنات، الحقول، والعلاقات ثنائية الاتجاه.

المنطق

دوال منطقية، مهارات، وكلاء، واتصالات OAuth.

التخطيط

العروض، التنقّل، تخطيطات الصفحات، ومكوّنات الواجهة الأمامية.

العمليات

سطر الأوامر (CLI)، الاختبار، المستودعات البعيدة (remotes)، التكامل المستمر (CI)، ونشر تطبيقك.

نظرة عامة

التطبيقات

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

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

المساهمة

كيف تعمل التطبيقات

أنواع الكيانات

العزل

دورة حياة التطبيق

الخطوات التالية

التهيئة

بيانات

المنطق

التخطيط

العمليات

​كيف تعمل التطبيقات

​أنواع الكيانات

​العزل

​دورة حياة التطبيق

​الخطوات التالية

التهيئة

بيانات

المنطق

التخطيط

العمليات

كيف تعمل التطبيقات

أنواع الكيانات

العزل

دورة حياة التطبيق

الخطوات التالية