Kelverse Ticketing Tool — Kompletna Dokumentacja

Wersja 1.6.0 • Dwuwarstwowy system obsługi zgłoszeń i Helpdesk dla WordPress z natywnym serwerem AI (Model Context Protocol).

Spis Treści

• 01. Wprowadzenie i Instalacja
• 02. Obsługa Klienta i Portal
• 03. Workspace i Praca Zespołu
• 04. Konfiguracja i Administracja
• 05. Automatyzacja, Grupy i SLA
• 06. Produkty, Roadmapy i Procedury
• 07. Raporty i Wskaźniki CSAT
• 08. Integracja AI i Serwer MCP
• 09. REST API i Referencja dla Programistów
• 10. Bezpieczeństwo, RODO i Baza Danych
• 11. Shortcody i Bloki Gutenberg

01. Wprowadzenie i Instalacja

O projekcie

Kelverse Ticketing Tool (wersja 1.6.0) to kompleksowe rozwiązanie do zarządzania wsparciem klienta, zgłoszeniami błędów, propozycjami funkcji i zadaniami programistycznymi, zaprojektowane specjalnie dla ekosystemu WordPress.

Wtyczka łączy tradycyjny system Helpdesk z nowoczesną tablicą Kanban, silnikiem automatyzacji procesów, zarządzaniem SLA oraz unikalną na rynku natywną integracją z modelami sztucznej inteligencji (AI) za pośrednictwem protokołu Model Context Protocol (MCP).

Główne założenia architektoniczne

Architektura wtyczki opiera się na trzech filarach:

A[Kelverse Ticketing Tool Core] --> B[1. Warstwa Klienta & Społeczności]
A --> C[2. Warstwa Zespołu & Wsparcia]
A --> D[3. Warstwa Deweloperska & AI / MCP]
B --> B1["Support Hub (/support/)"]
B --> B2["Formularz zgłoszeń (/support/report/)"]
B --> B3["Portal klienta (/support/my-tickets/)"]
B --> B4["Forum publiczne (Gutenberg)"]
C --> C1["Frontend Workspace (/tickets/ - SPA/Kanban)"]
C --> C2["Panel wp-admin (Konfiguracja & Ustawienia)"]
C --> C3["Grupy agentów & Inteligentny przydział"]
C --> C4["Silnik SLA & Automatyzacji"]
D --> D1["Natywny serwer MCP (JSON-RPC 2.0)"]
D --> D2["Developer REST API (/development/*)"]
D --> D3["Rezerwacje zadań (Claims) & Idempotencja"]
D --> D4["Biblioteka procedur & Trust Boundary"]

1. Dwuwarstwowy model widoczności (Two-Layer Management):

• Klienci i użytkownicy zewnętrzni widzą wyłącznie to, co ich dotyczy – przesyłają zgłoszenia, śledzą statusy we własnym portalu i korzystają z bazy wiedzy.
• Zespół wsparcia i administratorzy operują na nowoczesnym interfejsie Kanban (Workspace), mają dostęp do notatek wewnętrznych, historii audytowej, zaawansowanych filtrów i narzędzi triażu.

1. Natywne wsparcie dla AI (AI-Ready Infrastructure):

• Wbudowany serwer MCP (Model Context Protocol) bez konieczności uruchamiania zewnętrznych mostków Node.js czy procesów pośredniczących.
• Bezpieczny cykl życia zadań realizowanych przez autonomicznych agentów AI (np. Claude Code, Cursor, Antigravity) z rezerwacją zgłoszeń (claims), linkowaniem commitów/PR i barierą bezpieczeństwa procedur (Trust Boundary).

1. Maksymalna wydajność i bezpieczeństwo danych:

• Ponad 20 dedykowanych tabel w bazie MySQL z optymalizowanymi indeksami (unikanie obciążania wp_postmeta).
• Wersjonowane, transakcyjne migracje bazy danych z blokadą MySQL named lock.
• Prywatny, tokenizowany magazyn załączników uniemożliwiający bezpośrednie pobieranie poufnych plików przez URL.

Wymagania systemowe

Przed instalacją upewnij się, że Twoje środowisko spełnia następujące wymagania:

• Wersja WordPress: 6.0 lub nowsza (zalecana 6.4+)
• Wersja PHP: 7.4 lub nowsza (rekomendowana PHP 8.1 / 8.2 / 8.3)
• Baza danych: MySQL 5.7+ lub MariaDB 10.3+ (wsparcie dla InnoDB i transakcji)
• Rozszerzenia PHP: json, mbstring, openssl, mysqli lub pdo_mysql
• Konfiguracja serwera:
• Dostęp do WP-Cron (zalecany systemowy cron wywołujący wp-cron.php co 5-10 minut)
• Włączona obsługa mod_rewrite / ładnych odnośników (Pretty Permalinks)
• Do integracji MCP/REST API: włączona obsługa nagłówka Authorization (nagłówki HTTP Basic Auth / Application Passwords)

Instalacja i Pierwsze Uruchomienie

Krok 1: Instalacja wtyczki

1. Pobierz plik archiwum kelverse-ticketing.zip.
2. Zaloguj się do panelu administratora WordPress (wp-admin).
3. Przejdź do: Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer.
4. Wskaż plik .zip i kliknij Zainstaluj teraz.
5. Po ukończeniu instalacji kliknij Włącz wtyczkę.

Krok 2: Automatyczna inicjalizacja (Co dzieje się przy aktywacji?)

Podczas aktywacji wtyczka automatycznie wykonuje następujące zadania:

1. Uprawnienia i role:

• Tworzy rolę użytkownika Kelverse Agent (kelverse_agent) z prawami do obsługi zgłoszeń i przesyłania załączników.
• Przydziela administratorom i agentom uprawnienia zarządzania (manage_kelverse_tickets i powiązane uprawnienia post type).

1. Kategorie początkowe:

• Zakłada domyślne kategorie zgłoszeń: Raport o błędzie (Bug report), Pytanie (Question), Pomysł (Idea).

1. Produkt domyślny:

• Tworzy domyślny produkt/projekt (Default), do którego przypisywane są nowe zgłoszenia.

1. Cykl życia statusów:

• Zapewnia obecność statusów deweloperskich (in_progress, in_review, blocked, done).

1. Utworzenie stron systemowych:

• /support/ – Główny Support Hub ze shortcodem [kelverse_support].
• /support/report/ – Formularz zgłaszania problemu ze shortcodem [kelverse_ticket_form].
• /support/my-tickets/ – Portal klienta ze shortcodem [kelverse_ticket_portal].
• /tickets/ – Przestrzeń robocza zespołu (Tickets / Workspace) ze shortcodem [kelverse_ticket_workspace].

1. Migracje bazy danych:

• Uruchamia sekwencję migracji bazy danych tworzącą dedykowane tabele (indeksy, registry, log zdarzeń, reguły automatyzacji itp.).

1. Reguły przepisywania URL (Rewrite Rules):

• Odświeża reguły permalinków, dzięki czemu pojedyncze zgłoszenia są od razu dostępne pod adresem /tickets/{numer}/.

Słowniczek pojęć systemu

02. Obsługa Klienta i Portal

Strefa klienta w Kelverse Ticketing Tool została zaprojektowana z myślą o prostocie, przejrzystości i ochronie prywatności. Klienci i użytkownicy końcowi mają do dyspozycji spójne centrum pomocy, nie wymagające poruszania się po panelu wp-admin.

1. Support Hub (/support/)

Support Hub to centralne „drzwi wejściowe” dla każdego użytkownika odwiedzającego witrynę. Zapewnia dostęp do:

• Formularza zgłoszeniowego
• Portalu „Moje zgłoszenia”
• Opcjonalnego odnośnika do bazy wiedzy / FAQ
• Publicznego spisu zgłoszeń (o ile włączono opcję publicznego trackera)

Osadzanie

Hub jest generowany za pomocą shortcode:

[kelverse_support]

Konfiguracja

W panelu administratora (Zgłoszenia → Ustawienia → sekcja Wsparcie):

• Własny tekst wprowadzający: Możliwość zdefiniowania powitania i instrukcji dla klientów.
• Strona FAQ: Wskazanie istniejącej strony WordPress z najczęściej zadawanymi pytaniami (pojawi się jako wyróżniony kafelek w hubie).
• Publiczny tracker: Przełącznik decydujący, czy lista publicznych zgłoszeń ma być prezentowana w hubie.

2. Formularz zgłaszania problemu (/support/report/)

Formularz umożliwia zgłaszanie błędów, zadawanie pytań oraz proponowanie nowych funkcji.

Osadzanie

[kelverse_ticket_form]

Można również skorzystać z bloku Gutenberga: Kelverse: Zgłoś problem (kelverse/submit).

Elementy formularza

1. Tytuł zgłoszenia: Zwięzłe podsumowanie problemu (pole wymagane).
2. Wybór produktu / projektu: Jeśli w systemie zdefiniowano wiele aktywnych produktów, zgłaszający wybiera właściwy z listy rozwijanej.
3. Kategoria zgłoszenia: Wybór kategorii (np. Błąd, Pytanie, Pomysł).
4. Treść zgłoszenia: Szczegółowy opis problemu.
5. Pola własne (Custom Fields): Dynamicznie dołączane pola formularza przypisane do danego produktu lub kategorii.
6. Widoczność zgłoszenia:

