# 帳票設計書 7-Image Share

## 概要

本ドキュメントは、Wikipedia iOSアプリケーションにおける「Image Share」帳票の設計仕様を定義する。この帳票は記事内の画像とメタデータを共有する機能を提供する。

### 本帳票の処理概要

本帳票は、Wikipedia記事内に含まれる画像をそのメタデータ（ファイルページURL、ライセンス情報など）と共に他のアプリやサービスに共有する機能である。画像そのものに加え、出典情報としてのURLを含めることで、著作権情報の適切な伝達を実現する。

**業務上の目的・背景**：Wikipediaには豊富なフリーライセンス画像が存在し、それらを適切なクレジット付きで共有できるようにすることで、オープンな知識の普及に貢献する。画像の出典URLを含めることで、利用者が画像のライセンス情報を確認できるようにする。

**帳票の利用シーン**：記事閲覧中に画像ギャラリーを表示し、特定の画像を選択して共有ボタンをタップした場合に使用される。画像単体での共有や、SNSへの投稿などに活用できる。

**主要な出力内容**：
1. 画像データ（静止画像またはアニメーションGIF）
2. テキスト情報（ファイルページURLまたは"via Wikipedia"）
3. 画像共有用URL（Twitter/Weibo/TencentWeibo向け）

**帳票の出力タイミング**：画像ギャラリー画面で画像選択後、共有ボタンをタップした時点でUIActivityViewControllerが表示される。

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

## 帳票種別

画像共有（UIActivityViewController + 画像データ）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | Image Gallery | WMFImageGalleryViewController | 共有ボタン |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| 出力形式 | 画像（UIImage/Data） + テキスト + URL |
| ファイル名 | システム生成（UIActivityViewController経由） |
| 出力方法 | UIActivityViewController |
| 文字コード | UTF-8 |

### 共有アイテム構成

| 項目 | 型 | 内容 | ソース |
|-----|-----|------|--------|
| テキスト | WMFImageTextActivitySource | SNS向けテキスト | MWKImageInfo |
| URL | WMFImageURLActivitySource | 画像共有用URL | MWKImageInfo |
| 画像 | Data/UIImage | 画像データ | ImageDownload |

## 帳票レイアウト

### 共有コンテンツ構成

```
[画像データ]
+
[テキスト（SNS別）]
  - Twitter: "via Wikipedia"
  - Facebook/Mail/Flickr: ファイルページURL
  - その他: なし
+
[URL（SNS別）]
  - Twitter/Weibo/TencentWeibo: wmf_URLForImageSharing
  - その他: なし
```

### SNS別出力内容

| 共有先 | テキスト | URL |
|--------|---------|-----|
| Twitter | "via Wikipedia" | wmf_URLForImageSharing |
| Facebook | ファイルページURL | なし |
| Mail | ファイルページURL | なし |
| Flickr | ファイルページURL | なし |
| Weibo | なし | wmf_URLForImageSharing |
| TencentWeibo | なし | wmf_URLForImageSharing |
| その他 | なし | なし |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| imageInfo | MWKImageInfo | Yes |
| imageDownload | ImageDownload | Yes |
| filePageURL | ファイルページのURL | No（存在時のみテキスト追加） |

### 画像タイプ判定

| 条件 | 出力データ |
|------|-----------|
| animatedImage存在 | animatedImage.data（GIFデータ） |
| animatedImageなし | staticImage（UIImage） |

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

### 参照オブジェクト

| オブジェクト | 用途 | 備考 |
|------------|------|------|
| MWKImageInfo | 画像メタデータ | filePageURL等 |
| ImageDownload | ダウンロード済み画像 | animatedImage/staticImage |

### MWKImageInfo参照項目

| 参照項目 | 帳票項目との対応 | 備考 |
|---------|----------------|------|
| filePageURL | テキスト情報（Facebook等） | オプショナル |
| filePageURL | 共有URL（Twitter等） | wmf_URLForImageSharing変換 |

### ImageDownload参照項目

| 参照項目 | 帳票項目との対応 | 備考 |
|---------|----------------|------|
| image.animatedImage | GIFデータ | Dataとして共有 |
| image.staticImage | 静止画像 | UIImageとして共有 |

## 計算仕様

### 画像データ選択

