ORVEN Studio
프로그램 시작 가이드

SYSTEM

빌드 대상과 준비물

구매 전과 다운로드 전에 OS별 실제 전달 가능 상태, 권한, 네트워크와 provider 계정을 먼저 확인합니다.

macOS 빌드 대상

Apple Silicon(M 시리즈) · 서명/공증 gate 필요

Windows 빌드 대상

Windows 10 22H2 / Windows 11 x64 · native gate 필요

초기 연결

라이선스 활성화와 업데이트 확인에 인터넷 필요

생성 비용

구매자 Atlas 계정에 별도 청구

• Intel Mac, 32비트 Windows, Windows on ARM 네이티브 실행은 현재 빌드 대상이 아닙니다.
• 이 웹 가이드는 OS별 패키지 연결이나 native release gate 통과 증거가 아닙니다. 주문 전에 실제 전달 가능 상태를 확인하세요.
• 로컬 UI는 브라우저에서 localhost로 열리지만, 외부 AI 생성 요청에는 네트워크가 필요합니다.
• 저장 공간은 원본·중간 산출물·결과물에 따라 계속 증가하므로 작업 전 여유 공간을 확인하세요.

PACKAGE

받아야 할 파일

정상 납품 ZIP에는 실행 런처뿐 아니라 manifest, 설치 문서, 보안 안내와 사용자 가이드가 함께 들어 있습니다.

• 공통: PACKAGE_MANIFEST.json, UPDATE_GUIDE.md, LOCAL_DELIVERY_GUIDE.md, ORVEN Studio User Guide.pdf
• Mac: ORVEN Studio.app, Start ORVEN.command, INSTALL_MAC.md, MAC_SECURITY_NOTICE.md
• Windows: Start ORVEN.cmd, INSTALL_WINDOWS.md, WINDOWS_SECURITY_NOTICE.md
• native release gate를 통과한 납품 artifact는 사전 빌드된 Next standalone, OS용 Node runtime, PyInstaller backend를 포함해야 합니다.

INTEGRITY

다운로드와 SHA-256 대조

다운로드 링크의 출처와 파일 해시를 함께 확인해야 손상·오배포 패키지를 걸러낼 수 있습니다.

1. 구매 메일에서 주문 ID, 대상 OS, 버전, 파일명, SHA-256을 확인합니다.
2. ZIP을 실행하기 전에 아래 OS 명령으로 해시를 계산합니다.
3. 문자 하나라도 다르면 삭제하고 다시 내려받습니다. 반복되면 실행하지 말고 지원팀에 전달합니다.

MAC

macOS 설치와 Gatekeeper

macOS native release gate를 통과한 Apple Silicon용 ZIP이 주문에 전달된 경우에만 압축을 풀고 ORVEN Studio.app을 실행합니다.

1. ZIP을 임의의 작업 폴더가 아닌 고정된 앱 보관 위치에 완전히 압축 해제합니다.
2. ORVEN Studio.app을 더블클릭합니다. 실행되면 브라우저에 로컬 주소가 자동으로 열립니다.
3. 보안 경고가 나오면 해시를 다시 확인하고 패키지의 MAC_SECURITY_NOTICE.md에 적힌 우클릭 > 열기 절차만 따릅니다.
4. 앱 실행이 실패할 때 Start ORVEN.command를 사용하고, 로그 폴더의 최신 파일을 지원팀에 전달합니다.

WINDOWS

Windows 설치와 SmartScreen

Windows native release gate와 운영 storage 연결을 통과한 ZIP이 주문에 전달된 경우에만 완전히 압축 해제한 뒤 Start ORVEN.cmd를 실행합니다.

1. 탐색기에서 ZIP을 우클릭하고 모두 압축 풀기를 선택합니다.
2. 압축 해제 폴더 안의 Start ORVEN.cmd를 더블클릭합니다. ZIP 미리보기 안에서 실행하지 마세요.
3. SmartScreen이 표시되면 파일 해시와 WINDOWS_SECURITY_NOTICE.md를 먼저 확인합니다.
4. 회사 PC에서 차단되면 보안 정책을 우회하지 말고 관리자에게 파일명·SHA-256·보안 안내 문서를 전달합니다.

LOCALHOST

첫 실행과 종료

런처는 사용 중이지 않은 로컬 포트에서 frontend와 backend를 시작하고 브라우저를 엽니다.

