snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/ko/user-guide/data-migration/capabilities/error-handling.mdx

@@ -0,0 +1,76 @@
+---
+title: 오류 처리 및 유효성 검사
+description: 확인하기 전에 UI에서 가져오기 오류를 검토하고 바로 수정하세요.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+## 가져오기 전 유효성 검사
+
+파일을 업로드하고 필드를 매핑한 후, Twenty는 데이터를 가져오기 **이전에** 유효성 검사를 수행합니다. 이렇게 하면 기존 데이터에 영향을 주지 않고 오류를 찾아 수정할 수 있습니다.
+
+## 작동 방식
+
+1. **업로드**: CSV 파일을 업로드하세요
+2. **매핑**: 열을 Twenty 필드에 매핑하세요
+3. **검토**: 노란색으로 강조 표시된 잠재적 오류를 확인하세요
+4. **오류 수정**: UI에서 바로 수정하세요
+5. **확인**: 가져오기를 확인하세요
+
+<VimeoEmbed videoId="1145273857" title="동영상 시연" />
+
+## 오류 표시
+
+문제가 있는 행은 **노란색**으로 강조 표시됩니다. 다음을 수행할 수 있습니다:
+
+* **셀을 직접 편집**하여 오류를 수정하세요
+* **행을 제거**하여 완전히 건너뛰세요
+
+이 인라인 편집은 시간을 절약해 줍니다 — 스프레드시트로 돌아가 오류를 수정하고 다시 업로드할 필요가 없습니다.
+
+## 일반적인 오류 유형
+
+### 중복 값
+
+**원인**: 고유 필드(이메일, 도메인)가 Twenty에 이미 존재하거나 파일에 두 번 나타납니다.
+
+**해결 방법**:
+
+* 가져오기 UI에서 중복 값을 편집하세요
+* 중복된 행 중 하나를 제거하세요
+
+고유성이 어떻게 적용되는지에 대한 자세한 내용은 [고유성 제약](/l/ko/user-guide/data-migration/capabilities/uniqueness-constraints)을 참조하세요.
+
+### 잘못된 형식
+
+**원인**: 데이터가 예상 형식과 일치하지 않습니다(예: 잘못된 이메일, 잘못된 날짜 형식).
+
+**해결 방법**: 올바른 형식을 사용하도록 셀을 편집하세요.
+
+필드 유형별로 예상되는 형식은 [필드 매핑](/l/ko/user-guide/data-migration/capabilities/field-mapping)을 참조하세요.
+
+### 필수 필드 누락
+
+**원인**: 필수 필드가 비어 있습니다.
+
+**해결 방법**: 필수 필드에 값을 입력하거나 해당 행을 제거하세요.
+
+### 관계를 찾을 수 없음
+
+**원인**: 참조된 레코드가 존재하지 않습니다(예: 가져오지 않은 회사 도메인).
+
+**해결 방법**:
+
+* 상위 레코드를 먼저 가져오세요
+* 또는 참조 값을 수정하세요
+
+올바른 가져오기 순서와 레코드를 연결하는 방법은 [관계 가져오기](/l/ko/user-guide/data-migration/capabilities/import-relations)를 참조하세요.
+
+## 오류를 줄이기 위한 팁
+
+1. **템플릿을 다운로드**하여 파일을 가져오기 전에 예상 형식을 확인하세요
+2. **데이터 정리**: 먼저 스프레드시트에서 데이터를 정리하세요
+3. **올바른 순서로 파일을 가져오세요** 관계를 가져오기 위해 (Companies → People → Opportunities)
+4. **소규모 배치로 테스트**: 전체 가져오기 전에 테스트해 보세요
+5. **중복 확인**: 업로드 전에 중복을 확인하세요
+6. **각 파일의 레코드를 10,000개로 제한하세요**

packages/twenty-docs/l/ko/user-guide/data-migration/capabilities/field-mapping.mdx

