BuddyUP – dokumentace pluginu

Tento software představuje výstup realizace výzkumného projektu TA ČR s názvem „BuddyUP! - Podpora začleňování ohrožených dětí žijících v segregovaném prostředí“, který je realizován na Fakultě sociálních studií ve spolupráci s Institutem prevence, z.s. a byl realizován za finanční podpory TA ČR.

BuddyUP je kompletní plugin pro párování mentorů, studentů a dětí a pro vedení deníků a reflexí (včetně cílů a jejich pokroku). Kombinuje administrační přehledy s front-end formuláři přes shortcody a přehledné veřejné URL.

Praktický tahák pro každodenní práci v administraci BuddyUP. Zaměřuje se na kontrolu dat, párování rolí a exporty.

Stručný návod pro studenty, jak pracovat s deníky, reflexemi a cíli dítěte na webu (front-end).

Co uvidíš na dashboardu

• Přehled deníků a reflexí včetně stavu rozpracovaných záznamů.
• Vizuální přehled dat v motivu vesmíru pokrývá cíle dítěte i cíle studenta: planety znázorňují jednotlivé cíle (dětské i studentské), jejich velikost ukazuje význam/naplnění, oběžné dráhy slouží jako časová osa a hvězdy zvýrazňují důležité milníky. Díky tomu je na první pohled vidět, co se daří a co ještě čeká.
• Rychlé odkazy na formuláře a výstupy.
• Kontakty na garanta a podporu.

1. Nainstaluj a aktivuj plugin (viz níže).
2. V administraci otevři BuddyUP → Nastavení a doplň kontakty + (volitelně) hravý motiv.
3. Vytvoř stránku „Nástěnka“ a vlož shortcode [buddyup_dashboard] (doporučený vstup pro studenty).
4. Vytvoř stránky pro práci studenta (doporučení v sekci „Front-end“ a „Shortcody“).
5. Po aktivaci/změně permalinků otevři Nastavení → Permalinky (flush rewrite pravidel).

• WordPress: plugin je psaný pro WP 6.x (řeší kompatibilitu s WP 6.9 ohledně „conditional comments“).
• PHP: doporučeno 8.0+ (kvůli funkcím jako str_contains).
• GD knihovna: volitelně pro generování timeline obrázku do PDF (pokud není dostupná, export použije fallback).
• mPDF: je součástí repozitáře (libs/mpdf) a používá se pro PDF exporty.
• Internet: některé admin grafy načítají Chart.js z CDN (viz „Statistiky“).

Instalace

• Nahraj složku pluginu do wp-content/plugins/buddyup (nebo přes ZIP v administraci).
• Aktivuj v Pluginy.

Co se stane po aktivaci

• Zaregistrují se role a CPT (Deníky, Reflexe, Děti, Zpětná vazba).
• Vytvoří se povinné stránky: /karty + podstránky /karta-buddy a /karta-ditete.
• Registrovaná rewrite pravidla se při aktivaci „flushnou“.

Důležité

• Pokud veřejné URL vrací 404, otevři Nastavení → Permalinky a ulož (flush rewrite).

Role se vytváří a udržují v includes/roles.php.

Custom Post Types (CPT)

• buddyup_journal – deníkový zápis (autor = student), meta např. dítě, cíle, aktivity, hodnocení, časomíra.
• buddyup_reflection – reflexe (autor = student), meta měsíc/rok, typ (měsíční/trimestrální), doplňující otázky.
• buddyup_child – dítě, meta základní údaje, cíle (buddyup_goals) a roční záznamy.
• buddyup_feedback – zpětná vazba z front-endu (kategorie, příloha, verze pluginu).

Párování přes user meta

• buddyup_child_id – přiřazené dítě ke studentovi.
• buddyup_mentor_id – přiřazený mentor ke studentovi.
• buddyup_supervisor_user_id – přiřazený supervizor ke studentovi.
• buddyup_practice_teacher_id – přiřazený vyučující semináře k praxi ke studentovi.

