# 機能設計書 12-検索サジェスト

## 概要

本ドキュメントは、Wikipedia iOSアプリにおける「検索サジェスト」機能の設計を記述する。この機能は、Places画面において検索入力時にオートコンプリート・サジェスト候補を表示するものである。

### 本機能の処理概要

**業務上の目的・背景**：ユーザーが検索キーワードを入力する際に、入力補完や検索候補を表示することで、効率的な検索体験を提供する。特にPlaces機能では、地名や記事名の候補を提示することで、ユーザーが目的の場所を素早く見つけられるようにする。モバイルデバイスでのテキスト入力は手間がかかるため、サジェスト機能は操作効率向上に大きく貢献する。

**機能の利用シーン**：Places画面で検索バーにキーワードを入力し始めると、入力内容に基づいて候補が表示される。過去の検索履歴、現在の入力に基づく補完候補、システム提案などが組み合わせて表示される。ユーザーは候補をタップすることで即座に検索を実行できる。

**主要な処理内容**：
1. 検索入力を監視し、入力に基づいてサジェスト候補を取得する
2. 最近の検索履歴を表示する
3. 現在の入力文字列に基づく補完候補を取得・表示する
4. 候補選択時に対応する検索を実行する
5. 検索履歴の管理（追加・削除）を行う

**関連システム・外部連携**：Wikipedia MediaWiki APIと連携し、入力に基づく記事候補を取得する。また、ローカルの検索履歴データと組み合わせて候補を提示する。

**権限による制御**：本機能は認証不要で利用可能。すべてのユーザーがサジェスト機能を使用できる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | Places画面 | 主画面 | 検索バーでの入力時にサジェスト表示 |

## 機能種別

オートコンプリート / サジェスト表示 / 履歴管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| searchString | String | No | 検索入力文字列 | なし |
| siteURL | URL | Yes | 検索対象のWikipediaサイトURL | 有効なURLであること |

### 入力データソース

- 画面入力：Places画面の検索バー
- ローカルデータ：検索履歴（PlaceSearch配列として保存）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| searches | [[PlaceSearch]] | セクション別のサジェスト候補配列 |
| localizedDescription | String? | 候補の表示用説明文 |
| searchResult | MWKSearchResult? | 記事検索結果（該当する場合） |
| type | PlaceSearchType | 検索タイプ（text/location/nearby） |

### 出力先

- 画面表示：PlaceSearchSuggestionControllerが管理するTableView

## 処理フロー

### 処理シーケンス

```
1. ユーザーが検索バーに入力
   └─ 入力変更イベントを検知
2. 入力内容の解析
   └─ 空の場合は履歴のみ表示、入力ありの場合は候補取得
3. サジェスト候補の構築
   └─ セクション0: システム提案
   └─ セクション1: 最近の検索履歴
   └─ セクション2: 現在の入力文字列
   └─ セクション3: 補完候補
4. TableViewに候補を反映
   └─ searchesプロパティに設定、テーブルリロード
5. ユーザーが候補を選択
   └─ delegate経由でPlacesViewControllerに通知
6. 選択された検索を実行
   └─ currentSearchプロパティに設定して検索開始
```

### フローチャート

