# 帳票設計書 6-Article Share

## 概要

本ドキュメントは、Wikipedia iOSアプリケーションにおける「Article Share」帳票の設計仕様を定義する。この帳票は記事のタイトルとURLを共有する機能を提供し、UIActivityViewControllerを使用してシステム共有シートを表示する。

### 本帳票の処理概要

本帳票は、Wikipedia記事のメタデータ（タイトル、URL、位置情報）をシステムの共有機能を通じて他のアプリやサービスに共有する機能である。画像生成を伴わないテキストベースの共有形式となる。

**業務上の目的・背景**：ユーザーが興味を持った記事を簡単に友人や知人と共有できるようにすることで、Wikipediaコンテンツの拡散とユーザーエンゲージメント向上を図る。メッセージアプリ、メール、SNSなど様々なチャネルで記事を共有できる汎用的な機能として提供される。

**帳票の利用シーン**：記事閲覧中または記事一覧画面で、ユーザーが共有ボタンをタップした場合に使用される。保存した記事、検索結果、閲覧履歴など、様々な画面から記事を共有できる。

**主要な出力内容**：
1. 記事タイトル（"[Title]" on Wikipedia形式）
2. 記事URL（フラグメント付き、テキスト共有用に最適化）
3. MapItem（位置情報がある記事の場合）

**帳票の出力タイミング**：共有ボタンタップ時にUIActivityViewControllerが即座に表示される。

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

## 帳票種別

テキスト共有（UIActivityViewController）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | Article View | ArticleViewController | 共有ボタン |
| - | Reading List Detail | ReadingListDetailViewController | コンテキストメニュー |
| - | Saved Articles | SavedViewController | コンテキストメニュー |
| - | History | HistoryViewController | コンテキストメニュー |
| - | Search | SearchViewController | コンテキストメニュー |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| 出力形式 | テキスト + URL + MapItem（任意） |
| ファイル名 | なし（直接共有） |
| 出力方法 | UIActivityViewController |
| 文字コード | UTF-8 |

### 共有アイテム構成

| 項目 | 型 | 内容 |
|-----|-----|------|
| テキスト | String | "[Title]" on Wikipedia |
| URL | URL | wmf_URLForTextSharing形式 |
| MapItem | MKMapItem | 位置情報（任意） |

## 帳票レイアウト

### 共有テキストフォーマット

```
"[記事タイトル]" on Wikipedia
https://ja.wikipedia.org/wiki/[記事名]#[フラグメント]
```

### カスタムアクティビティ

| アクティビティ | アイコン | 説明 |
|---------------|---------|------|
| Add to Reading List | add-to-reading-list | 読書リストに追加 |
| Move to Reading List | move-to-reading-list | 読書リスト間移動（ReadingListDetailViewControllerのみ） |

### システムアクティビティ

| アクティビティ | 説明 |
|---------------|------|
| TUSafariActivity | Safariで開く |
| WMFOpenInMapsActivity | マップで開く |
| WMFGetDirectionsInMapsActivity | 経路案内 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| article | WMFArticleオブジェクト | Yes |
| displayTitle | 記事タイトル | No（存在時のみテキスト追加） |
| url | 記事URL | No（存在時のみURL追加） |
| mapItem | MKMapItem | No（存在時のみ追加） |

### 除外アクティビティタイプ

| アクティビティタイプ | 理由 |
|-------------------|------|
| .addToReadingList | カスタムアクティビティで代替 |

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

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| WMFArticle | 記事メタデータ | articleKey |

### WMFArticle参照項目

| 参照項目 | 帳票項目との対応 | 備考 |
|---------|----------------|------|
| displayTitle | 共有テキストのタイトル | オプショナル |
| url | 共有URL | wmf_URLForTextSharing変換 |
| viewedFragment | URLフラグメント | 閲覧位置 |
| mapItem | 位置情報 | CLLocationCoordinate2D |

## 計算仕様

### URL変換処理

