# Feature Specification: Prebuilt Model Data Support

**Feature Branch**: `004-prebuilt-data`
**Created**: 2025-10-19
**Status**: Draft
**Input**: User description: "APIキーが設定されていない場合でも、事前生成されたモデルデータを利用できる機能"

## Clarifications

### Session 2025-10-19

- Q: FR-010はopenaiは有効だが、googleが無効の場合はデータソースが混在するということか？ → A: はい、その通りです。ただし、ユーザーの要望により、プロバイダーごとのデータソース混在機能（FR-010）を削除し、仕様をシンプル化しました。すべてのプロバイダーで統一的な動作（全てAPI取得 or 全て事前生成データ）のみをサポートします。

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Zero-Configuration Quick Start (Priority: P1)

新規ユーザーがAPIキーを取得することなく、即座にツールを試用してモデルリストを確認できる。

**Why this priority**: ツール導入の最大のハードルであるAPIキー取得を不要にし、ユーザーが即座に価値を体験できるようにする。これにより、ツールの採用率が大幅に向上する。

**Independent Test**: APIキーを設定せずにモデルリスト表示コマンドを実行し、事前生成されたデータが表示されることを確認する。この機能だけで、ツールの基本的な価値（モデル一覧の確認）を提供できる。

**Acceptance Scenarios**:

1. **Given** ユーザーが環境変数にAPIキーを設定していない状態で、**When** モデルリスト表示コマンドを実行すると、**Then** 事前生成されたモデルデータが表示され、データ取得元とタイムスタンプが明示される
2. **Given** ユーザーが初めてツールを使用する状態で、**When** モデルリスト表示コマンドを実行すると、**Then** 「事前生成データを使用中」である旨のメッセージが表示され、APIキー設定でリアルタイムデータを取得できることが案内される
3. **Given** 事前生成データが24時間以上古い状態で、**When** モデルリスト表示コマンドを実行すると、**Then** データの経過時間が警告とともに表示される

---

### User Story 2 - Seamless API Key Integration (Priority: P2)

事前生成データを使用していたユーザーが、APIキーを設定することで自動的にリアルタイムデータ取得に切り替わる。

**Why this priority**: ユーザーが段階的にツールを導入できるようにする。最初は事前生成データで試用し、価値を確認した後にAPIキーを設定してリアルタイムデータを利用する自然な移行パスを提供する。

**Independent Test**: APIキーを設定した状態でコマンドを実行し、リアルタイムデータが取得されることを確認する。既存のAPI取得機能と組み合わせてテスト可能。

**Acceptance Scenarios**:

1. **Given** 事前生成データモードでツールを使用していたユーザーが、**When** 環境変数にAPIキーを設定してコマンドを実行すると、**Then** 自動的にリアルタイムデータ取得モードに切り替わり、「最新データを取得中」というメッセージが表示される
2. **Given** APIキーが設定されているが無効な状態で、**When** コマンドを実行すると、**Then** エラーメッセージが明確に表示され、事前生成データが使用される旨が通知される

---

### User Story 3 - Automated Data Freshness (Priority: P3)

事前生成データが定期的に自動更新され、ユーザーは常に比較的新しいデータにアクセスできる。

**Why this priority**: 事前生成データの価値を維持するため。古いデータでは意味がないため、自動更新により実用性を確保する。ただし、コアユーザー体験（P1、P2）ほど緊急性は高くない。

**Independent Test**: 自動更新プロセスが正常に実行され、リポジトリに新しいデータが保存されることを確認する。スケジュール実行のログとデータのタイムスタンプで検証可能。

**Acceptance Scenarios**:

1. **Given** 自動更新プロセスが1日1回実行される設定で、**When** スケジュールされた時刻になると、**Then** 最新のモデルデータが取得され、リポジトリ内の事前生成データファイルが更新される
2. **Given** 自動更新プロセスが実行される状態で、**When** APIからのデータ取得に失敗すると、**Then** エラーが通知され、既存の事前生成データは保持される
3. **Given** 事前生成データが更新された状態で、**When** ユーザーがツールを使用すると、**Then** 更新されたタイムスタンプが表示され、最新のデータであることが確認できる

---

### User Story 4 - Data Source Transparency (Priority: P2)

ユーザーは、使用しているデータがリアルタイムAPIから取得されたものか、事前生成されたものかを明確に識別できる。

**Why this priority**: ユーザーがデータの信頼性と鮮度を判断するために必須。意思決定に影響するため、P2の優先度。

**Independent Test**: 各モードでコマンドを実行し、データソースが明確に表示されることを確認する。出力メッセージの検証のみで完結。

**Acceptance Scenarios**:

1. **Given** 事前生成データを使用している状態で、**When** モデルリスト表示コマンドを実行すると、**Then** 「事前生成データ使用中（更新: 2025-10-19 00:00 UTC、経過時間: 12時間）」のようなメッセージが表示される
2. **Given** リアルタイムAPIデータを使用している状態で、**When** モデルリスト表示コマンドを実行すると、**Then** 「最新データ取得中...」または「APIから取得済み」というメッセージが表示される
3. **Given** データをエクスポートする状態で、**When** エクスポートコマンドを実行すると、**Then** エクスポートされたファイルにデータソースとタイムスタンプのメタデータが含まれる

