# 画面設計書 58-参加コード編集画面

## 概要

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

### 本画面の処理概要

本画面は、参加コードの使用制限回数を変更するための画面である。管理者が招待リンクの使用可能回数を調整できる。

**業務上の目的・背景**：アカウントへの招待は使用回数制限により管理されている。本画面では、管理者が使用制限を増減させることで、新規メンバーの受け入れ可否をコントロールできる。使用制限が0になると招待リンクは無効となり、追加のメンバー招待ができなくなる。組織のポリシーや状況に応じて柔軟に制限を調整できる。

**画面へのアクセス方法**：参加コード表示画面の「Change limit」リンクをクリックしてアクセスする。URLパス `/account/join_code/edit` に直接アクセスすることも可能である（管理者のみ）。

**主要な操作・処理内容**：
1. 使用制限（usage_limit）の数値を変更する
2. 「Save changes」ボタンをクリックして変更を保存する
3. 「Go back」リンクで参加コード表示画面に戻る

**画面遷移**：参加コード表示画面から遷移してくる。戻るリンクまたはESCキーで参加コード表示画面に戻る。変更保存後も参加コード表示画面にリダイレクトされる。

**権限による表示制御**：管理者（admin）のみアクセス可能。非管理者がアクセスすると403 Forbiddenとなる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 76 | 参加コード管理 | 主機能 | 参加コードの利用制限を編集 |

## 画面種別

編集

## URL/ルーティング

| メソッド | パス | アクション |
|---------|------|-----------|
| GET | /account/join_code/edit | edit（編集画面表示） |
| PATCH | /account/join_code | update（使用制限更新） |

## 入出力項目

| 項目名 | 項目ID | 型 | 必須 | 入力形式 | 説明 |
|--------|--------|-----|------|----------|------|
| 使用制限 | usage_limit | number | ○ | 数値入力 | 0〜10,000,000,000の整数 |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| ページタイトル | "Change usage limit" |
| 戻るリンク | "Invite link" - 参加コード表示画面へのリンク |
| 説明文 | "How many times can this link be used to join the account?" |
| 使用制限入力 | 数値入力フィールド（autofocus） |
| エラーメッセージ | バリデーションエラー時に表示 |
| 使用状況 | "This code has been used X/Y times." |
| 保存ボタン | "Save changes" |
| キャンセルリンク | "Go back"（hidden、ESCキーで使用） |

## イベント仕様

### 1-Save changes ボタン押下

使用制限を更新する。

1. フォームバリデーション（required、数値範囲チェック）
2. PATCHリクエストを `/account/join_code` に送信
3. サーバー側でモデルバリデーション（USAGE_LIMIT_MAX以下）
4. バリデーション成功時は参加コード表示画面にリダイレクト
5. バリデーション失敗時は編集画面を再表示（422 Unprocessable Entity）

### 2-Go back リンク押下 / ESCキー押下

参加コード表示画面に遷移する。

### 3-入力フィールドフォーカス時

formコントローラのselectアクションで入力値が全選択される。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | account_join_codes | SELECT | 参加コード情報を取得 |
| Save changes押下 | account_join_codes | UPDATE | 使用制限を更新 |

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

#### account_join_codes

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | - | Current.account.join_code | 現在アカウントの参加コード |
| UPDATE | usage_limit | フォーム入力値 | 0〜10,000,000,000 |

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|----------|
| 情報 | This code has been used X/Y times. | 常時表示 |
| エラー | cannot be larger than the population of the planet | usage_limitが10,000,000,000超過時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 未ログイン | ログイン画面にリダイレクト |
| 非管理者がアクセス | ensure_adminで403 Forbidden |
| バリデーションエラー | 編集画面を再表示（422 Unprocessable Entity） |

## 備考

- 使用制限の最大値はUSAGE_LIMIT_MAX = 10,000,000,000
- エラーメッセージは「地球人口より大きくできない」というユニークな表現
- 入力フィールドは8ch幅で中央揃え、大きなフォントサイズで表示
- View Transitionsを使用したアニメーション対応
- usage_limit_in_databaseメソッドで保存前の値を取得し表示

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | join_code.rb | `app/models/account/join_code.rb` | usage_limitバリデーション、USAGE_LIMIT_MAX定数 |

**読解のコツ**: `validates :usage_limit, numericality: { less_than_or_equal_to: USAGE_LIMIT_MAX }`でバリデーション。エラーメッセージは「cannot be larger than the population of the planet」。

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

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

**主要処理フロー**:
1. **3行目**: before_action :ensure_admin - editとupdateは管理者のみ
2. **8-9行目**: editアクション - フォーム表示
3. **11-16行目**: updateアクション - 使用制限更新、バリデーション処理

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | edit.html.erb | `app/views/account/join_codes/edit.html.erb` | 数値入力フォーム、エラー表示 |

**主要処理フロー**:
- **5行目**: back_link_toで参加コード表示画面への戻りリンク
- **12行目**: 説明文表示
- **15行目**: form_withでフォーム生成、formコントローラ使用
- **16-20行目**: number_fieldで使用制限入力（範囲制限付き）
- **22-28行目**: エラーメッセージ表示
- **30-32行目**: 現在の使用状況表示（usage_limit_in_database）
- **34-36行目**: 保存ボタン
- **38行目**: キャンセルリンク（hidden）

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

```
ブラウザ
    │
    ├─ GET /account/join_code/edit
    │      └─ Account::JoinCodesController#edit
    │             ├─ ensure_admin (before_action)
    │             └─ set_join_code
    │                    └─ @join_code = Current.account.join_code
    │
    └─ PATCH /account/join_code
           └─ Account::JoinCodesController#update
                  ├─ ensure_admin (before_action)
                  ├─ @join_code.update(join_code_params)
                  │      ├─ 成功時 → redirect_to show
                  │      └─ 失敗時 → render :edit, status: :unprocessable_entity
                  └─ join_code_params
                         └─ params.expect(account_join_code: [ :usage_limit ])
```

### データフロー図

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

usage_limit ─────────────▶ JoinCodesController#update ────▶ redirect_to show
(数値)                            │                          or
                                  ▼                        render :edit
                          JoinCode.update
                                  │
                                  ├─ バリデーション成功
                                  │      └─ account_join_codes UPDATE
                                  │
                                  └─ バリデーション失敗
                                         └─ エラーメッセージ表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| join_codes_controller.rb | `app/controllers/account/join_codes_controller.rb` | コントローラ | 参加コード画面制御 |
| join_code.rb | `app/models/account/join_code.rb` | モデル | 参加コードモデル、バリデーション |
| edit.html.erb | `app/views/account/join_codes/edit.html.erb` | ビュー | 編集フォーム |
| form_controller.js | `app/javascript/controllers/form_controller.js` | Stimulus | フォーム制御（select、cancel） |
| hotkey_controller.js | `app/javascript/controllers/hotkey_controller.js` | Stimulus | ホットキー制御 |
