# 画面設計書 19-カード詳細画面

## 概要

本ドキュメントは、Fizzyアプリケーションにおける「カード詳細画面」の設計書です。カードの詳細情報、コメント、ステップ、リアクションなどを表示・操作する画面仕様を定義します。

### 本画面の処理概要

本画面では、個別のカードの詳細情報を表示し、様々な操作（編集、コメント追加、ステップ管理、リアクション、クローズ等）を行うことができます。Fizzyにおけるタスク管理の中心的な画面です。

**業務上の目的・背景**：カードはFizzyにおける最小のタスク単位です。タスクの詳細な内容確認、進捗管理（ステップ）、チームコミュニケーション（コメント）、感情表現（リアクション）など、タスク管理に必要なすべての操作をこの画面で行います。

**画面へのアクセス方法**：カード一覧画面やボード詳細画面からカードプレビューをクリックしてアクセスします。URLは `/cards/:number` です（numberはアカウント内で一意のカード番号）。

**主要な操作・処理内容**：
1. カードタイトル・説明の表示と編集
2. 画像の表示と管理
3. カラムへの振り分け（トリアージ）
4. ステップの作成・編集・完了切り替え
5. コメントの表示・作成・編集・削除
6. リアクションの追加・削除
7. タグの付与・削除
8. 担当者のアサイン
9. カードのピン留め・ウォッチ
10. カードのクローズ・再オープン
11. カードの削除

**画面遷移**：
- 遷移元：カード一覧画面、ボード詳細画面、ボードカラム詳細画面、検索結果、通知
- 遷移先：ボード詳細画面（戻るリンク）、カード編集画面（インライン）

**権限による表示制御**：
- 閲覧：ボードへのアクセス権を持つユーザー
- 削除：カード作成者または管理者のみ

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 19 | カード詳細表示 | 主機能 | カードの詳細情報を表示 |
| 45 | コメント一覧表示 | 補助機能 | カードのコメント一覧を表示 |
| 46 | コメント作成 | 補助機能 | カードにコメントを追加 |
| 49 | カードにリアクション | 補助機能 | カードに絵文字リアクションを追加 |
| 42 | ステップ作成 | 補助機能 | カードにステップを追加 |
| 28 | カードをクローズ | 補助機能 | カードを完了状態にする |
| 33 | カードをピン留め | API連携 | カードをピン留めリストに追加 |
| 35 | カードをウォッチ | API連携 | カードの更新通知を受け取る設定 |

## 画面種別

詳細画面

## URL/ルーティング

| HTTP Method | URL | Controller#Action |
|-------------|-----|-------------------|
| GET | /cards/:id | cards#show |
| GET | /cards/:id/edit | cards#edit |
| PATCH/PUT | /cards/:id | cards#update |
| DELETE | /cards/:id | cards#destroy |

## 入出力項目

なし（詳細表示画面。編集はカード編集画面で処理）

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| ページタイトル | H1/ブラウザタブ | カードのタイトル |
| 戻るリンク | リンク | ボード詳細画面への戻りリンク |
| ボード名 | バッジ/ボタン | 所属ボードの名前（モバイル用ボタン含む） |
| カードタイトル | 見出し | カードのタイトル（編集可能） |
| カード説明 | リッチテキスト | カードの詳細説明（編集可能） |
| 画像 | 画像 | 添付された画像（Lightbox表示） |
| タグ | バッジ群 | カードに付与されたタグ |
| ステップ | チェックリスト | カードのサブタスク |
| 担当者 | アバター群 | アサインされたユーザー |
| 作成者・日時 | メタ情報 | カードの作成情報 |
| リアクション | 絵文字群 | カードへのリアクション |
| コメント一覧 | リスト | カードに投稿されたコメント |
| コメント入力 | フォーム | 新規コメント入力欄 |
| ウォッチャー | アバター群 | カードをウォッチしているユーザー |
| カラム振り分け | ボタン群 | トリアージ用カラム選択UI |
| ピンボタン | ボタン | ピン留め操作 |
| ウォッチボタン | ボタン | ウォッチ操作 |
| クローズボタン | ボタン | 完了操作 |
| 削除ボタン | ボタン | カード削除（権限保持者のみ） |

## イベント仕様

### 1-カード編集

**トリガー**: タイトルまたは説明エリアをクリック

**処理内容**:
1. Turbo FrameでEdit画面をインライン読み込み
2. タイトル・説明の編集フォームを表示
3. 保存後にTurbo Streamsで表示を更新

### 2-コメント作成

**トリガー**: コメント入力フォームで送信

**処理内容**:
1. POST /cards/:card_id/comments
2. Commentレコードを作成
3. Turbo Streamsでコメント一覧に追加

### 3-ステップ作成

**トリガー**: ステップ入力フォームで送信

**処理内容**:
1. POST /cards/:card_id/steps
2. Stepレコードを作成
3. Turbo Streamsでステップ一覧に追加

### 4-ステップ完了切り替え

**トリガー**: ステップのチェックボックスをクリック

**処理内容**:
1. PATCH /cards/:card_id/steps/:id
2. Stepのcompleted状態を更新
3. Turbo Streamsで表示を更新

### 5-カードクローズ

**トリガー**: クローズボタンをクリック

**処理内容**:
1. POST /cards/:card_id/closure
2. Closureレコードを作成
3. カードをクローズドカラムに移動

### 6-カード削除

**トリガー**: 削除ボタンをクリック

**事前条件**:
- Current.userがカード管理権限を持つこと（can_administer_card?がtrue）

