エラーハンドリング・トレーサビリティ設計
本ドキュメントは、TASHIKA プラットフォームにおけるエラーハンドリングとトレーサビリティのアーキテクチャ設計を定義します。
概要
目的
ユーザーに表示されるすべてのエラーを、TraceId を起点として発生元のリクエスト・処理まで一気通貫で追跡可能にする。これにより、以下を実現する:
- ユーザーがサポートに問い合わせる際、TraceId を伝えるだけで迅速な原因特定が可能
- フロントエンドエラーとバックエンドの分散トレースを単一の TraceId で紐付け
- 障害発生時 5分以内 に根本原因（RCA）の特定に着手できる体制を構築
関連要件
| 要件ID | 内容 | 参照 |
|---|---|---|
| QA-003 | 可観測性（ログ、メトリクス、トレース、フロントエンドエラー） | → QA-003 可観測性 |
| AV-003 | 弾力性（Circuit Breaker、Retry、Graceful Degradation） | → AV-003 弾力性 |
| SR-010 | インシデント対応（検知、対応フロー、通知義務） | → SR-010 インシデント対応 |
設計原則
- TraceId ファースト: すべてのエラーに TraceId を付与し、ユーザー画面 → フロントエンドログ → バックエンドログ → DB クエリまで一貫して追跡可能にする
- 機密情報の排除: エラーレスポンス・ログ・エラー追跡サービスにマイナンバー等の機密情報を含めない
- 影響範囲の最小化: Error Boundary 3層構成により、エラーの影響を最小のコンポーネント単位に局所化する
- 縮退運転の保証: 外部依存の障害時も申告業務を継続可能にする
アーキテクチャ決定
本設計における分散トレーシングのツール選定（Sentry + OpenTelemetry ハイブリッド方式）の根拠は → ADR-005 を参照。
サブページ
| ドキュメント | 内容 |
|---|---|
| 分散トレーシングアーキテクチャ | トレーシング階層、TraceId 伝播フロー、ミドルウェア |
| エラーカテゴリとレスポンス設計 | エラーカテゴリ、RFC 7807 Problem Details、エラーコードレジストリ |
| フロントエンドエラーハンドリング | Error Boundary 3層、TanStack Query、Sentry 統合、ChunkLoadError |
| バックエンドエラーハンドリング | 例外ミドルウェア、FluentValidation、縮退運転、税計算エラー |
| エッジケース仕様 | 自動保存復帰、マルウェアスキャン、一括操作部分失敗、セッション期限切れ等 |
| 監視・アラート連携 | 監視システム連携、アラート重要度、ログフォーマット、可観測性データフロー |