Прогрессивная загрузка иерархии документов

Пользователь открывает страницу документов. Frontend отправляет запрос:

POST /api/v1/web/documents/query
{
  "query_type": "structured",
  "depth": 1,
  "depth_mode": "inclusive",
  "parent_path": "",
  "include_documents": false
}

Результат: Загружается только первый уровень иерархии (например, список компаний):

Пользователь кликает на "Company A". Frontend отправляет:

POST /api/v1/web/documents/query
{
  "query_type": "structured",
  "depth": 1,
  "depth_mode": "inclusive",
  "parent_path": "company-a-uuid/",
  "include_documents": false
}

Результат: Загружаются дочерние элементы Company A:

Пользователь кликает на "Deal 1". Frontend отправляет:

POST /api/v1/web/documents/query
{
  "query_type": "structured",
  "depth": 1,
  "depth_mode": "inclusive",
  "parent_path": "company-a-uuid/deal-1-uuid/",
  "include_documents": true
}

Результат: Загружаются подразделы сделки с документами:

-- Примеры hierarchy_path в базе данных
"company-uuid-1/"                                    -- Company A (level 1)
"company-uuid-1/deal-uuid-1/"                        -- Deal 1 (level 2)
"company-uuid-1/deal-uuid-1/contracts-uuid-1/"       -- Contracts (level 3)
"company-uuid-1/deal-uuid-1/contracts-uuid-1/doc1/"  -- Document 1 (level 4)

Фильтрация поддерева:

-- Получить все элементы внутри "Company A / Deal 1"
SELECT * FROM documents
WHERE hierarchy_path LIKE 'company-uuid-1/deal-uuid-1/%'

Загружает только непосредственные дочерние элементы:

{
  "depth": 1,
  "parent_path": "company-a/"
}

Результат: Загрузятся только сделки компании A, но не их подразделы.

Загружает два уровня вложенности:

{
  "depth": 2,
  "parent_path": "company-a/"
}

Результат: Загрузятся сделки компании A и их подразделы (но не документы внутри подразделов).

Структура:

inclusive (depth=2): Вернет Deal 1, Deal 2, Contracts, Invoices

exact (depth=2): Вернет только Contracts, Invoices

""                                           // Корень дерева
"550e8400-e29b-41d4-a716-446655440000/"     // Company A
"550e8400-e29b-41d4-a716-446655440000/      // Company A / Deal 1
 e29b-41d4-a716-446655440001/"

{
  "group_by": ["company_id", "deal_id", "document_type"]
}

Результат: Документы будут сгруппированы по компаниям, затем по сделкам, затем по типам документов.

// Первая страница (50 элементов)
{
  "limit": 50,
  "offset": 0
}

// Вторая страница
{
  "limit": 50,
  "offset": 50
}

curl -X POST https://api.example.com/api/v1/web/documents/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "query_type": "structured",
    "depth": 1,
    "depth_mode": "inclusive",
    "parent_path": "",
    "group_by": [],
    "include_documents": false
  }'

{
  "data": [
    {
      "key": "company_id",
      "value": "550e8400-e29b-41d4-a716-446655440000",
      "label": "Company A",
      "level": 1,
      "document_count": 0,
      "has_children": true,
      "children_count": 3,
      "documents": [],
      "children": []
    },
    {
      "key": "company_id",
      "value": "550e8400-e29b-41d4-a716-446655440001",
      "label": "Company B",
      "level": 1,
      "document_count": 0,
      "has_children": true,
      "children_count": 2,
      "documents": [],
      "children": []
    }
  ],
  "total": 1250
}

curl -X POST https://api.example.com/api/v1/web/documents/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "query_type": "structured",
    "depth": 1,
    "depth_mode": "inclusive",
    "parent_path": "550e8400-e29b-41d4-a716-446655440000/",
    "group_by": [],
    "include_documents": false
  }'

