openapi: 3.0.3
info:
  title: ИИ-юрист
  description: API для системы ИИ-юриста с RAG функциональностью
  version: 1.0.0
  contact:
    name: API Support

servers:
  - url: http://localhost:8000
    description: Локальный сервер
  - url: http://backend:8000
    description: Docker контейнер

tags:
  - name: users
    description: Управление пользователями
  - name: collections
    description: Управление коллекциями документов
  - name: documents
    description: Управление документами
  - name: conversations
    description: Управление беседами
  - name: messages
    description: Управление сообщениями
  - name: rag
    description: RAG функциональность для ответов на вопросы
  - name: admin
    description: Административные функции

paths:
  /:
    get:
      summary: Корневой эндпоинт
      description: Информация об API
      tags: []
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Добро пожаловать в API ИИ-юриста
                  version:
                    type: string
                    example: "1.0.0"
                  docs:
                    type: string
                    example: /docs

  /health:
    get:
      summary: Проверка здоровья приложения
      description: Проверка работоспособности API
      tags: []
      responses:
        '200':
          description: Сервис работает
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok

  /api/v1/users:
    post:
      summary: Создать пользователя
      description: Создание нового пользователя в системе
      tags: [users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '201':
          description: Пользователь создан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

    get:
      summary: Получить список пользователей
      description: Получить список всех пользователей с пагинацией
      tags: [users]
      parameters:
        - name: skip
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: Список пользователей
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserResponse'

  /api/v1/users/me:
    get:
      summary: Получить информацию о текущем пользователе
      description: Получить информацию о текущем аутентифицированном пользователе
      tags: [users]
      security:
        - TelegramAuth: []
      responses:
        '200':
          description: Информация о пользователе
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/users/telegram/{telegram_id}:
    get:
      summary: Получить пользователя по Telegram ID
      description: Получить информацию о пользователе по его Telegram ID
      tags: [users]
      parameters:
        - name: telegram_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Информация о пользователе
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/users/telegram/{telegram_id}/increment-questions:
    post:
      summary: Увеличить счетчик использованных вопросов
      description: Увеличить счетчик использованных вопросов для пользователя
      tags: [users]
      parameters:
        - name: telegram_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Счетчик обновлен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/users/telegram/{telegram_id}/activate-premium:
    post:
      summary: Активировать premium статус
      description: Активировать premium подписку для пользователя
      tags: [users]
      parameters:
        - name: telegram_id
          in: path
          required: true
          schema:
            type: string
        - name: days
          in: query
          schema:
            type: integer
            default: 30
            minimum: 1
      responses:
        '200':
          description: Premium активирован
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/users/{user_id}:
    get:
      summary: Получить пользователя по ID
      description: Получить информацию о пользователе по его UUID
      tags: [users]
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Информация о пользователе
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      summary: Обновить пользователя
      description: Обновить информацию о пользователе
      tags: [users]
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
      responses:
        '200':
          description: Пользователь обновлен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      summary: Удалить пользователя
      description: Удалить пользователя из системы
      tags: [users]
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Пользователь удален
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/collections:
    post:
      summary: Создать коллекцию
      description: Создать новую коллекцию документов
      tags: [collections]
      security:
        - TelegramAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionCreate'
      responses:
        '201':
          description: Коллекция создана
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

    get:
      summary: Получить список коллекций
      description: Получить список коллекций, доступных текущему пользователю
      tags: [collections]
      security:
        - TelegramAuth: []
      parameters:
        - name: skip
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: Список коллекций
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CollectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/collections/{collection_id}:
    get:
      summary: Получить коллекцию по ID
      description: Получить информацию о коллекции
      tags: [collections]
      security:
        - TelegramAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Информация о коллекции
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      summary: Обновить коллекцию
      description: Обновить информацию о коллекции (только владелец)
      tags: [collections]
      security:
        - TelegramAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionUpdate'
      responses:
        '200':
          description: Коллекция обновлена
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      summary: Удалить коллекцию
      description: Удалить коллекцию (только владелец)
      tags: [collections]
      security:
        - TelegramAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Коллекция удалена
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/collections/{collection_id}/access:
    post:
      summary: Предоставить доступ к коллекции
      description: Предоставить доступ пользователю к коллекции (только владелец)
      tags: [collections]
      security:
        - TelegramAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionAccessGrant'
      responses:
        '201':
          description: Доступ предоставлен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionAccessResponse'
        '403':
          $ref: '#/components/responses/Forbidden'

    get:
      summary: Получить список пользователей с доступом
      description: Получить список пользователей, имеющих доступ к коллекции
      tags: [collections]
      security:
        - TelegramAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Список пользователей с доступом
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CollectionAccessListResponse'

  /api/v1/collections/{collection_id}/access/{user_id}:
    delete:
      summary: Отозвать доступ к коллекции
      description: Отозвать доступ пользователя к коллекции (только владелец)
      tags: [collections]
      security:
        - TelegramAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Доступ отозван
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/v1/collections/{collection_id}/access/telegram/{telegram_id}:
    post:
      summary: Предоставить доступ по Telegram ID
      description: Предоставить доступ пользователю к коллекции по Telegram ID
      tags: [collections]
      security:
        - TelegramAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: telegram_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Доступ предоставлен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionAccessResponse'

    delete:
      summary: Отозвать доступ по Telegram ID
      description: Отозвать доступ пользователя к коллекции по Telegram ID
      tags: [collections]
      security:
        - TelegramAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: telegram_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Доступ отозван

  /api/v1/documents:
    post:
      summary: Создать документ
      description: Создать новый документ в коллекции
      tags: [documents]
      security:
        - TelegramAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentCreate'
      responses:
        '201':
          description: Документ создан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/v1/documents/upload:
    post:
      summary: Загрузить документ
      description: Загрузить и распарсить PDF документ или изображение с автоматической индексацией
      tags: [documents]
      security:
        - TelegramAuth: []
      parameters:
        - name: collection_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
              required:
                - file
      responses:
        '201':
          description: Документ загружен и проиндексирован
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '400':
          description: Неподдерживаемый формат файла
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/v1/documents/{document_id}:
    get:
      summary: Получить документ по ID
      description: Получить информацию о документе
      tags: [documents]
      parameters:
        - name: document_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Информация о документе
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      summary: Обновить документ
      description: Обновить информацию о документе
      tags: [documents]
      security:
        - TelegramAuth: []
      parameters:
        - name: document_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentUpdate'
      responses:
        '200':
          description: Документ обновлен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      summary: Удалить документ
      description: Удалить документ (только владелец коллекции)
      tags: [documents]
      security:
        - TelegramAuth: []
      parameters:
        - name: document_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Документ удален
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/documents/collection/{collection_id}:
    get:
      summary: Получить документы коллекции
      description: Получить список документов в коллекции
      tags: [documents]
      security:
        - TelegramAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: skip
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: Список документов
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentResponse'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/v1/conversations:
    post:
      summary: Создать беседу
      description: Создать новую беседу для коллекции
      tags: [conversations]
      security:
        - TelegramAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationCreate'
      responses:
        '201':
          description: Беседа создана
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

    get:
      summary: Получить список бесед
      description: Получить список бесед текущего пользователя
      tags: [conversations]
      security:
        - TelegramAuth: []
      parameters:
        - name: skip
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: Список бесед
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConversationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/conversations/{conversation_id}:
    get:
      summary: Получить беседу по ID
      description: Получить информацию о беседе
      tags: [conversations]
      security:
        - TelegramAuth: []
      parameters:
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Информация о беседе
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      summary: Удалить беседу
      description: Удалить беседу (только владелец)
      tags: [conversations]
      security:
        - TelegramAuth: []
      parameters:
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Беседа удалена
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/messages:
    post:
      summary: Создать сообщение
      description: Создать новое сообщение в беседе
      tags: [messages]
      security:
        - TelegramAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageCreate'
      responses:
        '201':
          description: Сообщение создано
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/messages/{message_id}:
    get:
      summary: Получить сообщение по ID
      description: Получить информацию о сообщении
      tags: [messages]
      parameters:
        - name: message_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Информация о сообщении
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      summary: Обновить сообщение
      description: Обновить содержимое сообщения
      tags: [messages]
      parameters:
        - name: message_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageUpdate'
      responses:
        '200':
          description: Сообщение обновлено
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      summary: Удалить сообщение
      description: Удалить сообщение
      tags: [messages]
      parameters:
        - name: message_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Сообщение удалено
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/messages/conversation/{conversation_id}:
    get:
      summary: Получить сообщения беседы
      description: Получить список сообщений в беседе
      tags: [messages]
      security:
        - TelegramAuth: []
      parameters:
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: skip
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: Список сообщений
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MessageResponse'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/v1/rag/question:
    post:
      summary: Задать вопрос через RAG
      description: Получить ответ на вопрос используя RAG (Retrieval-Augmented Generation)
      tags: [rag]
      security:
        - TelegramAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuestionRequest'
      responses:
        '200':
          description: Ответ сгенерирован
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RAGAnswer'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/admin/users:
    get:
      summary: Получить список всех пользователей (админ)
      description: Получить список всех пользователей в системе (только для администраторов)
      tags: [admin]
      security:
        - TelegramAuth: []
      parameters:
        - name: skip
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: Список пользователей
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserResponse'
        '403':
          description: Требуются права администратора
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/admin/collections:
    get:
      summary: Получить список всех коллекций (админ)
      description: Получить список всех коллекций в системе (только для администраторов)
      tags: [admin]
      security:
        - TelegramAuth: []
      parameters:
        - name: skip
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: Список коллекций
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CollectionResponse'
        '403':
          description: Требуются права администратора
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  securitySchemes:
    TelegramAuth:
      type: apiKey
      in: header
      name: X-Telegram-ID
      description: Telegram ID пользователя для аутентификации

  schemas:
    UserRole:
      type: string
      enum: [user, admin]
      description: Роль пользователя

    UserCreate:
      type: object
      required:
        - telegram_id
        - role
      properties:
        telegram_id:
          type: string
          description: Telegram ID пользователя
          example: "123456789"
        role:
          $ref: '#/components/schemas/UserRole'

    UserUpdate:
      type: object
      properties:
        telegram_id:
          type: string
          description: Telegram ID пользователя
        role:
          $ref: '#/components/schemas/UserRole'

    UserResponse:
      type: object
      properties:
        user_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        telegram_id:
          type: string
          example: "123456789"
        role:
          $ref: '#/components/schemas/UserRole'
        created_at:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"
        is_premium:
          type: boolean
          default: false
          description: Является ли пользователь premium
        premium_until:
          type: string
          format: date-time
          nullable: true
          description: Дата окончания premium подписки
        questions_used:
          type: integer
          default: 0
          description: Количество использованных вопросов

    CollectionCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Название коллекции
          example: "Юридические документы"
        description:
          type: string
          default: ""
          description: Описание коллекции
          example: "Коллекция юридических документов"
        is_public:
          type: boolean
          default: false
          description: Публичная ли коллекция

    CollectionUpdate:
      type: object
      properties:
        name:
          type: string
          description: Название коллекции
        description:
          type: string
          description: Описание коллекции
        is_public:
          type: boolean
          description: Публичная ли коллекция

    CollectionResponse:
      type: object
      properties:
        collection_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        name:
          type: string
          example: "Юридические документы"
        description:
          type: string
          example: "Коллекция юридических документов"
        owner_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        is_public:
          type: boolean
          example: false
        created_at:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"

    CollectionAccessGrant:
      type: object
      required:
        - user_id
      properties:
        user_id:
          type: string
          format: uuid
          description: ID пользователя для предоставления доступа

    CollectionAccessResponse:
      type: object
      properties:
        access_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        collection_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time

    CollectionAccessUserInfo:
      type: object
      properties:
        user_id:
          type: string
          format: uuid
        telegram_id:
          type: string
        role:
          type: string
        created_at:
          type: string
          format: date-time

    CollectionAccessListResponse:
      type: object
      properties:
        access_id:
          type: string
          format: uuid
        user:
          $ref: '#/components/schemas/CollectionAccessUserInfo'
        collection_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time

    DocumentCreate:
      type: object
      required:
        - collection_id
        - title
        - content
      properties:
        collection_id:
          type: string
          format: uuid
          description: ID коллекции
        title:
          type: string
          description: Название документа
          example: "Гражданский кодекс РФ"
        content:
          type: string
          description: Содержимое документа
          example: "Статья 1. Гражданское законодательство..."
        metadata:
          type: object
          additionalProperties: true
          default: {}
          description: Дополнительные метаданные

    DocumentUpdate:
      type: object
      properties:
        title:
          type: string
          description: Название документа
        content:
          type: string
          description: Содержимое документа
        metadata:
          type: object
          additionalProperties: true
          description: Дополнительные метаданные

    DocumentResponse:
      type: object
      properties:
        document_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        collection_id:
          type: string
          format: uuid
        title:
          type: string
          example: "Гражданский кодекс РФ"
        content:
          type: string
          example: "Статья 1. Гражданское законодательство..."
        metadata:
          type: object
          additionalProperties: true
          example:
            filename: "document.pdf"
        created_at:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"

    ConversationCreate:
      type: object
      required:
        - collection_id
      properties:
        collection_id:
          type: string
          format: uuid
          description: ID коллекции для беседы

    ConversationResponse:
      type: object
      properties:
        conversation_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        user_id:
          type: string
          format: uuid
        collection_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"

    MessageRole:
      type: string
      enum: [user, assistant, system]
      description: Роль сообщения

    MessageCreate:
      type: object
      required:
        - conversation_id
        - content
        - role
      properties:
        conversation_id:
          type: string
          format: uuid
          description: ID беседы
        content:
          type: string
          description: Содержимое сообщения
          example: "Какие права имеет работник?"
        role:
          $ref: '#/components/schemas/MessageRole'
        sources:
          type: object
          additionalProperties: true
          default: {}
          description: Источники для сообщения

    MessageUpdate:
      type: object
      properties:
        content:
          type: string
          description: Содержимое сообщения
        sources:
          type: object
          additionalProperties: true
          description: Источники для сообщения

    MessageResponse:
      type: object
      properties:
        message_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        conversation_id:
          type: string
          format: uuid
        content:
          type: string
          example: "Работник имеет следующие права..."
        role:
          $ref: '#/components/schemas/MessageRole'
        sources:
          type: object
          additionalProperties: true
          example:
            chunks:
              - document_id: "123e4567-e89b-12d3-a456-426614174000"
                chunk_id: "456e7890-e12b-34c5-d678-901234567890"
        created_at:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"

    QuestionRequest:
      type: object
      required:
        - conversation_id
        - question
      properties:
        conversation_id:
          type: string
          format: uuid
          description: ID беседы
          example: "123e4567-e89b-12d3-a456-426614174000"
        question:
          type: string
          minLength: 3
          description: Вопрос пользователя
          example: "Какие права имеет работник при увольнении?"
        top_k:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
          description: Количество кандидатов для векторного поиска
        rerank_top_n:
          type: integer
          default: 5
          minimum: 1
          maximum: 20
          description: Количество релевантных чанков после реранкинга

    RAGSource:
      type: object
      properties:
        index:
          type: integer
          description: Порядковый номер источника
          example: 1
        document_id:
          type: string
          format: uuid
          description: ID документа
          example: "123e4567-e89b-12d3-a456-426614174000"
        chunk_id:
          type: string
          format: uuid
          description: ID чанка
          example: "456e7890-e12b-34c5-d678-901234567890"
        title:
          type: string
          nullable: true
          description: Название документа
          example: "Трудовой кодекс РФ"

    RAGAnswer:
      type: object
      properties:
        answer:
          type: string
          description: Сгенерированный ответ на вопрос
          example: "Работник при увольнении имеет право на..."
        sources:
          type: array
          items:
            $ref: '#/components/schemas/RAGSource'
          description: Список источников, использованных для генерации ответа
        usage:
          type: object
          additionalProperties: true
          description: Информация об использовании токенов
          example:
            prompt_tokens: 150
            completion_tokens: 250
            total_tokens: 400

    Error:
      type: object
      properties:
        detail:
          type: string
          description: Описание ошибки
          example: "Ресурс не найден"

  responses:
    BadRequest:
      description: Неверный запрос
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: "Неверные параметры запроса"

    Unauthorized:
      description: Не авторизован
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: "Требуется аутентификация"

    Forbidden:
      description: Доступ запрещен
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: "У вас нет доступа к этому ресурсу"

    NotFound:
      description: Ресурс не найден
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: "Ресурс не найден"

    InternalServerError:
      description: Внутренняя ошибка сервера
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: "Внутренняя ошибка сервера"