# 分析 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 エンドポイント

### 分析（Analytics）

#### GET /api/v1/analytics/monthly-comparison

月次データのトレンド比較を取得します。

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

**クエリパラメータ:**
- months: number（オプション、デフォルト: 3）

**レスポンス スキーマ:**
```json
{
  "data": {
    "months": [
      {
        "year": number,
        "month": number,
        "completionRate": number,
        "avgConcentration": number | null,
        "avgMood": number | null,
        "streak": { "current": number, "longest": number }
      }
    ],
    "trends": {
      "completionRate": "improving" | "declining" | "stable",
      "concentration": "improving" | "declining" | "stable",
      "mood": "improving" | "declining" | "stable"
    },
    "insights": Array<string>
  },
  "error": null
}
```

---

#### GET /api/v1/analytics/daily-averages

日別の集中度・気分の平均値を取得します。

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

**クエリパラメータ:**
- days: number（オプション）
- timezone: string（オプション、デフォルト: "Asia/Tokyo"）
- includeTasks: boolean（オプション）

**レスポンス スキーマ:**
```json
{
  "data": {
    "overall": Array<{
      "date": "string",
      "avg_concentration": number | null,
      "avg_mood": number | null,
      "answer_count": number,
      "unanswered_count": number
    }>,
    "tasks": Record<string, {
      "taskTitle": "string",
      "data": Array<DailyAverage>
    }> | null
  },
  "error": null
}
```

---

#### GET /api/v1/analytics/task-completion-grid

タスク完了ヒートマップデータを取得します。

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

**クエリパラメータ:**
- days: number（オプション）
- timezone: string（オプション、デフォルト: "Asia/Tokyo"）

**レスポンス スキーマ:**
```json
{
  "data": Array<{
    "date": "string",
    "task_id": "string",
    "task_title": "string",
    "status": "not_scheduled" | "completed" | "not_completed",
    "target_count": number,
    "completed_count": number,
    "time_slots": Array<TimeSlotSummary> | null
  }>,
  "dates": Array<string>,
  "tasks": Array<{ "id": string, "title": string }>,
  "error": null
}
```

---

#### GET /api/v1/analytics/task-day-detail

特定の日のタスク詳細データを取得します。

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

**クエリパラメータ:**
- date: string（必須、ISO 8601形式）
- timezone: string（オプション、デフォルト: "Asia/Tokyo"）

**レスポンス スキーマ:**
```json
{
  "data": {
    "date": "string",
    "tasks": Array<{
      "task_id": "string",
      "task_title": "string",
      "status": "not_scheduled" | "completed" | "not_completed",
      "target_count": number,
      "completed_count": number,
      "answer_events": Array<{
        "id": "string",
        "happened_at": "string",
        "concentration_level": -2 | -1 | 0 | 1 | 2,
        "mood_level": -2 | -1 | 0 | 1 | 2,
        "comment_text": "string | null"
      }>,
      "comments": Array<string>,
      "ai_prediction": {
        "broad_category": "string",
        "specific_reason": "string",
        "suggestion": "string | null",
        "confidence": number | null
      } | null
    }>
  },
  "error": null
}
```

---

#### GET /api/v1/analytics/daily-detail

日別詳細分析を取得します（RPC経由）。

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

**クエリパラメータ:**
- date: string（必須、ISO 8601形式）
- timezone: string（オプション、デフォルト: "Asia/Tokyo"）

**レスポンス スキーマ:**
```json
{
  "data": {
    "date": "string",
    "avg_concentration": number | null,
    "avg_mood": number | null,
    "answer_events": Array<{
      "id": "string",
      "happened_at": "string",
      "task_id": "string | null",
      "task_title": "string | null",
      "concentration_level": -2 | -1 | 0 | 1 | 2,
      "mood_level": -2 | -1 | 0 | 1 | 2,
      "comment_text": "string | null"
    }>,
    "comments": Array<{
      "id": "string",
      "happened_at": "string",
      "task_title": "string | null",
      "text": "string"
    }>,
    "unanswered_count": number,
    "unanswered_events": Array<{
      "id": "string",
      "happened_at": "string",
      "reason": "ignored" | "closed" | "cancelled",
      "task_title": "string | null"
    }>
  },
  "error": null
}
```