brief-rags-bench/DB_API_CONTRACT.md

# DB API Contract

Контракт для взаимодействия FastAPI приложения Brief Bench с внешним DB API сервисом.

## Base URL

```
{DB_API_URL}  # Из .env, например: http://db-api-service:8080/api/v1
```

---

## Authentication & Users

### POST /users/login

Авторизация пользователя и запись логина.

**Request:**
```json
{
  "login": "12345678",  // 8-значный логин (строка)
  "client_ip": "192.168.1.100"
}
```

**Response 200:**
```json
{
  "user_id": "uuid-string",
  "login": "12345678",
  "last_login_at": "2025-12-17T12:00:00Z",
  "created_at": "2025-12-01T10:00:00Z"
}
```

**Errors:**
- 400: Неверный формат логина
- 500: Ошибка сервера

---

## User Settings

### GET /users/{user_id}/settings

Получить настройки пользователя для всех окружений (IFT, PSI, PROD).

**Path Parameters:**
- `user_id`: UUID пользователя

**Response 200:**
```json
{
  "user_id": "uuid-string",
  "settings": {
    "ift": {
      "apiMode": "bench",
      "bearerToken": "...",
      "systemPlatform": "...",
      "systemPlatformUser": "...",
      "platformUserId": "...",
      "platformId": "...",
      "withClassify": false,
      "resetSessionMode": true
    },
    "psi": { ... },
    "prod": { ... }
  },
  "updated_at": "2025-12-17T12:00:00Z"
}
```

**Errors:**
- 404: Пользователь не найден
- 500: Ошибка сервера

---

### PUT /users/{user_id}/settings

Обновить настройки пользователя.

**Path Parameters:**
- `user_id`: UUID пользователя

**Request:**
```json
{
  "settings": {
    "ift": {
      "apiMode": "bench",
      "bearerToken": "...",
      "systemPlatform": "...",
      "systemPlatformUser": "...",
      "platformUserId": "...",
      "platformId": "...",
      "withClassify": false,
      "resetSessionMode": true
    },
    "psi": { ... },
    "prod": { ... }
  }
}
```

**Response 200:**
```json
{
  "user_id": "uuid-string",
  "settings": { ... },
  "updated_at": "2025-12-17T12:05:00Z"
}
```

**Errors:**
- 404: Пользователь не найден
- 400: Неверный формат настроек
- 500: Ошибка сервера

---

## Analysis Sessions

### POST /users/{user_id}/sessions

Создать новую сессию анализа.

**Path Parameters:**
- `user_id`: UUID пользователя

**Request:**
```json
{
  "environment": "ift",  // ift | psi | prod
  "api_mode": "bench",   // bench | backend
  "request": [
    { "body": "Вопрос 1", "with_docs": true },
    { "body": "Вопрос 2", "with_docs": true }
  ],
  "response": {
    "answers": [ ... ]  // RagResponseBenchList format
  },
  "annotations": {
    "0": {
      "overall": { "rating": "correct", "comment": "..." },
      "body_research": { "issues": [], "comment": "" },
      ...
    }
  }
}
```

**Response 201:**
```json
{
  "session_id": "uuid-string",
  "user_id": "uuid-string",
  "environment": "ift",
  "api_mode": "bench",
  "request": [ ... ],
  "response": { ... },
  "annotations": { ... },
  "created_at": "2025-12-17T12:00:00Z",
  "updated_at": "2025-12-17T12:00:00Z"
}
```

**Errors:**
- 404: Пользователь не найден
- 400: Неверный формат данных
- 500: Ошибка сервера

---

### GET /users/{user_id}/sessions

Получить список сессий пользователя.

**Path Parameters:**
- `user_id`: UUID пользователя

**Query Parameters:**
- `environment` (optional): Фильтр по окружению (ift/psi/prod)
- `limit` (optional): Лимит результатов (default: 50)
- `offset` (optional): Смещение для пагинации (default: 0)

**Response 200:**
```json
{
  "sessions": [
    {
      "session_id": "uuid-string",
      "environment": "ift",
      "created_at": "2025-12-17T12:00:00Z"
    },
    ...
  ],
  "total": 123
}
```

**Errors:**
- 404: Пользователь не найден
- 500: Ошибка сервера

---

### GET /users/{user_id}/sessions/{session_id}

Получить конкретную сессию по ID.

**Path Parameters:**
- `user_id`: UUID пользователя
- `session_id`: UUID сессии

**Response 200:**
```json
{
  "session_id": "uuid-string",
  "user_id": "uuid-string",
  "environment": "ift",
  "api_mode": "bench",
  "request": [ ... ],
  "response": { ... },
  "annotations": { ... },
  "created_at": "2025-12-17T12:00:00Z",
  "updated_at": "2025-12-17T12:00:00Z"
}
```

**Errors:**
- 404: Сессия или пользователь не найдены
- 500: Ошибка сервера

---

### PUT /users/{user_id}/sessions/{session_id}

Обновить сессию (например, аннотации).

**Path Parameters:**
- `user_id`: UUID пользователя
- `session_id`: UUID сессии

**Request:**
```json
{
  "annotations": {
    "0": { ... },
    "1": { ... }
  }
}
```

**Response 200:**
```json
{
  "session_id": "uuid-string",
  "user_id": "uuid-string",
  ...
  "updated_at": "2025-12-17T12:05:00Z"
}
```

**Errors:**
- 404: Сессия или пользователь не найдены
- 400: Неверный формат данных
- 500: Ошибка сервера

---

### DELETE /users/{user_id}/sessions/{session_id}

Удалить сессию.

**Path Parameters:**
- `user_id`: UUID пользователя
- `session_id`: UUID сессии

**Response 204:**
Нет тела ответа.

**Errors:**
- 404: Сессия или пользователь не найдены
- 500: Ошибка сервера

---

## Common Error Format

Все ошибки возвращаются в едином формате:

```json
{
  "detail": "Описание ошибки",
  "error_code": "OPTIONAL_ERROR_CODE"
}
```

---

## Notes

1. Все даты в формате ISO 8601: `YYYY-MM-DDTHH:MM:SSZ`
2. UUID используется для идентификации пользователей и сессий
3. Все запросы должны включать `Content-Type: application/json`
4. Пустые строки в настройках означают "не задано" (опциональные поля)