# 帳票設計書 3-Year in Review Most Read Date Shareable

## 概要

本ドキュメントは、Wikipedia iOSアプリケーションにおける「Year in Review Most Read Date Shareable」帳票の設計仕様を定義する。この帳票は最も読書した日時・曜日・月の統計を共有可能な画像として生成する機能を提供する。

### 本帳票の処理概要

本帳票は、ユーザーの一年間のWikipedia閲覧パターンを分析し、最も読書活動が活発だった時間帯、曜日、月を視覚的に表現した共有可能な画像を生成する機能である。

**業務上の目的・背景**：ユーザーの読書習慣を可視化することで、自己の学習パターンへの気づきを促す。時間帯・曜日・月という3つの軸で読書傾向を示すことで、ユーザーが自身の知的活動を客観的に振り返ることができる。SNS共有により、友人やフォロワーとの共通点や違いを発見する楽しみも提供する。

**帳票の利用シーン**：Year in Review機能において、読書パターンスライドの内容をソーシャルメディアで共有したい場合に使用される。「あなたが最もWikipediaを読んだのは○曜日の○時」といった個人的な統計を友人と共有できる。

**主要な出力内容**：
1. Wikipediaロゴ（W-share-logo）とヘッダー部
2. 時計をモチーフにしたGIF画像（clock）
3. タイトルテキスト（読書パターンの概要）
4. 3つの統計項目：最も読んだ時間帯、曜日、月
5. フッター部（globeアイコン、ハッシュタグ）

**帳票の出力タイミング**：Year in Review画面のMost Read Dateスライド表示中に、ユーザーが「Share」ボタンをタップした時点で画像が生成される。

**帳票の利用者**：Wikipediaアプリのログインユーザー（一年間で閲覧記録がある程度蓄積されたユーザー）

## 帳票種別

共有画像（読書パターン統計カード画像）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | Year in Review Most Read Date Slide View | WMFYearInReviewSlideMostReadDateV3View | Shareボタンタップ |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | PNG（UIImage） |
| 用紙サイズ | 402 x 847ポイント（最小高さ） |
| 向き | 縦 |
| ファイル名 | システム生成（UIActivityViewController経由） |
| 出力方法 | UIActivityViewController（共有シート） |
| 文字コード | UTF-8 |

### 画像固有設定

| 項目 | 内容 |
|-----|------|
| スケール | UIScreen.main.scale（デバイス解像度対応） |
| 背景色 | theme.paperBackground |
| レンダリング | SwiftUI ImageRenderer |

## 帳票レイアウト

### レイアウト概要

縦長のカード形式で、ヘッダー、GIF画像、統計項目、フッターの構成となっている。

