# クラウド版とローカルキャッシュ

> マスターデータの所在、保存とアップロードの順序、画像のクラウド保存、未ログイン時に利用可能な機能を解説します。

Source: https://loomworld.ai/ja/docs/sync-model

## 正本（マスター）とキャッシュの役割

ログイン状態のWeb版本番環境において、クラウドプロジェクトが正式な正本（マスター）となり、お使いの端末には快適な執筆とオフライン作業のためのローカルキャッシュが保持されます。デスクトップ版ではさらに一歩進み、1つのプロジェクトがディスク上の独立したフォルダとして管理されます（本文下書き、添付画像、対話履歴、バージョン履歴、設計アウトラインを内包）。フォルダ内のローカルSQLiteデータベースが、その端末における正規のローカル正本となります。

クラウド連携されたプロジェクトを開く際、以下の検証シーケンスが実行されます：

- まずプロジェクト一覧のサマリー情報とバージョンを比較します。クラウド側に更新がなく、ローカルにも保留中の変更がない場合は、全量ダウンロードを行わず即座に執筆を開始できます。
- クラウドの方が新しく、ローカルに未保存の変更がない場合：最新データを全量プルしてローカルキャッシュを上書きします。デスクトップ版では設計ファイルとメモリ上の派生データも同期して再構築されます。
- ローカルに未送信の変更が存在し（350msのデバウンス待機中を含む）、同時にクラウド側のバージョンも進んでいた場合：並行編集による競合と判定され、双方のデータを保護する競合コピー処理が行われます。

## ローカル保存とクラウド同期の順序

すべての編集内容はまずローカルストレージに確実に書き込まれ、その後にクラウド同期キューへ登録されます。通信が切断されても、ディスクに保存済みの文章が失われることはありません。ネットワークが回復した際に自動で再試行されます。アップロード処理の実行中に執筆を続けた場合でも、再試行時には最新のテキストを含むデータが送信され、古い下書きで現在の作業が巻き戻されることはありません。

- トップバーには現在の同期状態が常に明示されます（Synced / Syncing / Offline / Sync failed / Paused / Conflict）。クラウド側で一時的なエラーが発生しても状態表示が変わるだけであり、ローカルでの保存成功という事実は揺らぎません。
- 開いている連携プロジェクトは、ウィンドウのフォーカス復帰時および60秒間隔のハートビートによって自動照合されます。バックグラウンドのタブではタイマーが停止し、別プロジェクトへの切り替えやプロジェクトを閉じた際も即座に停止します。ハートビートによって入力中の原稿がカーソルの下で勝手にすり替わることはありません。
- クラウドAIタスクを開始する前、クライアントは同期キューをすべてフラッシュし、バージョンの一致を厳密にチェックします。不整合がある場合は、古いデータに基づいたAI処理を避けるため、タスクの実行を明示的にブロックします。

## 画像データのアップロード仕様

クラウドへの送信時、本文やカード内の長いDataURL画像はコンテンツハッシュに基づく独立したBlobデータへ自動分離されます。クラウド全体で同一画像は1件のみ保存・アップロードされ、プロジェクトJSON内には軽量な参照キーのみが保持されます。プロジェクトを開く際や同期照合時には、これらの参照から画像を復元したうえでローカルキャッシュへ渡します。初回のクラウド作成時も同じ手順を踏みます。画像のアップロードが完了しなかった場合、作成途中だったクラウドプロジェクトは自動的にゴミ箱へ移動され、中途半端な不完全プロジェクトが残るのを防ぎます。

- 何らかの理由で画像が取得できなかった参照データは、同期エラーのタグを付与したうえで本文内にそのまま維持されます。画像を勝手に削除することはありません。
- 単体で20MBを超える生バイナリ画像、または画像分離後もドラフトサイズが32MBを超える場合はエラーとして記録され、無駄なアップロードのループを防止します。該当する画像は事前に圧縮または分割してください。

## 未ログインおよびオフライン時の挙動

未ログイン状態では、クラウド同期パイプライン全体が自動的にスキップされます（プル、プッシュ、エラー通知のいずれも行われません）。ブラウザのローカルプロジェクトは当該ブラウザの内部ストレージに完全に依存します。ブラウザデータの消去、ブラウザの変更、端末の移行時には引き継がれませんので、必ず定期的にプロジェクトパックをエクスポートしてください。なお、デスクトップ版のプロジェクトフォルダはアカウントから完全に独立しており、フォルダごとコピーすれば全データをそのまま移動できます。

オフライン時でも普段どおりに執筆を継続できます。編集内容はローカルデータベースに正常保存されて送信キューに入り、再接続時に自動でアップロードされます。クラウドプロジェクトがリモート側で完全に削除された場合（一覧サマリーに存在しないか404応答時）、ローカルの連携リンクは安全に解除され、プロジェクト自体はローカル端末上にそのまま残ります。

## 制限事項とトラブルシューティング

- 本システムの同期はプロジェクト全体の完全バージョン照合を採用しており、フィールド単位の3方向自動マージは行いません。そのため競合が発生した際も勝手な統合を行わず、双方のバージョンを確実に個別保存します。
- 同期エラーが発生した場合は、ブラウザのタブとローカルプロジェクトをそのまま保持し、ブラウザデータを消去しないでください。再試行に失敗した場合も「Sync failed」の理由が明示されます。
- PCや環境を移行する際の最初の操作は、ブラウザの内部ストレージを漁ることではなく、.quill.json プロジェクトパックをエクスポートすることです。

競合発生時の復旧手順は [競合コピー](https://loomworld.ai/ja/docs/conflict-copies)、バックアップとデータ移行は [プロジェクトパックのエクスポートとインポート](https://loomworld.ai/ja/docs/export-quill) を参照してください。