1. contract/ フォルダにAPI検証ファイルがあるか確認
   ├─ あり → 確定モード（実データ優先）
   └─ なし → 2へ

2. OpenAPI/Contract仕様書を探す
   ├─ 見つかった → 確定モード（仕様書ベース）
   └─ 見つからない → 提案モード

1. converting-figma-to-html
   └─> Figmaから静的/動的を推測 → spec.md「コンテンツ分析」に仮決定

2. executing-api-from-openapi（オプション）
   └─> OpenAPIからAPIを実行してレスポンス形式を取得
   └─> contract/{endpoint-name}.json に検証結果を保存

3. mapping-html-to-api（このスキル）
   └─> contract/ フォルダのAPI検証ファイルを参照（あれば）
   └─> 全コンテンツ要素をAPI仕様書/実データと照合
   └─> 動的要素の確定 + 静的→動的への再分類
   └─> spec.md「APIマッピング」に確定結果を記載

1. contract/{endpoint-name}.json を確認
   ├─ 存在する → 実際のレスポンスデータを使用（高精度）
   └─ 存在しない → OpenAPI仕様書のみを使用

{
  "endpoint": "/api/v1/messages",
  "method": "GET",
  "executed_at": "2024-01-15T10:30:00Z",
  "request": { ... },
  "response": { ... },
  "schema_diff": [ ... ]
}

.agents/tmp/{screen-id}/
├── spec.md                 # ← このスキルが「APIマッピング」セクションを更新
├── index.html              # ← APIマッピング属性を追加
├── contract/               # API検証結果（executing-api-from-openapiで生成）
│   ├── get-messages.json   # 例: GET /api/v1/messages の検証結果
│   └── post-feedback.json  # 例: POST /api/v1/feedback の検証結果
└── assets/

<!-- GET: データ表示 -->
<img data-figma-content-id="question_image"
     data-figma-content-classification="dynamic"
     data-api-endpoint="GET /student_api/ask_ai/submission/{id}/info"
     data-api-response-field="image_uri"
     data-api-contract="get_submission_info.md"
     src="placeholder.png">

<!-- POST: アクション送信 -->
<button data-figma-content-id="feedback_positive"
        data-figma-content-classification="static"
        data-api-endpoint="POST /student_api/ask_ai/feedback"
        data-api-request-body='{"question_id": "{id}", "rating": 1}'
        data-api-contract="post_feedback.md">
  解決した
</button>

以下の画面のAPIマッピングを整理してください：
画面ID: course-list
OpenAPI: openapi/index.yaml

API Mapping Progress:
- [ ] Step 0: spec.md の存在確認
- [ ] Step 1: contract/ フォルダのAPI検証ファイルを確認
- [ ] Step 2: 全コンテンツ要素を抽出（静的・動的両方）
- [ ] Step 3: APIエンドポイントを特定
- [ ] Step 4: リクエスト構造を定義
- [ ] Step 5: レスポンス構造を定義
- [ ] Step 6: データバインディングを整理（静的→動的の再分類含む）
- [ ] Step 7: API呼び出しタイミングを決定
- [ ] Step 8: エラーハンドリングを定義
- [ ] Step 9: spec.md の「APIマッピング」セクションを更新
- [ ] Step 10: HTMLにdata-api-*属性を追加
- [ ] Step 11: マッピングオーバーレイ生成（任意）
  - [ ] テンプレートをコピー: ../../templates/mapping-overlay.js
  - [ ] CONTRACT_DATA にGET APIのサンプルJSONを追加
  - [ ] HTMLに <script src="mapping-overlay.js"></script> を追加

ls .agents/tmp/{screen-id}/spec.md