• 주소창이 localhost 또는 127.0.0.1인지 확인합니다. 외부 도메인에 API key를 입력하지 마세요.
• 브라우저 탭만 닫아도 백그라운드 프로세스가 남을 수 있습니다. 런처 창의 종료 안내를 따라 완전히 종료하세요.
• 빈 화면이면 브라우저 새로고침보다 먼저 런처 로그에서 frontend/backend 준비 메시지를 확인합니다.
• release gate를 통과한 납품 패키지의 첫 실행에서 npm install, next build, Python 설치가 시작되면 정상 artifact로 보지 않습니다.

ACTIVATION

라이선스 활성화

Prefs > License에서 구매 메일의 license key를 입력합니다. 라이선스 1개는 최대 2대 기기에서 활성화할 수 있습니다.

1. 인터넷 연결 상태에서 구매 메일의 key를 공백 없이 붙여 넣습니다.
2. 활성화 버튼을 한 번 누르고 상태가 Active로 바뀔 때까지 기다립니다.
3. 구매자 마스킹 이메일, License ID, machine hash 앞자리, 재검증 시점을 확인합니다.

• 서버에는 machine fingerprint 원본이 아니라 SHA-256 hash가 전송됩니다.
• activation은 사용자 데이터 폴더에 저장되며 앱 파일을 교체해도 보존하는 것이 정상입니다.
• 30일 재검증 시점이 지나면 온라인 상태에서 다시 확인하라는 안내가 표시될 수 있습니다.

API KEYS

구매자 API key 저장

Prefs > API Keys는 OpenAI, Gemini, Atlas 입력란을 제공하며 저장 후 값은 마스킹됩니다.

1. 현재 생성에 사용할 Atlas Cloud key를 provider 계정에서 발급합니다.
2. Atlas 입력란에 key를 넣고 입력한 key 저장을 누릅니다.
3. Configured 수가 늘고 마스킹된 값이 보이는지 확인합니다.
4. Create의 모델 목록에서 실제 사용할 모델이 연결됨으로 표시되는지 다시 확인합니다.

• macOS는 Keychain을 우선 사용하고 runtime/api_keys.enc에는 계정 index를 둡니다.
• Windows는 현재 Windows 사용자 계정에 묶인 DPAPI로 암호화합니다.
• ORVEN 내부 key는 포함되지 않으며 외부 AI API 비용은 구매자 계정에 청구됩니다.
• 연결·모델 확인은 저장된 key를 backend에서만 읽어 고정된 provider 조회 URL로 인증·모델 접근을 확인합니다. Atlas는 잔액 상태도 확인하며 이미지 생성 요청은 보내지 않습니다.

CURRENT ROUTING

현재 모델 연결의 실제 범위

설정 화면은 세 provider key를 저장하지만, 현재 공개 모델 카탈로그의 실행 경로는 모두 Atlas Cloud key를 요구합니다.

• OpenAI 또는 Gemini key만 저장해도 Configured 수는 증가하지만 현재 공개 모델을 실행할 준비가 됐다는 뜻은 아닙니다.
• 모델 선택 시 표시되는 연결 상태가 최종 기준입니다. 연결되지 않은 모델로 비용 승인을 진행하지 마세요.
• 모델명은 공급자 정책과 카탈로그 업데이트에 따라 달라질 수 있으므로 이 문서보다 앱의 live catalog를 우선합니다.

HOME

첫 실행 준비 보드

Home은 라이선스, API key, 첫 생성, 가이드 확인 상태를 보여주고 Create·Runs·Settings로 연결합니다.

• 수치가 비어 있으면 샘플 통계가 아니라 backend 연결 또는 실제 실행 기록 유무를 확인합니다.
• 오늘·이번 달 수치와 비용은 로컬 실행 기록을 기준으로 표시됩니다.
• 라이선스와 API key가 준비되지 않은 상태에서는 먼저 Settings로 이동하세요.

INPUT

원본 업로드와 작업 큐

Create는 한 번에 최대 10개 원본을 작업 큐에 올리고 순서를 조정할 수 있습니다.

1. 첫 검증은 정면·단일 제품·선명한 배경의 원본 1장으로 시작합니다.
2. 파일명이 겹치지 않게 정리하고 원본 색·부자재가 보이는 해상도를 사용합니다.
3. 여러 장을 올린 뒤 각 항목의 Inspector 설정을 개별 확인합니다.

INSPECTOR

Inspector 확인 순서

각 원본의 자동 분석 결과, 근거, 신뢰도와 preset을 검수한 뒤 작업 의도, 컷, 레퍼런스, 모델, 출력 설정을 확정합니다.

