API設計方針

年分パス（TaxYear Path）

税務データを扱うAPIは、一律で年分をパスに含める：

/api/v1/{taxYear}/declarations
/api/v1/2024/employees/{id}/withholding

• 「最新年分のみ省略可」とはせず、全て明示的に年分を指定
• 予測可能性・キャッシュ戦略の観点から年分を必須化

テナントコンテキスト

• テナントIDはJWTクレームから取得（パスには含めない）
• PostgreSQL RLS により、コネクションレベルでテナント分離を強制

APIバージョニング

• 破壊的変更は /v1/, /v2/ でパス分離
• 年分とAPIバージョンは独立した概念として管理

スキーマ駆動開発

• 全APIエンドポイントは OpenAPI 3.1 仕様で定義
• バックエンド DTO → フロントエンド型 がすべて同一スキーマから派生
• → OP-002 相互運用性 参照