局所トレーサビリティ — グループ: CLI

# 局所トレーサビリティビュー グループ: CLI

生成日時: 2026-03-11 00:06:09

### 対象アイテム

5

### REQ

1

### ARCH

1

### SPEC

1

### TST

1

### IMPL

1

### レビュー済

5/5

### Suspect

0

### グループ

CLI

## トレーサビリティマトリクス

✓=レビュー済 ○=未レビュー ⚠=Suspect（複数同時表示あり。IDクリックで詳細へ）

グループ | REQ | ARCH | SPEC | TST | IMPL
--- | --- | --- | --- | --- | ---
CLI | REQ011 ✓ コマンドラインインターフェースからキャッシュの一覧表示、詳細確認、統計表示、削除、GC等の管理操作ができること。 | ARCH011 ✓ ## コンポーネント構成 ```mermaid graph TD A[beautyspot CLI] -->|Command| B[Typer App] ... | SPEC021 ✓ ## インターフェース ```bash beautyspot list [--db DB_PATH] beautyspot gc [--name PROJEC... | TST021 ✓ ## 目的 CLI はユーザーがキャッシュの状況確認・管理を行う主要インターフェースであり、コマンドの不具合はユーザー体験と運用効率に直接影響する。`CliR... | IMPL021 ✓ ## 実装概要 `Typer` を利用したコマンドラインインターフェースの実装。 `list`, `show`, `stats`, `clear`, `cle...

## カバレッジ（局所）

リンク方向 | カバー数 | カバー率 | 未カバー
--- | --- | --- | ---
ARCH → REQ | 1 / 1 | 100.0% | —
SPEC → ARCH | 1 / 1 | 100.0% | —
TST → SPEC | 1 / 1 | 100.0% | —
IMPL → SPEC | 1 / 1 | 100.0% | —

## アイテム詳細

### REQ011 REQ {h(g)} ✓ レビュー済

コマンドラインインターフェースからキャッシュの一覧表示、詳細確認、統計表示、削除、GC等の管理操作ができること。

コマンドラインインターフェースからキャッシュの一覧表示、詳細確認、統計表示、削除、GC等の管理操作ができること。

親: —

子: ARCH011

### ARCH011 ARCH {h(g)} ✓ レビュー済

## コンポーネント構成

    graph TD
      A[beautyspot CLI] -->|Command| B[Typer App]
      B -->|Business Logic| C[MaintenanceService]
      B -->|Output| D[Rich Console]
      B -->|Dashboard| E[Dashboard App]

## コンポーネント責務

コンポーネント | 責務 | インターフェース
--- | --- | ---
Typer App | コマンドライン引数のパースとサブコマンドのディスパッチ | `main()`, `gc()`, `list()`
MaintenanceService | 実際のキャッシュ管理ロジックの実行 | `clean_garbage()`, `clear()`
Rich Console | ターミナルでの視覚的に分かりやすいテーブルやパネルの描画 | `Console`, `Table`
Dashboard App | キャッシュ状態をインタラクティブに閲覧するためのTUI | `dashboard.py`

## データフロー

    sequenceDiagram
      participant User as ユーザー
      participant CLI as CLI App
      participant Service as MaintenanceService
      participant Output as Rich Console

      User->>CLI: beautyspot gc --name my-project
      CLI->>Service: clean_garbage()
      Service-->>CLI: result (removed count, etc.)
      CLI->>Output: print summary table
      Output-->>User: formatted output

## 技術選定

技術領域 | 選定 | 理由
--- | --- | ---
フレームワーク | Typer | 型ヒントに基づいた堅牢なコマンドラインインターフェースを迅速に構築
出力装飾 | Rich | プログレスバーやステータス表示により、長時間処理の進捗を可視化
連携 | Factory DI | カレントディレクトリや設定から自動的に `Spot` インスタンスを組み立て

## 非機能要件方針

- UX: 破壊的な操作（`clear`等）には対話的な確認プロンプトを表示
- 互換性: 標準出力のパイプ連携を妨げないよう、色の自動無効化に対応
- 利便性: 特定のプロジェクトだけでなく、全DBを横断的にスキャンする機能を提供