• Prywatne (domyślne): Dostępne tylko dla zgłaszającego i zespołu pomocy.
• Publiczne: Zgłoszenie trafia do publicznego katalogu problemów, gdzie inni użytkownicy mogą je przeglądać i śledzić.

1. Załączniki:

• Możliwość dołączenia maksymalnie 3 plików (konfigurowalne w ustawieniach).
• Dopuszczalne formaty: JPG, PNG, GIF, WebP, PDF.
• Maksymalny rozmiar: domyślnie 5 MB na plik.

Zabezpieczenia antyspamowe

Formularz posiada wbudowany, wielopoziomowy system ochrony bez konieczności uciążliwych kodów CAPTCHA:

• Honeypot: Ukryte pole formularza, którego wypełnienie przez bota powoduje ciche odrzucenie zgłoszenia.
• Minimalny czas wysyłki (min_seconds): Odrzucenie formularzy przesłanych w czasie krótszym niż np. 3 sekundy od otwarcia strony.
• Ograniczenie częstotliwości (rate_per_hour): Limit zgłoszeń z jednego adresu IP/konta na godzinę (domyślnie 5).

3. Portal Klienta „Moje zgłoszenia” (/support/my-tickets/)

Dedykowane miejsce dla zalogowanego klienta, w którym ma pełną kontrolę nad swoimi sprawami.

Osadzanie

[kelverse_ticket_portal]

Kluczowe funkcje portalu

• Autoryzacja: Niezalogowani użytkownicy widzą komunikat z bezpiecznym odnośnikiem do logowania, który po zalogowaniu przekierowuje z powrotem do portalu.
• Izolacja danych: Zapytanie bazodanowe bezwzględnie filtruje rekordy według identyfikatora bieżącego użytkownika (post_author = current_user_id). Żadne manipulacje parametrami adresu URL nie pozwolą na podejrzenie cudzych spraw.
• Filtrowanie i wyszukiwanie:
• Filtrowanie według statusu: Otwarte / Zamknięte / Wszystkie.
• Filtrowanie według kategorii.
• Wyszukiwarka tekstowa po tytule i numerze zgłoszenia.
• Paginacja: Czytelna paginacja (20 zgłoszeń na stronę) działająca bez przeładowań JavaScript (wsparcie dla przeglądarek z wyłączonym JS).

4. Widok pojedynczego zgłoszenia (/tickets/{numer}/)

Gdy klient kliknie numer zgłoszenia w portalu lub otrzyma bezpośredni link w wiadomości e-mail, trafia na stronę pojedynczego zgłoszenia.

Architektura szablonu

• Adres URL przyjmuje czytelną formę: https://twojadomena.pl/tickets/142/.
• Motywy klasyczne korzystają z dedykowanego szablonu wtyczki templates/single-ticket.php, który można łatwo nadpisać w motywie potomnym (twój-motyw/kelverse-ticketing/single-ticket.php).
• W motywach blokowych (FSE) treść integruje się bezpośrednio z filtrem the_content.

Co widzi klient na stronie zgłoszenia?

