# 機能設計書 203-アクセストークン

## 概要

本ドキュメントは、Chatwootのアクセストークン管理機能について記載する。Super Admin管理画面から、ユーザー、エージェントボット、プラットフォームアプリに紐づくアクセストークンを管理する機能である。

### 本機能の処理概要

アクセストークン管理機能は、API認証に使用されるトークンをSuper Admin画面で一元管理する機能である。Chatwootでは各種エンティティ（User、AgentBot、PlatformApp）がAPIアクセス用のトークンを持ち、このトークンによりAPI呼び出しの認証・認可が行われる。

**業務上の目的・背景**：APIベースの統合やボット開発を行う際、アクセストークンが必要となる。システム管理者は、発行されたトークンの状況を把握し、必要に応じてトークンの無効化や再発行を行う必要がある。本機能により、全テナントにわたるトークンを一元的に管理できる。

**機能の利用シーン**：
- システム管理者が発行済みトークンの一覧を確認する場面
- セキュリティインシデント発生時に特定のトークンを無効化する場面
- 新規ボットやプラットフォームアプリにトークンを発行する場面
- トークンの所有者（User/AgentBot/PlatformApp）別にフィルタリングする場面

**主要な処理内容**：
1. アクセストークンの一覧表示
2. 所有者タイプ別のフィルタリング（User/AgentBot/PlatformApp）
3. トークンの詳細表示
4. トークンの新規作成
5. トークンの削除

**関連システム・外部連携**：アクセストークンはChatwootのAPI認証に使用される。Platform API、Agent Bot API、ユーザーAPIなど、各種APIエンドポイントへのアクセスに利用される。

**権限による制御**：本機能はSuper Admin権限を持つユーザーのみがアクセス可能である。トークン自体はSecretFieldとして表示され、全文は表示されない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Access Tokens一覧 | 主画面 | トークンの一覧表示・フィルタリング |
| - | Access Token詳細 | 詳細画面 | トークン詳細の表示 |
| - | Access Token作成 | 作成画面 | 新規トークンの発行 |

## 機能種別

CRUD操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| owner_type | String | Yes | 所有者タイプ（User/AgentBot/PlatformApp） | 許可された値のみ |
| owner_id | Integer | Yes | 所有者ID | 存在チェック |
| token | String | No | トークン値（自動生成も可） | 一意性チェック |

### 入力データソース

Super Admin管理画面のフォーム入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | Integer | トークンID |
| owner | Polymorphic | 所有者（User/AgentBot/PlatformApp） |
| token | String | トークン値（マスク表示） |
| created_at | DateTime | 作成日時 |
| updated_at | DateTime | 更新日時 |

### 出力先

- Super Admin管理画面の一覧ビュー
- Super Admin管理画面の詳細ビュー

## 処理フロー

### 処理シーケンス

```
1. 認証チェック
   └─ Super Adminとしてログインしているか確認
2. トークン一覧取得（indexアクション）
   └─ オプションでフィルタ適用（user/agent_bot/platform_app）
3. トークン詳細表示（showアクション）
   └─ トークン値は部分的にマスク表示
4. トークン作成（createアクション）
   └─ has_secure_tokenにより自動生成
5. トークン削除（destroyアクション）
   └─ 該当トークンを無効化
```

### フローチャート

```mermaid
flowchart TD
    A[Super Admin アクセス] --> B{認証済み?}
    B -->|No| C[ログイン画面へリダイレクト]
    B -->|Yes| D{アクション種別}
    D -->|index| E[トークン一覧取得]
    E --> F{フィルタ指定?}
    F -->|Yes| G[所有者タイプでフィルタ]
    F -->|No| H[全件表示]
    D -->|show| I[トークン詳細表示]
    D -->|create| J[トークン自動生成]
    J --> K[保存]
    D -->|destroy| L[トークン削除]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | トークン一意性 | トークン値はシステム全体で一意 | 作成・更新時 |
| BR-002 | 自動生成 | トークンはhas_secure_tokenにより自動生成可能 | 作成時 |
| BR-003 | ポリモーフィック関連 | 所有者はUser/AgentBot/PlatformAppのいずれか | 常時 |
| BR-004 | マスク表示 | トークンは詳細画面でもSecretFieldとして扱われる | 表示時 |

### 計算ロジック

トークンの自動生成は`has_secure_token`により行われる：
```ruby
class AccessToken < ApplicationRecord
  has_secure_token :token