{
  "data": [
    {
      "key": "deal_id",
      "value": "e29b-41d4-a716-446655440001",
      "label": "Deal X - 2024",
      "level": 1,
      "document_count": 0,
      "has_children": true,
      "children_count": 5,
      "documents": [],
      "children": []
    },
    {
      "key": "deal_id",
      "value": "e29b-41d4-a716-446655440002",
      "label": "Deal Y - 2024",
      "level": 1,
      "document_count": 0,
      "has_children": true,
      "children_count": 3,
      "documents": [],
      "children": []
    }
  ],
  "total": 800
}

curl -X POST https://api.example.com/api/v1/web/documents/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "query_type": "structured",
    "depth": 1,
    "depth_mode": "inclusive",
    "parent_path": "550e8400-e29b-41d4-a716-446655440000/e29b-41d4-a716-446655440001/",
    "group_by": [],
    "include_documents": true
  }'

{
  "data": [
    {
      "key": "document_type",
      "value": "contracts",
      "label": "Contracts",
      "level": 1,
      "document_count": 3,
      "has_children": false,
      "children_count": 0,
      "documents": [
        {
          "id": "doc-001",
          "name": "Contract_2024_01.pdf",
          "size": 245678,
          "mime_type": "application/pdf",
          "created_at": "2024-01-15T10:30:00Z",
          "hierarchy": ["550e8400-e29b-41d4-a716-446655440000", "e29b-41d4-a716-446655440001", "contracts"]
        },
        {
          "id": "doc-002",
          "name": "Contract_2024_02.pdf",
          "size": 189234,
          "mime_type": "application/pdf",
          "created_at": "2024-02-10T14:20:00Z",
          "hierarchy": ["550e8400-e29b-41d4-a716-446655440000", "e29b-41d4-a716-446655440001", "contracts"]
        }
      ],
      "children": []
    },
    {
      "key": "document_type",
      "value": "invoices",
      "label": "Invoices",
      "level": 1,
      "document_count": 2,
      "has_children": false,
      "children_count": 0,
      "documents": [
        {
          "id": "doc-003",
          "name": "Invoice_001.pdf",
          "size": 98765,
          "mime_type": "application/pdf",
          "created_at": "2024-01-20T09:15:00Z",
          "hierarchy": ["550e8400-e29b-41d4-a716-446655440000", "e29b-41d4-a716-446655440001", "invoices"]
        }
      ],
      "children": []
    }
  ],
  "total": 5
}

curl -X POST https://api.example.com/api/v1/web/documents/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "query_type": "structured",
    "depth": 3,
    "depth_mode": "inclusive",
    "parent_path": "",
    "group_by": [],
    "include_documents": false,
    "limit": 100
  }'

curl -X POST https://api.example.com/api/v1/web/documents/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "query_type": "structured",
    "depth": 1,
    "depth_mode": "inclusive",
    "parent_path": "550e8400-e29b-41d4-a716-446655440000/",
    "include_documents": true,
    "limit": 50,
    "offset": 0
  }'

{
  "query_type": "structured",
  "depth": 1,
  "depth_mode": "inclusive",
  "parent_path": "550e8400-e29b-41d4-a716-446655440000/",
  "include_documents": true,
  "limit": 50,
  "offset": 50
}

Вычисление количества страниц:

const totalPages = Math.ceil(response.total / limit);
// Если total = 800, limit = 50, то totalPages = 16

curl -X POST https://api.example.com/api/v1/web/documents/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "query_type": "structured",
    "depth": 3,
    "depth_mode": "exact",
    "parent_path": "",
    "include_documents": true
  }'

{
  "data": [...],      // Массив узлов дерева
  "total": 1250       // Общее количество документов (игнорирует limit/offset)
}

{
  "key": "company_id",                          // Имя ключа иерархии
  "value": "550e8400-e29b-41d4-a716-446655440000",  // UUID или ID значения
  "label": "Company A",                         // Читаемое название для UI
  "level": 1,                                   // Относительный уровень (1, 2, 3...)
  "document_count": 150,                        // Количество документов в узле
  "has_children": true,                         // Есть ли дочерние узлы
  "children_count": 5,                          // Количество дочерних узлов
  "documents": [...],                           // Массив документов (если include_documents=true)
  "children": [...]                             // Массив дочерних узлов (если depth > 1)
}