1. Nagłówek zgłoszenia: Numer (#142), tytuł, data utworzenia, kategoria, plakietka statusu (np. W toku, Rozwiązane).
2. Treść pierwotna: Pełen opis problemu oraz bezpieczne załączniki.
3. Wątek korespondencji:

• Odpowiedzi agentów wsparcia oznaczone plakietką zespołu.
• Odpowiedzi klienta.
• Pełne ukrycie notatek wewnętrznych: Notatki sporządzone przez pracowników są całkowicie wycięte z drzewa komentarzy dla klienta i nie pojawiają się w kodzie HTML strony.

1. Formularz odpowiedzi: Klient może dopisać nową wiadomość lub uzupełnić brakujące informacje.
2. Ocena satysfakcji (CSAT): Po zmianie statusu zgłoszenia na rozwiązane pojawia się interaktywny moduł oceny obsługi (1–5 gwiazdek z opcjonalnym komentarzem).

5. Publiczny Tracker i Forum Społecznościowe

Dla projektów o charakterze otwartym (np. pluginy, aplikacje, gry) wtyczka oferuje mechanizm publicznego zgłaszania i przeglądania zgłoszeń.

• Blok Gutenberg kelverse/public-tickets:
• Prezentuje publiczne zgłoszenia użytkowników z filtrowaniem i wyszukiwarką.
• Pozwala na zawężenie listy do konkretnego produktu lub kategorii.
• Wyświetla status wdrożenia (np. zgłoszone błędy i ich stan).
• Blok Gutenberg kelverse/products:
• Siatka lub lista kafelków reprezentujących produkty wraz z licznikami aktywnych publicznych zgłoszeń.
• Ochrona danych osobowych: Na liście publicznej nigdy nie są publikowane adresy e-mail zgłaszających, wewnętrzne notatki ani prywatne załączniki.

03. Workspace i Praca Zespołu

Przestrzeń robocza (Tickets / Workspace) dostępna pod adresem /tickets/ to nowoczesna, responsywna aplikacja SPA (Single Page Application) stworzona z myślą o agentach wsparcia, liderach projektów i programistach. Pozwala na błyskawiczne zarządzanie tysiącami spraw bez ciągłego przeładowywania stron.

1. Architektura Workspace

• Adres strony: /tickets/ (strona tworzona automatycznie podczas instalacji).
• Shortcode: [kelverse_ticket_workspace].
• Szablon Canvas: Strona korzysta z dedykowanego, pełnoekranowego szablonu templates/workspace.php, eliminując niepotrzebne paski boczne i nagłówki motywu.
• Optymalizacja wydajności: Skrypty i style aplikacji (workspace.js, workspace.css) są ładowane wyłącznie na stronie zawierającej ten shortcode.
• Autoryzacja: Dostęp do Workspace wymaga uprawnienia manage_kelverse_tickets (posiadanego domyślnie przez Administratorów oraz rolę Kelverse Agent). Użytkownicy bez tych uprawnień widzą czytelny komunikat braku dostępu.

B[Tablica Kanban]
L[Widok Listy / Tabeli]
D[Boczna Szuflada Zgłoszenia]
R1["Bootstrap & Dictionaries"]
R2["Tickets Query & Paginate"]
R3["Update / Group Change"]
R4["Replies & Internal Notes"]
R5["Merge & Relations"]
DB1[(wp_posts & wp_postmeta)]
DB2[(kelverse_ticket_events)]
DB3[(kelverse_ticket_relations)]
DB4[(kelverse_ticket_reads)]
Frontend Workspace <--> REST API
REST API <--> Baza Danych MySQL

2. Tablica Kanban i Układy Widoku

Przełączanie trybów wyświetlania

Workspace oferuje trzy podstawowe tryby pracy:

1. Tablica (Kanban Board): Kolumny reprezentują statusy (lub inne właściwości). Karty można swobodnie przeciągać i upuszczać (Drag & Drop).
2. Lista (List): Zwarta lista zoptymalizowana pod kątem szybkiego przeglądania dużej liczby spraw.
3. Tabela (Table): Wielokolumnowy arkusz pozwalający na sortowanie po polach i jednoczesny podgląd metadanych.

Elastyczne grupowanie kart

Domyślnie kolumny tablicy odzwierciedlają Statusy zgłoszeń. Użytkownik może w każdej chwili zmienić kryterium grupowania na:

• Priorytet (Krytyczny, Wysoki, Normalny, Niski)
• Osobę przypisaną (Agenci, Nieprzypisane)
• Produkt / Projekt
• Kategorię

Przeciągnięcie karty pomiędzy kolumnami natychmiast wysyła żądanie do API aktualizujące daną właściwość z weryfikacją numeru rewizji (ochrona przed nadpisaniem).

3. Zapisane Widoki (Saved Views) i Filtrowanie

Agenci mogą precyzyjnie konfigurować i zapisywać własne widoki robocze:

• Dostępne filtry:
• Produkt / Projekt
• Status i Priorytet
• Przypisany agent (w tym filtr „Moje zgłoszenia” lub „Nieprzypisane”)
• Tagi i Kategorie
• Zakres dat utworzenia lub ostatniej aktywności
• Stan przeczytania (Przeczytane / Nieprzeczytane)
• Zapisywanie widoków: Dowolną kombinację filtrów i wybranego układu można zapisać pod własną nazwą (np. „Moje błędy krytyczne”, „Czeka na weryfikację Dev”). Widoki są synchronizowane z kontem użytkownika w bazie danych.

4. Szuflada Zgłoszenia (Ticket Drawer)

Kliknięcie dowolnego zgłoszenia wysuwa z prawej strony ekranu pełny panel szczegółów, bez konieczności opuszczania tablicy:

Sekcje w szufladzie:

1. Nagłówek i statusy:

• Bezpośrednia zmiana statusu, priorytetu, przypisanego agenta i produktu.
• Informacje o czasie SLA (czas do przekroczenia terminu).

1. Karty właściwości i pola własne:

• Edycja pól tekstowych, list rozwijanych i metadanych jednym kliknięciem.

1. Wątek korespondencji i historia zdarzeń:

• Oś czasu (Timeline) łącząca wiadomości od klienta, odpowiedzi publiczne agentów, notatki wewnętrzne oraz automatyczny rejestr zmian (np. zmiana statusu przez automatyzację, rezerwacja zadania przez AI).

1. Przełącznik trybu wprowadzania:

• 🟢 Odpowiedź publiczna (Public Reply): Wysyła wiadomość widoczną dla klienta w portalu oraz generuje e-mail z powiadomieniem.
• 🟡 Notatka wewnętrzna (Internal Note): Dodaje komentarz na żółtym tle, widoczny wyłącznie dla zespołu wsparcia i agentów MCP.

1. Wskaźnik nieprzeczytanych zmian (mark_read):

• Zgłoszenia z nowymi odpowiedziami od klienta lub zmianami mają status nieprzeczytanych do momentu otwarcia szuflady przez agenta.

5. Gotowe Odpowiedzi (Canned Replies)

Funkcja ułatwiająca standaryzację odpowiedzi na powtarzające się zapytania.

• Dostęp z poziomu edytora: Kliknięcie ikony szablonów w polu edycji odpowiedzi pozwala na wyszukanie i wstawienie gotowego tekstu.
• Symbole zastępcze (Placeholders):

Tekst szablonu może zawierać znaczniki, które są automatycznie uzupełniane danymi zgłoszenia:

• {{ticket_number}} – numer zgłoszenia (np. #104)
• {{ticket_title}} – tytuł zgłoszenia
• {{customer_name}} – imię i nazwisko lub nick zgłaszającego
• {{customer_email}} – adres e-mail klienta
• {{agent_name}} – nazwa agenta odpowiadającego
• {{site_name}} – nazwa witryny
• Zasięg: Szablony mogą być ogólnodostępne dla całego zespołu lub prywatne dla danego agenta.

6. Relacje i Łączenie Zgłoszeń (Relations & Merge)

Typy relacji między zgłoszeniami:

• Związane z (Relates to): Luźne powiązanie tematyczne.
• Blokuje / Jest blokowane przez (Blocks / Is blocked by): Oznaczenie zależności technologicznych (np. błąd API blokuje wdrożenie w aplikacji mobilnej).
• Zadanie podrzędne (Subticket): Podział dużego problemu na mniejsze zadania składowe.
• Zduplikowane przez (Duplicated by): Identyfikacja powielonych zgłoszeń.

Łączenie zgłoszeń (Merge Tickets):

Jeśli kilku klientów zgłosiło ten sam problem, agent może scalić zgłoszenie źródłowe ze zgłoszeniem docelowym:

1. Podgląd na żywo (Merge Preview): System weryfikuje zgodność projektów i wyświetla raport, jakie komentarze, załączniki i obserwatorzy zostaną przeniesieni.
2. Zachowanie historii: Komentarze i załączniki trafiają do głównego zgłoszenia, a zgłoszenie źródłowe zostaje automatycznie zamknięte z notatką wskazującą numer zgłoszenia głównego.
3. Powiadomienie klientów: Zgłaszający scalonego ticketa staje się obserwatorem zgłoszenia głównego i otrzymuje powiadomienia o jego rozwiązaniu.

7. Detekcja Kolizji i Aktywność na Żywo (Presence)

Aby uniknąć sytuacji, w której dwóch agentów odpowiada na to samo zgłoszenie w tym samym czasie:

• System śledzi aktywność użytkowników w szufladzie zgłoszenia za pomocą tzw. pulsu (heartbeat).
• Jeśli inny agent ma otwarte dane zgłoszenie, w prawym górnym rogu szuflady pojawia się awatar i ostrzeżenie o kolizji: „Jan Kowalski obecnie edytuje to zgłoszenie”.
• Mechanizm rewizji optymistycznej (expected_revision) zapobiega przypadkowemu nadpisaniu zmian, informując o konieczności odświeżenia danych.

04. Konfiguracja i Administracja

Panel administracyjny WordPress (wp-admin) zapewnia pełną kontrolę nad konfiguracją systemu, słownikami, polami formularzy oraz powiadomieniami.

1. Menu i Podstrony Administracyjne

W menu bocznym WordPressa pojawia się główna sekcja Zgłoszenia:

• Wszystkie zgłoszenia (edit.php?post_type=kelverse_ticket): Klasyczna lista WordPress z filtrami statusu, priorytetu, agenta, tagu i zapisanych widoków.
• Dodaj nowe: Ręczne tworzenie zgłoszenia przez pracownika.
• Kategorie: Zarządzanie taksonomią kelverse_ticket_category.
• Tagi: Zarządzanie słownikiem etykiet kelverse_ticket_tag.
• Produkty: Karty produktów i repozytoriów (kelverse_project).
• Procedury: Biblioteka reguł operacyjnych i instrukcji (kelverse_procedure).
• Tablica Kanban: Wbudowany w kokpit podgląd tablicy.
• Statusy: Konfigurator cyklu życia zgłoszeń.
• Priorytety: Skala ważności spraw.
• Pola własne: Edytor dynamicznych pól formularza.
• Grupy agentów: Zespoły wsparcia i zasady rotacji.
• Automatyzacja: Silnik reguł biznesowych.
• SLA: Konfiguracja umów o poziomie świadczenia usług.
• Raporty: Statystyki, wykresy i analiza wydajności.
• Szablony e-mail: Dostosowanie treści powiadomień.
• Integracje: Zarządzanie dostępem API i serwerem MCP.
• Ustawienia: Konfiguracja globalna wtyczki.

2. Ustawienia Ogólne (Kelverse_Ticketing_Settings)

W zakładce Zgłoszenia → Ustawienia znajdują się główne parametry systemu:

1. Język interfejsu (UI Language)

• Możliwość wymuszenia języka wtyczki (np. Polski pl_PL lub Angielski en_US) niezależnie od języka całej witryny WordPress.

2. Domyślne wartości

• Domyślny status: Status nadawany nowo tworzonym zgłoszeniom (zwykle new – Nowe).
• Domyślna widoczność: Rekomendowane ustawienie: Prywatne (zgłoszenie widoczne dla klienta i zespołu).

3. Moduł plików i załączników

• Maksymalna liczba plików: Standardowo 3 pliki na formularz.
• Maksymalny rozmiar pliku: W kilobajtach (domyślnie 5120 KB = 5 MB).
• Dozwolone rozszerzenia: Biała lista rozszerzeń (np. jpg, jpeg, png, gif, webp, pdf).

4. Ochrona antyspamowa

• Minimalny czas wysyłki: Odrzucanie botów wypełniających formularz poniżej zadanego czasu w sekundach.
• Limit na godzinę (Rate Limit): Maksymalna liczba zgłoszeń z danego adresu IP / sesji w ciągu 60 minut.

5. Korespondencja e-mail

• Nazwa i adres nadawcy: Nadpisanie domyślnych nagłówków From.
• Adres e-mail zespołu: Skrzynka zbiorcza otrzymująca powiadomienia o nowych zgłoszeniach nieprzypisanych.
• Przełączniki zdarzeń: Opcja włączenia/wyłączenia e-maili przy: nowym zgłoszeniu, zmianie statusu, przydzieleniu agenta, dodaniu nowej odpowiedzi.

3. Konfigurator Statusów

Strona Zgłoszenia → Statusy pozwala na swobodne definiowanie etapów przez które przechodzi zgłoszenie:

Właściwości statusu:

• Klucz systemowy: Unikalny identyfikator (np. new, todo, in_progress, in_review, waiting_customer, done, rejected).
• Etykieta: Nazwa wyświetlana w interfejsie.
• Kolor / Plakietka: Kod HEX koloru używany na tablicy Kanban i w widokach zgłoszeń.
• Charakter statusu:
• Otwarte: Sprawa w toku wymagająca działania.
• Zamknięte: Sprawa sfinalizowana (np. done, rejected). Zgłoszenia ze statusem zamkniętym nie obciążają wskaźników SLA i odblokowują ankietę CSAT dla klienta.
• Kolejność: Ustala porządek kolumn na tablicy Kanban.

4. Konfigurator Priorytetów

W zakładce Zgłoszenia → Priorytety zarządza się poziomami pilności:

Waga priorytetu jest bezpośrednio wykorzystywana przez reguły automatyzacji oraz moduł SLA (im wyższa waga, tym krótszy wymagany czas reakcji).

5. Pola Własne (Custom Fields)

System zawiera zaawansowany silnik pól dodatkowych, przechowywanych w zoptymalizowanych tabelach bazodanowych kelverse_ticket_fields oraz kelverse_ticket_field_values.

Obsługiwane typy pól:

1. Pole tekstowe (Text): Krótkie dane tekstowe (np. wersja systemu, numer zamówienia).
2. Obszar tekstu (Textarea): Dłuższe opisy, logi błędów.
3. Lista wyboru (Select): Pojedynczy wybór z predefiniowanej listy opcji.
4. Wielokrotny wybór (Multiselect): Wybór wielu wartości.
5. Pole wyboru (Checkbox / Toggle): Wartość logiczna Tak/Nie.
6. Liczba (Number): Wartości numeryczne z opcjonalnym zakresem min/max.
7. Data (Date): Wybór daty z kalendarza.
8. Adres URL: Link do repozytorium, zgłoszenia w zewnętrznym systemie lub środowiska staging.

Zakres i warunki wyświetlania pól:

• Wymagane / Opcjonalne: Walidacja po stronie serwera przed zapisem zgłoszenia.
• Widoczność:
• Publiczne w formularzu: Klient wypełnia pole podczas zgłaszania sprawy.
• Tylko dla zespołu: Pole widoczne i edytowalne wyłącznie przez agentów w Workspace.
• Powiązanie z produktem lub kategorią: Pole może pojawiać się tylko dla wybranego produktu (np. pole Wersja PHP tylko dla pluginu WordPress) lub wybranej kategorii.

6. Szablony E-mail

Zakładka Zgłoszenia → Szablony e-mail pozwala na personalizację automatycznej korespondencji:

Dostępne szablony:

1. Potwierdzenie przyjęcia zgłoszenia (wysyłane do klienta po wypełnieniu formularza).
2. Powiadomienie zespołu o nowym zgłoszeniu (wysyłane do przypisanego agenta lub grupy).
3. Nowa odpowiedź w zgłoszeniu (dla klienta, gdy agent odpowie; dla agenta, gdy klient dopisze wiadomość).
4. Zmiana statusu zgłoszenia (informacja o postępach w realizacji).
5. Zaproszenie do oceny obsługi (CSAT) (wysyłane po rozwiązaniu problemu).

Zmienne dynamiczne (Placeholdery):

Treści e-maili obsługują pełny zestaw znaczników:

• {{ticket_number}} – numer referencyjny
• {{ticket_title}} – temat zgłoszenia
• {{ticket_url}} – bezpośredni odnośnik do zgłoszenia w portalu
• {{customer_name}} – dane klienta
• {{status_name}} – aktualny status
• {{priority_name}} – aktualny priorytet
• {{reply_content}} – treść najnowszej odpowiedzi
• {{site_name}} – nazwa serwisu

05. Automatyzacja, Grupy i SLA

Moduł automatyzacji i zarządzania poziomem usług (SLA) w Kelverse Ticketing Tool umożliwia delegowanie powtarzalnych zadań, automatyczne kierowanie zgłoszeń do właściwych specjalistów oraz rygorystyczne przestrzeganie terminów odpowiedzi.

1. Silnik Automatyzacji (Automation Engine)

Silnik automatyzacji reaguje na zdarzenia domenowe (np. nadejście zgłoszenia, zmiana statusu) oraz zdarzenia upływu czasu (zadania harmonogramu WP-Cron).

E[Zdarzenie wyzwalające / Trigger] --> LG{Zabezpieczenie pętli Loop Guard}
LG -- Limit przekroczony --> STOP[Zatrzymaj kaskadę]
LG -- Zezwolono --> R[Pobierz aktywne reguły dla zdarzenia]
R --> C{Ewaluacja warunków ALL / ANY}
C -- Niespełnione --> SKIP[Pomiń regułę]
C -- Spełnione --> A[Wykonaj listę akcji]
A --> LOG[(Zapisz przebieg w kelverse_automation_runs)]

Zdarzenia wyzwalające (Triggers):

1. Zgłoszenie utworzone (ticket_created): Uruchamiane natychmiast po zapisaniu nowego zgłoszenia przez klienta, agenta lub API.
2. Status zmieniony (status_changed): Uruchamiane przy przejściu między statusami.
3. Przypisanie zmienione (assignee_changed): Uruchamiane przy zmianie osoby odpowiedzialnej.
4. Czas: brak aktywności przez X godzin (time_no_activity): Cykliczne zadanie skanujące zgłoszenia, w których nic się nie wydarzyło przez zadany czas.
5. Czas: brak odpowiedzi przez X godzin (time_no_reply): Wykrywanie zgłoszeń oczekujących na odpowiedź agenta.
6. Czas: zamknięte od X godzin (time_closed): Automatyczne archiwizowanie lub ostateczne zamykanie rozwiązanych spraw.

2. Kreator Warunków (Conditions)

Każda reguła może zawierać grupę warunków łączonych operatorem Wszystkie (AND) lub Dowolny (OR).

Obsługiwane pola kontekstu:

• status oraz old_status (aktualny i poprzedni status)
• priority (priorytet)
• assignee (ID przypisanego agenta)
• category (slug kategorii)
• tag (slugi przypisanych tagów)
• visibility (publiczne / prywatne)
• origin (źródło: user, admin, api, agent)
• author_role (rola użytkownika zgłaszającego)
• age_hours (wiek zgłoszenia w godzinach)
• hours_since_activity, hours_since_reply, hours_since_closed

Dostępne operatory:

equals (równa się), not_equals (różne od), contains (zawiera), not_contains, in (znajduje się na liście), not_in, greater (większe niż), less (mniejsze niż), is_empty (jest puste), is_not_empty (nie jest puste), before (przed datą), after (po dacie).

3. Akcje Automatyzacji (Actions)

Gdy warunki zostaną spełnione, system wykonuje zdefiniowaną sekwencję akcji:

Bezpieczeństwo i Testowanie

• Loop Guard: Zabezpieczenie przed pętlami nieskończonymi. Jeśli akcja reguły wyzwoli kolejne zdarzenie, kaskada jest ucinana po przekroczeniu bezpiecznego limitu głębokości wywołań.
• Audyt uruchomień: Każde wykonanie reguły jest rejestrowane w tabeli kelverse_automation_runs wraz z czasem, ID zgłoszenia i statusem wykonania.
• Tryb testowy (Dry Run): W panelu edycji reguły można przetestować jej działanie na istniejącym zgłoszeniu bez wprowadzania realnych zmian w bazie.

4. Grupy Agentów i Strategie Przydziału

Zakładka Zgłoszenia → Grupy agentów pozwala na organizację pracowników w wyspecjalizowane zespoły (np. Wsparcie I Linii, Zespół Rozliczeń, Programiści).

Strategie inteligentnego przydziału:

1. Konkretny agent (Specific Agent): Zawsze przypisuje wskazaną osobę.
2. Karuzela (Round-Robin): Równomiernie rozdziela kolejne zgłoszenia pomiędzy członków grupy po kolei.
3. Równoważenie obciążenia (Load-Balanced): System sprawdza liczbę aktualnie otwartych zgłoszeń każdego członka grupy i przydziela sprawę temu agentowi, który ma w danym momencie najmniej pracy.

5. Polityki SLA i Godziny Pracy (Business Hours)

Moduł SLA gwarantuje, że żadne zgłoszenie nie zostanie zignorowane, a terminy odpowiedzi są precyzyjnie mierzone.

Godziny robocze (Business Hours):

System umożliwia zdefiniowanie harmonogramu pracy biura:

• Dni tygodnia (np. Poniedziałek – Piątek)
• Godziny otwarcia (np. 09:00 – 17:00)
• Strefa czasowa
• Dni wolne i święta (wyłączenia z kalkulatora SLA)

Polityki SLA:

Każda polityka przypisywana jest do priorytetu i określa dwa kluczowe wskaźniki:

1. Czas pierwszej odpowiedzi (First Response Time): Czas, w jakim pracownik musi dodać pierwszą odpowiedź publiczną dla klienta.
2. Czas rozwiązania problemu (Resolution Time): Czas do momentu nadania statusu zamkniętego (done, rejected).

Monitorowanie i eskalacja:

• Na tablicy Kanban i w szufladzie zgłoszenia wyświetlany jest dynamiczny licznik czasu pozostałego do naruszenia umowy SLA.
• W przypadku przekroczenia terminu zgłoszenie zostaje oznaczone etykietą SLA Breached, a silnik automatyzacji może natychmiast wysłać alert e-mail do kierownika zespołu lub podnieść priorytet sprawy.

06. Produkty, Roadmapy i Procedury

Wtyczka Kelverse Ticketing Tool wykracza poza standardowy Helpdesk, oferując architekturę multi-projektową zaprojektowaną do równoczesnego zarządzania wieloma produktami cyfrowymi oraz standaryzacji procesów programistycznych.

1. Zarządzanie Produktami (Multi-Project Architecture)

W systemie każdy problem i zadanie przynależy do konkretnego Produktu (w kodzie: kelverse_project). Produktem może być wtyczka WordPress, biblioteka programistyczna, aplikacja mobilna, program desktopowy lub gra komputerowa.

P[Produkt / Kelverse Project] --> M1[Repozytoria Kodu Git]
P --> M2[Karta Produktu / Brief Techniczny]
P --> M3[Roadmapa & Milestone'y]
P --> M4[Prywatne & Publiczne Zgłoszenia]
P --> M5[Powiązane Procedury Operacyjne]

Właściwości Produktu:

• Tytuł i Slug: Identyfikator w adresach URL i zapytaniach API (np. kelverse-ticketing, mobile-app).
• Typ produktu: Wtyczka (plugin), Aplikacja/Program (program), Gra (game), Inny (other).
• Kolorystyka: Kod koloru wykorzystywany na tablicy Kanban do natychmiastowej identyfikacji wizualnej.
• Konfiguracja Repozytoriów Kodu: Lista repozytoriów Git powiązanych z produktem (adres URL, domyślna gałąź, etykieta).
• Produkt domyślny: Jeden z produktów oznaczony jest jako domyślny (default), co zapewnia, że każde nowe zgłoszenie zawsze posiada przypisany produkt.

2. Karta Produktu (Product Brief)

Każdy produkt posiada własną bazę wiedzy technicznej, która stanowi kontekst dla programistów oraz agentów sztucznej inteligencji:

• Opis architektury: Założenia techniczne, użyte technologie, struktura modułów.
• Decyzje architektoniczne (ADR): Kluczowe wytyczne dlaczego dane rozwiązanie zostało zaimplementowane w określony sposób.
• Zależności zewnętrzne: Biblioteki, zewnętrzne API, wymagania środowiskowe.

Agent AI po połączeniu przez MCP może odczytać kartę produktu za pomocą narzędzia get_project_brief, zyskując natychmiastowy kontekst niezbędny do realizacji zadań programistycznych.

3. Roadmapy i Milestone’y (Roadmap Management)

Moduł roadmapy pozwala na planowanie kolejnych wydań i wersji oprogramowania:

• Tworzenie Milestone’ów: Określenie nazwy wydania (np. v1.7.0, MVP 2026), planowanej daty zakończenia oraz zakresu prac.
• Przypisywanie zgłoszeń do wydań: Zgłoszenia z tablicy Kanban mogą być przypisane do konkretnego milestone’u.
• Wskaźniki postępu: Automatyczne wyliczanie procentu ukończenia wydania na podstawie zgłoszeń rozwiązanych w stosunku do otwartych.
• Dostęp przez API: Zespoły i asystenci AI mogą sprawdzać aktualny stan roadmapy (get_project_roadmap) oraz przypisywać realizowane zadania do wydań (assign_ticket_milestone).

4. Biblioteka Procedur i Granica Zaufania AI (Trust Boundary)

Jednym z najbardziej innowacyjnych elementów systemu jest biblioteka procedur (kelverse_procedure). Procedury to ustandaryzowane instrukcje operacyjne mówiące jak zespół i agenci AI powinni pracować (np. „Procedura tworzenia pull requesta”, „Procedura weryfikacji bezpieczeństwa SQL”, „Procedura publikacji nowej wersji”).

Problem bezpieczeństwa w pracy z AI:

Ponieważ procedury sterują zachowaniem modeli AI we wszystkich podłączonych repozytoriach, nieautoryzowana modyfikacja procedury przez złośliwy prompt (prompt injection) mogłaby skłonić agenta do obejścia testów lub wycieku danych. Z tego względu Kelverse Ticketing Tool implementuje rygorystyczną barierę bezpieczeństwa (Trust Boundary):

AI->>REST: propose_procedure_change(slug, propozycja)
REST->>WP: Zapisz wyłącznie jako propozycję (Status: Draft/Proposal)
Note over WP: Brak prawa do publikacji dla AI!
WP-->>AI: Propozycja zarejestrowana (oczekuje na człowieka)
Human->>WP: Weryfikacja w panelu wp-admin
alt Propozycja bezpieczna
Human->>WP: Publikuj procedurę (Uprawnienie: kelverse_manage_procedures)
WP-->>Human: Procedura aktywna dla wszystkich agentów
else Naruszenie zasad
Human->>WP: Odrzuć / Usuń propozycję

Trzy filary ochrony procedur:

1. Separacja Uprawnień (Capability Guard):

• Agenci AI posiadają co najwyżej uprawnienie kelverse_author_procedures – mogą tworzyć własne szkice lub proponować zmiany (propose_procedure_change).
• Pełne zatwierdzenie i aktywacja procedury wymaga uprawnienia człowieka: kelverse_manage_procedures (zastrzeżonego wyłącznie dla zaufanych ról administratora).

1. Zasada nadrzędności repozytorium (The Precedence Rule):

• Do każdej procedury przesyłanej do agenta dołączana jest niezmienna klauzula:

1. Automatyczna filtracja treści (Bounded Content & Redaction):

• System skanuje treść procedur pod kątem prób wyłączenia zabezpieczeń, omijania autoryzacji czy automatycznego zatwierdzania kodu.
• Podejrzane instrukcje są automatycznie blokowane lub zastępowane znacznikiem [removed: a procedure may not instruct this].

07. Raporty i Wskaźniki CSAT

Zarządzanie jakością obsługi w Kelverse Ticketing Tool opiera się na twardych danych analitycznych. Moduł raportowy przetwarza codzienne operacje na czytelne wykresy i wskaźniki KPI, a moduł CSAT pozwala poznać bezpośrednie opinie klientów.

1. Moduł Raportów i Analityki

Dostępny w menu: Zgłoszenia → Raporty (admin.php?page=kelverse-ticketing-reports).

Zoptymalizowana agregacja dzienna (kelverse_daily_metrics)

Aby generowanie raportów nie spowalniało działania serwera przy dziesiątkach tysięcy zgłoszeń, system nie przelicza całej historii na bieżąco. Zamiast tego, zadanie w tle agreguje codzienne metryki do dedykowanej tabeli kelverse_daily_metrics.

T1[Nowe zgłoszenia]
T2[Odpowiedzi agentów]
T3[Rozwiązania spraw]
T4[Zdarzenia SLA]
AGG[Kelverse Reports Aggregator]
M[(Zindeksowane metryki dzienne)]
DASH[Interaktywne Wykresy & Filtry]
T1 & T2 & T3 & T4 --> AGG
AGG --> M
M --> DASH

Kluczowe wskaźniki efektywności (KPI):

1. Wolumen zgłoszeń:

• Liczba zgłoszeń wpłyniętych vs. liczba zgłoszeń rozwiązanych w zadanym okresie.
• Wskaźnik Backlogu (liczba spraw pozostających otwartych).

1. Czas Pierwszej Reakcji (First Response Time / MTTA):

• Średni i medianowy czas (w minutach/godzinach) od wpłynięcia zgłoszenia do pierwszej merytorycznej odpowiedzi publicznej agenta.

1. Czas Pełnego Rozwiązania (Resolution Time / MTTR):

• Średni czas potrzebny na doprowadzenie sprawy do statusu zamkniętego (done / resolved).

1. Zgodność z umowami SLA (SLA Compliance Rate):

• Procent spraw zrealizowanych w terminie w stosunku do zgłoszeń z naruszonym terminem (SLA Breaches).

1. Rozkład obciążenia:

• Zestawienie liczby zgłoszeń w podziale na: produkty, kategorie problemów, priorytety oraz poszczególnych agentów.

Zakresy czasowe i eksport:

• Szybkie filtry: Ostatnie 7 dni, Ostatnie 30 dni, Bieżący miesiąc, Ostatni kwartał, Dowolny zakres dat.
• Możliwość filtrowania raportu do wybranego produktu (projektu).

2. Badanie Satysfakcji Klienta (CSAT)

Moduł CSAT (Customer Satisfaction Score) automatycznie zbiera informacje zwrotne po zakończeniu obsługi sprawy.

Jak działa proces oceny?

1. Wyzwalacz (Trigger): W momencie zmiany statusu zgłoszenia na zamknięty (np. done), system odblokowuje ankietę w portalu klienta oraz opcjonalnie wysyła e-mail z prośbą o opinię.
2. Formularz oceny:

• Skala 1 do 5 gwiazdek (od Bardzo niezadowolony do Świetna obsługa).
• Opcjonalne pole tekstowe na komentarz (uwagi klienta).

1. Jednokrotność oceny: Każde zgłoszenie może zostać ocenione tylko raz; zmiana oceny jest blokowana, co gwarantuje wiarygodność statystyk.

Struktura danych CSAT (kelverse_csat):

Rekordy ocen są przechowywane w dedykowanej tabeli powiązanej ze zgłoszeniem, klientem oraz agentem, który rozwiązał sprawę.

Wskaźniki CSAT w panelu administracyjnym:

• Ogólny wskaźnik CSAT: Procent ocen pozytywnych (4 i 5 gwiazdek) w odniesieniu do wszystkich nadesłanych ankiet.
• Średnia ocena gwiazdkowa: Średnia arytmetyczna ze wszystkich ocen.
• Ranking i statystyki agentów: Zestawienie pokazujące, którzy pracownicy cieszą się najwyższym uznaniem klientów.
• Lista komentarzy: Przegląd jakościowy opinii użytkowników pomagający w identyfikacji problemów z procedurami lub dokumentacją.

08. Integracja AI i Serwer MCP (Model Context Protocol)

Kelverse Ticketing Tool jest jednym z pierwszych na świecie systemów Helpdesk i Issue Trackerów dla WordPress posiadających natywny serwer Model Context Protocol (MCP). Pozwala to zaawansowanym modelom sztucznej inteligencji (takim jak Claude Code, Cursor, Google Antigravity czy autonomiczne boty programistyczne) na bezpośrednią, ustrukturyzowaną interakcję z systemem zgłoszeń.

1. Czym jest natywny serwer MCP w Kelverse?

Tradycyjne integracje AI wymagają uruchamiania pośredniczących skryptów w Node.js lub Pythonie. W Kelverse Ticketing Tool serwer MCP jest wbudowany bezpośrednio w rdzeń wtyczki WordPress:

C1[Claude Code CLI]
C2[Cursor IDE]
C3[Antigravity Agent]
POST[POST /wp-json/kelverse-ticketing/v1/mcp]
AUTH[Nagłówek: Authorization Basic App-Password]
JSONRPC[JSON-RPC 2.0 Parser]
REG[Rejestr 39 Narzędzi MCP]
CAP[Weryfikacja Uprawnień & Rate Limit]
EXEC[Wykonanie Metody & Odpowiedź]
C1 & C2 & C3 --> POST
POST --> AUTH
AUTH --> JSONRPC
JSONRPC --> REG
REG --> CAP
CAP --> EXEC

• Endpoint: https://twojadomena.pl/wp-json/kelverse-ticketing/v1/mcp
• Format protokołu: JSON-RPC 2.0 (zgodny ze specyfikacją MCP).
• Transport: HTTP Streamable (--transport http).
• Autoryzacja: Hasła aplikacji WordPress (Application Passwords). Każde żądanie jest autoryzowane niezależnie; brak konieczności zarządzania stanem sesji (Mcp-Session-Id).
• Wersje protokołu: Obsługa wersji 2025-06-18, 2025-03-26 oraz 2024-11-05.

2. Profile Narzędzi: work i debug

Narzędzia serwera podzielone są na dwa profile:

1. Profil work: Narzędzia operacyjne wykorzystywane w codziennej pracy programistycznej (pobieranie zadań, rezerwacja, aktualizacja statusów, linkowanie kodu, zgłaszanie do przeglądu).
2. Profil debug: Narzędzia inspekcyjne (sprawdzanie kontekstu konta, uprawnień użytkownika, limitów zapytań i konfiguracji środowiska).

3. Kompletny Rejestr 39 Narzędzi MCP

System udostępnia 39 ściśle zdefiniowanych narzędzi ze schematami JSON Schema:

Narzędzia Odczytu (Read Tools – 14 narzędzi):

1. get_integration_context: Zwraca tożsamość zalogowanego agenta, posiadane uprawnienia, powiązane repozytoria i limity zapytań.
2. list_ready_tickets: Zwraca listę zgłoszeń zakwalifikowanych jako gotowe do podjęcia przez programistę / AI.
3. search_tickets: Wyszukiwarka zgłoszeń według filtrów (status, produkt, priorytet, klasa agenta, tagi).
4. get_ticket: Pobiera pełne szczegóły wybranego zgłoszenia (numer, tytuł, opis, pola własne, SLA).
5. get_ticket_notes: Pobiera wewnętrzne notatki techniczne zgłoszenia.
6. get_ticket_activity: Zwraca audytową historię zmian zgłoszenia (oś czasu zdarzeń).
7. get_ticket_relations: Zwraca listę powiązań (zależności, blokerów, duplikatów).
8. get_active_claim: Sprawdza, czy zadanie jest aktualnie zarezerwowane i przez kogo.
9. list_projects: Zwraca listę wszystkich aktywnych produktów/projektów.
10. get_project_brief: Pobiera kartę techniczną produktu (architektura, wytyczne techniczne).
11. get_project_roadmap: Zwraca roadmapę wydań i stan milestone’ów projektu.
12. list_procedures: Pobiera spis obowiązujących procedur operacyjnych.
13. get_procedure: Pobiera treść konkretnej procedury operacyjnej z zachowaniem reguły nadrzędności.
14. list_changelog: Pobiera wpisy z rejestru zmian (changelog).

Narzędzia Zapisu (Write Tools – 25 narzędzi):

1. create_ticket: Tworzy nowe zgłoszenie deweloperskie w wybranym produkcie.
2. create_subticket: Tworzy zadanie podrzędne powiązane ze zgłoszeniem nadrzędnym.
3. create_project: Zakłada nowy produkt/projekt w systemie.
4. add_changelog_entry: Dopisuje pozycję do dziennika zmian.
5. clear_changelog: Czyści wersję roboczą changeloga.
6. renumber_changelog: Porządkuje numerację pozycji w changelogu.
7. delete_changelog_entry: Usuwa wskazany wpis z changeloga.
8. propose_project_brief: Składa propozycję aktualizacji karty technicznej produktu (oczekuje na akceptację człowieka).
9. propose_procedure_change: Składa propozycję modyfikacji procedury (bezpieczna granica zaufania).
10. record_procedure: Zapisuje procedurę stworzoną przez agenta w ramach własnych uprawnień.
11. assign_ticket_milestone: Przypisuje zgłoszenie do wskazanego wydania (milestone’u).
12. define_milestone: Definiuje nowe wydanie w roadmapie projektu.
13. update_ticket: Modyfikuje parametry zgłoszenia (priorytet, kategoria, pola dodatkowe).
14. add_ticket_relation: Tworzy relację między zgłoszeniami (np. dodaje powiązanie blokujące).
15. start_ticket_work: Zajmuje zgłoszenie (Claim) – rozpoczyna pracę nad zadaniem, przestawia status na in_progress i rezerwuje dzierżawę czasową.
16. renew_ticket_claim: Odnawia dzierżawę czasową rezerwacji (Heartbeat zadania).
17. release_ticket_claim: Zwalnia rezerwację zadania, przywracając je do puli zadań gotowych.
18. add_ticket_internal_note: Dodaje techniczną notatkę wewnętrzną z podsumowaniem analizy lub napotkanych problemów.
19. update_ticket_internal_note: Modyfikuje istniejącą notatkę wewnętrzną.
20. mark_ticket_blocked: Oznacza zadanie jako zablokowane (blocked) z podaniem przyczyny.
21. resume_ticket_work: Wznawia pracę nad uprzednio zablokowanym zadaniem.
22. link_ticket_code_artifact: Wiąże zadanie z artefaktem kodu (URL commita, gałęzi lub Pull Requesta).
23. submit_ticket_for_review: Przekazuje zadanie do weryfikacji (in_review) po zakończeniu prac programistycznych.
24. add_ticket_public_reply: Wysyła oficjalną odpowiedź publiczną do klienta (wymaga uprawnienia).
25. close_ticket: Zamyka rozwiązane zgłoszenie.

4. Cykl Pracy Agenta AI nad Zgłoszeniem (Claims Lifecycle)

Mechanizm rezerwacji zadań (Claims) zapobiega konfliktom, gdy nad repozytorium pracuje wielu programistów lub równoległych agentów AI:

[*] --> Ready: Zgłoszenie w stanie ready
Ready --> InProgress: start_ticket_work (Ustanowienie Claim)
InProgress --> InProgress: renew_ticket_claim (Odnowienie dzierżawy)
InProgress --> Blocked: mark_ticket_blocked (Wykryto bloker)
Blocked --> InProgress: resume_ticket_work (Bloker usunięty)
InProgress --> InReview: submit_ticket_for_review + link_ticket_code_artifact
InProgress --> Ready: release_ticket_claim (Zwolnienie przez agenta)
InProgress --> Ready: Wygaśnięcie dzierżawy (Auto-release przez Cron)
InReview --> Done: close_ticket (Zatwierdzenie przez człowieka)
Done --> [*]

1. Wybór zadania: Agent odpytuje list_ready_tickets o zadania oczekujące na realizację.
2. Rezerwacja (Lease): Agent wywołuje start_ticket_work. System przypisuje agenta do zadania, zmienia status na in_progress i tworzy wpis w tabeli kelverse_ticket_claims z czasem wygaśnięcia (np. 60 minut).
3. Auto-zwolnienie przy awarii: Jeśli agent AI ulegnie awarii i nie odnowi rezerwacji (renew_ticket_claim), cogodzinne zadanie WP-Cron automatycznie zwalnia rezerwację i przywraca zgłoszenie do statusu ready.
4. Finalizacja: Po napisaniu kodu agent linkuje Pull Request (link_ticket_code_artifact) i przekazuje zadanie do recenzji (submit_ticket_for_review).

5. Przykładowa Konfiguracja Klientów AI

Konfiguracja w Claude Code / Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "kelverse-ticketing": {
      "command": "curl",
      "args": [
        "-s",
        "-X", "POST",
        "https://twojadomena.pl/wp-json/kelverse-ticketing/v1/mcp",
        "-H", "Content-Type: application/json",
        "-u", "twoj_login_wp:xxxx xxxx xxxx xxxx"
      ]
    }
  }
}

Konfiguracja w Cursor IDE / Antigravity (mcp.json):

{
  "mcpServers": {
    "kelverse": {
      "url": "https://twojadomena.pl/wp-json/kelverse-ticketing/v1/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Basic dHdval9sb2dpbjp0d29qZV9oYXNsb19hcGxpa2Fjamk="
      }
    }
  }
}

