# 機能設計書 15-監査ログ

## 概要

本ドキュメントは、Chatwootの監査ログ機能について、その処理内容、データベース操作、およびコード構成を詳細に記述した設計書である。本機能はEnterprise版限定の機能である。

### 本機能の処理概要

監査ログ機能は、アカウント内で行われた重要な操作を自動的に記録し、セキュリティ監査やコンプライアンス要件の充足、問題発生時のトレースを可能にする機能である。Audited gemを使用して実装されており、各種モデルの変更履歴を自動的に追跡する。

**業務上の目的・背景**：エンタープライズ環境では、セキュリティ監査、コンプライアンス要件（SOC 2、GDPR等）の充足のため、誰が・いつ・何をしたかを追跡可能な状態にする必要がある。監査ログにより、不正アクセスの検出、問題発生時の原因特定、操作履歴の証跡保全が実現できる。

**機能の利用シーン**：
- セキュリティインシデント発生時の操作履歴確認
- 定期的なセキュリティ監査
- ユーザー操作の追跡・分析
- コンプライアンス監査への対応
- 問題発生時のデバッグ・トレース

**主要な処理内容**：
1. Audited gemによる各種モデルの変更自動追跡
2. 監査対象モデル（AccountUser, Team, Inbox, InboxMember等）の操作記録
3. 変更内容（audited_changes）のJSON形式での保存
4. 操作者情報（user_id, username）の自動記録
5. ページネーション対応の監査ログ一覧取得

**関連システム・外部連携**：
- Enterprise認証・ライセンス管理システム
- 各種監査対象モデル（include_mod_with経由で拡張）

**権限による制御**：
- 監査ログの閲覧はAdministratorロールのみ
- 監査ログ機能自体の有効/無効はEnterprise機能フラグで制御

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 76 | 監査ログ一覧画面 | 主画面 | 監査ログの一覧表示 |

## 機能種別

参照操作（READ専用） / セキュリティ機能（Enterprise機能）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| page | Integer | No | ページ番号（デフォルト: 1） | 正の整数 |

### 入力データソース

- 画面入力（監査ログ一覧画面からのページング操作）
- API経由（Enterprise REST API）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| audit_logs | Array | 監査ログレコードの配列 |
| current_page | Integer | 現在のページ番号 |
| total_entries | Integer | 総レコード数 |
| per_page | Integer | 1ページあたりの件数（15件） |

### 監査ログレコードの構造

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | Integer | 監査ログID |
| auditable_type | String | 監査対象モデル名 |
| auditable_id | Integer | 監査対象レコードID |
| action | String | 操作種別（create/update/destroy） |
| audited_changes | JSON | 変更内容 |
| user_id | Integer | 操作者ユーザーID |
| username | String | 操作者メールアドレス |
| created_at | DateTime | 操作日時 |
| associated_type | String | 関連モデル名 |
| associated_id | Integer | 関連レコードID |
| remote_address | String | 操作元IPアドレス |
| request_uuid | String | リクエストUUID |

### 出力先

- APIレスポンス（JSON形式）

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ AuditLogsController経由で監査ログ取得リクエスト受信

2. Enterprise認証チェック
   └─ EnterpriseAccountsController継承により自動チェック

3. 管理者権限チェック
   └─ check_admin_authorization?で Administrator 権限確認

4. 機能有効チェック
   └─ audit_logs_enabled? で機能フラグ確認

5. 監査ログ取得
   └─ account.associated_audits で関連する監査ログ取得

6. ページネーション適用
   └─ Kaminari によるページング処理

7. レスポンス返却
   └─ 監査ログ一覧をJSON形式で返却
```

### フローチャート

```mermaid
flowchart TD
    A[監査ログ取得リクエスト] --> B{Enterprise版?}
    B -->|No| C[403エラー]
    B -->|Yes| D{Administrator?}
    D -->|No| C
    D -->|Yes| E{audit_logs機能有効?}
    E -->|No| F[空の結果返却 + 警告ログ]
    E -->|Yes| G[associated_audits取得]
    G --> H[created_at DESC でソート]
    H --> I[ページネーション適用]
    I --> J[レスポンス返却]
    F --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Enterprise限定 | 監査ログ機能はEnterprise版のみ利用可能 | 全操作時 |
| BR-002 | Administrator限定 | 監査ログの閲覧はAdministratorのみ | 閲覧時 |
| BR-003 | 機能フラグ制御 | audit_logs機能フラグが有効な場合のみ動作 | 取得時 |
| BR-004 | 自動記録 | 監査対象モデルの変更は自動的に記録される | モデル変更時 |
| BR-005 | ページサイズ固定 | 1ページあたり15件固定 | 一覧取得時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 監査ログ一覧取得 | audits | SELECT | アカウント関連の監査ログ取得 |
| 監査ログ自動記録 | audits | INSERT | モデル変更時に自動挿入 |

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

