# 機能設計書 8-アカウント作成・管理

## 概要

本ドキュメントは、Chatwootシステムにおけるアカウント作成・管理機能の設計を記載する。複数アカウント対応、サブスクリプション管理、アカウント設定の管理を実現する。

### 本機能の処理概要

本機能は、Chatwootにおける組織単位（アカウント）の作成・管理を行い、複数のワークスペースを独立して運営できる基盤を提供する。

**業務上の目的・背景**：SaaS型のカスタマーサポートシステムでは、複数の組織（企業、チーム）が独立したワークスペースで業務を行う必要がある。本機能により、組織ごとにインボックス、エージェント、会話を分離し、データのセキュリティと管理の独立性を確保する。

**機能の利用シーン**：
- 新規ユーザーがサインアップして自社のアカウントを作成
- 管理者がアカウント名、ドメイン、ロケール等の設定を変更
- 複数アカウントを持つユーザーがアカウントを切り替え
- アカウント削除（契約終了時）

**主要な処理内容**：
1. アカウントの新規作成（ユーザー登録と同時）
2. アカウント情報の表示・更新
3. アカウント設定（自動解決、ロケール等）の管理
4. アクティビティ追跡（active_at更新）
5. キャッシュキーの取得

**関連システム・外部連携**：
- Stripe（Enterprise版サブスクリプション管理）
- Captcha（hCaptcha/reCAPTCHA、スパム防止）

**権限による制御**：アカウント作成は誰でも可能（ENABLE_ACCOUNT_SIGNUP=true時）。アカウント更新はadministratorロールのみ。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | サインアップ画面 | 主画面 | 新規ユーザー登録とアカウント作成 |
| 7 | アカウント停止画面 | 参照画面 | 停止されたアカウントの状態表示 |
| 8 | アカウントなし画面 | 参照画面 | アカウントが存在しない状態の表示 |
| 45 | 一般設定画面 | 主画面 | アカウントの一般設定管理 |
| 77 | 請求設定画面 | 参照画面 | 請求・課金の設定 |

## 機能種別

CRUD操作 / 設定管理

## 入力仕様

### 入力パラメータ

#### アカウント作成（create）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| account_name | String | Yes | アカウント名 | 必須 |
| user_full_name | String | Yes | ユーザー表示名 | 必須 |
| email | String | Yes | ユーザーメールアドレス | 有効なメール形式、重複不可 |
| password | String | No | ユーザーパスワード | パスワードポリシー準拠 |
| locale | String | No | ロケール設定 | 対応ロケールのみ |
| h_captcha_client_response | String | No | Captcha検証トークン | Captcha有効時必須 |

#### アカウント更新（update）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | String | No | アカウント名 | 必須 |
| locale | String | No | ロケール設定 | 対応ロケールのみ |
| domain | String | No | ドメイン | 100文字以内 |
| support_email | String | No | サポートメール | 有効なメール形式 |
| auto_resolve_after | Integer | No | 自動解決時間（分） | 10〜1,439,856 |
| auto_resolve_message | String | No | 自動解決メッセージ | - |

### 入力データソース

- 画面入力（サインアップ画面、一般設定画面）
- API（Platform API）

## 出力仕様

### 出力データ

#### アカウント情報

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | Integer | アカウントID |
| name | String | アカウント名 |
| locale | String | ロケール設定 |
| domain | String | ドメイン |
| support_email | String | サポートメール |
| feature_flags | Object | 有効な機能フラグ |
| custom_attributes | Object | カスタム属性 |

### 出力先

- データベース（accountsテーブル、usersテーブル、account_usersテーブル）
- HTTPレスポンスボディ（JSON形式）

## 処理フロー

### 処理シーケンス

```
【アカウント作成フロー】
1. サインアップ要求
   └─ AccountsController#create
   └─ Captcha検証

2. メール検証
   └─ Account::SignUpEmailValidationService
   └─ フリーメールドメインチェック（設定による）

3. ユーザー重複チェック
   └─ User.exists?(email: email)

4. アカウント・ユーザー作成
   └─ AccountBuilder.perform（トランザクション内）
   └─ Account.create!
   └─ User.create!
   └─ AccountUser.create!（administratorロール）

5. 認証トークン返却
   └─ send_auth_headers
   └─ ユーザー情報返却

【アカウント更新フロー】
6. 更新要求
   └─ AccountsController#update
   └─ administratorロール確認

7. アカウント情報更新
   └─ account.assign_attributes
   └─ account.save!
```

