# 機能設計書 65-説明追加ウェルカム

## 概要

本ドキュメントは、Wikipedia iOSアプリにおける「説明追加ウェルカム」機能の設計仕様を記載する。説明文追加機能（Wikidata短い説明文）の紹介画面を提供するものである。

### 本機能の処理概要

本機能は、ユーザーが初めて記事の説明文（Wikidata description）追加機能を利用する際に、その目的と使い方を紹介するオンボーディングフローを提供する。2ページ構成のシンプルな紹介画面で、説明文の役割と追加方法を案内する。

**業務上の目的・背景**：Wikipediaの記事には「短い説明文」（Wikidata description）を追加できる。これはWikipediaの検索結果やモバイルアプリでの記事一覧表示で使用される重要なメタデータである。ユーザーがこの機能を理解し適切に利用できるよう、初回利用時に案内を行う。

**機能の利用シーン**：
- 記事の説明文を初めて追加しようとした際
- 説明追加機能のオンボーディング設定がONの場合
- 機能の使い方を再確認したい場合

**主要な処理内容**：
1. 導入画面（Intro）の表示：説明文機能の概要紹介
2. 探索画面（Exploration）の表示：説明文の具体的な使い方
3. ページ間のスワイプ/ボタンによるナビゲーション
4. オンボーディング完了後の説明編集画面への遷移

**関連システム・外部連携**：
- UserDefaults: 説明追加ウェルカム表示済みフラグの保存
- Wikidata API: 説明文の取得・更新（本機能では直接呼び出さない）

**権限による制御**：認証不要で表示可能。実際の説明追加はログインが必要な場合あり。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 63 | DescriptionWelcomeContainer画面 | 主画面 | 説明追加機能の紹介 |
| 64 | DescriptionWelcomePanel画面 | 補助画面 | 説明追加機能の各ステップ |

## 機能種別

画面表示 / オンボーディング / ユーザー教育

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| theme | Theme | No | 現在のテーマ設定 | デフォルト: Theme.standard |
| completionBlock | (() -> Void)? | No | オンボーディング完了時のコールバック | - |

### 入力データソース

- Storyboard: DescriptionWelcome.storyboardからのUI定義読み込み
- UserDefaults: 説明追加ウェルカム表示済み状態の確認

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 説明追加ウェルカム表示済みフラグ | Bool | オンボーディング完了状態 |

### 出力先

- UserDefaults: 表示済みフラグの永続化
- 画面表示: 2ページのオンボーディングUI

## 処理フロー

### 処理シーケンス

```
1. DescriptionWelcomePageViewControllerの初期化
   └─ dataSource、delegateを設定
   └─ 2ページのpageControllersを構築

2. 各ページの表示
   └─ Page 1: Intro - 説明文機能の紹介
   └─ Page 2: Exploration - 説明文の使い方

3. DescriptionWelcomeContainerViewControllerの表示
   └─ DescriptionWelcomePanelViewController（テキスト）
   └─ DescriptionWelcomeImageViewController（画像）

4. ページ遷移
   └─ スワイプまたはNextボタンで次ページへ
   └─ Skipボタンで全スキップ可能

5. 最終ページでの完了処理
   └─ completionBlockの実行
   └─ モーダルを閉じる
```

### フローチャート

```mermaid
flowchart TD
    A[説明追加開始] --> B{説明追加ウェルカム表示済み?}
    B -->|Yes| Z[説明編集画面表示]
    B -->|No| C[DescriptionWelcomePageViewController]

    C --> D[Page 1: Intro]

    D --> E{ユーザー操作}
    E -->|Next/Swipe| F[Page 2: Exploration]
    E -->|Skip| Y[オンボーディング完了]

    F --> G{ユーザー操作}
    G -->|Complete/次へ| Y
    G -->|Skip| Y

    Y --> H[completionBlock実行]
    H --> I[dismiss]
    I --> Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-65-01 | 2ページ構成 | 説明追加ウェルカムは2ページで構成 | 常時 |
| BR-65-02 | フェードインアニメーション | 2ページ目はフェードインで表示 | ページ遷移時 |
| BR-65-03 | スキップ許可 | どのページからでもスキップ可能 | 任意のページ表示中 |
| BR-65-04 | 最終ページでボタン非表示 | 最終ページではNext/Skip/PageControlを非表示 | 最終ページ表示時 |

### 計算ロジック

ページ表示制御:
```swift
// フェードインアニメーション判定
func shouldFadeInAndUp() -> Bool {
    switch pageType {
    case .intro:
        return false  // 最初のページはフェードインなし
    case .exploration:
        return true   // 2ページ目はフェードイン
    }
}
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 表示済み確認 | UserDefaults | SELECT | 説明追加ウェルカム表示済み状態の取得 |
| 表示済み保存 | UserDefaults | UPDATE | 説明追加ウェルカム完了の記録 |

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

#### UserDefaults

| 操作 | 項目（キー名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT/UPDATE | hasShownDescriptionWelcome | Bool | 説明追加ウェルカム表示済みフラグ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| E-65-01 | Storyboard読み込み失敗 | DescriptionWelcome.storyboardが見つからない | アサーション失敗（開発時検出） |

### リトライ仕様

説明追加ウェルカムにリトライは不要。エラー時は完了として扱い説明編集画面へ遷移。

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

設定の保存はUserDefaultsへの単一書き込みで行う。

## パフォーマンス要件

- ページ遷移アニメーション: 60fps維持
- フェードイン/アップアニメーション: 0.4秒、0.1秒遅延

## セキュリティ考慮事項

- 設定情報はローカルのみに保存
- 外部への情報送信なし

## 備考

- Storyboard（DescriptionWelcome.storyboard）ベースの実装
- 初回起動ウェルカム（No.63）と同様のUIパターン
- 2ページのみのシンプルな構成

