# バッチ設計書 2-starwars.R

## 概要

本ドキュメントは、Star Wars API（SWAPI）から取得したキャラクター情報を基に、starwarsサンプルデータセットを生成し、dplyrパッケージのdataディレクトリに保存するバッチ処理の設計書である。

### 本バッチの処理概要

このバッチは、外部API（swapi.py4e.com）からStar Warsのキャラクター情報を取得し、データの加工・変換を行った上で、dplyrパッケージで利用可能なサンプルデータセットとして保存する処理を行う。

**業務上の目的・背景**：dplyrパッケージでは、データ操作の例示やチュートリアルに使用する魅力的なサンプルデータセットが必要である。Star Warsのキャラクターデータは、多様なデータ型（数値、文字列、リスト型カラム）を含み、欠損値の処理やデータ変換の例示に適している。また、広く知られたコンテンツであるため、ユーザーにとって直感的に理解しやすいデータセットとなる。

**バッチの実行タイミング**：パッケージ開発時の手動実行。外部APIのデータが更新された場合や、データセット構造を変更する場合に実行される。APIの応答速度に依存するため、ネットワーク接続環境で実行する必要がある。

**主要な処理内容**：
1. tidyverse、httrライブラリの読み込み
2. Star Wars API（SWAPI）からキャラクター情報をページネーション対応で全件取得
3. 種族、映画、惑星、乗り物、宇宙船のルックアップテーブルを生成
4. 取得データをtibble形式に変換し、各フィールドを適切な型に変換
5. ドロイドの性別・生物学的性別の特別処理
6. 名前のタイポ修正（Beru Whitesun lars -> Beru Whitesun Lars）
7. データの検証チェック
8. CSVファイルとしてdiff確認用に保存
9. usethis::use_data()でパッケージデータとして保存

**前後の処理との関連**：前提となるバッチは存在しない。本バッチの出力は、パッケージのビルド時にdata/ディレクトリに含まれ、パッケージ利用者がdata(starwars)で読み込み可能となる。

**影響範囲**：dplyrパッケージのdata/starwars.rdaファイルおよびdata-raw/starwars.csvファイルが更新される。starwarsデータセットはパッケージの公開APIの一部であり、カラム構造や値の変更は後方互換性に影響する可能性がある。

## バッチ種別

データ生成（外部API連携）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | 手動（開発者による実行） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| tidyverseパッケージ | tidyverseがインストールされていること |
| httrパッケージ | httrがインストールされていること |
| usethisパッケージ | usethisがインストールされていること |
| ネットワーク接続 | swapi.py4e.comへのアクセスが可能であること |
| Rプロジェクト構成 | dplyrパッケージのルートディレクトリで実行すること |

### 実行可否判定

手動実行のため、開発者の判断により実行。外部APIが利用可能であることを確認後に実行する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 本バッチは入力パラメータを受け取らない |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| swapi.py4e.com/api/people | JSON/REST API | キャラクター情報 |
| swapi.py4e.com/api/species | JSON/REST API | 種族情報 |
| swapi.py4e.com/api/films | JSON/REST API | 映画情報 |
| swapi.py4e.com/api/planets | JSON/REST API | 惑星情報 |
| swapi.py4e.com/api/vehicles | JSON/REST API | 乗り物情報 |
| swapi.py4e.com/api/starships | JSON/REST API | 宇宙船情報 |
| ハードコード値 | Rスクリプト内 | ドロイドの性別マッピング |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| data/starwars.rda | R binary | Star Warsキャラクターデータセット |
| data-raw/starwars.csv | CSV | diff確認用テキストファイル |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | starwars.rda, starwars.csv |
| 出力先 | data/, data-raw/ |
| 文字コード | UTF-8（CSV） |
| 区切り文字 | カンマ（CSV） |

#### starwarsデータセット構造

| カラム名 | 型 | 説明 |
|---------|-----|------|
| name | character | キャラクター名 |
| height | integer | 身長（cm） |
| mass | numeric | 体重（kg） |
| hair_color | character | 髪の色 |
| skin_color | character | 肌の色 |
| eye_color | character | 目の色 |
| birth_year | numeric | 誕生年（BBY） |
| sex | character | 生物学的性別（male, female, hermaphroditic, none） |
| gender | character | 性自認（masculine, feminine） |
| homeworld | character | 出身惑星 |
| species | character | 種族 |
| films | list | 出演映画リスト |
| vehicles | list | 使用乗り物リスト |
| starships | list | 操縦宇宙船リスト |

## 処理フロー

### 処理シーケンス

```
1. ライブラリの読み込み
   └─ tidyverse, httrをロード
2. get_all関数によるAPIデータ取得
   └─ ページネーション対応で全キャラクターを取得
3. ルックアップテーブルの生成
   └─ species, films, planets, vehicles, starshipsのマッピング作成
4. starwarsデータフレームの構築
   └─ 各フィールドを抽出し適切な型に変換
5. 性別データの補完
   └─ ドロイドとハットの性別を手動マッピングで補完
6. タイポ修正
   └─ Beru Whitesun larsをBeru Whitesun Larsに修正
7. 基本チェックの実行
   └─ species, homeworld, skin_colorのカウント確認
8. CSV形式で保存
   └─ data-raw/starwars.csvに出力
9. パッケージデータとして保存
   └─ usethis::use_data()でdata/starwars.rdaに出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[ライブラリ読み込み]
    B --> C[SWAPI からキャラクター取得]
    C --> D[ルックアップテーブル生成]
    D --> E[tibble構築・型変換]
    E --> F[性別データ補完]
    F --> G[タイポ修正]
    G --> H[データ検証チェック]
    H --> I[CSV保存]
    I --> J[RDAファイル保存]
    J --> K[バッチ終了]
```

## データベース操作仕様

### 操作別データベース影響一覧

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | 本バッチはデータベースを使用しない |

### テーブル別操作詳細

本バッチはファイルシステムへの出力のみを行い、データベースは使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | HTTPエラー | APIリクエスト失敗 | stop_for_status()でエラー停止、ネットワーク確認後再実行 |
| - | パッケージ未インストール | 必要なパッケージがない | 必要なパッケージをインストール |
| - | API変更 | SWAPIのレスポンス構造変更 | スクリプトを更新 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動実行） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

エラー発生時は、エラーメッセージを確認し、ネットワーク接続やAPIの状態を確認後に再実行する。

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（ファイル出力） |
| コミットタイミング | write_csv(), use_data()呼び出し時 |
| ロールバック条件 | なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 約87キャラクター + 関連データ |
| 目標処理時間 | 数分（API応答速度に依存） |
| メモリ使用量上限 | 数MB |

## 排他制御

同時実行の制御は行わない。開発者が手動で実行するため、同時実行は想定されない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | API取得時 | "Getting {URL}" メッセージ |
| 検証ログ | チェック実行時 | count()結果の表示 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| N/A | N/A | N/A（手動実行バッチのため監視なし） |

## 備考

- このスクリプトは開発時のデータセット生成用であり、通常のパッケージ利用時には実行されない
- 外部API（SWAPI）に依存するため、APIのサービス停止やURLの変更に注意が必要
- ドロイドの性別データは@MeganBeckettによる手動収集データに基づく
- films, vehicles, starshipsカラムはリスト型カラムであり、tidyrのunnest()等で展開可能
