yodogawa 1.0.0

package/.windsurf/templates/project/04-design/04-data-model.md

@@ -0,0 +1,211 @@
+# データモデル（ERD）
+
+<!--
+何を書くか: データベース構造、エンティティ、属性、リレーションシップ、制約
+
+目的:
+  - データ構造の全体像を可視化
+  - テーブル設計の一貫性を保つ
+  - 開発者間の認識統一
+  - データの整合性ルールを明確化
+  - マイグレーション計画の基盤
+
+重要性:
+  - データベース設計の記録（ADR: Architecture Decision Record の一部）
+  - 正規化・非正規化の判断根拠を記録
+  - パフォーマンス最適化の指針
+  - データ整合性の担保
+  - 将来の拡張性を考慮した設計
+
+記載のポイント:
+  - Mermaid ERD で視覚的に表現
+  - エンティティごとに責務を明確化
+  - リレーションシップと多重度を正確に記載
+  - 制約（NOT NULL, UNIQUE, CHECK）を明記
+  - インデックス戦略を記録
+  - データ型の選択理由を記載
+
+更新頻度:
+  - プロジェクト初期にドメインモデルから作成
+  - テーブル追加・変更時に更新
+  - マイグレーション実行時に更新
+  - パフォーマンスチューニング時に見直し
+-->
+
+---
+
+## エンティティ一覧
+
+<!--
+各エンティティの責務と主要属性を明記
+
+まずエンティティの一覧を把握してから、ERDで視覚化する流れが自然です。
+
+テーブル構成:
+【エンティティ名】
+  - テーブル名（物理名）
+  - 複数形推奨（例: users, orders, products）
+  - スネークケース推奨（例: order_items, user_roles）
+
+【説明】
+  - そのエンティティが表現するビジネス概念
+  - 責務と役割
+  - ドメインモデルとの対応
+
+【主要属性】
+  - 重要なカラムをリスト化
+  - すべてを列挙する必要はない（詳細は ERD 参照）
+  - ビジネスキーとなる属性を優先的に記載
+
+【備考】
+  - 正規化・非正規化の判断理由
+  - パーティショニング戦略
+  - 削除方法（論理削除 or 物理削除）
+  - 監査要件（作成日時、更新日時、削除日時）
+
+記載のベストプラクティス:
+  - エンティティの分類を明記（コア、参照、関連、履歴）
+  - ソフトデリート（論理削除）の有無を記載
+  - タイムスタンプ（created_at, updated_at）の有無
+  - ドメインモデルの Aggregate との対応を記載
+
+よくあるエンティティの分類:
+  - コアエンティティ: ビジネスの中心（User, Order, Product）
+  - 参照エンティティ: マスタデータ（Category, Status, Country）
+  - 関連エンティティ: 多対多の中間テーブル（UserRole, OrderItem）
+  - 履歴エンティティ: 監査ログ、変更履歴（AuditLog, OrderHistory）
+-->
+
+| エンティティ名 | 説明 | 主要属性 | 備考 |
+|---------------|------|----------|------|
+| <!-- 例: users --> | <!-- 例: ユーザー情報を管理。システムにアクセスする全てのユーザーを表す --> | <!-- 例: id, email, name, password_hash --> | <!-- 例: 論理削除（deleted_at）、email は一意制約 --> |
+| <!-- 例: orders --> | <!-- 例: 注文情報を管理。ユーザーが商品を購入する取引単位 --> | <!-- 例: id, user_id, status, total_amount --> | <!-- 例: status は enum 型または CHECK 制約、物理削除不可（履歴保持） --> |
+| <!-- 例: products --> | <!-- 例: 商品マスタ。販売可能な商品の情報を管理 --> | <!-- 例: id, name, price, stock --> | <!-- 例: 論理削除（is_active）、在庫数は別テーブルでも可 --> |
+| <!-- 例: order_items --> | <!-- 例: 注文明細。注文に含まれる商品と数量を管理 --> | <!-- 例: id, order_id, product_id, quantity, unit_price --> | <!-- 例: 価格変更の影響を避けるため unit_price を保持 --> |
+
+---
+
+## リレーションシップ
+
+<!--
+エンティティ間の関係性を明記
+
+エンティティ一覧で各テーブルの責務を把握した後、このセクションでテーブル間の関係性を理解します。
+その後、ERDで視覚的に確認する流れが自然です。
+
+テーブル構成:
+【エンティティA / エンティティB】
+  - リレーションシップの両端のエンティティ名
+
+【関係性】
+  - 多重度を記載
+  - 1:1（一対一）
+  - 1:N（一対多）
+  - N:M（多対多） → 通常は中間テーブルで 1:N + N:1 に分解
+
+【外部キー】
+  - FK として使用されるカラム名
+  - 命名規則: {参照先テーブル名}_id（例: user_id, product_id）
+
+【制約】
+  - ON DELETE の動作（CASCADE, SET NULL, RESTRICT）
+  - ON UPDATE の動作
+  - NOT NULL 制約の有無
+
+【備考】
+  - ビジネスルールの説明
+  - リレーションシップの意味
+  - インデックスの有無
+
+記載のベストプラクティス:
+  - 親子関係を明確に
+  - CASCADE 削除は慎重に（意図しないデータ削除を防ぐ）
+  - 循環参照に注意
+  - パフォーマンスを考慮した FK インデックス
+-->
+
+| エンティティA | エンティティB | 関係性 | 外部キー | 制約 | 備考 |
+|--------------|--------------|--------|----------|------|------|
+| <!-- 例: users --> | <!-- 例: orders --> | <!-- 例: 1:N --> | <!-- 例: user_id --> | <!-- 例: ON DELETE RESTRICT --> | <!-- 例: 1人のユーザーが複数の注文を持つ。ユーザー削除時は注文が残るため RESTRICT --> |
+| <!-- 例: orders --> | <!-- 例: order_items --> | <!-- 例: 1:N --> | <!-- 例: order_id --> | <!-- 例: ON DELETE CASCADE --> | <!-- 例: 1つの注文が複数の明細を持つ。注文削除時は明細も削除 --> |
+| <!-- 例: products --> | <!-- 例: order_items --> | <!-- 例: 1:N --> | <!-- 例: product_id --> | <!-- 例: ON DELETE RESTRICT --> | <!-- 例: 商品削除時は注文明細が残るため削除不可 --> |
+
+---
+
+## ERD（Entity Relationship Diagram）
+
+<!--
+Mermaid を使用してデータベース構造を可視化
+
+エンティティ一覧とリレーションシップで理解した内容を、このERDで視覚的に確認します。
+
+記載のベストプラクティス:
+  1. すべてのエンティティとリレーションシップを記載
+  2. 主キー（PK）、外部キー（FK）を明記
+  3. データ型を記載（int, string, datetime, boolean など）
+  4. リレーションシップの多重度を正確に表現（1:1, 1:N, N:M）
+  5. 複雑な場合は複数の図に分割（コアドメイン、サブドメインごと）
+
+Mermaid ERD の記法:
+  - エンティティ名 { 属性名 データ型 制約 }
+  - リレーションシップ記法:
+    - ||--|| : 1対1（必須-必須）
+    - ||--o| : 1対0..1（必須-オプション）
+    - ||--o{ : 1対多（必須-0以上）
+    - }o--o{ : 多対多
+  - PK: Primary Key（主キー）
+  - FK: Foreign Key（外部キー）
+  - UK: Unique Key（一意制約）
+-->
+
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : "places"
+    USER {
+        bigint id PK "ユーザーID"
+        string email UK "メールアドレス（一意）"
+        string name "氏名"
+        string password_hash "パスワードハッシュ"
+        datetime created_at "作成日時"
+        datetime updated_at "更新日時"
+    }
+
+    ORDER ||--|{ ORDER_ITEM : "contains"
+    ORDER {
+        bigint id PK "注文ID"
+        bigint user_id FK "ユーザーID"
+        string status "ステータス: pending, confirmed, shipped, delivered, cancelled"
+        decimal total_amount "合計金額"
+        datetime created_at "作成日時"
+        datetime updated_at "更新日時"
+    }
+
+    PRODUCT ||--o{ ORDER_ITEM : "is ordered in"
+    PRODUCT {
+        bigint id PK "商品ID"
+        string name "商品名"
+        text description "商品説明"
+        decimal price "価格"
+        int stock "在庫数"
+        boolean is_active "有効フラグ"
+        datetime created_at "作成日時"
+        datetime updated_at "更新日時"
+    }
+
+    ORDER_ITEM {
+        bigint id PK "注文明細ID"
+        bigint order_id FK "注文ID"
+        bigint product_id FK "商品ID"
+        int quantity "数量"
+        decimal unit_price "単価（注文時の価格）"
+        datetime created_at "作成日時"
+    }
+```
+
+**補足**:
+<!-- 例:
+- USER と ORDER は 1:N の関係（1人のユーザーが複数の注文を持つ）
+- ORDER と ORDER_ITEM は 1:N の関係（1つの注文が複数の明細を持つ）
+- PRODUCT と ORDER_ITEM は 1:N の関係（1つの商品が複数の注文明細に含まれる）
+- unit_price を ORDER_ITEM に持たせることで、価格変更の影響を回避
+-->

package/.windsurf/templates/project/04-design/05-api-spec.md

@@ -0,0 +1,221 @@
+# 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** | サーバーエラー | サーバー内部エラー |

package/.windsurf/templates/project/04-design/06-architecture.md

@@ -0,0 +1,183 @@
+# アーキテクチャ設計
+
+<!--
+何を書くか: システム全体の構造、採用アーキテクチャパターン、重要な設計決定（ADR）
+
+目的:
+  - システム全体の見通しを向上
+  - コンポーネント間の関係を明確化
+  - アーキテクチャ決定の記録と共有
+
+重要性:
+  - 高レベルなアーキテクチャの全体像を把握
+  - 詳細な実装仕様（スペック、パフォーマンス数値）はコードとインフラコードで管理
+
+記載のポイント:
+  - システムアーキテクチャ図で視覚的に表現
+  - 採用したアーキテクチャパターンとその理由
+  - 重要な技術的決定事項（ADR）
+
+更新頻度:
+  - プロジェクト初期にアーキテクチャ設計を作成
+  - アーキテクチャ変更時に更新
+  - 重要な技術的決定時に ADR を追加
+-->
+
+---
+
+## システムアーキテクチャ図
+
+<!--
+Mermaid を使用してシステム全体の構造を可視化
+
+記載のベストプラクティス:
+  1. 主要なコンポーネントとその関係を記載
+  2. データフローを矢印で表現
+  3. 外部システムとの連携も記載
+  4. レイヤーごとに色分けまたはグループ化
+  5. 複雑な場合は複数の図に分割（全体図、詳細図）
+
+よくあるコンポーネント:
+  - クライアント層: Webブラウザ、モバイルアプリ
+  - プレゼンテーション層: フロントエンド（React, Vue）
+  - API層: REST API, GraphQL
+  - ビジネスロジック層: サービス、ドメインモデル
+  - データアクセス層: ORM、リポジトリ
+  - データストア層: RDBMS, NoSQL, キャッシュ
+  - 外部サービス: 決済API、メール送信、認証サービス
+  - インフラ: ロードバランサー、CDN、キューシステム
+
+Mermaid の記法:
+  - graph TD: 上から下へのフロー
+  - graph LR: 左から右へのフロー
+  - subgraph でグループ化
+  - []: 四角、(): 丸角四角、{}: ひし形、[()]: スタジアム型、[[]]: サブルーチン、[()]: 円柱
+-->
+
+```mermaid
+graph TB
+    subgraph "クライアント層"
+        Web[Webブラウザ]
+        Mobile[モバイルアプリ]
+    end
+
+    subgraph "CDN層"
+        CDN[CloudFront CDN]
+    end
+
+    subgraph "ロードバランシング層"
+        LB[Application Load Balancer]
+    end
+
+    subgraph "アプリケーション層"
+        API1[APIサーバー 1<br/>Node.js + Express]
+        API2[APIサーバー 2<br/>Node.js + Express]
+    end
+
+    subgraph "キャッシュ層"
+        Cache[(Redis)]
+    end
+
+    subgraph "データ層"
+        DB[(PostgreSQL<br/>Primary)]
+        DBRead[(PostgreSQL<br/>Read Replica)]
+    end
+
+    subgraph "外部サービス"
+        Auth[認証サービス<br/>Auth0]
+        Payment[決済サービス<br/>Stripe]
+        Email[メール送信<br/>SendGrid]
+    end
+
+    subgraph "ストレージ"
+        S3[Object Storage<br/>Amazon S3]
+    end
+
+    Web --> CDN
+    Mobile --> CDN
+    CDN --> LB
+    LB --> API1
+    LB --> API2
+
+    API1 --> Cache
+    API2 --> Cache
+    API1 --> DB
+    API2 --> DB
+    API1 --> DBRead
+    API2 --> DBRead
+
+    API1 --> Auth
+    API2 --> Auth
+    API1 --> Payment
+    API2 --> Payment
+    API1 --> Email
+    API2 --> Email
+
+    API1 --> S3
+    API2 --> S3
+```
+
+**補足**:
+<!-- 例:
+- クライアントからのリクエストは CDN を経由してキャッシュ可能な静的コンテンツを配信
+- API層は水平スケール可能（オートスケーリング）
+- データベースは Primary/Replica 構成で読み取り負荷を分散
+- Redis でセッション管理とキャッシュを実現
+- 外部サービスとの連携は API Gateway 経由で統一
+-->
+
+---
+
+## 採用アーキテクチャパターン
+
+<!--
+採用したアーキテクチャパターンとその理由を簡潔に記載
+
+よくあるアーキテクチャパターン:
+  - Layered Architecture: プレゼンテーション層 → ビジネスロジック層 → データアクセス層
+  - Clean Architecture: ドメイン中心、依存性逆転
+  - Microservices: サービスごとに独立したデプロイ
+  - Event-Driven: 非同期処理、疎結合
+
+記載すべき内容:
+  - 採用パターン名
+  - 選定理由（なぜこのパターンが適しているか）
+  - 適用範囲
+-->
+
+| 項目 | 内容 |
+|------|------|
+| **採用パターン** | <!-- 例: Layered Architecture（レイヤードアーキテクチャ） --> |
+| **選定理由** | <!-- 例: チームサイズが小規模なため、シンプルで運用コストの低いアーキテクチャを選択 --> |
+| **適用範囲** | <!-- 例: バックエンド全体 --> |
+
+---
+
+## ADR（Architecture Decision Record）
+
+<!--
+重要なアーキテクチャ決定を記録
+
+ADR とは:
+  - アーキテクチャに関する重要な決定を記録
+  - 「なぜその決定をしたか」の背景を残す
+  - 将来的な見直しや移行の判断材料
+
+記載すべき内容:
+  - 決定事項: 何を決めたか
+  - 背景: なぜその決定が必要だったか
+  - 代替案: 他の選択肢
+  - 影響: その決定による影響
+  - 決定日: いつ決定したか
+
+よくある決定事項:
+  - データベースの選択
+  - キャッシュ戦略
+  - 認証方式
+  - デプロイ戦略
+-->
+
+| 決定事項 | 背景 | 代替案 | 影響 | 決定日 |
+|---------|------|--------|------|--------|
+| <!-- 例: PostgreSQL を採用 --> | <!-- 例: ACID準拠のトランザクションが必要 --> | <!-- 例: MySQL, MongoDB --> | <!-- 例: データ整合性が高い --> | <!-- 例: 2024-01-05 --> |
+| <!-- 例: Redis をセッション管理に使用 --> | <!-- 例: ステートレスな API サーバーを実現 --> | <!-- 例: DB保存, JWT のみ --> | <!-- 例: セッション管理が高速 --> | <!-- 例: 2024-01-10 --> |