# 画面設計書 51-アクセストークン新規作成画面

## 概要

本ドキュメントは、Fizzyアプリケーションにおけるアクセストークン新規作成画面の設計仕様を記述したものである。

### 本画面の処理概要

本画面は、ユーザーがAPI連携用の個人アクセストークンを新規に生成するための画面である。

**業務上の目的・背景**：外部システムやスクリプトからFizzy APIにアクセスするためには、認証用のアクセストークンが必要である。本画面では、ユーザーが自身の権限でAPIアクセスを許可するトークンを発行できる。これにより、パスワードを共有することなく、安全にAPI連携を実現できる。トークンには読み取り専用（Read）と読み書き可能（Read + Write）の2種類の権限レベルを設定でき、最小権限の原則に基づいたアクセス制御が可能である。

**画面へのアクセス方法**：ユーザープロフィール画面からアクセストークン一覧画面へ遷移し、「Generate new token」ボタンをクリックすることで本画面にアクセスする。URLパス `/my/access_tokens/new` に直接アクセスすることも可能である。

**主要な操作・処理内容**：
1. アクセストークンの説明（description）を入力する（例：Github、CI/CD等の用途を識別するための名称）
2. 権限レベル（permission）を選択する（Read または Read + Write）
3. 「Generate access token」ボタンをクリックしてトークンを生成する
4. 「Cancel and go back」リンクで一覧画面に戻る

**画面遷移**：アクセストークン一覧画面（/my/access_tokens）から遷移してくる。トークン生成成功後はアクセストークン詳細画面（/my/access_tokens/:id）に遷移する。キャンセル時はアクセストークン一覧画面に戻る。

**権限による表示制御**：ログイン済みユーザーのみアクセス可能。トークンは各ユーザーの個人認証情報（Identity）に紐づくため、他のユーザーのトークンには干渉できない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | APIアクセストークン管理 | 主機能 | 新しいアクセストークンを生成 |

## 画面種別

登録

## URL/ルーティング

| メソッド | パス | アクション |
|---------|------|-----------|
| GET | /my/access_tokens/new | new（入力フォーム表示） |
| POST | /my/access_tokens | create（トークン生成） |

## 入出力項目

| 項目名 | 項目ID | 型 | 必須 | 入力形式 | 説明 |
|--------|--------|-----|------|----------|------|
| 説明 | description | text | ○ | テキスト入力 | トークンの用途を識別するための説明文（例：Github） |
| 権限 | permission | select | ○ | プルダウン選択 | Read（読み取り専用）/ Read + Write（読み書き可能） |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| ページタイトル | "Generate a personal access token" |
| 戻るリンク | "tokens" - アクセストークン一覧画面へのリンク |
| 説明ラベル | "Access token description" |
| 権限ラベル | "Permission" |
| 生成ボタン | "Generate access token" |
| キャンセルリンク | "Cancel and go back"（hidden属性、ESCキーで表示） |

## イベント仕様

### 1-Generate access token ボタン押下

フォームの入力内容を検証し、アクセストークンを新規作成する。

1. フォームバリデーション（description必須、permission必須）
2. POSTリクエストを `/my/access_tokens` に送信
3. サーバー側でアクセストークンを生成
4. 生成されたトークンIDを暗号化して有効期限付きURL（10秒）を生成
5. アクセストークン詳細画面にリダイレクト

### 2-Cancel and go back リンク押下

アクセストークン一覧画面に遷移する。ESCキー押下時も同様の動作となる。

### 3-ESCキー押下

キャンセル動作をトリガーし、アクセストークン一覧画面に遷移する。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Generate access token押下 | identity_access_tokens | INSERT | 新しいアクセストークンレコードを作成 |

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

