Реализация базы знаний и FAQ на сайте

Реализация базы знаний и FAQ

База знаний — структурированный каталог статей с поиском. FAQ — плоский список вопрос/ответ. Обе задачи решаются похожим стеком, разница — в иерархии категорий и полнотекстовом поиске.

Структура базы данных

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
);

Laravel: поиск и API

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,
        ]);
    }
}

React: аккордеон FAQ

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>
  );
}

React: поиск по базе знаний

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>
  );
}

FAQ Schema.org разметка

// В Blade-шаблоне
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    @foreach($faqItems as $item)
    {
      "@type": "Question",
      "name": {{ json_encode($item->question) }},
      "acceptedAnswer": {
        "@type": "Answer",
        "text": {{ json_encode(strip_tags($item->answer)) }}
      }
    }{{ $loop->last ? '' : ',' }}
    @endforeach
  ]
}
</script>

FAQ Schema.org позволяет FAQ появляться в расширенных результатах поиска Google (rich results).

Срок реализации

База знаний с категориями и PostgreSQL полнотекстовым поиском: 3–4 дня. С FAQ-аккордеоном, Schema.org разметкой и оценкой полезности: 4–5 дней.