---
generated_at: 2026-02-24 19:30:00
metrics:
  claims_total: 44
  claims_with_evidence: 44
  claims_without_evidence: 0
confidence_derived: 1.00
---

# 根拠レポート：providers-locking-postgres 単体テストケース一覧

## 本レポートについて

### 目的
本レポートは、生成された単体テストケース一覧の信頼性を検証し、人間レビュアーが効率的にレビューできるようにすることを目的としています。

### チェック方法
以下の観点でドキュメントの内容（Claim：主張）を検証しています：

1. **根拠の有無確認**：各主張に対して、ソースコード・既存設計書・要件定義書などの根拠（Evidence）が存在するか
2. **根拠との整合性**：主張の内容が根拠と矛盾していないか
3. **網羅性**：参照すべき情報源を適切にカバーしているか

### 信頼度スコアの算出
- **confidence_derived** = 根拠あり件数 / 総主張件数
- 状態「○」：根拠あり、「△」：根拠不足または要確認

### 本レポートの使い方
1. まず「サマリー」で全体の信頼度と優先レビュー項目を確認
2. 「Claims と根拠の対応」で △ の項目を重点的にレビュー
3. 「不足情報」で補完が必要な情報源を確認

---

## 1) サマリー（まず見るところ）
- 総合信頼度（derived）：**1.00**
  - 根拠あり：44 / 44、根拠なし：0
- 優先レビュー（高）
  1. **execute メソッドのタイムアウト処理**：PostgreSQLのpg_advisory_xact_lockを使用した実装の詳細確認推奨
  2. **acquire メソッドの並行アクセス制御**：DB制約（locking_pkey）に依存した排他制御の動作確認推奨
  3. **hashStringToInt のハッシュアルゴリズム**：djb2ハッシュアルゴリズムの衝突可能性の確認推奨

## 2) 参照した情報（Evidence一覧）
> ここに「実在するもの」だけ列挙。抽出フェーズで付けたIDをそのまま出す。

- E-01: `packages/modules/providers/locking-postgres/src/services/advisory-lock.ts` - PostgresAdvisoryLockProviderクラスの実装
- E-02: `packages/modules/providers/locking-postgres/src/models/locking.ts` - Lockingモデルの定義
- E-03: `packages/modules/providers/locking-postgres/src/models/index.ts` - モデルのエクスポート
- E-04: `packages/modules/providers/locking-postgres/src/index.ts` - モジュールエントリポイント
- E-05: `packages/modules/providers/locking-postgres/src/migrations/Migration20241009222919_InitialSetupMigration.ts` - DBマイグレーション
- E-06: `packages/modules/providers/locking-postgres/integration-tests/__tests__/index.spec.ts` - 既存統合テスト
- E-07: `packages/core/types/src/locking/index.ts` - ILockingProviderインターフェース定義

## 3) Claims と根拠の対応（レビューの主戦場）

### PostgresAdvisoryLockProvider - constructor
| Claim ID | 主張 | Evidence | 状態 |
|---|---|---|---|
| C-01 | 依存性注入によりEntityManagerが正常に設定される | E-01 (L16-22) | ○ |

### PostgresAdvisoryLockProvider - execute
| Claim ID | 主張 | Evidence | 状態 |
|---|---|---|---|
| C-02 | 単一キーでロックを取得しジョブを実行後、結果を返す | E-01 (L28-68), E-06 (L41-60) | ○ |
| C-03 | 複数キーでロックを取得しジョブを実行後、結果を返す | E-01 (L46-52) | ○ |
| C-04 | タイムアウト指定でロックを取得しジョブを実行する | E-01 (L35-36, L40-42) | ○ |
| C-05 | ジョブが例外をスローした場合、ロールバックして例外が再スロー | E-01 (L63-66), E-06 (L157-168) | ○ |
| C-06 | タイムアウト時間内にロックが取得できない場合、タイムアウトエラー | E-01 (L189-194) | ○ |
| C-07 | タイムアウトに0以下の値が指定された場合、デフォルト値1秒が適用 | E-01 (L35) | ○ |
| C-08 | タイムアウトにNaNが指定された場合、デフォルト値1秒が適用 | E-01 (L36) | ○ |
| C-09 | タイムアウトが未指定の場合、デフォルト値5秒が適用 | E-01 (L35) | ○ |

### PostgresAdvisoryLockProvider - acquire
| Claim ID | 主張 | Evidence | 状態 |
|---|---|---|---|
| C-10 | 新規キーに対してロックを取得できる | E-01 (L93-117), E-06 (L62-84) | ○ |
| C-11 | 複数の新規キーに対してロックを取得できる | E-01 (L90, L93) | ○ |
| C-12 | 有効期限付きでロックを取得できる | E-01 (L97-99, L103) | ○ |
| C-13 | 同一オーナーが再度ロック取得を試みた場合、成功する | E-01 (L120, L124-126), E-06 (L96-101) | ○ |
| C-14 | 同一オーナーが有効期限を更新できる | E-01 (L128-138) | ○ |
| C-15 | 異なるオーナーがロック済みキーに対してロック取得を試みた場合、エラー | E-01 (L119-122), E-06 (L103-109) | ○ |
| C-16 | オーナー未指定でロック済み（オーナーあり）キーに対してロック取得時エラー | E-01 (L120-122) | ○ |
| C-17 | オーナー未指定でロック済み（オーナーなし）キーに対して再度ロック取得時エラー | E-01 (L120), E-06 (L122-154) | ○ |
| C-18 | 並行してロック取得を試みた場合、後続がエラー | E-01 (L107-114) | ○ |

