102 lines
11 KiB
Plaintext
102 lines
11 KiB
Plaintext
---
|
|
title: Понятия
|
|
description: Как работают приложения Twenty — модель сущностей, изоляция в песочнице и жизненный цикл установки.
|
|
icon: sitemap
|
|
---
|
|
|
|
Приложения Twenty — это пакеты TypeScript, которые расширяют ваше рабочее пространство пользовательскими объектами, логикой, компонентами интерфейса и возможностями ИИ. Они работают на платформе Twenty с полной изоляцией в песочнице и контролем прав доступа.
|
|
|
|
## Как работают приложения
|
|
|
|
Приложение — это набор **сущностей**, объявленных с помощью функций `defineEntity()` из пакета `twenty-sdk`. SDK обнаруживает эти объявления посредством анализа AST на этапе сборки и формирует **манифест** — полное описание того, что ваше приложение добавляет в рабочее пространство. Эти функции проверяют вашу конфигурацию на этапе сборки и обеспечивают автодополнение в IDE и безопасность типов.
|
|
|
|
```
|
|
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/ru/developers/extend/apps/config/application) |
|
|
| **Роль** | Наборы прав для объектов и полей | [Роли и разрешения](/l/ru/developers/extend/apps/config/roles) |
|
|
| **Объект** | Пользовательские типы записей с полями | [Объекты](/l/ru/developers/extend/apps/data/objects) |
|
|
| **Поле** | Добавляйте поля к объектам из других приложений | [Расширение объектов](/l/ru/developers/extend/apps/data/extending-objects) |
|
|
| **Связь** | Двунаправленные связи между объектами | [Связи](/l/ru/developers/extend/apps/data/relations) |
|
|
| **Логическая функция** | Серверный TypeScript с триггерами | [Логические функции](/l/ru/developers/extend/apps/logic/logic-functions) |
|
|
| **Навык** | Повторно используемые инструкции для ИИ-агента | [Навыки и агенты](/l/ru/developers/extend/apps/logic/skills-and-agents) |
|
|
| **Агент** | ИИ-агенты с пользовательскими промптами | [Навыки и агенты](/l/ru/developers/extend/apps/logic/skills-and-agents) |
|
|
| **Провайдер подключения** | Учётные данные OAuth для сторонних API | [Подключения](/l/ru/developers/extend/apps/logic/connections) |
|
|
| **Представление** | Преднастроенные представления списков записей | [Представления](/l/ru/developers/extend/apps/layout/views) |
|
|
| **Пункт меню навигации** | Пользовательские элементы боковой панели | [Элементы меню навигации](/l/ru/developers/extend/apps/layout/navigation-menu-items) |
|
|
| **Макет страницы** | Вкладки и виджеты на странице сведений о записи | [Макеты страниц](/l/ru/developers/extend/apps/layout/page-layouts) |
|
|
| **Компонент фронтенда** | Изолированный в песочнице интерфейс React внутри Twenty | [Компоненты фронтенда](/l/ru/developers/extend/apps/layout/front-components) |
|
|
| **Элемент меню команд** | Быстрые действия и элементы Cmd+K | [Элементы меню команд](/l/ru/developers/extend/apps/layout/command-menu-items) |
|
|
|
|
## Изоляция в песочнице
|
|
|
|
* **Логические функции** выполняются в изолированных процессах 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 и формирует манифест.
|
|
* **Хуки до/после установки** — необязательные функции, которые выполняются во время установки. См. раздел [Install Hooks](/l/ru/developers/extend/apps/config/install-hooks) для подробностей.
|
|
|
|
## Следующие шаги
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Конфигурация" icon="screwdriver-wrench" href="/l/ru/developers/extend/apps/config/overview">
|
|
Идентификация приложения, роль по умолчанию и хуки установки.
|
|
</Card>
|
|
<Card title="Данные" icon="database" href="/l/ru/developers/extend/apps/data/overview">
|
|
Объекты, поля и двунаправленные связи.
|
|
</Card>
|
|
<Card title="Логика" icon="bolt" href="/l/ru/developers/extend/apps/logic/overview">
|
|
Логические функции, навыки, агенты и OAuth-подключения.
|
|
</Card>
|
|
<Card title="Макет" icon="table-columns" href="/l/ru/developers/extend/apps/layout/overview">
|
|
Представления, навигация, макеты страниц, фронтенд-компоненты.
|
|
</Card>
|
|
<Card title="Операции" icon="rocket" href="/l/ru/developers/extend/apps/operations/overview">
|
|
CLI, тестирование, удаленные окружения, CI и публикация вашего приложения.
|
|
</Card>
|
|
</CardGroup>
|