(Wartość nagłówka to zakodowany w Base64 ciąg login:hasło_aplikacji).

09. REST API i Referencja dla Programistów

Kelverse Ticketing Tool udostępnia bogaty interfejs REST API osadzony w oficjalnym mechanizmie WordPress REST API w przestrzeni nazw:

/wp-json/kelverse-ticketing/v1

Interfejs podzielony jest na trzy dedykowane warstwy o różnym poziomie dostępu i przeznaczeniu.

1. Warstwy REST API

API["/wp-json/kelverse-ticketing/v1"]
API --> PUB["1. /public/* (Publiczne)"]
API --> WS["2. /workspace/* (Zespół / SPA)"]
API --> DEV["3. /development/* (Developer & AI)"]
PUB --> PUB1["GET /public/tickets (Feed forum bez autoryzacji)"]
WS --> WS1["GET /workspace/bootstrap"]
WS --> WS2["GET|POST /workspace/tickets"]
WS --> WS3["POST /workspace/tickets/{nr}/reply"]
WS --> WS4["POST /workspace/tickets/{nr}/update"]
WS --> WS5["POST /workspace/tickets/bulk"]
DEV --> DEV1["GET|POST /development/tickets"]
DEV --> DEV2["POST /development/tickets/{nr}/claim"]
DEV --> DEV3["POST /development/tickets/{nr}/code-links"]
DEV --> DEV4["GET|POST /development/procedures"]
DEV --> DEV5["GET|POST /development/changelog"]

