# 帳票設計書 5-Share-a-Fact Card

## 概要

本ドキュメントは、Wikipedia iOSアプリケーションにおける「Share-a-Fact Card」帳票の設計仕様を定義する。この帳票は記事から選択したテキストを引用形式のカードとして画像化し共有する機能を提供する。

### 本帳票の処理概要

本帳票は、ユーザーがWikipedia記事内で選択したテキストを、視覚的に魅力的な引用カードとして画像化し、SNS等で共有できるようにする機能である。

**業務上の目的・背景**：Wikipediaの豊富なコンテンツをより多くの人に広めるため、記事内の興味深い事実や情報を引用カード形式で共有できるようにする。「Share-a-Fact」（事実を共有）というコンセプトで、知識の拡散と新規ユーザーの獲得を促進する。

**帳票の利用シーン**：記事閲覧中にユーザーがテキストを選択し、コンテキストメニューから「Share-a-Fact」を選択した場合に使用される。選択したテキストが引用形式のカードとして画像化され、画像単体またはテキスト付きでSNS共有できる。

**主要な出力内容**：
1. 記事タイトル
2. 選択されたテキスト（引用文）
3. 関連画像（存在する場合）
4. 画像ライセンス情報
5. 記事ライセンス情報（CC BY-SA）
6. Wikipediaワードマークと「Made with the Wikipedia app」表記

**帳票の出力タイミング**：記事閲覧中にテキスト選択後、コンテキストメニューから「Share-a-Fact」を選択した時点でカード画像が生成される。

**帳票の利用者**：Wikipediaアプリの全ユーザー

## 帳票種別

共有画像（引用カード画像）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | Article View | ArticleViewController | テキスト選択後、コンテキストメニュー「Share-a-Fact」 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | PNG（UIImage） |
| 用紙サイズ | デバイス画面サイズ依存 |
| 向き | 横（画像あり）/ 縦（画像なし） |
| ファイル名 | システム生成（UIActivityViewController経由） |
| 出力方法 | UIActivityViewController（共有シート） |
| 文字コード | UTF-8 |

### 画像固有設定

| 項目 | 内容 |
|-----|------|
| 背景色 | theme.paperBackground |
| レンダリング | UIView snapshot |

## 帳票レイアウト

### レイアウト概要（画像あり）

2列レイアウトで、左側にテキスト、右側に画像を配置。

```
┌──────────────────────────────────────────────┐
│  Article Title          │                    │
│──────────────────────────│     [Image]        │
│                          │                    │
│  "Selected quote text    │                    │
│   from the article..."   │                    │
│                          │                    │
│  [CC][BY][SA]            │  [License Icons]   │
│                          │  Made with Wikipedia│
│  [W] Made with Wikipedia │                    │
└──────────────────────────────────────────────┘
```

### レイアウト概要（画像なし）

1列レイアウトで、テキストのみを中央に配置。

