# 機能設計書 176-リセットトークン

## 概要

本ドキュメントは、Chatwootにおけるアクセストークンリセット機能の設計仕様を定義する。この機能は、ユーザーがAPI認証用のアクセストークンを再生成するためのAPIを提供する。

### 本機能の処理概要

**業務上の目的・背景**：
APIアクセストークンは、外部システムやスクリプトからChatwoot APIにアクセスする際に使用される。セキュリティ上の理由（トークンの漏洩、定期的なローテーション、アクセス権の取り消し等）から、ユーザーがトークンを再生成する機能が必要である。トークンを再生成すると、古いトークンは即座に無効化される。

**機能の利用シーン**：
- APIトークンが外部に漏洩した可能性がある場合
- セキュリティポリシーにより定期的なトークンローテーションが必要な場合
- API連携を行っていた外部システムとの連携を終了する場合
- 新しい連携システムに対して新しいトークンを発行したい場合

**主要な処理内容**：
1. 認証済みユーザーの確認
2. ユーザーのアクセストークンの再生成
3. ユーザー情報のリロード
4. 新しいトークンを含むレスポンス返却

**関連システム・外部連携**：
- AccessToken: アクセストークンの管理
- has_secure_token: Railsのセキュアトークン生成機能

**権限による制御**：
認証済みユーザーのみが自身のアクセストークンを再生成可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 89 | プロフィール設定画面 | 主画面 | アクセストークンのリセット |

## 機能種別

セキュリティ操作 / トークン管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | 認証トークンのみで識別 | - |

### 入力データソース

- 認証トークンからのユーザー識別

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| access_token | String | 新しく生成されたアクセストークン |
| その他 | - | プロフィール情報全体を返却 |

### 出力先

- JSON形式でHTTPレスポンスとして返却

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ POST /api/v1/profile/reset_access_token
2. 認証検証
   └─ current_userから@userを設定
3. トークン再生成
   └─ @user.access_token.regenerate_token
4. ユーザーリロード
   └─ @user.reload
5. レスポンス生成
   └─ 新しいトークンを含むユーザー情報をJSON返却
```

### フローチャート

```mermaid
flowchart TD
    A[POST /api/v1/profile/reset_access_token] --> B{認証済み?}
    B -->|No| C[401 Unauthorized]
    B -->|Yes| D[トークン再生成]
    D --> E[ユーザーリロード]
    E --> F[JSON レスポンス返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-176-01 | 即時無効化 | 古いトークンは再生成と同時に無効化される | トークン再生成時 |
| BR-176-02 | 自動生成 | 新しいトークンはhas_secure_tokenにより自動生成 | regenerate_token呼び出し時 |
| BR-176-03 | リロード必須 | トークン再生成後はユーザー情報をリロード | 再生成後 |

### 計算ロジック

特になし。トークンはhas_secure_tokenにより暗号学的に安全なランダム文字列として生成される。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| トークン再生成 | access_tokens | UPDATE | tokenカラムの更新 |

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

#### access_tokens

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | token | SecureRandom.base58(24) | has_secure_tokenにより生成 |
| UPDATE | updated_at | 現在時刻 | 自動更新 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 401 | Unauthorized | 認証トークンが無効 | 再ログイン |

### リトライ仕様

特になし

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

AccessTokenの更新は暗黙のトランザクション内で実行される。

## パフォーマンス要件

- レスポンス時間: 300ms以内

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

- 認証トークンによるアクセス制御
- 古いトークンは即座に無効化
- 新しいトークンは暗号学的に安全なランダム文字列

## 備考

- トークンはhas_secure_tokenにより生成される（SecureRandom.base58(24)）
- access_tokensテーブルのtokenカラムにはユニークインデックスが設定されている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | access_token.rb | `app/models/access_token.rb` | AccessTokenモデルのスキーマ、has_secure_tokenの使用 |
| 1-2 | access_tokenable.rb | `app/models/concerns/access_tokenable.rb` | ユーザー作成時のトークン自動生成 |

**読解のコツ**: `has_secure_token :token`は、`regenerate_token`メソッドを自動的に提供し、新しいトークンを生成・保存する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | profiles_controller.rb | `app/controllers/api/v1/profiles_controller.rb` | reset_access_tokenアクションの実装 |

**主要処理フロー**:
1. **41行目**: `reset_access_token`アクション定義
2. **42行目**: `@user.access_token.regenerate_token` - トークンの再生成
3. **43行目**: `@user.reload` - ユーザー情報のリロード

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | reset_access_token.json.jbuilder | `app/views/api/v1/profiles/reset_access_token.json.jbuilder` | レスポンスJSON構造 |
| 3-2 | _user.json.jbuilder | `app/views/api/v1/models/_user.json.jbuilder` | access_tokenの出力 |

**主要処理フロー**:
- **_user.json.jbuilder 1行目**: `json.access_token resource.access_token.token` - 新しいトークンを出力

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

```
Api::V1::ProfilesController#reset_access_token
    │
    ├─ @user.access_token
    │      └─ AccessToken (has_one association)
    │
    ├─ AccessToken#regenerate_token
    │      └─ has_secure_token (Rails built-in)
    │             └─ SecureRandom.base58(24)
    │             └─ access_tokens UPDATE
    │
    └─ @user.reload
           └─ User#access_token.token (新しいトークン)
```

### データフロー図

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

POST リクエスト ───────▶ ProfilesController#reset_access_token ───────▶ JSON Response
                              │                                        (新しいaccess_token)
                              ▼
                        AccessToken
                              │
                              └─▶ access_tokens UPDATE (token)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| profiles_controller.rb | `app/controllers/api/v1/profiles_controller.rb` | コントローラー | reset_access_tokenアクションの定義（41-44行目） |
| access_token.rb | `app/models/access_token.rb` | モデル | AccessTokenモデル、has_secure_token定義 |
| access_tokenable.rb | `app/models/concerns/access_tokenable.rb` | concern | トークン自動生成機能 |
| user.rb | `app/models/user.rb` | モデル | AccessTokenableをinclude（49行目） |
| reset_access_token.json.jbuilder | `app/views/api/v1/profiles/reset_access_token.json.jbuilder` | ビュー | レスポンステンプレート |
| _user.json.jbuilder | `app/views/api/v1/models/_user.json.jbuilder` | ビュー | access_tokenの出力 |
| routes.rb | `config/routes.rb` | 設定 | ルーティング定義（375行目） |
