# 画面設計書 56-インポート状況画面

## 概要

本ドキュメントは、Fizzyアプリケーションにおけるインポート状況画面の設計仕様を記述したものである。

### 本画面の処理概要

本画面は、アカウントデータのインポート処理の進行状況を表示する画面である。インポート処理はバックグラウンドで実行されるため、本画面でリアルタイムにステータスを確認できる。

**業務上の目的・背景**：データインポートは大量のデータを処理するため、時間がかかる場合がある。本画面ではTurbo Streamsを使用してリアルタイムにステータスを更新し、ユーザーに処理の進行状況を伝える。インポートが完了すれば新しいアカウントへのリンクを提供し、失敗した場合は適切なエラーメッセージとリトライオプションを表示する。

**画面へのアクセス方法**：インポート画面でZIPファイルをアップロード後、自動的にリダイレクトされる。URLパス `/account/imports/:id` に直接アクセスすることも可能だが、インポート実行者のみがアクセスできる。

**主要な操作・処理内容**：
1. インポート処理のステータスをリアルタイムで確認する
2. 完了時は「Go to your account」リンクで新しいアカウントにアクセスする
3. 失敗時は「Try again」リンクで再度インポートを試行する

**画面遷移**：インポート画面（/account/imports/new）から自動的にリダイレクトされる。完了時は新しいアカウントのランディングページへ、失敗時はインポート画面へ遷移可能。

**権限による表示制御**：インポートを実行した本人（identity）のみがアクセス可能。他のユーザーがアクセスすると403 Forbiddenとなる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 78 | アカウントデータインポート | 主機能 | インポート処理の状況を表示 |

## 画面種別

詳細

## URL/ルーティング

| メソッド | パス | アクション |
|---------|------|-----------|
| GET | /account/imports/:id | show（インポート状況表示） |

## 入出力項目

本画面には入力項目はない（表示のみ）。

## 表示項目

| 項目名 | 説明 |
|--------|------|
| ページタイトル | "Import status" |
| 見出し | "Import status" |
| 処理中メッセージ | "Your import is in progress. This may take a while for large accounts." |
| 完了メッセージ | "Your import was successful!" |
| 完了リンク | "Go to your account →" |
| 失敗メッセージ | "Import failed" |
| 失敗理由（conflict） | "The account you're trying to import already exists..." |
| 失敗理由（invalid_export） | "The .zip file you uploaded doesn't look like a Fizzy account export." |
| 失敗理由（その他） | "This may be due to corrupted export data or a conflict with existing data..." |
| リトライリンク | "Try again" |

## イベント仕様

### 1-Turbo Stream更新

インポートのステータスが変更されると、Turbo Streamsによりページが自動更新される。

1. turbo_stream_from @importでActionCableチャネルを購読
2. broadcasts_refreshesにより、モデル更新時にページがリフレッシュされる
3. ステータスに応じた表示内容に切り替わる

### 2-Go to your account リンク押下（完了時）

新しいアカウントのランディングページに遷移する。

### 3-Try again リンク押下（失敗時）

インポート画面（/account/imports/new）に遷移する。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | account_imports | SELECT | インポート情報を取得 |

### テーブル別更新項目詳細

#### account_imports

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id | params[:id] | URLパラメータから取得 |
| SELECT | status | - | 現在のステータス |
| SELECT | failure_reason | - | 失敗時の理由 |
| SELECT | account_id | - | インポート先アカウント |
| SELECT | identity_id | - | アクセス権限チェック用 |

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|----------|
| 情報 | Your import is in progress. This may take a while for large accounts. | status = pending または processing |
| 成功 | Your import was successful! | status = completed |
| エラー | Import failed | status = failed |
| エラー詳細 | The account you're trying to import already exists. Make sure you're importing a [self-hosted/fizzy.do] account. | failure_reason = conflict |
| エラー詳細 | The .zip file you uploaded doesn't look like a Fizzy account export. | failure_reason = invalid_export |
| エラー詳細 | This may be due to corrupted export data or a conflict with existing data. Please try again with a fresh export. | failure_reason = nil（その他） |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 未ログイン | ログイン画面にリダイレクト（allow_unauthorized_access設定により部分的に許可） |
| インポート実行者以外がアクセス | 403 Forbidden |
| 存在しないインポートID | RecordNotFound例外 |