**処理内容**:
1. 確認ダイアログの表示
2. DELETE /cards/:id
3. ボード詳細画面にリダイレクト

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | cards | SELECT | カード情報取得 |
| 画面表示 | comments | SELECT | コメント一覧取得 |
| 画面表示 | steps | SELECT | ステップ一覧取得 |
| コメント作成 | comments | INSERT | 新規コメント追加 |
| ステップ作成 | steps | INSERT | 新規ステップ追加 |
| カードクローズ | closures | INSERT | クローズレコード作成 |
| カード削除 | cards | DELETE | カードと関連データ削除 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| M001 | 成功 | Card deleted | カード削除成功時 |

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|----------|----------|
| レコード不存在 | 存在しないカード番号でアクセス | HTTPステータス404を返却 |
| アクセス権なし | ボードへのアクセス権がない | HTTPステータス404を返却 |
| 権限エラー | 削除権限のないユーザーが削除を試行 | HTTPステータス403を返却 |
| 認証エラー | 未ログイン状態でアクセス | ログイン画面にリダイレクト |
| 下書き状態 | 下書きカードにアクセス | カード下書き画面にリダイレクト |

## 備考

- OGP（Open Graph Protocol）タグが設定され、SNS共有時に適切なプレビューが表示されます
- Turbo Streamsによるリアルタイム更新が実装されています
- 画像はLightbox表示に対応しています
- ビーコン機能でカードの閲覧履歴を記録します（reading）
- 共有ボタンでカードURLをコピーできます

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | card.rb | `app/models/card.rb` | Cardモデル、include されているconcern（Commentable, Multistep, Closeable等）を確認 |
| 1-2 | schema.rb | `db/schema.rb` | cardsテーブル（202-218行目）、comments（252-260行目）、steps（705-715行目）を確認 |

**読解のコツ**: Cardモデルは多くのconcernをincludeしています。各機能（コメント、ステップ、クローズ等）はそれぞれのconcernで実装されています。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | routes.rb | `config/routes.rb` | 76-103行目の `resources :cards` とネストされたリソースを確認 |
| 2-2 | cards_controller.rb | `app/controllers/cards_controller.rb` | show/destroy アクション、before_action（set_card, redirect_if_drafted等）を確認 |

**主要処理フロー**:
1. **27-28行目**: `show`アクション - カード詳細表示
2. **56-58行目**: `set_card` - accessible_cardsからカード取得
3. **60-62行目**: `redirect_if_drafted` - 下書き時はリダイレクト

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | show.html.erb | `app/views/cards/show.html.erb` | ページ構造、OGPタグ、Turbo Stream購読を確認 |
| 3-2 | _container.html.erb | `app/views/cards/_container.html.erb` | カードコンテナ、各セクションのパーシャル呼び出しを確認 |
| 3-3 | _messages.html.erb | `app/views/cards/_messages.html.erb` | コメント一覧、新規コメントフォームを確認 |

**主要処理フロー**:
- **1行目(show.html.erb)**: ページタイトルをカードタイトルから設定
- **4-6行目**: OGPタグの設定（card_social_tags）
- **15-16行目**: Turbo Stream購読（リアルタイム更新用）
- **18行目**: ビーコンコントローラー（閲覧記録）
- **19-20行目**: カードコンテナとメッセージ（コメント）のレンダリング
- **22-24行目**: Lightbox設定

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

```
ブラウザ（GET /cards/:id）
    │
    ├─ CardsController#show
    │      ├─ set_card（before_action）
    │      │      └─ Current.user.accessible_cards.find_by!(number: params[:id])
    │      └─ redirect_if_drafted（before_action）
    │             └─ 下書きの場合はcard_draft_pathにリダイレクト
    │
    └─ app/views/cards/show.html.erb
           ├─ card_social_tags（OGPタグ）
           ├─ turbo_stream_from @card
           ├─ turbo_stream_from @card, :activity
           ├─ beacon（閲覧記録）
           ├─ render "cards/container"
           │      ├─ _gild.html.erb（ゴールデン設定）
           │      ├─ _image.html.erb（画像）
           │      ├─ _content.html.erb（タイトル・説明）
           │      ├─ cards/triage/columns（トリアージ）
           │      ├─ _stamp.html.erb（メタ情報）
           │      ├─ reactions/reactions（リアクション）
           │      └─ footer/_published.html.erb（ピン・ウォッチ・クローズ）
           ├─ render "cards/messages"
           │      ├─ comments一覧
           │      ├─ comments/new（新規コメント）
           │      ├─ comments/watchers（ウォッチャー）
           │      └─ cards/delete（削除ボタン、権限者のみ）
           └─ layouts/lightbox
```

### データフロー図

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

card_number ──────────▶ CardsController#show ──────▶ @card
                                 │
                                 ├─ Card.preloaded ────▶ 関連データ取得
                                 │      ├─ comments
                                 │      ├─ steps
                                 │      ├─ tags
                                 │      ├─ assignees
                                 │      └─ reactions
                                 │
                                 └─ render ────────────▶ カード詳細表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| show.html.erb | `app/views/cards/show.html.erb` | テンプレート | カード詳細画面のメインビュー |
| _container.html.erb | `app/views/cards/_container.html.erb` | パーシャル | カードコンテナ |
| _messages.html.erb | `app/views/cards/_messages.html.erb` | パーシャル | コメントセクション |
| _content.html.erb | `app/views/cards/container/_content.html.erb` | パーシャル | タイトル・説明表示 |
| footer/_published.html.erb | `app/views/cards/container/footer/_published.html.erb` | パーシャル | フッターボタン群 |
| cards_controller.rb | `app/controllers/cards_controller.rb` | コントローラー | show/destroyアクション |
| card.rb | `app/models/card.rb` | モデル | カードモデル |
| cards_helper.rb | `app/helpers/cards_helper.rb` | ヘルパー | card_social_tags等 |
| routes.rb | `config/routes.rb` | 設定 | ルーティング定義 |
