nene2-python 1.8.33__tar.gz → 1.8.35__tar.gz

{nene2_python-1.8.33 → nene2_python-1.8.35}/CHANGELOG.md

@@ -5,6 +5,24 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.34] — 2026-05-20
+
+テストの ResourceWarning 解消と `SqlAlchemyQueryExecutor` / `SqlAlchemyTransactionManager` の `engine` プロパティ追加。
+
+### Added
+- `SqlAlchemyQueryExecutor.engine` プロパティ — 下層の SQLAlchemy エンジンを公開（テストのティアダウンで `executor.engine.dispose()` に使用）(#428)
+- `SqlAlchemyTransactionManager.engine` プロパティ — 同上 (#428)
+
+### Fixed
+- テスト実行時に Python 3.14 で 80+ 件出ていた `ResourceWarning: unclosed database` を解消 (#428)
+  - `create_app()` で `app.state.db_executor` を保存してテストからエンジンを dispose できるように変更
+  - `export_openapi.py` でエンジンを dispose するように修正
+  - テストフィクスチャを `yield` + `engine.dispose()` パターンに統一
+  - `tests/conftest.py` を新規作成し module-level app エンジンをセッション終了時に dispose
+  - `StaticPool` の最後の 1 件は `pyproject.toml` の `filterwarnings` で抑制
+
+---
+
 ## [1.8.33] — 2026-05-20
 
 FT100 フィールドトライアル — In-memory TTL レスポンスキャッシュパターン検証と nene2.cache モジュール追加。

{nene2_python-1.8.33 → nene2_python-1.8.35}/CLAUDE.md

@@ -355,7 +355,75 @@ docs/
 
 ---
 
-## 12. PHP版 NENE2 との対応表
+## 12. フィールドトライアル（FT）方法論
+
+### 目的
+
+Python 標準ライブラリ・サードパーティライブラリを nene2-python 上で実装し、
+フレームワーク API の安定性を実装者目線で検証する。
+「実際に詰まったポイント」だけを観察ベースで Issue 化し、
+ドキュメントと設計を同時に成長させるサイクルを回す。
+
+### フロー（1 FT あたり）
+
+```
+1. テーマ選定（docs/todo/current.md から未検証パターンを選ぶ）
+2. 独立サンドボックスを作成
+   場所: /home/xi/docker/nene2-python-FT/ftNNN-テーマ名/
+   ゼロから uv init → nene2-python を依存として追加
+3. 実装 + 全チェック通過
+   uv run pytest && uv run mypy src/ && uv run ruff check src/ tests/
+4. 摩擦点を記録（F-1, F-2, ...）
+5. FT レポート作成 → docs/field-trials/2026-05-field-trial-NNN.md
+   テンプレート: docs/templates/field-trial-report.md
+6. DX Review（6ペルソナ）を実施（後述）
+7. FT番号が3の倍数なら セキュリティ診断 を実施（後述）
+8. Follow-up Issues を GitHub Issue に変換
+9. まとめて main merge → パッチバージョン（v1.8.N）でリリース
+```
+
+### DX Review — 6ペルソナ
+
+各 FT レポートの末尾に、以下 6 ペルソナ目線での評価を必ず記載する。
+「コードが動く」だけでなく「初心者から経験者まで安全に使えるか」を客観的に検証する。
+
+| ペルソナ | 属性 | 主な評価観点 |
+|---|---|---|
+| **1. 初心者** | Python 歴1年・独学中・女性・バックエンド志望 | ドキュメント理解・事故リスク・規約の使いやすさ |
+| **2. ロースキル経験者** | Python 歴3-4年・スクリプト系・男性・SES | コピペ可能性・拡張時の罠・セキュリティ的な事故リスク |
+| **3. フロントエンド寄り** | React/TS 歴4年・バックエンド転向中・ノンバイナリ | エラーレスポンスの質・Python 固有概念の学習コスト |
+| **4. バックエンド経験者** | Django/FastAPI 歴5-6年・男性・リードエンジニア | 他フレームワークとの差異・nene2 の薄さへの評価 |
+| **5. シニアエンジニア** | 設計・コードレビュー担当・女性・10-12年 | コードレビューチェックポイント・チームでの安全なパターン |
+| **6. 設計者** | nene2-python 設計ポリシー目線 | CLAUDE.md ポリシー整合性・初心者でも安全な API 達成度 |
+
+各ペルソナの記述フォーマット:
+- 状況説明 1 文（ペルソナが置かれているコンテキスト）
+- 太字サブヘッディング 2〜4個（ドキュメント理解 / 事故リスク / 規約の使いやすさ など）
+- 事故リスクは「高 / 中 / 低」で定性評価
+
+### セキュリティ診断（3の倍数 FT）
+
+**FT番号 % 3 == 0 のとき**（FT165, FT168, ...）、通常のFT完了後に追加で実施する。
+
+**診断レベル**: Django・FastAPI・SQLAlchemy 本体でも CVE が報告されてきた攻撃ベクターを対象とする。
+
+対象カテゴリ（詳細は `docs/templates/field-trial-report.md` のセキュリティ診断セクション参照）:
+
+1. **OWASP API Security Top 10 (2023)** — BOLA/IDOR・認証破損・Mass Assignment・リソース消費・SSRF・設定ミス
+2. **インジェクション攻撃** — SQL・コマンド・パストラバーサル・SSTI・HTTP ヘッダーインジェクション
+3. **認証・認可** — パスワードハッシュ・タイミング攻撃・JWT alg:none・セッション固定
+4. **入力バリデーション** — 上限なし文字列・数値オーバーフロー・Null バイト・Unicode RTL
+5. **情報漏洩** — スタックトレース公開・ログへの機密データ出力・pip-audit CVE スキャン
+6. **Python/FastAPI 固有** — ReDoS・pickle/yaml インジェクション・非同期レースコンディション・Pydantic 型強制・SQLAlchemy raw query バイパス
+
+**合否判定**:
+- **合格**: 全カテゴリ問題なし
+- **条件付き合格**: MEDIUM 以下の指摘のみ、次 FT までに修正
+- **不合格**: HIGH/CRITICAL の指摘あり → main merge 前に必須修正
+
+---
+
+## 13. PHP版 NENE2 との対応表
 
 | PHP | Python |
 |---|---|

{nene2_python-1.8.33 → nene2_python-1.8.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.33
+Version: 1.8.35
 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.35/docs/field-trials/2026-05-field-trial-101.md

@@ -0,0 +1,59 @@
+# Field Trial 101: Query Parameter Filter/Sort パターン
+
+## テーマ
+
+`?status=published&sort=views&order=desc&tag=fastapi` のような複数フィルター + ソートのクエリパラメーターを型安全に扱うパターンを nene2 上で実装する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft101-query-filter/` に以下を実装:
+
+- `ArticleFilter` dataclass に `StrEnum` で列挙型フィルター
+- `get_article_filter()` ファクトリ関数で `Depends()` に接続
+- `PaginationQueryParser` と組み合わせてページネーション
+- 11 テスト通過
+
+## テスト結果
+
+全 11 テスト通過（修正後）。
+
+## Friction Points
+
+### FP1: `PaginationQueryParser.as_depends()` が存在しない（ドキュメントとの乖離）
+
+**状況**: 他のパーサー系クラスで `as_depends()` ファクトリパターンを使うケースがあり（FT83 など）、`PaginationQueryParser.as_depends()` を試みたが `AttributeError`。
+
+正しい使い方は:
+```python
+# ✅ Annotated スタイル
+pagination: Annotated[PaginationQueryParser, Depends()]
+
+# ❌ as_depends() は存在しない
+pagination: PaginationQueryParser = Depends(PaginationQueryParser.as_depends())
+```
+
+**影響**: `Depends()` の使い方が複数あるため混乱しやすい。how-to ガイドに明記が必要。
+
+### FP2: `Depends()` スタイルとデフォルト値の混在でシンタックスエラー
+
+**状況**: 複数の `Depends()` パラメーターを持つハンドラーで、`= Depends(...)` スタイルと `Annotated[T, Depends()]` スタイルを混在させると `SyntaxError: parameter without a default follows parameter with a default` が出る。
+
+```python
+# ❌ SyntaxError
+def list_articles(
+    filter_: ArticleFilter = Depends(get_article_filter),  # デフォルト値あり
+    pagination: Annotated[PaginationQueryParser, Depends()],  # デフォルト値なし
+) -> JSONResponse: ...
+
+# ✅ Annotated スタイルに統一
+def list_articles(
+    filter_: Annotated[ArticleFilter, Depends(get_article_filter)],
+    pagination: Annotated[PaginationQueryParser, Depends()],
+) -> JSONResponse: ...
+```
+
+**影響**: エラーメッセージが直感的でなく、原因がわかりにくい。
+
+## まとめ
+
+摩擦の原因はドキュメント不足。FP1・FP2 を how-to ガイドに追記する Issue を起票する。コード修正は不要。

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-102.md

@@ -0,0 +1,34 @@
+# Field Trial 102: response_model と PaginationResponse の型整合性
+
+## テーマ
+
+`response_model` と `PaginationResponse` / `JSONResponse` の組み合わせパターンを実際に動かして、OpenAPI スキーマへの影響と型整合性を検証する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft102-response-model/` に 4 パターンを実装:
+
+1. **v1**: `response_model` なし + `JSONResponse` + `PaginationResponse`
+2. **v2**: `response_model=ProductListResponse` + Pydantic モデル直返し
+3. **v3**: `response_model=ProductListResponse` + `dict` 返却（FastAPI が変換）
+4. **v4**: `response_model=ProductListResponse` + `JSONResponse`（検証はされない）
+
+## テスト結果
+
+全 9 テスト通過。
+
+## Friction Points
+
+摩擦なし。
+
+`response-patterns.md` How-to（PR #403 で追加済み）がこのパターンを説明しており、スムーズに実装できた。
+
+- パターン1（JSONResponse + PaginationResponse）は OpenAPI スキーマなしで OK
+- パターン2（Pydantic 直返し + response_model）は OpenAPI スキーマあり
+- パターン4（JSONResponse + response_model）は response_model があってもバリデーション非実施
+
+前回の摩擦（`problem_details_response()` と Pydantic 直返しの非一貫性）は PR #403 で文書化済み。
+
+## まとめ
+
+ドキュメント整備が功を奏し、摩擦ゼロで実装完了。

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-103.md

@@ -0,0 +1,47 @@
+# Field Trial 103: カスタムミドルウェアで認証情報をリクエストスコープに格納
+
+## テーマ
+
+JWT ミドルウェアで検証後の認証情報（`AuthUser`）を `request.state` に格納し、ハンドラーで `Depends()` を通じて取得するパターンを検証する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft103-request-state-auth/` に以下を実装:
+
+- `JwtAuthMiddleware` — JWT を検証して `request.state.user` に `AuthUser` を格納
+- `get_current_user()` — `request.state.user` から `AuthUser` を取得する Depends ファクトリ
+- `require_admin()` — `admin` ロールチェック依存
+- `EXCLUDE_PATHS` で `/health` をスキップ
+
+## テスト結果
+
+全 7 テスト通過。`InsecureKeyLengthWarning` はテスト用の短いシークレットによるもの（想定内）。
+
+## Friction Points
+
+### FP1: `request.state.user` アクセスに `type: ignore[attr-defined]` が必要
+
+**状況**: `request.state` は `starlette.datastructures.State` で動的属性を持つ。ミドルウェアで `request.state.user = AuthUser(...)` と設定しても、Depends ファクトリで `request.state.user` を参照する際に mypy が `attr-defined` エラーを出す。
+
+```python
+def get_current_user(request: Request) -> AuthUser:
+    user: AuthUser = request.state.user  # type: ignore[attr-defined]  # reason: middleware で確実に設定済み
+    return user
+```
+
+これは `app.state` でも同様（FT100 で確認済み）。
+
+**影響**: 低。`type: ignore` + `reason` コメントで対処可能。
+
+### FP2: `BearerTokenMiddleware` のトークン文字列が `request.state` に格納されない
+
+**状況**: nene2 の `BearerTokenMiddleware` は JWT/API キーの検証後にトークン文字列を返す（`make_require_auth()` Depends 経由）が、検証済みのペイロードやユーザー情報を `request.state` に自動格納する機能がない。
+
+カスタム JWT ミドルウェアで対応したが、`BearerTokenMiddleware` + `request.state` の統合パターンがない。
+
+**影響**: 中。`BearerTokenMiddleware` を使いたいが `request.state` にユーザー情報を格納したい場合、自前ミドルウェアを書き直す必要がある。
+
+## まとめ
+
+FP1 は既知の Starlette 制約（low）。FP2 は nene2 の認証統合に関する中程度の摩擦。
+docs として「request.state を使った認証情報伝播パターン」を how-to に追加する。

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-104.md

@@ -0,0 +1,48 @@
+# Field Trial 104: AsyncIterator を返す UseCase + StreamingResponse
+
+## テーマ
+
+UseCase が `AsyncIterator` を返し、FastAPI の `StreamingResponse` でストリーミングする本格的なパターンを検証する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft104-streaming-usecase/` に以下を実装:
+
+- `StreamLogsUseCase` — `AsyncIterator[LogEntry]` を返す UseCase
+- `ExportCsvUseCase` — CSV 行を `AsyncIterator[str]` で返す UseCase
+- NDJSON / SSE / CSV の 3 形式にストリーミング変換
+- 6 テスト通過
+
+## テスト結果
+
+全 6 テスト通過（修正後）。
+
+## Friction Points
+
+### FP1: `TestClient.stream()` 内で `r.text` が使えない
+
+**状況**: `with client.stream("GET", "/export/users.csv") as r:` コンテキスト内で `r.text` にアクセスすると `httpx.ResponseNotRead` が発生する。
+
+```python
+# ❌ ResponseNotRead
+with client.stream("GET", "/export/csv") as r:
+    content = r.text  # エラー!
+
+# ✅ iter_text() でチャンク収集
+with client.stream("GET", "/export/csv") as r:
+    content = "".join(r.iter_text())
+```
+
+**影響**: ストリーミングレスポンスのテストで直感に反するエラーが出る。`streaming.md` How-to に `iter_text()` パターンを追記する必要がある。
+
+### FP2: `AsyncUseCaseProtocol` は `AsyncIterator` を返す UseCase に対応していない
+
+**状況**: `AsyncUseCaseProtocol` は `async def execute(self, input_: I) -> O` を定義しており、`O = AsyncIterator[T]` として使うことは技術的には可能だが、`O` 型が `AsyncIterator` であることを表現するのが難しい。
+
+現在の実装では `AsyncUseCaseProtocol` を使わず、独立した UseCase クラスとして実装した。
+
+**影響**: 低。ストリーミング UseCase は専用の Protocol を定義するか、型注釈なしで書くのが現実的。
+
+## まとめ
+
+FP1 をドキュメント修正で対応。FP2 は将来の検討事項として記録。

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-105.md

@@ -0,0 +1,43 @@
+# Field Trial 105: マルチテナント DB 接続
+
+## テーマ
+
+`X-Tenant-Id` ヘッダーでテナントを切り替え、リクエストごとに異なる SQLite DB に接続するマルチテナントパターンを検証する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft105-multitenant/` に以下を実装:
+
+- `TENANT_DB_URLS` マップでテナント DB URL を管理
+- `get_tenant_session()` Depends でテナント特定・セッション生成
+- テナント分離テスト（A と B は独立した DB）
+
+## テスト結果
+
+全 6 テスト通過。
+
+## Friction Points
+
+### FP1: `create_engine()` をリクエストごとに呼ぶのはパフォーマンス上の問題
+
+**状況**: `get_tenant_session()` がリクエストごとに `create_engine()` を呼ぶ。SQLAlchemy では `create_engine()` はアプリ起動時に一度だけ呼ぶべきで、コネクションプールを使い回す設計が推奨される。
+
+nene2 にテナントごとのエンジンキャッシュパターンがない。`TtlCache[Session]` で代替できるが、セッションはリクエストスコープで閉じる必要があるため、エンジンをキャッシュすべき。
+
+```python
+# 推奨パターン
+_engine_cache: dict[str, Engine] = {}
+
+def get_engine(tenant_id: str) -> Engine:
+    if tenant_id not in _engine_cache:
+        _engine_cache[tenant_id] = create_engine(TENANT_DB_URLS[tenant_id], ...)
+    return _engine_cache[tenant_id]
+```
+
+### FP2: `SqlAlchemyQueryExecutor` はシングルエンジン想定
+
+**状況**: `nene2.database.SqlAlchemyQueryExecutor` はアプリ起動時に単一エンジンで初期化することを前提としている。マルチテナントでリクエストごとに異なるエンジンを使う場合、`SqlAlchemyQueryExecutor` を使わず直接 `Session` を操作する必要がある。
+
+## まとめ
+
+FP1 は `TtlCache` を使ったエンジンキャッシュパターンとして docs に追記する。FP2 はアーキテクチャ設計上の制約として記録。コード修正は不要。

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-106.md

@@ -0,0 +1,39 @@
+# Field Trial 106: Idempotency Key パターン
+
+## テーマ
+
+`Idempotency-Key` ヘッダーを使って POST リクエストを冪等にするパターンを検証する。
+`nene2.cache.TtlCache` の実用例として組み込む。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft106-idempotency/` に以下を実装:
+
+- `TtlCache[dict[str, Any]]` を `app.state.idempotency_cache` として lifespan で初期化
+- `POST /orders` で `Idempotency-Key` ヘッダーをチェック
+- 既存キャッシュがあれば `X-Idempotency-Replayed: true` ヘッダーと共にキャッシュから返す
+- キャッシュなければ UseCase を実行してキャッシュに保存
+- 7 テスト通過
+
+## テスト結果
+
+全 7 テスト通過。
+
+## Friction Points
+
+### FP1: Idempotency Key 同一キー + 異なるボディの扱いが未定義
+
+**状況**: Stripe などの実装では、同じ `Idempotency-Key` で異なるリクエストボディを送ると `422 Unprocessable Entity` を返す。現在の実装ではキャッシュされた最初のレスポンスを無条件に返すため、ボディが変わっても同じレスポンスが返る。
+
+**影響**: 中。金融系 API では重要だが、一般的な API では省略可。
+
+### FP2: Idempotency Key ユーティリティがない
+
+**状況**: `TtlCache` を使って実装できたが、`get_idempotency_cache()` Depends パターンや `X-Idempotency-Replayed` ヘッダーの付与は完全に自前実装。Stripe / Square などで標準化されたパターンであるため、nene2 に軽量ユーティリティがあると便利。
+
+**影響**: 低。`TtlCache` + ハンドラーコードで完結可能。
+
+## まとめ
+
+`TtlCache` の実用例として Idempotency Key パターンはスムーズに実装できた。摩擦は小さい。
+docs として how-to を追加する。

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-107.md

@@ -0,0 +1,46 @@
+# Field Trial 107: Bulk Operations（一括作成・削除）
+
+## テーマ
+
+`POST /items/bulk` と `DELETE /items/bulk` による一括操作パターンを検証する。
+部分成功（一部成功・一部失敗）を 207 Multi-Status で返す方法も確認する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft107-bulk-ops/` に以下を実装:
+
+- `POST /items/bulk` — 一括作成（価格制限でビジネスバリデーション、部分失敗対応）
+- `DELETE /items/bulk` — 一括削除（存在しない ID は failed に入れる）
+- 207 Multi-Status レスポンスに `succeeded` / `failed` を含める
+- 8 テスト通過（修正後）
+
+## テスト結果
+
+全 8 テスト通過（修正後）。
+
+## Friction Points
+
+### FP1: `TestClient.delete()` が `json` パラメーターを受け付けない
+
+**状況**: `DELETE` リクエストにリクエストボディを付ける場合、`client.delete(url, json=body)` は `TypeError` になる。
+
+```python
+# ❌ TypeError: unexpected keyword argument 'json'
+r = client.delete("/items/bulk", json={"ids": [1, 2]})
+
+# ✅ request() を使う
+r = client.request("DELETE", "/items/bulk", json={"ids": [1, 2]})
+```
+
+**影響**: 中。DELETE + ボディはやや非標準だが、一括削除では一般的なパターン。テストコードが `request()` を直接使う必要があるため直感的でない。
+
+**代替案**: ボディを持つ DELETE の代わりに `POST /items/bulk-delete` にする方が REST 的にクリーン（ボディを持つ DELETE は RFC 9110 で「意味がないわけではないが、推奨されない」）。
+
+### FP2: 207 Multi-Status のレスポンス型が OpenAPI スキーマに表現しにくい
+
+**状況**: `response_model` で 207 のスキーマを定義しようとすると、succeeded/failed の型が複雑になる。実用的には `response_model` なしで `JSONResponse` を直接返すのが現実的。
+
+## まとめ
+
+FP1 は how-to に追記（`TestClient` の HTTP メソッドと `json` パラメーターの注意点）。
+FP2 はドキュメント摩擦（bulk 操作は `response_model` を省略して OK）。

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-108.md

@@ -0,0 +1,46 @@
+# Field Trial 108: Pydantic computed_field と property パターン
+
+## テーマ
+
+Pydantic v2 の `@computed_field` + `@property` を使って、ストアドフィールドから計算されるプロパティを
+OpenAPI スキーマに自動的に含めるパターンを検証する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft108-computed-field/` に以下を実装:
+
+- `ProductResponse` — `price_dollars`, `is_in_stock`, `display_name` の computed fields
+- `OrderLineResponse` — ネストした computed fields (`line_total_cents`, `line_total_dollars`)
+- `/order-preview` エンドポイントで `JSONResponse(line.model_dump(mode="json"))` パターン確認
+- 6 テスト通過
+
+## テスト結果
+
+全 6 テスト通過。
+
+## Friction Points
+
+### FP1: `model_dump()` が datetime を Python オブジェクトのまま返す → `JSONResponse` で 500 エラー
+
+**状況**: `OrderLineResponse` のネストモデルには `created_at: datetime` フィールドがある。
+`JSONResponse(line.model_dump())` を使うと、`json.dumps` が `datetime` を直列化できずに
+`TypeError: Object of type datetime is not JSON serializable` で 500 エラーになる。
+
+```python
+# ❌ model_dump() は datetime をそのまま返す → JSONResponse でエラー
+return JSONResponse(line.model_dump())
+
+# ✅ mode="json" を指定すると datetime を ISO 8601 文字列に変換する
+return JSONResponse(line.model_dump(mode="json"))
+```
+
+**影響**: 大。`response_model=` を使う通常のルートは FastAPI が自動変換するため問題ないが、
+`JSONResponse` を直接返すルート（207 Multi-Status, /order-preview など）でこのパターンを
+使い忘れると本番で 500 エラーになる。
+
+**代替案**: `jsonable_encoder(line.model_dump())` でも変換できるが、`mode="json"` の方が Pydantic 標準。
+
+## まとめ
+
+`@computed_field` + `@property` は摩擦ゼロで OpenAPI スキーマに含められる優れたパターン。
+FP1 は `JSONResponse` を直接使う場合の注意点として how-to に追記する。

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-109.md

@@ -0,0 +1,53 @@
+# Field Trial 109: API バージョニング（v1/v2 ルーティング）
+
+## テーマ
+
+FastAPI の `APIRouter` を使って `/v1` と `/v2` でエンドポイントを分離するパターンを検証する。
+- フィールド名の変更（`email` → `contact_email`）
+- フィールドの追加（`age` を v2 で追加）
+- `full_name` から `first_name`/`last_name` への分割
+- OpenAPI スキーマが両バージョンを正確に反映するか
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft109-api-versioning/` に以下を実装:
+
+- ドメイン `User` dataclass（バージョン非依存）
+- `UserResponseV1` — `full_name`, `email`
+- `UserResponseV2` — `first_name`, `last_name`, `contact_email`, `age`
+- `v1_router = APIRouter(prefix="/v1", tags=["v1"])`
+- `v2_router = APIRouter(prefix="/v2", tags=["v2"])`
+- 9 テスト通過
+
+## テスト結果
+
+全 9 テスト一発通過。摩擦ゼロ。
+
+## Friction Points
+
+なし。`APIRouter(prefix="/v1")` でルーターを分離し `app.include_router()` で登録するだけで
+バージョン分離が完成する。OpenAPI スキーマも `UserResponseV1` / `UserResponseV2` を
+個別に定義することで両バージョンのスキーマが正確に生成される。
+
+## 観察
+
+### O1: バージョン間の共有ロジックはドメイン層に置く
+
+`find_user()` などのクエリ関数はバージョン非依存のドメイン層に置き、
+各バージョンのハンドラーから呼ぶ設計が自然に機能した。
+`from_domain()` クラスメソッドで変換することでドメインと HTTP を分離できた。
+
+### O2: OpenAPI タグでバージョンを整理できる
+
+`tags=["v1"]` / `tags=["v2"]` を `APIRouter` に指定すると、
+Swagger UI でバージョンごとにグループ化されて見やすくなる。
+
+### O3: `APIRouter` prefix は重複しない
+
+`app.include_router(v1_router)` で登録すると `/v1/users` になる。
+ルーター内のパスに `/v1` を書く必要はない（二重にならない）。
+
+## まとめ
+
+FT109 は摩擦ゼロ確認。APIバージョニングは FastAPI の `APIRouter` + `prefix` で
+自然に実現できる。how-to ドキュメントに記録のみ。

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-110.md

@@ -0,0 +1,66 @@
+# Field Trial 110: ソフトデリートパターン（論理削除）
+
+## テーマ
+
+`deleted_at: datetime | None` フィールドを使った論理削除パターンを検証する。
+- `DELETE /resources/{id}` が物理削除ではなく `deleted_at` をセットする
+- `GET /resources` / `GET /resources/{id}` が削除済みアイテムを除外する
+- DELETE は冪等（既に削除済みでも 204）
+- `deleted_at` を公開レスポンスに含めない（管理エンドポイントのみ）
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft110-soft-delete/` に以下を実装:
+
+- `Article` dataclass — `deleted_at: datetime | None = None`、`is_deleted` プロパティ
+- `dataclasses.replace()` で frozen dataclass を更新（`deleted_at` をセット）
+- `ArticleResponse` に `deleted_at` フィールドを含めない設計
+- 管理用 `/articles/{id}/deleted` エンドポイントで `deleted_at` を確認
+- 9 テスト通過
+
+## テスト結果
+
+全 9 テスト一発通過。摩擦ゼロ。
+
+## Friction Points
+
+なし。
+
+## 観察
+
+### O1: frozen dataclass の更新は dataclasses.replace() で簡潔に書ける
+
+```python
+from dataclasses import replace
+
+_articles[article_id] = replace(article, deleted_at=datetime.now(UTC))
+```
+
+`frozen=True` な dataclass でも `replace()` で新しいインスタンスを作成できる。
+イミュータブル設計を壊さずに更新できる。
+
+### O2: is_deleted プロパティでビジネスロジックをドメインに閉じ込める
+
+```python
+@property
+def is_deleted(self) -> bool:
+    return self.deleted_at is not None
+```
+
+クエリフィルタ（`a.is_deleted`）でリポジトリ層が `deleted_at is not None` を意識しなくてよい。
+
+### O3: DELETE は 204 + 冪等が REST ベストプラクティス
+
+既に削除済みのリソースへの DELETE も 204 を返すことで冪等性を保つ。
+存在しないリソースへの DELETE も同様。
+
+### O4: deleted_at をレスポンスモデルから除外するのは Pydantic の通常設計で簡単
+
+`ArticleResponse` に `deleted_at` フィールドを定義しなければ、自動的に除外される。
+`exclude=` や `model_config` の設定は不要。
+
+## まとめ
+
+FT110 は摩擦ゼロ。ソフトデリートは nene2 + Python dataclass で自然に実装できる。
+`dataclasses.replace()` / `is_deleted` プロパティ / Pydantic レスポンスフィルタリングの
+各パターンを how-to に記録する。

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-111.md

@@ -0,0 +1,53 @@
+# Field Trial 111: カーソルベースページネーション
+
+## テーマ
+
+ID ベースのカーソル（Base64 エンコード）で大規模データを安定的にページングするパターンを検証する。
+既存の `PaginationQueryParser`（オフセット型）との比較として実装する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft111-cursor-pagination/` に以下を実装:
+
+- `after` クエリパラメータ + `limit` でカーソルページネーション
+- `next_cursor` / `has_next` を含む `CursorPage` レスポンスモデル
+- Base64 URL-safe エンコードでカーソルを不透明にする
+- 100件のサンプルデータで重複なし検証
+- 7 テスト通過（修正後）
+
+## テスト結果
+
+全 7 テスト通過（1件修正後）。
+
+## Friction Points
+
+### FP1: 無効なカーソルで `binascii.Error` が捕捉されず 500 になる
+
+**状況**: `?after=invalidcursor!` のような無効な Base64 文字列を渡すと、
+`base64.urlsafe_b64decode()` が `binascii.Error` を raise する。
+これを捕捉しないと `ErrorHandlerMiddleware` が 500 として返す。
+
+```python
+# ❌ binascii.Error が uncaught → 500
+after_id = _decode_cursor(after)
+
+# ✅ try-except でカーソルデコードを保護する
+try:
+    after_id = _decode_cursor(after)
+except Exception:
+    return JSONResponse({"detail": "Invalid cursor"}, status_code=400)
+```
+
+**影響**: 中。入力バリデーションとして当然捕捉すべきだが、
+Pydantic の `Query()` では Base64 形式の検証はできない（文字列型のみ）。
+カーソルデコードは必ず try-except で保護する必要がある。
+
+**代替案**: `ValidationException` を raise して 422 にするパターンもあるが、
+不正なカーソルは「バリデーションエラー」ではなく「不正リクエスト」なので 400 が適切。
+
+## まとめ
+
+FP1 を how-to に追記。カーソルのデコードは必ず try-except で保護し 400 を返す。
+オフセットページネーションとの使い分け:
+- オフセット型: 件数が少ない、管理画面など「ページ番号」で飛びたい場合
+- カーソル型: 件数が多い、リアルタイムデータ、無限スクロールなど