내장 온톨로지를 사용하는 오프라인 앱

내장 온톨로지(Embedded Ontology)는 앱이 선택한 온톨로지 데이터를 로컬에 동기화하여 네트워크 없이 사용할 수 있게 합니다. Embedded Ontology React 템플릿은 @palantir/lohi-ts와 PWA 구성을 제공하며 사용자는 동기화한 데이터를 오프라인에서 읽고 작업할 수 있습니다.

SuperRepo 미리보기의 로컬 seed 서버와는 다른 용도입니다. 이 앱은 실제 온톨로지 데이터를 기기에 저장하므로 오프라인에 필요한 범위와 기기 접근 통제를 함께 정해야 합니다.

선행 설정

Developer Console에서 Client-facing 앱을 만들고 온톨로지 및 객체 유형을 선택하여 SDK를 생성합니다. 웹사이트 하위 도메인과 리다이렉트 URL도 호스팅 절차에 맞춰 설정합니다.

WebAssembly CSP

내장 온톨로지는 WebAssembly를 실행합니다. Website Hosting > Advanced의 scriptSrc에 작은따옴표를 포함한 'wasm-unsafe-eval'을 추가하고 오른쪽 미리보기에서 반영을 확인합니다.

이 설정 없이 배포하면 앱 초기화가 실패합니다. 일반 JavaScript eval까지 모두 허용하는 별도 설정으로 확대하지 않습니다.

저장소 템플릿

Start developing > Bootstrap in Foundry에서 Embedded Ontology React를 선택하고 Generate repo를 실행합니다.

생성 저장소의 기반 저장소는 다음과 같습니다.

환경 설정

.env.development와 .env.production에 다음 공개 앱 설정을 채웁니다. 생성기가 기본값을 제공하며 생성 뒤 수동으로 바꿀 항목은 .env.production의 VITE_FOUNDRY_REDIRECT_URL입니다.

다음은 형식 설명용 가상 호스팅 주소입니다.

VITE_FOUNDRY_REDIRECT_URL=https://your-subdomain.your-enrollment.palantirfoundry.com/auth/callback

실제 주소로 바꾸고 Developer Console의 OAuth 리다이렉트 목록에도 같은 값을 추가합니다. Vite는 빌드 때 index.html의 메타 태그에 값을 넣고 src/infra/config.ts가 실행 시 읽습니다. 일반 설정을 위해 config.ts를 직접 고칠 필요는 없습니다.

오프라인 객체 선택

src/syncConfig.ts의 syncedObjectTypes는 초기에는 비어 있습니다. 실제 생성 SDK에서 가져온 유형을 넣어 오프라인 사용 범위를 정합니다.

import { Employee, Task } from "@your-app/sdk";
import type { SyncConfigParam } from "@palantir/lohi-ts";

export const syncedObjectTypes: SyncConfigParam[] = [Employee, Task];

패키지와 유형은 가상 예입니다. SyncConfigParam은 생성 유형 정의뿐 아니라 유형 API 이름 문자열 또는 필터링한 ObjectSetQuery를 받아 일부 데이터만 동기화할 수도 있습니다. 필요한 객체만 선택해야 최초 로드 시간과 기기 저장량을 줄일 수 있습니다.

src/main.tsx의 createAppLohiClient가 이 목록을 받습니다. src/router.tsx의 SyncProvider에는 같은 목록을 다시 넣지 않습니다. 동기화 뒤 전체 OSDK 캐시를 무효화하는 역할이기 때문입니다.

동기화와 온라인 전용 액션

템플릿의 SyncProvider는 mount 때 첫 동기화를 실행하고 성공할 때마다 OSDK 캐시를 무효화합니다. 기본 syncInterval은 10,000밀리초로 10초마다 배경 동기화를 수행합니다. 이 속성을 제거하면 mount와 사용자 요청 때만 동기화합니다.

src/Home.tsx의 SyncGate는 첫 동기화가 끝날 때까지 UI를 보류합니다. 직접 동기화하려면 src/infra/lohi/LohiContext.tsx의 useLohiClient를 사용합니다. 사용자가 동기화 상태 표시를 선택하는 흐름도 지원합니다.

