Розробка бази знань та Q&A на сайті: від схеми до деплою

Як ми прискорюємо підтримку клієнтів за допомогою автоматизованої бази знань та Q&A

Уявіть: на вашому сайті кілька сотень статей техпідтримки, клієнти не знаходять відповіді, запити в підтримку дублюються. База знань з нормальним пошуком та розділом запитань-відповідей вирішують цю біль — але тільки якщо реалізовані правильно, з урахуванням продуктивності та юзабіліті. Ми займаємося такими проєктами не перший рік: спроєктували та впровадили бази знань для десятків компаній — від стартапів до enterprise-рівня. Одна з ключових проблем — швидкість пошуку: користувач не готовий чекати більше секунди. Рішення — повнотекстовий індекс на стороні БД. Вартість такої розробки починається від $1500, а економія часу підтримки може сягати 40%.

Проблеми, які вирішуємо

Перша проблема — N+1 запит при завантаженні списку статей з категоріями. Друга — повільний LIKE-пошук по тілу статті. Третя — відсутність зворотного зв'язку: клієнти не можуть оцінити корисність статті, а команда не знає, які матеріали потрібно покращити. Типова ситуація: на сайті 15 000 статей, пошук працює через LIKE '%query%', відповідь — 5–10 секунд. Після міграції на PostgreSQL tsvector час відгуку падає до 10 мілісекунд.

Розробка бази знань: проектування схеми

Ієрархія категорій будується через self-reference parent_id. Для кожного рівня можна зберігати іконку та порядок сортування. Статті прив'язуються до категорії, отримують slug і numeric лічильники.

CREATE TABLE kb_categories (
  id SERIAL PRIMARY KEY,
  parent_id INTEGER REFERENCES kb_categories(id),
  name VARCHAR(150) NOT NULL,
  slug VARCHAR(150) NOT NULL UNIQUE,
  icon VARCHAR(50),
  sort_order INTEGER NOT NULL DEFAULT 0
);

