# 画面設計書 13-ボードカラム詳細画面

## 概要

本ドキュメントは、Fizzyアプリケーションにおける「ボードカラム詳細画面」の設計書です。ボード内の特定カラムに属するカードの一覧を表示する画面仕様を定義します。

### 本画面の処理概要

本画面では、カンバンボード内の特定のカラム（例：「進行中」「レビュー待ち」等のユーザー定義カラム）に属するカードをグリッド形式で一覧表示します。カードのドラッグ＆ドロップ操作にも対応しています。

**業務上の目的・背景**：カンバンボードでは複数のカラムでカードを分類管理しますが、特定のカラムに絞ってカードを確認したい場合があります。本画面では選択したカラムのカードのみを表示し、そのカラムの作業に集中できる環境を提供します。カラム名を確認しながら、そのカラムに属するカードの進捗確認や操作を行えます。

**画面へのアクセス方法**：ボード詳細画面でカラム名をクリック、またはカラムの「もっと見る」リンクからアクセスします。URLは `/boards/:board_id/columns/:id` です。

**主要な操作・処理内容**：
1. カラムに属するカードの一覧表示
2. カードのプレビュー表示（タイトル、タグ、担当者、ステップ進捗等）
3. カードのドラッグ＆ドロップによる並び替え・移動
4. カードクリックでカード詳細画面へ遷移
5. ページネーション（無限スクロール）

**画面遷移**：
- 遷移元：ボード詳細画面
- 遷移先：カード詳細画面、ボード詳細画面（戻るリンク）

**権限による表示制御**：ボードへのアクセス権を持つユーザーのみ閲覧可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 12 | カラム一覧表示 | 主機能 | ボード内の特定カラムの詳細を表示 |
| 14 | カラム編集 | 補助機能 | カラムの名前や色を編集 |
| 15 | カラム削除 | 補助機能 | カラムを削除 |

## 画面種別

一覧画面（カード一覧）

## URL/ルーティング

| HTTP Method | URL | Controller#Action |
|-------------|-----|-------------------|
| GET | /boards/:board_id/columns/:id | boards/columns#show |

## 入出力項目

なし（閲覧専用画面）

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| ページタイトル | H1見出し | 「Column: {カラム名}」形式 |
| 戻るリンク | リンク | ボード詳細画面への戻りリンク（ボード名表示） |
| カード一覧 | グリッド | カードのプレビュー表示 |
| 空メッセージ | テキスト | カードがない場合「No cards here」を表示 |
| ドラッグヒント | テキスト | ドラッグ中「Drag cards here」を表示 |

### カードプレビュー項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| カードタイトル | テキスト | カードのタイトル |
| ボード名 | バッジ | 所属ボードの名前 |
| タグ | バッジ群 | カードに付与されたタグ |
| ステップ進捗 | 進捗バー | 完了ステップ数/全ステップ数 |
| カラム名 | バッジ | 現在のカラム名（トリアージ済みの場合） |
| 担当者 | アバター群 | アサインされたユーザーのアバター |
| コメント数 | 数値 | コメントの件数 |
| リアクション | アイコン | ブースト（リアクション）の有無 |
| 添付ファイル | アイコン | 添付ファイルの有無 |

## イベント仕様

### 1-カードクリック

**トリガー**: カードプレビューをクリック

**処理内容**:
- カード詳細画面（/cards/:number）に遷移

### 2-ドラッグ＆ドロップ

**トリガー**: カードをドラッグして別の位置にドロップ

**処理内容**:
- カードの表示順序を変更
- 必要に応じてカラム間移動のAPIを呼び出し

### 3-ページネーション

**トリガー**: 画面最下部へのスクロール（自動ページネーション）

**処理内容**:
- 次のページのカードを読み込み
- 既存のカード一覧に追加表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | cards | SELECT | カラムに属するカードを取得 |
| ドラッグ＆ドロップ | cards | UPDATE | カードのカラムまたは順序を更新（別APIで処理） |

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

本画面自体はSELECTのみで、更新操作は別のAPIエンドポイントで処理されます。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| M001 | 情報 | No cards here | カラムにカードが存在しない場合 |
| M002 | ヒント | Drag cards here | ドラッグ操作中 |

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|----------|----------|
| レコード不存在 | 存在しないカラムIDでアクセス | HTTPステータス404を返却 |
| アクセス権なし | ボードへのアクセス権がない | HTTPステータス404を返却 |
| 認証エラー | 未ログイン状態でアクセス | ログイン画面にリダイレクト |

## 備考