## コンポーネント構成 ```mermaid graph TD A[beautyspot CLI] -->|Command| B[Typer App] B -->|Business Logic| C[MaintenanceService] B -->|Output| D[Rich Console] B -->|Dashboard| E[Dashboard App] ``` ## コンポーネント責務 | コンポーネント | 責務 | インターフェース | |---|---|---| | Typer App | コマンドライン引数のパースとサブコマンドのディスパッチ | `main()`, `gc()`, `list()` | | MaintenanceService | 実際のキャッシュ管理ロジックの実行 | `clean_garbage()`, `clear()` | | Rich Console | ターミナルでの視覚的に分かりやすいテーブルやパネルの描画 | `Console`, `Table` | | Dashboard App | キャッシュ状態をインタラクティブに閲覧するためのTUI | `dashboard.py` | ## データフロー ```mermaid sequenceDiagram participant User as ユーザー participant CLI as CLI App participant Service as MaintenanceService participant Output as Rich Console User->>CLI: beautyspot gc --name my-project CLI->>Service: clean_garbage() Service-->>CLI: result (removed count, etc.) CLI->>Output: print summary table Output-->>User: formatted output ``` ## 技術選定 | 技術領域 | 選定 | 理由 | |---|---|---| | フレームワーク | Typer | 型ヒントに基づいた堅牢なコマンドラインインターフェースを迅速に構築 | | 出力装飾 | Rich | プログレスバーやステータス表示により、長時間処理の進捗を可視化 | | 連携 | Factory DI | カレントディレクトリや設定から自動的に `Spot` インスタンスを組み立て | ## 非機能要件方針 - **UX**: 破壊的な操作（`clear`等）には対話的な確認プロンプトを表示 - **互換性**: 標準出力のパイプ連携を妨げないよう、色の自動無効化に対応 - **利便性**: 特定のプロジェクトだけでなく、全DBを横断的にスキャンする機能を提供

親: REQ011

子: SPEC021

### SPEC021 SPEC {h(g)} ✓ レビュー済

## インターフェース

    beautyspot list [--db DB_PATH]
    beautyspot gc [--name PROJECT_NAME] [--force]
    beautyspot stats
    beautyspot ui

## 振る舞い

1. コンテキスト解決: `--db` 指定がない場合、デフォルトの `.beautyspot/` ディレクトリを探索する
2. コマンド実行: `MaintenanceService` または `Spot` インスタンスを生成し、対応するメソッドを呼び出す
3. フォーマット出力: `Rich` ライブラリを使用して、結果をテーブルやプログレスバーで表示する

## サブコマンド詳細

コマンド | 説明
--- | ---
`list` | 保存されているキャッシュキーと関数名の一覧を表示
`gc` | 期限切れタスクと孤立Blobのクリーンアップを実行
`stats` | キャッシュヒット率やストレージ使用量の統計を表示
`ui` | ターミナルベースのインタラクティブダッシュボードを起動

## エラーハンドリング

- DB不在: 指定されたパスにDBがない場合は、エラーメッセージを表示して終了する。
- 権限不足: ファイル削除権限がない場合は、スキップされた旨を表示する。

## エッジケース

- 非対話環境: CI等での実行を考慮し、色の無効化や確認プロンプトのスキップ（`--force`）に対応する。

## インターフェース ```bash beautyspot list [--db DB_PATH] beautyspot gc [--name PROJECT_NAME] [--force] beautyspot stats beautyspot ui ``` ## 振る舞い 1. **コンテキスト解決**: `--db` 指定がない場合、デフォルトの `.beautyspot/` ディレクトリを探索する 2. **コマンド実行**: `MaintenanceService` または `Spot` インスタンスを生成し、対応するメソッドを呼び出す 3. **フォーマット出力**: `Rich` ライブラリを使用して、結果をテーブルやプログレスバーで表示する ## サブコマンド詳細 | コマンド | 説明 | |---|---| | `list` | 保存されているキャッシュキーと関数名の一覧を表示 | | `gc` | 期限切れタスクと孤立Blobのクリーンアップを実行 | | `stats` | キャッシュヒット率やストレージ使用量の統計を表示 | | `ui` | ターミナルベースのインタラクティブダッシュボードを起動 | ## エラーハンドリング - **DB不在**: 指定されたパスにDBがない場合は、エラーメッセージを表示して終了する。 - **権限不足**: ファイル削除権限がない場合は、スキップされた旨を表示する。 ## エッジケース - **非対話環境**: CI等での実行を考慮し、色の無効化や確認プロンプトのスキップ（`--force`）に対応する。

親: ARCH011

子: IMPL021, TST021

### TST021 TST {h(g)} ✓ レビュー済

## 目的

CLI はユーザーがキャッシュの状況確認・管理を行う主要インターフェースであり、コマンドの不具合はユーザー体験と運用効率に直接影響する。`CliRunner` によるコマンド実行と出力の正確性を E2E で検証する。

## 検証観点