1. 자동 분류의 품목, 신뢰도, 근거와 확인 필요 필드를 먼저 봅니다.
2. 미분류 또는 낮은 신뢰도 값은 직접 선택하고 보존 영역·금지 변형을 확인합니다.
3. 필요하면 초기화, 다른 항목 복사 또는 전체 적용을 사용하고 최근 변경 audit를 확인합니다.
4. A/B컷·레퍼런스·모델·파이프라인·해상도·비율·개수·포맷을 최종 확인합니다.

GARMENT

품목 유형

Inspector는 9개 품목군과 확인 필요 상태를 구분하고, 확정한 분류를 실행용 상의·하의·아우터 범주와 보존 preset에 연결합니다.

상의군

셔츠 · 니트 · 티셔츠

하의군

팬츠 · 스커트

기타 품목군

아우터 · 드레스 · 셋업 · 액세서리

불확실

확인 필요 · 생성 전 수동 확정

• 셋업처럼 한 이미지에 여러 품목이 있으면 첫 배치에서 단일 품목으로 분리하는 편이 검수하기 쉽습니다.
• 목록에 없는 특수 품목은 임의로 확정하지 말고 소량 테스트 후 지원팀과 기준을 합의하세요.

CUT

A/B컷과 디테일 위치

A컷은 메인 셀렉션, B컷은 서브 셀렉션으로 사용하며 전체 전·후면과 부위별 디테일을 선택할 수 있습니다.

• 디테일 후보에는 전·후면 상단, 소매, 포켓, 안주머니, 허리, 밑단, 무릎, 원단 등이 있습니다.
• B컷은 실루엣 정리 여부를 별도로 설정할 수 있습니다.
• 디테일 위치가 원본에서 충분히 보이지 않으면 생성 결과가 제품 사실을 보완해 주는 것이 아니라 추정할 수 있습니다.

REFERENCE

레퍼런스와 보존 강도

레퍼런스는 원하는 구도·외곽 기준을 전달하지만 원본에 없는 제품 정보를 보증하지 않습니다.

• 유사는 원본 비율을 남기며 형태를 따라가고, 정밀은 외곽과 중심축을 더 강하게 맞춥니다.
• 대칭은 끔, 밸런스 정리, 엄격 정렬 중에서 선택합니다.
• 레퍼런스와 원본의 부자재·절개·기장이 다르면 실루엣보다 실제 원본의 제품 사실을 우선해 검수하세요.
• 레퍼런스 이미지의 사용 권한은 업로드한 사용자가 확인해야 합니다.

MODEL

모델과 처리 파이프라인

모델과 파이프라인은 수동 선택이며, 앱이 보여주는 연결 상태와 추가 비용·시간 안내를 함께 확인합니다.

• local + AI, 다단계, 색감 락, Nano Banana + Imagen 등 연결된 경로만 사용합니다.
• Photoshop + AI는 필요한 Adobe 환경 설정이 없으면 unavailable로 표시됩니다.
• 모델 표시 이름과 실제 provider 모델은 운영 카탈로그에서 재지정될 수 있습니다.
• 고가·다단계 경로가 항상 더 정확하다는 보장은 없습니다. 동일 원본 소량 비교 후 기준을 고정하세요.

OUTPUT

해상도·비율·개수·포맷

현재 UI는 1080p·2K·4K, 1:1·4:5·3:4·16:9·9:16, 항목당 1~4개 결과를 선택할 수 있습니다.

• 모든 모델이 선택값을 동일한 방식으로 네이티브 지원하는 것은 아닙니다. live catalog 설명을 확인하세요.
• 출력 개수를 늘리거나 다단계 파이프라인을 고르면 예상 비용과 시간이 증가합니다.
• PNG가 기본 결과 형식입니다. PSD 선택의 실제 동작은 내보내기 섹션을 반드시 확인하세요.

APPROVAL

실제 API 비용 승인

생성과 재생성 전에는 항목 수, 모델 구성, 예상 비용, 예상 시간을 보여주는 확인 창이 열립니다.

1. 호출 범위와 항목 수가 의도와 같은지 확인합니다.
2. 각 모델과 파이프라인의 예상 비용·시간을 확인합니다.
3. 실제 외부 API 호출 안내를 읽고 승인 체크를 해야 실행 버튼이 열립니다.

RUN

생성 진행과 중단 대응