```
┌─────────────────────────────────────┐
│         W-share-logo (50pt)         │
│              ヘッダー部               │
├─────────────────────────────────────┤
│                                     │
│         clock GIF画像                │
│                                     │
├─────────────────────────────────────┤
│         タイトル（boldTitle1）        │
│    "Your reading pattern in 2024"   │
├─────────────────────────────────────┤
│  時間帯: 10 PM                       │
│  (Most active time)                 │
│                                     │
│  曜日: Saturday                      │
│  (Favorite day)                     │
│                                     │
│  月: December                        │
│  (Most read month)                  │
│              統計項目部               │
├─────────────────────────────────────┤
│  [globe]  #WikipediaYearInReview    │
│              フッター部               │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | Wikipediaロゴ | W-share-logoアセット | Bundle.module | Image 50pt高さ |
| 2 | GIF画像 | 時計モチーフ画像 | viewModel.gifName | 可変幅 |

### 明細部（統計項目）

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | タイトル | 読書パターン概要 | viewModel.title | boldTitle1フォント | 全幅-56pt |
| 2 | 時間帯 | 最も読んだ時間 | viewModel.time | georgiaTitle3フォント | 全幅 |
| 3 | 時間帯フッター | 説明テキスト | viewModel.timeFooter | subheadlineフォント | 全幅 |
| 4 | 曜日 | 最も読んだ曜日 | viewModel.day | georgiaTitle3フォント | 全幅 |
| 5 | 曜日フッター | 説明テキスト | viewModel.dayFooter | subheadlineフォント | 全幅 |
| 6 | 月 | 最も読んだ月 | viewModel.month | georgiaTitle3フォント | 全幅 |
| 7 | 月フッター | 説明テキスト | viewModel.monthFooter | subheadlineフォント | 全幅 |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | Globeアイコン | 地球儀アイコン | Bundle.module | 50x50pt |
| 2 | ハッシュタグ | キャンペーンタグ | hashtag | boldTitle3、リンク色 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| viewModel | WMFYearInReviewSlideMostReadDateV3ViewModel | Yes |
| hashtag | 共有用ハッシュタグ文字列 | Yes |
| mostReadDay.viewCount > 0 | 曜日の閲覧数が1以上 | Yes |
| mostReadTime.viewCount > 0 | 時間帯の閲覧数が1以上 | Yes |
| mostReadMonth.viewCount > 0 | 月の閲覧数が1以上 | Yes |

### ソート順

該当なし（単一画像出力のため）

### 改ページ条件

該当なし（単一画像出力のため）

## データベース参照仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| CDYearInReviewReport | 年間レポートデータ | year = 対象年 |
| CDYearInReviewSlide | スライドデータ（mostReadDate） | report.year = 対象年, id = "mostReadDate" |

### テーブル別参照項目詳細

#### CDYearInReviewSlide (mostReadDate)

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| data | WMFPageViewDates | Binary | JSON形式 |

### WMFPageViewDates構造

| フィールド | 型 | 説明 |
|-----------|-----|------|
| days | [WMFPageViewDay] | 曜日別閲覧統計 |
| times | [WMFPageViewTime] | 時間帯別閲覧統計 |
| months | [WMFPageViewMonth] | 月別閲覧統計 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| 画像スケール | UIScreen.main.scale | - | デバイス解像度に応じた値 |
| 提案サイズ幅 | 402ポイント固定 | - | レンダラー設定 |
| 最多時間帯 | max(times, by: viewCount) | - | 複数同数の場合は先頭 |
| 最多曜日 | max(days, by: viewCount) | - | 複数同数の場合は先頭 |
| 最多月 | max(months, by: viewCount) | - | 複数同数の場合は先頭 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[Shareボタンタップ] --> B[tappedShare呼び出し]
    B --> C{スライドタイプ判定}
    C -->|mostReadDateV3| D[WMFYearInReviewSlideMostReadDateV3ShareableView生成]
    D --> E[ImageRenderer初期化]
    E --> F[proposedSize設定 402x nil]
    F --> G[scale設定 UIScreen.main.scale]
    G --> H[renderer.uiImage取得]
    H --> I{画像生成成功?}
    I -->|Yes| J[coordinatorDelegate.share呼び出し]
    I -->|No| K[処理終了]
    J --> L[UIActivityViewController表示]
    L --> M[終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 画像生成失敗 | renderer.uiImageがnil | なし（サイレント失敗） | 処理を中断 |
| データ不足 | viewCount = 0 | なし | スライド自体が表示されない |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1件/回 |
| 目標出力時間 | 1秒以内 |
| 同時出力数上限 | 1件 |

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

- 個人情報：ユーザーの読書パターン（時間帯、曜日、月）を含む
- プライバシー：読書習慣から生活リズムが推測される可能性
- アクセス制御：ユーザーの明示的な操作（Shareボタンタップ）が必要
- 出力ログ：loggingDelegateを通じてlogYearInReviewDidTapShareで記録

## 備考

- Georgiaフォントを使用した日付・時間表示でエレガントな印象を演出
- 各統計項目は2段構成（値+説明文）で可読性を確保
- スライドの表示条件として、すべての統計カテゴリで閲覧数が1以上必要

---

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

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

### 推奨読解順序

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

まず、プログラム間で受け渡されるデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | WMFYearInReviewMostReadDateV3ViewModel.swift | `WMFComponents/Sources/WMFComponents/Components/Year in Review/View Models/WMFYearInReviewMostReadDateV3ViewModel.swift` | ViewModelのプロパティ構成（time, day, month, 各footer）を理解 |

**読解のコツ**: 時間帯・曜日・月の3軸データ構造と、それぞれのフッターテキストの関係を把握する。

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

処理の起点となるファイル・関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | WMFYearInReviewViewModel.swift | `WMFComponents/Sources/WMFComponents/Components/Year in Review/View Models/WMFYearInReviewViewModel.swift` | tappedShare()関数内のmostReadDateV3ケース（行972-979）が共有処理 |

**主要処理フロー**:
1. **行972**: mostReadDateV3スライドの場合の分岐
2. **行973**: WMFYearInReviewSlideMostReadDateV3ShareableViewを生成
3. **行974-979**: ImageRendererで画像化、coordinatorDelegate.share呼び出し

#### Step 3: 共有可能ビューの構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | WMFYearInReviewSlideMostReadDateV3ShareableView.swift | `WMFComponents/Sources/WMFComponents/Components/Year in Review/Views/Shareable Slide Views/WMFYearInReviewSlideMostReadDateV3ShareableView.swift` | SwiftUIビューの構造、dateItemView関数を理解 |

**主要処理フロー**:
- **行24-32**: dateItemView関数 - 値とフッターの2段構成ビュー
- **行34-49**: body定義 - header(), content(), footer()の組み合わせ
- **行51-66**: header()関数 - ロゴとGIF画像
- **行68-86**: content()関数 - タイトルと3つの統計項目
- **行88-107**: footer()関数 - globeとハッシュタグ

#### Step 4: データ取得・変換処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | WMFYearInReviewViewModel.swift | `WMFComponents/Sources/WMFComponents/Components/Year in Review/View Models/WMFYearInReviewViewModel.swift` 行419-444 | mostReadDateケースのデータ処理 |

**主要処理フロー**:
- **行419-427**: WMFPageViewDatesをデコード、各最大値を取得
- **行429-430**: highlightsFavoriteReadingDayに代入
- **行431-443**: ViewModelを生成、ローカライズ文字列を適用

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

```
WMFYearInReviewView (UI)
    │
    ├─ WMFYearInReviewViewModel.tappedShare()
    │      │
    │      ├─ case .mostReadDateV3(let viewModel)
    │      │
    │      ├─ WMFYearInReviewSlideMostReadDateV3ShareableView(viewModel:hashtag:)
    │      │      │
    │      │      └─ body: View
    │      │             ├─ header()
    │      │             │     ├─ Image("W-share-logo")
    │      │             │     └─ Image(viewModel.gifName)
    │      │             ├─ content()
    │      │             │     ├─ Text(viewModel.title)
    │      │             │     ├─ dateItemView(time, timeFooter)
    │      │             │     ├─ dateItemView(day, dayFooter)
    │      │             │     └─ dateItemView(month, monthFooter)
    │      │             └─ footer()
    │      │                   └─ HStack [globe + hashtag]
    │      │
    │      ├─ ImageRenderer(content: view)
    │      │      └─ renderer.uiImage
    │      │
    │      └─ coordinatorDelegate.handleYearInReviewAction(.share(image:))
    │
    └─ UIActivityViewController (システム共有シート)
