no-copy/infrastructure/open-api-controller.yaml

openapi: 3.0.3
info:
  title: NoCopy API
  description: |
    Основной API для работы с файлами, загрузкой, поиском и управлением данными.
    Включает контроллеры:
    - ApiController (основная обработка данных, файлы, поиск)
    - FileController (загрузка и скачивание файлов)
  version: 1.0.0
  contact:
    name: NoCopy

servers:
  - url: http://localhost:8080
    description: Локальный
  - url: https://dev-workspace.not-copy.com/
    description: Дев

tags:
  - name: Auth
    description: Аутентификация и регистрация
  - name: Files
    description: Работа с файлами (загрузка, скачивание, проверка)
  - name: Data
    description: Основные операции с данными
  - name: Internal
    description: Внутренние эндпоинты для администрирования

paths:
  /api/auth:
    post:
      tags:
        - Auth
      summary: Универсальный эндпоинт аутентификации
      description: |
        Обрабатывает запросы аутентификации по msg_id:
        - **20001** - Вход в систему
        - **20002** - Регистрация 
        - **20010** - Сброс пароля
      operationId: handleAuth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseRequest'
            examples:
              login:
                summary: Вход в систему
                value:
                  msg_id: 20001
                  message_body:
                    email: "user@example.com"
                    password: "securePassword123"
              register:
                summary: Регистрация
                value:
                  msg_id: 20002
                  message_body:
                    fullName: "Vladislav Sergevich"
                    email: "321@mail.ru"
                    password: "qweqweqwe123"
                    phone: "+79994521523"
                    mail_verified: "false"
                    accountType: "b2c"
                    ip: "127.0.0.1"
                    user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko)"
              resetPassword:
                summary: Сброс пароля
                value:
                  version: 1
                  msg_id: 20010
                  message_body:
                    email: "user@example.com"
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              examples:
                loginSuccess:
                  summary: Успешный вход
                  value:
                    msg_id: 20001
                    message_code: 0
                    message_desc: "Operation successful"
                    message_body:
                      token: "eyJhbGciOiJIUzI1NiIs..."
                      user_id: 123
                invalidCredentials:
                  summary: Неверные учетные данные
                  value:
                    msg_id: 20001
                    message_code: 2
                    message_desc: "Invalid credentials"
                    message_body: {}
                userNotFound:
                  summary: Пользователь не найден
                  value:
                    msg_id: 20010
                    message_code: 2
                    message_desc: "User not found"
                    message_body: {}

  /api/internal/data-info:
    post:
      tags:
        - Internal
      summary: Внутренняя информация (статистика)
      description: |
        Эндпоинт для получения внутренней статистики и информации.
      operationId: handleInternalInfo
      parameters:
        - name: X-Internal-Key
          in: header
          required: true
          description: Внутренний ключ для доступа к API
          schema:
            type: string
            example: "your-internal-key-here"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseRequest'
            examples:
              userInfo:
                summary: Информация о пользователе
                value:
                  msg_id: 30014
                  message_body:
                    user_id: 123
              userFileInfo:
                summary: Информация по файлам
                value:
                  msg_id: 30019
                  message_body:
                    top: 10
                    type: "image"
              tariffStatistic:
                summary: Информация по тарифам
                value:
                  msg_id: 30020
                  message_body:
                    active_only: true
              dynamicStatistic:
                summary: Динамика
                value:
                  msg_id: 30021
              fileUserStatistic:
                summary: Статистика по файлам пользователей
                value:
                  msg_id: 30022
                  message_body:
                    active_only: true
              violations:
                summary: Нарушения
                value:
                  msg_id: 30023
              subscribesStatistic:
                summary: Подписки
                value:
                  msg_id: 30024
              tokenStatistic:
                summary: Статистика токенов
                value:
                  msg_id: 30025
              incomingStatistic:
                summary: Доходы статистика
                value:
                  msg_id: 30026
              complaintStatistic:
                summary: Жалобы
                value:
                  msg_id: 30029
              filesInfo:
                summary: Информация о файлах
                value:
                  msg_id: 40001
                  message_body:
                    action: "get_all"
                    page: 1
                    page_size: 10
                    sort_by: "createdAt"
                    sort_direction: "desc"
              tariffsInfo:
                summary: Информация о тарифах
                value:
                  msg_id: 40004
                  message_body:
                    action: "get_all"
                    page: 1
                    page_size: 10
                    sort_by: "createdAt"
                    sort_direction: "desc"
      responses:
        '200':
          description: Ответ с запрашиваемой информацией
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'

  /api/internal/data-control:
    post:
      tags:
        - Internal
      summary: Управление контентом
      description: Эндпоинт для модерации и управления контентом.
      operationId: handleInternalControl
      parameters:
        - name: X-Internal-Key
          in: header
          required: true
          description: Внутренний ключ для доступа к API
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseRequest'
            examples:
              userInfoGetAll:
                summary: Получить всех пользователей с пагинацией
                value:
                  msg_id: 30014
                  message_body:
                    action: "getAllWithPagination"
                    page: 0
                    size: 10
                    sort_by: "createdAt"
                    sort_direction: "desc"
              userInfoGetById:
                summary: Получить информацию о пользователе по ID
                value:
                  msg_id: 30014
                  message_body:
                    action: "getInfoById"
                    user_id: 123
              userInfoUpdate:
                summary: Обновить дополнительную информацию пользователя
                value:
                  msg_id: 30014
                  message_body:
                    action: "update"
                    user_id: 123
                    ip_address: "192.168.1.1"
                    user_agent: "Mozilla/5.0"
              userInfoDelete:
                summary: Удалить дополнительную информацию пользователя
                value:
                  msg_id: 30014
                  message_body:
                    action: "delete"
                    user_id: 123
              complaintCreate:
                summary: Создать жалобу
                value:
                  msg_id: 30030
                  message_body:
                    action: "create"
                    violation_id: 456
                    complaint_text: "Нарушение правил использования"
              complaintUpdateStatus:
                summary: Обновить статус жалобы
                value:
                  msg_id: 30030
                  message_body:
                    action: "update_status"
                    id: "complaint-uuid"
                    status: "RESOLVED"
              complaintUpdate:
                summary: Обновить жалобу
                value:
                  msg_id: 30030
                  message_body:
                    action: "update"
                    id: "complaint-uuid"
                    complaint_text: "Обновленный текст жалобы"
              complaintDelete:
                summary: Удалить жалобу
                value:
                  msg_id: 30030
                  message_body:
                    action: "delete"
                    id: "complaint-uuid"
              fileModerate:
                summary: Модерировать файл
                value:
                  msg_id: 40002
                  message_body:
                    action: "moderate_file"
                    file_id: "file-uuid"
                    file_status: "APPROVED"
                    comment: "Файл проверен"
              fileChangeStatus:
                summary: Изменить статус файла
                value:
                  msg_id: 40002
                  message_body:
                    action: "change_file_status"
                    file_id: "file-uuid"
                    file_status: "BLOCKED"
              fileReviewAppeal:
                summary: Рассмотреть апелляцию
                value:
                  msg_id: 40002
                  message_body:
                    action: "review_appeal"
                    appeal_id: "appeal-uuid"
                    approve: true
                    comment: "Апелляция одобрена"
              tariffAdd:
                summary: Добавить тариф
                value:
                  msg_id: 40003
                  message_body:
                    action: "add"
                    name: "Premium"
                    price: 999.99
                    type: "MONTHLY"
                    tokens: 1000
                    disk_size: 50
                    max_users: 5
                    max_files_count: 100
                    tariff_term: "MONTHLY"
                    description: "Премиум тариф"
                    account_type: "PREMIUM"
              tariffRemove:
                summary: Удалить тариф
                value:
                  msg_id: 40003
                  message_body:
                    action: "remove"
                    id: "tariff-uuid"
              tariffUpdate:
                summary: Обновить тариф
                value:
                  msg_id: 40003
                  message_body:
                    action: "update"
                    id: "tariff-uuid"
                    name: "Premium Plus"
                    price: 1499.99
                    description: "Обновленный премиум тариф"
      responses:
        '200':
          description: Результат операции управления
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '401':
          description: Неверный или отсутствующий внутренний ключ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'

  /api/internal/data-download/{fileId}:
    get:
      tags:
        - Internal
      summary: Внутреннее скачивание файла
      description: Прямое скачивание файла из хранилища для внутренних нужд
      operationId: internalDownloadFile
      parameters:
        - name: X-Internal-Key
          in: header
          required: true
          description: Внутренний ключ для доступа к API
          schema:
            type: string
        - name: fileId
          in: path
          required: true
          schema:
            type: string
          description: ID файла
      responses:
        '200':
          description: Файл
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: Файл не найден

  /api/v{version}/data:
    post:
      tags:
        - Data
      summary: Основной эндпоинт обработки данных
      description: |
        Обрабатывает запросы по msg_id. Доступные операции:
        
        **Файлы:**
        - **20004** - Инициализация загрузки/информация о типах файлов/статус чанков (FileUploadHandler)
        - **20005** - Операции с файлами (FileEntityHandler)
        - **20007** - Поиск по изображению (ImageFoundRequestHandler)
        
        **Пользователи:**
        - **20009** - Верификация регистрации (VerifyRegisterUserHandler)
        - **30014** - Информация о пользователе (UserInfoHandler)
        - **30016** - Верификация пользователя (UserVerificationHandler)
        
        **Компании и тарифы:**
        - **30000** - Управление компанией (CompanyHandler)
        - **30001** - Управление тарифами (TariffHandler)
        - **30002** - Информация о тарифах (TariffInfoHandler)
        - **30003** - Реферальная система (ReferralHandler)
        
        **Платежи:**
        - **30005** - Платежи (PaymentHandler)
        
        **Мониторинг и нарушения:**
        - **30007** - Мониторинг (MonitoringHandler)
        - **30009** - Нарушения (ViolationHandler)
        - **30010** - Статистика нарушений (ViolationStatisticsHandler)
        - **30027** - Статистика мониторинга (MonitoringStatisticHandler)
        
        **Поиск и жалобы:**
        - **30011** - Глобальный поиск (GlobalSearchHandler)
        - **30012** - Уведомления о нарушениях (ViolationNotionHandler)
        - **30013** - Жалобы (ComplaintEntityHandler)
        
        **Уведомления:**
        - **30015** - Уведомления (NotificationHandler)
        
        **Юридические дела:**
        - **30017** - Управление делами (LawCaseHandler)
        
        **Токены:**
        - **30018** - Операции с токенами (TokenOperationHandler)
        
        **Просмотр документов:**
        - **30028** - Просмотр документов (DockViewFileHandler)
      operationId: handleDataRequest
      parameters:
        - name: version
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: Версия API
          example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseRequest'
            examples:
              fileUploadInit:
                summary: "[20004] Инициализация загрузки файла"
                value:
                  msg_id: 20004
                  message_body:
                    action: "init"
                    file_name: "document.pdf"
                    file_type: "document"
                    extension: "pdf"
                    convertTo: "protected"
                    file_size: 1048576
              fileTypes:
                summary: "[20004] Получение типов файлов"
                value:
                  msg_id: 20004
                  message_body:
                    action: "file_types"
              fileExtensions:
                summary: "[20004] Получение расширений для типа"
                value:
                  msg_id: 20004
                  message_body:
                    action: "file_extension"
                    file_type: "image"
              fileUploadChunks:
                summary: "[20004] Статус чанков загрузки"
                value:
                  msg_id: 20004
                  message_body:
                    action: "chunks"
                    upload_id: "550e8400-e29b-41d4-a716-446655440000"
              fileUploadCancel:
                summary: "[20004] Отмена загрузки"
                value:
                  msg_id: 20004
                  message_body:
                    action: "cancel"
                    upload_id: "550e8400-e29b-41d4-a716-446655440000"
              fileUploadProgress:
                summary: "[20004] Прогресс загрузки"
                value:
                  msg_id: 20004
                  message_body:
                    action: "progress"
                    upload_id: "550e8400-e29b-41d4-a716-446655440000"

              fileInfo:
                summary: "[20005] Информация о файле"
                value:
                  msg_id: 20005
                  message_body:
                    action: "file_info"
                    file_id: "550e8400-e29b-41d4-a716-446655440000"
              userFilesInfo:
                summary: "[20005] Статистика по файлам пользователя"
                value:
                  msg_id: 20005
                  message_body:
                    action: "user_files_info"
              userFiles:
                summary: "[20005] Список файлов пользователя"
                value:
                  msg_id: 20005
                  message_body:
                    action: "user_files"
                    page: 1
                    page_size: 20
              searchFiles:
                summary: "[20005] Поиск файлов с фильтрацией"
                value:
                  msg_id: 20005
                  message_body:
                    action: "search_files"
                    query: "документ"
                    type: "application/pdf"
                    statuses: ["ACTIVE", "BLOCKED"]
                    date_filter: "month"
                    sort_by: "createdAt"
                    sort_order: "desc"
                    page: 1
                    page_size: 20
              storageUsage:
                summary: "[20005] Использование дискового пространства"
                value:
                  msg_id: 20005
                  message_body:
                    action: "storage_usage"
              deleteFile:
                summary: "[20005] Удаление файла"
                value:
                  msg_id: 20005
                  message_body:
                    action: "delete_file"
                    file_id: "550e8400-e29b-41d4-a716-446655440000"
              changePermission:
                summary: "[20005] Изменение прав доступа"
                value:
                  msg_id: 20005
                  message_body:
                    action: "change_permission"
                    file_id: "550e8400-e29b-41d4-a716-446655440000"
                    permissions:
                      VIEW: true
                      DOWNLOAD: false

              imageSearch:
                summary: "[20007] Поиск изображения"
                value:
                  msg_id: 20007
                  message_body:
                    file_id: "550e8400-e29b-41d4-a716-446655440000"

              verifyUser:
                summary: "[20009] Верификация пользователя"
                value:
                  msg_id: 20009
                  message_body:
                    user_id: 123
                    verify_token: "abc123def456"

              companyCreate:
                summary: "[30000] Создание компании"
                value:
                  msg_id: 30000
                  message_body:
                    action: "create"
                    company_name: "ООО Моя Компания"
                    company_data:
                      phone: "+79991234567"
                      email: "info@company.ru"
              companyGetById:
                summary: "[30000] Получение компании по ID"
                value:
                  msg_id: 30000
                  message_body:
                    action: "getCompany"
                    company_id: "company-uuid-123"

              tariffAdd:
                summary: "[30001] Добавление тарифа"
                value:
                  msg_id: 30001
                  message_body:
                    action: "add"
                    type: "MONTHLY"
                    tariff_name: "Премиум"
                    tariff_price: 999.99

              tariffInfoCreate:
                summary: "[30002] Создание информации о тарифе"
                value:
                  msg_id: 30002
                  message_body:
                    action: "create"
                    tariff_id: 1

              referralUserStats:
                summary: "[30003] Статистика пользователя"
                value:
                  msg_id: 30003
                  message_body:
                    action: "userStats"

              paymentUserPayments:
                summary: "[30005] Список платежей"
                value:
                  msg_id: 30005
                  message_body:
                    action: "user_payments"
                    email: "user@example.com"

              monitoringSet:
                summary: "[30007] Установка мониторинга"
                value:
                  msg_id: 30007
                  message_body:
                    file_id: "550e8400-e29b-41d4-a716-446655440000"
                    monitoring_type: "MONITORING_DAILY"

              violationList:
                summary: "[30009] Список нарушений"
                value:
                  msg_id: 30009
                  message_body:
                    action: "list"
                    page: 0
                    size: 10

              violationStats:
                summary: "[30010] Статистика нарушений"
                value:
                  msg_id: 30010
                  message_body: {}

              globalSearch:
                summary: "[30011] Глобальный поиск"
                value:
                  msg_id: 30011
                  message_body:
                    query: "изображение кота"
                    filters:
                      file_type: "image"

              notionAdd:
                summary: "[30012] Добавление заметки"
                value:
                  msg_id: 30012
                  message_body:
                    action: "add_notion"
                    violation_id: 1
                    message: "Текст заметки"

              complaintCreate:
                summary: "[30013] Создание жалобы"
                value:
                  msg_id: 30013
                  message_body:
                    action: "create"
                    violation_id: 1
                    text: "Текст жалобы"

              userInfoGetAllPaginated:
                summary: "[30014] Получить всех пользователей с пагинацией"
                value:
                  msg_id: 30014
                  message_body:
                    action: "getAllWithPagination"
                    page: 0
                    size: 10

              notificationList:
                summary: "[30015] Список уведомлений"
                value:
                  msg_id: 30015
                  message_body:
                    action: "list"
                    page: 0
                    size: 10

              userVerificationVerify:
                summary: "[30016] Верифицировать пользователя"
                value:
                  msg_id: 30016
                  message_body:
                    action: "verified"
                    user_id: 123
                    verified: true

              lawCaseCreate:
                summary: "[30017] Создать юридическое дело"
                value:
                  msg_id: 30017
                  message_body:
                    action: "create"
                    name: "Дело о нарушении"
                    description: "Описание дела"
                    priority: "HIGH"
                    violation_id: 1

              tokenOpGetList:
                summary: "[30018] Список операций с токенами"
                value:
                  msg_id: 30018
                  message_body:
                    action: "get_list"
                    page: 0
                    size: 20

              monitoringStatistic:
                summary: "[30027] Статистика мониторинга"
                value:
                  msg_id: 30027
                  message_body: {}

              dockViewHistory:
                summary: "[30028] История просмотров документов"
                value:
                  msg_id: 30028
                  message_body:
                    action: "history_view"
                    page: 0
                    size: 10

      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              examples:
                fileUploadInitSuccess:
                  summary: "[20004] Успешная инициализация загрузки"
                  value:
                    msg_id: 20004
                    message_code: 0
                    message_desc: "Operation successful"
                    message_body:
                      upload_id: "550e8400-e29b-41d4-a716-446655440000"
                      file_name: "document.pdf"
                      total_chunks: 5
                      chunk_size: 209715
                      status: "INITIALIZED"
                fileTypesSuccess:
                  summary: "[20004] Типы файлов"
                  value:
                    msg_id: 20004
                    message_code: 0
                    message_desc: "Operation successful"
                    message_body:
                      file_types: ["IMAGE", "DOCUMENT", "AUDIO"]
                      count: 3

                fileInfoSuccess:
                  summary: "[20005] Информация о файле"
                  value:
                    msg_id: 20005
                    message_code: 0
                    message_desc: "Operation successful"
                    message_body:
                      id: "550e8400-e29b-41d4-a716-446655440000"
                      file_name: "document.pdf"
                      status: "ACTIVE"

                imageSearchSuccess:
                  summary: "[20007] Результаты поиска изображений"
                  value:
                    msg_id: 20007
                    message_code: 0
                    message_desc: "Operation successful"
                    message_body:
                      images:
                        - url: "https://example.com/similar-image.jpg"
                          title: "Похожее изображение"
                      page: 1
                      total_results: 25

                verifySuccess:
                  summary: "[20009] Успешная верификация"
                  value:
                    msg_id: 20009
                    message_code: 0
                    message_desc: "Operation successful"
                    message_body:
                      token: "eyJhbGciOiJIUzI1NiIs..."
                      verified: true
                      email: "user@example.com"

                companyCreateSuccess:
                  summary: "[30000] Компания создана"
                  value:
                    msg_id: 30000
                    message_code: 0
                    message_desc: "Company created successfully"
                    message_body:
                      id: "company-uuid-123"
                      company_name: "ООО Моя Компания"

                tariffAddSuccess:
                  summary: "[30001] Тариф добавлен"
                  value:
                    msg_id: 30001
                    message_code: 0
                    message_desc: "Tariff added successfully"
                    message_body:
                      tariff_name: "Премиум"
                      tariff_type: "MONTHLY"

                referralUserStatsSuccess:
                  summary: "[30003] Статистика пользователя"
                  value:
                    msg_id: 30003
                    message_code: 0
                    message_desc: "Operation successful"
                    message_body:
                      total_invitees: 15
                      total_earned: 5000.00

                paymentUserPaymentsSuccess:
                  summary: "[30005] Список платежей"
                  value:
                    msg_id: 30005
                    message_code: 0
                    message_desc: "Operation successful"
                    message_body:
                      payments:
                        - payment_uuid: "payment-uuid-123"
                          amount: 999.99

                monitoringSetSuccess:
                  summary: "[30007] Мониторинг установлен"
                  value:
                    msg_id: 30007
                    message_code: 0
                    message_desc: "Monitoring settings updated"
                    message_body:
                      file_id: "550e8400-e29b-41d4-a716-446655440000"
                      monitoring_type: "MONITORING_DAILY"

                violationListSuccess:
                  summary: "[30009] Список нарушений"
                  value:
                    msg_id: 30009
                    message_code: 0
                    message_desc: "Operation successful"
                    message_body:
                      violations: []
                      total_elements: 25

                globalSearchStatsSuccess:
                  summary: "[30011] Статистика глобального поиска"
                  value:
                    msg_id: 30011
                    message_code: 0
                    message_desc: ""
                    message_body:
                      total_searches: 150

                complaintCreateSuccess:
                  summary: "[30013] Жалоба создана"
                  value:
                    msg_id: 30013
                    message_code: 0
                    message_desc: "Complaint created successfully"
                    message_body:
                      id: 1
                      status: "OPEN"

                notificationListSuccess:
                  summary: "[30015] Список уведомлений"
                  value:
                    msg_id: 30015
                    message_code: 0
                    message_desc: "Operation successful"
                    message_body:
                      notifications: []
                      unread_count: 5

                lawCaseCreateSuccess:
                  summary: "[30017] Юридическое дело создано"
                  value:
                    msg_id: 30017
                    message_code: 0
                    message_desc: "Operation successful"
                    message_body:
                      id: 1
                      name: "Дело о нарушении"

                tokenOpListSuccess:
                  summary: "[30018] Список операций с токенами"
                  value:
                    msg_id: 30018
                    message_code: 0
                    message_desc: "Operation successful"
                    message_body:
                      operations: []
                      total_elements: 50

                monitoringStatisticSuccess:
                  summary: "[30027] Статистика мониторинга"
                  value:
                    msg_id: 30027
                    message_code: 0
                    message_desc: "Operation successful"
                    message_body:
                      day: 10
                      month: 5
                      weekly: 7

                invalidMsgId:
                  summary: "[Common] Неверный msg_id"
                  value:
                    msg_id: 99999
                    message_code: 4
                    message_desc: "Message id not found"
                    message_body: {}

  /api/v{version}/files/chunk:
    post:
      tags:
        - Files
      summary: Загрузка чанка файла
      description: Загрузка части файла (чанка) в рамках multipart-загрузки
      operationId: uploadChunk
      parameters:
        - name: version
          in: path
          required: true
          schema:
            type: integer
          description: Версия API
        - name: upload_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
          description: ID сессии загрузки
        - name: chunk_number
          in: query
          required: true
          schema:
            type: integer
            minimum: 0
          description: Номер чанка (начиная с 0)
        - name: findSimilar
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Искать похожие файлы (1 - да, 0 - нет)
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - chunk
              properties:
                chunk:
                  type: string
                  format: binary
                  description: Файл чанка
      responses:
        '200':
          description: Результат загрузки чанка
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              examples:
                success:
                  summary: Чанк загружен успешно
                  value:
                    msg_id: 20000
                    message_code: 0
                    message_desc: "Chunk uploaded successfully"
                    message_body:
                      upload_id: "550e8400-e29b-41d4-a716-446655440000"
                      chunk_number: 0
                      chunk_size: 209715
                      file_id: "abc123"
                      message: "Chunk uploaded successfully"
                duplicateFile:
                  summary: Найден дубликат файла
                  value:
                    msg_id: 20004
                    message_code: 2
                    message_desc: "Duplicate file upload"
                    message_body:
                      duplicate_file_id: "xyz789"
                      user_id: 123
                      message: "Duplicate file found"

  /api/v{version}/files/{uploadId}/complete:
    post:
      tags:
        - Files
      summary: Завершение загрузки файла
      description: Подтверждение завершения загрузки всех чанков
      operationId: completeUpload
      parameters:
        - name: version
          in: path
          required: true
          schema:
            type: integer
          description: Версия API
        - name: uploadId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID сессии загрузки
      responses:
        '200':
          description: Статус завершения загрузки
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              examples:
                success:
                  summary: Сборка файла запущена
                  value:
                    msg_id: 20004
                    message_code: 0
                    message_desc: "File assembly in progress"
                    message_body:
                      upload_id: "550e8400-e29b-41d4-a716-446655440000"
                      status: "COMPLETING"
                      uploaded_chunks: 5
                      total_chunks: 5
                      message: "File assembly in progress"
                incomplete:
                  summary: Не все чанки загружены
                  value:
                    msg_id: 20004
                    message_code: 2
                    message_desc: "Not all chunks uploaded"
                    message_body:
                      upload_id: "550e8400-e29b-41d4-a716-446655440000"
                      status: "IN_PROGRESS"
                      uploaded_chunks: 3
                      total_chunks: 5
                      message: "Not all chunks uploaded"

  /api/v{version}/files/progress/{uploadId}:
    get:
      tags:
        - Files
      summary: Прогресс загрузки файла
      description: Получение текущего статуса загрузки
      operationId: getUploadProgress
      parameters:
        - name: version
          in: path
          required: true
          schema:
            type: integer
          description: Версия API
        - name: uploadId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID сессии загрузки
      responses:
        '200':
          description: Прогресс загрузки
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              examples:
                inProgress:
                  summary: Загрузка в процессе
                  value:
                    msg_id: 20004
                    message_code: 0
                    message_desc: "Operation successful"
                    message_body:
                      upload_id: "550e8400-e29b-41d4-a716-446655440000"
                      file_name: "document.pdf"
                      total_chunks: 5
                      uploaded_chunks: 3
                      status: "IN_PROGRESS"
                      progress_percentage: 60.0
                      file_path: "/uploads/user123/doc.pdf"
                      remaining_chunks: 2

  /api/v{version}/files/download/{fileId}:
    get:
      tags:
        - Files
      summary: Скачивание защищенного файла
      description: |
        Скачивание файла с проверкой прав доступа. Требуется авторизация.
        Проверяет права пользователя на скачивание файла.
      operationId: downloadFile
      parameters:
        - name: version
          in: path
          required: true
          schema:
            type: integer
          description: Версия API
        - name: fileId
          in: path
          required: true
          schema:
            type: string
          description: ID файла
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Токен авторизации
          example: "Bearer eyJhbGciOiJIUzI1NiIs..."
      responses:
        '200':
          description: Файл для скачивания
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              schema:
                type: string
              description: Имя файла для сохранения
              example: 'attachment; filename="document.pdf"'
        '403':
          description: Ошибка при скачивании
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              examples:
                fileBlocked:
                  summary: Файл заблокирован
                  value:
                    msg_id: 20004
                    message_code: 1
                    message_desc: "File is blocked,deleted or removed"
                    message_body:
                      file_id: "abc123"
                noPermission:
                  summary: Нет прав на скачивание
                  value:
                    msg_id: 20004
                    message_code: 2
                    message_desc: "Not have permission for download"
                    message_body:
                      file_id: "abc123"

  /api/v{version}/files/public-download/{fileId}:
    get:
      tags:
        - Files
      summary: Публичное скачивание файла
      description: Скачивание файла без авторизации (если разрешено)
      operationId: publicDownloadFile
      parameters:
        - name: version
          in: path
          required: true
          schema:
            type: integer
          description: Версия API
        - name: fileId
          in: path
          required: true
          schema:
            type: string
          description: ID файла
      responses:
        '200':
          description: Файл для скачивания
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

  /api/file/link:
    post:
      tags:
        - Files
      summary: Получение ссылки на файл для DocViewer
      description: Создает ссылку для просмотра документа и логирует просмотр
      operationId: getFileLink
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocViewerRequest'
      responses:
        '200':
          description: Файл для скачивания/просмотра
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

  /api/v{version}/files/{fileId}/similar:
    get:
      tags:
        - Files
      summary: Поиск похожих файлов
      description: |
        Поиск файлов, похожих на указанный. 
        Для изображений использует алгоритм перцептивного хеша.
        Для документов и аудио проверяет на полные дубликаты.
      operationId: findSimilarFiles
      parameters:
        - name: version
          in: path
          required: true
          schema:
            type: integer
          description: Версия API
        - name: fileId
          in: path
          required: true
          schema:
            type: string
          description: ID файла для поиска похожих
        - name: similarityLevels
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          description: Уровни схожести для фильтрации
          example: ["HIGH", "MEDIUM"]
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Номер страницы
        - name: size
          in: query
          required: false
          schema:
            type: integer
            default: 20
          description: Размер страницы
        - name: sort
          in: query
          required: false
          schema:
            type: string
            default: "hammingDistance"
          description: Поле для сортировки
      responses:
        '200':
          description: Список похожих файлов
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              examples:
                success:
                  summary: Найдены похожие файлы
                  value:
                    msg_id: 20004
                    message_code: 0
                    message_desc: "Similar files found"
                    message_body:
                      content:
                        - file_id: "xyz789"
                          similarity: 95.5
                          file_name: "similar_image.jpg"
                      page: 0
                      size: 20
                      total_elements: 1
                      total_pages: 1
                      has_next: false
                      has_previous: false


  /api/check/{fileId}:
    get:
      tags:
        - Files
      summary: Проверка защиты файла
      description: Проверяет, защищен ли файл системой NoCopy
      operationId: checkFileProtection
      parameters:
        - name: fileId
          in: path
          required: true
          schema:
            type: string
          description: ID файла для проверки
      responses:
        '200':
          description: Результат проверки
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'

  /api/check/file_stats:
    get:
      tags:
        - Files
      summary: Статистика защиты файлов
      description: Получение статистики по защищенным файлам пользователя
      operationId: checkFileProtectStats
      responses:
        '200':
          description: Статистика по типам файлов
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              example:
                IMAGE: 150
                DOCUMENT: 45
                AUDIO: 12