Admin stránka BuddyUP → Nastavení (includes/admin/settings.php) ukládá hodnoty do wp_options:

Hravý motiv lze dočasně zapnout i bez uložení parametrem ?buddyup_playful=1 na front-endu.

Plugin používá Bootstrap 5 + Bootstrap Icons (registrace a připojení v includes/assets.php). Na front-endu se Bootstrap připojí jen pokud je potřeba (shortcody / vlastní URL / speciální stránky).

• Bootstrap CSS/JS: načítá se z CDN (cdn.jsdelivr.net).
• Ikony: Bootstrap Icons z CDN.
• Hravý motiv: extra CSS + „wave“ ve footeru, toggle v nastavení + preview přes query param.

Pokud web nemá přístup na CDN, je potřeba dodat lokální variantu Bootstrapu/ikon.

Menu se registruje v includes/admin-menu.php (zkráceno):

BuddyUP
  - Nástěnka
  - Deníky (CPT)
  - Reflexe (CPT)
  - Mentoři
  - Supervizoři
  - Vyučující semináře
  - Studenti
  - Děti (CPT)
  - Statistiky
  - Export dat
  - Nastavení
  - Zpětná vazba (CPT)
  - O pluginu

Přístup se řídí kombinací capability (např. manage_options) a role/capabilities definovaných v includes/roles.php.

Funkce: buddyup_render_dashboard_page() v includes/admin/dashboard.php.

• Kontrola chybějících reflexí (v rámci školního roku březen–listopad).
• Seznam studentů bez přiřazeného dítěte / bez mentora.
• Poslední deníky a poslední reflexe.
• Časomíra: agregované časy z deníků (přímá práce, příprava, reflexe).

Na front-endu je dostupná přes shortcode [buddyup_dashboard].

Funkce: buddyup_render_risk_signals_page() v includes/admin/risk-signals.php. Slouží k rychlé identifikaci studentů, kteří mohou potřebovat zvýšenou pozornost.

Funkce rizikové signály upozorňují administrátora na potenciální problémy na základě analýzy deníků ve dvou rovinách:
1) detekce konkrétních negativních výrazů v textu deníků
2) sledování vzorců chování (neaktivita, chybějící reflexe, nízké hodnocení, stagnace cílů).

Co z toho vyčteš

• Přehled rizikových signálů (neaktivita, chybějící reflexe, nízké hodnocení, stagnace cílů).
• Skóre rizika (0–100) a trend v čase (poslední 4 měsíce).
• Odkazy na konkrétní deníky s negativními výrazy.
• Rozšířenou analýzu deníků: sentiment, témata, konzistence a nesoulad.

Jak se to hodnotí (zjednodušeně)

• Skóre je vážený součet detekovaných signálů; vyšší skóre = vyšší riziko.
• Trend ukazuje vývoj skóre po měsících (zhoršování/zlepšování).
• Sentiment je heuristika nad textem deníků (pozitivní vs. negativní výrazy).
• Konzistence sleduje krátké nebo „chudé“ záznamy (bez aktivit/časů/cílů).
• Nesoulad upozorňuje, když text popisuje pokrok, ale cíle stagnují.

Nastavení klíčových slov

• Seznam negativních slov lze upravovat přímo v této sekci.
• Klíčová slova ovlivňují detekci negativních zkušeností v denících.

Poznámka: jedná se o heuristiku, ne automatické rozhodování.

Deníky, reflexe a děti jsou vedené jako vlastní CPT a mají standardní WP seznamy a editaci v administraci (menu položky „Deníky“, „Reflexe“, „Děti“).

• Deníky: CPT buddyup_journal (autor = student). Mentor/supervizor může mít přístup dle capabilities.
• Reflexe: CPT buddyup_reflection (měsíc/rok, typ měsíční/trimestrální).
• Děti: CPT buddyup_child (základní údaje + cíle v meta buddyup_goals).

