Standardyzacja systemu odpowiedzi i obsługi błędów (Unified Response System)

[dam2452]

Obecnie komunikaty zwracane przez bota są niespójne. Różne komendy zwracają błędy w różnych formatach – raz jest to surowy tekst, raz sformatowany blok, a innym razem brak jest jasnej instrukcji dla użytkownika.

Dodatkowo, logika tworzenia tych komunikatów jest rozproszona po poszczególnych handlerach, co prowadzi do redundancji kodu (np. osobne handlery dla pomocy, osobne dla błędów walidacji). Logi systemowe mieszały się czasem z komunikatami przeznaczonymi dla użytkownika.

Cel

Zaprojektować i wdrożyć globalny, abstrakcyjny mechanizm generowania odpowiedzi dla użytkownika. Wszystkie komunikaty (Błędy, Ostrzeżenia, Sukcesy, Info) mają posiadać identyczną strukturę wizualną, wykorzystującą bloki kodu Markdown.

Proponowane Rozwiązanie Architektoniczne

1. Abstrakcja (Base Command / ResponseFactory)

Należy wynieść logikę formatowania do klasy bazowej lub dedykowanego serwisu (np. ResponseBuilder).
Każda komenda powinna dziedziczyć po klasie bazowej (lub implementować interfejs), który wymusza zdefiniowanie:

• usage_description (opis działania)
• parameters (lista parametrów)
• example (przykład użycia)

Metoda w klasie bazowej (np. send_error, send_success) automatycznie złoży te dane w sformatowany blok tekstu.

2. Standard Wizualny (Markdown + Formatting)

Każda odpowiedź do użytkownika ma być wysyłana jako blok kodu (lub sformatowany tekst zachowujący wcięcia) według wzorca:

1. Nagłówek: Typ komunikatu (wielkimi literami) + Tytuł.
2. Treść: Opis sytuacji lub błędu.
3. Parametry (opcjonalnie): Wypunktowana lista dostępnych opcji.
4. Przykład (opcjonalnie): Gotowa komenda do skopiowania.

Wymaganie techniczne: Aby zachować wcięcia i czytelność w klientach czatu, spacje wiodące i formatujące muszą być programowo zamieniane na \u00A0 (non-breaking space).

3. Typy Komunikatów

System musi wspierać 4 główne typy komunikatów (różniące się nagłówkiem):

• ERROR – Krytyczne błędy, niepoprawne użycie komendy.
• WARNING – Akcja wykonana częściowo lub wymagająca uwagi.
• INFO – Informacje ogólne.
• SUCCESS – Potwierdzenie pomyślnego wykonania akcji.

Wzorzec Implementacji

Przykład logiki formatującej (pseudo-kod):

def build_response(type, title, description, params=None, example=None):
    # Logika mapująca typ na odpowiedni nagłówek
    # Logika składająca string
    # Logika zamieniająca spacje " " na "\u00A0" w odpowiednich miejscach
    pass

Docelowy wygląd outputu (dla błędu użycia):

[IKONA_TYPU] BŁĄD - BRAK CELU

Podaj cel reindeksowania:
• all - wszystkie seriale
• all-new - tylko nowe seriale
• <nazwa> - konkretny serial

Przykład:
   /reindex ranczo

Zadania do wykonania

• Stworzyć klasę/moduł ResponseFormatter lub ResponseBuilder implementującą logikę zamiany spacji i składania szablonu.
• Zaktualizować klasę bazową komend lub stworzyć abstrakcję, aby wymusić ujednolicone zwracanie błędów.
• Oddzielić warstwę logowania (angielski, proste logi) od warstwy prezentacji (polski, sformatowany Markdown).
• Przeprowadzić refaktoryzację wszystkich istniejących komend w projekcie, aby korzystały z nowego systemu.
• Usunąć redundantne funkcje "help" w poszczególnych komendach (nowy komunikat błędu zawiera już instrukcję i przykład).

Kryteria Akceptacji

1. Wszystkie komendy w projekcie zwracają błędy w identycznym formacie wizualnym.
2. Kod jest wolny od "hardkodowanych" stringów z błędami w poszczególnych plikach (używa centralnego helpera).
3. Wcięcia w komunikatach są poprawnie wyświetlane u klienta (dzięki \u00A0).
4. Usunięto stary, niespójny kod odpowiedzialny za wyświetlanie pomocy przy błędach.