Presentation Layer

1. 入口の責務を決める

• 必須認証なら OidcUserInfo
• 任意認証なら Option<OidcUserInfo>
• 読み取りか更新かでレスポンス型を決める

actor が必要なら registry 経由で準備し、handler では認証ロジックを複製しない。

2. handler を実装する

• State(AppRegistry) を受ける。
• Path, Query, Json を Axum extractor で受ける。
• application service の execute(...) を呼ぶ。
• JSON 返却は Json<T>、空レスポンスは NoContent を使う。
• 作成系は StatusCode::CREATED と Json<EntityCreationDTO> の組み合わせを優先する。
• #[tracing::instrument(...)] を既存の粒度で付ける。

3. router を追加する

• ApiRouter::new().nest(...) を使う。
• get_with, post_with, put_with, delete_with で operation metadata を足す。
• tag(...) と response::<...>() を必要に応じて設定する。
• 新しい router は api/src/router.rs の build_api_router() に merge する。

4. 認証・claims・extractor を整える

• Bearer token 抽出は auth/extractor.rs に寄せる。
• token decode / validation は既存の auth モジュールを再利用する。
• claims から application DTO への変換は TryFrom で扱う。
• token 不備を HTTP へ出す責務は ApiError / OidcAuthError に閉じる。

5. registry 配線を確認する

• 新しい handler が呼ぶ use case があれば AppRegistry で公開する。
• registry は application と infrastructure の接続点として保つ。
• handler から infrastructure 実装を直接参照しない。

6. エラーと OpenAPI を整える

• ApplicationError / OidcAuthError からの変換を ApiError にまとめる。
• IntoResponse の出力形式を壊さない。
• OpenAPI の tag や security scheme を増やすときは build_openapi_schema に寄せる。

Editing Heuristics

• handler で try_into() や actor 準備以上の分岐が増えたら application へ寄せられないか確認する。
• api crate に domain repository や SeaORM を持ち込まない。
• 認証 optional / required の違いは extractor 型で表現する。
• エラー本文を返すのは BadRequest だけ、という既存ルールを意識する。
• debug 専用の OpenAPI 出力ロジックは #[cfg(debug_assertions)] を守る。

Validation

• cargo test -p api
• 必要に応じて cargo check -p api
• ルートやスキーマを変えたら debug ビルドで OpenAPI 出力も確認する

References

具体例は references/presentation-patterns.md を読む。