# API リファレンス

## 基本情報

- **ベース URL**: `http://localhost:3000`
- **認証方式**: JWT Bearer トークン
- **Content-Type**: `application/json`

## 認証 API

### ユーザー登録

```http
POST /auth/register
Content-Type: application/json

{
  "username": "string",
  "password": "string"
}
```

**レスポンス**:

```json
{
  "message": "ユーザーが正常に作成されました",
  "user": {
    "id": "string",
    "username": "string",
    "isAdmin": false
  }
}
```

### ユーザーログイン

```http
POST /auth/login
Content-Type: application/json

{
  "username": "string", 
  "password": "string"
}
```

**レスポンス**:

```json
{
  "access_token": "jwt_token_string",
  "user": {
    "id": "string",
    "username": "string",
    "isAdmin": false
  }
}
```

### パスワード変更

```http
POST /auth/change-password
Authorization: Bearer <token>
Content-Type: application/json

{
  "currentPassword": "string",
  "newPassword": "string"
}
```

## モデル設定 API

### モデル一覧の取得

```http
GET /model-configs
Authorization: Bearer <token>
```

**レスポンス**:

```json
[
  {
    "id": "string",
    "name": "string",
    "provider": "openai|gemini",
    "modelId": "string",
    "baseUrl": "string",
    "type": "llm|embedding|rerank",
    "supportsVision": boolean
  }
]
```

### モデル設定の作成

```http
POST /model-configs
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "string",
  "provider": "openai|gemini", 
  "modelId": "string",
  "baseUrl": "string",
  "apiKey": "string",
  "type": "llm|embedding|rerank",
  "supportsVision": boolean
}
```

### モデル設定の更新

```http
PUT /model-configs/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "string",
  "apiKey": "string",
  // ... その他のフィールド
}
```

### モデル設定の削除

```http
DELETE /model-configs/:id
Authorization: Bearer <token>
```

## ナレッジベース API

### ファイルのアップロード

```http
POST /upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

{
  "file": File,
  "chunkSize": number,
  "chunkOverlap": number,
  "embeddingModelId": "string",
  "mode": "fast|precise"  // 処理モード
}
```

**レスポンス**:

```json
{
  "id": "string",
  "name": "string",
  "originalName": "string",
  "size": number,
  "mimetype": "string",
  "status": "pending|indexing|completed|failed"
}
```

### ファイル一覧の取得

```http
GET /knowledge-bases
Authorization: Bearer <token>
```

**レスポンス**:

```json
[
  {
    "id": "string",
    "name": "string", 
    "originalName": "string",
    "size": number,
    "mimetype": "string",
    "status": "pending|indexing|completed|failed",
    "createdAt": "datetime"
  }
]
```

### ファイルの削除

```http
DELETE /knowledge-bases/:id
Authorization: Bearer <token>
```

### ナレッジベースの全消去

```http
DELETE /knowledge-bases/clear
Authorization: Bearer <token>
```

## チャット API

### ストリーミングチャット

```http
POST /chat/stream
Authorization: Bearer <token>
Content-Type: application/json

{
  "message": "string",
  "history": [
    {
      "role": "user|assistant",
      "content": "string"
    }
  ],
  "userLanguage": "zh|en|ja"
}
```

**レスポンス**: Server-Sent Events (SSE)

```
data: {"type": "content", "data": "ナレッジベースを検索中..."}

data: {"type": "content", "data": "関連情報が見つかりました..."}

data: {"type": "content", "data": "回答内容の断片"}

data: {"type": "sources", "data": [
  {
    "fileName": "string",
    "content": "string", 
    "score": number,
    "chunkIndex": number
  }
]}

data: [DONE]
```

## ユーザー設定 API

### ユーザー設定の取得

```http
GET /user-settings
Authorization: Bearer <token>
```

**レスポンス**:

```json
{
  "selectedLLMId": "string",
  "selectedEmbeddingId": "string", 
  "selectedRerankId": "string",
  "temperature": number,
  "maxTokens": number,
  "topK": number,
  "enableRerank": boolean,
  "scoreThreshold": number,
  "similarityThreshold": number,
  "enableFullTextSearch": boolean,
  "language": "zh|en|ja"
}
```

### ユーザー設定の更新

```http
PUT /user-settings
Authorization: Bearer <token>
Content-Type: application/json

{
  "selectedLLMId": "string",
  "temperature": number,
  "maxTokens": number,
  // ... その他の設定フィールド
}
```

## Vision Pipeline API

### 推奨モードの取得

```http
GET /api/vision/recommend-mode?file=xxx&size=xxx
Authorization: Bearer <token>
```

**レスポンス**:

```json
{
  "recommendedMode": "precise",
  "reason": "ファイルサイズが大きいため、高精度モードを推奨します",
  "estimatedCost": 0.5,
  "estimatedTime": 60,
  "warnings": ["処理時間が長くなる可能性があります", "API 利用料が発生します"]
}
```

### LibreOffice 変換サービス

```http
POST /libreoffice/convert
Content-Type: multipart/form-data

{
  "file": File
}
```

**レスポンス**:

```json
{
  "pdf_path": "/uploads/document.pdf",
  "converted": true,
  "original": "document.docx",
  "file_size": 102400
}
```

### ヘルスチェック

```http
GET /libreoffice/health
```

**レスポンス**:

```json
{
  "status": "healthy",
  "service": "libreoffice-converter",
  "version": "1.0.0",
  "uptime": 3600.5
}
```

## ユーザー管理 API (管理者用)

### ユーザー一覧の取得

```http
GET /users
Authorization: Bearer <admin_token>
```

### ユーザーの作成

```http
POST /users
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "username": "string",
  "password": "string",
  "isAdmin": boolean
}
```

### ユーザーの削除

```http
DELETE /users/:id
Authorization: Bearer <admin_token>
```

## エラーレスポンス形式

```json
{
  "statusCode": number,
  "message": "string",
  "error": "string"
}
```

## ステータスコードの説明

- `200` - 成功
- `201` - 作成成功
- `400` - リクエストパラメータの不正
- `401` - 認証エラー / トークン無効
- `403` - 権限不足
- `404` - リソースが見つかりません
- `409` - リソースの競合
- `500` - サーバー内部エラー

## 実装例

### JavaScript/TypeScript

```javascript
// ログイン
const loginResponse = await fetch('/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    username: 'user',
    password: 'password'
  })
});

const { access_token } = await loginResponse.json();

// ファイル一覧の取得
const filesResponse = await fetch('/knowledge-bases', {
  headers: {
    'Authorization': `Bearer ${access_token}`
  }
});

const files = await filesResponse.json();

// ストリーミングチャット
const chatResponse = await fetch('/chat/stream', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'こんにちは',
    history: [],
    userLanguage: 'ja'
  })
});

const reader = chatResponse.body.getReader();
// SSE ストリームの処理...
```