# AI API リファレンス

TaskWorks API のAIアシスタント関連エンドポイントの詳細ドキュメントです。すべてのエンドポイントはユーザー固有のデータのみを返します（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 エンドポイント

### AIアシスタント（AI）

#### POST /api/v1/ai/chat

AIアシスタントとチャットします（LLM）。

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

**リクエストボディ:**
```json
{
  "question": "string (required)",
  "context": {
    "year": number,
    "month": number,
    "completionRate": number,
    "streak": number,
    "taskCount": number,
    "habitDashboard": Object,
    "monthlyComparison": Object,
    "concentrationMoodData": Array<Object>,
    "habitsMatrix": Object
  } | {},
  "messages": Array<{
    "role": "user" | "assistant",
    "content": "string",
    "timestamp": "string"
  }>
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "answer": "string",
    "messages": Array<{
      "role": "user" | "assistant",
      "content": "string",
      "timestamp": "string"
    }>
  },
  "error": null
}
```

**エラーケース:**
- 400: 質問は必須、または空です
- 400: 利用可能なLLMプロバイダー設定がありません
- 503: LLM設定テーブルが作成されていません

---

#### GET /api/v1/ai/report

保存されたAI習慣レポートを取得します。

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

**クエリパラメータ:**
- providerId: string（オプション）

**レスポンス スキーマ:**
```json
{
  "data": {
    "id": "string",
    "year": number,
    "month": number,
    "content": "string",
    "providerName": "string",
    "providerKind": "openai" | "anthropic" | "azure-openai" | "openrouter" | "custom-openai",
    "generatedAt": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "error": null
}
```

---

#### POST /api/v1/ai/report

AI習慣分析レポートを生成します。

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

**リクエストボディ:**
```json
{
  "providerId": "string | null",
  "useOfficial": boolean,
  "year": number,
  "month": number
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "content": "string",
    "generatedAt": "string",
    "providerName": "string",
    "providerKind": "openai" | "anthropic" | "azure-openai" | "openrouter" | "custom-openai"
  },
  "error": null
}
```

---

#### GET /api/v1/ai/providers

LLMプロバイダー設定一覧を取得します。

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

**レスポンス スキーマ:**
```json
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "kind": "openai" | "anthropic" | "azure-openai" | "openrouter" | "custom-openai",
      "apiKey": "string",
      "isDefault": boolean,
      "model": "string | null",
      "maxTokens": number | null,
      "temperature": number | null
    }
  ],
  "error": null
}
```

---

#### POST /api/v1/ai/providers

LLMプロバイダー設定を作成/更新します。

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

**リクエストボディ:**
```json
{
  "id": "string | null",
  "name": "string",
  "kind": "openai" | "anthropic" | "azure-openai" | "openrouter" | "custom-openai",
  "apiKey": "string",
  "isDefault": boolean,
  "model": "string | null",
  "maxTokens": number | null,
  "temperature": number | null
}
```

**レスポンス スキーマ:** GET /api/v1/ai/providers と同じ（配列内の単一アイテム）

---

#### DELETE /api/v1/ai/providers

LLMプロバイダー設定を削除します。

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

**リクエストボディ:**
```json
{
  "providerId": "string (required)"
}
```

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

---

#### POST /api/v1/ai/daily-reflection

AIで日次リフレクションを生成します。

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

**リクエストボディ:**
```json
{
  "question": "string",
  "context": Object,
  "providerId": "string | null"
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "reflection": "string",
    "generatedAt": "string"
  },
  "error": null
}
```