// JavaScript
if (node.has_children) {
  // Показать иконку expand/collapse
  showExpandIcon(node);
} else {
  // Узел конечный, иконку не показывать
  hideExpandIcon(node);
}

// Отобразить: "Company A (5)"
const label = `${node.label} (${node.children_count})`;

{
  "id": "doc-001",                              // Уникальный ID документа
  "name": "Contract_2024.pdf",                  // Имя файла
  "size": 245678,                               // Размер в байтах
  "mime_type": "application/pdf",               // MIME-тип
  "created_at": "2024-01-15T10:30:00Z",        // Дата создания (ISO 8601)
  "updated_at": "2024-01-15T10:30:00Z",        // Дата обновления
  "hierarchy": [                                // Массив иерархии (UUID элементов)
    "550e8400-e29b-41d4-a716-446655440000",
    "e29b-41d4-a716-446655440001",
    "contracts"
  ],
  "hierarchy_path": "550e8400-e29b-41d4-a716-446655440000/e29b-41d4-a716-446655440001/contracts/",
  "metadata": {                                 // Дополнительные метаданные (опционально)
    "author": "John Doe",
    "department": "Legal",
    "tags": ["contract", "2024"]
  }
}

{
  "data": [],
  "total": 0
}

// 400 Bad Request
{
  "error": "Invalid depth parameter: must be a positive integer"
}

// 401 Unauthorized
{
  "error": "Invalid or expired JWT token"
}

// 500 Internal Server Error
{
  "error": "Internal server error occurred"
}

// Инициализация состояния
const treeState = {
  data: [],              // Массив узлов верхнего уровня
  expandedNodes: new Set(), // Множество раскрытых узлов
  loadedPaths: new Set(),   // Множество загруженных путей (для кеширования)
};

async function loadInitialTree() {
  const response = await fetch('/api/v1/web/documents/query', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${getJWTToken()}`
    },
    body: JSON.stringify({
      query_type: 'structured',
      depth: 1,
      depth_mode: 'inclusive',
      parent_path: '',
      include_documents: false
    })
  });

  const result = await response.json();

  if (response.ok) {
    treeState.data = result.data;
    treeState.loadedPaths.add('');
    renderTree();
  } else {
    handleError(result.error);
  }
}

async function expandNode(node, nodePath) {
  // Проверка, не загружен ли уже путь
  if (treeState.loadedPaths.has(nodePath)) {
    treeState.expandedNodes.add(nodePath);
    renderTree();
    return;
  }

  // Формируем parent_path из nodePath
  const parentPath = buildParentPath(nodePath);

  // Загружаем дочерние элементы
  const response = await fetch('/api/v1/web/documents/query', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${getJWTToken()}`
    },
    body: JSON.stringify({
      query_type: 'structured',
      depth: 1,
      depth_mode: 'inclusive',
      parent_path: parentPath,
      include_documents: isLeafLevel(node)  // Документы только на конечных узлах
    })
  });

  const result = await response.json();

  if (response.ok) {
    // Находим реальный узел в дереве и обновляем его
    const actualNode = findNodeByPath(treeState.data, nodePath);
    if (actualNode) {
      actualNode.children = result.data;
      treeState.loadedPaths.add(nodePath);
      treeState.expandedNodes.add(nodePath);
      renderTree();
    }
  } else {
    handleError(result.error);
  }
}

function buildParentPath(nodePath) {
  // nodePath: "company_id|uuid1/deal_id|uuid2"
  // Нужно: "uuid1/uuid2/"
  return nodePath.split('/').map(part => {
    const [key, value] = part.split('|');
    return value;
  }).join('/') + '/';
}

function findNodeByPath(nodes, path) {
  const parts = path.split('/').filter(p => p);
  let current = nodes;

  for (const part of parts) {
    const node = current.find(n => `${n.key}|${n.value}` === part);
    if (!node) return null;
    current = node.children || [];
  }

  return current;
}

function collapseNode(nodePath) {
  treeState.expandedNodes.delete(nodePath);
  renderTree();

  // Опционально: очистить дочерние элементы для экономии памяти
  const node = findNodeByPath(treeState.data, nodePath);
  if (node && shouldClearChildren(node)) {
    node.children = [];
    treeState.loadedPaths.delete(nodePath);
  }
}