end
```

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 一覧表示 | access_tokens | SELECT | 全トークンまたはフィルタ済み取得 |
| 詳細表示 | access_tokens | SELECT | 個別トークン取得 |
| 新規作成 | access_tokens | INSERT | トークン発行 |
| 削除 | access_tokens | DELETE | トークン無効化 |

### テーブル別操作詳細

#### access_tokens

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | owner_type条件（オプション） | フィルタ可能 |
| INSERT | owner_type, owner_id, token | 入力値/自動生成 | has_secure_token |
| DELETE | - | id指定 | 完全削除 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 401 | 認証エラー | Super Admin未ログイン | ログイン画面へリダイレクト |
| 404 | 存在しないリソース | 指定IDのトークンが存在しない | エラーページ表示 |
| 422 | バリデーションエラー | 所有者が存在しない | エラーメッセージ表示 |

### リトライ仕様

本機能にリトライ処理は実装されていない。

## トランザクション仕様

単一レコードの操作のため、明示的なトランザクション制御は不要。

## パフォーマンス要件

特別なパフォーマンス要件なし。

## セキュリティ考慮事項

- Super Admin権限のみアクセス可能
- トークンはSecretFieldとして表示（全文表示しない）
- トークンはハッシュ化されずに保存されているため、データベースアクセスに注意
- 不要なトークンは速やかに削除することを推奨

## 備考

- Administrate gemによる管理画面フレームワークを使用
- ポリモーフィック関連により、複数のモデルタイプを所有者として設定可能
- COLLECTION_FILTERSにより所有者タイプでフィルタリング可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | access_token.rb | `app/models/access_token.rb` | テーブル構造、ポリモーフィック関連、has_secure_token |

**読解のコツ**:
- `has_secure_token :token`によりトークンが自動生成される
- `belongs_to :owner, polymorphic: true`により複数モデルを所有者として設定可能
- tokenカラムにユニークインデックスが設定されている

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | access_tokens_controller.rb | `app/controllers/super_admin/access_tokens_controller.rb` | CRUD操作のカスタマイズポイント |

**主要処理フロー**:
- コントローラーはほぼデフォルト実装を使用
- Administrateの標準CRUDアクションが使用される

#### Step 3: ダッシュボード定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | access_token_dashboard.rb | `app/dashboards/access_token_dashboard.rb` | 管理画面の表示項目定義とフィルタ |

**主要処理フロー**:
- **10-16行目**: 属性タイプ定義（Polymorphic、SecretField）
- **32-34行目**: SHOW_PAGE_ATTRIBUTESでtokenのみ表示
- **54-58行目**: COLLECTION_FILTERSで所有者タイプフィルタ

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

```
SuperAdmin::AccessTokensController
    │
    ├─ index
    │      └─ AccessToken.all
    │             └─ COLLECTION_FILTERS適用（オプション）
    │
    ├─ show
    │      └─ AccessToken.find(id)
    │
    ├─ create
    │      └─ AccessToken.new
    │             └─ has_secure_token :token（自動生成）
    │
    └─ destroy
           └─ AccessToken.destroy
```

### データフロー図

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

フォーム入力 ────▶ AccessTokensController ───▶ 一覧/詳細ビュー
(owner_type,            │
 owner_id)         ┌────┴────┐
                   ▼         ▼
              バリデーション  トークン生成
                   │         (has_secure_token)
                   └────┬────┘
                        ▼
                   access_tokens
                   テーブル操作
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| access_tokens_controller.rb | `app/controllers/super_admin/access_tokens_controller.rb` | コントローラー | CRUD操作の制御 |
| access_token.rb | `app/models/access_token.rb` | モデル | トークンデータの管理 |
| access_token_dashboard.rb | `app/dashboards/access_token_dashboard.rb` | ダッシュボード | 管理画面の表示定義 |
| application_controller.rb | `app/controllers/super_admin/application_controller.rb` | コントローラー | Super Admin共通処理 |