#### audits

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | associated_type/associated_id条件 | アカウント関連のみ |
| INSERT | action | create/update/destroy | Audited gem自動設定 |
| INSERT | auditable_type | 監査対象モデル名 | 自動設定 |
| INSERT | auditable_id | 監査対象レコードID | 自動設定 |
| INSERT | audited_changes | 変更内容（JSON） | 自動設定 |
| INSERT | user_id | 操作者ID | Current.user |
| INSERT | username | 操作者メール | after_saveで設定 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 403 | Forbidden | Enterprise版でない / Administrator権限なし | プランアップグレード案内 |

### リトライ仕様

特になし（同期処理のため）

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

監査ログの記録は、監査対象モデルの操作と同一トランザクション内で行われる（Audited gemの動作）。

## パフォーマンス要件

- 監査ログ一覧取得: 200ms以内のレスポンス
- インデックス（associated_type, associated_id）、（created_at）による高速検索

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

- Enterprise認証による機能アクセス制御
- Administrator権限必須の認可制御
- 監査ログ自体の改ざん防止（読み取り専用）
- 操作者情報の自動記録

## 備考

- Audited gemを使用して実装
- 監査対象モデルは `include_mod_with('Audit::ModelName')` で拡張される
- Enterprise::AuditLog クラスで追加情報（username等）を自動設定

---

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

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

### 推奨読解順序

#### Step 1: 監査ログモデルを理解する

Enterprise::AuditLogモデルのスキーマとコールバックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | audit_log.rb | `enterprise/app/models/enterprise/audit_log.rb` | スキーマ、after_saveコールバック |

**読解のコツ**:
- `Audited::Audit`を継承しているため、Audited gemの機能がベース
- `after_save :log_additional_information` でusername等を追加設定
- `update_columns` でコールバックをスキップした直接更新（無限ループ防止）

**主要処理フロー**:
1. **1-28行目**: スキーマ情報（テーブル名: audits）
2. **29行目**: Audited::Auditを継承
3. **30行目**: after_saveコールバック定義
4. **34-42行目**: log_additional_information - associated情報とusername設定

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

コントローラでの監査ログ取得の入り口を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | audit_logs_controller.rb | `enterprise/app/controllers/api/v1/accounts/audit_logs_controller.rb` | 監査ログ取得API |

**主要処理フロー**:
1. **1行目**: EnterpriseAccountsController継承
2. **2行目**: check_admin_authorization? - 管理者権限チェック
3. **3行目**: fetch_audit - 監査ログ取得処理
4. **5行目**: RESULTS_PER_PAGE = 15 - ページサイズ定数
5. **7-12行目**: show - ページネーション適用して返却
6. **16-25行目**: fetch_audit - 機能フラグチェックと監査ログ取得
7. **27-29行目**: audit_logs_enabled? - 機能フラグ確認

#### Step 3: Audited gem設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | audited.rb | `config/initializers/audited.rb` | Audited gem初期設定 |

**主要処理フロー**:
- 監査クラスの指定
- グローバル設定

#### Step 4: 監査対象モデルの拡張を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | 各モデルファイル | `app/models/*.rb` | include_mod_with('Audit::ModelName') |

**例: account_user.rb**
- `AccountUser.include_mod_with('Audit::AccountUser')` で監査機能追加

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

```
Api::V1::Accounts::AuditLogsController
    │
    ├─ EnterpriseAccountsController (Enterprise認証)
    │
    ├─ check_admin_authorization? (管理者チェック)
    │
    └─ fetch_audit
           ├─ audit_logs_enabled? (機能フラグ確認)
           │      └─ account.feature_enabled?(:audit_logs)
           │
           └─ account.associated_audits (監査ログ取得)
                  └─ Enterprise::AuditLog (Audited::Audit継承)
                         └─ after_save: log_additional_information
```

### データフロー図

```
[モデル操作時の監査ログ記録]

モデル変更 ────────▶ Audited gem ────────▶ audits テーブル
(create/update/destroy)    │
                           ▼
                   Enterprise::AuditLog
                   (after_save コールバック)
                           │
                           ▼
                   username, associated_id 設定


[監査ログ閲覧時]

APIリクエスト ────────▶ AuditLogsController ────────▶ JSONレスポンス
(page)                      │                        (audit_logs配列)
                            ▼
                   Enterprise認証 + 管理者チェック
                            │
                            ▼
                   account.associated_audits
                            │
                            ▼
                   ページネーション (Kaminari)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| audit_log.rb | `enterprise/app/models/enterprise/audit_log.rb` | モデル | 監査ログモデル（Audited拡張） |
| audit_logs_controller.rb | `enterprise/app/controllers/api/v1/accounts/audit_logs_controller.rb` | コントローラ | 監査ログ取得API |
| audited.rb | `config/initializers/audited.rb` | 設定 | Audited gem初期設定 |
| account_user.rb | `app/models/account_user.rb` | モデル | 監査対象モデル例 |
| team.rb | `app/models/team.rb` | モデル | 監査対象モデル例 |
| inbox.rb | `app/models/inbox.rb` | モデル | 監査対象モデル例 |
| inbox_member.rb | `app/models/inbox_member.rb` | モデル | 監査対象モデル例 |
