База знаний¶

База знаний состоит из обычных страниц Grav. Любая страница с типом Help Article (шаблон kb-article) — статья: поиск справочного центра находит её сразу после сохранения, форма запроса предлагает её, пока люди печатают, а сотрудники видят, какие статьи клиент читал перед тем, как написать.

Люди сначала ищут, а когда статья не решает вопрос, форма запроса продолжает с того места, где остановился поиск, сохраняя то, что уже пробовали.

Написание статьи¶

1. В Admin Next добавьте страницу под справочным центром (например, /help/account/reset-password) и выберите тип Help Article.
2. Напишите её как любую страницу. Поиск сопоставляет её заголовок и содержимое, причём заголовок весит втрое больше текста.
3. На вкладке Help Center редактора страницы задайте любое из:
4. Categories: заполняет таксономию kb_category. Справочный центр показывает каждую категорию карточкой темы с числом статей. Helpdesk Pro сам добавляет kb_category в site.taxonomies, когда ваш сайт его не перечисляет.
5. Project (kb.project, слаг или id проекта): привязывает статью к одному проекту. Оставьте пустым для статей обо всём.
6. Related Articles (kb.related): маршруты, показываемые первыми в разделе «Related articles» в конце статьи.
7. Only These Groups (kb.groups): ограничивает статью вошедшими людьми из этих групп Grav.
8. Опубликуйте её.

Неопубликованные и страницы без маршрута исключаются из поиска.

Списки статей и результаты поиска показывают короткую сводку под каждым заголовком: собственную сводку страницы, когда она есть (текст до разделителя сводки Grav, по умолчанию ===), иначе первые примерно 160 символов текста статьи без заголовков, блоков кода и таблиц.

Списки следуют порядку папок страниц (01.change-email перед 02.reset-password), затем заголовку, поэтому нумерация папок ставит самые полезные статьи первыми. Нумерованные папки также появляются в меню темы; добавьте visible: false в заголовок статьи, чтобы не показывать её там.

Статьи не обязаны находиться под справочным центром: страница Help Article в любом месте сайта считается. Если держать их под ним, получаются аккуратные адреса (/help/billing/refunds) и хлебные крошки.

Кто может читать статью¶

Статья следует правилам доступа самой страницы, и поиск показывает её только тем, кто мог бы её открыть:

Сотрудники находят каждую статью в рабочей области. Каждая находка проверяется снова перед показом, поэтому устаревший индекс никогда не покажет статью не тому человеку. Те же правила решают, что показывают индекс статей, страницы категорий, их счётчики и ссылки «предыдущая» и «следующая» статьи.

Просмотр статей¶

Люди, которые предпочитают смотреть, а не искать, могут просматривать:

• {mount}/articles, индекс статей: поле поиска, затем карточка каждой категории, где посетитель может что-то читать, с её значком, описанием, числом статей и первыми пятью статьями. Статьи без категории перечисляются в General последними.
• {mount}/articles/{category}, одна категория: хлебные крошки, её имя, описание и число, затем статьи со сводками, по 20 на страницу (?page=2), и «Still stuck?» внизу. Несуществующая категория или категория, где посетителю нечего читать, отвечает «We couldn't find that topic» с 404.
• Статья: хлебные крошки, заголовок, строка метаданных (её тема · Updated {date} · N min read), содержимое, «Was this helpful? Yes / No», Related articles и More in {category}, а также Previous и Next внутри категории.

Описания и значки тем¶

Каждая карточка темы может нести однострочное описание и значок. Задайте их на странице настроек плагина в разделе Help Center → Topic Descriptions and Icons (Add Topic, затем категория, описание и значок) или в user/config/plugins/helpdesk-pro.yaml в kb.categories по имени категории или её слагу:

kb:
  categories:
    Account: { description: 'Signing in, your profile and keeping your account safe', icon: user }
    Billing: { description: 'Payments, invoices and refunds', icon: credit-card }
    Troubleshooting: { description: 'When something is slow, blank or missing', icon: wrench }
    General: { description: 'Everything else', icon: question }

General описывает статьи без категории. Значки — небольшой линейный набор, следующий цветам вашей темы: user, credit-card, wrench, book, shield, mail, settings, question, chat и rocket. Тема без значка показывает вместо него первую букву названия в плитке.

Адреса категорий¶