- list コマンド: キャッシュ済みタスクの一覧が正しく表示されること。DBが空の場合に適切なメッセージが表示されること
- show コマンド: 指定タスクの詳細情報（func_name, input_key, created_at, result サイズ等）が正しく表示されること
- stats コマンド: キャッシュ統計（総件数、関数別件数、ストレージ使用量等）が正確に表示されること
- clear コマンド: 確認プロンプト後にキャッシュが削除されること。`--force` フラグでプロンプトがスキップされること
- gc / prune コマンド: 有効期限切れタスクの削除と孤立Blobの清掃が正しく実行されること
- E2E パイプライン: `@mark` でキャッシュ保存 → `beautyspot list` で確認 → `beautyspot clear` で削除、という一連のワークフローが正常に動作すること
- エラー時の終了コード: 不正な引数やDB不在時に非ゼロの終了コードが返ること

## 目的 CLI はユーザーがキャッシュの状況確認・管理を行う主要インターフェースであり、コマンドの不具合はユーザー体験と運用効率に直接影響する。`CliRunner` によるコマンド実行と出力の正確性を E2E で検証する。 ## 検証観点 - **list コマンド**: キャッシュ済みタスクの一覧が正しく表示されること。DBが空の場合に適切なメッセージが表示されること - **show コマンド**: 指定タスクの詳細情報（func_name, input_key, created_at, result サイズ等）が正しく表示されること - **stats コマンド**: キャッシュ統計（総件数、関数別件数、ストレージ使用量等）が正確に表示されること - **clear コマンド**: 確認プロンプト後にキャッシュが削除されること。`--force` フラグでプロンプトがスキップされること - **gc / prune コマンド**: 有効期限切れタスクの削除と孤立Blobの清掃が正しく実行されること - **E2E パイプライン**: `@mark` でキャッシュ保存 → `beautyspot list` で確認 → `beautyspot clear` で削除、という一連のワークフローが正常に動作すること - **エラー時の終了コード**: 不正な引数やDB不在時に非ゼロの終了コードが返ること

references: tests/integration/cli/test_cli.py

親: SPEC021

子: —

### IMPL021 IMPL {h(g)} ✓ レビュー済

## 実装概要

`Typer` を利用したコマンドラインインターフェースの実装。 `list`, `show`, `stats`, `clear`, `clean`, `gc`, `prune`, `version` 等の コマンドを提供し、`rich` ライブラリを用いてコンソール出力（テーブル、パネル、 プログレスバー等）をリッチにフォーマットしている。

## 設計判断

### Typer と Rich の組み合わせ

Typer は型ヒントベースでコマンドやオプションを定義でき、コードの記述量と メンテナンスコストを大幅に削減できる。Rich による出力は、単なるテキストではなく 構造化された情報（JSONやMarkdown）の視認性を劇的に向上させ、DXを高める。

### 安全性を考慮した対話的プロンプト

`clear` や `clean` など、データを大規模に削除するコマンドについては、 `--force` オプションが指定されない限り、`rich.prompt.Confirm` を用いて ユーザーに明示的な確認を求めることで、誤操作によるデータ喪失を防いでいる。

## 実装メモ

- コマンドは `MaintenanceService` などの内部 API を利用して処理を行う
- 各コマンドは特定のプロジェクト (`--project` / `-p`) に対して操作を行うが、 一部のコマンド（`list` 等）はワークスペース全体の走査もサポートする

## 実装概要 `Typer` を利用したコマンドラインインターフェースの実装。 `list`, `show`, `stats`, `clear`, `clean`, `gc`, `prune`, `version` 等の コマンドを提供し、`rich` ライブラリを用いてコンソール出力（テーブル、パネル、 プログレスバー等）をリッチにフォーマットしている。 ## 設計判断 ### Typer と Rich の組み合わせ Typer は型ヒントベースでコマンドやオプションを定義でき、コードの記述量と メンテナンスコストを大幅に削減できる。Rich による出力は、単なるテキストではなく 構造化された情報（JSONやMarkdown）の視認性を劇的に向上させ、DXを高める。 ### 安全性を考慮した対話的プロンプト `clear` や `clean` など、データを大規模に削除するコマンドについては、 `--force` オプションが指定されない限り、`rich.prompt.Confirm` を用いて ユーザーに明示的な確認を求めることで、誤操作によるデータ喪失を防いでいる。 ## 実装メモ - コマンドは `MaintenanceService` などの内部 API を利用して処理を行う - 各コマンドは特定のプロジェクト (`--project` / `-p`) に対して操作を行うが、 一部のコマンド（`list` 等）はワークスペース全体の走査もサポートする

references: src/beautyspot/cli.py

親: SPEC021

子: —