## 備考

- Turbo Streamsによるリアルタイム更新を実装
- broadcasts_refreshesでモデル更新時に自動リフレッシュ
- publicレイアウトを使用
- SaaSモードとセルフホストモードでエラーメッセージが異なる
- インポート失敗時、アカウントはcleanup処理で削除される場合がある

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | import.rb | `app/models/account/import.rb` | ステータス、failure_reason enum、broadcasts_refreshes |

**読解のコツ**: `broadcasts_refreshes`はHotwireの機能で、モデル更新時にTurbo Streamsでページをリフレッシュする。failure_reasonで失敗理由を判定。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imports_controller.rb | `app/controllers/account/imports_controller.rb` | showアクション、アクセス権限チェック |

**主要処理フロー**:
1. **5行目**: allow_unauthorized_access - 部分的に認証なしアクセスを許可
2. **6行目**: before_action :set_import - インポート情報取得
3. **7行目**: before_action :ensure_accessed_by_owner - 本人確認
4. **22-23行目**: showアクション
5. **26-28行目**: set_importメソッド
6. **30-32行目**: ensure_accessed_by_owner - identity比較

#### Step 3: ビューテンプレートを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | show.html.erb | `app/views/account/imports/show.html.erb` | ステータス別表示切替、Turbo Stream購読 |

**主要処理フロー**:
- **3行目**: turbo_stream_from @import - ActionCableチャネル購読
- **8-30行目**: case @import.statusでステータス別表示
- **9行目**: pending/processing時 - 処理中メッセージ
- **13-16行目**: completed時 - 成功メッセージとアカウントリンク
- **18-29行目**: failed時 - エラーメッセージとリトライリンク
- **21-27行目**: failure_reasonで詳細メッセージを切り替え

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

```
ブラウザ
    │
    └─ GET /account/imports/:id
           └─ Account::ImportsController#show
                  ├─ set_import
                  │      └─ Current.account.imports.find(params[:id])
                  │
                  └─ ensure_accessed_by_owner
                         └─ @import.identity == Current.identity ?

ActionCable（リアルタイム更新）:
    │
    └─ Account::Import 更新
           └─ broadcasts_refreshes
                  └─ Turbo Stream refresh
                         └─ ブラウザがページをリロード
```

### データフロー図

```
[バックグラウンド]              [クライアント]

Account::DataImportJob         ブラウザ
        │                          │
        ▼                          ▼
account_imports更新 ──────────▶ turbo_stream_from
(status変更)                        │
        │                          ▼
        └──────────────────▶ broadcasts_refreshes
                                   │
                                   ▼
                            ページリフレッシュ
                                   │
                                   ▼
                            ステータス別表示
                            ├─ pending/processing: 処理中
                            ├─ completed: 成功 + リンク
                            └─ failed: エラー + リトライ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imports_controller.rb | `app/controllers/account/imports_controller.rb` | コントローラ | インポート画面制御 |
| import.rb | `app/models/account/import.rb` | モデル | インポートモデル、リアルタイム更新 |
| show.html.erb | `app/views/account/imports/show.html.erb` | ビュー | ステータス表示 |
| data_import_job.rb | `app/jobs/account/data_import_job.rb` | ジョブ | インポート処理 |
| import_mailer.rb | `app/mailers/import_mailer.rb` | メーラー | 完了/失敗通知 |
| _footer.html.erb | `app/views/sessions/_footer.html.erb` | パーシャル | フッター |