| 項目名 | 計算式 | 備考 |
|-------|-------|------|
| imageToShare | image.animatedImage?.data ?? image.staticImage | GIF優先 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[共有ボタンタップ] --> B[imageInfo, imageDownload取得]
    B --> C[ShareActivityController初期化]
    C --> D[WMFImageTextActivitySource生成]
    D --> E[WMFImageURLActivitySource生成]
    E --> F{animatedImage存在?}
    F -->|Yes| G[GIFデータをactivityItemsに追加]
    F -->|No| H[staticImageをactivityItemsに追加]
    G --> I[UIActivityViewController表示]
    H --> I
    I --> J[ユーザーが共有先選択]
    J --> K{activityType判定}
    K -->|Twitter| L[テキスト: via Wikipedia, URL: wmf_URLForImageSharing]
    K -->|Facebook/Mail/Flickr| M[テキスト: filePageURL, URL: なし]
    K -->|Weibo/TencentWeibo| N[テキスト: なし, URL: wmf_URLForImageSharing]
    K -->|その他| O[テキスト: なし, URL: なし]
    L --> P[共有実行]
    M --> P
    N --> P
    O --> P
    P --> Q[終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 画像なし | imageDownload = nil | なし | 共有不可 |
| filePageURLなし | imageInfo.filePageURL = nil | なし | テキストなしで共有 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1件/回 |
| 目標出力時間 | 即座（UIレスポンス） |
| 同時出力数上限 | 1件 |

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

- 著作権：ファイルページURLを含めることでライセンス情報への導線を確保
- 画像データ：Wikipediaから取得した画像のみ共有対象
- アクセス制御：ユーザーの明示的な操作（共有ボタンタップ）が必要

## 備考

- アニメーションGIFはDataとして共有することで動画を維持
- WMFImageTextActivitySourceとWMFImageURLActivitySourceでSNS別フォーマットを実現
- excludedActivityTypesで.addToReadingListを除外

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | WMFImageTextActivitySource.swift | `Wikipedia/Code/WMFImageTextActivitySource.swift` | SNS別テキストフォーマットを理解 |
| 1-2 | WMFImageURLActivitySource.swift | `Wikipedia/Code/WMFImageURLActivitySource.swift` | SNS別URL提供を理解 |

**読解のコツ**: UIActivityItemSourceプロトコルのactivityTypeによる分岐処理を把握する。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ShareActivityController.swift | `Wikipedia/Code/ShareActivityController.swift` 行215-225 | init(imageInfo:imageDownload:) |

**主要処理フロー**:
1. **行217-219**: imageDownloadから画像取得、GIF/静止画判定
2. **行221**: activityItems配列構築
3. **行223-224**: super.init呼び出し、excludedActivityTypes設定

#### Step 3: テキストActivitySourceを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | WMFImageTextActivitySource.swift | `Wikipedia/Code/WMFImageTextActivitySource.swift` | activityType別テキスト生成 |

**主要処理フロー**:
- **行16-31**: activityViewController(_:itemForActivityType:) - activityType判定
- **行20-21**: Twitter → "via Wikipedia"
- **行22-25**: Facebook/Mail/Flickr → filePageURL
- **行26-27**: その他 → nil

#### Step 4: URLActivitySourceを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | WMFImageURLActivitySource.swift | `Wikipedia/Code/WMFImageURLActivitySource.swift` | activityType別URL生成 |

**主要処理フロー**:
- **行17-30**: activityViewController(_:itemForActivityType:) - activityType判定
- **行21-24**: Twitter/Weibo/TencentWeibo → wmf_URLForImageSharing
- **行25-27**: その他 → nil

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

```
WMFImageGalleryViewController (画像ギャラリー)
    │
    ├─ 共有ボタンタップ
    │
    ├─ ShareActivityController(imageInfo:imageDownload:)
    │      │
    │      ├─ 画像データ取得
    │      │     ├─ animatedImage?.data (GIF)
    │      │     └─ staticImage (静止画)
    │      │
    │      └─ activityItems配列構築
    │            ├─ WMFImageTextActivitySource(info:)
    │            ├─ WMFImageURLActivitySource(info:)
    │            └─ imageToShare (Data or UIImage)
    │
    ├─ UIActivityViewController表示
    │
    └─ ユーザー共有先選択
          │
          ├─ WMFImageTextActivitySource.item
          │     └─ activityType判定 → テキスト返却
          │
          └─ WMFImageURLActivitySource.item
                └─ activityType判定 → URL返却
```

### データフロー図

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

MWKImageInfo ───────────▶ ShareActivityController          共有先アプリ
  │                            │                         (Twitter/Facebook等)
  └─ filePageURL               │
                               ▼
ImageDownload ─────────▶ 画像データ判定
  │                            │
  ├─ animatedImage             ├─ GIF: Data
  └─ staticImage               └─ 静止画: UIImage
                                    │
                                    ▼
                          activityItems配列
                               │
                               ├─ WMFImageTextActivitySource
                               │     └─ activityType別テキスト
                               │
                               ├─ WMFImageURLActivitySource
                               │     └─ activityType別URL
                               │
                               └─ 画像データ
                                    │
                                    ▼
                          UIActivityViewController
                                    │
                                    ▼
                            共有先アプリ選択
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ShareActivityController.swift | `Wikipedia/Code/` | ソース | 共有コントローラー |
| WMFImageTextActivitySource.swift | `Wikipedia/Code/` | ソース | SNS別テキストプロバイダー |
| WMFImageURLActivitySource.swift | `Wikipedia/Code/` | ソース | SNS別URLプロバイダー |
| MWKImageInfo.swift | `WMF Framework/` | ソース | 画像メタデータモデル |
| ImageDownload.swift | `WMF Framework/` | ソース | ダウンロード済み画像モデル |
