yodogawa 2.1.3 → 2.3.0

package/templates/project/04-design/06-api-spec.md

@@ -1,226 +1,226 @@
-# API仕様
-
-<!--
-何を書くか: 認証方式、エンドポイント一覧、共通レスポンス形式
-
-目的:
-  - フロントエンド・バックエンド間の基本契約を明確化
-  - API設計の全体像を把握
-  - 開発者間の認識統一
-
-重要性:
-  - 高レベルなAPI設計の記録
-  - 詳細な仕様（リクエスト/レスポンスのスキーマ）はOpenAPI/Swaggerやコードで管理
-
-記載のポイント:
-  - 認証方式の基本情報
-  - エンドポイント一覧（メソッド、パス、説明、認証要否）
-  - 共通のレスポンス形式（成功/エラー）
-
-更新頻度:
-  - プロジェクト初期に基本設計を作成
-  - エンドポイント追加・削除時に更新
-
-**詳細な実装仕様の管理**:
-  - リクエスト/レスポンスの詳細なJSONスキーマ → OpenAPI/Swagger
-  - バリデーションルール → コード（バリデーター）
-  - エラーコード詳細 → コード（エラーハンドラー）
-  - ページネーション、レート制限 → コードと運用ドキュメント
--->
-
----
-
-## 認証・認可
-
-<!--
-API のセキュリティ方式の基本情報
-
-よくある認証方式:
-  - JWT (JSON Web Token): ステートレス、マイクロサービス向き
-  - OAuth 2.0: サードパーティ認証、権限委譲
-  - API Key: シンプル、内部API向き
-  - Session Cookie: ステートフル、Webアプリ向き
-
-記載すべき内容:
-  - 認証方法（JWT, OAuth 2.0, API Key など）
-  - トークンの基本的な有効期限
-  - 認証フローの概要
-  - 権限スコープの種類
--->
-
-| 項目 | 内容 |
-|------|------|
-| **認証方法** | <!-- 例: JWT Bearer Token --> |
-| **トークン有効期限** | <!-- 例: アクセストークン: 1時間、リフレッシュトークン: 30日 --> |
-| **トークン形式** | <!-- 例: Authorization: Bearer {token} --> |
-| **権限スコープ** | <!-- 例: read, write, admin --> |
-
-**認証フロー概要**:
-<!-- 例:
-1. POST /auth/login でログイン
-2. アクセストークンとリフレッシュトークンを取得
-3. 以降のリクエストで Authorization: Bearer {token} ヘッダーに含める
-4. トークン期限切れ時は POST /auth/refresh でリフレッシュ
--->
-
----
-
-## エンドポイント一覧
-
-<!--
-すべてのAPIエンドポイントを一覧化
-
-テーブル構成:
-【メソッド】
-  - HTTP メソッド（GET, POST, PUT, PATCH, DELETE）
-  - RESTful な使い分けを意識
-
-【パス】
-  - エンドポイントの URL パス
-  - パスパラメータは {id}, {userId} のように記載
-  - 例: /api/users/{id}, /api/orders/{orderId}/items
-
-【説明】
-  - エンドポイントの目的を1行で記載
-  - 例: 「ユーザー一覧を取得」「注文を作成」
-
-【認証】
-  - 必要/不要/オプション
-  - 必要な権限スコープがあれば記載（例: admin, write）
-
-【ステータス】
-  - 実装済み/未実装/非推奨（Deprecated）
-  - バージョニングで廃止予定のエンドポイントを記録
-
-記載のベストプラクティス:
-  - リソースごとにグループ化（ユーザー関連、注文関連など）
-  - CRUD 操作を揃える（GET一覧, GET詳細, POST作成, PUT更新, DELETE削除）
-  - ページネーションやフィルタリングのパラメータを記載
-  - 非推奨（Deprecated）エンドポイントも記録し、移行先を明記
--->
-
-### ユーザー管理
-
-| メソッド | パス | 説明 | 認証 | ステータス |
-|---------|------|------|------|-----------|
-| <!-- GET --> | <!-- /api/users --> | <!-- ユーザー一覧取得 --> | <!-- 必要（read） --> | <!-- 実装済み --> |
-| <!-- GET --> | <!-- /api/users/{id} --> | <!-- ユーザー詳細取得 --> | <!-- 必要（read） --> | <!-- 実装済み --> |
-| <!-- POST --> | <!-- /api/users --> | <!-- ユーザー作成 --> | <!-- 必要（write） --> | <!-- 実装済み --> |
-| <!-- PUT --> | <!-- /api/users/{id} --> | <!-- ユーザー更新（完全置換） --> | <!-- 必要（write） --> | <!-- 実装済み --> |
-| <!-- PATCH --> | <!-- /api/users/{id} --> | <!-- ユーザー更新（部分更新） --> | <!-- 必要（write） --> | <!-- 実装済み --> |
-| <!-- DELETE --> | <!-- /api/users/{id} --> | <!-- ユーザー削除 --> | <!-- 必要（admin） --> | <!-- 実装済み --> |
-
-### 注文管理
-
-| メソッド | パス | 説明 | 認証 | ステータス |
-|---------|------|------|------|-----------|
-| <!-- GET --> | <!-- /api/orders --> | <!-- 注文一覧取得 --> | <!-- 必要（read） --> | <!-- 実装済み --> |
-| <!-- GET --> | <!-- /api/orders/{id} --> | <!-- 注文詳細取得 --> | <!-- 必要（read） --> | <!-- 実装済み --> |
-| <!-- POST --> | <!-- /api/orders --> | <!-- 注文作成 --> | <!-- 必要（write） --> | <!-- 実装済み --> |
-| <!-- POST --> | <!-- /api/orders/{id}/cancel --> | <!-- 注文キャンセル --> | <!-- 必要（write） --> | <!-- 実装済み --> |
-
-### 認証
-
-| メソッド | パス | 説明 | 認証 | ステータス |
-|---------|------|------|------|-----------|
-| <!-- POST --> | <!-- /api/auth/login --> | <!-- ログイン --> | <!-- 不要 --> | <!-- 実装済み --> |
-| <!-- POST --> | <!-- /api/auth/logout --> | <!-- ログアウト --> | <!-- 必要 --> | <!-- 実装済み --> |
-| <!-- POST --> | <!-- /api/auth/refresh --> | <!-- トークンリフレッシュ --> | <!-- 不要（リフレッシュトークン必要） --> | <!-- 実装済み --> |
-
----
-
-## 共通レスポンス形式
-
-<!--
-全エンドポイントで統一するレスポンス形式
-
-記載すべき内容:
-  - 成功時のレスポンス構造
-  - エラー時のレスポンス構造
-  - 主要なHTTPステータスコード
-
-詳細な仕様（リクエスト/レスポンスの詳細なJSONスキーマ、
-バリデーションルール、エラーコード定義）は OpenAPI/Swagger で管理します。
--->
-
-### 成功レスポンス
-
-**基本構造**:
-
-```json
-{
-  "data": { /* リソースデータ */ },
-  "meta": { /* メタデータ（ページネーション情報など） */ }
-}
-```
-
-**単一リソース取得の例**:
-
-```json
-{
-  "data": {
-    "id": 1,
-    "email": "user@example.com",
-    "name": "User Name",
-    "created_at": "2024-01-01T00:00:00Z"
-  }
-}
-```
-
-**リスト取得の例**:
-
-```json
-{
-  "data": [
-    { "id": 1, "name": "User 1" },
-    { "id": 2, "name": "User 2" }
-  ],
-  "meta": {
-    "total": 100,
-    "limit": 20,
-    "offset": 0
-  }
-}
-```
-
-### エラーレスポンス
-
-**基本構造**:
-
-```json
-{
-  "error": {
-    "code": "ERROR_CODE",
-    "message": "Human-readable error message"
-  }
-}
-```
-
-**バリデーションエラーの例**:
-
-```json
-{
-  "error": {
-    "code": "VALIDATION_ERROR",
-    "message": "Validation failed",
-    "details": [
-      { "field": "email", "message": "Invalid email format" }
-    ]
-  }
-}
-```
-
-### 主要なHTTPステータスコード
-
-| ステータスコード | 説明 | 使用場面 |
-|----------------|------|---------|
-| **200 OK** | 成功 | GET, PUT, PATCH, DELETE の成功 |
-| **201 Created** | リソース作成成功 | POST でのリソース作成成功 |
-| **204 No Content** | 成功（レスポンスボディなし） | DELETE 成功時など |
-| **400 Bad Request** | 不正なリクエスト | バリデーションエラー |
-| **401 Unauthorized** | 認証エラー | トークン不正・期限切れ |
-| **403 Forbidden** | 権限不足 | 認証済みだが権限不足 |
-| **404 Not Found** | リソースが存在しない | 指定したIDのリソースが見つからない |
-| **409 Conflict** | リソースの競合 | 既に存在するメールアドレスなど |
-| **429 Too Many Requests** | レート制限超過 | リクエスト数が上限を超えた |
-| **500 Internal Server Error** | サーバーエラー | サーバー内部エラー |
+# API仕様
+
+<!--
+何を書くか: 認証方式、エンドポイント一覧、共通レスポンス形式
+
+目的:
+  - フロントエンド・バックエンド間の基本契約を明確化
+  - API設計の全体像を把握
+  - 開発者間の認識統一
+
+重要性:
+  - 高レベルなAPI設計の記録
+  - 詳細な仕様（リクエスト/レスポンスのスキーマ）はOpenAPI/Swaggerやコードで管理
+
+記載のポイント:
+  - 認証方式の基本情報
+  - エンドポイント一覧（メソッド、パス、説明、認証要否）
+  - 共通のレスポンス形式（成功/エラー）
+
+更新頻度:
+  - プロジェクト初期に基本設計を作成
+  - エンドポイント追加・削除時に更新
+
+**詳細な実装仕様の管理**:
+  - リクエスト/レスポンスの詳細なJSONスキーマ → OpenAPI/Swagger
+  - バリデーションルール → コード（バリデーター）
+  - エラーコード詳細 → コード（エラーハンドラー）
+  - ページネーション、レート制限 → コードと運用ドキュメント
+-->
+
+---
+
+## 認証・認可
+
+<!--
+API のセキュリティ方式の基本情報
+
+よくある認証方式:
+  - JWT (JSON Web Token): ステートレス、マイクロサービス向き
+  - OAuth 2.0: サードパーティ認証、権限委譲
+  - API Key: シンプル、内部API向き
+  - Session Cookie: ステートフル、Webアプリ向き
+
+記載すべき内容:
+  - 認証方法（JWT, OAuth 2.0, API Key など）
+  - トークンの基本的な有効期限
+  - 認証フローの概要
+  - 権限スコープの種類
+-->
+
+| 項目 | 内容 |
+|------|------|
+| **認証方法** | <!-- 例: JWT Bearer Token --> |
+| **トークン有効期限** | <!-- 例: アクセストークン: 1時間、リフレッシュトークン: 30日 --> |
+| **トークン形式** | <!-- 例: Authorization: Bearer {token} --> |
+| **権限スコープ** | <!-- 例: read, write, admin --> |
+
+**認証フロー概要**:
+<!-- 例:
+1. POST /auth/login でログイン
+2. アクセストークンとリフレッシュトークンを取得
+3. 以降のリクエストで Authorization: Bearer {token} ヘッダーに含める
+4. トークン期限切れ時は POST /auth/refresh でリフレッシュ
+-->
+
+---
+
+## エンドポイント一覧
+
+<!--
+すべてのAPIエンドポイントを一覧化
+
+テーブル構成:
+【メソッド】
+  - HTTP メソッド（GET, POST, PUT, PATCH, DELETE）
+  - RESTful な使い分けを意識
+
+【パス】
+  - エンドポイントの URL パス
+  - パスパラメータは {id}, {userId} のように記載
+  - 例: /api/users/{id}, /api/orders/{orderId}/items
+
+【説明】
+  - エンドポイントの目的を1行で記載
+  - 例: 「ユーザー一覧を取得」「注文を作成」
+
+【認証】
+  - 必要/不要/オプション
+  - 必要な権限スコープがあれば記載（例: admin, write）
+
+【ステータス】
+  - 実装済み/未実装/非推奨（Deprecated）
+  - バージョニングで廃止予定のエンドポイントを記録
+
+記載のベストプラクティス:
+  - リソースごとにグループ化（ユーザー関連、注文関連など）
+  - CRUD 操作を揃える（GET一覧, GET詳細, POST作成, PUT更新, DELETE削除）
+  - ページネーションやフィルタリングのパラメータを記載
+  - 非推奨（Deprecated）エンドポイントも記録し、移行先を明記
+-->
+
+### ユーザー管理
+
+| メソッド | パス | 説明 | 認証 | ステータス |
+|---------|------|------|------|-----------|
+| <!-- GET --> | <!-- /api/users --> | <!-- ユーザー一覧取得 --> | <!-- 必要（read） --> | <!-- 実装済み --> |
+| <!-- GET --> | <!-- /api/users/{id} --> | <!-- ユーザー詳細取得 --> | <!-- 必要（read） --> | <!-- 実装済み --> |
+| <!-- POST --> | <!-- /api/users --> | <!-- ユーザー作成 --> | <!-- 必要（write） --> | <!-- 実装済み --> |
+| <!-- PUT --> | <!-- /api/users/{id} --> | <!-- ユーザー更新（完全置換） --> | <!-- 必要（write） --> | <!-- 実装済み --> |
+| <!-- PATCH --> | <!-- /api/users/{id} --> | <!-- ユーザー更新（部分更新） --> | <!-- 必要（write） --> | <!-- 実装済み --> |
+| <!-- DELETE --> | <!-- /api/users/{id} --> | <!-- ユーザー削除 --> | <!-- 必要（admin） --> | <!-- 実装済み --> |
+
+### 注文管理
+
+| メソッド | パス | 説明 | 認証 | ステータス |
+|---------|------|------|------|-----------|
+| <!-- GET --> | <!-- /api/orders --> | <!-- 注文一覧取得 --> | <!-- 必要（read） --> | <!-- 実装済み --> |
+| <!-- GET --> | <!-- /api/orders/{id} --> | <!-- 注文詳細取得 --> | <!-- 必要（read） --> | <!-- 実装済み --> |
+| <!-- POST --> | <!-- /api/orders --> | <!-- 注文作成 --> | <!-- 必要（write） --> | <!-- 実装済み --> |
+| <!-- POST --> | <!-- /api/orders/{id}/cancel --> | <!-- 注文キャンセル --> | <!-- 必要（write） --> | <!-- 実装済み --> |
+
+### 認証
+
+| メソッド | パス | 説明 | 認証 | ステータス |
+|---------|------|------|------|-----------|
+| <!-- POST --> | <!-- /api/auth/login --> | <!-- ログイン --> | <!-- 不要 --> | <!-- 実装済み --> |
+| <!-- POST --> | <!-- /api/auth/logout --> | <!-- ログアウト --> | <!-- 必要 --> | <!-- 実装済み --> |
+| <!-- POST --> | <!-- /api/auth/refresh --> | <!-- トークンリフレッシュ --> | <!-- 不要（リフレッシュトークン必要） --> | <!-- 実装済み --> |
+
+---
+
+## 共通レスポンス形式
+
+<!--
+全エンドポイントで統一するレスポンス形式
+
+記載すべき内容:
+  - 成功時のレスポンス構造
+  - エラー時のレスポンス構造
+  - 主要なHTTPステータスコード
+
+詳細な仕様（リクエスト/レスポンスの詳細なJSONスキーマ、
+バリデーションルール、エラーコード定義）は OpenAPI/Swagger で管理します。
+-->
+
+### 成功レスポンス
+
+**基本構造**:
+
+```json
+{
+  "data": { /* リソースデータ */ },
+  "meta": { /* メタデータ（ページネーション情報など） */ }
+}
+```
+
+**単一リソース取得の例**:
+
+```json
+{
+  "data": {
+    "id": 1,
+    "email": "user@example.com",
+    "name": "User Name",
+    "created_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+**リスト取得の例**:
+
+```json
+{
+  "data": [
+    { "id": 1, "name": "User 1" },
+    { "id": 2, "name": "User 2" }
+  ],
+  "meta": {
+    "total": 100,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### エラーレスポンス
+
+**基本構造**:
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable error message"
+  }
+}
+```
+
+**バリデーションエラーの例**:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Validation failed",
+    "details": [
+      { "field": "email", "message": "Invalid email format" }
+    ]
+  }
+}
+```
+
+### 主要なHTTPステータスコード
+
+| ステータスコード | 説明 | 使用場面 |
+|----------------|------|---------|
+| **200 OK** | 成功 | GET, PUT, PATCH, DELETE の成功 |
+| **201 Created** | リソース作成成功 | POST でのリソース作成成功 |
+| **204 No Content** | 成功（レスポンスボディなし） | DELETE 成功時など |
+| **400 Bad Request** | 不正なリクエスト | バリデーションエラー |
+| **401 Unauthorized** | 認証エラー | トークン不正・期限切れ |
+| **403 Forbidden** | 権限不足 | 認証済みだが権限不足 |
+| **404 Not Found** | リソースが存在しない | 指定したIDのリソースが見つからない |
+| **409 Conflict** | リソースの競合 | 既に存在するメールアドレスなど |
+| **429 Too Many Requests** | レート制限超過 | リクエスト数が上限を超えた |
+| **500 Internal Server Error** | サーバーエラー | サーバー内部エラー |