active: true
derived: false
gherkin: |
  Feature: DB Protocol Hierarchy
    Scenario: Defining cache database operations via protocols
      Given a custom database implementation
      When it is evaluated against TaskDBCore or Maintenance protocols
      Then it must satisfy the required methods for core operations or maintenance tasks
groups:
- DB
header: |
  DB プロトコル階層
level: 2.8
links:
- ARCH003: hztRUPwAahIBkVhPgOSP_qIfRnh6FSkrUlxLmmzOQg8=
normative: true
ref: ''
reviewed: K5WRXwO5bWYh4ABR0dKDm-ga8ttACMaUNcqZ0CXn_DU=
text: |
  ## インターフェース

  ```python
  @runtime_checkable
  class TaskDBCore(Protocol):
      def get(self, cache_key: str, *, include_expired: bool = False) -> TaskRecord | None: ...
      def save(self, record: TaskRecord) -> None: ...

  class TaskDBBase(ABC):
      # TaskDBCore を満たしつつ、メンテナンスのデフォルト実装を提供
  ```

  ## 振る舞い

  ### 階層構造
  1. **TaskDBCore**: キャッシュの実行に必要な最小限のメソッド定義
  2. **Maintenable**: GCや統計取得に必要な管理用メソッドの定義
  3. **TaskDBBase**: 共通のバリデーションや例外処理を実装する基底クラス

  ## パラメータ詳細 (主要メソッド)

  | メソッド | 役割 |
  |---|---|
  | `get_blob_refs()` | 全レコードの `blob_key` を列挙する（GC用） |
  | `delete_expired()` | `expires_at` を経過したレコードを一括削除する |
  | `get_history()` | 実行履歴（統計）を取得する |

  ## エラーハンドリング

  - プロトコルに未実装のメソッドを呼び出した場合、実行時に `NotImplementedError` を送出する代わりに、`runtime_checkable` による事前チェックを推奨する。

  ## エッジケース

  - **複合実装**: 複数のプロトコルを一つのクラスで実装する場合、`TaskDBMaintenable` 構成プロトコルとして扱う。

  ## 設計判断

  データベースの実装（SQLite, Redis等）に依存しない共通の操作インターフェースを定義し、DIによるバックエンドの差し替えを可能にするため。