#### identity_access_tokens

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | identity_id | Current.identity.id | ログイン中ユーザーのIdentity ID |
| INSERT | description | フォーム入力値 | トークン説明 |
| INSERT | permission | フォーム選択値 | "read" または "write" |
| INSERT | token | SecureRandom生成値 | has_secure_tokenによる自動生成 |
| INSERT | created_at | 現在時刻 | 自動設定 |
| INSERT | updated_at | 現在時刻 | 自動設定 |

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|----------|
| エラー | ブラウザ標準バリデーションメッセージ | description未入力時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 未ログイン | ログイン画面にリダイレクト |
| バリデーションエラー | フォーム再表示（ブラウザ標準バリデーション） |

## 備考

- トークンは生成直後の詳細画面でのみ表示され、以降は再表示できない
- トークンIDはMessageVerifierで暗号化され、10秒間の有効期限が設定される
- ホットキー対応：左矢印キー・ESCキーで戻る操作が可能

---

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

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

### 推奨読解順序

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

まず、アクセストークンのデータモデルを理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | access_token.rb | `app/models/identity/access_token.rb` | アクセストークンモデルの定義、permission enumの設定、has_secure_tokenの使用 |

**読解のコツ**: `has_secure_token`はRails標準のセキュアトークン生成機能。`enum :permission`でread/writeの権限レベルを定義している。

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

処理の起点となるコントローラとルーティングを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | routes.rb | `config/routes.rb` | 174-180行目: `namespace :my`内の`resources :access_tokens`でCRUDルートを定義 |
| 2-2 | access_tokens_controller.rb | `app/controllers/my/access_tokens_controller.rb` | new/createアクションの実装 |

**主要処理フロー**:
1. **12-14行目**: newアクション - 空のAccessTokenインスタンスを生成
2. **16-20行目**: createアクション - トークン作成、暗号化ID生成、リダイレクト
3. **29-31行目**: my_access_tokensメソッド - Current.identity.access_tokensでスコープを限定
4. **37-39行目**: verifierメソッド - MessageVerifierでトークンIDを暗号化

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | new.html.erb | `app/views/my/access_tokens/new.html.erb` | フォーム構造、入力フィールド、Stimulusコントローラの使用 |

**主要処理フロー**:
- **5行目**: back_link_toヘルパーで戻るリンクを生成（ホットキー対応）
- **12行目**: form_withでフォーム生成、formコントローラを使用
- **15行目**: description入力フィールド（required属性、autofocus）
- **20行目**: permission選択プルダウン（Read/Read + Write）
- **23-25行目**: submitボタン
- **27行目**: キャンセルリンク（hidden、ESCキーで表示）

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

```
ブラウザ
    │
    ├─ GET /my/access_tokens/new
    │      └─ My::AccessTokensController#new
    │             └─ @access_token = my_access_tokens.new
    │                    └─ Current.identity.access_tokens.new
    │
    └─ POST /my/access_tokens
           └─ My::AccessTokensController#create
                  ├─ my_access_tokens.create!(access_token_params)
                  │      └─ Identity::AccessToken.create!
                  │             └─ has_secure_token (トークン自動生成)
                  ├─ verifier.generate(id, expires_in: 10.seconds)
                  │      └─ Rails.application.message_verifier(:access_tokens)
                  └─ redirect_to my_access_token_path(expiring_id)
```

### データフロー図

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

description ─────────────▶ AccessTokensController#create ───▶ redirect_to show
permission  ─────────────▶        │                          (encrypted ID)
                                  │
                                  ▼
                          Identity::AccessToken.create!
                                  │
                                  ▼
                          identity_access_tokens テーブル
                          (token自動生成)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| access_tokens_controller.rb | `app/controllers/my/access_tokens_controller.rb` | コントローラ | トークンのCRUD操作を制御 |
| access_token.rb | `app/models/identity/access_token.rb` | モデル | トークンデータモデル定義 |
| new.html.erb | `app/views/my/access_tokens/new.html.erb` | ビュー | 新規作成フォーム |
| routes.rb | `config/routes.rb` | 設定 | ルーティング定義 |
| form_controller.js | `app/javascript/controllers/form_controller.js` | Stimulus | フォーム制御（キャンセル等） |
| hotkey_controller.js | `app/javascript/controllers/hotkey_controller.js` | Stimulus | ホットキー制御 |