Front-end verze detailu a editace existují i přes rewrite URL (viz „Veřejné URL“), takže není nutné používat pouze admin editaci.

Funkce: buddyup_render_mentors_page() v includes/admin/mentors.php.

• Seznam mentorů a studentů, kteří mají v user meta buddyup_mentor_id daného mentora.
• Odkazy do seznamu studentů s předvyplněným filtrem.

Správa přiřazení student ↔ supervizor přes společnou „pairings“ stránku: buddyup_render_pairings_page() v includes/admin/pairings.php.

• Přiřazuje do meta buddyup_supervisor_user_id.
• Přístup vyžaduje capability buddyup_manage_supervisors.

Stejný mechanismus jako supervizoři (pairings), ukládá do meta buddyup_practice_teacher_id.

Funkce: buddyup_render_students_page() v includes/admin/students.php.

• Filtrovatelný seznam studentů (fulltext + filtr mentora).
• Detail studenta: přiřazené dítě, mentor, přehled deníků a reflexí.
• Tlačítka pro generování PDF (karta/deníky/reflexe) – viz sekce Exporty.

Funkce: buddyup_render_statistics_page() v includes/admin/stats.php.

• Přehled počtů rolí a počtů záznamů (deníky/reflexe/děti).
• Časová osa posledních 12 měsíců (deníky vs reflexe).
• Rozložení aktivit, pokroku cílů a typů reflexí.
• Rozložení hodnocení a top studenti/mentoři.

Grafy načítají Chart.js z CDN. V offline prostředí grafy nemusí fungovat.

