# 機能設計書 53-年間まとめ

## 概要

本ドキュメントは、Wikipedia iOSアプリにおけるYear in Review（年間まとめ）機能の設計を記述する。この機能は、ユーザーの年間利用統計を視覚的にまとめて表示するインタラクティブな機能である。

### 本機能の処理概要

**業務上の目的・背景**：Year in Review機能は、ユーザーが1年間にWikipediaをどのように利用したかを振り返ることができる機能である。ユーザーエンゲージメントを高め、Wikipediaへの貢献（編集や寄付）を促進することを目的としている。パーソナライズされた統計情報と全体統計を組み合わせて、ユーザーの利用体験を可視化する。

**機能の利用シーン**：年末年始の期間に、Explore画面やプロファイル画面からYear in Reviewにアクセス可能。ユーザーはスライド形式で自分の年間統計（読んだ記事数、読書時間、保存記事、編集回数等）を閲覧し、ハイライトを共有できる。

**主要な処理内容**：
1. Year in Reviewデータの取得と生成
2. イントロスライドの表示（ログイン誘導を含む）
3. パーソナライズされたスライドの表示（読書統計、編集統計等）
4. 全体統計スライドの表示（Wikipedia全体の統計）
5. ハイライトの画像生成と共有
6. 寄付フローへの誘導
7. アンケート調査の表示

**関連システム・外部連携**：
- WMFYearInReviewDataController（データ管理）
- MediaWiki API（ユーザー統計取得）
- 共有機能（UIActivityViewController）

**権限による制御**：ログインユーザーはパーソナライズされた統計を閲覧可能。未ログインユーザーも全体統計は閲覧可能だが、ログイン誘導が表示される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Explore画面 | 起点画面 | Year in Reviewへの遷移 |
| - | プロファイル画面 | 起点画面 | Year in Reviewへの遷移 |

## 機能種別

データ表示 / 共有機能 / アナリティクス

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| navigationController | UINavigationController | Yes | ナビゲーションコントローラ | nil不可 |
| theme | Theme | Yes | 現在のテーマ | nil不可 |
| dataStore | MWKDataStore | Yes | データストア | nil不可 |
| dataController | WMFYearInReviewDataController | Yes | YiRデータコントローラ | nil不可 |

### 入力データソース

- ローカル保存されたYear in Reviewレポートデータ
- MediaWiki APIからのユーザー統計
- アプリ設定（言語、国コード）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| slides | [WMFYearInReviewSlide] | 表示するスライドの配列 |
| shareImage | UIImage | 共有用のハイライト画像 |

### 出力先

Year in Reviewモーダル画面、共有シート

## 処理フロー

### 処理シーケンス

```
1. Year in Reviewボタンタップ
   └─ YearInReviewCoordinator.start()
2. ViewModelの生成
   └─ WMFYearInReviewViewModelの初期化
3. イントロスライド表示
   └─ ログイン状態に応じた表示
4a. ログイン済みの場合
   └─ レポートデータ取得、パーソナライズスライド表示
4b. 未ログインの場合
   └─ ログイン誘導 or 全体統計のみ表示
5. スライドナビゲーション
   └─ Next/Doneボタンでスライド遷移
6. 共有ボタンタップ時
   └─ ハイライト画像生成、共有シート表示
7. 寄付ボタンタップ時
   └─ DonateCoordinatorで寄付フロー開始
8. 完了時
   └─ アンケート調査表示（条件付き）
```

### フローチャート

