# バッチ設計書 17-Account::ConversationsResolutionSchedulerJob

## 概要

本ドキュメントは、Chatwootシステムにおける自動解決機能が有効なアカウントに対して、会話解決ジョブをスケジュールするバッチ処理の設計を記述するものです。

### 本バッチの処理概要

本バッチは、自動解決設定（auto_resolve_after）が有効なアカウントを検出し、各アカウントに対してConversations::ResolutionJobをキューイングするスケジューラー処理を実行します。

**業務上の目的・背景**：カスタマーサポート業務において、長期間アクティビティのない会話は、顧客からの反応がないまま放置されている可能性があります。本バッチは、設定された期間（auto_resolve_after分）が経過した非アクティブな会話を自動的に解決済み状態に変更することで、会話一覧の整理とエージェントの作業効率向上を実現します。本ジョブは親ジョブとして機能し、実際の解決処理は子ジョブ（ResolutionJob）に委譲します。

**バッチの実行タイミング**：TriggerScheduledItemsJobから5分毎にトリガーされます。

**主要な処理内容**：
1. auto_resolve設定が有効なアカウントを検索（with_auto_resolveスコープ）
2. 各アカウントに対してConversations::ResolutionJobをキューイング
3. （Enterprise版）CaptainInbox連携のための追加処理

**前後の処理との関連**：本バッチはTriggerScheduledItemsJobから呼び出される子ジョブです。本バッチが親ジョブとしてConversations::ResolutionJob（孫ジョブ）をキューイングします。Enterprise版では、prepend_mod_withによりCaptain連携の追加処理が行われます。

**影響範囲**：auto_resolve_after設定が有効なすべてのアカウントが対象となります。本バッチ自体はジョブキューへのエンキュー処理のみを行い、直接的なデータ更新は行いません。

## バッチ種別

ジョブスケジューリング / トリガー処理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 5分毎 |
| 実行時刻 | 毎時0分、5分、10分、15分、... |
| 実行曜日 | 毎日 |
| 実行日 | 毎日 |
| トリガー | TriggerScheduledItemsJob経由 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| TriggerScheduledItemsJobが稼働していること | 親ジョブからのトリガーが必要 |
| データベース接続が可能であること | accountsテーブルへのアクセスに必要 |

### 実行可否判定

本バッチは無条件で実行されます。対象アカウントが存在しない場合も正常終了します。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | パラメータは不要 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| accounts | DB | 自動解決設定が有効なアカウントレコード |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Sidekiqジョブキュー | Queue | Conversations::ResolutionJobがlowキューにエンキューされる |

### 出力ファイル仕様

ファイル出力はありません。

## 処理フロー

### 処理シーケンス

```
1. バッチ開始
   └─ scheduled_jobsキューから起動
2. 自動解決設定が有効なアカウントを検索
   └─ Account.with_auto_resolve.find_each(batch_size: 100)
3. 各アカウントに対してResolutionJobをエンキュー
   └─ Conversations::ResolutionJob.perform_later(account: account)
4. （Enterprise版）Captain連携処理
   └─ resolve_captain_conversations
5. バッチ終了
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[Account.with_auto_resolve取得]
    B --> C[find_each batch_size:100]
    C --> D{アカウントあり?}
    D -->|No| E{Enterprise版?}
    D -->|Yes| F[ResolutionJob.perform_later]
    F --> C
    E -->|No| G[バッチ終了]
    E -->|Yes| H[resolve_captain_conversations]
    H --> I[CaptainInbox.all取得]
    I --> J{CaptainInboxあり?}
    J -->|No| G
    J -->|Yes| K[InboxPendingConversationsResolutionJob.perform_later]
    K --> I
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 対象アカウント取得 | accounts | SELECT | with_auto_resolveスコープで検索 |
| （Enterprise）CaptainInbox取得 | captain_inboxes, inboxes | SELECT | Captain連携インボックスを取得 |

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

#### accounts

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, settings | (settings ->> 'auto_resolve_after')::int IS NOT NULL | with_auto_resolveスコープ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | StandardError | DB操作失敗時 | Sidekiqの標準リトライ機構により再実行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | Sidekiqのデフォルト設定 |
| リトライ間隔 | 指数バックオフ |
| リトライ対象エラー | StandardError全般 |

### 障害時対応

バッチ失敗時は次回の定期実行（5分後）で自動的にリカバリされます。緊急時はRailsコンソールから手動実行可能です：
```ruby
Account::ConversationsResolutionSchedulerJob.perform_now
```

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（読み取りとジョブエンキューのみ） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 自動解決設定が有効なアカウント数 |
| 目標処理時間 | 5分以内（次回実行までに完了） |
| メモリ使用量上限 | find_each(batch_size: 100)により一定に制御 |

## 排他制御

- 同時実行制御なし
- 5分間隔の実行であるため、重複実行のリスクは低い
- 子ジョブ（ResolutionJob）は同一アカウントでの重複キューイングが発生する可能性があるが、ResolutionJob側で冪等性を担保

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | Sidekiq標準ログ |
| 進捗ログ | - | 明示的なログ出力なし |
| 終了ログ | バッチ終了時 | Sidekiq標準ログ |
| エラーログ | エラー発生時 | Sidekiq標準エラーログ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 5分以上 | Sidekiq監視システム |
| エラー件数 | 1件以上 | Sidekiq監視システム |

## 備考

- with_auto_resolveスコープ: `(settings ->> 'auto_resolve_after')::int IS NOT NULL` でフィルタ
- Enterprise版では`prepend_mod_with`により拡張され、Captain連携の処理が追加される
- Enterprise版のresolve_captain_conversationsでは、email以外のCaptainInboxに対してInboxPendingConversationsResolutionJobがキューイングされる
- 本バッチはジョブスケジューラーとして機能し、実際の会話解決処理はResolutionJobで行われる
