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

## 概要

本ドキュメントは、Chatwootにおける監査ログ機能の設計を記載したものである。この機能はEnterprise版の機能であり、アカウント内のすべての操作履歴を記録・表示する。

### 本機能の処理概要

**業務上の目的・背景**：エンタープライズ環境では、セキュリティおよびコンプライアンス要件を満たすため、システム内で行われた操作の履歴を追跡する必要がある。監査ログ機能は、誰がいつ何を変更したかを記録し、問題発生時の調査や監査対応を支援する。

**機能の利用シーン**：管理者がシステム設定の変更履歴を確認する際、セキュリティインシデント発生時の調査、コンプライアンス監査への対応時に利用される。

**主要な処理内容**：
1. 監査ログの一覧表示（ページネーション付き）
2. アカウントに関連するすべての操作履歴の取得
3. 操作日時、操作者、変更内容の表示

**関連システム・外部連携**：Audited gemを使用した監査ログ記録。

**権限による制御**：管理者（Administrator）ロールのみアクセス可能。audit_logsフィーチャーフラグが有効なアカウントのみ利用可能。

## 関連画面

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

## 機能種別

参照（一覧表示）

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- 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 | JSONB | 変更内容 |
| version | Integer | バージョン番号 |
| username | String | 操作者のメールアドレス |
| remote_address | String | 操作元IPアドレス |
| request_uuid | String | リクエストUUID |
| created_at | DateTime | 操作日時 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ 管理者権限チェック
2. フィーチャーフラグチェック
   └─ audit_logs機能の有効/無効確認
3. 監査ログ取得
   ├─ 有効: アカウントに関連する監査ログを取得
   └─ 無効: 空の結果セットを返却
4. ページネーション適用
   └─ 15件/ページ
5. レスポンス返却
```

### フローチャート

```mermaid
flowchart TD
    A[リクエスト受信] --> B{管理者権限あり?}
    B -->|No| C[403 Forbidden]
    B -->|Yes| D{audit_logs機能有効?}
    D -->|No| E[空の結果セット]
    D -->|Yes| F[associated_audits取得]
    F --> G[日時降順ソート]
    G --> H[ページネーション適用]
    H --> I[レスポンス返却]
    E --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-196-01 | 管理者限定 | Administrator権限のみアクセス可能 | 常時 |
| BR-196-02 | フィーチャーフラグ | audit_logs機能が有効なアカウントのみ監査ログを表示 | 常時 |
| BR-196-03 | ページサイズ固定 | 1ページあたり15件固定 | 常時 |
| BR-196-04 | 降順表示 | 最新の操作が先頭に表示される | 常時 |

### 計算ロジック

なし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 監査ログ表示 | audits | SELECT | アカウントに関連する監査ログ取得 |

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

#### audits

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | associated_type = 'Account' AND associated_id = account_id | has_associated_auditsによる関連 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 403 | Forbidden | 管理者権限がない場合 | アクセス拒否 |

### リトライ仕様

なし

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

- 読み取り専用のため、明示的なトランザクション管理なし

## パフォーマンス要件

- ページネーションによる結果セット制限
- created_atカラムのインデックスを使用した高速ソート

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

- 管理者権限のみアクセス可能
- フィーチャーフラグによる機能制御
- 監査ログ自体は変更・削除不可（監査証跡の保全）

## 備考

- この機能はEnterprise版限定
- Audited gemを使用して監査ログを自動記録
- usernameフィールドにはafter_saveコールバックでユーザーのメールアドレスが設定される

---

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

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

### 推奨読解順序

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

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

**主要処理フロー**:
1. **2行目**: `before_action :check_admin_authorization?` - 管理者権限チェック
2. **3行目**: `before_action :fetch_audit` - 監査ログの取得
3. **5行目**: `RESULTS_PER_PAGE = 15` - ページサイズ定義
4. **7-12行目**: `show`アクション - ページネーション適用と結果返却
5. **16-25行目**: `fetch_audit`メソッド - フィーチャーフラグチェックと監査ログ取得
6. **27-29行目**: `audit_logs_enabled?`メソッド - フィーチャーフラグ確認

**読解のコツ**: `Current.account.associated_audits`はAudited gemの`has_associated_audits`により提供される関連。Accountモデルに設定された監査対象モデルの変更履歴が取得される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | audit_log.rb | `enterprise/app/models/enterprise/audit_log.rb` | カスタム監査ログモデル |

**主要処理フロー**:
1. **29行目**: `Audited::Audit`を継承
2. **30行目**: `after_save :log_additional_information` - 追加情報の記録
3. **34-42行目**: `log_additional_information`メソッド - usernameフィールドの設定

#### Step 3: アカウントの監査設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | audit/account.rb | `enterprise/app/models/enterprise/audit/account.rb` | アカウントモデルの監査設定 |

**主要処理フロー**:
1. **5行目**: `audited except: :updated_at, on: [:update]` - 更新時のみ監査
2. **6行目**: `has_associated_audits` - 関連モデルの監査ログを取得可能に

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

```
Api::V1::Accounts::AuditLogsController#show
    │
    ├─ check_admin_authorization? (before_action)
    │
    ├─ fetch_audit (before_action)
    │      │
    │      ├─ audit_logs_enabled?
    │      │      └─ Current.account.feature_enabled?(:audit_logs)
    │      │
    │      └─ Current.account.associated_audits
    │             └─ Audited::Audit (Enterprise::AuditLog)
    │
    └─ page/per (ページネーション)
```

### データフロー図

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

page パラメータ ───▶ AuditLogsController#show
                          │
                          ▼
                    check_admin_authorization?
                          │
                          ▼
                    fetch_audit
                          │
                    ┌─────┴─────┐
                    ▼           ▼
              有効         無効
                │           │
                ▼           ▼
        associated_audits  空の結果
                │           │
                └─────┬─────┘
                      ▼
                ページネーション
                      │
                      ▼
              { audit_logs,
                current_page,
                total_entries,
                per_page }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| audit_logs_controller.rb | `enterprise/app/controllers/api/v1/accounts/audit_logs_controller.rb` | ソース | 監査ログAPIコントローラー |
| audit_log.rb | `enterprise/app/models/enterprise/audit_log.rb` | ソース | カスタム監査ログモデル |
| audit/account.rb | `enterprise/app/models/enterprise/audit/account.rb` | ソース | アカウントの監査設定 |
| routes.rb | `config/routes.rb` | 設定 | ルーティング定義（96行目） |
