problem-solvinglisted

# 問題解決ガイドライン データ不整合、バグ、障害対応における問題解決の原則と手順。 ## 1. 根本原因を探る（つじつま合わせをしない） ### 原則: 上流で直す 問題はデータフローの**最も上流**で修正する。下流でのパッチ（migrationによるデータ修正、SQL直接更新、出力時の辻褄合わせ）は最終手段。 ``` ❌ 悪いパターン DBに異常データがある → migrationで論理削除 → バッチ再実行 ✅ 良いパターン DBに異常データがある → なぜ入ったか調査 → 取り込みロジックにバリデーション追加 → 異常データを論理削除 → バッチ再実行 ``` ### 判断フロー ``` 1. 症状を確認（どのデータ・どの機能が、どう間違っているか） 2. データフロー/呼び出しチェーンを遡る（結果 → 計算 → 素材 → 取り込み → 外部ソース） 3. 最初に異常が発生した地点を特定 4. 再現テストを追加する（この時点で失敗することを確認する。下記「再現テストを先に書く」） 5. その地点のコードを修正 6. 再現テストが通ることを確認する 7. 下流にも防御的チェックを追加（多層防御） 8. 修正後にデータ修復（パイプライン再実行） ``` ### 再現テストを先に書く（必須） **修正の前に、不具合を再現する失敗テストを追加する。** 再現できないまま修正すると、 直ったかどうかを判定できず、同じ不具合の再発も検出できない。 | 確認すること | 目的 | | --- | --- | | 追加したテストが**失敗する** | 不具合を再現できている | | 失敗の理由が症状と一致する | 別の原因で落ちていない | | 修正後に**通る** | 直ったことの証跡 | | テストを残す | 同じ退行を二度検出できる | サイクルの詳しい進め方は `tdd-cycle`（未導入なら対象プロジェクトの既存テスト手順）に従う。 **再現テストが書けないときは、再現条件がまだ特定できていない。** 修正へ進まず 1〜3 に戻る。 どうしても自動テストにできない場合（外部環境依存など）は、手動の再現手順と確認結果を 記録して代わりとし、その旨を報告に明記する。 ### テストが困難な既存コードでは現状固定テストを先行する 対象にテストがほとんどない場合、再現テストを書く前に**現状の振る舞いを固定するテスト**を 置く。副作用を分離できず再現テストが書けない状態で修正すると、直したい振る舞い以外を 壊しても気づけない。手順は `refactoring` の現状固定テストに従う。 ```text 1. 変更対象の入口と副作用を洗い出す 2. 現状の出力を固定するテストを置く（不具合を含む現状もそのまま固定される） 3. 不具合を再現するテストを追加する（ここは失敗する） 4. 修正する → 3 が通り、2 のうち仕様として正しいものは通ったまま 5. 2 のうち不具合を固定していたものは、期待値を修正後の正しい値へ更新する ``` ### 典型的な見逃しパターン | 症状 | 表層の「原因」 | 真の根本原因 | |------|-------------|-------------| | 料金が異常値 | 計算ロジックのバグ | 上流の取り込み時に異常値が混入、バリデーション欠如 | | レコードの2WD/4WD逆転 | 割当ロジックの不具合 | ORM（Eloquent等）のリレーション型