@@ -0,0 +1,198 @@
+---
+title: 필드 매핑
+description: 데이터 가져오기 시 필드 매핑이 작동하는 방식.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+## 필드 매핑 작동 방식
+
+파일을 업로드하면 Twenty가 열을 분석하여 기존 필드와 일치시키려고 시도합니다.
+
+### 자동 매핑
+
+Twenty는 다음을 기준으로 열을 일치시키려고 시도합니다:
+
+* 열 헤더 이름(정확 또는 유사 일치)
+* 데이터 유형 감지(날짜, 숫자, 이메일)
+* 일반적인 필드 패턴
+
+<Note>**빠른 팁:** 가져오려는 객체에서 몇 행을 내보내세요. 내보낸 파일에는 Twenty가 기대하는 정확한 열 이름이 포함되어, 가져오는 동안 자동 매핑이 원활해집니다.</Note>
+
+### 수동 매핑 옵션
+
+각 열에 대해 다음을 수행할 수 있습니다:
+
+* **필드에 매핑**: 드롭다운에서 일치하는 Twenty 필드를 선택
+* **매핑하지 않음**: 해당 열을 완전히 건너뜁니다(데이터가 가져오지 않습니다)
+
+<Note>**가져오기 전에 필드가 존재해야 합니다.** 가져오기는 필드가 아니라 레코드를 생성합니다. 가져오기 전에 **설정 → 데이터 모델**에서 사용자 지정 필드를 생성하세요.</Note>
+
+## 필드 유형 호환성
+
+데이터 모델에서 제공되는 모든 필드 유형이 가져오기를 지원합니다.
+
+`id` 값을 가져와 새 레코드에 특정 ID를 지정하거나 기존 레코드를 업데이트할 수도 있습니다.
+
+<img src="/images/user-guide/fields/all-field-types.png" style={{width:'100%'}} />
+
+## 데이터 형식 요구 사항
+
+<Note>**일부 필드는 특별한 구문이 있습니다.** 가져오기를 준비하기 전에 샘플 파일을 다운로드하여 각 필드 유형에 필요한 구문을 확인하는 것을 권장합니다.</Note>
+
+### 주소 필드
+
+Address는 여러 열로 구성된 중첩 필드입니다. 일부는 비워 둘 수 있습니다.
+
+* **Address / Address 1**: 주소 1행
+* **Address / Address 2**: 주소 2행
+* **Address / City**: 도시 이름
+* **Address / State**: 주 또는 도
+* **Address / Country**: 국가 이름
+* **Address / Post Code**: 우편번호/ZIP 코드
+
+### 배열 필드
+
+다음 형식을 사용하세요:
+
+```
+["value1","value2"]
+```
+
+### 부울 필드
+
+`TRUE` 또는 `FALSE`(대문자) - `true`나 `false`는 사용하지 마세요
+
+### 통화 필드
+
+통화는 두 개의 열이 있는 중첩 필드이며, **두 열 모두** 채워야 합니다:
+
+* **Amount / Amount**: 숫자 값(예: `1234.56`)
+* **Amount / Currency**: 통화 코드(예: `USD`, `EUR`)
+
+### 날짜 필드
+
+지원되는 형식:
+
+* `YYYY-MM-DD`(권장)
+* `MM/DD/YYYY`
+* `DD/MM/YYYY`
+* ISO 8601 형식
+
+### 도메인 필드
+
+* 중복 생성을 방지하려면 `https://domain.com` 형식 사용을 권장합니다. 이 형식은 메일박스 및 캘린더 동기화로 생성되는 Companies 객체에 사용됩니다.
+* `Domain Label`과 `Domain URL`을 모두 채울 수 있습니다. 모범 사례는 라벨에는 `domain.com`, URL에는 `https://domain.com`을 입력하는 것입니다.
+* 도메인은 Companies 객체 내에서 고유해야 합니다
+* **가져올 파일 내에서도 도메인은 고유해야 합니다**
+
+### 이메일 필드
+
+* 유효한 이메일 형식이어야 합니다
+* 이메일은 People 객체 내에서 고유해야 합니다
+* **가져올 파일 내에서도 이메일은 고유해야 합니다**
+* 추가 이메일의 경우: 기본 이메일은 **Emails / Primary Email**을 사용하고, **Emails / Additional Emails**에는 다음 형식을 사용하세요:
+
+```
+["jane@twenty.com","jane.doe@twenty.com"]
+```
+
+### ID 필드
+
+가져오기 중 `id`를 지정하는 것은 선택 사항입니다. 제공하지 않으면 Twenty가 ID를 자동으로 생성합니다.
+
+`id` 열을 매핑하는 사용 사례:
+
+* **특정 ID 설정**: 새로 생성될 레코드에 사용할 UUID를 선택
+* **기존 레코드 업데이트**: 중복 생성 대신 기존 레코드와 일치시켜 업데이트 이 경우 다른 고유 필드는 매핑하지 않는 것을 권장합니다. 고유 필드를 하나만 매핑하면 가져오기가 더 원활합니다.
+
+<Note>`id`를 제공하는 경우 UUID 형식이어야 합니다(예: `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`).</Note>
+
+### JSON 필드
+
+유효한 JSON 형식을 사용하세요:
+
+```
+{"key":"value","key2":"value2"}
+```
+
+### 링크 필드
+
+도메인 필드와 유사합니다:
+
+* 라벨과 URL 두 열을 모두 채우세요: **Links / Link URL** 및 **Links / Link Label**
+* 전체 URL 형식을 사용하세요: `https://example.com`
+* 보조 링크의 경우 **Links / Secondary Links** 열을 사용하고 다음 형식을 사용하세요:
+
+```
+[{"url":"https://twenty.com","label":"Twenty"}]
+```
+
+### 다중 선택 필드
+
+표시 라벨이 아니라 **API 이름**을 다음 형식으로 사용하세요:
+
+```
+["VALUE1","VALUE2"]
+```
+
+API 이름을 찾는 위치는 [여기](#finding-api-names-for-select-fields)를 참고하세요.
+
+<Note>새 선택 옵션은 가져오기로 자동 생성되지 않습니다. 가져오기 전에 **설정 → 데이터 모델**에서 추가해야 합니다.</Note>
+
+<Warning>
+**가져오기는 추가하지 않고 덮어씁니다.**
+
+레코드에 이미 `VALUE2`와 `VALUE3`가 선택되어 있고 `["VALUE1"]`을 가져오면, 가져온 후 해당 레코드에는 `VALUE1`만 남습니다. 이전 선택 항목은 병합되지 않고 대체됩니다.
+</Warning>
+
+### 숫자 필드
+
+* 숫자만 입력
+* 소수점은 점을 사용합니다: `1234.56`
+* 천 단위 구분 기호 사용 금지
+
+### 전화 필드
+
+전화는 여러 열로 구성된 중첩 필드이며 **반드시 채워야 합니다**
+
+* **Phones / Primary Phone Number**: 전화번호(예: `4159095555`)
+* **Phones / Primary Phone Country Code**: 국가 코드(예: `US`)
+* **Phones / Primary Phone Calling Code**: 전화 걸기 코드(예: `+1`)
+
+### 평점 필드
+
+API 이름 형식을 사용하세요: `RATING_1`, `RATING_2`, `RATING_3`, `RATING_4`, `RATING_5`
+
+### 관계 필드
+
+전용 문서를 참고하세요: [객체 간 관계 가져오기](/l/ko/user-guide/data-migration/capabilities/import-relations)
+
+### 선택 필드
+
+표시 라벨이 아니라 옵션의 **API 이름**을 사용하세요:
+
+```
+VALUE1
+```
+
+API 이름을 찾는 위치는 [여기](#finding-api-names-for-select-fields)를 참고하세요.
+<Note>새 선택 옵션은 가져오기로 자동 생성되지 않습니다. 가져오기 전에 **설정 → 데이터 모델**에서 추가해야 합니다.</Note>
+
+### 텍스트 필드
+
+* 특별한 형식 지정은 필요하지 않습니다
+* 앞뒤 공백은 제거됩니다
+
+## API 이름 찾기
+
+사전 정의된 옵션이 있는 Select, Multi-Select, Array 필드의 경우 표시 레이블이 아니라 반드시 **API 이름**을 사용해야 합니다.
+
+### API 이름을 찾는 방법
+
+1. **설정 → 데이터 모델**로 이동
+2. 객체와 필드를 선택하세요
+3. **고급 모드**를 활성화하세요(설정 페이지 오른쪽 하단의 토글)
+4. 각 옵션의 API 이름을 확인하세요
+
+<VimeoEmbed videoId="1144910809" title="동영상 시연" />

packages/twenty-docs/l/ko/user-guide/data-migration/capabilities/file-formats.mdx

@@ -0,0 +1,48 @@
+---
+title: 지원되는 파일 형식
+description: Twenty에서 데이터 가져오기에 지원되는 파일 형식입니다.
+---
+
+## 지원되는 형식
+
+Twenty는 가져오기를 위해 세 가지 파일 형식을 지원합니다:
+
+| 형식             | 확장자   | 노트             |
+| -------------- | ----- | -------------- |
+| **CSV**        | .csv  | 권장, 가장 호환성이 높음 |
+| **Excel**      | .xlsx | 최신 Excel 형식    |
+| **Excel(레거시)** | .xls  | 이전 Excel 형식    |
+
+## 파일 요구 사항
+
+| 요구 사항      | 값                         |
+| ---------- | ------------------------- |
+| **인코딩**    | UTF-8 권장                  |
+| **레코드 제한** | 파일당 10,000개 레코드           |
+| **구조**     | 첫 번째 행에는 열 머리글이 포함되어야 합니다 |
+| **내용**     | 파일당 개체 유형 1개              |
+
+## CSV 모범 사례
+
+* **구분 기호**: 쉼표(`,`) 또는 세미콜론(`;`)을 사용하세요
+* **텍스트 한정 기호**: 쉼표가 포함된 텍스트에는 큰따옴표(`"`)를 사용하세요
+* **줄 바꿈**: Windows(CRLF) 또는 Unix(LF) 모두 지원
+* **빈 값**: 셀을 비워 두고, "NULL"이나 "N/A"는 사용하지 마세요
+
+## Excel 모범 사례
+
+Excel에서 내보낼 때:
+
+* 수식을 제거하세요(값만 내보내기)
+* 끝부분의 빈 행을 삭제하세요
+* 병합된 셀이 없도록 하세요
+* 첫 번째 시트만 사용하세요
+
+## 대용량 데이터셋
+
+레코드가 10,000개를 초과하는 데이터셋의 경우:
+
+* 여러 파일로 분할하세요
+* 또는 레코드 수에 제한이 없는 [API 가져오기](/l/ko/user-guide/data-migration/how-tos/import-data-via-api)를 사용하세요
+
+<Note>매우 큰 마이그레이션(레코드 100,000개 이상)에는 CSV 가져오기보다 API가 훨씬 더 빠르고 신뢰성이 높습니다.</Note>

packages/twenty-docs/l/ko/user-guide/data-migration/capabilities/import-relations.mdx

@@ -0,0 +1,148 @@
+---
+title: 객체 간 관계 가져오기
+description: CSV를 통해 레코드 간 관계를 가져옵니다.
+---
+
+## 개요
+
+Twenty는 CSV 가져오기 시 객체 간 관계 가져오기를 지원합니다. 이를 통해 데이터 마이그레이션의 일부로 레코드를 연결할 수 있습니다(예: 사람을 회사에 연결).
+
+<Note>**현재 가져오기에서 지원됨**: 각 측이 단일 객체 유형을 가리키는 일대다 관계(예: 사람 → 회사). 여러 객체 유형을 가리키는 관계는 아직 가져오기/내보내기를 지원하지 않습니다.</Note>
+
+## Twenty에서 관계가 작동하는 방식
+
+### 일대다 / 다대일
+
+Twenty는 하나의 레코드가 여러 다른 레코드에 연결되는 표준 관계를 지원합니다:
+
+* **하나의 회사 → 여러 사람**: 한 회사에는 여러 직원이 있을 수 있지만, 각 사람은 하나의 회사에 속합니다
+* **하나의 회사 → 여러 기회**: 한 회사에는 여러 거래가 있을 수 있지만, 각 기회는 하나의 회사에 속합니다
+
+### 여러 객체 유형을 가리킬 수 있는 관계
+
+일부 관계는 서로 다른 유형의 객체에 연결될 수 있습니다. 이는 두 가지 방식으로 작동합니다:
+
+**패턴 1: 서로 다른 객체 유형의 많은 레코드가 각각 하나의 레코드에 연결**
+
+여러 개의 노트 또는 작업을 한 번에 여러 객체 유형에 각각 연결할 수 있습니다:
+
+* **노트**는 동시에 한 사람, 한 회사, 한 기회에 연결될 수 있습니다
+* **작업**은 동시에 한 사람, 한 회사, 한 기회에 연결될 수 있습니다
+
+여기서 노트/작업은 "many" 쪽에 있습니다. 각각은 객체 유형당 하나의 레코드에 연결됩니다.
+
+<img src="/images/user-guide/fields/many-to-one-morph.png" style={{width:'100%'}} />
+
+**패턴 2: 하나의 레코드가 서로 다른 객체 유형의 많은 레코드로부터 연결을 받는 경우**
+
+프로젝트는 서로 다른 객체 유형의 여러 레코드로부터 연결을 받을 수 있습니다:
+
+* **프로젝트**에는 많은 사람이 연결될 수 있고, 많은 회사가 연결될 수 있으며, 많은 노트가 첨부될 수 있습니다
+
+여기서 프로젝트는 "one" 쪽에 있습니다. 서로 다른 객체의 여러 레코드가 모두 동일한 프로젝트에 연결될 수 있습니다.
+
+<img src="/images/user-guide/fields/one-to-many-morph.png" style={{width:'100%'}} />
+
+<Warning>
+**가져오기/내보내기 제한사항**: 여러 객체 유형을 가리키는 관계(예: 노트 → 사람/회사/기회)는 CSV 가져오기나 내보내기에서 **아직 지원되지 않습니다**.
+
+* **가져오기**: 각 측이 단일 객체 유형을 가리키는 일대다 관계만 가져올 수 있습니다
+* **내보내기**: 여러 객체 유형을 가리키는 관계의 열은 현재 비워 둡니다
+
+이는 로드맵에 포함되어 있습니다.
+</Warning>
+
+### 현재 지원되지 않는 사항
+
+**다대다 관계**는 아직 제공되지 않습니다. 예를 들어, 현재 다음과 같은 관계는 만들 수 없습니다:
+
+* 여러 사람이 여러 프로젝트에 연결되는 경우
+
+<Note>다대다 관계는 2026년 하반기에 제공될 예정입니다.</Note>
+
+## 가져오기 중 레코드 연결
+
+<Note>**알림**: 각 측이 단일 객체 유형을 가리키는 일대다 관계만 가져올 수 있습니다(예: 사람 → 회사). 여러 객체 유형을 가리키는 관계(예: 노트 → 사람/회사/기회)는 아직 지원되지 않습니다.</Note>
+
+### 1단계: "One"과 "Many" 쪽 식별하기
+
+먼저, 어떤 객체가 관계의 "one" 쪽이고 어떤 객체가 "many" 쪽인지 결정하세요.
+
+**예시**:
+
+* **회사**는 "one" 쪽입니다(한 회사에는 많은 직원이 있음)
+* **사람**은 "many" 쪽입니다(각 사람은 하나의 회사에 속함)
+
+### 2단계: "One" 쪽 레코드가 존재하는지 확인
+
+"many" 쪽을 가져오기 전에, "one" 쪽 레코드는 이미 Twenty에 존재해야 합니다.
+
+* "one" 쪽 레코드를 먼저 가져오거나 생성하세요(예: 회사)
+* 해당 고유 식별자를 확인하세요. 이는 다음 중 하나일 수 있습니다:
+  * `id`(Twenty의 UUID)
+  * 고유로 설정된 필드(예: 회사의 `domain`, 또는 이전 시스템의 외부 ID)
+
+<Warning>존재하지 않는 레코드를 참조하면 가져오기는 실패합니다.</Warning>
+
+### 3단계: CSV 파일 준비
+
+"many" 쪽 CSV 파일에 "one" 쪽 레코드를 참조하는 열을 추가하세요.
+
+**예시**: 회사에 연결되는 사람 CSV 파일의 경우:
+
+```
+firstName,lastName,email,companyDomain
+John,Smith,john@acme.com,https://acme.com
+Jane,Doe,jane@widgets.co,https://widgets.co
+```
+
+**중요**:
+
+* 값은 회사 레코드의 고유 필드와 정확히 일치해야 합니다
+* 도메인의 경우 도메인 라벨이 아니라 **도메인 URL**(예: `https://acme.com`)을 사용하세요
+* 관계당 고유 식별자는 오직 하나만 매핑하세요: 이렇게 하면 가져오기가 원활해집니다
+
+### 4단계: 관계 필드가 존재하는지 확인
+
+파일을 업로드하기 전에 객체 간에 관계 필드가 존재하는지 확인하세요.
+
+존재하지 않는 경우:
+
+1. **설정 → 데이터 모델**로 이동
+2. 객체를 선택하세요(예: 사람)
+3. 대상 객체(예: 회사)를 가리키는 관계 필드를 생성하세요
+
+### 5단계: 업로드하고 관계 매핑하기
+
+1. 가져오기 UI를 통해 CSV 파일을 업로드하세요
+2. 필드 매핑 단계에서 관계 열을 찾으세요(예: `companyDomain`)
+3. 이를 관계 필드에 매핑하세요(예: 회사)
+4. Twenty가 각 레코드를 일치하는 상위에 자동으로 연결합니다
+
+### 관계를 위한 사용 가능한 고유 필드
+
+| 객체                    | 사용 가능한 고유 필드                     |
+| --------------------- | -------------------------------- |
+| **회사**                | `id`, `domain`, 임의의 사용자 지정 고유 필드 |
+| **사람**                | `id`, `email`, 임의의 사용자 지정 고유 필드  |
+| **워크스페이스 구성원**        | `id`, `email`(이름 아님)             |
+| **기타 표준 및 사용자 지정 객체** | `id`, 고유로 표시된 모든 필드              |
+
+<Note>**워크스페이스 구성원에 연결**: 관계가 워크스페이스 구성원(Twenty에 로그인하는 팀)을 가리키는 경우, 이름이 아니라 **이메일 주소**로 참조하세요.</Note>
+
+<Note>스프레드시트에서 읽기 쉽고 관리가 간편하므로, 회사에는 `domain`, 사람에는 `email` 사용을 권장합니다.</Note>
+
+<Note>**알림**: 소프트 삭제된 레코드(Command Menu → See deleted records에서 확인 가능)도 고유성 기준에 포함됩니다. 삭제된 레코드와 동일한 고유 값을 가진 레코드를 가져오면, 삭제된 레코드가 복원됩니다. 자세한 내용은 [고유성 제약](/l/ko/user-guide/data-migration/capabilities/uniqueness-constraints)을 참조하세요.</Note>
+
+## 가져오기 순서 규칙
+
+<Warning>
+**항상 "one" 쪽을 먼저 가져오세요!**
+
+1. **회사** 먼저(종속성 없음)
+2. **사람** 두 번째(회사에 연결됨)
+3. **기회** 세 번째(회사/사람에 연결됨)
+4. **사용자 지정 객체**는 종속성에 따라 순서대로
+
+참조하려면 상위 레코드가 먼저 존재해야 합니다.
+</Warning>

packages/twenty-docs/l/ko/user-guide/data-migration/capabilities/uniqueness-constraints.mdx

@@ -0,0 +1,72 @@
+---
+title: 고유성 제약 조건
+description: Twenty가 가져오기 중 데이터 고유성을 강제하는 방법.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+## 개요
+
+Twenty는 중복 레코드를 방지하고 데이터 무결성을 보장하기 위해 일부 필드에 고유성을 강제합니다. 이러한 제약 조건을 이해하는 것은 성공적인 가져오기에 필수적입니다.
+
+## 기본 고유 필드
+
+| 객체            | 고유 필드          |
+| ------------- | -------------- |
+| **사람**        | `id`, `email`  |
+| **회사**        | `id`, `domain` |
+| **사용자 지정 개체** | `id`만 (기본값)    |
+
+<Note>`id` 필드는 Twenty의 내부 식별자로, 각 레코드에 대해 자동 생성됩니다. UUID 형식을 사용합니다(예: `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`).</Note>
+
+## 사용자 지정 고유 필드
+
+**설정 → 데이터 모델**에서 추가 고유 필드를 정의할 수 있습니다:
+
+1. **설정 → 데이터 모델**로 이동
+2. 객체를 선택하세요
+3. 필드를 클릭하세요
+4. 필드 설정에서 **Unique**를 활성화하세요
+
+### 사용자 지정 고유 필드의 활용 사례
+
+* **외부 ID**: 다른 시스템의 ID 저장(Salesforce ID, HubSpot ID)
+* **비즈니스 식별자**: 사번, 고객 코드
+* **대체 연락처 정보**: LinkedIn 프로필, 전화번호
+
+<Note>필드 이름 `id`는 Twenty의 내부 ID로 예약되어 있습니다. 외부 식별자에는 `externalId` 또는 `legacyId`와 같은 다른 이름을 사용하세요.</Note>
+
+## 가져오기 동작 방식
+
+### 새 레코드 생성
+
+고유 필드 값이 존재하지 않으면 새 레코드가 생성됩니다.
+
+### 기존 레코드 업데이트
+
+고유 필드 값이 기존 레코드와 일치하면 해당 레코드는 새 데이터로 **업데이트**됩니다.
+<Warning>기존 레코드를 **업데이트**하려면 **하나의 고유 필드만** 매칭하는 것을 권장합니다.</Warning>
+
+### 소프트 삭제된 레코드
+
+<Warning>
+**삭제된 레코드도 고유성에 포함됩니다.**
+
+소프트 삭제된 레코드는(Command Menu → See deleted records에서 확인 가능) 고유성 검사에 포함됩니다. 삭제된 레코드와 동일한 고유 값을 가진 레코드를 가져오면, 삭제된 레코드는 새 데이터로 **복원**됩니다.
+</Warning>
+
+## 가져오기 중 중복 감지
+
+유효성 검사 단계에서:
+
+* 파일 내 중복 항목은 노란색으로 강조 표시됩니다
+* 가져오기를 시작하기 전에 UI에서 중복 행을 편집하거나 제거할 수 있습니다
+
+<VimeoEmbed videoId="1145246326" title="동영상 시연" />
+
+## 모범 사례
+
+1. 가져오기 전에 파일에서 **중복 항목을 제거**하세요
+2. 가져오기 전에 Twenty에서 **기존 레코드가 있는지 확인**하세요
+3. 다른 시스템에서 마이그레이션할 때 **외부 ID를 사용**하세요
+4. 기존 레코드를 업데이트하려면 **고유 필드를 포함**하세요