# 機能設計書 64-編集ウェルカム

## 概要

本ドキュメントは、Wikipedia iOSアプリにおける「編集ウェルカム」機能の設計仕様を記載する。編集機能の紹介画面を提供し、ユーザーがWikipedia編集を始める際のガイダンスを行う。

### 本機能の処理概要

本機能は、ユーザーが初めて記事編集を行う際に、Wikipedia編集の基本原則（大胆であること、中立的な視点、信頼できる出典の引用、知識を自由にすること）を紹介するオンボーディングフローを提供する。

**業務上の目的・背景**：Wikipediaの編集は特有のルールとマナーがあり、新規編集者がこれらを理解することで質の高い貢献が可能になる。編集開始前に基本原則を案内することで、編集の品質向上とコミュニティとの良好な関係構築を支援する。

**機能の利用シーン**：
- 記事編集画面に初めてアクセスした際
- 編集機能のオンボーディングを表示する設定がONの場合
- 編集の基本原則を再確認したい場合（設定から）

**主要な処理内容**：
1. 「大胆であること」（Be Bold）ページの表示
2. 「中立的な視点で書く」（Impartial Tone）ページの表示
3. 「信頼できる出典を引用する」（Cite Reliable Sources）ページの表示
4. 「知識を自由にする」（Set Knowledge Free）ページの表示
5. アニメーション付きのビジュアル説明
6. ページ間のスワイプ/ボタンによるナビゲーション

**関連システム・外部連携**：
- UserDefaults: 編集ウェルカム表示済みフラグの保存

**権限による制御**：認証不要。編集を開始するすべてのユーザーに表示可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | EditingWelcome画面 | 主画面 | 編集機能の紹介画面 |

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| theme | Theme | Yes | 現在のテーマ設定 | nil不可 |
| completion | () -> Void | Yes | オンボーディング完了時のコールバック | nil不可 |

### 入力データソース

- UserDefaults: 編集ウェルカム表示済み状態の確認

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 編集ウェルカム表示済みフラグ | Bool | 編集ウェルカム完了状態 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. EditingWelcomeViewControllerの初期化
   └─ theme、completionを受け取る
   └─ 4つのDataSourceを生成

2. WelcomeViewControllerの初期化
   └─ 4つのWelcomeContainerViewControllerを生成
   └─ WelcomePageViewControllerでラップ

3. 各ページの表示
   └─ Page 1: Be Bold（大胆に編集）
   └─ Page 2: Impartial Tone（中立的な視点）
   └─ Page 3: Cite Reliable Sources（信頼できる出典）
   └─ Page 4: Set Knowledge Free（知識を自由に）

4. アニメーション再生
   └─ 各ページのpropertyAnimatorを実行
   └─ 画像のフェードイン、移動アニメーション

5. 完了処理
   └─ viewWillDisappearでcompletionを実行
   └─ モーダルを閉じる
