Skip to content

Latest commit

 

History

History
499 lines (387 loc) · 15.3 KB

REQUIREMENTS.md

File metadata and controls

499 lines (387 loc) · 15.3 KB

file-funeral 要件定義書

プロジェクト概要

コンセプト

file-funeralは、ローカルファイルをクラウドストレージにバックアップ・同期するデスクトップアプリケーションです。複数PC間でのファイル共有を主な用途とし、軽量で高速な動作を目指します。

主な機能

  • ローカルファイルのクラウドへのアップロード/バックアップ
  • クラウドからローカルへのダウンロード
  • ローカルとクラウド間の双方向同期
  • ファイル/フォルダのリスト表示と同期状態の可視化

技術スタック

バックエンド

  • フレームワーク: Tauri v2
  • 言語: Rust
  • 非同期ランタイム: Tokio
  • クラウドSDK:
    • v1.0: aws-sdk-s3
    • v2.0+: S3互換、GCS SDK等
  • Tauriプラグイン: tauri-plugin-fs(ファイルシステムアクセス)

フロントエンド

  • ビルドツール: Vite 7
  • フレームワーク: React 19
  • 言語: TypeScript 5.9

認証情報管理

  • keyring クレート(OS標準キーチェーン)

機能要件

1. 同期機能

1.1 同期の基本仕様

  • 同期方向: 双方向同期(ローカル ↔ クラウド)
  • 主な用途: 複数PC間でのファイル共有

1.2 同期タイミング

  • アプリ起動時に自動同期
  • ユーザーが「同期」ボタンを押したとき
  • (オプション)アプリ終了時に自動同期

