# 画面設計書 28-カードステップ詳細画面

## 概要

本ドキュメントは、Fizzyアプリケーションにおけるカードステップ詳細画面の設計を記述したものです。カードステップ詳細画面は、カードのステップ（サブタスク）を表示するTurbo Frameコンポーネントです。

### 本画面の処理概要

**業務上の目的・背景**：複雑なタスクを管理する際、1つのカードに複数のサブタスク（ステップ）を設定し、進捗をチェックリスト形式で管理できると便利です。ステップ機能により、タスクの細分化と完了状況の追跡が容易になります。この画面は個別のステップ情報を表示し、完了状態の切り替えや編集画面への遷移を提供します。

**画面へのアクセス方法**：カード詳細画面のステップ一覧から個別のステップをクリック、または `/cards/:card_id/steps/:id` に直接アクセスします。通常はTurbo Frameとしてカード詳細画面に埋め込まれます。

**主要な操作・処理内容**：
1. ステップの内容と完了状態の表示
2. チェックボックスによる完了状態の切り替え
3. ステップ内容クリックによる編集画面への遷移

**画面遷移**：
- 遷移元：カード詳細画面（インライン表示）
- 遷移先：カードステップ編集画面（ステップ内容クリック時）

**権限による表示制御**：ログインユーザーのみアクセス可能です。カードにアクセス権限があるユーザーのみ操作可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 42 | ステップ作成 | 主機能 | カードのステップ詳細を表示 |
| 43 | ステップ編集 | 補助機能 | ステップの内容や完了状態を編集 |

## 画面種別

詳細/操作（インライン）

## URL/ルーティング

| HTTPメソッド | URL | コントローラー#アクション |
|-------------|-----|------------------------|
| GET | `/cards/:card_id/steps/:id` | `cards/steps#show` |
| PATCH | `/cards/:card_id/steps/:id` | `cards/steps#update` |

## 入出力項目

| 項目名 | 入出力 | データ型 | 必須 | 説明 |
|-------|-------|---------|-----|------|
| completed | 入力 | Boolean | - | ステップの完了状態 |

## 表示項目

| 項目名 | データソース | 説明 |
|-------|-------------|------|
| 完了チェックボックス | step.completed | チェック状態で完了/未完了を表示 |
| ステップ内容 | step.content | ステップの説明文（クリックで編集画面へ） |

## イベント仕様

### 1-チェックボックス変更

完了チェックボックスの状態を変更すると、即座にステップの完了状態が更新されます。

**処理内容**：
1. フォーム自動送信（`change->form#submit`）
2. `card_step_path`へPATCHリクエスト送信
3. `@step.update!(step_params)`で完了状態を更新
4. Turbo Streamで応答

### 2-ステップ内容クリック

ステップの内容テキストをクリックすると、編集画面に遷移します。

**処理内容**：
1. `edit_card_step_path`へのリンク
2. Turbo Frameでステップ編集画面を読み込み

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | steps | SELECT | ステップ情報の取得 |
| チェックボックス変更 | steps | UPDATE | completedフラグの更新 |
| チェックボックス変更 | cards | UPDATE | updated_atの更新（touch） |

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

#### steps

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | id = params[:id], card_id = @card.id | ステップの取得 |
| UPDATE | completed | true/false | チェックボックスの状態 |
| UPDATE | updated_at | 現在時刻 | 自動更新 |

#### cards

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | updated_at | 現在時刻 | steps belongs_to :card, touch: true |

## メッセージ仕様

本画面では明示的なメッセージ表示はありません。完了状態の変更は即座にUIに反映されます。

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| カードが存在しない | 404エラーページを表示 |
| ステップが存在しない | 404エラーページを表示 |
| カードへのアクセス権限がない | 404エラーページを表示 |

## 備考

- Turbo Frameで読み込まれ、`turbo_frame_tag @step`でフレームを識別します
- `_step.html.erb`パーシャルで実際の表示が行われます
- `form`コントローラーでチェックボックス変更時の自動送信が実装されています
- ステップはリスト形式（`<li>`）で表示されます
- 完了したステップは視覚的に区別されます（チェック状態）

---

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

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

### 推奨読解順序

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

まず、ステップ機能に関連するモデル構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | step.rb | `app/models/step.rb` | Stepモデル、completedスコープ、バリデーション |
| 1-2 | schema.rb | `db/schema.rb` | stepsテーブル（705-715行目） |

**読解のコツ**: Stepモデルはシンプルな構造で、content（内容）とcompleted（完了フラグ）を持ちます。contentには存在チェックのバリデーションがあります。

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

処理の起点となるコントローラーを特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | steps_controller.rb | `app/controllers/cards/steps_controller.rb` | show/updateアクションの処理 |
| 2-2 | card_scoped.rb | `app/controllers/concerns/card_scoped.rb` | CardScopedモジュール |

**主要処理フロー**:
1. **4行目**: `before_action :set_step` - ステップの取得
2. **15-16行目**: `show` - ビューの描画
3. **21-27行目**: `update` - ステップの更新
4. **40-42行目**: `set_step` - カードに属するステップの取得

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

画面の表示内容を構成するビューファイルを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | show.html.erb | `app/views/cards/steps/show.html.erb` | Turbo Frame定義 |
| 3-2 | _step.html.erb | `app/views/cards/steps/_step.html.erb` | ステップのUI |

**主要処理フロー**:
- **1行目**: `turbo_frame_tag @step` - Turbo Frameの定義
- **2行目**: パーシャルをレンダリング
- パーシャル内でチェックボックスと編集リンクを表示

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

```
GET /cards/:card_id/steps/:id
    |
    +-- Cards::StepsController#show
           |
           +-- CardScoped#set_card (before_action)
           |      +-- Current.user.accessible_cards.find_by!
           |
           +-- set_step (before_action)
           |      +-- @card.steps.find(params[:id])
           |
           +-- render 'cards/steps/show'
                  +-- render 'cards/steps/_step'

PATCH /cards/:card_id/steps/:id
    |
    +-- Cards::StepsController#update
           |
           +-- set_step (before_action)
           +-- @step.update!(step_params)
           |
           +-- respond_to turbo_stream / json
```

### データフロー図

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

チェックボックス         StepsController                   Turbo Stream
completed ────────────▶ update ──────────────────────▶ steps UPDATE
                              |                            cards UPDATE (touch)
                              ▼
                        step.update!(completed:)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| steps_controller.rb | `app/controllers/cards/steps_controller.rb` | ソース | ステップ機能コントローラー |
| card_scoped.rb | `app/controllers/concerns/card_scoped.rb` | ソース | カード取得の共通処理 |
| show.html.erb | `app/views/cards/steps/show.html.erb` | テンプレート | ステップ表示のTurbo Frame |
| _step.html.erb | `app/views/cards/steps/_step.html.erb` | テンプレート | ステップパーシャル |
| step.rb | `app/models/step.rb` | ソース | Stepモデル |
| routes.rb | `config/routes.rb` | 設定 | ルーティング定義 |
| schema.rb | `db/schema.rb` | 設定 | データベーススキーマ |
