# タスク 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 エンドポイント

### タスク（Tasks）

#### GET /api/v1/tasks

認証済みユーザーの全タスクを取得します。

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

**クエリパラメータ:**
- active: boolean（オプション）- アクティブ状態でフィルタリング
- kind: string（オプション）- タスク種別でフィルタリング（"single" | "habit"）

**レスポンス スキーマ:**
```json
{
  "data": [
    {
      "id": "string",
      "title": "string",
      "description": "string | null",
      "kind": "single" | "habit",
      "active": boolean,
      "start_date": "string | null",
      "end_date": "string | null",
      "created_at": "string",
      "updated_at": "string",
      "period_rules": Array<PeriodRule>,
      "time_rules": Array<TimeRule>,
      "tags": Array<{ "id": string, "name": string }>
    }
  ],
  "error": null
}
```

---

#### POST /api/v1/tasks

新しいタスクを作成します。

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

**リクエストボディ:**
```json
{
  "title": "string (required)",
  "description": "string | null",
  "kind": "single" | "habit",
  "active": boolean,
  "start_date": "string | null",
  "end_date": "string | null"
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "id": "string",
    "title": "string",
    "description": "string | null",
    "kind": "single" | "habit",
    "active": boolean,
    "start_date": "string | null",
    "end_date": "string | null",
    "created_at": "string",
    "updated_at": "string",
    "period_rules": Array<PeriodRule>,
    "time_rules": Array<TimeRule>
  },
  "error": null
}
```

**エラーケース:**
- 400: タイトルは必須です

---

#### GET /api/v1/tasks/today

今日のタスクを時間帯付きで取得します。

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

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

**レスポンス スキーマ:**
```json
{
  "data": {
    "date": "string",
    "timezone": "string",
    "tasks": [
      {
        "taskId": "string",
        "slotId": "string",
        "title": "string",
        "kind": "single" | "habit",
        "tags": Array<string>,
        "timeLabel": "string",
        "anytime": boolean,
        "startTime": "string | null",
        "endTime": "string | null",
        "target": number,
        "completed": number,
        "remaining": number,
        "status": "todo" | "done" | "skipped",
        "sortMinutes": number
      }
    ]
  },
  "error": null
}
```

**エラーケース:**
- 400: 無効な日付形式
- 401: 認証が必要です

---

#### GET /api/v1/tasks/overview

タスクの概要と統計情報を取得します。

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

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

**レスポンス スキーマ:**
```json
{
  "data": {
    "date": "string",
    "timezone": "string",
    "today": Array<TodayTaskRow>,
    "stats": {
      "totalTasks": number,
      "completedTasks": number,
      "remainingTasks": number,
      "completionRate": number
    }
  },
  "error": null
}
```

---

#### GET /api/v1/tasks/search

キーワードでタスクを検索します。

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

**クエリパラメータ:**
- q: string（必須）- 検索キーワード
- limit: number（オプション、1-50、デフォルト: 8）

**レスポンス スキーマ:**
```json
{
  "data": [
    {
      "id": "string",
      "title": "string",
      "description": "string | null",
      "kind": "single" | "habit"
    }
  ],
  "error": null
}
```

**エラーケース:**
- 400: 検索キーワードは必須、または limit が無効です

---

#### GET /api/v1/tasks/streak

現在の連続達成日数を取得します。

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

**レスポンス スキーマ:**
```json
{
  "data": {
    "current": number,
    "longest": number,
    "breakDate": "string | null"
  },
  "error": null
}
```

**備考:** 未認証時は current / longest に 0 が返されます。

---

#### GET /api/v1/tasks/:id

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

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

**パスパラメータ:**
- id: string（必須）- タスクID

**レスポンス スキーマ:**
```json
{
  "data": {
    "id": "string",
    "title": "string",
    "description": "string | null",
    "kind": "single" | "habit",
    "active": boolean,
    "start_date": "string | null",
    "end_date": "string | null",
    "period_rules": Array<PeriodRule>,
    "time_rules": Array<TimeRule>,
    "tags": Array<{ "id": string, "name": string }>
  },
  "error": null
}
```

---

#### PUT /api/v1/tasks/:id

特定のタスクを更新します。

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

**パスパラメータ:**
- id: string（必須）- タスクID

**リクエストボディ:**
```json
{
  "title": "string",
  "description": "string | null",
  "kind": "single" | "habit",
  "active": boolean,
  "start_date": "string | null",
  "end_date": "string | null"
}
```

**レスポンス スキーマ:** GET /api/v1/tasks/:id と同じ

---

#### DELETE /api/v1/tasks/:id

特定のタスクを削除します。

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

**パスパラメータ:**
- id: string（必須）- タスクID

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

---

#### POST /api/v1/tasks/:id/execute

タスク実行を記録し、報酬を付与します。

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

**パスパラメータ:**
- id: string（必須）- タスクID

**リクエストボディ:**
```json
{
  "qty": number (optional, default: 1)
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "success": boolean,
    "qty": number,
    "rewardTotal": number,
    "rewardErrors": Array<{ "source": string, "message": string }>,
    "streakDays": number
  },
  "error": null
}
```

---

#### POST /api/v1/tasks/:id/skip

理由付きでタスクをスキップします。

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

**パスパラメータ:**
- id: string（必須）- タスクID

**リクエストボディ:**
```json
{
  "reason": "string",
  "scheduled_date": "string"
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "id": "string",
    "task_id": "string",
    "reason": "string",
    "scheduled_date": "string",
    "skipped_at": "string"
  },
  "error": null
}
```

---

#### DELETE /api/v1/tasks/:id/skip

タスクのスキップをキャンセルします。

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

**パスパラメータ:**
- id: string（必須）- タスクID

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