1.3 競合解決

  • 方式: 両方保存方式(Dropbox方式)
  • 動作:
    • 競合検知時、両方のファイルを保存
    • クラウド版: filename.txt
    • ローカル版: filename (PC名's conflicted copy YYYY-MM-DD).txt
    • 通知で競合発生を知らせる

1.4 削除の扱い

  • v1.0 (MVP): 削除を同期(完全同期)
    • 一方で削除されたファイルは、他方でも削除
  • v2.0: ソフト削除(ゴミ箱方式)
    • 削除されたファイルにフラグを付けてクラウドに保持
    • 一定期間後に自動削除
    • ユーザーはゴミ箱から復元可能

1.5 同期対象の選択

  • v1.0 (MVP): 1つのフォルダ全体を同期
    • ユーザーが指定したフォルダ配下すべてを同期
  • v1.5: 除外パターン機能
    • .gitignore方式で除外ファイル/フォルダを指定
  • v2.0: 複数フォルダ選択機能
    • ユーザーが複数のフォルダを選択して同期

1.6 初回同期

  • 方式: マージ方式
  • 動作:
    • クラウドからすべてのファイルをダウンロード
    • ローカルの既存ファイルとの競合は両方保存
    • ローカルの新しいファイルは次回同期でアップロード

2. ファイル管理

2.1 フォルダ構造

  • ローカルのフォルダ構造を完全に保持
  • S3のキー(パス)として保存
    • 例: Work/project1/document.txt

2.2 メタデータ

保持するメタデータ:

  • ファイル名
  • ファイルサイズ
  • 更新日時(modified time)
  • ETag/ハッシュ値(ファイルの同一性確認用)

保持しないメタデータ:

  • 作成日時
  • アクセス権限(パーミッション)
  • 所有者情報
  • 拡張属性

2.3 同期状態の表示

2.3.1 ステータスの種類

HOME画面では各ファイルに以下の8種類のステータスを表示する:

ステータス アイコン 色 説明
同期済み ✓ 緑 (#22c55e) ローカルとクラウドが一致
同期中 ⏳ 青 (#3b82f6) アップロード/ダウンロード中
アップロード待ち ⬆️ オレンジ (#f59e0b) ローカルが新しい、次回同期でアップロード
ダウンロード待ち ⬇️ オレンジ (#f59e0b) クラウドが新しい、次回同期でダウンロード
競合 ⚠️ 黄 (#eab308) 両方で変更あり、両方保存される
エラー ❌ 赤 (#ef4444) 同期失敗
除外 🚫 グレー (#9ca3af) 同期対象外(デフォルトで表示)
削除待ち 🗑️ グレー (#6b7280) ローカルで削除済み、次回同期でクラウドからも削除
2.3.2 判定条件

各ステータスの判定ロジック:

✓ 同期済み:

  • ローカルとクラウド両方に存在
  • ETag/ハッシュ値が一致

⏳ 同期中:

  • 現在アップロード/ダウンロード処理が実行中

⬆️ アップロード待ち:

  • パターンA: ローカルのみ存在(新規作成ファイル)
  • パターンB: 両方に存在し、以下のいずれかを満たす:
    • ローカルのETag/ハッシュ値がクラウドと異なる
    • ローカルの更新日時がクラウドより新しい
    • ローカルの更新日時が最終同期時刻より新しい

⬇️ ダウンロード待ち:

  • パターンA: クラウドのみ存在(他のPCで追加されたファイル)
  • パターンB: 両方に存在し、以下のいずれかを満たす:
    • クラウドのETag/ハッシュ値がローカルと異なる
    • クラウドの更新日時がローカルより新しい
    • クラウドの更新日時が最終同期時刻より新しい

⚠️ 競合:

  • 両方に存在
  • ローカルとクラウドのETag/ハッシュ値が異なる
  • ローカルの更新日時が最終同期時刻より新しい
  • クラウドの更新日時が最終同期時刻より新しい

❌ エラー:

  • 同期処理が失敗した(ネットワークエラー、権限エラー、ファイルロック等)

🚫 除外:

  • 除外パターンに一致(.DS_Store、*.tmp等、2.5節参照)

🗑️ 削除待ち:

  • ローカルで削除されたが、クラウドにまだ存在
  • 次回同期時にクラウドからも削除される
2.3.3 ステータスの優先順位

複数の条件が同時に成立する場合の表示優先順位(上から優先):

  1. ❌ エラー(問題があれば必ず表示)
  2. ⏳ 同期中(処理中は他の状態より優先)
  3. ⚠️ 競合(ユーザーの注意が必要)
  4. 🗑️ 削除待ち(削除操作は重要)
  5. 🚫 除外(同期対象外を明示)
  6. ⬆️ アップロード待ち
  7. ⬇️ ダウンロード待ち
  8. ✓ 同期済み(デフォルト、すべて正常)
2.3.4 UI表示仕様

基本表示:

  • アイコン + ファイル名の形式
  • アイコンはファイル名の左側に配置
  • 競合(⚠️)とエラー(❌)は背景色も変更:
    • 競合: 薄黄 (#fef9c3)
    • エラー: 薄赤 (#fee2e2)

プログレスバー(⏳ 同期中のみ):

  • 表示条件: ファイルサイズが100MB以上
  • 表示内容:
    ⏳ document.txt ▓▓▓▓▓▓▓▓░░░░ 65% (3.2 MB/s, 残り15秒)
    
    • プログレスバー(0-100%)
    • 転送速度(MB/s)
    • 残り時間(秒)
  • 100MB未満: 単に「⏳ 同期中」のみ表示

特殊表示:

🗑️ 削除待ち:

  • テキスト色: グレー (#9ca3af)
  • 取り消し線: あり
  • ホバー時: 「復元」ボタンを表示

🚫 除外:

  • テキスト色: グレー (#d1d5db)
  • フォントサイズ: 小さめ(90%)
  • デフォルトで表示(設定で非表示化可能)

ツールチップ(ホバー時の詳細情報):

各ステータスにカーソルを合わせた時に詳細を表示:

✓ 同期済み
→ ローカルとクラウドが一致しています
  最終同期: 2025-12-21 14:30

⬆️ アップロード待ち
→ ローカルが新しいファイルです
  ローカル: 2025-12-21 15:00
  クラウド: 2025-12-21 10:00
  次回同期でアップロードされます

⬇️ ダウンロード待ち
→ クラウドが新しいファイルです
  ローカル: 2025-12-21 10:00
  クラウド: 2025-12-21 15:00
  次回同期でダウンロードされます

⚠️ 競合
→ 両方で異なる変更が行われています
  ローカル: 2025-12-21 15:00
  クラウド: 2025-12-21 14:00
  同期時に両方保存されます

❌ エラー
→ 同期に失敗しました
  エラー内容: [具体的なエラーメッセージ]
  「再試行」ボタンで再度同期を試みる

🚫 除外
→ 同期対象外のファイルです
  除外パターン: *.tmp

🗑️ 削除待ち
→ ローカルで削除されました
  削除日時: 2025-12-21 14:00
  「復元」で取り消せます
2.3.5 メタデータ管理

上記の判定を実現するため、各ファイルごとに以下のメタデータをローカルのSQLite DBに記録:

struct FileMetadata {
    path: String,                           // ファイルパス
    size: u64,                              // ファイルサイズ
    last_modified: DateTime<Utc>,          // 更新日時
    etag: String,                           // ETag/ハッシュ値(ファイル同一性確認用)
    last_synced_at: Option<DateTime<Utc>>, // 最終同期時刻(競合判定に使用)
    status: FileStatus,                     // 現在のステータス
}

記録タイミング:

  • 同期成功時: last_synced_atを更新
  • ファイル変更検知時: last_modified、etagを更新
  • ステータス変更時: statusを更新

2.4 ファイルサイズ制限

  • v1.0 (MVP): 最大5GB
  • 100MB以上のファイル:
    • プログレスバーを表示
    • 転送速度を表示(例: 5.2 MB/s)
    • 残り時間を表示(例: 残り2分30秒)
  • 将来: マルチパートアップロードで制限緩和

2.5 除外ファイル

デフォルトで以下を除外:

  • .DS_Store (macOS)
  • Thumbs.db (Windows)
  • desktop.ini (Windows)
  • *.tmp
  • *.swp

2.6 特殊ファイル

  • v1.0 (MVP): シンボリックリンク、ハードリンク等は無視(警告表示)
  • 将来: シンボリックリンク対応を検討

3. セキュリティ

3.1 認証情報管理

  • 保存場所: OS標準キーチェーン
    • macOS: Keychain
    • Windows: Credential Manager
    • Linux: Secret Service API (gnome-keyring等)
  • 環境変数サポート: 開発者向けに環境変数からの読み込みもサポート
    • AWS_ACCESS_KEY_ID
    • AWS_SECRET_ACCESS_KEY

3.2 ファイル暗号化

  • v1.0 (MVP): サーバーサイド暗号化(SSE-S3)
    • S3がファイルを暗号化
    • 実装が簡単、コスト無料
  • 将来:
    • v2.0: SSE-KMS対応(オプション)
    • v3.0: クライアントサイド暗号化(ゼロナレッジ)

3.3 通信の暗号化

  • HTTPS(AWS SDK標準)

3.4 アプリロック機能

  • v1.0 (MVP): 不要
  • 将来: パスワード/PIN入力によるアプリロック機能を検討

4. クラウドプロバイダー対応

4.1 対応プロバイダー

v1.0 (MVP):

  • AWS S3

v2.0:

  • S3互換ストレージ
    • MinIO
    • Backblaze B2
    • Cloudflare R2
    • Wasabi
    • DigitalOcean Spaces

v2.5:

  • Google Cloud Storage (GCS)

v3.0以降:

  • Azure Blob Storage(優先度低)

対象外:

  • Dropbox、Google Drive、OneDrive等のコンシューマー向けサービス

4.2 アーキテクチャ

  • 抽象化レイヤー(Storage Trait)を実装
  • プロバイダーごとの実装を分離
  • S3 APIベースで設計(S3互換対応を容易に)

4.3 認証情報

各プロバイダーで必要な情報:

AWS S3:

  • Access Key ID
  • Secret Access Key
  • Region
  • Bucket名

S3互換:

  • Access Key ID
  • Secret Access Key
  • Endpoint URL
  • Bucket名

Google Cloud Storage:

  • Service Account Key (JSON)
  • Project ID
  • Bucket名

非機能要件

パフォーマンス

  • アプリ起動時間: 3秒以内
  • 同期処理の応答性: UIがブロックされない(非同期処理)
  • 大量ファイル対応: 10,000ファイル以上の同期に対応

使いやすさ

  • 初回セットアップ: 5分以内で完了
  • シンプルなUI: 技術的知識がなくても使える
  • 明確な同期状態表示: ファイルの状態が一目で分かる

信頼性

  • エラーハンドリング: ネットワークエラー時の適切な処理
  • データ整合性: ファイルの破損を防ぐ(ハッシュ値チェック)
  • ログ記録: トラブルシューティング用のログ出力

クロスプラットフォーム

  • 対応OS: Windows, macOS, Linux
  • 一貫したユーザー体験

開発ロードマップ

v1.0 (MVP) - AWS S3対応

目標: 基本的な同期機能の実装

実装内容:

  • Storage Trait定義(抽象化層)
  • AWS S3 Provider実装
  • 双方向同期機能
  • 競合解決(両方保存方式)
  • 削除の同期
  • 1つのフォルダ全体の同期
  • OS標準キーチェーンでの認証情報管理
  • サーバーサイド暗号化(SSE-S3)
  • ファイル状態の表示
  • デフォルト除外パターン
  • 基本的なUI(ファイルリスト、同期ボタン)

v1.5 - 除外パターン機能

目標: 同期対象の柔軟な管理

実装内容:

  • .gitignore方式の除外パターン設定
  • 除外ファイル/フォルダのUI
  • パターンマッチングエンジン

v2.0 - S3互換対応 + ソフト削除

目標: 複数プロバイダー対応とデータ保護強化

実装内容:

  • S3互換Provider実装
  • カスタムエンドポイント設定UI
  • プロバイダー選択機能
  • 複数フォルダ選択機能
  • ソフト削除(ゴミ箱方式)
  • ゴミ箱UI・復元機能
  • SSE-KMS対応(オプション)

v2.5 - Google Cloud Storage対応

目標: GCPユーザーへの対応

実装内容:

  • GCS Provider実装
  • Google認証フロー
  • GCS固有機能の対応

v3.0 - 高度な機能

目標: エンタープライズ向け機能

実装内容:

  • Azure Blob Storage対応
  • クライアントサイド暗号化
  • アプリロック機能
  • シンボリックリンク対応
  • バージョン履歴表示
  • 高度なフィルタリング機能

UI/UX設計

注: 詳細は実装フェーズで決定

最低限必要な画面:

  1. メイン画面

    • ファイルリスト表示
    • 同期ボタン
    • 同期状態表示
  2. 設定画面

    • クラウドプロバイダー選択
    • 認証情報設定
    • 同期フォルダ選択
    • 除外パターン設定(v1.5+)
  3. 初回セットアップウィザード

    • プロバイダー選択
    • 認証情報入力
    • 同期フォルダ選択

技術的制約・前提条件

前提条件

  • ユーザーはAWSアカウントを持っている(v1.0)
  • ユーザーはAWS S3バケットを作成済み
  • インターネット接続が必要

制約事項

  • オフライン時は同期不可(オフラインキューは将来検討)
  • ファイル名の文字コード制限(OS/S3の制約に従う)
  • 同時実行する同期は1つのみ(複数同時同期は将来検討)

付録

参考プロジェクト

  • Dropbox: 競合解決の方式
  • rclone: 複数クラウド対応のアーキテクチャ
  • AWS SDK for Rust: S3操作の実装

用語集

  • 同期: ローカルとクラウド間でファイルを一致させる操作
  • 競合: 両方で同じファイルが変更された状態
  • SSE-S3: S3サーバーサイド暗号化(S3管理キー)
  • Storage Trait: クラウドプロバイダーの抽象化インターフェース