클라우드 버전과 로컬 캐시

로그인된 프로덕션 Web 환경에서는 클라우드 프로젝트가 권위 있는 공식 원본(Authoritative version)이며, 사용자 기기는 계속 편집이 가능한 로컬 캐시를 보관합니다. 데스크톱 앱은 여기에 한 단계가 더 추가됩니다. 하나의 프로젝트가 디스크 상의 폴더 하나와 1:1로 대응하며, 원고 본문, 이미지, 대화 세션, 히스토리, 설계 파일이 해당 폴더 안에 저장되고 SQLite 데이터베이스가 로컬의 진정한 원천 데이터로 작동합니다.

클라우드에 연결된 프로젝트를 열 때 시스템은 다음 순서로 검증을 실행합니다.

• 먼저 프로젝트 목록의 요약 정보와 버전을 대조합니다. 클라우드에 변경이 없고 로컬에도 대기 중인 편집이 없다면 전체 다운로드를 건너뛰고 즉시 집필을 시작합니다.
• 클라우드에 최신 업데이트가 있고 로컬 상태가 깨끗하다면(대기 중인 수정 없음), 최신 원고를 다운로드하여 로컬 캐시를 갱신합니다. 데스크톱 앱은 이어 설계 파일과 파생 데이터를 디스크에 다시 씁니다.
• 로컬에 아직 업로드되지 않은 편집 내용이 남아 있고(디바운스 350ms 동안 아직 디스크에 기록되지 않은 편집 포함) 클라우드에도 새로운 버전이 생성되어 있다면 충돌 상태로 진입하며 양측 복사본을 모두 안전하게 보존합니다.

모든 편집은 항상 로컬 기기에 먼저 안전하게 저장된 후 업로드 대기열에 들어갑니다. 일시적인 네트워크 오류가 발생하더라도 이미 로컬 디스크에 기록된 수정을 되돌리지 않으며, 인터넷 연결이 복구되면 자동으로 업로드를 재시도합니다. 업로드가 진행되는 도중 본문을 계속 수정하더라도 재시도 시에는 가장 최신의 원고를 전송하므로 과거의 구형 초안이 최신 작업을 덮어쓰지 않습니다.

• 상단 바에 항상 하나의 상태가 명확하게 표시됩니다(Synced / Syncing / Offline / Sync failed / Paused / Conflict: 동기화 완료 / 동기화 중 / 오프라인 / 동기화 실패 / 일시정지 / 충돌 발생). 클라우드 연결에 실패하면 이 상태 표시만 바뀔 뿐 로컬 저장이 성공했다는 사실 자체는 변하지 않습니다.
• 열려 있는 연결 프로젝트는 창이 다시 포커스를 받을 때와 매 60초 요약 하트비트를 통해 동기화 상태를 조정합니다. 백그라운드 탭에서는 타이머가 작동하지 않으며 다른 프로젝트로 전환하거나 닫으면 즉시 정지합니다. 하트비트가 타이핑 중인 원고를 몰래 바꿔치기하지 않습니다.
• 클라우드 AI 작업을 시작하기 전에 클라이언트는 먼저 동기화 대기열을 완전히 비우고 버전 일치 여부를 검증합니다. 불일치가 감지되면 구버전 데이터를 바탕으로 실행하지 않고 작업을 명확히 중단합니다.

클라우드로 업로드할 때 본문과 자료에 포함된 긴 data-URL 이미지는 내용 기반 주소 지정(Content-addressed) Blob 데이터로 자동 분할됩니다. 동일한 이미지는 전체 클라우드에 단 한 번만 저장되고 한 번만 전송되며, 프로젝트 JSON에는 가벼운 참조 링크만 유지됩니다. 프로젝트를 열고 정합성을 맞출 때 이 참조 링크로부터 이미지를 복원하여 로컬 캐시에 전달합니다. 처음으로 프로젝트를 클라우드에 올릴 때도 동일한 경로를 거칩니다. 이미지 업로드가 완료되지 못하면 방금 생성된 클라우드 프로젝트는 휴지통으로 이동하고 로컬 링크를 맺지 않으므로 불완전한 미완성 프로젝트가 남지 않습니다.

• 다운로드할 수 없는 이미지 참조는 임의로 삭제되지 않고 동기화 오류 상태를 붙인 채 원고 안에 그대로 유지됩니다.
• 단일 이미지의 원시 크기가 20MB를 초과하거나 이미지를 분리한 후에도 본문 크기가 32MB를 초과하는 경우 오류로 표시되며 동일한 콘텐츠를 무한 반복 재전송하지 않습니다. 이런 이미지는 크기를 줄이거나 분할하시기 바랍니다.

오프라인 상태에서도 자유롭게 집필을 계속할 수 있습니다. 편집 내용은 로컬에 즉시 저장되고 대기열에 쌓였다가 인터넷이 연결되면 자동으로 업로드됩니다. 클라우드 프로젝트가 삭제된 경우(목록 요약에 없거나 404 반환), 로컬 링크만 제거될 뿐 프로젝트 자체는 사용자 기기에 안전하게 보존됩니다.

• 동기화는 필드 단위의 3방향 자동 병합이 아닌 전체 콘텐츠 버전 대조 방식으로 처리됩니다. 그렇기 때문에 충돌 발생 시 시스템이 임의로 자동 병합하지 않고 양측 버전을 모두 보존하는 방식을 취합니다.
• 동기화 오류가 발생했을 때는 브라우저 페이지와 로컬 프로젝트를 그대로 유지하고 절대 사이트 데이터를 삭제하지 마십시오. 반복되는 실패는 상단에 구체적인 사유와 함께 "Sync failed"(동기화 실패)로 계속 표시됩니다.
• 기기를 변경할 때 가장 먼저 해야 할 일은 브라우저 스토리지를 복사하는 것이 아니라 .quill.json 프로젝트 팩을 내보내는 것입니다.

충돌 발생 시 내용 복구 방법은 충돌 복사본 문서를, 백업 및 마이그레이션은 프로젝트 팩 내보내기 및 가져오기 문서를 참고하시기 바랍니다.