<div x-data="documentTree()">
  <template x-for="node in treeData" :key="node.key + '|' + node.value">
    <div class="tree-node">
      <div class="node-header" @click="toggleNode(node)">
        <span x-show="node.has_children">
          <span x-show="!isExpanded(node)">▶</span>
          <span x-show="isExpanded(node)">▼</span>
        </span>
        <span x-text="node.label"></span>
        <span class="badge" x-text="node.children_count"></span>
      </div>

      <div x-show="isExpanded(node)" class="node-children">
        <!-- Рекурсивная отрисовка детей -->
      </div>
    </div>
  </template>
</div>

<script>
function documentTree() {
  return {
    treeData: [],
    expandedNodes: new Set(),
    loadedPaths: new Set(),

    async init() {
      await this.loadInitialTree();
    },

    async loadInitialTree() {
      const result = await this.queryDocuments('', 1, false);
      this.treeData = result.data;
      this.loadedPaths.add('');
    },

    async toggleNode(node) {
      const nodePath = this.getNodePath(node);

      if (this.expandedNodes.has(nodePath)) {
        this.expandedNodes.delete(nodePath);
      } else {
        await this.expandNode(node, nodePath);
      }
    },

    async expandNode(node, nodePath) {
      if (!this.loadedPaths.has(nodePath)) {
        const parentPath = this.buildParentPath(nodePath);
        const result = await this.queryDocuments(parentPath, 1, this.isLeafLevel(node));

        const actualNode = this.findNodeByPath(nodePath);
        if (actualNode) {
          actualNode.children = result.data;
          this.loadedPaths.add(nodePath);
        }
      }

      this.expandedNodes.add(nodePath);
    },

    async queryDocuments(parentPath, depth, includeDocuments) {
      const response = await fetch('/api/v1/web/documents/query', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${this.getJWTToken()}`
        },
        body: JSON.stringify({
          query_type: 'structured',
          depth: depth,
          depth_mode: 'inclusive',
          parent_path: parentPath,
          include_documents: includeDocuments
        })
      });

      return await response.json();
    },

    isExpanded(node) {
      return this.expandedNodes.has(this.getNodePath(node));
    },

    getNodePath(node) {
      return `${node.key}|${node.value}`;
    }
  };
}
</script>

import { useState, useEffect } from 'react';

function DocumentTree() {
  const [treeData, setTreeData] = useState([]);
  const [expandedNodes, setExpandedNodes] = useState(new Set());
  const [loadedPaths, setLoadedPaths] = useState(new Set());

  useEffect(() => {
    loadInitialTree();
  }, []);

  const loadInitialTree = async () => {
    const result = await queryDocuments('', 1, false);
    setTreeData(result.data);
    setLoadedPaths(new Set(['']));
  };

  const queryDocuments = async (parentPath, depth, includeDocuments) => {
    const response = await fetch('/api/v1/web/documents/query', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${getJWTToken()}`
      },
      body: JSON.stringify({
        query_type: 'structured',
        depth,
        depth_mode: 'inclusive',
        parent_path: parentPath,
        include_documents: includeDocuments
      })
    });

    return await response.json();
  };

  const toggleNode = async (node, nodePath) => {
    if (expandedNodes.has(nodePath)) {
      setExpandedNodes(prev => {
        const newSet = new Set(prev);
        newSet.delete(nodePath);
        return newSet;
      });
    } else {
      await expandNode(node, nodePath);
    }
  };

  const expandNode = async (node, nodePath) => {
    if (!loadedPaths.has(nodePath)) {
      const parentPath = buildParentPath(nodePath);
      const result = await queryDocuments(parentPath, 1, isLeafLevel(node));

      setTreeData(prevData => {
        const newData = [...prevData];
        const actualNode = findNodeByPath(newData, nodePath);
        if (actualNode) {
          actualNode.children = result.data;
        }
        return newData;
      });

      setLoadedPaths(prev => new Set([...prev, nodePath]));
    }

    setExpandedNodes(prev => new Set([...prev, nodePath]));
  };

  return (
    <div className="tree">
      {treeData.map(node => (
        <TreeNode
          key={`${node.key}|${node.value}`}
          node={node}
          onToggle={toggleNode}
          isExpanded={expandedNodes.has(getNodePath(node))}
        />
      ))}
    </div>
  );
}

