← 全体レポートに戻る

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

生成日時: 2026-03-09 23:19:54

対象アイテム

5

REQ

1

ARCH

1

SPEC

1

TST

1

IMPL

1

レビュー済

5/5

Suspect

0

グループ

CLI
アイテム: REQ011 ARCH011 SPEC021 TST021 IMPL021

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

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

グループREQARCHSPECTSTIMPL
CLIREQ011 ✓
コマンドラインインターフェースからキャッシュの一覧表示、詳細確認、統計表示、削除、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等の管理操作ができること。

親: —

子: 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 インスタンスを組み立て

非機能要件方針

親: 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 ターミナルベースのインタラクティブダッシュボードを起動

エラーハンドリング

エッジケース

親: ARCH011

子: IMPL021, TST021

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

目的

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

検証観点

親: 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 を用いて ユーザーに明示的な確認を求めることで、誤操作によるデータ喪失を防いでいる。

実装メモ

references: src/beautyspot/cli.py

親: SPEC021

子: —