실행 후 항목별 queued, running, done, failed 상태와 진행 단계·남은 시간 추정을 확인합니다.

• 실행 중 브라우저를 닫기보다 결과 또는 실패 상태가 확정될 때까지 유지하세요.
• 네트워크가 끊기면 즉시 새 실행을 만들지 말고 Runs에서 기존 실행이 계속 진행 중인지 확인합니다.
• 동일 요청을 연속 승인하면 provider 비용이 중복 발생할 수 있습니다.
• 실패 메시지는 key 형태 문자열을 redaction하지만 지원 문의 전 로그에 민감 정보가 없는지 다시 확인하세요.

REVIEW

원본/결과 비교와 검수

Review는 원본·결과 슬라이더, 품질 지표, 승인·거부, 다운로드, 라이트박스를 제공합니다.

1. 전체 실루엣과 기장·중심축을 먼저 비교합니다.
2. 카라·후드·포켓·지퍼·단추·절개·소매·밑단을 확대 확인합니다.
3. 원단 조직, 색, 프린트, 로고, 부자재 수와 위치를 원본과 대조합니다.
4. 검수 기준을 통과한 결과만 승인하고, 근거 없이 애매한 결과는 거부하거나 재생성합니다.

RETRY

거부와 재생성

거부는 review state를 기록하고, 재생성은 선택 항목에 대해 새 외부 API 호출을 승인받아 실행합니다.

• 재생성 전 실패 원인을 원본 품질, 품목·컷 설정, 레퍼런스 충돌, provider 연결로 나눠 확인합니다.
• 설정을 바꾸지 않은 반복 재생성은 비용만 늘릴 수 있습니다.
• 재생성도 비용 승인 체크가 필요하며 이전 결과를 자동으로 환불하지 않습니다.

EXPORT

PNG와 PSD-ready 내보내기

승인 여부와 별개로 완료된 결과를 PNG로 내려받을 수 있으며, 오늘 갤러리에서도 다시 받을 수 있습니다.

• PNG 선택은 생성된 결과 파일을 PNG 이름으로 내려받습니다.
• PSD 선택은 현재 네이티브 .psd가 아니라 2000×2000으로 평탄화한 *_psd-ready_2000x2000.png를 만듭니다.
• 레이어, 마스크, 스마트 오브젝트가 필요한 작업은 현재 결과를 Photoshop에서 별도로 구성해야 합니다.
• 결과 metadata에는 license id/hash 등 추적 정보가 기록될 수 있습니다.

RUNS

실행 기록과 로그 내보내기

Runs는 최근 실행의 상태·모델·비용·시간을 검색·필터하고 CSV 또는 JSON으로 내보낼 수 있습니다.

• 실패만, 고비용, 긴 작업 필터로 문제 실행을 먼저 확인합니다.
• 표시되는 보관 일수는 UI 조회 정책이며 원본·결과 파일을 실제로 삭제하는 기능이 아닙니다.
• 지원 문의에는 실행 시각, 작업명, 모델, 상태, 정리된 오류 메시지를 포함하고 API key 원문은 보내지 마세요.

STORAGE

영구 데이터 위치

release gate를 통과한 납품 패키지 계약은 앱 파일과 사용자 데이터를 분리하고, Prefs > Storage에서 디스크·영구 데이터·캐시 현황을 확인하게 구성합니다.

macOS

~/ORVEN Studio Data

Windows

%LOCALAPPDATA%\ORVEN Studio

runtime

activation, API key index/store, 업로드, 실행 상태

outputs

생성 결과와 실행별 산출물

• Prefs > Storage는 경로, 디스크 여유 공간, 영구 데이터·캐시 용량, 카테고리별 항목과 최근 정리 시점을 표시합니다.
• 일반 사용자용 폴더 열기와 데이터 위치 이동 버튼은 아직 제공하지 않습니다.
• 개발용 소스 실행 경로와 구매자 패키지의 외부 데이터 경로는 다를 수 있습니다.

CACHE

캐시와 보존 데이터 구분

Prefs > Storage는 재생성 가능한 캐시만 dry-run으로 계산하고 명시적 확인 뒤 allowlist 범위에서 정리합니다.