2. Warstwa Publiczna (/public/*)

Dostępna bez autoryzacji. Zwraca wyłącznie dane jawnie oznaczone przez użytkowników jako publiczne.

GET /wp-json/kelverse-ticketing/v1/public/tickets

Pobiera publiczny strumień zgłoszeń (np. do zasilenia zewnętrznego widżetu, aplikacji mobilnej lub bloku Gutenberga).

• Filtry zapytania:
• product (string): Slug produktu.
• category (string): Slug kategorii.
• search (string): Fraza wyszukiwania.
• page (int), per_page (int, domyślnie 10, max 50).
• Bezpieczeństwo: Zwraca wyłącznie pola z twardej białej listy (number, title, status, category, product, created_at). Nigdy nie ujawnia adresów e-mail, danych osobowych, prywatnych załączników ani notatek wewnętrznych.

3. Warstwa Zespołowa Workspace (/workspace/*)

Dedykowana dla interfejsu React SPA na stronie /tickets/. Wszystkie trasy wymagają zalogowania i uprawnienia manage_kelverse_tickets.

Główne endpointy:

• GET /workspace/bootstrap: Pobiera słowniki statusów, priorytetów, produktów, uprawnień użytkownika i flag systemowych.
• GET /workspace/properties: Zwraca schemat właściwości i dynamicznych pól formularza.
• GET /workspace/tickets: Zwraca przefiltrowaną i spaginowaną listę zgłoszeń.
• GET /workspace/tickets/{number}: Zwraca pełne szczegóły wybranego zgłoszenia na potrzeby bocznej szuflady.
• POST /workspace/tickets: Tworzy nowe zgłoszenie z poziomu panelu agenta.
• POST /workspace/tickets/{number}/update: Częściowa aktualizacja pól zgłoszenia z weryfikacją expected_revision.
• POST /workspace/tickets/{number}/group: Zmiana kolumny na tablicy Kanban (np. zmiana statusu lub priorytetu).
• POST /workspace/tickets/{number}/reply: Wysłanie odpowiedzi publicznej do klienta.
• POST /workspace/tickets/{number}/note: Dopisanie notatki wewnętrznej na żółtym tle.
• POST /workspace/tickets/{number}/read: Oznaczenie zgłoszenia jako przeczytanego do danego identyfikatora zdarzenia.
• POST /workspace/tickets/{number}/followers: Dodanie użytkownika do listy obserwujących.
• POST /workspace/tickets/{number}/relations: Ustanowienie relacji (zależność, bloker).
• GET|POST /workspace/tickets/{number}/merge: Podgląd i wykonanie scalenia zgłoszeń.
• POST /workspace/tickets/bulk: Wykonanie akcji masowej (zmiana statusu, przypisania lub przeniesienie do kosza dla wielu ID).
• GET|POST|DELETE /workspace/views: Zarządzanie zapisanymi widokami agenta.

4. Warstwa Deweloperska (/development/*)

Wykorzystywana przez integracje CI/CD, zewnętrzne repozytoria Git, asystentów AI oraz zaawansowane narzędzia automatyzacji.

Autoryzacja i Zasada Najmniejszych Uprawnień (Least Privilege)

Trasy deweloperskie są zabezpieczone precyzyjnymi uprawnieniami szczegółowymi:

5. Bezpieczeństwo Zapisów: Idempotencja i Rate Limiting

Nagłówek Idempotencji (Idempotency-Key):

Wszystkie operacje zapisu (POST, PUT, DELETE) obsługują nagłówek idempotencji:

Idempotency-Key: 7b9a5281-2c1b-4f81-8b3d-1a892e6f4321

• Gdy żądanie zostanie ponowione z tym samym kluczem w ciągu 24 godzin (np. w wyniku zerwania połączenia sieciowego lub podwójnego kliknięcia), serwer nie wykonuje operacji ponownie.
• Serwer zwraca zbuforowaną odpowiedź z tabeli kelverse_idempotency, eliminując ryzyko zduplikowanych komentarzy lub podwójnych zmian statusu.

Ograniczanie częstotliwości (Rate Limiting):

• Operacje zapisu są chronione przez Kelverse_Ticketing_Rate_Limiter.
• W przypadku przekroczenia dozwolonej liczby zapytań w oknie czasowym, serwer zwraca kod błędu 429 Too Many Requests wraz z informacją o czasie oczekiwania na odblokowanie.
• Odczyty (GET) w warstwie Workspace nie podlegają limitom, zapewniając płynne działanie interfejsu użytkownika.

10. Bezpieczeństwo, RODO i Baza Danych

Bezpieczeństwo danych klientów, integralność bazy danych oraz zgodność z wymogami prawnymi (RODO / GDPR) stanowiły kluczowe wytyczne przy projektowaniu Kelverse Ticketing Tool.

1. Bezpieczny Magazyn Załączników (Secure File Storage)

Tradycyjne załączniki w WordPressie trafiają do katalogu wp-content/uploads/ i są publicznie dostępne dla każdego, kto odgadnie bezpośredni adres URL. W Kelverse Ticketing Tool zastosowano zupełnie inne podejście:

U[Użytkownik przesyła załącznik] --> FC[File Controller & Sanitizer]
FC --> ST[Dedykowany katalog wp-content/uploads/kelverse-ticketing-token/]
ST --> HTA[.htaccess: Deny from all]
ST --> NGN[nginx: Odrzucanie bezpośrednich żądań statycznych]
ST --> IDX[Pusty plik index.php]
REQ[Żądanie pobrania pliku] --> DISP[Endpoint PHP: /kelverse-file/{id}]
DISP --> POL{Kelverse Access Policy: Czy użytkownik ma uprawnienia?}
POL -- NIE --> E403[403 Forbidden / 404 Not Found]
POL -- TAK --> STREAM[Bezpieczne strumieniowanie pliku przez PHP z nagłówkami no-cache]

Elementy ochrony plików:

1. Losowy katalog magazynu: Ścieżka katalogu zawiera unikalny, 32-znakowy token kryptograficzny przechowywany w opcjach bazy danych.
2. Blokada na poziomie serwera WWW: W katalogu generowany jest plik .htaccess z dyrektywą Deny from all oraz pliki index.php i web.config (dla IIS).
3. Pobieranie wyłącznie z weryfikacją uprawnień: Pliki są pobierane przez kontroler Kelverse_Ticketing_File_Controller. Pobranie pliku jest dozwolone wyłącznie dla:

• Autora zgłoszenia (po zalogowaniu).
• Członków zespołu z uprawnieniem manage_kelverse_tickets.
• Żadne żądanie anonimowe nie ma możliwości odczytania zawartości pliku.

2. Ochrona Prywatności i Zgodność z RODO (GDPR)

Wtyczka aktywnie blokuje przypadkowe wycieki poufnych zgłoszeń przez wbudowane mechanizmy WordPressa:

1. Blokada publicznych powierzchni WordPressa:

• Mapy witryny (XML Sitemaps): Filtr wp_sitemaps_post_types całkowicie wyklucza post type kelverse_ticket z generowanych map sitemap.
• Kanały RSS / Feeds: Bezpośrednie blokowanie prób odpytywania kanałów RSS dla zgłoszeń (/feed/?post_type=kelverse_ticket).
• Endpointy oEmbed: Blokada generowania podglądów oEmbed (disable_oembed), zapobiegająca odczytaniu fragmentów prywatnych spraw przez zewnętrzne serwisy.

2. Narzędzia ochrony danych osobowych WordPress (Privacy Tools):

Wtyczka w pełni integruje się z oficjalnymi narzędziami WordPressa dostępnymi w menu: Narzędzia → Eksportuj dane osobowe oraz Usuń dane osobowe:

• Eksport danych klienta: Eksportuje wszystkie zgłoszenia, komentarze, oceny CSAT i metadane powiązane z adresem e-mail użytkownika.
• Prawo do bycia zapomnianym (Anonimizacja / Usunięcie): Po zatwierdzeniu wniosku o usunięcie danych, system anonimizuje zgłoszenia klienta (zastępuje dane osobowe ciągami zanonimizowanymi lub usuwa rekordy zgodnie z konfiguracją retencji).

3. Architektura Tabel Bazy Danych MySQL

Zamiast przeciążać standardową tabelę wp_postmeta, Kelverse Ticketing Tool wykorzystuje zestaw wyspecjalizowanych tabel relacyjnych:

4. Transakcyjne Migracje Bazy Danych

Silnik migracji (Kelverse_Ticketing_Migrations) zarządza wersjonowaniem schematu bazy:

• Idempotencja: Każda z 32 migracji posiada unikalny numer i jest wykonywana dokładnie jeden raz.
• Blokada MySQL Named Lock: Przed rozpoczęciem migracji system zakłada nazwaną blokadę na poziomie silnika MySQL. Zapobiega to jednoczesnemu uruchomieniu migracji przez dwa równoległe żądania HTTP (np. przy dużym ruchu na witrynie).
• Automatyczne wznawianie po błędzie: Jeśli którakolwiek migracja zgłosi błąd, numer wersji nie jest podnoszony, a administrator widzi czytelny komunikat w panelu wp-admin z informacją o przyczynie.

5. Bezpieczny Cykl Życia przy Deinstalacji (uninstall.php)

Zgodnie z najlepszymi praktykami inżynierii oprogramowania:

• Zwykłe wyłączenie lub usunięcie wtyczki NIGDY nie usuwa danych zgłoszeń ani bazy klientów.
• Całkowite wyczyszczenie danych jest możliwe wyłącznie wtedy, gdy administrator świadomie zaznaczy opcję:

• Dopiero po włączeniu tej flagi plik uninstall.php wykonuje bezpieczne, porcjowane usuwanie postów, tabel, katalogu załączników i opcji konfiguracyjnych.

11. Shortcody, Bloki Gutenberg i Szablony Motywu

Kelverse Ticketing Tool zapewnia pełną elastyczność w integracji z dowolnym motywem WordPress — zarówno klasycznym, jak i nowoczesnym motywem blokowym (Full Site Editing / FSE).

1. Referencja Shortcodów

Wtyczka udostępnia cztery główne kody krótkie (shortcody), które można umieścić na dowolnych podstronach WordPressa:

1. [kelverse_support]

• Zastosowanie: Główny Support Hub – centralny punkt pomocy dla odwiedzających.
• Domyślny adres: /support/
• Działanie: Prezentuje kafelki nawigacyjne do formularza zgłoszeń, portalu „Moje zgłoszenia”, opcjonalnej strony FAQ oraz publicznego spisu spraw. Dla zalogowanych agentów wyświetla również dyskretny odnośnik do przestrzeni roboczej Workspace.

2. [kelverse_ticket_form]

• Zastosowanie: Publiczny formularz przesyłania nowego zgłoszenia.
• Domyślny adres: /support/report/
• Działanie: Renderuje responsywny formularz z polami tytułu, opisu, wyboru produktu, kategorii, widoczności, dynamicznych pól własnych oraz modułem bezpiecznych załączników wraz z zabezpieczeniami antyspamowymi.

3. [kelverse_ticket_portal]

• Zastosowanie: Portal klienta „Moje zgłoszenia”.
• Domyślny adres: /support/my-tickets/
• Działanie: Wyświetla zalogowanemu użytkownikowi listę jego zgłoszeń z filtrowaniem według statusu, kategorii oraz wyszukiwarką tekstową. Użytkownicy niezalogowani widzą formularz logowania.

4. [kelverse_ticket_workspace]

• Zastosowanie: Przestrzeń robocza zespołu i agentów (aplikacja React SPA).
• Domyślny adres: /tickets/
• Działanie: Inicjalizuje aplikację Kanban i szufladę szczegółów zgłoszenia. Wymaga uprawnienia manage_kelverse_tickets. Ładuje skrypty i arkusze stylów wyłącznie na stronie, na której występuje shortcode.

2. Dynamiczne Bloki Gutenberg (FSE)

W edytorze bloków WordPressa dostępna jest dedykowana kategoria Kelverse:

CAT[Kategoria: Kelverse] --> B1["kelverse/public-tickets (Publiczne zgłoszenia)"]
CAT --> B2["kelverse/products (Katalog produktów)"]
CAT --> B3["kelverse/submit (Zgłoś problem)"]

Wszystkie bloki Kelverse są blokami dynamicznymi (Server-Side Rendered), co oznacza, że ich treść jest zawsze świeża, bezpieczna i nie wymaga kompilowania osobnych skryptów edytora (@wordpress/scripts).

Blok 1: kelverse/public-tickets (Kelverse: Publiczne zgłoszenia)

Prezentuje listę publicznie udostępnionych zgłoszeń (np. otwarty bug tracker dla oprogramowania).

• Atrybuty i opcje w panelu bocznym edytora:
• product (tekst): Slug produktu, dla którego mają być pokazane zgłoszenia (pozostawienie pustego wyświetla zgłoszenia ze wszystkich produktów; wartość current pobiera produkt z bieżącej strony).
• count (liczba): Liczba zgłoszeń na stronę (domyślnie 10).
• show_search (przełącznik): Czy wyświetlać pole wyszukiwarki nad listą.
• show_pagination (przełącznik): Czy włączyć stronicowanie wyników.

Blok 2: kelverse/products (Kelverse: Produkty)

Prezentuje katalog dostępnych produktów jako sekcje forum kierujące do właściwych zgłoszeń.

• Atrybuty i opcje w panelu bocznym edytora:
• layout (wybór): Układ kafelkowy (Grid) lub widok listy (List).
• show_counts (przełącznik): Czy wyświetlać liczniki otwartych zgłoszeń przy każdym produkcie.

Blok 3: kelverse/submit (Kelverse: Zgłoś problem)

Blokowy formularz zgłaszania spraw do osadzenia w treści artykułu lub landing page’a.

• Atrybuty i opcje w panelu bocznym edytora:
• product (tekst): Blokada do konkretnego produktu (jeśli wypełnione, użytkownik nie musi wybierać produktu z listy).
• intro (tekst): Opcjonalny tekst wprowadzający wyświetlany nad formularzem.

3. Nadpisywanie Szablonów w Motywie (Theme Overrides)

Strukturę widoków wtyczki można łatwo dostosować do indywidualnego designu Twojej witryny bez modyfikowania kodu źródłowego wtyczki:

1. Widok pojedynczego zgłoszenia (single-ticket.php)

Domyślny szablon znajduje się w katalogu wtyczki:

wp-content/plugins/kelverse-ticketing/templates/single-ticket.php

Aby go nadpisać, utwórz w katalogu swojego aktywnego motywu (lub motywu potomnego) plik:

wp-content/themes/twoj-motyw/kelverse-ticketing/single-ticket.php

Wtyczka automatycznie wykryje ten plik za pomocą funkcji locate_template() i użyje go zamiast szablonu domyślnego.

2. Szablon pełnoekranowy Workspace (workspace.php)

Dla przestrzeni roboczej /tickets/ wtyczka rejestruje szablon Canvas, który eliminuje nagłówki i stopki motywu. W razie potrzeby pełnej integracji z własnym layoutem, szablon można również nadpisać w katalogu motywu:

wp-content/themes/twoj-motyw/kelverse-ticketing/workspace.php

4. Personalizacja Wizualna (CSS)

Wszystkie elementy interfejsu posiadają intuicyjne klasy CSS z przedrostkiem kelverse-, ułatwiające dostosowanie kolorów i typografii w arkuszu style.css motywu:

/* Przykładowe reguły dostosowujące wygląd */
/* Karta w Support Hubie */
.kelverse-support-card {
    border-radius: 12px;
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.05);
    transition: transform 0.2s ease;
}
.kelverse-support-card:hover {
    transform: translateY(-4px);
}
/* Plakietki statusów */
.kelverse-status-badge {
    font-weight: 600;
    text-transform: uppercase;
    letter-spacing: 0.5px;
    border-radius: 4px;
}
/* Formularz zgłoszeniowy */
.kelverse-ticket-form input,
.kelverse-ticket-form textarea,
.kelverse-ticket-form select {
    border-color: #e2e8f0;
    border-radius: 6px;
}