openapi: 3.0.3
info:
  title: Legal RAG AI API
  description: API для юридического AI-ассистента. Обеспечивает работу RAG-пайплайна (поиск + генерация), управление коллекциями документов и биллинг.
  version: 1.0.0
servers:
  - url: http://localhost:8000/api/v1
    description: Local Development Server
tags:
  - name: Auth & Users
    description: Управление пользователями и проверка лимитов
  - name: RAG & Chat
    description: Основной функционал (чат, поиск)
  - name: Collections
    description: Управление базами знаний
  - name: Billing
    description: Платежи
paths:
  /users/register:
    post:
      tags:
        - Auth & Users
      summary: Регистрация/Вход пользователя через Telegram
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserAuthRequest'
      responses:
        '200':
          description: Успешная авторизация
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
  /users/me:
    get:
      tags:
        - Auth & Users
      summary: Получить профиль пользователя
      parameters:
        - in: header
          name: X-Telegram-ID
          schema:
            type: string
          required: true
          description: Telegram ID пользователя
      responses:
        '200':
          description: Профиль пользователя
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '403':
          description: Доступ запрещен
  /chat/ask:
    post:
      tags:
        - RAG & Chat
      summary: Задать вопрос юристу
      parameters:
        - in: header
          name: X-Telegram-ID
          schema:
            type: string
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
      responses:
        '200':
          description: Ответ сгенерирован
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
        '402':
          description: Лимит бесплатных запросов исчерпан
  /chat/history:
    get:
      tags:
        - RAG & Chat
      summary: Получить историю диалога
      parameters:
        - in: query
          name: conversation_id
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          description: Список сообщений
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MessageDTO'
  /collections:
    get:
      tags:
        - Collections
      summary: Список доступных коллекций
      parameters:
        - in: header
          name: X-Telegram-ID
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Список коллекций
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CollectionDTO'
    post:
      tags:
        - Collections
      summary: Создать новую коллекцию
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCollectionRequest'
      responses:
        '201':
          description: Коллекция создана
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionDTO'
  /collections/{collection_id}/upload:
    post:
      tags:
        - Collections
      summary: Загрузка документа в коллекцию
      parameters:
        - in: path
          name: collection_id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '202':
          description: Файл принят в обработку
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_id:
                    type: string
                  status:
                    type: string
  /billing/create-payment:
    post:
      tags:
        - Billing
      summary: Создать ссылку на оплату
      parameters:
        - in: header
          name: X-Telegram-ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Ссылка сформирована
          content:
            application/json:
              schema:
                type: object
                properties:
                  payment_url:
                    type: string
                  payment_id:
                    type: string
  /billing/webhook:
    post:
      tags:
        - Billing
      summary: Вебхук от платежной системы
      responses:
        '200':
          description: OK
components:
  schemas:
    UserAuthRequest:
      type: object
      required:
        - telegram_id
      properties:
        telegram_id:
          type: string
          example: "123456789"
        username:
          type: string
        first_name:
          type: string
    UserResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        telegram_id:
          type: string
        role:
          type: string
          enum:
            - user
            - admin
        request_count:
          type: integer
        is_premium:
          type: boolean
    ChatRequest:
      type: object
      required:
        - query
        - collection_id
      properties:
        query:
          type: string
          example: "Какая ответственность за неуплату НДС?"
        collection_id:
          type: string
          format: uuid
        conversation_id:
          type: string
          format: uuid
          nullable: true
    ChatResponse:
      type: object
      properties:
        answer:
          type: string
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
        conversation_id:
          type: string
          format: uuid
        request_count_left:
          type: integer
    Source:
      type: object
      properties:
        title:
          type: string
        page:
          type: integer
        relevance_score:
          type: number
          format: float
        snippet:
          type: string
    MessageDTO:
      type: object
      properties:
        role:
          type: string
          enum:
            - user
            - ai
        content:
          type: string
        created_at:
          type: string
          format: date-time
    CollectionDTO:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        is_public:
          type: boolean
        owner_id:
          type: string
          format: uuid
    CreateCollectionRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
        is_public:
          type: boolean
          default: false