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:

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

Response 200:

{
  "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:

{
  "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:

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

Response 200:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "annotations": {
    "0": { ... },
    "1": { ... }
  }
}

Response 200:

{
  "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

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

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

---

Notes

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