nene2-python 1.8.26__tar.gz → 1.8.28__tar.gz

{nene2_python-1.8.26 → nene2_python-1.8.28}/CHANGELOG.md

@@ -5,6 +5,29 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.27] — 2026-05-20
+
+FT81 フィールドトライアル — CORS 設定パターン検証と setup_middlewares() への CORS 統合。
+
+### Added
+- `setup_middlewares()` に `cors_allowed_origins` / `cors_allow_credentials` / `cors_allow_methods` / `cors_allow_headers` パラメーターを追加 (#348) (FT81)
+  — `CORSMiddleware` を最外側に自動配置し、OPTIONS プリフライトが確実に処理される
+  — `cors_allowed_origins=["*"]` を渡すと `ValueError` を raise（wildcard 禁止ポリシーの実装強制）
+- Field trial report: `docs/field-trials/2026-05-field-trial-81.md` (FT81)
+
+---
+
+## [1.8.26] — 2026-05-20
+
+FT80 フィールドトライアル — LocalMcpServer + HttpxMcpClient MCP E2E 検証と list_tools() 追加。
+
+### Added
+- `LocalMcpServer` に `list_tools()` メソッドを追加 (#342) (FT80)
+  — 登録済みツール名の一覧を返す。デバッグ・イントロスペクション用途
+- Field trial report: `docs/field-trials/2026-05-field-trial-80.md` (FT80)
+
+---
+
 ## [1.8.25] — 2026-05-20
 
 FT79 フィールドトライアル — RequestLoggingMiddleware の構造化ログ検証と context_extractor 追加。

{nene2_python-1.8.26 → nene2_python-1.8.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.26
+Version: 1.8.28
 Summary: NENE2 Python — minimal API framework following NENE2's design philosophy
 Project-URL: Homepage, https://github.com/hideyukiMORI/nene2-python
 Project-URL: Repository, https://github.com/hideyukiMORI/nene2-python

nene2_python-1.8.28/docs/field-trials/2026-05-field-trial-81.md

@@ -0,0 +1,198 @@
+# FT81: CORS 設定 — setup_middlewares() と CORSMiddleware の組み合わせ
+
+**日付**: 2026-05-20  
+**テーマ**: setup_middlewares() に CORS サポートがない場合の正しい設定パターン検証  
+**バージョン**: v1.8.26  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft81-cors/`
+
+---
+
+## 概要
+
+nene2 の `setup_middlewares()` は CORS をサポートしていないため、
+ブラウザから API を呼び出すアプリで CORS が必要になった際に
+ユーザーは `CORSMiddleware` を手動で追加する必要がある。
+その際、Starlette の LIFO ミドルウェア順序を理解していないと
+OPTIONS プリフライトが正常に動作しない問題を確認した。
+
+---
+
+## 実装パターン
+
+### 正しい CORS 設定（CORS を最外側に配置）
+
+```python
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from nene2.middleware import setup_middlewares
+
+ALLOWED_ORIGINS = [
+    "https://app.example.com",
+    "https://admin.example.com",
+]
+
+app = FastAPI()
+
+# ✅ CORS を先に add_middleware → setup_middlewares() 後は LIFO で最外側になる
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=ALLOWED_ORIGINS,
+    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+    allow_headers=["Authorization", "Content-Type"],
+    allow_credentials=True,
+)
+setup_middlewares(app)
+```
+
+### 間違ったパターン（CORS が内側になる）
+
+```python
+# ❌ setup_middlewares() の後に CORS を追加すると内側に入る
+app = FastAPI()
+setup_middlewares(app)
+app.add_middleware(CORSMiddleware, allow_origins=["https://app.example.com"])
+# → OPTIONS プリフライトが nene2 ミドルウェアに遮断される可能性がある
+```
+
+### 禁止パターン（CLAUDE.md ポリシー違反）
+
+```python
+# ❌ CLAUDE.md 明示禁止: allow_origins=["*"]
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # セキュリティリスク
+)
+```
+
+---
+
+## 発見した問題
+
+### 問題1: setup_middlewares() に CORS パラメーターがない
+
+```python
+# CORS が必要でも setup_middlewares() のシグネチャに cors パラメーターなし
+setup_middlewares(
+    app,
+    # cors_allowed_origins=["https://app.example.com"],  # 存在しない
+)
+```
+
+ユーザーは `FastAPI.add_middleware(CORSMiddleware, ...)` を直接呼ぶ必要がある。
+FastAPI/Starlette のドキュメントを参照しなければ方法がわからない。
+
+### 問題2: ミドルウェア順序が直感に反する（LIFO）
+
+```python
+# Starlette は LIFO — 最後に add_middleware したものが最外側になる
+# つまり CORS を「最外側にしたい」なら「最初に add する」
+
+app.add_middleware(CORSMiddleware, ...)  # ← 先に追加 = 最外側（正しい）
+setup_middlewares(app)                   # ← 後から追加 = 内側
+
+# 逆にすると:
+setup_middlewares(app)                   # ← 先に追加 = 最内側（危険）
+app.add_middleware(CORSMiddleware, ...)  # ← 後から追加 = 最外側になってしまう
+```
+
+「最外側に置きたいなら先に add する」という反直感的な順序。
+
+### 問題3: nene2 が allow_origins=["*"] を禁止しない
+
+```python
+# CLAUDE.md で明示禁止されているが、nene2 フレームワークは検証しない
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # 禁止ポリシーだが動作してしまう
+)
+```
+
+フレームワークレベルで `ValueError` を raise することも可能だが、
+`setup_middlewares()` を経由しない場合は検証できない。
+
+### 問題4: 複数オリジン・credentials 設定パターンがドキュメントにない
+
+本番アプリでは複数オリジン（本番環境 + ステージング環境）や
+`allow_credentials=True` が必要なケースが多いが、
+nene2 のドキュメントにこのパターンの記載がない。
+
+---
+
+## テスト結果（全13件パス）
+
+```
+test_list_items_returns_200                            PASSED
+test_create_item_returns_201                           PASSED
+test_cors_allowed_origin_returns_access_control_header PASSED
+test_cors_disallowed_origin_no_access_control_header   PASSED
+test_cors_preflight_options_returns_200                PASSED  # OPTIONS プリフライト正常動作
+test_cors_preflight_disallowed_origin                  PASSED
+test_cors_credentials_allowed                          PASSED
+test_security_headers_present_with_cors               PASSED  # nene2 ミドルウェアと共存
+test_request_id_present_with_cors                     PASSED  # X-Request-Id と共存
+test_friction_no_cors_in_setup_middlewares             PASSED  # 摩擦: CORS パラメーターなし
+test_friction_cors_order_matters                       PASSED  # 摩擦: LIFO 順序問題
+test_friction_wildcard_origin_is_insecure              PASSED  # 摩擦: ["*"] を止めない
+test_friction_multiple_origins_not_documented          PASSED  # 摩擦: ドキュメント不足
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F81-1 | `setup_middlewares()` に CORS パラメーターがなく手動追加が必要 | 中 |
+| F81-2 | Starlette の LIFO 順序を知らないと OPTIONS プリフライトが壊れる | 中 |
+| F81-3 | `allow_origins=["*"]` を nene2 が禁止しない（ポリシーのみ） | 低 |
+| F81-4 | 複数オリジン・credentials パターンがドキュメントに未記載 | 低 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★★☆☆
+
+`setup_middlewares()` を使うと CORS は自分で追加しなければならず、
+しかも「先に add する = 最外側になる」という反直感的な順序ルールがある。
+FastAPI や Express.js、Spring Security の CORS 設定を知っているユーザーでも
+nene2 特有の LIFO 順序で一度はつまずく。
+
+### 実害の深刻さ ★★★☆☆
+
+ブラウザからの CORS エラーは「API が動かない」として即座に表面化する。
+原因が「ミドルウェア順序」であることを特定するのに時間がかかることがある。
+特に OPTIONS プリフライトが通らないと PUT/DELETE/POST with Auth が全滅する。
+
+### 修正のしやすさ ★★★★★
+
+`setup_middlewares()` に `cors_allowed_origins` パラメーターを追加するだけ。
+CORS は最外側（最初の add_middleware）に固定できるため、
+ユーザーが順序を気にする必要がなくなる。
+
+```python
+# 理想の API:
+setup_middlewares(
+    app,
+    cors_allowed_origins=["https://app.example.com"],
+    cors_allow_credentials=True,
+)
+```
+
+### 総合コメント
+
+CORS は「作ったら必ず必要になる」機能でありながら、
+nene2 の `setup_middlewares()` には組み込まれていない。
+`["*"]` 禁止は CLAUDE.md のポリシーとして正しいが、
+フレームワークが強制しないと誰かが違反する。
+`cors_allowed_origins` を追加してワイルドカードを `ValueError` にすれば
+セキュリティポリシーをコードで強制できる。
+
+---
+
+## 推奨アクション
+
+1. **Issue**: `setup_middlewares()` に `cors_allowed_origins` パラメーターを追加
+   — `allow_origins=["*"]` を渡した場合に `ValueError` を raise
+   — CORS を最外側に自動配置（ユーザーが順序を意識しなくていい）
+2. **docs**: 複数オリジン・credentials のパターンを how-to ガイドに追加