let jwtToken = null;
let tokenExpiry = null;

async function getJWTToken() {
  // Проверяем, валиден ли текущий токен
  if (jwtToken && tokenExpiry && Date.now() < tokenExpiry) {
    return jwtToken;
  }

  // Получаем новый токен
  const response = await fetch('/api/v1/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      username: 'user@example.com',
      password: 'password'
    })
  });

  const result = await response.json();

  if (response.ok) {
    jwtToken = result.token;
    // JWT обычно содержит exp claim, парсим его
    const payload = JSON.parse(atob(jwtToken.split('.')[1]));
    tokenExpiry = payload.exp * 1000; // Конвертируем в миллисекунды
    return jwtToken;
  } else {
    throw new Error('Failed to authenticate');
  }
}

// Автоматическое обновление токена за 5 минут до истечения
setInterval(async () => {
  if (tokenExpiry && Date.now() > tokenExpiry - 5 * 60 * 1000) {
    await getJWTToken();
  }
}, 60000); // Проверяем каждую минуту

const cache = {
  paths: new Map(),    // Кеш загруженных путей
  ttl: 5 * 60 * 1000   // 5 минут
};

async function queryWithCache(parentPath, depth, includeDocuments) {
  const cacheKey = `${parentPath}|${depth}|${includeDocuments}`;

  // Проверяем кеш
  if (cache.paths.has(cacheKey)) {
    const cached = cache.paths.get(cacheKey);
    if (Date.now() - cached.timestamp < cache.ttl) {
      console.log('Cache hit:', cacheKey);
      return cached.data;
    }
  }

  // Загружаем с сервера
  const data = await queryDocuments(parentPath, depth, includeDocuments);

  // Сохраняем в кеш
  cache.paths.set(cacheKey, {
    data,
    timestamp: Date.now()
  });

  return data;
}

-- B-tree индекс для LIKE запросов с префиксом
CREATE INDEX idx_hierarchy_path ON documents(hierarchy_path);

-- GIN индекс для полнотекстового поиска (если используется)
CREATE INDEX idx_hierarchy_path_gin ON documents USING GIN (hierarchy_path gin_trgm_ops);

-- Частичный индекс для активных документов
CREATE INDEX idx_active_hierarchy_path
ON documents(hierarchy_path)
WHERE deleted_at IS NULL;

// Измерение времени запроса
const startTime = performance.now();
const result = await queryDocuments(parentPath, depth, includeDocuments);
const duration = performance.now() - startTime;

// Логирование метрик
console.log('Query performance:', {
  parent_path: parentPath,
  depth,
  include_documents: includeDocuments,
  duration_ms: duration.toFixed(2),
  result_count: result.data.length,
  total_documents: result.total
});

// Отправка в систему мониторинга (например, DataDog, New Relic)
if (duration > 1000) {
  analytics.track('slow_query', {
    endpoint: '/api/v1/web/documents/query',
    duration,
    parent_path: parentPath
  });
}

// Определение мобильного устройства
const isMobile = /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);

// Настройки для мобильных
const mobileConfig = {
  depth: 1,                  // Всегда depth=1
  limit: 20,                 // Меньший лимит
  include_documents: false,  // По умолчанию без документов
  lazy_load_images: true     // Ленивая загрузка превью
};

// Использование
const config = isMobile ? mobileConfig : desktopConfig;

Возможные причины:

1. Отсутствует индекс на hierarchy_path - создайте индекс
2. Загружается слишком много документов - используйте пагинацию
3. Слишком большая глубина (depth > 3) - уменьшите depth
4. База данных перегружена - масштабируйте БД или добавьте read replicas

Решения:

1. Очищайте children при закрытии узла
2. Используйте виртуализацию для больших списков
3. Ограничивайте количество одновременно раскрытых узлов
4. Не храните полные объекты документов, только ID и метаданные