# 機能設計書 199-プラットフォームアカウント

## 概要

本ドキュメントは、ChatwootにおけるPlatform API用アカウント管理機能の設計を記載したものである。この機能により、外部アプリケーションがPlatform APIを通じてアカウントの作成・取得・更新・削除が可能となる。

### 本機能の処理概要

**業務上の目的・背景**：マルチテナント環境でChatwootを運用する場合、顧客ごとにアカウントを作成・管理する必要がある。Platform APIは、外部アプリケーションがプログラムからアカウントのライフサイクルを管理するためのインターフェースを提供する。SaaS製品の統合やホワイトラベルソリューションの構築に不可欠な機能である。

**機能の利用シーン**：SaaS製品が新規顧客にChatwoot環境をプロビジョニングする際にアカウントを自動作成する。管理ダッシュボードからアカウント設定を一括更新する。顧客解約時にアカウントを削除する。

**主要な処理内容**：
1. アカウントの一覧取得（Platform Appに関連付けられたアカウント）
2. アカウントの作成（フィーチャーフラグ設定含む）
3. アカウント情報の取得
4. アカウント情報の更新（フィーチャーフラグ更新含む）
5. アカウントの削除（非同期）

**関連システム・外部連携**：Platform App（api_access_token）を通じた認証。

**権限による制御**：Platform Appに関連付けられたアカウントのみ操作可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | APIのみ（画面なし） |

## 機能種別

CRUD操作

## 入力仕様

### 入力パラメータ

#### createアクション

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | String | Yes | アカウント名 | 必須 |
| locale | String | No | ロケール | - |
| domain | String | No | ドメイン | 最大100文字 |
| support_email | String | No | サポートメールアドレス | 最大100文字 |
| status | String | No | ステータス（active/suspended） | - |
| features | Hash | No | フィーチャーフラグ設定 | - |
| limits | Hash | No | リミット設定 | - |
| custom_attributes | Hash | No | カスタム属性 | - |

#### updateアクション

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | String | No | アカウント名 | - |
| locale | String | No | ロケール | - |
| domain | String | No | ドメイン | 最大100文字 |
| support_email | String | No | サポートメールアドレス | 最大100文字 |
| status | String | No | ステータス | - |
| features | Hash | No | フィーチャーフラグ設定 | - |
| limits | Hash | No | リミット設定 | - |
| custom_attributes | Hash | No | カスタム属性 | - |

### 入力データソース

- Platform API経由のHTTPリクエスト（JSON形式）
- api_access_tokenヘッダーによる認証

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | Integer | アカウントID |
| name | String | アカウント名 |
| locale | String | ロケール |
| domain | String | ドメイン |
| support_email | String | サポートメールアドレス |
| features | Hash | 有効なフィーチャーフラグ |
| custom_attributes | JSON | カスタム属性 |
| limits | JSON | リミット設定 |
| status | String | ステータス |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ api_access_tokenヘッダーの検証
2. Platform App確認
   └─ アクセストークンの所有者がPlatform Appか確認
3. アクション実行
   ├─ index: Platform Appに関連付けられたアカウント一覧を返却
   ├─ show: アカウント情報を返却
   ├─ create: アカウント作成 + フィーチャー設定 + Permissible作成
   ├─ update: アカウント情報更新 + フィーチャー設定
   └─ destroy: 非同期削除ジョブ発行
4. Permissible検証（show/update/destroy）
   └─ Platform Appに関連付けられているか確認
```

### フローチャート

```mermaid
flowchart TD
    A[リクエスト受信] --> B{api_access_token有効?}
    B -->|No| C[401 Unauthorized]
    B -->|Yes| D{Platform App?}
    D -->|No| C
    D -->|Yes| E{アクション?}
    E -->|index| F[Permissible Account一覧取得]
    E -->|show| G[set_resource + validate_permissible]
    E -->|create| H[Account.create!]
    E -->|update| G
    E -->|destroy| G
    G --> I{Permissible?}
    I -->|No| J[401 Non permissible]
    I -->|Yes| K[処理実行]
    H --> L[update_resource_features]
    L --> M[Permissible作成]
    F --> N[レスポンス返却]
    K --> N
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-199-01 | Platform App認証 | api_access_tokenがPlatform Appに紐づいている必要がある | 常時 |
| BR-199-02 | Permissible検証 | 操作対象リソースがPlatform Appに関連付けられている必要がある | show/update/destroy |
| BR-199-03 | フィーチャー有効化 | features[key]がtrueの場合、該当フィーチャーを有効化 | create/update |
| BR-199-04 | フィーチャー無効化 | features[key]がfalseまたは空の場合、該当フィーチャーを無効化 | create/update |
| BR-199-05 | 非同期削除 | 削除はDeleteObjectJobで非同期実行 | destroy |
| BR-199-06 | index一覧制限 | indexはPermissibleに関連付けられたアカウントのみ返却 | index |

### 計算ロジック

