KnowledgeBaseAI

React + TypeScript + Vite приложение для визуализации и управления графом знаний, интегрированное с ИИ-ассистентом.

Документация

Полная документация доступна в мастер-индексе: docs/INDEX.md

Ключевые разделы:

• Архитектура и конвейер предложений (Proposal): ARCHITECTURE.md
• Каноническая спецификация графа (CANON): CANONICAL_SPEC.md
• API справочник: API_REFERENCE.md
• Векторный поиск и индексация: VECTOR_SPEC.md
• Деплой: DEPLOYMENT.md
• Миграция данных: MIGRATION_GUIDE.md
• Руководство разработчика: DEVELOPER_GUIDE.md

---

🛠️ Запуск и Разработка

Для корректной работы приложения (включая граф, поиск и ИИ) требуется запущенная инфраструктура (Neo4j, Postgres, FastAPI).

🐳 Способ 1: Полный запуск через Docker (Рекомендуется)

Это самый быстрый способ поднять все сервисы одной командой.

1. Настройка окружения:

   cp .env.example .env.prod
   # Проверьте настройки в .env.prod (пароли, хосты)

2. Запуск всех контейнеров:

   docker-compose up -d --build

3. Инициализация данных: Если база данных пуста, запустите скрипты загрузки данных внутри контейнера:

   # Загрузка графа в Neo4j
   docker exec knowledgebase-fastapi-dev-1 python scripts/load_data.py
   docker exec knowledgebase-fastapi-dev-1 python scripts/push_to_neo4j.py

4. Доступ:

   • Frontend: http://localhost:5173
   • Backend API: http://localhost:8000/docs

---

💻 Способ 2: Локальная разработка фронтенда

Если бэкенд уже запущен (в Docker или удаленно), вы можете запустить фронтенд локально для быстрой HMR-разработки.

1. Установка зависимостей:

   cd frontend
   npm install

2. Настройка API: Убедитесь, что в коде или переменных окружения указан правильный URL бэкенда (обычно http://localhost:8000).

3. Запуск:

   npm run dev

---

🧭 Эпик 2: Модуль Explore (просмотр и анализ графа)

Explore — это страница визуального исследования графа знаний на vis-network, заточенная под навигацию, анализ и быстрые “точечные” действия.

Как пользоваться (UX)

• Один клик по узлу: открывает правый сайдбар с деталями узла.
• Двойной клик по узлу: делает узел новым центром графа (перестраивает viewport).
• Kind: фильтрация узлов по типу (без повторных запросов).
• Depth: глубина построения viewport (влияет на объём данных).
• Навигация по приложению: камера и раскладка сохраняются — можно уходить/возвращаться без потери контекста.

---

[EXP-01] Оптимизация рендеринга vis-network (сохранение состояния)

Что сделано

• GraphContext хранит “живое” состояние графа: viewport, selectedUid, depth, camera, positions.
• На странице ExplorePage.tsx используется проверка валидности контекста (совпадают selectedUid и depth) — если валиден, не делаем getViewport.
• Состояние камеры и позиции узлов сохраняются на cleanup (unmount/пересоздание сети) и восстанавливаются при возвращении:
  • камера восстанавливается через network.moveTo(...) с анимацией;
  • при восстановлении отключается стабилизация (stabilization.enabled = !isContextValid) и запрещён авто‑fit (stabilization.fit = false).
• Для стабильности React‑эффектов применяются useRef (networkRef, cameraRef, graphStateRef), чтобы не пересоздавать сеть из‑за обновлений состояния.

Исправленные баги

• Сброс камеры при переходах между страницами → сохраняем camera в контекст и восстанавливаем через moveTo.
• Потеря раскладки (узлы “разъезжались” заново) → сохраняем getPositions() и при восстановлении отключаем стабилизацию.
• Авто‑зум/fit от vis-network ломал анализ → stabilization.fit = false, камерой управляем сами.
• Рывки из-за пересоздания Network при обновлении камеры → камера убрана из зависимостей эффекта, чтение через graphStateRef.
• Гонка отложенного moveTo при быстром уходе со страницы → блокировка отложенного вызова флагом isMounted.

---

[EXP-02] Расширенная карточка узла (Sidebar/Drawer)

Что сделано

• Добавлен NodeDetailsSidebar (drawer справа).
• На событие selectNode в vis-network выставляется detailsUid → сайдбар открывается по uid.
• Детали подгружаются через useNodeDetails(uid) → UI отрабатывает loading/error/empty.
• Кнопка “Спросить AI” интегрирована через toggleChat() (открывает чат).

Исправленные баги

• Повторный клик по тому же узлу не открывал сайдбар (узел уже выделен, selectNode не срабатывает) → при закрытии делаем networkRef.current?.unselectAll().
• setState после unmount в загрузке деталей → в useNodeDetails добавлен cancelled‑флаг.

---

[EXP-03] Фильтрация и “легенда” по типам (Kind)

Что сделано

• Типы для фильтра автоматически вычисляются из viewport (уникальные kind), плюс опция All.
• Фильтрация применяется реактивно без повторных запросов к API: меняется набор узлов перед toVisData(...).
• kind нормализован к стандарту 4.2 ('concept' | 'skill' | 'resource') через APP_CONFIG.kindMap, с fallback на defaultKind.
• Для стабильности данных:
  • устранены дубли узлов по uid (через seenIds);
  • добавлен перенос длинных названий в label и font.multi = true.

Исправленные баги

• Неизвестные типы ломали цвета/размеры узлов → kindMap + fallback + проверка наличия стиля в теме.
• Дубли uid вызывали артефакты/конфликты id в vis-network → дедупликация через seenIds.
• Длинные подписи делали граф нечитаемым → перенос строк + font.multi = true.