```

### フローチャート

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

    C --> D[WelcomePageViewController]
    D --> E[Page 1: Be Bold]

    E --> F{ユーザー操作}
    F -->|Next/Swipe| G[Page 2: Impartial Tone]

    G --> H{ユーザー操作}
    H -->|Next/Swipe| I[Page 3: Cite Sources]

    I --> J{ユーザー操作}
    J -->|Next/Swipe| K[Page 4: Set Knowledge Free]

    K --> L[Get Started タップ]
    L --> M[completion実行]
    M --> N[dismiss]
    N --> Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-64-01 | 初回表示 | 編集ウェルカムは初回編集時に表示 | 編集ウェルカム未表示時 |
| BR-64-02 | アニメーション再生 | 各ページでアニメーションを自動再生 | ページ表示時 |
| BR-64-03 | 最初のページ識別 | isFirst=trueで最初のページを識別 | BeBoldDataSource |
| BR-64-04 | アクションボタン | 最初と最後のページのみアクションボタンを表示 | isFirst/isLast |

### 計算ロジック

アニメーション設定:
```swift
// BeBoldアニメーション
propertyAnimator = UIViewPropertyAnimator(duration: 0.8, curve: .easeInOut)
editAnimatedImageView.alpha = 1  // フェードイン
plusesAnimatedImageView.alpha = 1  // 遅延後フェードイン (delayFactor: 0.6)
```

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

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

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

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

#### UserDefaults

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| E-64-01 | 画像読み込み失敗 | アニメーション画像が見つからない | 画像なしで継続 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- アニメーション: 60fps維持
- ページ遷移: 滑らかなスワイプ対応
- 画像読み込み: バンドル内画像のため即時

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

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

## 備考

- コードベース実装（Storyboard不使用）
- WelcomeAnimationViewで共通アニメーション基盤を使用
- UIViewPropertyAnimatorによるモダンなアニメーション実装

---

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

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

### 推奨読解順序

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

各ページのDataSourceプロトコルを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | WelcomeContainerViewController.swift | `Wikipedia/Code/WelcomeContainerViewController.swift` | WelcomeContainerViewControllerDataSourceプロトコルを理解する |

**読解のコツ**:
- WelcomeContainerViewControllerDataSourceプロトコルがページの内容を定義
- animationView、panelViewController、isFirstプロパティが主要

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

EditingWelcomeViewControllerの実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | EditingWelcomeViewController.swift | `Wikipedia/Code/EditingWelcomeViewController.swift` | 4つのDataSourceとWelcomeViewController継承を理解する |

**主要処理フロー**:
- **4行目**: WelcomeViewControllerを継承
- **5-8行目**: 4つのDataSource（BeBold, ImpartialTone, CiteReliableSources, SetKnowledgeFree）を定義
- **10-16行目**: init(theme:completion:)で4ページのViewControllerを生成

#### Step 3: 各ページのDataSourceを理解する

BeBoldDataSourceを例に、DataSourceの実装パターンを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | EditingWelcomeViewController.swift | `Wikipedia/Code/EditingWelcomeViewController.swift` | BeBoldDataSourceの実装（行26-53）を理解する |

**主要処理フロー**:
- **27行目**: isFirst = true（最初のページ識別）
- **29-30行目**: WelcomeAnimatedImageViewでアニメーション画像を定義
- **32-34行目**: animationViewでWelcomeAnimationViewを構築
- **36-46行目**: propertyAnimatorでアニメーション動作を定義
- **48-52行目**: panelViewControllerでテキストコンテンツを定義

#### Step 4: アニメーション基盤を理解する

WelcomeAnimationViewの実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | WelcomeAnimationView.swift | `Wikipedia/Code/WelcomeAnimationView.swift` | 静的画像とアニメーション画像の組み合わせを理解する |

**読解のコツ**:
- staticImageNamed: 背景の静的画像
- animatedImageViews: アニメーションする画像の配列
- propertyAnimator: UIViewPropertyAnimatorによるアニメーション

#### Step 5: ベースクラスを理解する

WelcomeViewControllerの実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | WelcomeViewController.swift | `Wikipedia/Code/WelcomeViewController.swift` | ベースクラスの初期化とテーマ適用を理解する |

**主要処理フロー**:
- **7-11行目**: init(theme:viewControllers:completion:)で初期化
- **23-26行目**: viewWillDisappearでcompletionを実行
- **42-57行目**: Themeable準拠でテーマ適用

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

```
EditingWelcomeViewController
    │
    ├─ init(theme:completion:)
    │      │
    │      └─ super.init(theme:viewControllers:completion:)
    │             │
    │             └─ WelcomeViewController
    │                    │
    │                    └─ WelcomePageViewController
    │                           │
    │                           └─ [WelcomeContainerViewController]
    │
    └─ DataSources
           │
           ├─ BeBoldDataSource
           │      ├─ animationView (WelcomeAnimationView)
           │      │      ├─ staticImage: "be-bold/article"
           │      │      └─ animatedImageViews: [edit, pluses]
           │      ├─ propertyAnimator (UIViewPropertyAnimator)
           │      └─ panelViewController (WelcomePanelViewController)
           │
           ├─ ImpartialToneDataSource
           │      ├─ animationView (scale animation)
           │      ├─ propertyAnimator (rotation + translation)
           │      └─ panelViewController
           │
           ├─ CiteReliableSourcesDataSource
           │      ├─ animationView (highlight animation)
           │      ├─ propertyAnimator (fade in)
           │      └─ panelViewController
           │
           └─ SetKnowledgeFreeDataSource
                  ├─ animationView (articles spreading)
                  ├─ propertyAnimator (movement)
                  └─ panelViewController
```

### データフロー図

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

編集開始 ───▶ 編集ウェルカム表示判定 ───▶ 未表示時のみ表示
                      │
                      ▼
          EditingWelcomeViewController
                      │
                      ▼
           WelcomeViewController
                      │
                      ▼
         WelcomePageViewController
                      │
                      ▼
         ┌──────────────────────────┐
         │    ページ遷移ループ      │
         │  ┌────────────────────┐  │
         │  │ Page 1: Be Bold   │  │ ───▶ "大胆に編集しよう"
         │  │ Page 2: Impartial │  │ ───▶ "中立的な視点で"
         │  │ Page 3: Cite      │  │ ───▶ "出典を引用しよう"
         │  │ Page 4: Free      │  │ ───▶ "知識を自由に"
         │  └────────────────────┘  │
         └──────────────────────────┘
                      │
                      ▼
             completion ───▶ dismiss() ───▶ 編集画面
                      │
                      ▼
               UserDefaults ───▶ 表示済みフラグ保存
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| EditingWelcomeViewController.swift | `Wikipedia/Code/EditingWelcomeViewController.swift` | ソース | 編集ウェルカムのメインVC |
| WelcomeViewController.swift | `Wikipedia/Code/WelcomeViewController.swift` | ソース | ウェルカム画面のベースVC |
| WelcomePageViewController.swift | `Wikipedia/Code/WelcomePageViewController.swift` | ソース | ページング制御 |
| WelcomeContainerViewController.swift | `Wikipedia/Code/WelcomeContainerViewController.swift` | ソース | ページコンテナとDataSourceプロトコル |
| WelcomePanelViewController.swift | `Wikipedia/Code/WelcomePanelViewController.swift` | ソース | テキストパネル表示 |
| WelcomePanelLabelContentViewController.swift | `Wikipedia/Code/WelcomePanelLabelContentViewController.swift` | ソース | ラベルコンテンツ表示 |
| WelcomeAnimationView.swift | `Wikipedia/Code/WelcomeAnimationView.swift` | ソース | アニメーションビュー基盤 |
| WelcomeAnimationViewController.swift | `Wikipedia/Code/WelcomeAnimationViewController.swift` | ソース | アニメーションVC |
| editing-welcome/* | `Wikipedia/Images.xcassets/editing-welcome/` | 画像 | 編集ウェルカム用画像アセット |