CREATE TABLE kb_articles (
  id SERIAL PRIMARY KEY,
  category_id INTEGER REFERENCES kb_categories(id),
  title VARCHAR(255) NOT NULL,
  slug VARCHAR(255) NOT NULL UNIQUE,
  excerpt TEXT,
  body TEXT NOT NULL,
  body_search TSVECTOR GENERATED ALWAYS AS (
    to_tsvector('russian', title || ' ' || body)
  ) STORED,
  helpful_yes INTEGER NOT NULL DEFAULT 0,
  helpful_no INTEGER NOT NULL DEFAULT 0,
  views_count INTEGER NOT NULL DEFAULT 0,
  is_published BOOLEAN NOT NULL DEFAULT true,
  sort_order INTEGER NOT NULL DEFAULT 0,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX ON kb_articles USING gin(body_search);
CREATE INDEX ON kb_articles(category_id, is_published, sort_order);

CREATE TABLE faq_items (
  id SERIAL PRIMARY KEY,
  category VARCHAR(100),
  question TEXT NOT NULL,
  answer TEXT NOT NULL,
  sort_order INTEGER NOT NULL DEFAULT 0
);

Поле body_search — generated column, що виключає розсинхрон даних. Індекс GIN забезпечує пошук зі швидкістю <10 мс на 10K статей. Для запитань-відповідей окрема таблиця — так простіше керувати порядком і робити категорії.

Кроки реалізації

1. Проектування БД та створення міграцій.
2. Розробка API на Laravel (контролери, ресурси, валідація).
3. Реалізація повнотекстового пошуку (tsvector/tsquery).
4. Інтеграція фронтенду на React: компоненти пошуку, акордеону Q&A, сторінки статей.
5. Тестування (feature tests, оптимізація запитів).

Як реалізувати повнотекстовий пошук на PostgreSQL?

Ми використовуємо plainto_tsquery('russian', $query) і ранжуємо ts_rank. Контролер на Laravel:

class KnowledgeBaseController extends Controller {
    // Повнотекстовий пошук
    public function search(Request $request): JsonResponse {
        $query = trim($request->input('q', ''));
        if (strlen($query) < 2) {
            return response()->json(['data' => [], 'query' => $query]);
        }
        $articles = KbArticle::published()
            ->whereRaw(
                "body_search @@ plainto_tsquery('russian', ?)",
                [$query]
            )
            ->selectRaw("*, ts_rank(body_search, plainto_tsquery('russian', ?)) as rank", [$query])
            ->orderByDesc('rank')
            ->limit(10)
            ->get(['id', 'title', 'slug', 'excerpt', 'category_id', 'rank']);
        return response()->json([
            'data' => KbArticleResource::collection($articles),
            'query' => $query,
        ]);
    }

    // Стаття з трекінгом переглядів
    public function show(string $slug): JsonResponse {
        $article = KbArticle::published()
            ->with('category')
            ->where('slug', $slug)
            ->firstOrFail();
        // Інкрементувати перегляди (асинхронно)
        dispatch(fn() => $article->increment('views_count'))->afterResponse();
        // Пов'язані статті тієї ж категорії
        $related = KbArticle::published()
            ->where('category_id', $article->category_id)
            ->where('id', '!=', $article->id)
            ->orderByDesc('views_count')
            ->limit(5)
            ->get(['id', 'title', 'slug']);
        return response()->json([
            'article' => KbArticleResource::make($article),
            'related' => $related,
        ]);
    }

    // Оцінити корисність статті
    public function helpful(Request $request, KbArticle $article): JsonResponse {
        $request->validate(['helpful' => 'required|boolean']);
        $session = $request->session()->getId();
        $key = "helpful:{$article->id}:{$session}";
        if (Cache::has($key)) {
            return response()->json(['already_voted' => true]);
        }
        Cache::put($key, true, now()->addDays(30));
        if ($request->boolean('helpful')) {
            $article->increment('helpful_yes');
        } else {
            $article->increment('helpful_no');
        }
        return response()->json([
            'yes' => $article->fresh()->helpful_yes,
            'no' => $article->fresh()->helpful_no,
        ]);
    }
}

Метод show використовує afterResponse() — перегляди рахуються без уповільнення відповіді. Кеш голосування виключає накрутку. У відповіді віддаємо пов'язані статті — це підвищує час на сайті.

React-компоненти: акордеон запитань-відповідей і пошук

Фронтенд збираємо на React або Vue — без різниці. Покажу варіант на React.

Акордеон запитань-відповідей

import { useState } from 'react';

interface FaqItem {
  id: number;
  question: string;
  answer: string;
}

function FaqAccordion({ items, category }: { items: FaqItem[]; category: string }) {
  const [openId, setOpenId] = useState<number | null>(null);

  return (
    <section>
      <h2>{category}</h2>
      <dl>
        {items.map(item => (
          <div key={item.id} className={`faq-item ${openId === item.id ? 'open' : ''}`}>
            <dt>
              <button
                onClick={() => setOpenId(openId === item.id ? null : item.id)}
                aria-expanded={openId === item.id}
                aria-controls={`faq-answer-${item.id}`}
              >
                {item.question}
                <span aria-hidden>{openId === item.id ? '−' : '+'}</span>
              </button>
            </dt>
            <dd id={`faq-answer-${item.id}`} hidden={openId !== item.id}>
              <div dangerouslySetInnerHTML={{ __html: item.answer }} />
            </dd>
          </div>
        ))}
      </dl>
    </section>
  );
}

Реалізовано за Accessibility guidelines: aria-expanded, aria-controls, hidden. У відповіді може бути HTML (зображення, посилання).

Пошук з debounce

function KbSearch() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState<KbArticle[]>([]);

  useEffect(() => {
    if (query.length < 2) {
      setResults([]);
      return;
    }

    const timer = setTimeout(async () => {
      const { data } = await api.get('/api/kb/search', { params: { q: query } });
      setResults(data.data);
    }, 300);

    return () => clearTimeout(timer);
  }, [query]);

  return (
    <div className="kb-search">
      <input
        type="search"
        value={query}
        onChange={e => setQuery(e.target.value)}
        placeholder="Пошук по базі знань..."
        aria-label="Пошук по базі знань"
      />
      {results.length > 0 && (
        <ul className="kb-search__results" role="listbox">
          {results.map(article => (
            <li key={article.id} role="option">
              <a href={`/help/${article.slug}`}>
                <strong>{article.title}</strong>
                <p>{article.excerpt}</p>
              </a>
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

Debounce 300 мс запобігає зайвим запитам. Використовуємо role="listbox" і role="option" для доступності.

Що робити, якщо потрібно швидко знайти відповідь?

Пошук з автодоповненням — це мінімум. Додатково можна впровадити фільтрацію за категоріями, сортування за популярністю та датою. У складних випадках підключаємо Elasticsearch, але для 95% проєктів достатньо PostgreSQL tsvector. PostgreSQL tsvector швидше LIKE-пошуку в 500 разів.

Скільки часу займе розробка?

Разом: від 4 до 5 днів на стандартну базу знань з розділом запитань-відповідей. Термін може збільшитися, якщо потрібна інтеграція із зовнішніми системами або кастомна аналітика.

Порівняння способів пошуку

---
version: '3.8'
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: knowledge_base
      POSTGRES_USER: kb_user
      POSTGRES_PASSWORD: secret
    ports:
      - '5432:5432'
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata: