# 画面設計書 57-参加コード表示画面

## 概要

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

### 本画面の処理概要

本画面は、アカウントへの招待リンクと参加コードを表示し、新しいメンバーを招待するための画面である。QRコードの生成やリンクのコピー機能も提供する。

**業務上の目的・背景**：組織やチームでFizzyを使用する際、新しいメンバーを簡単に招待できる仕組みが必要である。本画面では、招待リンクを共有することで、メンバーがセルフサービスでアカウントに参加できる。使用回数の制限があり、無制限にメンバーが追加されることを防止できる。また、QRコードを使用することで、対面での招待も容易に行える。

**画面へのアクセス方法**：アカウント設定画面の「Invite people」リンクをクリックしてアクセスする。URLパス `/account/join_code` に直接アクセスすることも可能である。

**主要な操作・処理内容**：
1. 招待リンクをクリップボードにコピーする
2. QRコードをダイアログで表示し、スキャンさせる
3. 管理者は「refresh」ボタンで新しいコードを生成する
4. 管理者は「Change limit」リンクで使用制限を変更する

**画面遷移**：アカウント設定画面から遷移してくる。戻るリンクでアカウント設定画面に戻る。「Change limit」リンクから参加コード編集画面へ遷移する。

**権限による表示制御**：
- 全ユーザー：招待リンクの表示、コピー、QRコード表示が可能
- 管理者（admin）のみ：コードの再生成、使用制限の変更が可能

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 76 | 参加コード管理 | 主機能 | アカウントへの招待リンク・QRコードを表示 |
| 88 | QRコード生成 | 補助機能 | URLのQRコードを生成 |

## 画面種別

詳細

## URL/ルーティング

| メソッド | パス | アクション |
|---------|------|-----------|
| GET | /account/join_code | show（参加コード表示） |
| DELETE | /account/join_code | destroy（コード再生成） |

## 入出力項目

本画面には入力項目はない（表示のみ）。再生成ボタンはDELETEリクエストを送信。

## 表示項目

| 項目名 | 説明 |
|--------|------|
| ページタイトル | "Add people" |
| 戻るリンク | "Account Settings" - アカウント設定画面へのリンク |
| 説明文 | "Share the link below to invite people to this account" |
| 招待リンク | 読み取り専用テキストフィールドに招待URL表示 |
| 再生成ボタン | refreshアイコン - 新しいコードを生成（管理者のみ） |
| コピーボタン | "Copy invite link" |
| QRコードボタン | "Get QR code" - QRコードダイアログを表示 |
| 使用状況 | "This code has been used X/Y times (Z remaining)" |
| 制限変更リンク | "Change limit"（管理者のみ） |

## イベント仕様

### 1-Copy invite link ボタン押下

招待リンクをクリップボードにコピーする。

1. copy-to-clipboardコントローラがクリップボードAPIを呼び出す
2. コピー成功時、ボタンに成功スタイル（btn--success）が適用される

### 2-Get QR code ボタン押下

QRコードダイアログを表示する。

1. dialogコントローラがモーダルダイアログを開く
2. 招待URLのQRコードが表示される
3. 「Done」ボタンでダイアログを閉じる

### 3-refresh ボタン押下（管理者のみ）

新しい参加コードを生成する。

1. 確認ダイアログ表示（turbo_confirm）
2. 確認後、DELETEリクエストを `/account/join_code` に送信
3. JoinCodeモデルのresetメソッドで新しいコードを生成
4. 使用回数がリセットされる
5. 同じ画面にリダイレクト

### 4-Change limit リンク押下（管理者のみ）

参加コード編集画面に遷移する。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | account_join_codes | SELECT | 参加コード情報を取得 |
| refresh押下 | account_join_codes | UPDATE | コード再生成、使用回数リセット |

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

#### account_join_codes

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | - | Current.account.join_code | 現在アカウントの参加コード |
| UPDATE | code | SecureRandom.base58で生成 | 新しいコード |
| UPDATE | usage_count | 0 | リセット |

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|----------|
| 確認 | Are you sure you want to generate a new link? The previous code will stop working. | refresh押下時 |
| 情報 | This code has been used X/Y times (Z remaining) | 常時表示 |
| 警告 | (none remaining) | 使用制限に達した場合（txt-negativeスタイル） |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 未ログイン | ログイン画面にリダイレクト |
| 非管理者がコード再生成を試行 | ensure_adminで403 Forbidden |

## 備考

- 参加コードは12文字、4文字ごとにハイフン区切り（例：XXXX-XXXX-XXXX）
- 使用制限の最大値はUSAGE_LIMIT_MAX = 10,000,000,000
- QRコードはqr_code_imageヘルパーで生成
- View Transitionsを使用したアニメーション対応

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | join_code.rb | `app/models/account/join_code.rb` | コード生成ロジック、active?メソッド、resetメソッド |

**読解のコツ**: `generate_code`メソッドでSecureRandom.base58を使用し、12文字のコードを4文字ごとにハイフン区切りで生成。`active?`でusage_count < usage_limitを判定。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | join_codes_controller.rb | `app/controllers/account/join_codes_controller.rb` | show/destroyアクションの実装 |

**主要処理フロー**:
1. **2行目**: before_action :set_join_code - 参加コード取得
2. **3行目**: before_action :ensure_admin - destroy（再生成）は管理者のみ
3. **5-6行目**: showアクション - ビュー表示
4. **19-22行目**: destroyアクション - コード再生成（reset呼び出し）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | show.html.erb | `app/views/account/join_codes/show.html.erb` | UI構造、QRコードダイアログ |

**主要処理フロー**:
- **5行目**: back_link_toでAccount Settingsへの戻りリンク
- **15行目**: join_urlで招待URL生成
- **17行目**: 読み取り専用テキストフィールドに招待URL
- **19-25行目**: 管理者のみ再生成ボタン表示
- **29-34行目**: copy-to-clipboardコントローラでコピーボタン
- **36-55行目**: dialogコントローラでQRコードダイアログ
- **47行目**: qr_code_imageヘルパーでQRコード生成
- **58-70行目**: 使用状況表示、管理者向けChange limitリンク

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

```
ブラウザ
    │
    ├─ GET /account/join_code
    │      └─ Account::JoinCodesController#show
    │             └─ set_join_code
    │                    └─ @join_code = Current.account.join_code
    │
    └─ DELETE /account/join_code
           └─ Account::JoinCodesController#destroy
                  ├─ ensure_admin (before_action)
                  └─ @join_code.reset
                         ├─ generate_code（新しいコード生成）
                         └─ usage_count = 0（リセット）
```

### データフロー図

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

(なし) ──────────────────▶ JoinCodesController#show ────────▶ show.html.erb
                                 │                              │
                                 ▼                              ├─ 招待リンク
                          account_join_codes                    ├─ QRコード
                          (SELECT)                              └─ 使用状況

refresh押下 ─────────────▶ JoinCodesController#destroy ─────▶ redirect_to show
                                 │
                                 ▼
                          JoinCode#reset
                                 │
                                 ▼
                          account_join_codes
                          (UPDATE: code, usage_count)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| join_codes_controller.rb | `app/controllers/account/join_codes_controller.rb` | コントローラ | 参加コード画面制御 |
| join_code.rb | `app/models/account/join_code.rb` | モデル | 参加コードモデル |
| show.html.erb | `app/views/account/join_codes/show.html.erb` | ビュー | 参加コード表示 |
| copy_to_clipboard_controller.js | `app/javascript/controllers/copy_to_clipboard_controller.js` | Stimulus | コピー機能 |
| dialog_controller.js | `app/javascript/controllers/dialog_controller.js` | Stimulus | QRコードダイアログ |
| qr_code_helper.rb | `app/helpers/qr_code_helper.rb` | ヘルパー | QRコード生成 |
