# 機能設計書 9-トランザクション管理

## 概要

本ドキュメントは、Laravel Frameworkのトランザクション管理機能について、その設計思想、処理フロー、および実装詳細を記述したものである。データベーストランザクションのライフサイクル管理とコールバック機能の設計を定義する。

### 本機能の処理概要

トランザクション管理機能は、データベーストランザクションの開始、コミット、ロールバックを管理し、トランザクション完了時のコールバック実行を制御する機能である。ネストされたトランザクション（セーブポイント）もサポートする。

**業務上の目的・背景**：複数のデータベース操作を一貫性のある単位として扱うには、トランザクションが不可欠である。本機能は、トランザクションのライフサイクルを管理し、コミット後の処理（メール送信、イベント発火など）を適切なタイミングで実行することを保証する。

**機能の利用シーン**：
- 複数テーブルへの一括更新
- 決済処理とポイント付与の同時処理
- 注文作成と在庫減算の原子性保証
- コミット後の通知メール送信
- ロールバック時のクリーンアップ処理

**主要な処理内容**：
1. トランザクションの開始（begin）
2. トランザクションのコミット（commit）
3. トランザクションのロールバック（rollback）
4. コミット後コールバックの管理と実行
5. ロールバック時コールバックの管理と実行
6. ネストトランザクション（セーブポイント）の管理

**関連システム・外部連携**：
- Connection（実際のDBトランザクション操作）
- Event Dispatcher（TransactionBeginning等のイベント）
- Queue（afterCommit属性付きジョブ）

**権限による制御**：トランザクション管理自体は権限制御を行わない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | インフラ機能のため直接関連画面なし |

## 機能種別

データベース管理 / トランザクション / コールバック管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| connection | string | Yes | 接続名 | - |
| level | int | Yes | トランザクションレベル | >= 1 |
| callback | callable | No | 実行するコールバック | - |

### 入力データソース

- アプリケーションコード（DB::transaction()等）
- Connection（トランザクション状態）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | mixed | transaction()の戻り値 |

### 出力先

- アプリケーションコード
- Event Dispatcher（トランザクションイベント）

## 処理フロー

### 処理シーケンス

```
1. トランザクション開始
   └─ begin()でDatabaseTransactionRecord作成
2. 処理実行
   └─ コールバック内でDB操作
3. コミット/ロールバック判定
   ├─ 成功時: commit()で確定
   └─ 失敗時: rollback()で復元
4. コールバック実行
   ├─ コミット時: afterCommitコールバック実行
   └─ ロールバック時: rollbackコールバック実行
```

### フローチャート

