# 画面設計書 8-Reference画面

## 概要

本ドキュメントは、Wikipedia iOSアプリのReference画面（参照詳細画面）の設計仕様を記載したものである。

### 本画面の処理概要

Reference画面は、記事内の脚注（参照）の詳細内容を表示する画面である。ポップオーバーまたはシートとして表示され、参照元情報やリンクを提供する。

**業務上の目的・背景**：ユーザーが記事の脚注をタップした際に、その参照内容（書籍情報、URL、引用など）を詳細に確認できるようにする。記事内の情報の出典を追跡し、信頼性を確認する手段を提供。

**画面へのアクセス方法**：Article画面内で脚注リンク（[1]など）をタップ。

**主要な操作・処理内容**：
1. 参照内容の表示
2. 閉じるボタンによる画面終了
3. 「参照元に戻る」ボタンによる記事内参照セクションへのジャンプ
4. 参照内リンクのタップによる外部/内部遷移

**画面遷移**：
- 遷移元：Article画面
- 遷移先：なし（閉じる）、または参照元セクションへスクロール

**権限による表示制御**：なし

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | 参照表示 | 主機能 | 参照の詳細内容表示 |
| 1 | 記事閲覧 | 親機能 | Article画面との連携 |

## 画面種別

ポップオーバー/シート

## URL/ルーティング

- エントリーポイント：`ArticleViewController`の参照タップハンドラ経由
- Storyboard ID：`ReferenceViewController`

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|----------|------|
| 参照ID | 入力 | String | referenceId プロパティ |
| 参照リンクテキスト | 入力 | String | referenceLinkText プロパティ（例: "[1]"） |
| デリゲート | 入力 | ReferenceViewControllerDelegate | delegate プロパティ |

## 表示項目

| 項目名 | データソース | 表示条件 | 備考 |
|--------|-------------|----------|------|
| ナビゲーションバー | customNavigationBar | 常時 | カスタム実装 |
| タイトル | referenceLinkText | 常時 | "Reference [1]" 形式 |
| 閉じるボタン | closeButton | 常時 | 右側に配置 |
| 参照元に戻るボタン | backToReferenceButton | 常時 | 左側に配置 |
| 参照内容 | - | 常時 | サブクラスで実装 |

## イベント仕様

### 1-閉じるボタンタップ

`closeButton`（UIBarButtonItem）タップで`closeButtonPressed`メソッドが呼び出され、`delegate?.referenceViewControllerUserDidTapClose(self)`でArticleViewControllerに通知。

**ソースコード参照**: ReferenceViewController.swift 行82-90（closeButton、closeButtonPressed）

### 2-参照元に戻るボタンタップ

`backToReferenceButton`タップで`goBackToReference`メソッドが呼び出され、`delegate?.referenceViewControllerUserDidNavigateBackToReference(self)`でArticleViewControllerに通知。記事内の参照セクションへスクロール。

**ソースコード参照**: ReferenceViewController.swift 行77-94（backToReferenceButton、goBackToReference）

### 3-タイトル更新

`referenceLinkText`プロパティのdidSetで`updateTitle()`が呼び出され、ローカライズされたタイトル形式「Reference %@」でナビゲーションタイトルを設定。

**ソースコード参照**: ReferenceViewController.swift 行13-25（referenceLinkText、updateTitle）

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| なし | - | - | この画面ではデータベース更新なし |

## メッセージ仕様

| メッセージID | メッセージ内容 | 表示条件 | 種別 |
|-------------|---------------|----------|------|
| article-reference-view-title | Reference %@ | 常時（タイトル） | 表示 |
| reference-section-button-accessibility-label | Jump to reference section | 参照元ボタン（VoiceOver） | アクセシビリティ |

## 例外処理

- **参照リンクテキストなし**：`referenceLinkText`がnilの場合、タイトル更新をスキップ
- **デリゲート未設定**：delegateがnilの場合、操作を無視して安全に処理

## 備考

- ReferenceViewControllerはThemeableViewControllerを継承
- ReferenceViewControllerDelegateプロトコルでArticleViewControllerと通信
- カスタムUINavigationBarを使用（システムナビゲーションバーではない）
- 実際の参照内容表示はサブクラス（ReferenceWebViewController等）で実装

---

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

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

### 推奨読解順序

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

参照データの構造を理解。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ReferenceViewControllerDelegate | `ReferenceViewController.swift 行3-7` | デリゲートプロトコルの3メソッド |

**読解のコツ**: デリゲートメソッドがそれぞれどのユーザーアクションに対応するか把握。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ReferenceViewController.swift | `Wikipedia/Code/ReferenceViewController.swift` | 全体114行の基底クラス |

**主要処理フロー**:
1. **行64-67 viewDidLoad**: setupCustomNavbar()でナビゲーションバー設定
2. **行33-60 setupCustomNavbar**: カスタムナビゲーションバーの構築、閉じる/戻るボタン配置
3. **行98-112 apply(theme:)**: テーマ適用、ナビゲーションバーのスタイル設定

#### Step 3: 呼び出し元を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ArticleViewController+Reference.swift | `Wikipedia/Code/` | 参照タップハンドリング |
| 3-2 | ArticleWebMessagingController.swift | `Wikipedia/Code/` | JSブリッジからの参照イベント |

#### Step 4: サブクラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ReferenceWebViewController.swift | `Wikipedia/Code/` | WebView内で参照内容を表示（推定） |

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

```
ArticleViewController
    │
    ├─ ArticleWebMessagingController (JS Bridge)
    │      └─ Reference Tap Event
    │
    └─ ReferenceViewController
           │
           ├─ customNavigationBar (UINavigationBar)
           │      ├─ closeButton (UIBarButtonItem)
           │      └─ backToReferenceButton (UIBarButtonItem)
           │
           └─ ReferenceViewControllerDelegate
                  │
                  ├─ referenceViewControllerUserDidTapClose
                  │      └─ Dismiss Reference View
                  │
                  └─ referenceViewControllerUserDidNavigateBackToReference
                         └─ Scroll to Reference Section
```

### データフロー図

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

Reference Tap ───▶ ArticleWebMessagingController ───▶ Show ReferenceVC
                           │
referenceId ──────▶ ReferenceViewController
referenceLinkText ─│      │
                   │      ▼
                   └─▶ updateTitle() ───▶ Navigation Title
                           │
Close Button ─────────▶ closeButtonPressed() ───▶ Delegate.didTapClose
                           │
Back Button ──────────▶ goBackToReference() ───▶ Delegate.didNavigateBack
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ReferenceViewController.swift | `Wikipedia/Code/` | ソース | 基底ViewController（114行） |
| ReferenceViewControllerDelegate | `ReferenceViewController.swift` | プロトコル | デリゲート定義 |
| ArticleViewController+Reference.swift | `Wikipedia/Code/` | ソース | 参照関連の拡張（推定） |
| ReferenceWebViewController.swift | `Wikipedia/Code/` | ソース | WebView実装サブクラス（推定） |
| ArticleWebMessagingController.swift | `Wikipedia/Code/` | ソース | JSブリッジ、参照タップ検出 |