기본 클라이언트는 Lohi입니다. @osdk/react 훅의 읽기와 쓰기는 로컬 캐시를 사용하며 쓰기를 낙관적으로 적용합니다. 특정 액션이 실제 Foundry에 즉시 도달해야 하면 해당 하위 컴포넌트를 StandardClientScope로 감싸고 src/infra/lohi/useOnlineAction.ts의 useOnlineAction을 사용합니다. 이 훅은 온라인 액션 성공 뒤 다시 동기화하고 캐시를 무효화합니다.

로컬 낙관적 변경을 실제 원격 액션의 확정 성공과 동일하게 표시하지 않도록 앱의 상태 표현을 정합니다. 템플릿의 세부 인터페이스는 생성 저장소 README 및 설치된 라이브러리 타입과 함께 사용합니다.

배포

VS Code 작업 공간이나 코드 저장소의 태그 기능으로 릴리스를 만듭니다.

로컬에서 실제 릴리스 버전을 선택하여 태그를 push하는 경로도 있습니다. 다음 1.0.0은 예제 릴리스 값입니다.

git tag 1.0.0 && git push origin tag 1.0.0

push하면 Code Repositories가 앱을 빌드하고 설정된 하위 도메인에 배포합니다. 자산 검사와 도메인 승인 등 호스팅 조건은 그대로 적용합니다.

PWA 설치와 오프라인 사용

배포한 앱을 지원 브라우저에서 열고 Install 또는 Add to Home Screen을 선택합니다. 데스크톱은 주소 표시줄 설치 아이콘이나 Cast, Save, and Share > Install Page as App... 메뉴를 사용할 수 있습니다.

모바일은 브라우저 메뉴의 Add to Home Screen을 사용합니다. 설치 후 앱 목록이나 홈 화면에서 열 수 있으며 네트워크가 없어도 이미 동기화한 데이터로 작업합니다. 연결이 복구되면 최신 데이터를 다시 동기화합니다.

오프라인에 있는 데이터는 syncedObjectTypes에 구성한 범위뿐입니다. 첫 동기화를 완료하지 않은 데이터를 네트워크 없이 새로 읽을 수는 없습니다.

선택 기능: Peering

기본 동기화는 설정한 유형의 모든 객체를 다시 읽습니다. Peering은 이전 동기화 이후의 차이만 가져와 반복 동기화 비용을 줄일 수 있습니다.

1. Ontology Manager에서 대상 객체 유형의 Capabilities를 엽니다.

2. Offline App Sync를 켭니다.

3. Datasources에서 Peering 객체 데이터베이스의 인덱싱이 성공할 때까지 기다립니다.

4. src/syncConfig.ts의 해당 유형에 설치된 lohi-ts SyncConfigParam이 제공하는 유형별 peering 옵션을 설정합니다. 일반 유형 배열만 두는 것과 peering 옵션을 활성화한 구성은 다릅니다.

유형별 옵션의 필드 이름과 값 형식은 설치된 lohi-ts 버전의 SyncConfigParam 정의에서 확인하고, 생성 저장소의 동기화 구성에 적용합니다.

문제 해결

CORS 오류는 개발 origin http://localhost:8080 및 실제 프로덕션 하위 도메인이 허용되어 있는지 확인합니다. Control Panel 권한이 없으면 관리자에게 요청합니다.

dev-dist 관련 빌드 오류가 나면 자동 생성된 해당 디렉터리만 제거하고 다시 생성할 수 있습니다. 이 경로는 템플릿 .gitignore에 포함합니다. 소스 디렉터리와 혼동하여 삭제하지 않습니다.

앱의 오프라인 동작을 확인할 때는 초기 동기화 이후 네트워크를 끊고 필요한 객체와 작업이 있는지, 연결 복구 후 동기화가 진행되는지 확인합니다. 아이콘과 시작 화면 같은 PWA 요소는 앱 요구에 맞춰 추가합니다.