> ## Documentation Index
> Fetch the complete documentation index at: https://make.edicus.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 큰 그림

> 편집기가 내 사이트에 들어오는 방식과 세 참여자가 주고받는 것

Edicus 연동을 시작하기 전에, 누가 누구와 무엇을 주고받는지 한 번 정리하고 갑니다. 이 그림을 잡아 두면 이후 문서가 훨씬 빨리 읽힙니다.

## 세 참여자

| 참여자 | 하는 일 | 가지고 있는 것 |
| - | - | - |
| **브라우저** | 편집기를 iframe으로 띄우고 편집기와 메시지를 주고받습니다 | 토큰 |
| **고객사 서버** | 토큰을 발급받고, 프로젝트를 조회하고, 주문을 넣습니다 | API 키 |
| **Edicus 서버** | 토큰으로 사용자를 확인하고, 프로젝트와 주문을 보관하고, 인쇄용 파일을 렌더링합니다 | 전부 |

```mermaid theme={null}
sequenceDiagram
    participant B as 브라우저
    participant P as 고객사 서버
    participant E as Edicus 서버

    B->>P: 1. 토큰 요청
    P->>E: 2. POST /v2/auth/token
    E-->>P: token
    P-->>B: token

    B->>E: 3. 편집기 iframe 띄우기 (token, ps_code, template_uri)
    E-->>B: ready-to-listen
    Note over B,E: postMessage로 이벤트와 커맨드를 주고받습니다
    E-->>B: project-id-created
    B->>P: 4. project_id 저장

    Note over B,E: 사용자가 편집하고 저장합니다
    E-->>B: save-doc-report (status: end)
    E-->>B: goto-cart (사용자가 나가기를 누름)

    B->>P: 5. 주문 요청
    P->>E: POST /v2/.../order/tentative
    E-->>P: order_id
```

<Warning>
  화살표 2번과 5번은 반드시 서버에서 갑니다. API 키가 브라우저로 내려가면 누구나 그 키로 남의 프로젝트를 조회하고 주문을 넣을 수 있습니다.
</Warning>

고객사 서버가 Edicus 서버를 부를 때 실패는 4xx와 5xx 상태 코드로 옵니다. body의 `error.code`로 원인을 구분합니다. 자세한 내용은 [오류 처리](/docs/server/errors)에 있습니다.

## 편집기는 iframe입니다

편집기는 내 페이지에 설치되는 것이 아니라, Edicus가 호스팅하는 페이지를 내가 지정한 요소 안에 iframe으로 넣는 방식입니다. 그래서 다음이 따라옵니다.

* 편집기와 내 페이지는 서로 다른 origin입니다. 직접 함수를 부를 수 없고 `postMessage`로만 대화합니다. 이 `postMessage`를 감싸 준 것이 SDK의 **세션**입니다.
* iframe을 넣을 요소에 크기가 없으면 편집기가 보이지 않습니다.
* 브라우저 뒤로가기나 앞으로가기로 편집기 iframe이 다시 보여야 하는 경우, 편집기는 보이지 않도록 되어 있습니다. 페이지 전환을 직접 관리하셔야 합니다.

## SDK는 브라우저 쪽에만 있습니다

| 어디서 | 무엇으로 | 무엇을 |
| - | - | - |
| 브라우저 | `@edicus/sdk` | 편집기, TnView, Preview iframe을 띄우고 통신합니다. API 키를 다루지 않습니다 |
| 고객사 서버 | HTTP 직접 호출 | 토큰 발급, 프로젝트 조회, 주문 처리를 합니다. **API 키를 다룹니다** |

**서버용 JS SDK는 제공하지 않습니다.** 서버 연동은 언어를 가리지 않도록 HTTP 엔드포인트를 직접 호출하는 방식입니다. 자세한 내용은 [설치와 진입점](/docs/sdk/install)과 [Server API 호출하기](/docs/server/client)에 있습니다.

## 세션 하나가 iframe 하나입니다

브라우저 쪽 SDK의 핵심 개념입니다. 띄우기 메서드를 한 번 부르면 세션이 하나 생기고, 그 세션이 iframe 하나를 담당합니다.

```ts theme={null}
const edicus = createEdicusClient()          // 클라이언트 하나
const editor = edicus.createProject({ ... }) // 세션 하나 = iframe 하나
const preview = edicus.openPreview({ ... })  // 또 다른 세션 = 또 다른 iframe
```

들어오는 메시지는 어느 iframe에서 왔는지로 구분해 해당 세션에만 전달됩니다. 편집기와 미리보기를 동시에 띄워도 메시지가 섞이지 않습니다.

## 편집기 화면에는 세 가지 모드가 있습니다

| 모드 | 무엇 | 문서 |
| - | - | - |
| **편집기** | 사용자가 디자인을 편집합니다. 가장 많이 쓰는 모드입니다 | [편집기 띄우기](/docs/sdk/launch) |
| **TnView** | 저장된 프로젝트의 썸네일만 가볍게 보여줍니다. 가변 데이터를 주입할 수 있습니다 | [TnView와 VDP](/docs/sdk/tnview) |
| **Preview** | 저장된 프로젝트를 읽기 전용으로 보여줍니다 | [Preview](/docs/sdk/preview) |

## 프로젝트의 일생

사용자가 편집한 결과물을 Edicus에서는 **프로젝트**라고 부릅니다.

```mermaid theme={null}
stateDiagram-v2
    [*] --> editing: 편집기로 생성
    editing --> ordering: 잠정 주문
    ordering --> editing: 취소
    ordering --> ordered: 확정 주문
    ordered --> rendering
    rendering --> rendered
```

* `editing`에서는 사용자가 자유롭게 편집하고 저장합니다.
* 잠정 주문을 넣으면 `ordering`이 됩니다. 편집 권한이 회수되지만 아직 취소할 수 있습니다.
* 확정 주문을 넣으면 `ordered`가 되고 인쇄용 파일 렌더링이 시작됩니다. 이 뒤로는 취소할 수 없습니다.

자세한 내용은 [주문 라이프사이클](/docs/server/orders)에 있습니다.

## 다음 단계

<Columns cols={2}>
  <Card title="토큰과 API 키" icon="key" href="/docs/concepts/authentication">
    두 자격 증명이 각각 무엇을 할 수 있는지 정리합니다.
  </Card>

  <Card title="설치와 진입점" icon="box" href="/docs/sdk/install">
    세 개의 임포트 경로 중 무엇을 언제 쓰는지 봅니다.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.