- カードは `latest` スコープ（last_active_at降順）でソートされます
- ゴールデンカード（golden）は常に先頭に表示されます（with_golden_first）
- カードのプレビューにはキャッシュが適用されています（cached: true）
- Turbo Framesを使用して部分的な画面更新に対応しています
- ETag/fresh_whenによるHTTPキャッシュが実装されています

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | column.rb | `app/models/column.rb` | Columnモデルの定義、belongs_to :board、has_many :cardsを確認 |
| 1-2 | card.rb | `app/models/card.rb` | Cardモデル、belongs_to :column、スコープ（latest, with_golden_first）を確認 |
| 1-3 | schema.rb | `db/schema.rb` | columnsテーブル（239-250行目）、cardsテーブル（202-218行目）を確認 |

**読解のコツ**: ColumnとCardの1対多の関係、およびCardのソートスコープを理解することが重要です。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | routes.rb | `config/routes.rb` | 42行目の `resources :columns` を確認 |
| 2-2 | columns_controller.rb | `app/controllers/boards/columns_controller.rb` | showアクション、set_columnを確認 |

**主要処理フロー**:
1. **11-14行目**: `show`アクション - カラムのカード一覧を取得、ページネーション、ETagキャッシュ
2. **44-46行目**: `set_column` - ボードに属するカラムを取得
3. **12行目**: `@column.cards.active.latest.with_golden_first.preloaded` - カード取得クエリ

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | show.html.erb | `app/views/boards/columns/show.html.erb` | ページ構造、turbo_frame_tag、ページネーションを確認 |
| 3-2 | _previews.html.erb | `app/views/cards/display/_previews.html.erb` | カードコレクションのレンダリング |
| 3-3 | _preview.html.erb | `app/views/cards/display/_preview.html.erb` | 個別カードのプレビュー表示 |
| 3-4 | _empty_placeholder.html.erb | `app/views/boards/columns/_empty_placeholder.html.erb` | 空状態の表示 |

**主要処理フロー**:
- **1行目(show.html.erb)**: ページタイトル設定（Column: {カラム名}）
- **14行目**: turbo_frame_tagでカード一覧をフレーム化
- **17-18行目**: with_automatic_paginationでページネーション実装
- **21行目**: カードがない場合の空プレースホルダー表示

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

```
ブラウザ（GET /boards/:board_id/columns/:id）
    │
    ├─ Boards::ColumnsController#show
    │      ├─ set_board（BoardScoped concern）
    │      │      └─ Current.user.boards.find(params[:board_id])
    │      ├─ set_column
    │      │      └─ @board.columns.find(params[:id])
    │      ├─ set_page_and_extract_portion_from
    │      │      └─ @column.cards.active.latest.with_golden_first.preloaded
    │      └─ fresh_when（ETagキャッシュ）
    │
    └─ app/views/boards/columns/show.html.erb
           ├─ link_back_to_board(@column.board)
           ├─ turbo_frame_tag @column, :cards
           │      ├─ with_automatic_pagination
           │      │      └─ _previews.html.erb
           │      │             └─ _preview.html.erb（各カード）
           │      └─ _empty_placeholder.html.erb（空の場合）
           └─ ページタイトル表示
```

### データフロー図

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

board_id ─────────────▶ Boards::ColumnsController ────▶ @column
column_id ────────────▶          │                        │
                                 │                        ▼
                                 ├─ @column.cards ────▶ @page.records
                                 │    .active                 │
                                 │    .latest                 │
                                 │    .with_golden_first      │
                                 │    .preloaded              │
                                 │                            │
                                 └─ render ───────────────────┘
                                        │
                                        ▼
                                   カードグリッド表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| show.html.erb | `app/views/boards/columns/show.html.erb` | テンプレート | カラム詳細画面のメインビュー |
| _previews.html.erb | `app/views/cards/display/_previews.html.erb` | パーシャル | カードコレクションのレンダリング |
| _preview.html.erb | `app/views/cards/display/_preview.html.erb` | パーシャル | 個別カードのプレビュー |
| _empty_placeholder.html.erb | `app/views/boards/columns/_empty_placeholder.html.erb` | パーシャル | 空状態表示 |
| columns_controller.rb | `app/controllers/boards/columns_controller.rb` | コントローラー | showアクションの実装 |
| column.rb | `app/models/column.rb` | モデル | カラムモデル定義 |
| card.rb | `app/models/card.rb` | モデル | カードモデル定義 |
| routes.rb | `config/routes.rb` | 設定 | ルーティング定義 |