• 오늘 갤러리는 다운로드 편의를 위한 복사본과 썸네일을 만들고 지난 날짜 캐시를 정리합니다.
• 원본 업로드, 실행 결과, 작업 기록은 별도 영구 데이터로 남을 수 있습니다.
• 완료 전 Create 초안은 브라우저 IndexedDB에 저장되며 사용자 데이터 폴더 백업만으로 복구된다고 보장할 수 없습니다.
• 캐시 크기와 후보 수·예상 확보 용량을 미리 확인한 뒤 캐시 정리를 실행할 수 있습니다.
• 업로드 원본, 결과, 상태, API key와 라이선스는 캐시 정리 대상에서 제외됩니다.

BACKUP

백업과 격리 복원

Prefs > Storage에서 업로드·결과·상태를 SHA-256 manifest와 함께 백업하고, 원본 live 데이터를 덮어쓰지 않는 새 격리 위치로 복원할 수 있습니다.

1. 진행 중 실행이 없는지 확인하고 필요한 결과를 먼저 다운로드합니다.
2. Prefs > Storage에서 사용자 데이터 백업을 생성하고 파일 수와 manifest를 확인합니다.
3. API key, 라이선스, 캐시와 provider 작업 파일이 백업에서 제외된다는 안내를 확인합니다.
4. 복원 검증은 최신 백업 격리 복원을 실행해 새 위치와 SHA 검증 결과를 확인합니다.
5. 미완료 Create 초안은 브라우저 저장소에 있을 수 있으므로 중요한 설정과 원본을 별도로 보관합니다.

MOVE

데이터 위치 변경과 PC 이동

Settings에는 데이터 위치 이동 기능이 없으며, 다른 PC 활성화와 데이터 이전은 별도 작업입니다.

• 새 PC에서는 먼저 해당 OS 패키지와 라이선스 활성화 가능 대수를 확인합니다.
• 앱 실행 중 폴더를 옮기거나 junction/symlink를 임의로 만들지 마세요.
• 운영 환경은 ORVEN_USER_DATA_DIR로 외부 위치를 지정할 수 있지만 일반 사용자 UI로 제공되지 않으므로 지원팀 안내 없이 변경하지 않습니다.
• macOS Keychain과 Windows DPAPI key는 단순 폴더 복사로 다른 기기에 이전되지 않습니다. 새 기기에서 key를 다시 저장합니다.

DELETE

결과·원본·전체 데이터 삭제

현재 프로젝트 휴지통이나 항목별 영구 삭제 UI가 없으므로 파일 삭제는 앱 종료 후 수동으로 수행합니다.

• 삭제 전 필요한 결과와 실행 로그를 내보내고 사용자 데이터 폴더를 백업합니다.
• 특정 실행 폴더를 구조를 모른 채 지우면 Runs와 결과 경로가 불일치할 수 있습니다.
• 전체 삭제는 앱 종료 후 OS 사용자 데이터 폴더를 제거하는 방식이며 되돌릴 수 없습니다.
• Mac Keychain의 provider key는 데이터 폴더와 별도로 남을 수 있습니다. Prefs > API Keys에서 provider별 저장 key를 삭제할 수 있지만 환경변수 key는 별도 회전이 필요합니다.

UPDATE

수동 업데이트

Prefs > Updates는 활성 라이선스로 최신 manifest, 버전, 다운로드 URL, SHA-256을 확인합니다.

1. 진행 중 실행을 끝내고 사용자 데이터 폴더를 수동 백업합니다.
2. Prefs > Updates에서 업데이트 확인을 실행합니다.
3. 최신 버전, 필수 여부, 릴리스 일자, SHA-256을 확인한 뒤 패키지를 받습니다.
4. 새 ZIP의 SHA-256을 직접 대조하고 기존 앱 파일만 교체합니다.
5. activation, API key 저장소, uploads, outputs가 있는 사용자 데이터 폴더는 삭제하지 않습니다.

UNINSTALL

삭제와 재설치

프로그램 파일 제거와 사용자 데이터 제거를 분리해야 재설치 시 작업을 보존할지 완전히 삭제할지 선택할 수 있습니다.

1. 앱과 런처를 종료하고 백그라운드 프로세스가 없는지 확인합니다.
2. 재설치 목적이면 앱 패키지만 제거하고 사용자 데이터 폴더는 보존합니다.
3. 완전 삭제 목적이면 결과 백업 후 앱 패키지와 사용자 데이터 폴더를 각각 제거합니다.
4. provider 계정에서 사용하지 않을 API key를 폐기하거나 회전합니다. Mac Keychain 잔여 항목은 별도 확인합니다.
5. 새 패키지를 설치하면 Settings에서 라이선스·API key·저장 경로를 다시 확인합니다.