Stránka: includes/admin/export.php. Exportní handlery jsou v includes/exports/*.

• CSV: Deníky, Děti, Párování.
• PDF: Deníky, Děti, Párování.
• Metriky: anonymizované souhrny (CSV/XLS/PDF).

Zpětná vazba se ukládá jako CPT buddyup_feedback. V administraci ji najdeš přes menu položku „Zpětná vazba“ (standardní seznam příspěvků CPT).

• Vytváří se přes front-end shortcode [buddyup_feedback].
• Obsahuje kategorii, text a volitelně přílohu (nahranou do WP Media).
• Současně se odesílá e-mail na kontaktní adresu z nastavení (fallback admin_email).

Stránka: includes/admin/about.php.

• Zobrazuje verzi pluginu, WP/PHP, URL webu a aktivní pluginy.
• Vypisuje CHANGELOG.md a generuje kopírovatelný System Report.

Front-end je postavený primárně na shortcodech (stránky ve WP) a doplněný o hezké URL přes rewrite pravidla. Přístup je řízen rolemi (nejčastěji buddyup_student) a WordPress capabilities.

Notifikace v admin baru

• Studentům se (v období březen–listopad) zobrazuje upozornění, pokud chybí měsíční reflexe (viz includes/restrictions.php).

Doporučené stránky ve WordPressu

• Nástěnka: [buddyup_dashboard]
• Moje deníky: [buddyup_student_journals]
• Nový deník: [buddyup_new_journal_form] (nebo legacy [buddyup_add_journal])
• Moje reflexe: [buddyup_my_reflections]
• Nová reflexe: [buddyup_new_reflection_form] (nebo legacy [buddyup_add_reflection])
• Moje dítě: [buddyup_student_child_form]
• Cíle dítěte: [buddyup_child_goals]
• Plánování cílů: [buddyup_goal_planning]
• Můj rok s buddym: [buddyup_child_year_review]
• Zpětná vazba: [buddyup_feedback]

Rewrite pravidla jsou v includes/url-handlers.php:

Pokud URL nefungují, proveď „flush permalinks“ (Nastavení → Permalinky → Uložit).

Shortcody jsou v includes/shortcodes/*. V repozitáři existují i starší soubory (legacy) se stejnými názvy shortcode; v praxi používej preferované varianty níže.

Route /vystupy/ vykresluje výstupní stránku pro studenty (např. exportní odkazy). Pokud je přítomen query parametr buddyup_pdf_export, spouští se obsluha PDF exportu.

Přístup je omezen na přihlášené studenty; jinak se vrací 403.

Exporty běží přes admin_init hooky a reagují na konkrétní POST parametry (tlačítka v admin UI).

• CSV/PDF deníků: includes/exports/journals-csv.php, includes/exports/journals-pdf.php
• CSV/PDF dětí: includes/exports/children-csv.php, includes/exports/children-pdf.php
• CSV/PDF párování: includes/exports/pairing-csv.php, includes/exports/pairing-pdf.php
• PDF karet: includes/exports/pdf-cards.php (mPDF + volitelně GD pro timeline obrázek)

Export metrik je v includes/exports/metrics-csv.php. Je určen pro anonymizované souhrny pro evaluaci (počty, timeline po měsících, rozložení pokroku, délka textu, agregace za studenty).

Vyžaduje manage_options.

Admin stránka Studenti nabízí tlačítka pro generování PDF (karta / deníky / reflexe). Implementace je v includes/exports/student-card-pdf.php.

• 404 na /denik nebo /reflexe: ulož permalinky (flush rewrite pravidel).
• Nejde vytvořit deník/reflexe: zkontroluj roli buddyup_student a přiřazené dítě.
• Grafy ve Statistikách prázdné: Chart.js se načítá z CDN – ověř přístup k internetu.
• Bootstrap bez stylů: ověř, že front-end může načíst CDN (nebo dodej lokální soubory).
• PDF export padá: ověř dostupnost mPDF knihovny v libs/mpdf a dostatek paměti.

Vstupní bod

• buddyup.php – načítá moduly z includes/ a registruje activation hook pro vytvoření základních stránek.

Klíčové moduly

• includes/assets.php – Bootstrap, ikony, „playful“ motiv.
• includes/helpers.php – helpery (URL buildery, výpočty, progress, validace časů, navigace).
• includes/url-handlers.php – rewrite pravidla a front-end routování.
• includes/frontend-handlers.php – zpracování POST z front-end formulářů (PRG redirect).
• includes/rendering.php – HTML rendering detailů, dashboardu, formulářů.
• includes/admin/* – admin stránky.
• includes/shortcodes/* – shortcody.
• includes/exports/* – exportní handlery.

Shrnutí funkcionality pluginu BuddyUP ve formě požadavků, které lze ověřit a doložit.

Funkční požadavky (výběr)

• Uživatel se rolí buddyup_student může vytvářet a upravovat své deníky a reflexe.
• Deníky jsou svázané s konkrétním dítětem a cíli (meta data).
• Admin vidí rizikové signály odvozené z aktivity studenta a obsahu deníků.
• Administrace umožňuje export dat a přehled metrik.
• Systém poskytuje „hezké“ URL pro zobrazení/úpravy záznamů.

Nefunkční požadavky (výběr)

• Bezpečnost: kontrola přístupů přes role/capabilities a nonces.
• Udržitelnost: modularita (admin, shortcody, exporty, renderování).
• Kompatibilita: WordPress, standardní CPT + user meta.

Technický popis architektury, datového modelu a rozhraní pluginu BuddyUP.

Architektura a moduly

• Vstupní bod buddyup.php načítá moduly z includes/.
• Oddělení logiky: admin stránky, front-end handlery, renderování, shortcody, exporty.
• Frontend využívá vlastní URL routování přes rewrite pravidla.

Datové struktury

• CPT: buddyup_journal, buddyup_reflection, buddyup_child, buddyup_feedback.
• User meta pro párování: buddyup_child_id, buddyup_mentor_id, buddyup_supervisor_user_id, buddyup_practice_teacher_id.
• Post meta pro deníky/reflexe/cíle (podrobně v sekci „Datový model“).

Rozhraní a integrace

• Admin menu: BuddyUP (nástěnka, CPT, párování, statistiky, exporty, nastavení).
• Shortcody pro front-end formuláře a přehledy (sekce „Shortcody“).
• Rewrite URL: /denik/{ID}, /reflexe/{ID}, /cil/{child}/{index}, /buddy-cil/{user}/{index}, /vystupy.
• Exporty: CSV/PDF (mPDF), metriky a karty.
• Admin přehled „Rizikové signály“ s heuristikou nad deníky/reflexemi.

Návrhové principy

• PRG pattern u front-end formulářů (Post/Redirect/Get).
• Oprávnění přes role/capabilities, kontrola přístupu ve front-end routách.
• „Virtuální post“ pro lepší integraci s WP šablonami.

Závislosti

• Bootstrap 5 + Bootstrap Icons (CDN), Chart.js (CDN) a mPDF (lokálně v libs/mpdf).

Základní mapa kódu, entry pointů a programátorských rozhraní.

Struktura projektu

• buddyup.php – bootstrap, registrace modulů a activation hook.
• includes/admin/* – admin stránky (dashboard, exporty, nastavení).
• includes/shortcodes/* – front-end shortcody.
• includes/exports/* – exporty CSV/PDF.
• includes/url-handlers.php – rewrite a template_redirect routy.
• includes/frontend-handlers.php – zpracování POST požadavků z front-endu.
• includes/rendering.php – HTML rendering detailů a formulářů.

Klíčové hooky a flow

• init – registrace CPT/rolí, front-end handlery, rewrite pravidla.
• template_redirect – renderování detailů deníků/reflexí/cílů.
• admin_menu – menu BuddyUP v administraci.
• admin_init – uložení párování a nastavení.
• register_activation_hook – vytvoření povinných stránek + flush permalinks.

Ukázka programátorských rozhraní

• Shortcody: [buddyup_dashboard], [buddyup_new_journal_form], [buddyup_new_reflection_form] aj.
• Meta klíče (příklady): buddyup_goals, buddyup_reflection_month, buddyup_time_direct_minutes.
• Helpery: funkce pro práci s cíli, časem, validací a přístupem (v includes/helpers.php).

Doporučený postup ověření funkčnosti pro účely dokladování výsledku.

1. Nainstaluj a aktivuj plugin; ověř vytvoření stránek „Karty“ a flush permalinků.
2. V administraci nastav role a přiřazení (student ↔ dítě, mentor/supervizor/vyučující ↔ student).
3. Ověř front-end shortcody: dashboard, formuláře deníku/reflexe, cíle dítěte.
4. Ověř přístupové scénáře podle rolí (student/mentor/supervizor).
5. Ověř přímé URL: /denik/{ID}, /reflexe/{ID}, /cil/{child}/{index}, /vystupy.
6. Ověř admin panel „Rizikové signály“ na testovacích datech.
7. Ověř exporty CSV/PDF a funkčnost statistik.

Výstupy ověření: screenshoty, ukázkové exporty, logy případných chyb.

Krátký záznam (3–7 min) s průchodem klíčových funkcí: přihlášení, práce studenta, kontrola v administraci, exporty.

Scénář videa (doporučeno)

1. Nástěnka studenta + vytvoření deníku a reflexe.
2. Detail deníku/reflexe přes „hezkou“ URL.
3. Admin dashboard + statistiky.
4. Export CSV/PDF a ukázka výsledku.

Dokumentace

• Veřejná dokumentace: https://buddyup.osu.cz/dokumentace/

Dostupnost software

• Download: https://buddyup.osu.cz/dokumentace/buddyup.zip

Licenční podmínky

• Licence: Toto dílo je publikováno pod licencí Creative Commons BY-NC-SA 4.0 (Uveďte původ - Neužívejte komerčně - Zachovejte Licenci)

Verze a změny

• Changelog: CHANGELOG.md (zobrazeno i v admin „O pluginu“).