github-actions[bot]
a3a6a55051
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
102 lines
8.1 KiB
Plaintext
102 lines
8.1 KiB
Plaintext
---
|
|
title: 개념
|
|
description: Twenty 앱이 작동하는 방식 — 엔티티 모델, 샌드박싱, 설치 라이프사이클.
|
|
icon: sitemap
|
|
---
|
|
|
|
Twenty 앱은 사용자 정의 객체, 로직, UI 컴포넌트 및 AI 기능으로 워크스페이스를 확장하는 TypeScript 패키지입니다. 앱은 Twenty 플랫폼에서 완전한 샌드박싱과 권한 제어 하에 실행됩니다.
|
|
|
|
## 앱 작동 방식
|
|
|
|
앱은 `twenty-sdk` 패키지의 `defineEntity()` 함수를 사용해 선언된 **엔티티**의 모음입니다. 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>
|
|
|
|
## 엔티티 유형
|
|
|
|
| 엔티티 | 목적 | 문서 |
|
|
| --------------- | ------------------------- | ----------------------------------------------------------------------------- |
|
|
| **애플리케이션** | 앱 식별, 기본 역할, 변수 | [Application Config](/l/ko/developers/extend/apps/config/application) |
|
|
| **역할** | 객체와 필드에 대한 권한 세트 | [Roles & Permissions](/l/ko/developers/extend/apps/config/roles) |
|
|
| **객체** | 필드가 있는 사용자 정의 레코드 타입 | [Objects](/l/ko/developers/extend/apps/data/objects) |
|
|
| **필드** | 다른 앱의 객체에 필드를 추가 | [Extending Objects](/l/ko/developers/extend/apps/data/extending-objects) |
|
|
| **관계** | 객체 간 양방향 링크 | [Relations](/l/ko/developers/extend/apps/data/relations) |
|
|
| **로직 함수** | 트리거가 있는 서버 측 TypeScript | [로직 함수](/l/ko/developers/extend/apps/logic/logic-functions) |
|
|
| **스킬** | 재사용 가능한 AI 에이전트 지침 | [스킬 및 에이전트](/l/ko/developers/extend/apps/logic/skills-and-agents) |
|
|
| **에이전트** | 사용자 지정 프롬프트를 사용하는 AI 에이전트 | [스킬 및 에이전트](/l/ko/developers/extend/apps/logic/skills-and-agents) |
|
|
| **연결 제공자** | 서드파티 API용 OAuth 자격 증명 | [Connections](/l/ko/developers/extend/apps/logic/connections) |
|
|
| **뷰** | 사전 구성된 레코드 목록 뷰 | [Views](/l/ko/developers/extend/apps/layout/views) |
|
|
| **내비게이션 메뉴 항목** | 사용자 정의 사이드바 항목 | [Navigation Menu Items](/l/ko/developers/extend/apps/layout/navigation-menu-items) |
|
|
| **페이지 레이아웃** | 레코드 상세 페이지의 탭과 위젯 | [Page Layouts](/l/ko/developers/extend/apps/layout/page-layouts) |
|
|
| **프런트 컴포넌트** | Twenty 내부의 샌드박스 React UI | [프런트 컴포넌트](/l/ko/developers/extend/apps/layout/front-components) |
|
|
| **명령 메뉴 항목** | 빠른 작업 및 Cmd+K 항목 | [Command Menu Items](/l/ko/developers/extend/apps/layout/command-menu-items) |
|
|
|
|
## 샌드박싱
|
|
|
|
* **로직 함수**는 서버의 격리된 Node.js 프로세스에서 실행됩니다. 이들은 앱의 역할 권한 범위로 제한된 타입이 지정된 API 클라이언트를 통해서만 데이터에 접근합니다.
|
|
* **프런트 컴포넌트**는 Remote DOM을 사용하는 Web Worker에서 실행됩니다 — 메인 페이지와는 샌드박스로 격리되어 있지만 네이티브 DOM 요소를 렌더링합니다(iframe이 아님). 이들은 메시지 전달 호스트 API를 통해 Twenty와 통신합니다.
|
|
* **권한**은 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로 번들링하며, 매니페스트를 생성합니다.
|
|
* **사전/사후 설치 및 제거 훅** — 설치 중이거나 제거 직전에 실행되는 선택적 함수입니다. 자세한 내용은 [Install Hooks](/l/ko/developers/extend/apps/config/install-hooks)를 참조하세요.
|
|
|
|
## 다음 단계
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="설정" icon="screwdriver-wrench" href="/l/ko/developers/extend/apps/config/overview">
|
|
애플리케이션 식별, 기본 역할, 설치 및 제거 훅.
|
|
</Card>
|
|
<Card title="데이터" icon="database" href="/l/ko/developers/extend/apps/data/overview">
|
|
객체, 필드, 양방향 관계.
|
|
</Card>
|
|
<Card title="로직" icon="bolt" href="/l/ko/developers/extend/apps/logic/overview">
|
|
로직 함수, 스킬, 에이전트, OAuth 연결.
|
|
</Card>
|
|
<Card title="레이아웃" icon="table-columns" href="/l/ko/developers/extend/apps/layout/overview">
|
|
뷰, 내비게이션, 페이지 레이아웃, 프런트 컴포넌트.
|
|
</Card>
|
|
<Card title="작업" icon="rocket" href="/l/ko/developers/extend/apps/operations/overview">
|
|
CLI, 테스트, 리모트, CI, 앱 게시.
|
|
</Card>
|
|
</CardGroup>
|