```mermaid
flowchart TD
    A[検索バー入力] --> B{入力内容確認}
    B -->|空| C[履歴セクションのみ表示]
    B -->|入力あり| D[補完候補取得]
    D --> E[セクション構築]
    E --> F[TableView更新]
    C --> F
    F --> G{ユーザー操作}
    G -->|候補タップ| H[検索実行]
    G -->|履歴削除| I[履歴から削除]
    G -->|全履歴クリア| J[履歴全削除]
    H --> K[Places検索処理]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-12-01 | セクション構造 | サジェストは4セクション構成（提案/履歴/現在入力/補完） | 常時 |
| BR-12-02 | デフォルト候補 | 提案セクションが空で補完があれば、補完の先頭をデフォルト候補として使用 | shouldUseFirstSuggestionAsDefault |
| BR-12-03 | 履歴セクション編集 | 履歴セクションのみスワイプ削除が可能 | セクション1のみ |
| BR-12-04 | 履歴上限 | 検索履歴は最大15件まで保持 | searchHistoryCountLimit |

### 計算ロジック

特になし。

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 履歴取得 | PlaceSearch履歴 | SELECT | 保存された検索履歴を取得 |
| 履歴追加 | PlaceSearch履歴 | INSERT | 新しい検索を履歴に追加 |
| 履歴削除 | PlaceSearch履歴 | DELETE | 特定の検索履歴を削除 |
| 履歴全削除 | PlaceSearch履歴 | DELETE | 全検索履歴を削除 |

### テーブル別操作詳細

#### PlaceSearch履歴

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | filter | 検索フィルタタイプ | top/saved |
| INSERT | type | 検索タイプ | text/location/nearby |
| INSERT | origin | 検索起点 | user/system |
| INSERT | string | 検索文字列 | nullable |
| INSERT | region | 地図領域 | MKCoordinateRegion |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | デシリアライズエラー | 保存された検索データの復元失敗 | PlaceSearchError.deserializationをスロー |

### リトライ仕様

特になし。サジェストの取得失敗時は候補を表示しない。

## トランザクション仕様

検索履歴の保存は単一操作で完結し、特別なトランザクション管理は不要。

## パフォーマンス要件

- サジェスト表示は入力から200ms以内に開始
- 候補表示は即座に行い、ユーザー入力を阻害しない

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

- 検索履歴はローカルデバイスにのみ保存
- 履歴削除機能により、プライバシー保護が可能

## 備考

PlaceSearchSuggestionControllerはPlaces機能専用のサジェストコントローラーであり、一般的な検索画面（SearchViewController）では異なる履歴管理が使用される。

---

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

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

### 推奨読解順序

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

サジェスト候補のデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | PlaceSearch.swift | `Wikipedia/Code/PlaceSearch.swift` | 検索を表すデータ構造、filter/type/origin/string/regionなど |

**読解のコツ**: PlaceSearch構造体はCodableに準拠しており、UserDefaultsへの保存・復元が可能。key計算ロジックにより重複検出を行う。

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

PlaceSearchSuggestionControllerがサジェスト機能のメインコントローラー。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | PlaceSearchSuggestionController.swift | `Wikipedia/Code/PlaceSearchSuggestionController.swift` | サジェストテーブルの管理コントローラー |

**主要処理フロー**:
1. **21-24行目**: セクション定数定義（suggestionSection=0, recentSection=1, currentStringSection=2, completionSection=3）
2. **45-49行目**: searchesプロパティ - セクション別候補配列、変更時にtableViewリロード
3. **57-59行目**: shouldUseFirstSuggestionAsDefault - 提案セクション空時のデフォルト候補判定
4. **72-83行目**: searchForIndexPath - インデックスパスから対応するPlaceSearchを取得
5. **106-109行目**: tableView(_:didSelectRowAt:) - 候補選択時のデリゲート呼び出し

#### Step 3: セルの表示を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | PlacesSearchSuggestionTableViewCell | `Wikipedia/Code/PlacesSearchSuggestionTableViewCell.swift` | サジェストセルの表示 |

**主要処理フロー**:
- **85-104行目**: tableView(_:cellForRowAt:) - セルの構成、アイコン・タイトル・詳細の設定
- **93-98行目**: アイコン設定ロジック（nearby/検索結果あり/テキストで分岐）

#### Step 4: Places画面との連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | PlacesViewController.swift | `Wikipedia/Code/PlacesViewController.swift` | Places画面のメインViewController |

**主要処理フロー**:
- **166-169行目**: searchSuggestionControllerの初期化とデリゲート設定
- PlaceSearchSuggestionControllerDelegateプロトコル実装部分

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

```
PlacesViewController
    │
    ├─ PlaceSearchSuggestionController
    │      └─ UITableViewDataSource/Delegate実装
    │             └─ PlacesSearchSuggestionTableViewCell
    │
    └─ PlaceSearchSuggestionControllerDelegate
           └─ didSelectSearch → currentSearch設定 → 検索実行
```

### データフロー図

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

検索バー入力 ───▶ PlacesViewController ───▶ 候補テーブル表示
                         │
                         ├─▶ PlaceSearchSuggestionController
                         │       ├─ searches配列構築
                         │       └─ TableView更新
                         │
                         └─▶ PlaceSearchService
                                 └─ 補完候補取得
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| PlaceSearchSuggestionController.swift | `Wikipedia/Code/` | ソース | サジェストテーブル管理 |
| PlaceSearch.swift | `Wikipedia/Code/` | ソース | 検索データモデル |
| PlacesSearchSuggestionTableViewCell.swift | `Wikipedia/Code/` | ソース | サジェストセル表示 |
| PlacesViewController.swift | `Wikipedia/Code/` | ソース | Places画面ViewController |
| PlaceSearchService.swift | `Wikipedia/Code/` | ソース | 検索サービス |