| 項目名 | 計算式 | 備考 |
|-------|-------|------|
| shareURL | article.url?.wmf_URL(withOptionalFragment: viewedFragment)?.wmf_URLForTextSharing | フラグメント付きテキスト共有用URL |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[共有ボタンタップ] --> B{articleあり?}
    B -->|Yes| C[ShareActivityController初期化]
    B -->|No| D{articleURLあり?}
    D -->|Yes| E[articleSummaryController.updateOrCreateArticleSummary]
    D -->|No| F[処理終了 return false]
    E --> G{article取得成功?}
    G -->|Yes| C
    G -->|No| F
    C --> H[activityItems配列構築]
    H --> I{displayTitle存在?}
    I -->|Yes| J[テキスト追加]
    I -->|No| K[スキップ]
    J --> L{shareURL存在?}
    K --> L
    L -->|Yes| M[URL追加]
    L -->|No| N[スキップ]
    M --> O{mapItem存在?}
    N --> O
    O -->|Yes| P[MapItem追加]
    O -->|No| Q[スキップ]
    P --> R[UIActivityViewController表示]
    Q --> R
    R --> S[終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 記事なし | article = nil && articleURL = nil | なし | return false |
| URL取得失敗 | wmf_inMemoryKey = nil | なし | return true（非同期処理継続） |
| サマリー取得失敗 | articleSummaryController失敗 | なし | コールバック内で処理中断 |

## パフォーマンス要件

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

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

- 個人情報：共有内容は公開記事のみ、個人データは含まない
- 位置情報：記事に付与された位置情報（ユーザー位置ではない）
- アクセス制御：ユーザーの明示的な操作（共有ボタンタップ）が必要

## 備考

- ShareableArticlesProviderプロトコルで共有機能を提供
- MEPEventsProvidingプロトコルでイベントログを記録
- カスタムアクティビティで読書リスト機能を拡張
- iPad対応（popoverPresentationController設定）

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ShareActivityController.swift | `Wikipedia/Code/ShareActivityController.swift` | ShareActivityControllerの各イニシャライザを理解 |

**読解のコツ**: 複数のイニシャライザがあり、用途によって異なる引数を受け取る。article, customActivities, textActivitySourceなどの組み合わせを把握する。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ShareActivityController.swift | `Wikipedia/Code/ShareActivityController.swift` 行33-81 | ShareableArticlesProviderプロトコル拡張 |

**主要処理フロー**:
1. **行37-50**: share関数 - articleまたはarticleURLから共有開始
2. **行52-81**: createAndPresentShareActivityController - カスタムアクティビティ設定、共有コントローラー表示

#### Step 3: 共有コントローラーの初期化を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ShareActivityController.swift | `Wikipedia/Code/ShareActivityController.swift` 行138-157 | init(article:customActivities:) |

**主要処理フロー**:
- **行140-145**: テキストアイテム構築（"[Title]" on Wikipedia形式）
- **行146-148**: shareURL構築（フラグメント付き）
- **行150-152**: mapItem追加（存在時）
- **行154-156**: super.init呼び出し、excludedActivityTypes設定

#### Step 4: カスタムアクティビティを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ShareActivityController.swift | `Wikipedia/Code/ShareActivityController.swift` 行83-131 | AddToReadingListActivity, MoveToReadingListActivity |

**主要処理フロー**:
- **行83-106**: AddToReadingListActivity - 読書リスト追加アクション
- **行108-131**: MoveToReadingListActivity - 読書リスト間移動アクション

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

```
ArticleViewController / ReadingListDetailViewController / etc.
    │ (ShareableArticlesProvider準拠)
    │
    ├─ share(article:articleURL:dataStore:theme:eventLoggingCategory:eventLoggingLabel:sourceView:)
    │      │
    │      ├─ article存在時 → createAndPresentShareActivityController
    │      │
    │      └─ articleURL存在時 → articleSummaryController.updateOrCreateArticleSummary
    │                              └─ コールバック内でcreateAndPresentShareActivityController
    │
    ├─ createAndPresentShareActivityController
    │      │
    │      ├─ カスタムアクティビティ構築
    │      │     ├─ AddToReadingListActivity
    │      │     └─ MoveToReadingListActivity (ReadingListDetailViewControllerのみ)
    │      │
    │      └─ ShareActivityController(article:customActivities:)
    │
    └─ ShareActivityController
           │
           ├─ activityItems配列
           │     ├─ String: "[Title]" on Wikipedia
           │     ├─ URL: wmf_URLForTextSharing
           │     └─ MKMapItem (任意)
           │
           ├─ applicationActivities配列
           │     ├─ TUSafariActivity
           │     ├─ WMFOpenInMapsActivity
           │     ├─ WMFGetDirectionsInMapsActivity
           │     └─ customActivities
           │
           └─ excludedActivityTypes: [.addToReadingList]
```

### データフロー図

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

WMFArticle ─────────────▶ ShareActivityController          共有先アプリ
  │                            │                         (Messages/Mail/Twitter等)
  ├─ displayTitle              │
  ├─ url                       ▼
  ├─ viewedFragment      activityItems構築
  └─ mapItem                   │
                               ├─ "[Title]" on Wikipedia
                               │
                               ├─ wmf_URLForTextSharing
                               │
                               └─ MKMapItem
                                    │
                                    ▼
                          UIActivityViewController
                                    │
                                    ▼
                            共有先アプリ選択
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ShareActivityController.swift | `Wikipedia/Code/` | ソース | 共有コントローラー、プロトコル拡張 |
| TUSafariActivity.swift | `Wikipedia/Code/` | ソース | Safariで開くアクティビティ |
| WMFOpenInMapsActivity.swift | `Wikipedia/Code/` | ソース | マップで開くアクティビティ |
| WMFGetDirectionsInMapsActivity.swift | `Wikipedia/Code/` | ソース | 経路案内アクティビティ |
| WMFArticle.swift | `WMF Framework/` | ソース | 記事モデル |
| AddArticlesToReadingListViewController.swift | `Wikipedia/Code/` | ソース | 読書リスト追加画面 |
