# 画面設計書 61-WelcomeAnimation画面

## 概要

本ドキュメントは、Wikipedia iOSアプリのWelcomeAnimation画面の設計を記載したものです。この画面はオンボーディングフローにおいてアニメーションを表示するためのViewControllerです。

### 本画面の処理概要

WelcomeAnimation画面は、アプリの初回起動時に表示されるオンボーディングフローの一部として、アニメーションによる視覚的な演出を提供する画面です。

**業務上の目的・背景**：初回起動時のユーザー体験を向上させるため、視覚的に魅力的なアニメーションを表示し、アプリの世界観やブランドイメージを伝えることを目的としています。単純なテキストだけでなく、アニメーションを活用することで、ユーザーの興味を引きつけ、オンボーディングの完了率を高める効果が期待されています。

**画面へのアクセス方法**：Welcome画面からWelcomePageViewControllerを経由してページング形式で表示されます。オンボーディングフロー内の特定のステップでアニメーションパネルとして組み込まれます。

**主要な操作・処理内容**：
1. 画面表示時にWelcomeAnimationViewをビューに追加
2. waitsForAnimationTriggerフラグに応じて、viewDidAppear時に自動でアニメーションを開始するか、外部からのトリガーを待つ
3. animate()メソッド呼び出しでアニメーションを実行
4. 一度実行したアニメーションは再実行されない（completedAnimationフラグで管理）

**画面遷移**：
- 遷移元：WelcomeContainer画面、WelcomePage画面からのページング
- 遷移先：次のWelcomeパネル（ページング操作）、メインタブ画面（オンボーディング完了時）

**権限による表示制御**：特になし。初回起動時のすべてのユーザーに対して同一の表示が行われます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 63 | 初回起動ウェルカム | 補助機能 | オンボーディングのアニメーション表示 |

## 画面種別

アニメーション表示

## URL/ルーティング

該当なし（ネイティブViewController）

## 入出力項目

| 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|--------|-----|----------|------|------|
| animationView | WelcomeAnimationView | 入力 | 必須 | 表示するアニメーションビュー |
| waitsForAnimationTrigger | Bool | 入力 | 任意 | アニメーション開始を外部トリガーに委ねるかどうか（デフォルト: true） |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|----------|------|
| animationView | 画面全体 | アニメーションを表示するカスタムビュー |

## イベント仕様

### 1-viewDidLoad

画面がロードされた際の初期化処理。

- animationViewをビューにサブビューとして追加
- 制約を設定して画面全体にフィット

### 2-viewDidAppear

画面が表示された際の処理。

- waitsForAnimationTriggerがfalseの場合、自動的にanimate()を呼び出し
- waitsForAnimationTriggerがtrueの場合、外部からのanimate()呼び出しを待機

### 3-animate

アニメーション実行メソッド。

- completedAnimationフラグをチェックし、既に実行済みの場合は処理をスキップ
- animationView.animate()を呼び出してアニメーションを実行
- completedAnimationフラグをtrueに設定

## データベース更新仕様

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

この画面ではデータベース操作は発生しません。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| - | - | - | この画面にはユーザー向けメッセージはありません |

## 例外処理

| 例外条件 | 対処 |
|----------|------|
| animationViewの画像リソースが見つからない | fatalError（開発時に検出） |

## 備考

- WelcomeAnimationViewは静的画像と複数のAnimatedImageViewを組み合わせてアニメーションを構成
- アニメーションはUIViewPropertyAnimatorを使用して制御
- デバイスの向きや画面サイズに応じてアニメーション要素の位置が正規化される

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、アニメーションビューの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | WelcomeAnimationView.swift | `Wikipedia/Code/WelcomeAnimationView.swift` | AnimatedImageViewの定義と、アニメーション位置の正規化ロジック |

**読解のコツ**: AnimatedImageViewのstart, destination, normalizedDestinationプロパティがアニメーションの開始・終了位置を制御しています。AVMakeRectを使用したアスペクト比維持の位置計算に注目してください。

#### Step 2: エントリーポイントを理解する

処理の起点となるViewControllerを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | WelcomeAnimationViewController.swift | `Wikipedia/Code/WelcomeAnimationViewController.swift` | 初期化とアニメーショントリガーの制御 |

**主要処理フロー**:
1. **8-12行目**: init - animationViewとwaitsForAnimationTriggerを受け取って初期化
2. **18-21行目**: viewDidLoad - animationViewをサブビューとして追加
3. **23-29行目**: viewDidAppear - waitsForAnimationTrigger判定でアニメーション自動開始
4. **31-37行目**: animate - completedAnimationフラグチェック後、アニメーション実行

#### Step 3: アニメーション実装を理解する

アニメーションの詳細実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | WelcomeAnimationView.swift | `Wikipedia/Code/WelcomeAnimationView.swift` | animate()メソッドとUIViewPropertyAnimatorの使用 |

**主要処理フロー**:
- **44-51行目**: animate() - propertyAnimator.startAnimation()でアニメーション開始
- **53-70行目**: init - 静的画像とアニメーション画像の配置
- **81-103行目**: updateLayout() - 画面サイズに応じた位置の再計算

### プログラム呼び出し階層図

```
WelcomePageViewController
    |
    +-- WelcomeAnimationViewController.init(animationView:waitsForAnimationTrigger:)
           |
           +-- viewDidLoad()
           |      +-- wmf_addSubviewWithConstraintsToEdges(animationView)
           |
           +-- viewDidAppear()
           |      +-- animate() [waitsForAnimationTrigger=falseの場合]
           |
           +-- animate() [外部呼び出し]
                  +-- WelcomeAnimationView.animate()
                         +-- UIViewPropertyAnimator.startAnimation()
```

### データフロー図

```
[入力]                      [処理]                         [出力]

WelcomeAnimationView   --> WelcomeAnimationViewController --> 画面表示
                           |
                           +-- animate()トリガー
                           |
                           v
                       UIViewPropertyAnimator
                           |
                           v
                       AnimatedImageViewの
                       位置・透明度アニメーション
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| WelcomeAnimationViewController.swift | `Wikipedia/Code/WelcomeAnimationViewController.swift` | ソース | アニメーション画面のViewController |
| WelcomeAnimationView.swift | `Wikipedia/Code/WelcomeAnimationView.swift` | ソース | アニメーションビューの実装 |
| WelcomePageViewController.swift | `Wikipedia/Code/WMFWelcomePageViewController.swift` | ソース | オンボーディングのページング制御 |
| UIView+WMFSubviews.swift | `Wikipedia/Code/UIView+WMFSubviews.swift` | ソース | wmf_addSubviewWithConstraintsToEdges拡張 |