### フローチャート

```mermaid
flowchart TD
    A[サインアップ要求] --> B{Captcha検証}
    B -->|失敗| C[422エラー]
    B -->|成功| D{メール検証}
    D -->|失敗| E[InvalidEmailエラー]
    D -->|成功| F{ユーザー存在?}
    F -->|Yes| G[UserExistsエラー]
    F -->|No| H[AccountBuilder.perform]
    H --> I[Account.create!]
    I --> J[User.create!]
    J --> K[AccountUser.create!]
    K --> L[認証トークン生成]
    L --> M[200 OK + ユーザー情報]

    N[アカウント更新要求] --> O{administrator?}
    O -->|No| P[403 Forbidden]
    O -->|Yes| Q[account.assign_attributes]
    Q --> R[account.save!]
    R --> S[200 OK]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | サインアップ制御 | ENABLE_ACCOUNT_SIGNUP=falseの場合、新規登録不可 | サインアップ時 |
| BR-002 | 初期ロール | アカウント作成者はadministratorロール | アカウント作成時 |
| BR-003 | フリーメール制限 | 設定によりフリーメールドメインを制限 | サインアップ時 |
| BR-004 | ドメイン長制限 | ドメインは100文字以内 | アカウント更新時 |
| BR-005 | 自動解決時間範囲 | 10分〜999日（1,439,856分） | 設定更新時 |
| BR-006 | ロケール検証 | 対応ロケールのみ設定可能 | 設定更新時 |

### 計算ロジック

- **auto_resolve_duration**: auto_resolve_afterの値が自動解決の分数として使用

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| アカウント作成 | accounts | INSERT | 新規アカウントレコード作成 |
| ユーザー作成 | users | INSERT | 新規ユーザーレコード作成 |
| 紐付け作成 | account_users | INSERT | ユーザー・アカウント紐付け |
| アカウント取得 | accounts | SELECT | アカウント情報取得 |
| アカウント更新 | accounts | UPDATE | アカウント情報更新 |

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

#### accounts

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | account_name パラメータ | 必須 |
| INSERT | locale | I18n.locale | デフォルト: en |
| UPDATE | name, locale, domain, support_email | 各パラメータ値 | - |
| UPDATE | settings | auto_resolve_after等 | JSONB |
| UPDATE | custom_attributes | industry, company_size等 | JSONB |

#### account_users

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | account_id | 作成されたアカウントID | - |
| INSERT | user_id | 作成されたユーザーID | - |
| INSERT | role | administrator (1) | 初回作成時 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 404 | Not Found | ENABLE_ACCOUNT_SIGNUP=false | 管理者に連絡 |
| 422 | Unprocessable Entity | 無効なメールアドレス | 正しいメールアドレスで再試行 |
| 422 | Unprocessable Entity | ユーザーが既に存在 | ログインを試行 |
| 422 | Unprocessable Entity | Captcha検証失敗 | Captchaを再入力 |
| 403 | Forbidden | 権限不足（更新時） | administrator権限で再試行 |

### リトライ仕様

- Captcha失敗時は画面リロードで再試行
- メール重複時はログインまたは別メールで再試行

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

- AccountBuilder.performはActiveRecord::Transactionで囲まれる
- Account、User、AccountUserの作成は原子的に実行
- いずれかの作成に失敗した場合は全てロールバック

## パフォーマンス要件

- アカウント作成: 2秒以内
- アカウント取得: 100ms以内
- アカウント更新: 500ms以内

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

- Captchaによるボット防止
- メールドメイン制限によるスパム防止
- administrator権限でのみアカウント設定変更可能
- パスワードはbcryptでハッシュ化

## 備考

- Enterprise版ではサブスクリプション管理、利用制限機能が追加
- アカウント作成後、conv_dpid_seq_{id}とcamp_dpid_seq_{id}シーケンスが作成される

---

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

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

### 推奨読解順序

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

アカウントモデルの構造とスキーマを把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | account.rb | `app/models/account.rb` | Accountモデルの構造、アソシエーション |

**読解のコツ**:
- 1-23行目: スキーマ定義（id, name, locale, domain, settings等）
- 33-73行目: SETTINGS_PARAMS_SCHEMA（設定項目のJSONスキーマ）
- 86-89行目: store_accessor（settings JSONB内の項目アクセサ）
- 91-132行目: has_many アソシエーション（多数のリソースとの関連）

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

アカウントコントローラーの処理フローを把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | accounts_controller.rb | `app/controllers/api/v1/accounts_controller.rb` | create, show, update アクション |

**主要処理フロー**:
1. **5-11行目**: before_actionでの前処理（認証スキップ、Captcha検証等）
2. **24-39行目**: createアクションでAccountBuilder呼び出し
3. **46-52行目**: updateアクションでアカウント情報更新

#### Step 3: アカウントビルダーを理解する

アカウント・ユーザー作成のトランザクション処理を把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | account_builder.rb | `app/builders/account_builder.rb` | performメソッドの処理フロー |

**主要処理フロー**:
- **7-16行目**: performメソッドでトランザクション実行
- **34-36行目**: validate_emailでメール検証
- **38-44行目**: validate_userでユーザー重複チェック
- **46-49行目**: create_accountでアカウント作成
- **60-66行目**: link_user_to_accountでAccountUser作成

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

```
Api::V1::AccountsController#create
    │
    ├─ check_signup_enabled
    │      └─ GlobalConfigService.load('ENABLE_ACCOUNT_SIGNUP')
    │
    ├─ validate_captcha
    │      └─ ChatwootCaptcha.new.valid?
    │
    └─ AccountBuilder.new.perform
           │
           ├─ validate_email
           │      └─ Account::SignUpEmailValidationService
           │
           ├─ validate_user
           │      └─ User.exists?(email: @email)
           │
           └─ ActiveRecord::Base.transaction
                  │
                  ├─ create_account
                  │      └─ Account.create!(name:, locale:)
                  │
                  ├─ create_and_link_user
                  │      ├─ User.new.save!
                  │      └─ AccountUser.create!(role: administrator)
                  │
                  └─ return [@user, @account]