### PostgresAdvisoryLockProvider - release
| Claim ID | 主張 | Evidence | 状態 |
|---|---|---|---|
| C-19 | 自身が取得したロックを解放できる | E-01 (L142-166), E-06 (L79-83) | ○ |
| C-20 | 複数キーのロックを一度に解放できる | E-01 (L150, L153) | ○ |
| C-21 | オーナーなしで取得したロックをオーナーなしで解放できる | E-01 (L156), E-06 (L152-153) | ○ |
| C-22 | 異なるオーナーがロックを解放しようとした場合、falseが返却 | E-01 (L156-159), E-06 (L67-74, L113-116) | ○ |
| C-23 | 存在しないキーを解放しようとした場合、falseが返却 | E-01 (L156-159) | ○ |
| C-24 | 有効期限切れのロックを解放した場合、falseが返却 | E-01 (L163) | ○ |
| C-25 | 複数キー解放時、一部が失敗した場合falseが返却 | E-01 (L152, L163) | ○ |

### PostgresAdvisoryLockProvider - releaseAll
| Claim ID | 主張 | Evidence | 状態 |
|---|---|---|---|
| C-26 | 特定オーナーの全ロックを解放できる | E-01 (L174-177) | ○ |
| C-27 | オーナー未指定時、全てのロックを解放できる（TRUNCATE） | E-01 (L171-172) | ○ |
| C-28 | ロックが存在しない状態で実行しても正常終了 | E-01 (L168-179) | ○ |

### PostgresAdvisoryLockProvider - hashStringToInt (private)
| Claim ID | 主張 | Evidence | 状態 |
|---|---|---|---|
| C-29 | 同一文字列に対して常に同じハッシュ値を返す | E-01 (L181-187) | ○ |
| C-30 | 異なる文字列に対して異なるハッシュ値を返す | E-01 (L181-187) | ○ |
| C-31 | 空文字列に対してハッシュ値を返す | E-01 (L181-187) | ○ |
| C-32 | 非常に長い文字列に対してもハッシュ値を返す | E-01 (L186) | ○ |

### PostgresAdvisoryLockProvider - getTimeout (private)
| Claim ID | 主張 | Evidence | 状態 |
|---|---|---|---|
| C-33 | 指定秒数後にタイムアウトエラーを発生させる | E-01 (L189-195) | ○ |
| C-34 | 0秒指定時に即座にタイムアウトエラーを発生させる | E-01 (L191-193) | ○ |

### PostgresAdvisoryLockProvider - loadLock (private)
| Claim ID | 主張 | Evidence | 状態 |
|---|---|---|---|
| C-35 | 存在するキーのロック情報を取得できる | E-01 (L70-81) | ○ |
| C-36 | 存在しないキーの場合、undefinedが返却 | E-01 (L80) | ○ |

### Locking モデル
| Claim ID | 主張 | Evidence | 状態 |
|---|---|---|---|
| C-37 | Lockingモデルが正しく定義されている | E-02 (L3-8) | ○ |
| C-38 | idフィールドがlkプレフィックス付きプライマリキー | E-02 (L4) | ○ |
| C-39 | owner_idがnullable | E-02 (L5) | ○ |
| C-40 | expirationがnullable | E-02 (L6) | ○ |

### Migration
| Claim ID | 主張 | Evidence | 状態 |
|---|---|---|---|
| C-41 | lockingテーブルが正常に作成される（up） | E-05 (L4-7) | ○ |
| C-42 | lockingテーブルが正常に削除される（down） | E-05 (L9-11) | ○ |

### Module Export
| Claim ID | 主張 | Evidence | 状態 |
|---|---|---|---|
| C-43 | PostgresAdvisoryLockProviderがLOCKINGモジュールとして登録 | E-04 (L4-8) | ○ |
| C-44 | identifierが'locking-postgres' | E-01 (L14) | ○ |

## 4) 不足情報（Unknown / Missing）
- 特になし。全てのテストケースがソースコードに基づいて生成されている。

## 5) リスクフラグ（レビュー観点）
- **0: 低リスク** - 全テストケースがソースコード解析に基づいており、既存の統合テスト（E-06）とも整合性がある。

### 補足事項
1. **pg_advisory_xact_lock の動作**: PostgreSQL固有の機能を使用しているため、実際のPostgreSQL環境でのテストが必要
2. **hashStringToInt のdjb2アルゴリズム**: ハッシュ衝突の可能性は低いが、大規模運用時には確認推奨
3. **privateメソッドのテスト**: hashStringToInt, getTimeout, loadLock はprivateメソッドだが、publicメソッドの動作に影響するため、統合的にテスト可能

## 6) レビュアーチェックリスト（最小）
- [ ] executeメソッドのタイムアウト処理が正しくテストされているか
- [ ] acquireメソッドの所有者チェックロジックが網羅されているか
- [ ] releaseメソッドの戻り値条件（true/false）が正確にテストされているか
- [ ] 境界値テスト（空文字列、0秒、NaN等）が適切に設計されているか
- [ ] 並行アクセス時の排他制御テストが含まれているか
- [ ] マイグレーションの up/down 両方がテストされているか