```

### データフロー図

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

WMFPageViewDates ───────▶ JSONDecoder                     ユーザー共有先
  │                            │                         (Twitter/Facebook等)
  ├─ days[]                    ▼
  ├─ times[]              max(viewCount) 計算
  └─ months[]                  │
                               ▼
                    WMFYearInReviewSlide
                    MostReadDateV3ViewModel
                          │
                          ├─ time, timeFooter
                          ├─ day, dayFooter
                          └─ month, monthFooter
                               │
                               ▼
                    WMFYearInReviewSlide
                    MostReadDateV3ShareableView
                               │
hashtag ──────────────────────▶│
                               ▼
                          ImageRenderer
                               │
                               ▼
                          UIImage
                               │
                               ▼
                    UIActivityViewController
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| WMFYearInReviewSlideMostReadDateV3ShareableView.swift | `WMFComponents/Sources/WMFComponents/Components/Year in Review/Views/Shareable Slide Views/` | ソース | 共有用ビュー定義 |
| WMFYearInReviewMostReadDateV3ViewModel.swift | `WMFComponents/Sources/WMFComponents/Components/Year in Review/View Models/` | ソース | 読書パターンViewModel |
| WMFYearInReviewViewModel.swift | `WMFComponents/Sources/WMFComponents/Components/Year in Review/View Models/` | ソース | 共有処理ロジック |
| WMFYearInReviewSlideMostReadDateV3View.swift | `WMFComponents/Sources/WMFComponents/Components/Year in Review/Views/Slide Views/` | ソース | 表示用ビュー |
| WMFYearInReviewSlide.swift | `WMFData/Sources/WMFData/Models/Year In Review/` | ソース | スライドモデル |
