492 lines
19 KiB
Markdown
492 lines
19 KiB
Markdown
# ドキュメント例集（日本語版）
|
||
|
||
## requirements.md の例 - ECショッピングカート
|
||
|
||
```markdown
|
||
# 要件定義
|
||
|
||
## 概要
|
||
本仕様は、ユーザーが商品を追加し、数量を管理し、チェックアウトに進むことができるECサイトのショッピングカート機能の要件を定義します。
|
||
|
||
## ユーザーストーリー
|
||
|
||
### ストーリー1: 商品をカートに追加
|
||
**私は** 顧客として
|
||
**商品をショッピングカートに追加したい**
|
||
**なぜなら** 一度の取引で複数の商品を購入できるから
|
||
|
||
#### 受入基準（EARS記法）
|
||
|
||
- **REQ-001**: ユーザーが「カートに追加」ボタンをクリックした時、システムは500ms以内に商品をショッピングカートに追加しなければならない
|
||
- **REQ-002**: 商品がカートに追加された時、システムは3秒間確認メッセージを表示しなければならない
|
||
- **REQ-003**: もし商品が既にカートに存在する場合、システムは重複エントリを追加する代わりに数量を増やさなければならない
|
||
- **REQ-004**: 商品の在庫がゼロの場合、システムは「カートに追加」ボタンを無効化し、「在庫切れ」と表示しなければならない
|
||
|
||
### ストーリー2: カート内容の管理
|
||
**私は** 顧客として
|
||
**カート内容を表示し、変更したい**
|
||
**なぜなら** チェックアウト前に購入内容を調整できるから
|
||
|
||
#### 受入基準（EARS記法）
|
||
|
||
- **REQ-005**: システムは商品名、価格、数量、小計を含むすべてのカート商品を表示しなければならない
|
||
- **REQ-006**: ユーザーが数量を変更した時、システムは200ms以内にカート合計を更新しなければならない
|
||
- **REQ-007**: ユーザーが「削除」をクリックした時、システムは確認後に商品をカートから削除しなければならない
|
||
- **REQ-008**: もしカートが空の場合、システムは「カートは空です」と買い物継続へのリンクを表示しなければならない
|
||
- **REQ-009**: カートに商品が含まれている間、システムは税金と配送見積もりを含む合計価格を表示しなければならない
|
||
|
||
### ストーリー3: カート状態の永続化
|
||
**私は** 顧客として
|
||
**カートを保存してもらいたい**
|
||
**なぜなら** 後で戻って購入を完了できるから
|
||
|
||
#### 受入基準（EARS記法）
|
||
|
||
- **REQ-010**: ログインユーザーがカートに商品を追加した時、システムはカートをデータベースに永続化しなければならない
|
||
- **REQ-011**: ログインユーザーがブラウザを閉じた後に戻った時、システムは以前のカートを復元しなければならない
|
||
- **REQ-012**: ユーザーがログインしていない場合、システムはカートをローカルストレージに30日間保存しなければならない
|
||
- **REQ-013**: 匿名ユーザーがログインした時、システムはローカルカートを既存の保存済みカートとマージしなければならない
|
||
|
||
## 非機能要件
|
||
|
||
### パフォーマンス
|
||
- **NFR-001**: システムは4G接続でカートページを2秒以内に読み込まなければならない
|
||
- **NFR-002**: システムは最大10,000人のユーザーの同時カート操作を処理できなければならない
|
||
|
||
### セキュリティ
|
||
- **NFR-003**: システムは不正操作を防ぐためすべての価格情報をサーバーサイドで検証しなければならない
|
||
- **NFR-004**: システムはカート関連のすべての通信にHTTPSを使用しなければならない
|
||
|
||
### ユーザビリティ
|
||
- **NFR-005**: システムはWCAG 2.1レベルAAの基準に従ってアクセシブルでなければならない
|
||
- **NFR-006**: システムは320pxからの画面幅のモバイルデバイスをサポートしなければならない
|
||
|
||
## 依存関係
|
||
- 商品の在庫と価格情報のための商品カタログサービス
|
||
- ログインユーザーのカート永続化のためのユーザー認証サービス
|
||
- チェックアウト処理のための決済ゲートウェイ
|
||
|
||
## スコープ外
|
||
- ウィッシュリスト機能
|
||
- あとで買う機能
|
||
- カート共有機能
|
||
- プロモーションコードの適用（チェックアウトサービスで処理）
|
||
```
|
||
|
||
## design.md の例 - タスク管理API
|
||
|
||
```markdown
|
||
# 設計
|
||
|
||
## アーキテクチャ概要
|
||
タスク管理APIは、タスク管理、ユーザー認証、通知サービス間の関心事を分離したマイクロサービスアプローチによるRESTfulアーキテクチャパターンに従います。
|
||
|
||
\`\`\`mermaid
|
||
graph TD
|
||
Client[クライアントアプリ]
|
||
Gateway[APIゲートウェイ]
|
||
Auth[認証サービス]
|
||
Task[タスクサービス]
|
||
Notification[通知サービス]
|
||
Cache[Redisキャッシュ]
|
||
DB[(PostgreSQL)]
|
||
Queue[メッセージキュー]
|
||
|
||
Client --> Gateway
|
||
Gateway --> Auth
|
||
Gateway --> Task
|
||
Task --> Cache
|
||
Task --> DB
|
||
Task --> Queue
|
||
Queue --> Notification
|
||
\`\`\`
|
||
|
||
## コンポーネント
|
||
|
||
### コンポーネント1: APIゲートウェイ
|
||
**目的**: リクエストルーティング、認証処理、レート制限
|
||
**責務**:
|
||
- 適切なマイクロサービスへのリクエストルーティング
|
||
- JWTトークン検証
|
||
- レート制限（ユーザーあたり100リクエスト/分）
|
||
- リクエスト/レスポンスログ
|
||
|
||
**インターフェース**:
|
||
- REST APIエンドポイント（パブリック向け）
|
||
- gRPCによる内部サービス通信
|
||
|
||
### コンポーネント2: タスクサービス
|
||
**目的**: タスク管理のコアビジネスロジック
|
||
**責務**:
|
||
- タスクのCRUD操作
|
||
- タスク割り当てとステータス管理
|
||
- 期限追跡とリマインダー
|
||
- タスク検索とフィルタリング
|
||
|
||
**インターフェース**:
|
||
- POST /api/tasks - タスク作成
|
||
- GET /api/tasks - タスク一覧
|
||
- PUT /api/tasks/{id} - タスク更新
|
||
- DELETE /api/tasks/{id} - タスク削除
|
||
|
||
### コンポーネント3: 通知サービス
|
||
**目的**: すべての通知配信を処理
|
||
**責務**:
|
||
- タスク割り当てのメール通知
|
||
- 期限リマインダー
|
||
- ステータス変更通知
|
||
- 通知設定管理
|
||
|
||
## データフロー
|
||
|
||
### シーケンス: 割り当て付きタスク作成
|
||
\`\`\`mermaid
|
||
sequenceDiagram
|
||
participant Client as クライアント
|
||
participant Gateway as ゲートウェイ
|
||
participant Auth as 認証
|
||
participant TaskService as タスクサービス
|
||
participant DB as データベース
|
||
participant Queue as キュー
|
||
participant NotificationService as 通知サービス
|
||
|
||
Client->>Gateway: POST /api/tasks
|
||
Gateway->>Auth: JWT検証
|
||
Auth-->>Gateway: ユーザー検証済み
|
||
Gateway->>TaskService: タスク作成リクエスト
|
||
TaskService->>DB: タスク挿入
|
||
DB-->>TaskService: タスク作成完了
|
||
TaskService->>Queue: 割り当てイベント発行
|
||
TaskService-->>Gateway: タスクレスポンス
|
||
Gateway-->>Client: 201 Created
|
||
Queue->>NotificationService: 割り当てイベント
|
||
NotificationService->>NotificationService: メール送信
|
||
\`\`\`
|
||
|
||
## API設計
|
||
|
||
### エンドポイント: POST /api/tasks
|
||
**メソッド**: POST
|
||
**目的**: 新しいタスクを作成
|
||
**リクエスト**:
|
||
\`\`\`json
|
||
{
|
||
"title": "プロジェクト提案書の完成",
|
||
"description": "第4四半期プロジェクト提案書の草稿作成",
|
||
"assignee_id": "user-123",
|
||
"due_date": "2024-10-15T17:00:00Z",
|
||
"priority": "high",
|
||
"tags": ["project", "q4", "proposal"]
|
||
}
|
||
\`\`\`
|
||
**レスポンス**:
|
||
\`\`\`json
|
||
{
|
||
"id": "task-456",
|
||
"title": "プロジェクト提案書の完成",
|
||
"status": "pending",
|
||
"created_at": "2024-10-01T10:30:00Z",
|
||
"created_by": "user-789"
|
||
}
|
||
\`\`\`
|
||
|
||
## データベーススキーマ
|
||
|
||
### テーブル: tasks
|
||
| カラム | 型 | 制約 | 説明 |
|
||
|--------|------|-------------|-------------|
|
||
| id | UUID | PRIMARY KEY | タスク識別子 |
|
||
| title | VARCHAR(255) | NOT NULL | タスクタイトル |
|
||
| description | TEXT | | タスク詳細説明 |
|
||
| status | ENUM | NOT NULL | pending, in_progress, completed, cancelled |
|
||
| assignee_id | UUID | FOREIGN KEY | usersテーブルへの参照 |
|
||
| due_date | TIMESTAMP | | タスク期限 |
|
||
| priority | ENUM | DEFAULT 'medium' | low, medium, high, urgent |
|
||
| created_at | TIMESTAMP | NOT NULL | 作成タイムスタンプ |
|
||
| updated_at | TIMESTAMP | NOT NULL | 最終更新タイムスタンプ |
|
||
|
||
### テーブル: task_history
|
||
| カラム | 型 | 制約 | 説明 |
|
||
|--------|------|-------------|-------------|
|
||
| id | UUID | PRIMARY KEY | 履歴エントリ識別子 |
|
||
| task_id | UUID | FOREIGN KEY, NOT NULL | tasksテーブルへの参照 |
|
||
| user_id | UUID | FOREIGN KEY, NOT NULL | 変更を行ったユーザー |
|
||
| action | VARCHAR(50) | NOT NULL | 変更の種類 |
|
||
| old_value | JSONB | | 以前の状態 |
|
||
| new_value | JSONB | | 新しい状態 |
|
||
| created_at | TIMESTAMP | NOT NULL | 変更発生時刻 |
|
||
|
||
## 技術的決定事項
|
||
|
||
### 決定1: データベースの選択
|
||
**検討した選択肢**:
|
||
1. PostgreSQL - JSONB対応のリレーショナルデータベース
|
||
2. MongoDB - 柔軟なスキーマを持つドキュメントデータベース
|
||
|
||
**決定**: PostgreSQL
|
||
**根拠**: 強い一貫性要件、エンティティ間の複雑な関係、ACIDトランザクションの必要性、チームのPostgreSQL専門知識
|
||
|
||
### 決定2: キャッシング戦略
|
||
**検討した選択肢**:
|
||
1. Redis - 永続化オプション付きインメモリキャッシュ
|
||
2. Memcached - シンプルなインメモリキャッシュ
|
||
|
||
**決定**: Redis
|
||
**根拠**: キャッシュ永続化の必要性、リアルタイム更新のためのpub/sub機能、複雑なデータ構造のサポート
|
||
|
||
## セキュリティ考慮事項
|
||
- ヘルスチェック以外のすべてのエンドポイントでJWT認証が必要
|
||
- レート制限による悪用防止（ユーザーあたり100リク/分、書き込み操作は10リク/分）
|
||
- すべてのユーザー提供データの入力検証
|
||
- パラメータ化クエリによるSQLインジェクション防止
|
||
- 出力エンコーディングによるXSS防止
|
||
|
||
## パフォーマンス考慮事項
|
||
- 頻繁にクエリされるカラムのデータベースインデックス（assignee_id、status、due_date）
|
||
- 頻繁にアクセスされるタスクのRedisキャッシュ（TTL: 5分）
|
||
- リストエンドポイントのページネーション（デフォルト: 20件、最大: 100件）
|
||
- メッセージキューによる通知の非同期処理
|
||
- データベース接続のコネクションプーリング（プールサイズ: 20）
|
||
|
||
## エラー処理
|
||
- エラーコード付き構造化エラーレスポンス
|
||
- キャッシュ利用不可時のグレースフルデグレデーション
|
||
- 外部サービス呼び出しのサーキットブレーカー
|
||
- 一時的な障害に対する指数バックオフ付き再試行ロジック
|
||
- デバッグ用の包括的なログ記録
|
||
```
|
||
|
||
## tasks.md の例 - ユーザー認証機能
|
||
|
||
```markdown
|
||
# タスク
|
||
|
||
## 実装計画
|
||
|
||
### フェーズ1: 基盤構築
|
||
*推定期間: 3日*
|
||
|
||
#### タスク1.1: データベーススキーマ設定
|
||
**説明**: ユーザー、セッション、パスワードリセットトークンのデータベーステーブルを作成
|
||
**受入基準**:
|
||
- [ ] email、password_hash、created_at、updated_atを持つusersテーブル作成
|
||
- [ ] token、user_id、expires_atを持つsessionsテーブル作成
|
||
- [ ] パスワードリセットトークンテーブル作成
|
||
- [ ] データベースマイグレーションは可逆的
|
||
- [ ] パフォーマンス向上のためのインデックス追加
|
||
|
||
**依存関係**: なし
|
||
**推定工数**: 4時間
|
||
**ステータス**: `TODO`
|
||
|
||
#### タスク1.2: 環境設定
|
||
**説明**: 環境変数と設定管理のセットアップ
|
||
**受入基準**:
|
||
- [ ] JWT秘密鍵の設定
|
||
- [ ] データベース接続文字列の設定
|
||
- [ ] メールサービス認証情報の設定
|
||
- [ ] 起動時の設定検証
|
||
|
||
**依存関係**: なし
|
||
**推定工数**: 2時間
|
||
**ステータス**: `TODO`
|
||
|
||
### フェーズ2: コア認証
|
||
*推定期間: 5日*
|
||
|
||
#### タスク2.1: ユーザー登録エンドポイント
|
||
**説明**: POST /auth/registerエンドポイントの実装
|
||
**受入基準**:
|
||
- [ ] メール検証実装
|
||
- [ ] パスワード強度要件の強制（最低12文字、複雑性）
|
||
- [ ] bcryptでのパスワードハッシュ（12ラウンド）
|
||
- [ ] 重複メールチェック
|
||
- [ ] ウェルカムメール送信
|
||
- [ ] 90%以上のカバレッジを持つユニットテスト
|
||
|
||
**依存関係**: タスク1.1、タスク1.2
|
||
**推定工数**: 8時間
|
||
**ステータス**: `TODO`
|
||
|
||
#### タスク2.2: ログインエンドポイント
|
||
**説明**: POST /auth/loginエンドポイントの実装
|
||
**受入基準**:
|
||
- [ ] メール/パスワード検証
|
||
- [ ] JWTトークン生成（15分有効期限）
|
||
- [ ] リフレッシュトークン生成（7日有効期限）
|
||
- [ ] 失敗ログイン試行の追跡
|
||
- [ ] 5回失敗後のアカウントロックアウト
|
||
- [ ] 90%以上のカバレッジを持つユニットテスト
|
||
|
||
**依存関係**: タスク2.1
|
||
**推定工数**: 6時間
|
||
**ステータス**: `TODO`
|
||
|
||
#### タスク2.3: トークンリフレッシュエンドポイント
|
||
**説明**: POST /auth/refreshエンドポイントの実装
|
||
**受入基準**:
|
||
- [ ] リフレッシュトークンの検証
|
||
- [ ] 新しいアクセストークンの生成
|
||
- [ ] リフレッシュトークンのローテーション
|
||
- [ ] 古いリフレッシュトークンの無効化
|
||
- [ ] 期限切れトークンの適切な処理
|
||
|
||
**依存関係**: タスク2.2
|
||
**推定工数**: 4時間
|
||
**ステータス**: `TODO`
|
||
|
||
#### タスク2.4: ログアウトエンドポイント
|
||
**説明**: POST /auth/logoutエンドポイントの実装
|
||
**受入基準**:
|
||
- [ ] 現在のセッションの無効化
|
||
- [ ] リフレッシュトークンのクリア
|
||
- [ ] セキュリティイベントのログ
|
||
- [ ] 既にログアウト済み状態の処理
|
||
|
||
**依存関係**: タスク2.2
|
||
**推定工数**: 3時間
|
||
**ステータス**: `TODO`
|
||
|
||
### フェーズ3: パスワード管理
|
||
*推定期間: 3日*
|
||
|
||
#### タスク3.1: パスワードリセットリクエスト
|
||
**説明**: POST /auth/password-resetエンドポイントの実装
|
||
**受入基準**:
|
||
- [ ] セキュアなリセットトークンの生成
|
||
- [ ] リンク付きリセットメールの送信
|
||
- [ ] 1時間後のトークン有効期限
|
||
- [ ] リセットリクエストのレート制限（1時間に3回）
|
||
- [ ] セキュリティイベントのログ
|
||
|
||
**依存関係**: タスク2.1
|
||
**推定工数**: 5時間
|
||
**ステータス**: `TODO`
|
||
|
||
#### タスク3.2: パスワードリセット確認
|
||
**説明**: POST /auth/password-reset/confirmエンドポイントの実装
|
||
**受入基準**:
|
||
- [ ] リセットトークンの検証
|
||
- [ ] パスワード要件の強制
|
||
- [ ] すべての既存セッションの無効化
|
||
- [ ] 確認メールの送信
|
||
- [ ] トークン再利用の防止
|
||
|
||
**依存関係**: タスク3.1
|
||
**推定工数**: 4時間
|
||
**ステータス**: `TODO`
|
||
|
||
### フェーズ4: 統合とテスト
|
||
*推定期間: 2日*
|
||
|
||
#### タスク4.1: 統合テスト
|
||
**説明**: 包括的な統合テストの作成
|
||
**受入基準**:
|
||
- [ ] 完全な登録フローのテスト
|
||
- [ ] ログイン/ログアウトサイクルのテスト
|
||
- [ ] パスワードリセットフローのテスト
|
||
- [ ] トークンリフレッシュフローのテスト
|
||
- [ ] エラーシナリオのテスト
|
||
- [ ] 85%以上のコードカバレッジ達成
|
||
|
||
**依存関係**: フェーズ2、フェーズ3
|
||
**推定工数**: 8時間
|
||
**ステータス**: `TODO`
|
||
|
||
#### タスク4.2: セキュリティテスト
|
||
**説明**: セキュリティ検証の実施
|
||
**受入基準**:
|
||
- [ ] SQLインジェクション防止のテスト
|
||
- [ ] XSS防止のテスト
|
||
- [ ] CSRF保護のテスト
|
||
- [ ] レート制限のテスト
|
||
- [ ] パスワードハッシュ強度のテスト
|
||
- [ ] セキュリティ対策の文書化
|
||
|
||
**依存関係**: タスク4.1
|
||
**推定工数**: 6時間
|
||
**ステータス**: `TODO`
|
||
|
||
#### タスク4.3: ドキュメント作成
|
||
**説明**: APIドキュメントとデプロイガイドの作成
|
||
**受入基準**:
|
||
- [ ] OpenAPI/Swagger仕様の作成
|
||
- [ ] セットアップ手順付きREADME
|
||
- [ ] セキュリティベストプラクティスの文書化
|
||
- [ ] デプロイメントチェックリストの作成
|
||
- [ ] Postmanコレクションのエクスポート
|
||
|
||
**依存関係**: タスク4.1
|
||
**推定工数**: 4時間
|
||
**ステータス**: `TODO`
|
||
|
||
## タスクステータスの凡例
|
||
- `TODO` - 未着手
|
||
- `IN_PROGRESS` - 現在作業中
|
||
- `BLOCKED` - 依存関係または問題によりブロック
|
||
- `REVIEW` - コードレビュー待ち
|
||
- `DONE` - 完了済みおよびテスト済み
|
||
|
||
## リスクと軽減策
|
||
|
||
### リスク1: メールサービスの利用不可
|
||
**影響度**: 高
|
||
**発生確率**: 低
|
||
**軽減策**: 指数バックオフ付き再試行キューの実装、フォールバックメールプロバイダーの追加
|
||
|
||
### リスク2: JWT秘密鍵の漏洩
|
||
**影響度**: 重大
|
||
**発生確率**: 低
|
||
**軽減策**: 鍵管理サービスの使用、鍵ローテーションの実装、不正なトークン使用の監視
|
||
|
||
### リスク3: ブルートフォース攻撃
|
||
**影響度**: 高
|
||
**発生確率**: 中
|
||
**軽減策**: レート制限の実装、失敗試行後のCAPTCHA、アカウントロックアウト機構
|
||
|
||
## 備考
|
||
- 将来のイテレーションでOAuthプロバイダーの実装を検討
|
||
- 認証メトリクスの監視（ログイン成功率、パスワードリセット頻度）
|
||
- 複数デバイス間のセッション管理の計画
|
||
- 次フェーズでの2要素認証の実装を検討
|
||
```
|
||
|
||
## クイックリファレンス
|
||
|
||
### 各ドキュメントの使用タイミング
|
||
|
||
**requirements.md**
|
||
- システムが何をすべきかを記述
|
||
- ユーザーストーリーと受入基準を定義
|
||
- 測定可能でテスト可能な要件を指定
|
||
- 明確性のためにEARS記法を使用
|
||
|
||
**design.md**
|
||
- システムがどのように動作するかを文書化
|
||
- アーキテクチャとコンポーネントを定義
|
||
- APIとデータモデルを指定
|
||
- 技術的決定とトレードオフを含める
|
||
|
||
**tasks.md**
|
||
- 実装を管理可能な部分に分解
|
||
- タスク間の依存関係を定義
|
||
- 進捗とステータスを追跡
|
||
- リスクと軽減戦略を特定
|
||
|
||
### 避けるべき一般的な落とし穴
|
||
|
||
1. **曖昧な要件**: 常に具体的で測定可能に
|
||
2. **依存関係の欠落**: タスクの依存関係を明確に特定
|
||
3. **不完全な受入基準**: すべてのタスクに明確な完了基準が必要
|
||
4. **テスト不可能**: 要件とタスクは検証可能でなければならない
|
||
5. **非機能要件の無視**: パフォーマンス、セキュリティ、ユーザビリティを忘れない
|
||
|
||
### 成功のためのヒント
|
||
|
||
1. 「なぜ」を理解するためにユーザーストーリーから始める
|
||
2. 要件にはEARS記法を一貫して使用
|
||
3. 設計文書には明確性のために図を含める
|
||
4. 大きなタスクを小さな管理可能な部分に分解
|
||
5. 進捗を追跡するため定期的にタスクステータスを更新
|
||
6. ステークホルダーとドキュメントをレビューし検証
|
||
7. プロジェクトが進化するにつれてドキュメントを同期させる |