# チュートリアル機能 設計案

## 概要

JR四国非公式アプリにチュートリアル機能を追加し、ユーザーの初回体験を改善する。

---

## 案1: 初回起動ウォークスルー（オンボーディング）

初回起動時に 3〜5 画面のスワイプ式ウォークスルーを表示。

| 画面 | 内容 |
|------|------|
| 1 | 「JR四国の列車位置をリアルタイムで確認できます」（マップ画面のスクリーンショット） |
| 2 | 「よく使う駅をお気に入り登録しよう」（お気に入り機能の紹介） |
| 3 | 「駅名標・発車時刻表も見られます」（駅ダイヤグラム紹介） |
| 4 | 「通知設定で遅延情報を受け取れます」（通知設定への誘導） |

**表示制御**: `AsyncStorage` の `TUTORIAL_COMPLETED` キーで管理。

---

## 案2: コーチマーク（ツールチップ型ガイド）

各画面で初めてアクセスした際に、UIパーツをハイライト＋吹き出しで説明。

- **マップ画面**: 「ピンをタップすると列車情報が見られます」「このボタンで現在地に戻れます」
- **メニュー画面**: 「横スクロールで路線を切り替えられます」「★で駅をお気に入りに追加」
- **設定画面**: 「アプリアイコンを変更できます」

**表示制御**: `COACH_MARK_{SCREEN}_SHOWN` フラグで画面ごとに制御。

---

## 案3: コンテキスト依存ヒント

特定の操作タイミングで自動表示。

| トリガー | ヒント内容 |
|----------|-----------|
| お気に入り 0 件でメニュー表示 | 「駅をお気に入りに追加すると、ここからすぐアクセスできます」 |
| FeliCa 対応端末で初回起動 | 「交通系ICカードの履歴を読み取れます」 |
| 列車遅延発生時 | 「通知設定で遅延情報を自動受信できます → 設定へ」 |
| 長押し操作が可能な箇所 | 「長押しで詳細メニューが開きます」 |

---

## 案4: 「使い方」セクション刷新

現在の `howto.tsx`（WebView）を、アプリ内ネイティブ画面に置き換え。

- カテゴリ別に整理（「基本操作」「お気に入り」「ウィジェット」「FeliCa」など）
- GIF/Lottie アニメーションで操作手順を視覚的に表示（Lottie は導入済み）
- 設定画面からいつでもアクセス可能 + チュートリアルリセットボタン

---

## 案5: 段階的機能開放（プログレッシブ・ディスクロージャー）

使い込むにつれて高度な機能を提案。

```
初回起動 → 基本操作ガイド
3回目起動 → 「お気に入り登録してみませんか？」
1週間後  → 「ウィジェットを設定すると便利です」
```

---

## 実装の優先順位

1. **初回ウォークスルー** — 最もインパクト大、実装も比較的シンプル
2. **コンテキスト依存ヒント** — お気に入り 0 件ヒントなど簡単なものから
3. **コーチマーク** — マップ画面の操作説明に効果的
4. **使い方セクション刷新** — 既存の howto.tsx を段階的に改善
5. **段階的機能開放** — 長期的な改善施策

---

## 実装パターン比較: OTA vs ライブラリ追加

以下で詳細に比較する。

### パターンA: OTA配信可能（既存依存のみ）

既にインストール済みのライブラリのみで実装。`expo-updates` 経由の OTA で即座にユーザーへ配信可能。

#### 利用可能な既存ライブラリ

- `react-native-reanimated` (v4.2.1) — アニメーション全般
- `react-native-reanimated-carousel` (v4.0.3) — スワイプ式カルーセル（ウォークスルーに最適）
- `react-native-gesture-handler` (v2.30.0) — ジェスチャー制御
- `@gorhom/bottom-sheet` (v5) — ボトムシート型UI
- `react-native-actions-sheet` (v10.1.2) — アクションシート
- `lottie-react-native` (v7.3.1) — アニメーション素材再生
- `react-native-svg` (v15.15.3) — SVG描画
- `@react-native-async-storage/async-storage` — 表示状態の永続化
- `expo-haptics` — 触覚フィードバック

#### 設計方針

| 機能 | 実装方法 |
|------|----------|
| ウォークスルー | `react-native-reanimated-carousel` でページスワイプ + `reanimated` でフェードアニメーション |
| コーチマーク | 自前実装: `react-native-svg` で穴あきオーバーレイ + `View.measure()` でターゲット位置取得 |
| ヒント表示 | `@gorhom/bottom-sheet` or `react-native-actions-sheet` でスナックバー風表示 |
| アニメーション | `lottie-react-native` で手順説明アニメ |
| 状態管理 | `AsyncStorage` でフラグ管理 |

