Leistungsbeschreibung

Projekt: SharePin – Fragebogenplattform · Version 1.0 (TZ: Europe/Berlin)
Fragebögen (Übersicht) Klonen Gate (classic) Gate Reports v2 OPcache Logbuch

1. Intention & Zielbild

Ziel: Schlanke, schema-getriebene Erhebung von Antworten (Renderer), sichere Speicherung (DB), auswertende Berichte (Viewer/Reports) und Exporte (CSV) mit klarer Rechte-Steuerung (Gate/HMAC).

  • A-Serie Psychologie-/Likert-Fokus, z. B. A12.
  • KVI-Serie Kennzahlen-Fokus inkl. Zeitverlauf & Single-Choice, z. B. KVI10/KVI11.

Arbeitsmodus: konservativ, minimalinvasiv, upload-fertige Dateien (UTF-8 ohne BOM), keine riskanten Änderungen ohne explizites OK.

2. Leistungsbausteine

2.1 Erheben (Renderer)

  • Schema-gesteuertes Rendern (JSON questionnaires.schema_json).
  • Validieren & Absenden (POST → /api/post_result.php).
  • Signatur-/Gate-Checks (Render/Post).

2.2 Anzeigen (Reports/Viewer)

  • Item-Benchmarks (P10/P50/P90) & Interpretationen.
  • Timeseries (day/week/month) + Moving-Average (7/14/30).
  • Gesamt-Scores (Scale-Ø, SC-Quote) & Positionierung.

2.3 Export (CSV)

  • Ergebnis-CSV pro PID/Slug (/admin/report_timeseries_csv_v3.php).
  • Scoring-CSV (KVI SC) & Overview-CSV (optional).

2.4 Sicherheit

  • Gate v2 (app_settings.k='permissions', by_slug-Knoten).
  • Viewer-Scope, Report-Level, Signaturpflicht (HMAC-Links).

3. Nutzer- vs. Admin-Perspektive

RolleZweckWichtige Seiten
Nutzer Fragebogen ausfüllen, Ergebnis ansehen. Renderer-Guard: /admin/q_render_enforced_guard.php?slug=<SLUG>&pid=<PID>
Viewer-Guard: /result_view_pretty_guard.php?id=<RESULT_ID>&pid=<PID>
Admin Schema pflegen, Klonen, Rechte setzen, Berichte prüfen. Übersicht: /admin/q_list.php · Klonen: /admin/q_clone.php
Gate v2: /admin/gate_simple_reports_v2.php?slug=<SLUG>
Timeseries: /admin/report_timeseries.php?slug=<SLUG>&pid=<PID>

4. Prozesse

4.1 Klonen & Versionieren

  1. Quelle prüfen (Preview/Schema), Ziel-Slug festlegen (z. B. KVI11).
  2. Klonen: /admin/q_clone.php (Benchmarks/Permissions meist aus).
  3. Gate v2 setzen: by_slug.<SLUG>.report_access/report.
  4. Smoke-Links nutzen (Renderer, Reports, Timeseries, CSV).
Hinweis: KVI10 ist eingefroren (Archiv), aktive Arbeit über KVI11.

4.2 Benchmarks & Scale-Map

  • Katalog: benchmarks_catalog (Slug, Label, aktiv).
  • Items: benchmarks_item (percentile_json, bounds_json).
  • Interpretation: benchmarks_interpretation_map (Ranges, Label, Text).
  • Skalen: scale_map (scale_overall, method=sum/avg/custom, weights optional).

4.3 Rechte (Gate v2)

Report-Level
by_slug.SLUG.report_access.levels = ["basic","interp","bench"]
Report-Zugriff
by_slug.SLUG.report.allowed_pids / allowed_groups
Viewer
by_slug.SLUG.viewer.scope/signature_required
Classic Gate
Nur wo Legacy-Seiten es noch erfordern (Übergangsphase).

5. API-Endpunkte

PfadZweckHinweis
/api/get_questionnaire.phpSchema lesenslug-basiert
/api/post_result.phpErgebnis schreibenRenderer-Flow
/api/get_results.phpListe ErgebnissePaginierung
/api/get_result.phpEin Ergebnisjüngere Datei

6. Smoke-Tests (Beispiele)

  • Renderer (Guard): /admin/q_render_enforced_guard.php?slug=A12&pid=9003
  • Item-Bench A12: /admin/report_a12_itembench_demo.php?id=990012
  • KVI Scoring: /admin/reports/kvi/report_kvi_scoring.php?id=995006
  • Timeseries (day): /admin/report_timeseries.php?slug=KVI11&bucket=day&pid=9103
  • CSV: /admin/report_timeseries_csv_v3.php?slug=KVI11&bucket=day&pid=9103
OPcache danach ggf. aktualisieren: /admin/zz_opcache_invalidate.php?touch=1

7. Migration & Daten

Collation: utf8mb4_0900_ai_ci (Session ggf. per SET collation_connection angleichen).

Seeds (Beispiele, idempotent):

  • A12 Benchmarks: /db/seeds/benchmarks_A12_default_de_2025.sql
  • A12 Scale-Map: /db/seeds/scale_map_A12.sql
  • KVI11 Demo-Ergebnisse: /db/seeds/demo_results_KVI11.sql

8. Qualität & Checklisten

8.1 Vor Upload

  • Datei-Encoding: UTF-8 (ohne BOM).
  • Kein Framework, minimale Seiteneffekte.
  • Pfadnamen eindeutig (z. B. /admin/reports/kvi/report_kvi_total_v1.php).

8.2 Nach Upload

  • OPcache: aktualisieren.
  • Smoke-Links prüfen (Renderer/Reports/CSV).
  • Gate v2: Slug-Knoten & Rechte kontrollieren.

8.3 Sicherheit

  • Least Privilege (default deny).
  • Signaturen nur wo nötig, Viewer-Scope „own“ by default.

9. Glossar (Kurz)

slug
Fragebogenkennung (z. B. A12, KVI10…)
pid
Teilnehmer-ID (participants.id)
id
Ergebnis-ID (results.id)
Gate
Rechtematrix (render/post/report/viewer)
Level
Report-Tiefe: basic, interp, bench
Scale-Map
Aggregation (sum/avg/custom) pro Skala

10. Serien-Spezifika

A-Serie (Likert)

  • Likert 1–5, Fokus Interpretationen.
  • Benchmarks pro Item & Scale-Overall.

KVI-Serie (Kennzahlen)

  • Single-Choice + Zeitreihen zentriert.
  • Overview/Timeseries/SC-Score/Scale-Ø.