---

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

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

### 推奨読解順序

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

説明追加ウェルカムのページタイプを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DescriptionWelcomePageViewController.swift | `Wikipedia/Code/DescriptionWelcomePageViewController.swift` | DescriptionWelcomePageType enumで2種類のページを定義 |

**読解のコツ**:
- DescriptionWelcomePageType（intro/exploration）がページ種別を表す
- DescriptionWelcomeNavigationDelegateプロトコルでページ遷移を通知

**主要処理フロー**:
- **3-6行目**: DescriptionWelcomePageType enum定義
- **8-10行目**: DescriptionWelcomeNavigationDelegateプロトコル定義

#### Step 2: ページングを理解する

DescriptionWelcomePageViewControllerの実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | DescriptionWelcomePageViewController.swift | `Wikipedia/Code/DescriptionWelcomePageViewController.swift` | ページ配列とナビゲーション処理を理解する |

**主要処理フロー**:
- **48-56行目**: containerControllerForWelcomePageType()でページVC生成
- **58-63行目**: pageControllers lazy配列で2ページを管理
- **33-46行目**: showNextWelcomePage()でページ遷移
- **150-158行目**: nextButtonTapped/skipButtonTappedのハンドリング
- **191-202行目**: hideButtons()で最終ページのボタン制御

#### Step 3: コンテナを理解する

DescriptionWelcomeContainerViewControllerの実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | DescriptionWelcomeContainerViewController.swift | `Wikipedia/Code/DescriptionWelcomeContainerViewController.swift` | ページコンテンツとアニメーションの管理を理解する |

**主要処理フロー**:
- **13行目**: pageTypeプロパティ
- **21-34行目**: viewWillAppear/viewDidAppearでフェードインアニメーション
- **36-43行目**: shouldFadeInAndUp()でアニメーション対象判定
- **53-58行目**: useBottomAlignmentIfPhone()でiPhone対応
- **60-68行目**: prepare(for:sender:)で子VCに設定を渡す

#### Step 4: パネルを理解する

DescriptionWelcomePanelViewControllerの実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | DescriptionWelcomePanelViewController.swift | `Wikipedia/Code/DescriptionWelcomePanelViewController.swift` | テキストコンテンツとボタンの表示を理解する |

#### Step 5: 画像を理解する

DescriptionWelcomeImageViewControllerの実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | DescriptionWelcomeImageViewController.swift | `Wikipedia/Code/DescriptionWelcomeImageViewController.swift` | ページタイプに応じた画像表示を理解する |

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

```
DescriptionWelcomePageViewController
    │
    ├─ pageControllers (lazy)
    │      │
    │      ├─ DescriptionWelcomeContainerViewController (.intro)
    │      │      │
    │      │      ├─ prepare(for:sender:)
    │      │      │      ├─ DescriptionWelcomePanelViewController
    │      │      │      └─ DescriptionWelcomeImageViewController
    │      │      │
    │      │      └─ next(withSender:)
    │      │             └─ welcomeNavigationDelegate?.showNextWelcomePage()
    │      │
    │      └─ DescriptionWelcomeContainerViewController (.exploration)
    │             │
    │             ├─ prepare(for:sender:)
    │             │      ├─ DescriptionWelcomePanelViewController
    │             │      │      └─ nextButtonAction
    │             │      └─ DescriptionWelcomeImageViewController
    │             │
    │             └─ フェードインアニメーション
    │
    ├─ showNextWelcomePage()
    │      └─ setViewControllers()
    │
    └─ hideButtons()
           └─ UIView.animate()
```

### データフロー図

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

説明追加開始 ───▶ 説明追加ウェルカム表示判定 ───▶ 未表示時のみ表示
                      │
                      ▼
         DescriptionWelcomePageVC
                      │
                      ▼
         ┌──────────────────────────┐
         │    ページ遷移ループ      │
         │  ┌────────────────────┐  │
         │  │ Page 1: Intro     │  │ ───▶ 説明文機能の紹介
         │  │ Page 2: Exploration│  │ ───▶ 説明文の使い方
         │  └────────────────────┘  │
         └──────────────────────────┘
                      │
                      ▼
             completionBlock ───▶ dismiss() ───▶ 説明編集画面
                      │
                      ▼
               UserDefaults ───▶ 表示済みフラグ保存
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| DescriptionWelcomePageViewController.swift | `Wikipedia/Code/DescriptionWelcomePageViewController.swift` | ソース | ページングを管理するPageViewController |
| DescriptionWelcomeContainerViewController.swift | `Wikipedia/Code/DescriptionWelcomeContainerViewController.swift` | ソース | 各ページのコンテナVC |
| DescriptionWelcomePanelViewController.swift | `Wikipedia/Code/DescriptionWelcomePanelViewController.swift` | ソース | テキストパネル表示 |
| DescriptionWelcomeImageViewController.swift | `Wikipedia/Code/DescriptionWelcomeImageViewController.swift` | ソース | 画像表示 |
| DescriptionWelcomeContentsViewController.swift | `Wikipedia/Code/DescriptionWelcomeContentsViewController.swift` | ソース | コンテンツ管理 |
| DescriptionWelcomeInitialViewController.swift | `Wikipedia/Code/DescriptionWelcomeInitialViewController.swift` | ソース | 初期VC（言語選択等） |
| UIViewController+DescriptionWelcomeStoryboard.swift | `Wikipedia/Code/UIViewController+DescriptionWelcomeStoryboard.swift` | ソース | Storyboardからのインスタンス化 |
| DescriptionWelcome.storyboard | `Wikipedia/iOS Native/DescriptionWelcome.storyboard` | Storyboard | 説明追加ウェルカムUI定義 |
