# 評価 API リファレンス

TaskWorks API のポモドーロ評価関連エンドポイントの詳細ドキュメントです。すべてのエンドポイントはユーザー固有のデータのみを返します（RLS保護）。

## 認証方式

### ApiKey 認証（推奨）
```
Authorization: ApiKey <token>
```
- 設定 > APIキー管理 から生成
- トークンは一度しか表示されないため安全に保管
- ほとんどのエンドポイントで使用可能

### Bearer トークン認証
```
Authorization: Bearer <token>
```
- サービス間通信で使用
- 一部のエンドポイントで必須（例: /api/v1/blocks/windows）

### Cookie 認証
- 標準のセッションベース認証
- Webクライアントで使用
- Cookie専用エンドポイントで必須

## 共通レスポンス形式

すべての成功レスポンスは以下の構造に従います：
```json
{
  "data": <response_data>,
  "error": null
}
```

すべてのエラーレスポンスは以下の構造に従います：
```json
{
  "error": "<error_type>",
  "message": "<human_readable_message>",
  "code": "<optional_error_code>",
  "context": <optional_additional_context>
}
```

## HTTP ステータスコード

- 200: 成功
- 201: 作成完了
- 400: 不正なリクエスト（検証エラー）
- 401: 未認証（認証が必要）
- 403: 禁止（権限なし）
- 404: 未検出
- 409: 衝突（リソースの競合）
- 500: サーバー内部エラー

## ページネーション

一部のエンドポイントはカーソルベースのページネーションをサポート：
- cursor: 次ページの開始位置
- limit: 返す項目数（1-100、デフォルトはエンドポイントにより異なる）

レスポンス形式：
```json
{
  "data": {
    "items": [...],
    "nextCursor": "string | null",
    "hasMore": boolean
  },
  "error": null
}
```

## API エンドポイント

### 評価（Evaluations - ポモドーロ）

#### POST /api/v1/evaluations/submit

ポモドーロ評価を提出します（集中度・気分）。

**認証:** ApiKey / Bearer / Cookie

**リクエストボディ:**
```json
{
  "task_id": "string (required)",
  "concentration_level": -2 | -1 | 0 | 1 | 2,
  "mood_level": -2 | -1 | 0 | 1 | 2,
  "has_comment": boolean,
  "comment_text": "string | null",
  "pomodoro_session_id": "string | null",
  "execute_task": boolean,
  "task_qty": number
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "id": "string",
    "user_id": "string",
    "task_id": "string | null",
    "pomodoro_session_id": "string | null",
    "happened_at": "string",
    "concentration_level": -2 | -1 | 0 | 1 | 2,
    "mood_level": -2 | -1 | 0 | 1 | 2,
    "has_comment": boolean,
    "comment_text": "string | null"
  },
  "task_execution": {
    "qty": number,
    "rewardTotal": number,
    "streakDays": number,
    "bonusAmount": number,
    "rewardErrors": Array<{ "source": string, "message": string }>,
    "hasRewardFailure": boolean
  },
  "error": null
}
```

**エラーケース:**
- 400: task_idは必須、またはconcentration_level/mood_levelが範囲外（-2から2）
- 403: タスク実行の権限がありません

---

#### GET /api/v1/evaluations/last-task

最後のタスクを取得します（デフォルト選択用）。

**認証:** ApiKey / Bearer / Cookie

**レスポンス スキーマ:**
```json
{
  "data": {
    "task_id": "string",
    "task_title": "string",
    "selected_at": "string"
  },
  "error": null
}
```

---

#### POST /api/v1/evaluations/unanswered

未回答のポモドーロ評価を記録します。

**認証:** ApiKey / Bearer / Cookie

**リクエストボディ:**
```json
{
  "events": Array<{
    "id": "string",
    "user_id": "string",
    "task_id": "string | null",
    "pomodoro_session_id": "string | null",
    "happened_at": "string",
    "reason": "ignored" | "closed" | "cancelled"
  }>
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "success": true,
    "count": number
  },
  "error": null
}
```