```
┌─────────────────────────────────────┐
│         Article Title               │
│─────────────────────────────────────│
│                                     │
│  "Selected quote text               │
│   from the article..."              │
│                                     │
│  [CC][BY][SA]  [W] Made with Wikipedia│
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | 記事タイトル | 記事のタイトル | articleTitle | 標準フォント |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | セパレータ | 区切り線 | - | theme.border色 | 全幅 |
| 2 | 引用テキスト | 選択されたテキスト | text | title3/callout（長さ依存） | 画像有:50%、無:全幅 |
| 3 | 関連画像 | 記事に関連する画像 | image | アスペクト比維持 | 約50% |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | 記事ライセンス | CC BY-SAアイコン | 固定値 | LicenseView |
| 2 | 画像ライセンス | 画像のライセンスアイコン | imageLicense.code | LicenseView（白色） |
| 3 | Wマーク | Wikipediaワードマーク | アセット | imageWordmarkView |
| 4 | 作成表記 | "Made with the Wikipedia app" | ローカライズ文字列 | imageMadeWithLabel |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| articleURL | 記事のURL | Yes |
| articleTitle | 記事のタイトル | No |
| text | 選択されたテキスト | No |
| image | 関連画像 | No |
| imageLicense | 画像のライセンス情報 | No |

### テキスト長による表示調整

| 条件 | フォント | 動作 |
|------|---------|------|
| 高さ <= 60%画面高さ | title3 | 通常表示 |
| 高さ > 60%画面高さ | callout | 縮小表示、省略記号追加 |

### ソート順

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

### 改ページ条件

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

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

この帳票はデータベースを直接参照しない。記事コンテンツとユーザー選択テキストから生成される。

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| テキスト表示幅 | isImageViewHidden ? view.bounds.width : view.bounds.width * 0.5 | round | 画像有無で切り替え |
| フォントサイズ判定 | sizeThatFits.height > view.bounds.height * 0.6 | - | 60%超でcalloutに縮小 |
| レターボックス余白 | (view.bounds.height - 画像高さ) / 2 | round | 横長画像のみ |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[テキスト選択] --> B[Share-a-Fact選択]
    B --> C[ShareAFactViewController初期化]
    C --> D[update関数呼び出し]
    D --> E{画像あり?}
    E -->|Yes| F[2列レイアウト設定]
    E -->|No| G[1列レイアウト設定]
    F --> H[画像サイズ計算]
    H --> I[レターボックス設定]
    G --> J[フルWidthテキスト設定]
    I --> K[ライセンス設定]
    J --> K
    K --> L[スナップショット取得]
    L --> M[ShareAFactActivityImageItemProvider]
    M --> N[UIActivityViewController表示]
    N --> O[終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| テキストなし | text = nil | なし | 空文字列で継続 |
| 画像なし | image = nil | なし | 1列レイアウトに切り替え |
| ライセンス不明 | imageLicense.code = nil | なし | genericライセンスアイコン表示 |

## パフォーマンス要件

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

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

- 著作権：ライセンス情報を明示（CC BY-SAおよび画像ライセンス）
- アクセス制御：ユーザーの明示的な操作が必要
- コンテンツ：記事内容はWikipediaのライセンスに準拠

## 備考

- 標準テーマ固定（Theme.standard）でカード生成
- semanticContentAttributeで右から左の言語にも対応
- グラデーションオーバーレイで画像下部のテキスト可読性を確保
- 行間隔7ptで引用テキストの可読性向上

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ShareAFactActivityTextItemProvider.swift | `Wikipedia/Code/ShareAFactActivityTextItemProvider.swift` | テキスト共有時のフォーマット（email, message, social）を理解 |
| 1-2 | ShareAFactActivityImageItemProvider.swift | `Wikipedia/Code/ShareAFactActivityImageItemProvider.swift` | 画像共有のItemProvider構造を理解 |

**読解のコツ**: UIActivityItemProviderのサブクラスとして、activityType別に異なる出力形式を提供する仕組みを把握する。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ShareAFactViewController.swift | `Wikipedia/Code/ShareAFactViewController.swift` | viewDidLoadでの初期設定、updateでのレイアウト構築 |

**主要処理フロー**:
1. **行31-47**: viewDidLoad - テーマ設定、ラベル設定、グラデーション設定
2. **行49-111**: update関数 - レイアウト構築、画像・テキスト配置

#### Step 3: レイアウト処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ShareAFactViewController.swift | `Wikipedia/Code/ShareAFactViewController.swift` 行49-111 | update関数の詳細 |

**主要処理フロー**:
- **行50-55**: semanticContentAttribute設定（RTL対応）
- **行56-69**: テキスト設定、フォントサイズ調整
- **行70-71**: 記事タイトル設定
- **行72-89**: ライセンスアイコン設定
- **行91-111**: 画像レイアウト（レターボックス対応）

#### Step 4: 画像有無によるレイアウト切り替えを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ShareAFactViewController.swift | `Wikipedia/Code/ShareAFactViewController.swift` 行113-120 | isImageViewHiddenプロパティ |

**主要処理フロー**:
- **行113-120**: didSet内でConstraint切り替え、ワードマーク表示切り替え

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

```
ArticleViewController (記事表示)
    │
    ├─ テキスト選択 → コンテキストメニュー
    │
    ├─ ShareAFactViewController
    │      │
    │      ├─ viewDidLoad()
    │      │     ├─ Theme設定
    │      │     ├─ グラデーション設定
    │      │     └─ ローカライズ文字列設定
    │      │
    │      └─ update(with:articleURL:articleTitle:text:image:imageLicense:)
    │            ├─ semanticContentAttribute設定
    │            ├─ textLabel設定（フォントサイズ判定）
    │            ├─ articleTitleLabel設定
    │            ├─ ライセンス設定
    │            │     ├─ imageLicenseView（画像ライセンス）
    │            │     └─ articleLicenseView（CC BY-SA）
    │            └─ 画像レイアウト
    │                  └─ isImageViewHidden切り替え
    │
    ├─ ShareAFactActivityImageItemProvider(image:)
    │      └─ item -> UIImage
    │
    ├─ ShareAFactActivityTextItemProvider(text:articleTitle:articleURL:)
    │      └─ item -> String (activityType別フォーマット)
    │
    └─ UIActivityViewController (システム共有シート)
```

### データフロー図

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

articleURL ─────────────▶ ShareAFactViewController        ユーザー共有先
articleTitle                    │                         (Twitter/Facebook等)
text (選択テキスト)              │
image (関連画像)                 │
imageLicense                    ▼
                          update() レイアウト構築
                               │
                               ├─ テキストレイアウト
                               │     └─ フォントサイズ判定
                               │
                               ├─ 画像レイアウト
                               │     └─ レターボックス計算
                               │
                               └─ ライセンスレイアウト
                                    │
                                    ▼
                          UIView.snapshot()
                                    │
                                    ▼
                    ShareAFactActivityImageItemProvider
                    ShareAFactActivityTextItemProvider
                                    │
                                    ▼
                          UIActivityViewController
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ShareAFactViewController.swift | `Wikipedia/Code/` | ソース | カード画像生成ビューコントローラー |
| ShareAFactActivityTextItemProvider.swift | `Wikipedia/Code/` | ソース | テキスト共有プロバイダー |
| ShareAFactActivityImageItemProvider.swift | `Wikipedia/Code/` | ソース | 画像共有プロバイダー |
| LicenseView.swift | `Wikipedia/Code/` | ソース | ライセンスアイコン表示 |
| WMFGradientView.swift | `WMFComponents/` | ソース | グラデーションオーバーレイ |