components:
  schemas:
    BaseRequest:
      type: object
      required:
        - msg_id
        - message_body
      properties:
        msg_id:
          type: integer
          description: Идентификатор сообщения/операции
          example: 20004
        message_body:
          type: object
          description: Тело запроса с параметрами операции
          additionalProperties: true

    BaseResponse:
      type: object
      properties:
        msg_id:
          type: integer
          description: Идентификатор сообщения (копируется из запроса)
          example: 20004
        message_code:
          type: integer
          description: |
            Код результата:
            - 0 - Успешно
            - 1 - Предупреждение/особый случай
            - 2 - Ошибка валидации/бизнес-логики
            - 4 - Ресурс не найден
          example: 0
        message_desc:
          type: string
          description: Описание результата операции
          example: "Operation successful"
        message_body:
          type: object
          description: Данные ответа
          additionalProperties: true

    DocViewerRequest:
      type: object
      required:
        - file_id
      properties:
        file_id:
          type: string
          description: ID файла для просмотра
        user_id:
          type: integer
          description: ID пользователя (если не передан в заголовке)
        action:
          type: string
          description: Действие с документом

    FileUploadRequest:
      type: object
      properties:
        action:
          type: string
          enum: [init, file_types, file_extension, chunks, cancel, progress]
          example: init
        file_name:
          type: string
          example: "document.pdf"
        file_type:
          type: string
          enum: [IMAGE, DOCUMENT, AUDIO]
        extension:
          type: string
        convert_to:
          type: string
        file_size:
          type: integer
          format: int64
        upload_id:
          type: string
          format: uuid

    InitFileResponse:
      type: object
      properties:
        upload_id:
          type: string
          format: uuid
        file_name:
          type: string
        total_chunks:
          type: integer
        chunk_size:
          type: integer
        status:
          type: string

    ChunkUploadResponse:
      type: object
      properties:
        upload_id:
          type: string
          format: uuid
        chunk_number:
          type: integer
        chunk_size:
          type: integer
          format: int64
        file_id:
          type: string
        message:
          type: string

    UploadProgressResponse:
      type: object
      properties:
        upload_id:
          type: string
          format: uuid
        file_name:
          type: string
        total_chunks:
          type: integer
        uploaded_chunks:
          type: integer
        status:
          type: string
        progress_percentage:
          type: number
          format: float
        file_path:
          type: string
        remaining_chunks:
          type: integer

    CompleteUploadResponse:
      type: object
      properties:
        upload_id:
          type: string
          format: uuid
        status:
          type: string
        uploaded_chunks:
          type: integer
        total_chunks:
          type: integer
        message:
          type: string
        file_path:
          type: string

    ChunkStatusResponse:
      type: object
      properties:
        upload_id:
          type: string
          format: uuid
        total_chunks:
          type: integer
        uploaded_chunks:
          type: integer
        missing_chunks:
          type: integer
        chunk_status:
          type: object
          additionalProperties:
            type: boolean

    FileTypesResponse:
      type: object
      properties:
        file_types:
          type: array
          items:
            type: string
        count:
          type: integer

    FileExtensionResponse:
      type: object
      properties:
        extension:
          type: array
          items:
            type: string
        count:
          type: integer
        max_file_size:
          type: integer
          format: int64

    CanceledUploadResponse:
      type: object
      properties:
        upload_id:
          type: string
          format: uuid
        message:
          type: string

    ActionResponse:
      type: object
      properties:
        action:
          type: string
        available_actions:
          type: array
          items:
            type: string

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT токен для авторизации

security:
  - BearerAuth: []