# バッチ設計書 17-fastlane upload_app_store_metadata

## 概要

本ドキュメントは、App Store Connectへメタデータをアップロードするfastlaneレーン「upload_app_store_metadata」のバッチ設計書です。

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

このバッチはfastlaneのdeliverアクションを使用して、Wikipedia iOSアプリのApp Storeメタデータ（アプリ名、説明文、キーワード、リリースノートなど）をApp Store Connectにアップロードします。スクリーンショットとバイナリのアップロードはスキップされ、テキストベースのメタデータのみが対象となります。

**業務上の目的・背景**：Wikipedia iOSアプリは多言語でApp Storeに公開されており、各言語のメタデータ（アプリ名、サブタイトル、説明文、キーワード、リリースノート等）を管理する必要があります。これらのメタデータをGitリポジトリでバージョン管理し、fastlaneを通じて自動的にApp Store Connectへ反映することで、メタデータの変更履歴を追跡可能にし、手動操作によるミスを防止しています。また、翻訳チームが更新したメタデータをレビュー後に一括でアップロードできるため、リリース作業の効率化にも貢献しています。

**バッチの実行タイミング**：リリース準備時、またはメタデータ更新後に手動で実行されます。

**主要な処理内容**：
1. fastlane/metadata/ 配下の各言語ディレクトリからメタデータを読み込み
2. deliverアクションでApp Store Connectに接続
3. メタデータ（名前、説明、キーワード等）をアップロード
4. スクリーンショットとバイナリはスキップ

**前後の処理との関連**：通常、アプリのビルド・テストが完了した後のリリース準備フェーズで実行されます。バイナリのアップロードは別のワークフロー（Xcode Cloud等）で行われ、本レーンはメタデータの更新のみを担当します。

**影響範囲**：App Store Connectの全言語のメタデータに影響します。

## バッチ種別

デプロイ / App Storeメタデータアップロード

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（リリース準備時、メタデータ更新時） |
| 実行時刻 | 不定 |
| 実行曜日 | 不定 |
| 実行日 | 不定 |
| トリガー | 手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| fastlaneインストール | fastlaneがインストールされていること |
| App Store Connect認証 | 有効な認証情報（API Key / Apple ID）があること |
| メタデータファイル | fastlane/metadata/ 配下にメタデータが存在すること |
| Gitクリーン状態 | FL_ENSURE_CLEAN設定時はコミット済みであること |

### 実行可否判定

- FL_ENSURE_CLEAN環境変数設定時、Gitステータスがクリーンでなければエラー

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| FL_ENSURE_CLEAN | 環境変数 | No | なし | 設定時はGitクリーン状態を確認 |
| FL_BUILD_NUMBER_PROJECT | 環境変数 | No | Wikipedia.xcodeproj | 対象プロジェクトファイル |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| fastlane/metadata/[locale]/*.txt | テキストファイル | 各言語のメタデータ |
| fastlane/Appfile | Ruby | チームID、アプリID設定 |
| fastlane/Deliverfile | Ruby | deliver設定 |

### メタデータファイル一覧（各言語ディレクトリ）

| ファイル名 | 説明 |
|-----------|------|
| name.txt | アプリ名 |
| subtitle.txt | サブタイトル |
| description.txt | アプリ説明文 |
| keywords.txt | 検索キーワード |
| promotional_text.txt | プロモーションテキスト |
| release_notes.txt | リリースノート |
| privacy_url.txt | プライバシーポリシーURL |
| support_url.txt | サポートURL |
| marketing_url.txt | マーケティングURL |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| App Store Connect | API | アップロードされたメタデータ |

### 出力ファイル仕様

ローカルファイルの出力はありません。App Store Connectのメタデータが更新されます。

## 処理フロー

### 処理シーケンス

```
1. 前処理（before_all）
   └─ プロジェクトファイルを環境変数に設定
   └─ FL_ENSURE_CLEAN設定時、Gitステータス確認
2. レーン実行（upload_app_store_metadata）
   └─ deliverアクションを呼び出し
   └─ skip_binary_upload: true
   └─ skip_screenshots: true
3. メタデータアップロード
   └─ App Store Connect APIに接続
   └─ 各言語のメタデータを送信
```

### フローチャート

```mermaid
flowchart TD
    A[レーン開始] --> B[プロジェクト設定]
    B --> C{FL_ENSURE_CLEAN設定?}
    C -->|Yes| D[Gitステータス確認]
    C -->|No| E[スキップ]
    D --> F{クリーン?}
    F -->|No| G[エラー終了]
    F -->|Yes| E
    E --> H[deliverアクション実行]
    H --> I[skip_binary_upload: true]
    I --> J[skip_screenshots: true]
    J --> K[App Store Connect接続]
    K --> L[メタデータアップロード]
    L --> M[レーン終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | ローカルデータベース操作なし |

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

ローカルデータベース操作は行いません。App Store Connectのデータが更新されます。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 非0 | 認証エラー | App Store Connect認証失敗 | 認証情報を確認 |
| 非0 | Gitエラー | FL_ENSURE_CLEAN設定時に未コミット変更あり | 変更をコミットまたはスタッシュ |
| 非0 | APIエラー | App Store Connect API制限 | 時間をおいて再実行 |
| 非0 | バリデーションエラー | メタデータ形式不正 | メタデータファイルを修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | fastlane内部でのリトライあり |
| リトライ間隔 | 自動 |
| リトライ対象エラー | 一時的なネットワークエラー等 |

### 障害時対応

エラーメッセージを確認し、認証情報やメタデータの形式を確認してください。App Store Connect側の制限の場合は時間をおいて再実行してください。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（API呼び出し） |
| コミットタイミング | - |
| ロールバック条件 | - |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 対応言語数（約20言語） |
| 目標処理時間 | 数分〜十数分（ネットワーク状況に依存） |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

App Store Connect側で同時編集の制御が行われます。同じアプリの同時更新は避けてください。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報ログ | アップロード中 | 処理中の言語、ファイル |
| 成功ログ | 完了時 | アップロード完了メッセージ |
| エラーログ | エラー時 | エラー詳細、失敗した言語・ファイル |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| なし（手動実行） | - | - |

## 備考

- Team ID: AKK7J2GV64（Wikimedia Foundation）
- App Identifier: org.wikimedia.wikipedia
- automatic_release: false（手動リリース設定）
- copyright: 動的に現在年を使用（`#{Time.now.year} Wikimedia Foundation`）
- 対応言語例: en-US, ja, zh-hans, zh-hant, fr-fr, de-de, vi, sv など
- スクリーンショットは別途管理（fastlane/screenshots/配下）
- 認証方式はApp Store Connect APIキーまたはApple IDを使用可能
- 実行コマンド: `fastlane upload_app_store_metadata`

### メタデータディレクトリ構造

```
fastlane/
├── Fastfile
├── Appfile
├── Deliverfile
├── metadata/
│   ├── en-US/
│   │   ├── name.txt
│   │   ├── subtitle.txt
│   │   ├── description.txt
│   │   ├── keywords.txt
│   │   ├── promotional_text.txt
│   │   ├── release_notes.txt
│   │   ├── privacy_url.txt
│   │   ├── support_url.txt
│   │   └── marketing_url.txt
│   ├── ja/
│   │   └── ...
│   └── [other locales]/
│       └── ...
└── screenshots/
    └── ...
```