**フィーチャーフラグ更新**:
```ruby
def update_resource_features
  return if permitted_params[:features].blank?

  permitted_params[:features].each do |key, value|
    value.present? ? @resource.enable_features(key) : @resource.disable_features(key)
  end
end
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| index | platform_app_permissibles, accounts | SELECT | 関連アカウント一覧取得 |
| show | accounts | SELECT | アカウント情報取得 |
| create | accounts | INSERT | アカウント作成 |
| create | platform_app_permissibles | INSERT | Permissible関連付け |
| update | accounts | UPDATE | アカウント情報更新 |
| destroy | accounts | DELETE | アカウント削除（非同期） |

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

#### accounts

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id | params[:id] | - |
| INSERT | name, locale, domain, support_email, status, limits, custom_attributes | リクエストパラメータ | - |
| UPDATE | name, locale, domain, support_email, status, limits, custom_attributes | リクエストパラメータ | - |

#### platform_app_permissibles

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | permissible_type = 'Account' | Platform App ID | index用 |
| INSERT | platform_app_id, permissible_type, permissible_id | Platform App ID, 'Account', Account ID | find_or_create_by |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 401 | Unauthorized | api_access_tokenが無効 | エラーメッセージ「Invalid access_token」 |
| 401 | Unauthorized | Platform Appに関連付けられていないリソース | エラーメッセージ「Non permissible resource」 |

### リトライ仕様

なし

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

- アカウント作成、フィーチャー設定、Permissible作成は同一リクエスト内で実行
- 削除は非同期ジョブで実行

## パフォーマンス要件

- DeleteObjectJobによる非同期削除でレスポンス時間を短縮

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

- api_access_tokenによるPlatform App認証
- Permissible検証によるアクセス制御

## 備考

- フィーチャーフラグはenable_features/disable_featuresメソッドで制御される
- limitsパラメータはEnterprise版でのリソース制限に使用される可能性がある

---

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

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

### 推奨読解順序

#### Step 1: 基底コントローラーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | platform_controller.rb | `app/controllers/platform_controller.rb` | Platform API共通処理 |

**主要処理フロー**:
1. **4行目**: `before_action :ensure_access_token` - トークン検証
2. **5行目**: `before_action :set_platform_app` - Platform App設定
3. **6-7行目**: `before_action :set_resource, :validate_platform_app_permissible` - リソース検証
4. **17-20行目**: `ensure_access_token`メソッド - トークン取得
5. **22-25行目**: `set_platform_app`メソッド - Platform App検証
6. **32-36行目**: `validate_platform_app_permissible`メソッド - Permissible検証

#### Step 2: アカウントコントローラーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | accounts_controller.rb | `app/controllers/platform/api/v1/accounts_controller.rb` | アカウント管理API |

**主要処理フロー**:
1. **2-7行目**: `index`アクション - Permissibleアカウント一覧取得
2. **9行目**: `show`アクション - アカウント情報表示
3. **11-16行目**: `create`アクション - アカウント作成 + フィーチャー設定 + Permissible作成
4. **18-22行目**: `update`アクション - アカウント情報更新 + フィーチャー設定
5. **24-27行目**: `destroy`アクション - アカウント削除
6. **31-33行目**: `set_resource`メソッド - リソース設定
7. **35-37行目**: `account_params`メソッド - パラメータ取得（features除外）
8. **39-45行目**: `update_resource_features`メソッド - フィーチャーフラグ更新
9. **47-49行目**: `permitted_params`メソッド - 許可パラメータ定義

**読解のコツ**: `account_params`はfeaturesを除外し、`update_resource_features`でフィーチャーフラグを個別に処理している。これはenable_features/disable_featuresメソッドを使用するためである。

#### Step 3: ビューを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | _account.json.jbuilder | `app/views/platform/api/v1/models/_account.json.jbuilder` | JSON出力形式 |

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

```
Platform::Api::V1::AccountsController
    │
    ├─ PlatformController (継承)
    │      ├─ ensure_access_token
    │      ├─ set_platform_app
    │      └─ validate_platform_app_permissible
    │
    ├─ index
    │      └─ platform_app_permissibles.where(permissible_type: 'Account')
    │             └─ includes(:permissible).map(&:permissible)
    │
    ├─ create
    │      ├─ Account.create!(account_params)
    │      ├─ update_resource_features
    │      │      ├─ enable_features(key)
    │      │      └─ disable_features(key)
    │      └─ platform_app_permissibles.find_or_create_by(...)
    │
    ├─ update
    │      ├─ assign_attributes(account_params)
    │      ├─ update_resource_features
    │      └─ save!
    │
    └─ destroy
           └─ DeleteObjectJob.perform_later(@resource)
```

### データフロー図

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

api_access_token   ───▶ PlatformController
(Header)                    │
                            ▼
                    ensure_access_token
                            │
                            ▼
                    set_platform_app
                            │
                            ▼
name, locale,      ───▶ AccountsController#create
domain,                     │
support_email,              ▼
features,          ───▶ Account.create!(account_params)
limits,                     │
custom_attributes           ▼
                    update_resource_features
                            │
                            ▼
                    enable_features / disable_features
                            │
                            ▼
                    find_or_create_by(permissible)
                            │
                            ▼
                    { account JSON }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| accounts_controller.rb | `app/controllers/platform/api/v1/accounts_controller.rb` | ソース | アカウント管理APIコントローラー |
| platform_controller.rb | `app/controllers/platform_controller.rb` | ソース | Platform API基底コントローラー |
| _account.json.jbuilder | `app/views/platform/api/v1/models/_account.json.jbuilder` | テンプレート | JSON出力テンプレート |
| account.rb | `app/models/account.rb` | ソース | Accountモデル |
| platform_app_permissible.rb | `app/models/platform_app_permissible.rb` | ソース | Permissibleモデル |
| routes.rb | `config/routes.rb` | 設定 | ルーティング定義（496-502行目） |
