# Maintenance Service

`MaintenanceService` は、`beautyspot` システムの管理・運用に特化したサービスレイヤーです。データの整合性を保ち、ストレージ使用量を管理するためのすべてのクリーンアップ操作を処理します。

::: beautyspot.maintenance

## アーキテクチャ

このサービスは、**論理レイヤー**（データベースレコード）と**物理レイヤー**（Blobストレージ）を分離して管理します。

### 削除戦略

* **トランザクション安全性:** タスクを削除する際、`beautyspot` はデータベースレコードを削除する *前* に、物理Blobファイルの削除を試みます。ただし、Blob削除が失敗した場合（例: S3のネットワークエラー）でも、壊れたデータを提供しないようにDBレコードは削除されます。これにより「孤立したファイル」が残る可能性があるため、`clean` コマンドが用意されています。
* **寛容な削除 (Tolerant Deletion):** `delete_task` 操作は「寛容」です。つまり、物理ファイルが既に存在しない場合でもエラーを発生させず、DBレコードの削除を完了させます。

### ライフサイクル管理

データの保持期間（Retention）は、以下の2つの方法で管理できます。

1.  **明示的な Pruning (`prune` コマンド):**
    * `updated_at` タイムスタンプに基づいてタスクを削除します。
    * バッチ処理スクリプトなどでの定期実行に適しています。

2.  **TTL / 有効期限 (将来の機能):**
    * `@mark(retention=...)` デコレータによって、タスクに `expires_at` フィールドを設定できます。
    * `MaintenanceService` は `delete_expired_tasks()` を提供し、これらのレコードを物理削除します。
    * *注: 現在、有効期限は読み取り時に遅延チェックされます。物理的な削除を行うには、クリーンアップジョブを実行する必要があります。*

## ゾンビプロジェクト (`gc`)

「ゾンビプロジェクト」とは、Blobストレージルート（例: `.beautyspot/blobs/<name>`）内のサブディレクトリのうち、対応するSQLiteデータベースファイル（`.beautyspot/<name>.db`）を持たないものを指します。

`gc` コマンドは、ワークスペースを浅くスキャン (Shallow Scan) し、これらのディレクトリを特定して削除します。

