# 画面設計書 17-ボード参加設定画面

## 概要

本ドキュメントは、Fizzyアプリケーションにおける「ボード参加設定画面」の設計書です。ユーザーがボードへの参加設定（involvement）を更新するためのAPI応答画面の仕様を定義します。

### 本画面の処理概要

本画面は、ユーザーがボードへの参加レベル（アクセスのみ/ウォッチング）を切り替えた際のUI更新を提供します。実際には独立した画面ではなく、ボード詳細画面内のボタンコンポーネントとして機能し、Turbo Streamsによる部分更新で表示が切り替わります。

**業務上の目的・背景**：ボードへのアクセス権を持つユーザーは、そのボードの更新通知を受け取るかどうかを選択できます。「アクセスのみ」は通知なし、「ウォッチング」は通知ありの状態を表します。この切り替えにより、ユーザーは自分に関連するボードの情報だけを効率的に追跡できます。

**画面へのアクセス方法**：ボード詳細画面のヘッダーにある参加設定ボタンをクリックすることで、参加状態が切り替わります。直接的なページ表示はなく、API呼び出しとTurbo応答による更新です。

**主要な操作・処理内容**：
1. 参加設定ボタンのクリック
2. involvement値の切り替え（access_only / watching）
3. ボタン表示の更新

**画面遷移**：
- 遷移元：ボード詳細画面（インライン操作）
- 遷移先：なし（同一画面内で部分更新）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 9 | ボード編集 | 主機能 | ボードへの参加設定を更新 |

## 画面種別

API応答画面（Turbo Streamsコンポーネント）

## URL/ルーティング

| HTTP Method | URL | Controller#Action |
|-------------|-----|-------------------|
| PATCH | /boards/:board_id/involvement | boards/involvements#update |

## 入出力項目

| 項目名 | 項目ID | 入力/出力 | データ型 | 必須 | 最大長 | 説明 |
|--------|--------|-----------|----------|------|--------|------|
| 参加レベル | involvement | 入力 | String | 必須 | - | access_only または watching |
| ウォッチャー表示 | show_watchers | 入力 | Boolean | - | - | ウォッチャー一覧表示フラグ |
| アイコンのみ表示 | icon_only | 入力 | Boolean | - | - | アイコンのみの表示フラグ |

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| 参加設定ボタン | ボタン | 現在の参加状態を示すアイコンとラベル |

## イベント仕様

### 1-参加設定切り替え

**トリガー**: 参加設定ボタンのクリック

**処理内容**:
1. PATCH /boards/:board_id/involvement にリクエスト送信
2. involvement パラメータで新しい参加レベルを指定
3. Access#update!でinvolvement値を更新
4. Turbo応答で新しいボタン状態を返却

**事後処理**:
- ボタンの表示が新しい参加状態に更新される

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 参加設定切り替え | accesses | UPDATE | involvement値を更新 |

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

#### accesses

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | involvement | パラメータで指定された値（access_only/watching） | enum型 |
| UPDATE | updated_at | 現在日時 | 更新日時 |

## メッセージ仕様

なし（視覚的なボタン状態変化のみ）

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|----------|----------|
| レコード不存在 | 存在しないボードIDでアクセス | HTTPステータス404を返却 |
| アクセス権なし | ボードへのアクセス権がない | HTTPステータス404を返却 |
| 認証エラー | 未ログイン状態でアクセス | ログイン画面にリダイレクト |
| 無効なinvolvement値 | 許可されていない値を指定 | バリデーションエラー |

## 備考

- involvementは`access_only`（アクセスのみ）と`watching`（ウォッチング）の2つの状態を持ちます
- `watching`状態のユーザーはボードの更新通知を受け取ります
- このコンポーネントは`access_involvement_advance_button`ヘルパーで生成されます
- Turbo Streamsによる部分更新のため、ページ遷移は発生しません
- アイコン表示やウォッチャー一覧表示はパラメータで制御可能です

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | access.rb | `app/models/access.rb` | involvementのenum定義（access_only/watching）を確認 |
| 1-2 | schema.rb | `db/schema.rb` | accessesテーブル（14-26行目）、involvementカラムを確認 |

**読解のコツ**: involvementはenum型で、`access_only`がデフォルト、`watching`が通知を受け取る状態です。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | routes.rb | `config/routes.rb` | 32行目の `resource :involvement` を確認 |
| 2-2 | involvements_controller.rb | `app/controllers/boards/involvements_controller.rb` | updateアクション、access_for取得を確認 |

**主要処理フロー**:
1. **4-6行目**: `update`アクション - 現在のユーザーのアクセス権を取得し、involvementを更新

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | update.html.erb | `app/views/boards/involvements/update.html.erb` | 更新後のボタン表示を確認 |

**主要処理フロー**:
- **1行目**: `access_involvement_advance_button`ヘルパーでボタンをレンダリング

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

```
ボード詳細画面（参加設定ボタン）
    │
    └─ PATCH /boards/:board_id/involvement
           │
           ├─ Boards::InvolvementsController#update
           │      ├─ set_board（BoardScoped concern）
           │      └─ @board.access_for(Current.user).update!(involvement: params[:involvement])
           │
           └─ app/views/boards/involvements/update.html.erb
                  └─ access_involvement_advance_button（ヘルパー）
                         └─ 新しいボタン状態をレンダリング
```

### データフロー図

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

board_id ─────────────▶ InvolvementsController ─────▶ Access更新
involvement ──────────▶          │
show_watchers ────────▶          │
icon_only ────────────▶          │
                                 │
                                 └─ render ───────────────▶ ボタンHTML
                                                           （Turbo応答）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| update.html.erb | `app/views/boards/involvements/update.html.erb` | テンプレート | 更新後のボタン表示 |
| involvements_controller.rb | `app/controllers/boards/involvements_controller.rb` | コントローラー | updateアクションの実装 |
| access.rb | `app/models/access.rb` | モデル | アクセス権モデル、involvementのenum定義 |
| routes.rb | `config/routes.rb` | 設定 | ルーティング定義 |
