Doconut을 사용한 문서 관리 구현

.NET 포털에서 문서 관리 워크플로는 일반적으로 세 가지가 필요합니다:

1. 뷰어를 처음부터 작성하지 않고 PDF, Office 파일, CAD 도면 또는 이미지를 로드하는 방법.
2. 로드된 문서를 현재 브라우저 세션에 연결하는 보안 토큰.
3. 사용자가 작업을 마치면 즉시 메모리를 해제하는 정리 단계.

Doconut은 단일 Viewer 서비스, 가벼운 IMemoryCache 세션, 명시적인 CloseDocument 호출을 통해 이 세 가지를 모두 제공합니다.

---

1. DI 컨테이너에 뷰어 등록

애플리케이션 시작 시, 공식 문서에 설명된 Doconut 등록 메서드를 호출하여 DI 컨테이너에 Doconut 서비스를 추가합니다. 이 단계는 뷰어, 라이선스 처리 및 문서 세션을 보관할 인‑메모리 캐시를 등록합니다.

등록 과정은 시작 시 라이선스를 검증하므로, 누락되거나 잘못된 라이선스는 즉시 실패하고 첫 번째 요청이 서버에 도달하기 전에 문제를 알 수 있습니다.

---

2. 페이지 이미지, 썸네일 및 주석 데이터를 제공하는 미들웨어 삽입

요청 파이프라인에 Doconut 미들웨어를 구성하여 ?token= 쿼리 문자열이 포함된 모든 요청을 Doconut이 처리하도록 합니다. 미들웨어는 UnsafeMode가 false(기본값)일 때 기본 보안 마커(secure-{token})를 적용하고 페이지 이미지, 썸네일 및 주석 데이터를 제공합니다.

전용 브랜치에 미들웨어를 배치하면 파이프라인의 나머지 부분은 그대로 유지되며, 스티키 세션 없이 수평 확장이 가능합니다.

---

3. 문서를 열고 불투명 세션 토큰 얻기

파일 경로(또는 스트림)를 받아 토큰을 반환하는 단일 엔드포인트를 생성합니다. 토큰은 클라이언트 위젯이 볼 수 있는 유일한 인증 정보입니다.

app.MapPost("/api/open", async (Viewer viewer) =>
{
    // 토큰은 불투명합니다 — 위젯에 전달하고, 절대 로그에 남기거나 영구 저장하지 마세요.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Contract.pdf");
    return Results.Ok(new { token });
});

OpenDocumentAsync 내부에서 일어나는 일

1. 라이선스 게이트 – 잘못된 라이선스는 즉시 LicenseException을 발생시킵니다.
2. 세션 생성 – Doconut은 적절한 포맷 뷰어(PDF, Word, DWG, …)를 선택하고 엔진을 GUID 토큰 아래 IMemoryCache에 저장합니다.
3. 보안 등록 – UnsafeMode = false를 사용하여 토큰을 secure-{token} 마커를 통해 호출자의 ASP.NET 세션에 바인딩합니다. 해당 브라우저 세션만 페이지를 요청할 수 있습니다.
4. 토큰 반환 – 클라이언트는 토큰을 받아 이후 모든 요청(/DocImage.axd?token=…)에 사용합니다.

기본 슬라이딩 만료 시간은 60분이며(DocOptions.TimeOut를 통해 구성 가능) 각 페이지 요청 시 시간이 초기화되어 유휴 세션이 자동으로 사라집니다.

---

4. 클라이언트 측에서 문서 렌더링

브라우저에서 엔드포인트를 호출하고 토큰을 받아 Doconut 위젯에 전달합니다:

fetch('/api/open', { method: 'POST' })
    .then(r => r.json())
    .then(d => {
        const token = d.token;
        objViewer.View(token);   // Doconut에서 제공하는 JavaScript 위젯
    });

위젯은 내부적으로 페이지, 썸네일, 검색 및 주석 요청을 발생시키며 모두 동일한 token를 포함합니다. 토큰이 서버 측 세션에 연결되어 있기 때문에 악의적인 사용자가 다른 사용자의 문서를 탈취할 수 없습니다.

---

5. 사용자가 뷰어를 떠나면 즉시 문서 닫기

대용량 PDF 또는 CAD 파일의 경우 렌더링 엔진을 즉시 해제해야 합니다. 서버 측 엔드포인트 또는 위젯의 “unload” 이벤트에서 CloseDocument를 호출하십시오.

// 서버 측 엔드포인트
app.MapPost("/api/close", (Viewer viewer, string token) =>
{
    viewer.CloseDocument(token);
    return Results.Ok();
});

// 위젯에서 직접 호출 (토큰을 백엔드에 노출하는 경우)
viewer.CloseDocument(token);

CloseDocument는 캐시에서 세션을 제거하고, 기반 문서 엔진을 폐기하며, secure-{token} 마커를 삭제하고, 접근 권한을 회수합니다. 슬라이딩 만료도 결국 동일하게 동작하지만 명시적인 닫기는 사용자가 작업을 마치는 즉시 메모리가 회수됨을 보장합니다.

---

6. 선택 사항: 서버에서 문서 변환

워크플로에서 업로드된 Word 파일을 PDF로 내보내야 하는 경우 Doconut 구성에서 Converter 플러그인을 활성화하십시오(문서 참조). 플러그인이 등록된 후 DocumentConverter를 주입하고 해당 ConvertAsync 메서드를 호출할 수 있습니다. 변환은 서버에서 실행되므로 웹 서버에 Office를 설치할 필요가 없습니다.

---

7. 엔터프라이즈 급 문서 관리를 위한 확장 고려사항

• 무상태 프론트엔드 – 뷰어 위젯은 문서 데이터를 보유하지 않으며 모든 무거운 작업은 서버에서 수행됩니다.
• 분산 캐시 – 다중 웹 팜 노드를 운영하는 경우 기본 인‑메모리 캐시를 Redis, NCache와 같은 분산 제공자로 교체하십시오. 미들웨어가 구성된 IMemoryCache에서 읽기 때문에 토큰‑세션 매핑은 그대로 작동합니다.
• 백그라운드 작업 – 백그라운드 워커에서 문서를 미리 열고 토큰을 캐시한 뒤 UI에 전달할 수 있습니다. 각 토큰은 세션당 한 번만 사용할 수 있으므로 재사용하려면 새로운 OpenDocumentAsync 호출이 필요합니다.

이러한 패턴을 통해 뷰어 로직을 다시 작성하지 않고도 단일 서버 인트라넷 포털에서 다중 지역 클라우드 서비스까지 확장 가능한 문서 관리 플랫폼을 구축할 수 있습니다.

---

8. 프로덕션 준비 구현을 위한 빠른 체크리스트

단계	작업
1	Program.cs에 Doconut 서비스를 등록 (라이선스 검증).
2	전용 브랜치에 Doconut 미들웨어 추가.
3	/api/open 엔드포인트를 노출하고 OpenDocumentAsync를 호출합니다.
4	클라이언트에서 반환된 토큰을 objViewer.View(token)에 전달합니다.
5	뷰어가 숨겨지거나 페이지가 언로드될 때 CloseDocument(token)를 호출합니다.
6	(선택) 서버 측 변환이 필요하면 ConverterPlugin를 활성화합니다.
7	(선택) 수평 확장을 위해 IMemoryCache를 분산 캐시로 교체합니다.

목록을 따라 하면 Doconut의 네이티브 .NET 뷰어를 기반으로 한 완전하고 보안적이며 고성능 문서 관리 흐름을 구축할 수 있습니다.

---