```mermaid
flowchart TD
    A[DB::transaction($callback)] --> B[beginTransaction()]
    B --> C[manager->begin()]
    C --> D[pendingTransactionsに追加]
    D --> E[コールバック実行]
    E --> F{例外発生?}
    F -->|No| G[commit()]
    F -->|Yes| H[rollback()]
    G --> I[manager->commit()]
    I --> J{レベル0?}
    J -->|Yes| K[committedTransactions処理]
    J -->|No| L[stageTransactions()]
    K --> M[executeCallbacks()]
    H --> N[manager->rollback()]
    N --> O[executeCallbacksForRollback()]
    O --> P[pendingTransactionsから削除]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ネストトランザクション | セーブポイントを使用してネストをシミュレート | level > 1時 |
| BR-02 | afterCommit実行タイミング | ルートトランザクションのコミット時のみ実行 | afterCommitCallbacksShouldBeExecuted() |
| BR-03 | ロールバック伝播 | 親トランザクションのロールバックで子のコールバックも実行 | rollback()時 |
| BR-04 | コールバック即時実行 | トランザクション外でaddCallback()した場合は即時実行 | currentTransaction = null時 |

### 計算ロジック

- トランザクションレベル: ネストごとに+1
- コミット判定: newTransactionLevel === 0

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| begin() | - | BEGIN | トランザクション開始 |
| commit() | - | COMMIT | トランザクション確定 |
| rollback() | - | ROLLBACK | トランザクション復元 |
| savepoint() | - | SAVEPOINT | セーブポイント作成 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | DeadlockException | デッドロック検出 | 自動リトライ（attempts設定） |
| - | Throwable | コールバック内で例外 | ロールバック実行 |

### リトライ仕様

DB::transaction()の第2引数でリトライ回数を指定可能（デフォルト: 1）。デッドロック時に自動リトライ。

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

- トランザクション開始: BEGIN TRANSACTION / START TRANSACTION
- コミット: COMMIT
- ロールバック: ROLLBACK
- セーブポイント: SAVEPOINT trans_N / ROLLBACK TO SAVEPOINT trans_N

## パフォーマンス要件

- トランザクションは必要最小限の範囲で使用
- 長時間トランザクションは避ける（ロック時間増大）
- afterCommitコールバックは非同期処理を推奨

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

- トランザクション内のデータは他のコネクションから不可視（分離レベル依存）
- デッドロック検出とリトライ機能

## 備考

- afterCommit()でコミット後処理を登録
- Queueジョブの`afterCommit`属性でジョブディスパッチをコミット後に遅延
- withinTransaction設定でマイグレーションの自動トランザクション

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DatabaseTransactionRecord.php | `src/Illuminate/Database/DatabaseTransactionRecord.php` | トランザクションレコード |
| 1-2 | DatabaseTransactionsManager.php | `src/Illuminate/Database/DatabaseTransactionsManager.php` | トランザクションマネージャ |

**読解のコツ**: トランザクションはレコードとして管理され、pendingTransactions/committedTransactionsで状態を追跡する。

#### Step 2: DatabaseTransactionsManagerを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | DatabaseTransactionsManager.php | `src/Illuminate/Database/DatabaseTransactionsManager.php` | トランザクション管理本体 |

**主要処理フロー**:
- **33-37行目**: コンストラクタでCollection初期化
- **46-57行目**: begin()でトランザクション開始、レコード作成
- **67-97行目**: commit()でコミット処理、コールバック実行
- **106-119行目**: stageTransactions()でコミット待ちに移動
- **128-151行目**: rollback()でロールバック処理
- **205-212行目**: addCallback()でコミット後コールバック追加
- **220-225行目**: addCallbackForRollback()でロールバックコールバック追加

#### Step 3: Connectionのトランザクションメソッドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Connection.php | `src/Illuminate/Database/Connection.php` | 接続クラスのトランザクション部分 |
| 3-2 | ManagesTransactions.php | `src/Illuminate/Database/Concerns/ManagesTransactions.php` | トランザクション操作トレイト |

**読解ポイント**:
- transaction(): クロージャをトランザクション内で実行
- beginTransaction(): トランザクション開始
- commit(): コミット
- rollBack(): ロールバック

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

```
DB::transaction($callback, $attempts)
    │
    └─ Connection::transaction()
           │
           ├─ beginTransaction()
           │      │
           │      ├─ createTransaction() [PDO]
           │      │      └─ pdo->beginTransaction()
           │      │
           │      ├─ transactionManager->begin($name, $level)
           │      │      └─ pendingTransactions->push(new Record)
           │      │
           │      └─ fireConnectionEvent(TransactionBeginning)
           │
           ├─ $callback() 実行
           │
           └─ commit() / rollBack()
                  │
                  ├─ [commit]
                  │      ├─ performCommit()
                  │      │      └─ pdo->commit()
                  │      │
                  │      ├─ transactionManager->commit()
                  │      │      ├─ stageTransactions()
                  │      │      └─ executeCallbacks()
                  │      │
                  │      └─ fireConnectionEvent(TransactionCommitted)
                  │
                  └─ [rollBack]
                         ├─ performRollBack()
                         │      └─ pdo->rollBack()
                         │
                         ├─ transactionManager->rollback()
                         │      ├─ executeCallbacksForRollback()
                         │      └─ remove from pending
                         │
                         └─ fireConnectionEvent(TransactionRolledBack)
```

### データフロー図

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

DB::transaction() ──────▶ Connection ───────────────────▶ トランザクション結果
                              │
                              ▼
                        TransactionsManager
                              │
                              ├── begin()
                              │      └── pendingTransactions[]
                              │
                              ├── commit()
                              │      ├── committedTransactions[]
                              │      └── executeCallbacks()
                              │
                              └── rollback()
                                     └── executeCallbacksForRollback()
                              │
                              ▼
                        PDO ─────────────────────────────▶ DBMS
                              │
                              ▼
                        Events ──────────────────────────▶ Event Dispatcher
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| DatabaseTransactionsManager.php | `src/Illuminate/Database/DatabaseTransactionsManager.php` | ソース | トランザクションマネージャ |
| DatabaseTransactionRecord.php | `src/Illuminate/Database/DatabaseTransactionRecord.php` | ソース | トランザクションレコード |
| ManagesTransactions.php | `src/Illuminate/Database/Concerns/ManagesTransactions.php` | ソース | トランザクション操作トレイト |
| Connection.php | `src/Illuminate/Database/Connection.php` | ソース | データベース接続 |
| TransactionBeginning.php | `src/Illuminate/Database/Events/TransactionBeginning.php` | ソース | トランザクション開始イベント |
| TransactionCommitted.php | `src/Illuminate/Database/Events/TransactionCommitted.php` | ソース | コミットイベント |
| TransactionRolledBack.php | `src/Illuminate/Database/Events/TransactionRolledBack.php` | ソース | ロールバックイベント |