Адрес категории — её слаг: значение kb_category строчными ASCII-буквами и цифрами, с дефисом для всего остального. Billing & Invoices находится по {mount}/articles/billing-invoices, а Café — по {mount}/articles/cafe. Переименование категории переносит её страницу. Два имени, дающие один слаг (Billing и billing), — одна категория. Имя без букв, которые слаг может сохранить (например, целиком на кириллице), получает c- и короткий хеш имени. Статьи без категории находятся по {mount}/articles/general.

Если ваша страница уже находится по адресу, на который ответил бы портал, побеждает ваша страница.

Путь по справочному центру¶

Вот что видит посетитель от поля поиска до обращения:

1. Поиск. На главной справочного центра есть поле поиска. С JavaScript статьи появляются под ним по мере ввода; нажатие Search открывает {mount}/search?q=… со статьями, которые он может читать, и, если он вошёл, его собственными совпадающими обращениями. Синонимы означают, что «can't sign in» находит статью со словами «log in».
2. Чтение. Статья показывает содержимое, «Was this helpful? Yes / No», связанные статьи и другие в той же категории.
3. «No» ведёт к форме. Ответ No заменяет вопрос на «Still stuck? Ask us», кнопка которого открывает форму запроса с последним поиском посетителя в качестве summary (или заголовком статьи) и статьёй как источником перехода. Ответ Yes благодарит. Без JavaScript ответ — обычная отправка формы, возвращающаяся к статье.
4. Подсказки при вводе. В форме запроса есть блок «You may be looking for», заполняющийся совпадающими статьями (и более ранними обращениями человека) по мере ввода. Предложенные статьи открываются в новой вкладке, чтобы форма не потерялась. Установите portal.suggestions в false, чтобы отключить подсказки.
5. «Before writing in». Когда обращение отправлено, заявка сохраняет копию того, что было раньше: поиски (с числом найденных результатов), прочитанные статьи, ответы Yes/No, нажатые подсказки и страницу, с которой открыли форму. Сотрудники видят это в панели заявки Before writing in.

Cookie справочного центра¶

Чтобы связать обращение с поисками перед ним, справочный центр ставит один сторонний cookie hd_kb: случайный 128-битный id с SameSite=Lax и HttpOnly, хранящийся portal.kb_session_days дней (по умолчанию 30). В нём нет ничего личного, а база данных хранит только его SHA-256. Укажите его как функциональный cookie в уведомлении о конфиденциальности.

Записанное сессией удаляется через privacy.kb_events_days дней (по умолчанию 90) ежедневным заданием maintenance.prune. Заявка копирует до 20 событий за день до отправки и хранит их, пока существует заявка. Просмотр статьи считается один раз за сессию, страницу и час, как и один и тот же ответ на «Was this helpful?».

В рабочей области¶

• Панель заявки Before writing in перечисляет, что заявитель делал сначала, и статьи, лучше всего совпадающие с заявкой, у каждой есть Insert link для ответа.
• Insert article рядом с Attach files в редакторе ищет по базе знаний и вставляет ссылку на статью в ответ.
• Operations → Search показывает индекс и перестраивает его (см. Поиск).
• Карточка Searches without an answer в Отчётах перечисляет поиски справочного центра, не давшие результатов.

Маршруты портала¶

Шаблоны¶

Тема переопределяет любой из них, поставляя тот же путь в своей templates/. Текст находится в ICU.PLUGIN_HELPDESK_PRO.KB_* в languages/en.yaml.

Функции Twig¶

Для темы, которая строит свои страницы статей или хочет использовать части в другом месте. Каждый список содержит только статьи, которые смотрящий может читать. Функции, рисующие разметку, добавляют таблицу стилей и скрипт портала и оборачивают вывод в .helpdesk.

Например, боковая панель со всеми категориями и их статьями:

<nav aria-label="Help topics">
  {% for c in helpdesk_kb_categories() %}
    <h3><a href="{{ c.url }}">{{ c.name }}</a> ({{ c.count }})</h3>
    <ul>
      {% for a in helpdesk_kb_articles(c.slug, 10) %}
        <li><a href="{{ a.url }}">{{ a.title }}</a></li>
      {% endfor %}
    </ul>
  {% endfor %}
  <a href="{{ helpdesk_kb_url('articles') }}">All articles</a>
</nav>

API¶

Инструменты MCP: get_ticket_context и suggest_articles. Каждый ответ «Was this helpful?» порождает внутреннее событие kb.feedback.

Связанные разделы¶

• Поиск
• Справочный центр и портал
• Форма запроса и гости