nene2_python-1.8.28/docs/field-trials/2026-05-field-trial-82.md

@@ -0,0 +1,198 @@
+# FT82: Background Tasks — FastAPI BackgroundTasks と nene2 の組み合わせ
+
+**日付**: 2026-05-20  
+**テーマ**: FastAPI BackgroundTasks を nene2 アーキテクチャと組み合わせた際の動作とパターン検証  
+**バージョン**: v1.8.27  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft82-background-tasks/`
+
+---
+
+## 概要
+
+FastAPI の `BackgroundTasks` は「レスポンス返却後に処理を実行する」仕組みで、
+メール送信・在庫更新・監査ログなどのユースケースに使う。
+nene2 のミドルウェアスタック（`setup_middlewares()`）との共存、
+例外ハンドリングの限界、UseCase への注入パターンを検証した。
+
+---
+
+## 実装パターン
+
+### 基本パターン（ハンドラーで BackgroundTasks を受け取る）
+
+```python
+from fastapi import BackgroundTasks
+
+@app.post("/orders")
+def create_order(body: OrderBody, background_tasks: BackgroundTasks) -> JSONResponse:
+    output = use_case.execute(CreateOrderInput(item=body.item, quantity=body.quantity))
+    # レスポンス送信後にバックグラウンドで実行される
+    background_tasks.add_task(send_order_confirmation, output.order_id, output.item)
+    background_tasks.add_task(update_inventory, output.item, output.quantity)
+    return JSONResponse({...}, status_code=201)
+```
+
+### UseCase を注入可能にするパターン（テスト用ファクトリー）
+
+```python
+def create_app_with_use_case(
+    create_order_fn: Callable[[CreateOrderInput], CreateOrderOutput]
+) -> FastAPI:
+    factory_app = FastAPI()
+    setup_middlewares(factory_app)
+
+    @factory_app.post("/orders")
+    def _create_order(body: OrderBody, background_tasks: BackgroundTasks) -> JSONResponse:
+        output = create_order_fn(...)
+        background_tasks.add_task(send_order_confirmation, output.order_id, output.item)
+        return JSONResponse({...}, status_code=201)
+
+    return factory_app
+
+# テストでの使用
+injected_app = create_app_with_use_case(lambda _: mock_output)
+```
+
+---
+
+## 発見した問題
+
+### 問題1: バックグラウンドタスクの例外がクライアントに見えない
+
+```python
+# バックグラウンドタスクが例外を投げても...
+def send_email(order_id: int) -> None:
+    raise SMTPConnectionError("Mail server down")
+
+@app.post("/orders")
+def create_order(body: OrderBody, background_tasks: BackgroundTasks) -> JSONResponse:
+    output = use_case.execute(...)
+    background_tasks.add_task(send_email, output.order_id)
+    return JSONResponse({...}, status_code=201)  # ← 201 が返る
+
+# クライアントには 201 が届く（メール失敗は見えない）
+```
+
+FastAPI の設計上、レスポンスはすでに送信済みのため
+バックグラウンドタスクのエラーを HTTP レスポンスコードで伝えられない。
+エラーはサーバーログに記録されるが、クライアントには `201 Created` が届く。
+
+### 問題2: nene2 に BackgroundTasks 推奨パターンがない
+
+```python
+# UseCase にどうやって BackgroundTasks を渡すか、ドキュメントがない
+
+# ❌ UseCase の中で直接 BackgroundTasks を使う（アーキテクチャ違反）
+class CreateOrderUseCase:
+    def execute(self, input_: CreateOrderInput, bg: BackgroundTasks) -> CreateOrderOutput:
+        ...
+        bg.add_task(send_email, ...)  # UseCase が HTTP 境界に依存してしまう
+
+# ✅ ハンドラー層で BackgroundTasks を使い、UseCase は純粋に保つ
+@app.post("/orders")
+def create_order(body: OrderBody, background_tasks: BackgroundTasks) -> JSONResponse:
+    output = use_case.execute(CreateOrderInput(...))  # UseCase はクリーン
+    background_tasks.add_task(send_email, output.order_id)  # ハンドラー層で副作用
+    return JSONResponse({...})
+```
+
+正しいパターン（UseCase を純粋に保ちハンドラー層で BackgroundTasks を使う）が
+nene2 のドキュメントに記載されていない。
+
+### 問題3: バックグラウンドタスクの実行確認ができない
+
+```python
+# 「タスクをキューした」ことと「タスクが成功した」ことを HTTP で区別できない
+r = client.post("/orders/1/alert")
+# レスポンスは {"queued": True} — 成功したかどうかはわからない
+```
+
+本番運用では Celery・ARQ・FastAPI Scheduler などの外部ジョブキューが必要。
+「BackgroundTasks は軽量な one-shot 処理向け」という点がドキュメントに不足。
+
+---
+
+## テスト結果（全16件パス）
+
+```
+test_create_order_returns_201                              PASSED
+test_get_order_returns_200                                 PASSED
+test_get_nonexistent_order_returns_404                     PASSED
+test_background_tasks_execute_after_response               PASSED  # TestClient は同期実行
+test_multiple_background_tasks_all_execute                 PASSED
+test_background_task_with_alert                            PASSED
+test_background_task_not_queued_on_404                     PASSED  # 404 ではタスク未実行
+test_failing_background_task_does_not_affect_response      PASSED  # 例外 → 200 のまま
+test_failing_background_task_started                       PASSED
+test_request_id_present_with_background_tasks              PASSED  # nene2 と共存
+test_security_headers_present_with_background_tasks        PASSED  # nene2 と共存
+test_validation_error_does_not_queue_background_tasks      PASSED  # 422 では未実行
+test_injectable_use_case_pattern                           PASSED  # DI パターン動作
+test_friction_background_exception_not_visible_to_client   PASSED  # 摩擦記録
+test_friction_no_nene2_background_task_pattern             PASSED  # 摩擦記録
+test_friction_background_task_cannot_return_result         PASSED  # 摩擦記録
+```
+
+---
+
+## 重要な発見: TestClient はバックグラウンドタスクを同期実行する
+
+```python
+client = TestClient(app)
+r = client.post("/orders", json={"item": "Widget", "quantity": 1})
+# TestClient はレスポンスを返す前にバックグラウンドタスクも実行する
+assert "confirmation:order_1:Widget" in notification_log  # ✅ すでに実行済み
+```
+
+`TestClient` はバックグラウンドタスクをリクエスト完了前に同期的に実行するため、
+テストでは `background_tasks.add_task()` で追加した処理を即座に検証できる。
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F82-1 | バックグラウンドタスクの例外がクライアントに見えない（FastAPI 設計上の制約） | 中 |
+| F82-2 | nene2 に BackgroundTasks 推奨パターン（UseCase との分離）のドキュメントがない | 低 |
+| F82-3 | バックグラウンドタスクは result を返せない（外部キューが必要） | 低 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★★★☆
+
+`background_tasks.add_task(fn, arg1, arg2)` は非常にシンプルで直感的。
+FastAPI のドキュメントを読めば即座に使える。
+nene2 のミドルウェアスタックとの共存も問題なし。
+
+### 実害の深刻さ ★★☆☆☆
+
+バックグラウンド例外がクライアントに見えない問題は、
+軽量な通知タスク（メール送信）であれば許容範囲。
+ただし「注文確定」のような業務的に重要な処理を
+バックグラウンドタスクに入れるのは設計ミス — そこは UseCase に残すべき。
+
+### 修正のしやすさ ★★★★★
+
+必要なのはドキュメントのみ:
+- UseCase はクリーンに保つ（BackgroundTasks を引数に取らない）
+- ハンドラー層でのみ `background_tasks.add_task()` を呼ぶ
+- 失敗して困る処理はバックグラウンドタスクに入れない
+- TestClient はバックグラウンドタスクを同期実行する（テスト性良好）
+
+### 総合コメント
+
+FastAPI の `BackgroundTasks` は nene2 と相性が良く、
+`setup_middlewares()` のミドルウェアスタックとも完全に共存する。
+X-Request-Id・セキュリティヘッダーも正常に付与される。
+摩擦の大部分は「どう使うべきか」のドキュメント不足であり、
+フレームワークの改修は不要。
+
+---
+
+## 推奨アクション
+
+1. **docs**: BackgroundTasks パターン（UseCase との分離、TestClient の同期実行）を how-to ガイドに追加
+2. **minor**: BackgroundTasks は「失敗しても OK な副作用のみ」というガイドラインの明記

nene2_python-1.8.28/docs/field-trials/2026-05-field-trial-83.md

@@ -0,0 +1,223 @@
+# FT83: Depends() DI — FastAPI Depends を nene2 アーキテクチャで活用するパターン検証
+
+**日付**: 2026-05-20  
+**テーマ**: UseCase・認証・Pagination の Depends 組み合わせパターンと dependency_overrides  
+**バージョン**: v1.8.27  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft83-depends-injection/`
+
+---
+
+## 概要
+
+FastAPI の `Depends()` を nene2 の UseCase + Repository パターンと組み合わせた。
+依存チェーン（Repository → UseCase → Handler）、認証 Depends、
+`PaginationQueryParser` の統合、テスト時の `dependency_overrides` による差し替えを検証した。
+`PaginationResponse.model_dump()` が存在しない（`to_dict()` が正しい）という
+Pydantic ユーザーがつまずく摩擦点を発見した。
+
+---
+
+## 実装パターン
+
+### Repository → UseCase の Depends チェーン
+
+```python
+from typing import Annotated
+from fastapi import Depends
+
+def get_repo() -> InMemoryProductRepository:
+    return _repo  # シングルトン
+
+def get_list_use_case(
+    repo: Annotated[InMemoryProductRepository, Depends(get_repo)],
+) -> ListProductsUseCase:
+    return ListProductsUseCase(repo)
+
+@app.get("/products")
+def list_products(
+    use_case: Annotated[ListProductsUseCase, Depends(get_list_use_case)],
+) -> JSONResponse:
+    products, total = use_case.execute(...)
+    return JSONResponse(...)
+```
+
+### PaginationQueryParser + UseCase の両方を Depends
+
+```python
+@app.get("/products")
+def list_products(
+    pagination: Annotated[PaginationQueryParser, Depends(PaginationQueryParser)],
+    use_case: Annotated[ListProductsUseCase, Depends(get_list_use_case)],
+) -> JSONResponse:
+    products, total = use_case.execute(
+        limit=pagination.limit, offset=pagination.offset
+    )
+    return JSONResponse(
+        PaginationResponse(
+            items=[...], total=total, limit=pagination.limit, offset=pagination.offset
+        ).to_dict()  # ← model_dump() ではなく to_dict()
+    )
+```
+
+### 認証 Depends（Bearer Token）
+
+```python
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+security = HTTPBearer(auto_error=False)
+
+def get_current_user(
+    credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(security)],
+) -> str | None:
+    if credentials is None:
+        return None
+    return verify_token(credentials.credentials)
+
+def require_auth(user: Annotated[str | None, Depends(get_current_user)]) -> str:
+    if user is None:
+        raise HTTPException(status_code=401)
+    return user
+
+@app.post("/products")
+def create_product(
+    body: ProductBody,
+    use_case: Annotated[CreateProductUseCase, Depends(get_create_use_case)],
+    current_user: Annotated[str, Depends(require_auth)],
+) -> JSONResponse: ...
+```
+
+### テスト時の dependency_overrides
+
+```python
+custom_repo = InMemoryProductRepository()
+custom_repo.create("Test Product", 100)
+
+app.dependency_overrides[get_repo] = lambda: custom_repo
+# テスト実行
+del app.dependency_overrides[get_repo]  # クリーンアップ
+```
+
+---
+
+## 発見した問題
+
+### 問題1: PaginationResponse.model_dump() が存在しない
+
+```python
+# ❌ Pydantic ユーザーは model_dump() を期待してしまう
+PaginationResponse(...).model_dump()  # AttributeError!
+
+# ✅ 正しいメソッド
+PaginationResponse(...).to_dict()
+```
+
+`PaginationResponse` は dataclass だが、Pydantic v2 に慣れているユーザーは
+`model_dump()` を期待して AttributeError に直面する。
+FastAPI の OpenAPI ドキュメントや response_model を使うには
+Pydantic BaseModel にするか、FastAPI の Response 型として登録する必要がある。
+
+### 問題2: Annotated[T, Depends(fn)] の記述が冗長
+
+```python
+# 現在の書き方（型情報が Annotated の外側と内側に重複）
+def list_products(
+    pagination: Annotated[PaginationQueryParser, Depends(PaginationQueryParser)],
+    use_case: Annotated[ListProductsUseCase, Depends(get_list_use_case)],
+) -> JSONResponse: ...
+
+# 理想（nene2 が型エイリアスを提供）
+type PaginationDep = Annotated[PaginationQueryParser, Depends(PaginationQueryParser)]
+
+@app.get("/products")
+def list_products(pagination: PaginationDep, ...) -> JSONResponse: ...
+```
+
+`PaginationQueryParser` の `Annotated` エイリアスを nene2 が提供すれば
+毎回書く冗長さが解消される。
+
+### 問題3: nene2 の認証 Depends ユーティリティがない
+
+```python
+# nene2.auth に Depends ユーティリティがない
+# ユーザーは HTTPBearer + LocalTokenVerifier を手動で組み合わせる必要がある
+
+# 理想:
+from nene2.auth.deps import CurrentUser, require_auth
+# これが存在しない
+```
+
+`LocalTokenVerifier.from_env()` は実装されているが、
+FastAPI の Depends パターンに接続する `CurrentUser` 型や
+`require_auth` Depends がない。
+
+---
+
+## テスト結果（全16件パス）
+
+```
+test_list_products_empty                        PASSED
+test_create_product_returns_201                  PASSED
+test_get_product_returns_200                     PASSED
+test_get_nonexistent_returns_404                 PASSED
+test_create_product_requires_auth                PASSED
+test_create_product_with_auth_succeeds           PASSED
+test_pagination_with_depends                     PASSED  # PaginationQueryParser Depends 動作
+test_pagination_second_page                      PASSED
+test_override_repo_with_custom_data              PASSED  # dependency_overrides 動作
+test_override_repo_empty                         PASSED
+test_request_id_with_depends                     PASSED  # nene2 ミドルウェアと共存
+test_security_headers_with_depends               PASSED
+test_validation_error_returns_422                PASSED
+test_friction_annotated_syntax_verbosity         PASSED  # 摩擦記録
+test_friction_use_case_chains_in_depends         PASSED  # 摩擦記録
+test_friction_no_nene2_depends_utilities         PASSED  # 摩擦記録
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F83-1 | `PaginationResponse.model_dump()` が存在しない（`to_dict()` が正しい）— Pydantic ユーザー混乱 | 中 |
+| F83-2 | `Annotated[PaginationQueryParser, Depends(PaginationQueryParser)]` の冗長記述 | 低 |
+| F83-3 | nene2 認証の Depends ユーティリティ (`CurrentUser`, `require_auth`) がない | 低 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★★☆☆
+
+`Depends()` のパターン自体は FastAPI の機能なので明確。
+ただし Repository → UseCase → Handler の3層チェーンは
+Spring/NestJS の DI に慣れたユーザーには違和感がある
+（Constructor Injection ではなく Function Injection）。
+`dependency_overrides` によるテスト差し替えは非常に優れた機能。
+
+### 実害の深刻さ ★★☆☆☆
+
+`PaginationResponse.to_dict()` を知らなければ AttributeError で即座に詰まる。
+nene2 ドキュメントに `PaginationResponse` の使い方が記載されているが、
+`model_dump()` と混同するユーザーが続出する可能性がある。
+
+### 修正のしやすさ ★★★★★
+
+- `PaginationResponse` に `model_dump()` の alias を追加（または別名で明記）
+- `Annotated[PaginationQueryParser, Depends(PaginationQueryParser)]` を `PaginationDep` 型エイリアスとして公開
+- `nene2.auth.deps` モジュールに `CurrentUser` 型と `require_auth` Depends を追加
+
+### 総合コメント
+
+FastAPI の `Depends()` は nene2 のアーキテクチャと非常に相性がよく、
+Repository の差し替えも `dependency_overrides` で簡単にできる。
+主な摩擦は `PaginationResponse.to_dict()` の名前（Pydantic との不整合）と
+認証 Depends ユーティリティの欠如。どちらも小さな追加で解決できる。
+
+---
+
+## 推奨アクション
+
+1. **Issue**: `PaginationResponse` に `model_dump()` エイリアスを追加（Pydantic ユーザー向け）
+2. **Issue**: `nene2.http` に `PaginationDep` 型エイリアスを追加（`PaginationQueryParser` の Depends）
+3. **Issue**: `nene2.auth.deps` モジュールに認証 Depends ユーティリティを追加

{nene2_python-1.8.26 → nene2_python-1.8.28}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nene2-python"
-version = "1.8.26"
+version = "1.8.28"
 description = "NENE2 Python — minimal API framework following NENE2's design philosophy"
 readme = "README.md"
 license = {text = "MIT"}

{nene2_python-1.8.26 → nene2_python-1.8.28}/src/nene2/http/__init__.py

@@ -7,7 +7,7 @@ from .health import (
     HealthCheckProtocol,
     HealthStatus,
 )
-from .pagination import PaginationQuery, PaginationQueryParser, PaginationResponse
+from .pagination import PaginationDep, PaginationQuery, PaginationQueryParser, PaginationResponse
 from .problem_details import (
     PROBLEM_DETAILS_BASE_URL,
     configure_problem_details,
@@ -21,6 +21,7 @@ __all__ = [
     "CompositeHealthCheck",
     "HealthCheckProtocol",
     "HealthStatus",
+    "PaginationDep",
     "PaginationQuery",
     "PaginationQueryParser",
     "PaginationResponse",