---

### Edge Cases

- 事前生成データファイルが存在しない、または破損している場合はどうなるか？
  - 明確なエラーメッセージを表示し、APIキー設定を促す
- 自動更新プロセスが連続して失敗した場合はどうなるか？
  - 最後に成功したデータを保持し、データの経過時間を警告表示する
- 事前生成データが極端に古い（7日以上）場合はどうなるか？
  - 強い警告メッセージを表示し、APIキー設定またはプロジェクトメンテナーへの報告を促す
- ユーザーが手動で事前生成データファイルを削除した場合はどうなるか？
  - ファイル不在エラーとして扱い、APIキー設定を促す

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: システムは、環境変数にAPIキーが設定されていない場合、自動的に事前生成されたモデルデータを使用しなければならない
- **FR-002**: システムは、事前生成データを使用する際、データの取得元（事前生成データ）とタイムスタンプ（生成日時）を明示しなければならない
- **FR-003**: システムは、事前生成データの経過時間を計算し、24時間以上経過している場合は警告を表示しなければならない
- **FR-004**: システムは、環境変数にAPIキーが設定されている場合、自動的にリアルタイムAPIデータ取得モードに切り替わらなければならない
- **FR-005**: システムは、事前生成データファイルが存在しない場合、明確なエラーメッセージを表示し、APIキー設定を案内しなければならない
- **FR-006**: システムは、1日1回の頻度で最新のモデルデータを自動取得し、事前生成データファイルを更新しなければならない
- **FR-007**: 自動更新プロセスは、データ取得に失敗した場合でも既存の事前生成データを保持し、エラーを通知しなければならない
- **FR-008**: エクスポート機能は、データソース（API/事前生成）とタイムスタンプを含むメタデータを出力ファイルに含めなければならない
- **FR-009**: システムは、APIキーが設定されているが無効な場合、明確なエラーメッセージを表示し、事前生成データを使用する旨を通知しなければならない

### Key Entities

- **PrebuiltModelData**: 事前生成されたモデルデータを表すエンティティ
  - 生成日時（タイムスタンプ）
  - データバージョン
  - プロバイダーごとのモデルリスト
  - メタデータ（生成元、ツールバージョン等）

- **DataSourceIndicator**: データの取得元を示すエンティティ
  - データソースタイプ（API取得/事前生成）
  - タイムスタンプ
  - 経過時間
  - プロバイダー名

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: APIキーを設定していないユーザーが、30秒以内にモデルリストを確認できる
- **SC-002**: 事前生成データ使用時、データソースとタイムスタンプが100%のケースで明示される
- **SC-003**: 自動更新プロセスが95%以上の成功率で定期実行される
- **SC-004**: ツール導入から初回使用までの時間が、APIキー取得が必要な場合と比較して80%短縮される
- **SC-005**: 事前生成データの鮮度が、平均12時間以内に保たれる（1日1回更新の場合）
- **SC-006**: APIキー設定後、次回コマンド実行時に自動的にリアルタイムモードに切り替わる（100%のケースで）
- **SC-007**: エクスポートされたデータに、データソースとタイムスタンプのメタデータが100%含まれる
- **SC-008**: 事前生成データモードからリアルタイムモードへの移行が、ユーザーアクション（APIキー設定）のみで完了する

## Assumptions

- 事前生成データは、プロジェクトリポジトリ内の特定のディレクトリに保存される
- 自動更新プロセスは、GitHub Actionsまたは同等の CI/CD システムで実装される
- プロバイダーのモデルリストAPIは、日次更新で十分な頻度で変更される（リアルタイム性は重要でない）
- ユーザーは、24時間以内のデータ遅延を許容できる
- 事前生成データのファイルサイズは、リポジトリに含めるのに適切なサイズ（数百KB以内）である
- プロバイダーのAPI利用規約は、モデルリストデータの再配布を許可している
- 自動更新に使用するAPIキーは、プロジェクトメンテナーが管理し、秘密情報として適切に保護される
- 事前生成データは公開情報であり、機密性の懸念がない

## Dependencies

- 既存のモデル取得機能（OpenAI、Google、Anthropic fetchers）
- 既存のエクスポート機能（JSON、CSV等）
- 既存のキャッシュ機能（ローカルキャッシュ管理）
- CI/CD システム（GitHub Actions等）での定期実行機能
- Git リポジトリへのコミット・プッシュ機能（自動更新時）

## Out of Scope

- リアルタイムAPIデータと事前生成データの同時並行取得
- 事前生成データの配信をCDN経由で行う機能
- ユーザーが事前生成データの更新頻度を設定する機能
- 事前生成データの複数バージョン管理機能
- プロバイダーのAPI利用規約違反の検出機能
- 事前生成データの暗号化・署名機能
- 事前生成データのバージョン間の差分表示機能