ls .agents/tmp/{screen-id}/contract/*.json 2>/dev/null

const CONTRACT_DATA = {
  'get_api_endpoint_name.md': {
    endpoint: 'GET /api/path/{id}',
    json: {
      "field1": "value1",
      "field2": {
        "nested": "value"
      }
    }
  }
};

## APIマッピング

> **ステータス**: 完了 ✓  
> **生成スキル**: mapping-html-to-api  
> **更新日**: 2024-01-15

### 使用API一覧

| エンドポイント | メソッド | 用途 | 呼び出しタイミング |
|---------------|---------|------|------------------|
| /api/courses | GET | 講座一覧取得 | 画面表示時 |
| /api/courses/:id | GET | 講座詳細取得 | カードクリック時 |
| /api/courses | POST | 講座作成 | フォーム送信時 |

### データバインディング

#### GET /api/courses

**リクエスト**

| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|:----:|------|
| page | number | - | ページ番号 |
| limit | number | - | 取得件数 |
| q | string | - | 検索キーワード |
| category | string | - | カテゴリフィルター |

**レスポンス**

\`\`\`typescript
interface CoursesResponse {
  courses: Course[];
  total: number;
  page: number;
  limit: number;
}

interface Course {
  id: string;
  title: string;
  description: string;
  category: string;
  duration: number;
  created_at: string;
}
\`\`\`

**UIマッピング**

| UI要素 | data-figma-content | APIフィールド | 変換 |
|--------|-------------------|--------------|------|
| 講座タイトル | course-title | course.title | そのまま |
| 講座説明 | course-description | course.description | 100文字で切り詰め |
| カテゴリ | course-category | course.category | カテゴリ名に変換 |
| 所要時間 | course-duration | course.duration | \`${value}分\` |
| 作成日 | course-created-at | course.created_at | formatDate |

#### POST /api/courses

**リクエスト**

\`\`\`typescript
interface CreateCourseRequest {
  title: string;
  description: string;
  category: string;
  duration: number;
}
\`\`\`

**フォームマッピング**

| フォームフィールド | APIフィールド | バリデーション |
|------------------|--------------|---------------|
| タイトル入力 | title | 必須、100文字以内 |
| 説明入力 | description | 任意、1000文字以内 |
| カテゴリ選択 | category | 必須 |
| 所要時間入力 | duration | 必須、1-480 |

### API呼び出しタイミング

| タイミング | API | トリガー | 備考 |
|----------|-----|---------|------|
| 画面表示時 | GET /api/courses | マウント時 | 初回データ取得 |
| 検索実行時 | GET /api/courses?q=xxx | 検索フォーム送信 | デバウンス300ms |
| ページ遷移時 | GET /api/courses?page=N | ページネーションクリック | - |
| 作成実行時 | POST /api/courses | フォーム送信 | バリデーション後 |

### エラーハンドリング

| HTTPステータス | エラー種別 | UI対応 |
|--------------|----------|--------|
| 401 | 認証エラー | ログイン画面へリダイレクト |
| 403 | 権限エラー | 権限エラーメッセージ表示 |
| 404 | データ未検出 | Empty状態表示 |
| 422 | バリデーションエラー | フォームエラー表示 |
| 500 | サーバーエラー | リトライボタン表示 |

### 特記事項

- 講座一覧は無限スクロールまたはページネーションで対応
- 検索は300msのデバウンスを適用
- カテゴリは事前にマスタデータを取得してキャッシュ

## APIマッピング

> **ステータス**: 該当なし  
> **生成スキル**: mapping-html-to-api  
> **更新日**: 2024-01-15

この画面にはAPI連携がありません。

- [ ] spec.md の「APIマッピング」セクションが更新されている
- [ ] ステータスが「完了 ✓」になっている
- [ ] 使用API一覧が網羅されている
- [ ] リクエスト/レスポンス構造が定義されている
- [ ] UIマッピングが整理されている
- [ ] API呼び出しタイミングが明確
- [ ] エラーハンドリングが定義されている
- [ ] 完了チェックリストが更新されている
- [ ] 変更履歴に記録が追加されている