```

### データフロー図

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

【アカウント作成】
account_name ─────────▶ AccountsController#create
user_full_name                  │
email                           ▼
password            ─────▶ AccountBuilder.perform
                                  │
                                  ├─ Account.create! ─────▶ accounts (DB)
                                  │
                                  ├─ User.create! ────────▶ users (DB)
                                  │
                                  └─ AccountUser.create! ─▶ account_users (DB)
                                  │
                                  ▼
                          send_auth_headers ──────────────▶ HTTPヘッダー
                                  │
                                  ▼
                          200 OK + user data ─────────────▶ JSON Response

【アカウント更新】
name ─────────────────▶ AccountsController#update
locale                          │
domain                          ▼
support_email     ────▶ account.assign_attributes
settings                        │
                                ▼
                          account.save! ──────────────────▶ accounts (DB)
                                │
                                ▼
                          200 OK ─────────────────────────▶ JSON Response
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| account.rb | `app/models/account.rb` | モデル | アカウントエンティティ |
| accounts_controller.rb | `app/controllers/api/v1/accounts_controller.rb` | コントローラー | アカウントAPI |
| account_builder.rb | `app/builders/account_builder.rb` | ビルダー | アカウント・ユーザー作成 |
| account_user.rb | `app/models/account_user.rb` | モデル | ユーザー・アカウント紐付け |
| sign_up_email_validation_service.rb | `app/services/account/sign_up_email_validation_service.rb` | サービス | メールドメイン検証 |
| routes.rb | `config/routes.rb` | 設定 | アカウントルート定義（44行目） |
| show.json.jbuilder | `app/views/api/v1/accounts/show.json.jbuilder` | ビュー | アカウント情報レスポンス |
