active: true
derived: false
groups:
- HOOK
header: |
  フック機能構成
level: 2.9
links:
- REQ009: Pz2A0pug8oCFm4G1UmkLY_oBU2CrulUJDQCx4D6WXyk=
normative: true
ref: ''
reviewed: nrhbqQ86X6JfwCo7wnH2wxMqhFFhJSOFmi_i-aJ7MfE=
text: |
  ## コンポーネント構成

  ```mermaid
  graph TD
    A[core.Spot] -->|イベント通知| B[HookBase]
    C[ThreadSafeHookBase]　--> B
    B -->|コンテキスト| D[Context Objects]
    E[PreExecuteContext] --> D
    F[CacheHitContext] --> D
    G[CacheMissContext] --> D
  ```

  ## コンポーネント責務

  | コンポーネント | 責務 | インターフェース |
  |---|---|---|
  | HookBase | 実行ライフサイクルの各段階で呼び出される抽象基底クラス | `pre_execute`, `on_cache_hit`, `on_cache_miss` |
  | ThreadSafeHookBase | RLockを用いて各フックメソッドの実行を直列化する | `__init_subclass__` による自動ラップ |
  | Context Objects | フックに渡される実行時の引数、結果、例外、メタデータのコンテナ | `ctx.args`, `ctx.result` 等 |

  ## データフロー

  ```mermaid
  sequenceDiagram
    participant Spot as core.Spot
    participant Hook as HookBase
    participant Fn as Target Function

    Spot->>Hook: pre_execute(ctx)
    alt キャッシュヒット
        Spot->>Hook: on_cache_hit(ctx)
    else キャッシュミス
        Spot->>Fn: execute()
        Fn-->>Spot: result
        Spot->>Hook: on_cache_miss(ctx)
    end
  ```

  ## 技術選定

  | 技術領域 | 選定 | 理由 |
  |---|---|---|
  | パターン | オブザーバー | コアロジックを汚さずに、ログ出力や統計取得等の横断的関心を分離 |
  | スレッド安全 | 自動装飾 (Decorator) | ユーザーが意識せずに、サブクラス化するだけで安全なフックを実装可能 |
  | 実行制御 | 準同期実行 | フック内の例外をキャッチしログ出力に留めることで、主処理を保護 |

  ## 非機能要件方針

  -   **透過性**: フックの実行失敗（例外）は主処理の結果に影響を与えない

  -   **柔軟性**: 関数ごとに異なるフックリストを `hooks=[...]` で指定可能

  -   **パフォーマンス**: フック未登録時のオーバーヘッドを最小化するガード条件を実装

  ## 設計根拠

  コアロジックを肥大化させずにイベント駆動の拡張を可能にするため。ObserverパターンのバリエーションとしてHookBaseを定義し、各フェーズのコンテキスト（状態）をカプセル化して渡すことで、安全に状態を参照・変更できる構成とした。