#### 難易度

| 機能 | 難易度 | 工数目安 | 備考 |
|------|--------|----------|------|
| ウォークスルー | ★★☆☆☆ | 小 | carousel がそのまま使える |
| コンテキストヒント | ★★☆☆☆ | 小 | BottomSheet/ActionSheet で簡単 |
| コーチマーク | ★★★★☆ | 大 | 穴あきオーバーレイの自前実装が必要。ターゲット要素の位置計測、スクロール追従、画面回転対応など |
| 使い方画面刷新 | ★★☆☆☆ | 中 | 通常の画面実装 |
| 段階的開放 | ★★☆☆☆ | 小 | AsyncStorage カウンタ + 条件分岐 |

#### メリット・デメリット

- ✅ OTA即時配信可能（ストア審査不要）
- ✅ 追加依存なし、バンドルサイズ増加なし
- ❌ コーチマーク（穴あきオーバーレイ）の自前実装コストが高い
- ❌ コーチマークのエッジケース対応（ScrollView内要素、モーダル上など）が大変

---

### パターンB: ライブラリ追加（ネイティブビルド必要）

チュートリアル専用ライブラリを導入。次回のストアビルド＆審査が必要。

#### 追加候補ライブラリ

| ライブラリ | 用途 | ネイティブモジュール |
|-----------|------|---------------------|
| `react-native-copilot` | コーチマーク（ステップガイド） | なし（JS のみ） |
| `react-native-spotlight-tour` | スポットライト型ガイド | なし（JS のみ） |
| `@nickcarraway/react-native-tooltip-walkthrough` | ツールチップウォークスルー | なし（JS のみ） |

> **重要**: 上記候補はいずれも **Pure JS ライブラリ**（ネイティブモジュールなし）のため、実際には OTA 配信可能。ただし `node_modules` の変更を含むため EAS Build が推奨される場合がある。

#### 設計方針

| 機能 | 実装方法 |
|------|----------|
| ウォークスルー | パターンA と同じ（既存 carousel で十分） |
| コーチマーク | `react-native-copilot` の `CopilotProvider` + `walkthroughable()` HOC |
| ヒント表示 | パターンA と同じ |
| アニメーション | パターンA と同じ |

#### 難易度

| 機能 | 難易度 | 工数目安 | 備考 |
|------|--------|----------|------|
| ウォークスルー | ★★☆☆☆ | 小 | パターンAと同じ |
| コンテキストヒント | ★★☆☆☆ | 小 | パターンAと同じ |
| コーチマーク | ★★☆☆☆ | 小 | ライブラリが位置計測・オーバーレイを処理 |
| 使い方画面刷新 | ★★☆☆☆ | 中 | パターンAと同じ |
| 段階的開放 | ★★☆☆☆ | 小 | パターンAと同じ |

#### メリット・デメリット

- ✅ コーチマーク実装が大幅に楽（★★★★☆ → ★★☆☆☆）
- ✅ エッジケース（位置計測、スクロール追従）をライブラリが処理
- ❌ 新規依存追加（バンドルサイズ微増）
- ❌ ライブラリのメンテナンス状況・Expo SDK互換性リスク
- ⚠️ Pure JS ライブラリなら実質 OTA 可能だが、検証が必要

---

## 結論・推奨アプローチ

### フェーズ1（OTA配信）— すぐ着手可能

1. **ウォークスルー**: `react-native-reanimated-carousel` で実装 → OTA配信
2. **コンテキストヒント**: `BottomSheet` / `ActionSheet` で実装 → OTA配信
3. **段階的開放ロジック**: `AsyncStorage` カウンタ → OTA配信

### フェーズ2（次回ビルド時）— コーチマークの判断

- **コーチマークが必須なら**: `react-native-copilot`（Pure JS）を追加し、次回ビルドに含める
- **コーチマーク不要 or 後回しなら**: フェーズ1だけで十分な体験改善が可能

### 差分まとめ

| 観点 | パターンA（OTA） | パターンB（ライブラリ追加） |
|------|------------------|---------------------------|
| 配信速度 | 即座 | 次回ビルド待ち |
| コーチマーク難易度 | ★★★★☆ | ★★☆☆☆ |
| それ以外の難易度 | 同等 | 同等 |
| 依存リスク | なし | 低（Pure JS） |
| 推奨 | フェーズ1はこちら | コーチマーク実装時に検討 |