NAS同期

一言でいうと

sync は agent-based ストレージ（LOCAL / NETWORK_DRIVE）上のファイルと、Astar 側のドキュメントツリー・全文検索インデックスとの同期状態を管理するモジュール。WebSocket の接続・認証・メッセージルーティングそのものは core/agent が持ち、sync はその上で「どのドキュメントがどこまで同期済みか」というドメイン状態（SCANNING → INDEXING → COMPLETE のフェーズ遷移、進捗、コンフリクト）を扱う。Go agent（Go agent と CLI）はこのモジュールの直接の相手方で、NAS 上のファイルシステムを WebSocket 越しにスキャンして Astar backend へストリーミングする。

主要ドメイン概念

Backend 構造

• api/controller/: DocumentSyncController（ワークスペース単位の同期ステータス取得）
• domain/service/: DocumentSyncService（ドキュメント単位の同期ステータス CRUD — ローカル変更記録・クラウド変更記録・同期完了マーク）、SyncProgressService（SyncPhase の遷移管理、スキャン/インデックス進捗の集計、SSE 配信元）、StorageDataMigrationService（ストレージモード移行時のデータ移行）
• domain/model/: SyncOperation・SyncState・DocumentSyncStatus・MigrationModels
• domain/port/: SyncProgressPort

WebSocket メッセージ経路（core/agent との境界）

Go agent との WebSocket 接続・認証・メッセージのルーティングは core/sync ではなく core/agent/infrastructure/websocket/ が持つ（AgentWebSocketHandler・AgentRequestRouter・FileEventRouter・AgentMessages）。エージェントがファイルチャンクを送ってくると FileEventRouter がそれを解釈し、sync の SyncProgressService / DocumentSyncService を呼び出してドメイン状態を更新する、という分担。「同期まわりのバグ」を追うときは WebSocket 層（core/agent）とドメイン状態層（core/sync）のどちらの問題かをまず切り分けること。

Frontend 構造

app/modules/sync/ はデバイス接続のセットアップ UI と同期状態表示を持つ。

• components/: DeviceConnectDialog.vue / DeviceConnectButton.vue（新規デバイス接続の入口 UI）、QuickDeviceSetupCard.vue、NetworkDriveSetupWizard.vue + network-drive/（Docker/SSH 経由のセットアップ手順を段階的に表示）、LocalModeSetupDialog.vue、StorageSetupDialog.vue、SyncStatusBadge.vue、AiRuntimeConnectDialog.vue / AiRuntimeConnectPanel.vue（AI ランタイムをデバイス上で動かす接続）
• composables/: useSyncStatuses（ワークスペース単位の同期ステータス購読）、useSyncProgress（進捗 SSE の購読とグローバル状態）、useCurrentStorageMode、useQuickLocalDeviceSetup、useRegistrationCodeSetup
• repositories/: SyncRepository

他モジュールとの辺

• storage: デバイスそのもの（StorageDevice / StorageDeviceRoot）の CRUD・接続状態管理は storage モジュールの責務。sync はそのデバイス上のファイルの同期状態のみを扱う
• agent: WebSocket ハンドラ・メッセージルーティングは core/agent が持つ（上記参照）
• editor: 同期完了したファイルはドキュメントツリー（editor）のノードとして反映される
• search: 同期でインデックスフェーズに入ったドキュメントは全文検索インデックスに反映される