```mermaid
flowchart TD
    A[Year in Reviewボタン] --> B[Coordinator.start]
    B --> C[イントロスライド表示]
    C --> D{Get Started タップ}
    D --> E{ログイン済み?}
    E -->|Yes| F[レポートデータ取得]
    E -->|No| G{ログイン誘導実験}
    G -->|ログイン必要| H[ログイン画面]
    G -->|スキップ可| I[全体統計スライド]
    H --> J{ログイン成功?}
    J -->|Yes| F
    J -->|No| I
    F --> K[パーソナライズスライド]
    K --> L[全体統計スライド]
    I --> L
    L --> M[ハイライトスライド]
    M --> N{共有?}
    N -->|Yes| O[共有シート]
    N -->|No| P[完了]
    O --> P
    P --> Q{アンケート表示?}
    Q -->|Yes| R[アンケート]
    Q -->|No| S[終了]
    R --> S
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-53-01 | 対象年 | 設定された対象年のデータを表示 | 常時 |
| BR-53-02 | パーセンタイル計算 | 読書量に応じたパーセンタイル表示 | 読書統計スライド |
| BR-53-03 | 貢献者報酬 | 編集者/寄付者には特別アイコンを提供 | 貢献者スライド |
| BR-53-04 | ログイン実験 | A/Bテストでログイン誘導を制御 | 未ログインユーザー |
| BR-53-05 | アンケート表示 | 2スライド以上閲覧した場合に表示 | 完了時 |

### 計算ロジック

- パーセンタイル計算: 設定ファイルのtopReadPercentagesに基づき計算
- 読書時間: 記事閲覧回数から推定

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| レポート取得 | YearInReviewReport | SELECT | 年間レポートデータ取得 |
| レポート保存 | YearInReviewReport | INSERT/UPDATE | レポートデータ保存 |
| レポート削除 | YearInReviewReport | DELETE | 設定OFFで全削除 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| dataLoadError | データ取得エラー | レポート取得失敗 | デフォルトスライド表示 |
| networkError | ネットワークエラー | API通信失敗 | エラーメッセージ表示 |

### リトライ仕様

データ取得失敗時は全体統計スライドのみ表示

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

レポートデータの保存はCore Dataコンテキストで管理

## パフォーマンス要件

- スライドは縦向き固定（forcePortrait）
- 画像生成は非同期で実行

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

- ユーザー統計はローカル保存
- 共有画像には個人を特定する情報を含めない

## 備考

Year in Reviewは年次機能であり、対象年（targetYear）は設定で管理される。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | WMFYearInReviewSlide.swift | `WMFData/Sources/WMFData/Models/Year In Review/` | スライドデータモデル |
| 1-2 | WMFYearInReviewReport.swift | `WMFData/Sources/WMFData/Models/Year In Review/` | レポートデータモデル |

**読解のコツ**: スライドは種類ごとに異なるデータを持つ

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | YearInReviewCoordinator.swift | `Wikipedia/Code/YearInReviewCoordinator.swift` | メインコーディネータ |

**主要処理フロー**:
1. **778-819行目**: start() - Year in Review表示開始
2. **83-182行目**: localizedStrings - ローカライズ文字列生成
3. **831-857行目**: populateYearInReviewReport() - レポートデータ取得

#### Step 3: ビュー層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | WMFYearInReviewView.swift | `WMFComponents/Sources/WMFComponents/Components/Year in Review/Views/` | メインビュー |
| 3-2 | WMFYearInReviewViewModel.swift | `WMFComponents/Sources/WMFComponents/Components/Year in Review/View Models/` | ビューモデル |

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

```
ExploreViewController / ProfileCoordinator
    │
    └─ YearInReviewCoordinator
           ├─ start()
           │      ├─ WMFYearInReviewViewModel初期化
           │      ├─ WMFYearInReviewView作成
           │      └─ UIHostingController表示
           │
           ├─ handleYearInReviewAction()
           │      ├─ donate() → DonateCoordinator
           │      ├─ share() → UIActivityViewController
           │      └─ dismiss()
           │
           └─ populateYearInReviewReport()
                  └─ WMFYearInReviewDataController
```

### データフロー図

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

YiRボタン ───▶ YearInReviewCoordinator ───▶ WMFYearInReviewDataController
タップ            │                                │
                 │                                ▼
                 │                          レポートデータ
                 │                                │
                 ▼                                ▼
        WMFYearInReviewViewModel ───▶ WMFYearInReviewView
                 │                          (SwiftUI)
                 │                                │
                 ▼                                ▼
           共有画像生成 ───▶ UIActivityViewController
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| YearInReviewCoordinator.swift | `Wikipedia/Code/` | ソース | フロー制御 |
| YearInReviewSettingsViewController.swift | `Wikipedia/Code/` | ソース | 設定画面 |
| WMFYearInReviewDataController.swift | `WMFData/` | ソース | データ管理 |
| WMFYearInReviewView.swift | `WMFComponents/` | ソース | メインビュー |
| WMFYearInReviewViewModel.swift | `WMFComponents/` | ソース | ビューモデル |
| YearInReviewCoordinatorDelegate.swift | `WMFComponents/` | ソース | デリゲート |
| DonateFunnel.swift | `Wikipedia/Code/` | ソース | アナリティクス |
