461 lines
15 KiB
Markdown
461 lines
15 KiB
Markdown
# o‑Byte QA – Testprotokoll‑Tool (Full README)
|
||
|
||
**Stand:** 2025-09-04
|
||
**Stack:** PHP 8.3 ( Apache ), JS (Vanilla), MariaDB, Docker & Compose, Portainer
|
||
|
||
Dieses Repository enthält ein vollwertiges QA‑Tool mit Login (OIDC), GitLab‑Template‑Loader, DocBee‑Posting, PDF‑Erzeugung im Browser und persistenter Speicherung (DB + PDF‑Ablage). Diese README basiert ausschließlich auf dem mitgelieferten Projektstand.
|
||
|
||
---
|
||
|
||
## Inhaltsverzeichnis
|
||
|
||
1. [Überblick](#überblick)
|
||
2. [Architektur & Verzeichnisstruktur](#architektur--verzeichnisstruktur)
|
||
3. [Funktionen](#funktionen)
|
||
4. [UI‑Bedienung (Kurzüberblick)](#ui-bedienung-kurzüberblick)
|
||
5. [Datenmodell (DB)](#datenmodell-db)
|
||
6. [API‑Endpunkte](#api-endpunkte)
|
||
7. [Konfiguration per Umgebungsvariablen (.env)](#konfiguration-per-umgebungsvariablen-env)
|
||
8. [Lokale Entwicklung](#lokale-entwicklung)
|
||
9. [Deployment mit Docker Compose](#deployment-mit-docker-compose)
|
||
10. [Deployment mit Portainer (Stack)](#deployment-mit-portainer-stack)
|
||
11. [GitLab‑Vorlagen](#gitlab-vorlagen)
|
||
12. [DocBee‑Integration](#docbee-integration)
|
||
13. [PDF‑Export](#pdf-export)
|
||
14. [Troubleshooting](#troubleshooting)
|
||
15. [Sicherheitshinweise](#sicherheitshinweise)
|
||
16. [Lizenz / Nutzung](#lizenz--nutzung)
|
||
|
||
---
|
||
|
||
## Überblick
|
||
|
||
- **Ziel:** Manuelle QA‑Testläufe effizient vorbereiten, durchführen und revisionssicher exportieren.
|
||
- **Workflow:** Vorlage laden → Metadaten eintragen (inkl. **OLM‑Nummer**) → Schritte bearbeiten (Gruppen, Status, Evidenzen) → **Exportieren (DocBee, DB, PDF)**.
|
||
- **Login:** OpenID Connect (konfigurierbar), optional **bypassbar** über `AUTH_DISABLED=true` für lokale Tests.
|
||
- **Persistenz:** Reports (Metadaten & Steps) in MariaDB, PDFs serverseitig abgelegt.
|
||
- **Integrationen:** GitLab (YAML‑Vorlagen), DocBee (Login + Notiz‑Erzeugung via REST).
|
||
|
||
---
|
||
|
||
## Architektur & Verzeichnisstruktur
|
||
|
||
```
|
||
o-byte-qa-tool/
|
||
├─ compose/
|
||
│ ├─ Dockerfile # PHP 8.3 + Apache, Composer
|
||
│ └─ docker-compose.yml # app, mariadb, schema-loader, phpmyadmin, fix-pdf-perms
|
||
└─ htdocs/ # Webroot
|
||
├─ index.php # App-Entry, Token-Bootstrap für DocBee, UI
|
||
├─ app.js # UI-Logik, Exporte, DocBee-Push, GitLab-Loader
|
||
├─ style.css # Styles
|
||
├─ api/
|
||
│ ├─ export.php # Report+Steps in DB speichern, PDF entgegennehmen
|
||
│ ├─ echo.php # einfache Echo-Route (Debug)
|
||
│ └─ health.php # Health‑Check (DB/PDF‑Pfad)
|
||
├─ config/config.php # ENV‑Konfiguration (OIDC, DocBee, DB, APP_BASE_URL, …)
|
||
├─ login.php # OIDC‑Start
|
||
├─ callback.php # OIDC‑Callback, Session‑Bootstrap
|
||
├─ logout.php # Session reset (OLM beibehalten)
|
||
├─ logo.png / logo_light.png
|
||
├─ favicon.ico
|
||
├─ vendor/ # Composer (z. B. jumbojett/openid-connect-php, phpseclib, …)
|
||
└─ oidc/ # phpseclib Assets (lokal eingebunden)
|
||
```
|
||
|
||
---
|
||
|
||
## Funktionen
|
||
|
||
### Vorlagen & Schritte
|
||
- **Vorlagen laden**: YAML/JSON (lokal per Datei **oder** aus **GitLab**‑Repo/Pfad/Ref).
|
||
- **Gruppen**: Gruppenzeilen, ein-/ausklappbar; Schritte via Drag‑Handle verschiebbar (innerhalb und zwischen Gruppen).
|
||
- **Automatische Neu‑Nummerierung** der Steps bei Änderungen/Verschieben.
|
||
- **Pflichtschritte** (📌) werden geprüft – Export blockiert, wenn offen.
|
||
- **Gruppenstatus setzen** auf *pass/fail/skip/blocked*, inkl. **Warnung** bei Überschreiben bestehender Stati.
|
||
- **Kommentare & Evidenzen** (Freitext + URL).
|
||
|
||
### Metadaten
|
||
- **Module**, **Modul‑Version**, **PBX‑Version**, **Tester** (aus Session), **DocBee‑Ticket‑URL**, **OLM‑Nummer** (`olm_nummer`).
|
||
|
||
### Exporte
|
||
- **Exportieren (DocBee, DB, PDF)** per **einem** Button:
|
||
1. DocBee‑Notiz erstellen (falls Token vorhanden) → Ticket‑URL ggf. aktualisiert.
|
||
2. **PDF** im Browser generieren (jsPDF+AutoTable).
|
||
3. **/api/export.php**: JSON (Run) + PDF (multipart) an Server → DB‑Speicherung + PDF‑Ablage.
|
||
4. Server sendet `report_id` und `pdf_path` zurück.
|
||
- **Lauf speichern / laden** als JSON (Zwischenspeichern/Weiterarbeiten).
|
||
- **Template als YAML exportieren** (inkl. `olm_nummer`, Gruppen & Steps).
|
||
|
||
> Hinweis: Dedizierte Buttons für CSV/MD/PDF wurden in dieser Version **konsolidiert** – CSV/MD‑Funktionen existieren noch im Code, UI‑seitig aber nicht exponiert.
|
||
|
||
---
|
||
|
||
## UI‑Bedienung (Kurzüberblick)
|
||
|
||
- **GitLab Vorlage**: Dropdown befüllen (`GitLab: …` Tag zeigt Status), Datei wählen → Vorlage wird geladen.
|
||
- **Metadaten**: Felder ausfüllen (**OLM‑Nummer** nicht vergessen).
|
||
- **Steps**: `+ Step` / `+ Gruppe`, per Griff `⋮⋮` ziehen, Status setzen, Kommentare/Evidenzen pflegen.
|
||
- **Exportieren (DocBee, DB, PDF)**: Startet kompletten Lauf‑Export. Ergebnisdialog zeigt Ticket/PDF‑Pfad/Report‑ID.
|
||
|
||
---
|
||
|
||
## Datenmodell (DB)
|
||
|
||
Beim Export werden folgende Tabellen (idempotent) angelegt/aktualisiert:
|
||
|
||
**reports**
|
||
- `id` BIGINT (PK)
|
||
- `created_at` TIMESTAMP (Default `CURRENT_TIMESTAMP`)
|
||
- `module` VARCHAR(255)
|
||
- `module_version` VARCHAR(100)
|
||
- `pbx_version` VARCHAR(100)
|
||
- `olm_nummer` VARCHAR(100)
|
||
- `tester` VARCHAR(255)
|
||
- `docbee_url` TEXT
|
||
- `summary` VARCHAR(255) → z. B. `12/15 pass, 2 fail, 1 skip`
|
||
- `pdf_path` TEXT
|
||
|
||
**steps**
|
||
- `id` BIGINT (PK)
|
||
- `report_id` BIGINT (FK → reports.id, ON DELETE CASCADE)
|
||
- `step_index` INT
|
||
- `step_id` VARCHAR(50)
|
||
- `title` TEXT
|
||
- `expected` TEXT
|
||
- `status` ENUM('pass','fail','skip','na','')
|
||
- `comment` TEXT
|
||
- `evidence` TEXT
|
||
- `group_title` VARCHAR(255)
|
||
- `group_index` INT
|
||
|
||
Der **schema‑loader** Service in `docker-compose.yml` erstellt die Tabellen automatisch beim ersten Start.
|
||
|
||
---
|
||
|
||
## API‑Endpunkte
|
||
|
||
- `GET /api/health.php`
|
||
- Prüft PDO / MariaDB‑Erreichbarkeit, Schreibrechte des PDF‑Ordners.
|
||
- `POST /api/export.php` (multipart/form-data)
|
||
- **Felder:**
|
||
- `run` – JSON mit Metadaten (`module`, `module_version`, `pbx_version`, `olm_nummer`, `tester`, `docbee_url`, `ts`, `steps`[…])
|
||
- `pdf` – erzeugte PDF‑Datei (optional; Export läuft auch ohne PDF durch)
|
||
- **Antwort:** `{{"ok":true,"report_id":<int>,"pdf_path":"…","summary":"…"}}`
|
||
- `POST /api/echo.php`
|
||
- Debug/Echo.
|
||
|
||
---
|
||
|
||
## Konfiguration per Umgebungsvariablen (.env)
|
||
|
||
Beispiel **.env** (für Compose/Portainer):
|
||
|
||
```env
|
||
# App
|
||
APP_PORT=8009
|
||
APP_BASE_URL=http://localhost:8009
|
||
AUTH_DISABLED=false # true = Login-BYPASS (nur lokal verwenden)
|
||
|
||
# OpenID Connect (Login)
|
||
OIDC_PROVIDER=https://auth.o-byte.com/realms/o-byte.com
|
||
OIDC_CLIENT=qa-tool
|
||
OIDC_SECRET=<client-secret>
|
||
|
||
# MariaDB
|
||
DB_HOST=mariadb
|
||
DB_PORT=3306
|
||
DB_NAME=qa_tool
|
||
DB_USER=qa
|
||
DB_PASS=change_me
|
||
DB_ROOT_PASS=change_me_root
|
||
|
||
# Persistenz
|
||
PDF_STORAGE_DIR=/var/reports
|
||
|
||
# DocBee
|
||
DOCBEE_BASEURL=https://obyte.docbee.com
|
||
DOCBEE_USER=OBYTE/service
|
||
DOCBEE_PASS=<password>
|
||
DOCBEE_TIME=1440 # Minuten Token-Gültigkeit
|
||
|
||
# GitLab Templates
|
||
GITLAB_HOST=https://git.steinert.cc
|
||
GITLAB_PROJECT_ID=qa/templates # oder numerische ID
|
||
GITLAB_REF=main
|
||
GITLAB_PATH=templates
|
||
GITLAB_TOKEN= # optional (PRIVATE-TOKEN)
|
||
|
||
# Container-User (Dateirechte)
|
||
APP_UID=0
|
||
APP_GID=0
|
||
|
||
# phpMyAdmin Port (optional)
|
||
PHPMYADMIN_PORT=8010
|
||
```
|
||
|
||
> **Wichtig:** Keine Secrets in Repos commiten. Für Produktion Token/Passwörter über Portainer‑UI/Secrets setzen.
|
||
|
||
---
|
||
|
||
## Lokale Entwicklung
|
||
|
||
1. **Composer‑Abhängigkeiten** sind bereits im Repo (`vendor/`). Falls nötig:
|
||
```bash
|
||
cd htdocs && composer install
|
||
```
|
||
2. **PHP‑Built‑in** (nur für schnellen Test, ohne DB/PDF‑Ablage):
|
||
```bash
|
||
php -S 127.0.0.1:8009 -t htdocs
|
||
```
|
||
3. **Login‑Bypass** lokal aktivieren:
|
||
```bash
|
||
export AUTH_DISABLED=true
|
||
```
|
||
4. Browser: `http://127.0.0.1:8009`
|
||
|
||
---
|
||
|
||
## Deployment mit Docker Compose
|
||
|
||
Im Ordner `compose/` befindet sich ein funktionsfähiges Setup mit:
|
||
- **app** (Apache+PHP 8.3), bind‑mountet `htdocs` und nutzt `PDF_STORAGE_DIR` Volume
|
||
- **mariadb** (11.x)
|
||
- **schema-loader** (initialisiert Tabellen)
|
||
- **phpmyadmin** (optional)
|
||
- **fix-pdf-perms** (setzt 0777 auf PDF‑Volume)
|
||
|
||
**Starten:**
|
||
```bash
|
||
cd compose
|
||
cp ../.env .env # eigene Werte setzen
|
||
docker compose up -d
|
||
```
|
||
|
||
**Zugriff:** `http://<host>:${APP_PORT:-8009}`
|
||
**phpMyAdmin:** `http://<host>:${PHPMYADMIN_PORT:-8010}`
|
||
|
||
---
|
||
|
||
## Deployment mit Portainer (Stack)
|
||
|
||
1. **Stack → Add Stack**
|
||
2. **Environment Vars** nach obiger `.env` setzen (oder Datei hochladen).
|
||
3. **Compose** verwenden (aus `compose/docker-compose.yml`), z. B.:
|
||
|
||
```yaml
|
||
version: "3.8"
|
||
services:
|
||
app:
|
||
image: thecodingmachine/php:8.3-v4-apache
|
||
user: "${APP_UID:-0}:${APP_GID:-0}"
|
||
ports:
|
||
- "${APP_PORT:-8009}:80"
|
||
environment:
|
||
PHP_EXTENSION_PDO_MYSQL: "1"
|
||
APP_BASE_URL: ${APP_BASE_URL}
|
||
AUTH_DISABLED: ${AUTH_DISABLED}
|
||
DB_HOST: ${DB_HOST}
|
||
DB_PORT: ${DB_PORT}
|
||
DB_NAME: ${DB_NAME}
|
||
DB_USER: ${DB_USER}
|
||
DB_PASS: ${DB_PASS}
|
||
PDF_STORAGE_DIR: ${PDF_STORAGE_DIR}
|
||
OIDC_PROVIDER: ${OIDC_PROVIDER}
|
||
OIDC_CLIENT: ${OIDC_CLIENT}
|
||
OIDC_SECRET: ${OIDC_SECRET}
|
||
DOCBEE_BASEURL: ${DOCBEE_BASEURL}
|
||
DOCBEE_USER: ${DOCBEE_USER}
|
||
DOCBEE_PASS: ${DOCBEE_PASS}
|
||
DOCBEE_TIME: ${DOCBEE_TIME}
|
||
GITLAB_HOST: ${GITLAB_HOST}
|
||
GITLAB_PROJECT_ID: ${GITLAB_PROJECT_ID}
|
||
GITLAB_REF: ${GITLAB_REF}
|
||
GITLAB_PATH: ${GITLAB_PATH}
|
||
GITLAB_TOKEN: ${GITLAB_TOKEN}
|
||
volumes:
|
||
- ${APP_HTDOCS_HOST:-/opt/qa-tool/htdocs}:/var/www/html
|
||
- pdf_storage:/var/reports
|
||
depends_on:
|
||
mariadb:
|
||
condition: service_healthy
|
||
fix-pdf-perms:
|
||
condition: service_completed_successfully
|
||
restart: unless-stopped
|
||
|
||
mariadb:
|
||
image: mariadb:11
|
||
environment:
|
||
MYSQL_DATABASE: ${DB_NAME}
|
||
MYSQL_USER: ${DB_USER}
|
||
MYSQL_PASSWORD: ${DB_PASS}
|
||
MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASS}
|
||
volumes:
|
||
- db_data:/var/lib/mysql
|
||
healthcheck:
|
||
test: ["CMD", "mariadb-admin", "ping", "-h", "127.0.0.1", "-p${DB_PASS}"]
|
||
interval: 10s
|
||
timeout: 5s
|
||
retries: 30
|
||
start_period: 20s
|
||
restart: unless-stopped
|
||
|
||
schema-loader:
|
||
image: mariadb:11
|
||
depends_on:
|
||
mariadb:
|
||
condition: service_healthy
|
||
environment:
|
||
DB_HOST: ${DB_HOST}
|
||
DB_PORT: ${DB_PORT}
|
||
DB_NAME: ${DB_NAME}
|
||
DB_USER: ${DB_USER}
|
||
DB_PASS: ${DB_PASS}
|
||
command: >
|
||
sh -lc "
|
||
echo 'Waiting for DB…'; sleep 3;
|
||
mysql -h $DB_HOST -P $DB_PORT -u$DB_USER -p$DB_PASS $DB_NAME <<SQL
|
||
CREATE TABLE IF NOT EXISTS reports (
|
||
id BIGINT AUTO_INCREMENT PRIMARY KEY,
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
module VARCHAR(255),
|
||
module_version VARCHAR(100),
|
||
pbx_version VARCHAR(100),
|
||
olm_nummer VARCHAR(100),
|
||
tester VARCHAR(255),
|
||
docbee_url TEXT,
|
||
summary VARCHAR(255),
|
||
pdf_path TEXT
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|
||
CREATE TABLE IF NOT EXISTS steps (
|
||
id BIGINT AUTO_INCREMENT PRIMARY KEY,
|
||
report_id BIGINT NOT NULL,
|
||
step_index INT,
|
||
step_id VARCHAR(50),
|
||
title TEXT,
|
||
expected TEXT,
|
||
status ENUM('pass','fail','skip','na','') DEFAULT '',
|
||
comment TEXT,
|
||
evidence TEXT,
|
||
group_title VARCHAR(255),
|
||
group_index INT,
|
||
CONSTRAINT fk_steps_report FOREIGN KEY (report_id) REFERENCES reports(id) ON DELETE CASCADE
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|
||
SQL
|
||
"
|
||
restart: "no"
|
||
|
||
fix-pdf-perms:
|
||
image: busybox:1.36
|
||
volumes:
|
||
- pdf_storage:/target
|
||
command: |
|
||
sh -lc '
|
||
set +e
|
||
mkdir -p /target
|
||
chmod -R 0777 /target 2>/dev/null || true
|
||
chown -R 0:0 /target 2>/dev/null || true
|
||
exit 0
|
||
'
|
||
restart: "no"
|
||
|
||
phpmyadmin:
|
||
image: phpmyadmin:5
|
||
ports:
|
||
- "${PHPMYADMIN_PORT:-8010}:80"
|
||
environment:
|
||
PMA_HOST: mariadb
|
||
PMA_USER: ${DB_USER}
|
||
PMA_PASSWORD: ${DB_PASS}
|
||
depends_on:
|
||
mariadb:
|
||
condition: service_healthy
|
||
restart: unless-stopped
|
||
|
||
volumes:
|
||
db_data:
|
||
pdf_storage:
|
||
```
|
||
|
||
4. **Deploy Stack** → öffnen: `http://<host>:${APP_PORT}`.
|
||
|
||
---
|
||
|
||
## GitLab‑Vorlagen
|
||
|
||
- Konfiguration via ENV (`GITLAB_HOST`, `GITLAB_PROJECT_ID`, `GITLAB_REF`, `GITLAB_PATH`, `GITLAB_TOKEN`).
|
||
- UI lädt per GitLab API die Liste der YAML‑Dateien aus `GITLAB_PATH` (nur `.yaml`/`.yml`).
|
||
- Parser akzeptiert **YAML** und **JSON** (Fallback).
|
||
|
||
---
|
||
|
||
## DocBee‑Integration
|
||
|
||
- Beim Laden von `index.php` wird via `DOCBEE_BASEURL/restApi/login` ein Token geholt und **clientseitig** als `window.DOCBEE_TOKEN` bereitgestellt.
|
||
- Exportablauf:
|
||
1. **postToDocBee** erstellt eine Notiz im angegebenen **Ticket** (aus `DocBee Ticket‑URL`).
|
||
2. Bei Erfolg wird die URL im Lauf aktualisiert.
|
||
3. Danach erfolgt Server‑Export (DB + optional PDF).
|
||
|
||
**Erforderliche ENV:** `DOCBEE_BASEURL`, `DOCBEE_USER`, `DOCBEE_PASS`, `DOCBEE_TIME` (Minuten).
|
||
|
||
---
|
||
|
||
## PDF‑Export
|
||
|
||
- Erzeugung **im Browser** via **jsPDF** + **AutoTable** (CDN‑Fallbacks vorhanden).
|
||
- **Logo** `logo_light.png` wird proportional (max 26×12 mm) **rechtsbündig** im Kopf platziert.
|
||
- Fallback: Falls Libraries fehlen, wird ein Text‑PDF erzeugt.
|
||
- Server speichert PDFs in `PDF_STORAGE_DIR` (Default `/var/reports`).
|
||
|
||
---
|
||
|
||
## YAML‑Vorlage (Beispiel inkl. OLM)
|
||
|
||
```yaml
|
||
name: "Modul XYZ – Basis‑Tests"
|
||
module: "Modul XYZ"
|
||
module_version: "1.2.3"
|
||
pbx_version: "8.1"
|
||
olm_nummer: "OLM-12345"
|
||
steps:
|
||
- type: "group"
|
||
title: "Telefonie Basis"
|
||
- type: "step"
|
||
id: "s1"
|
||
title: "Anruf initiieren"
|
||
expected: "Ruf wird erfolgreich aufgebaut"
|
||
required: true
|
||
- type: "step"
|
||
id: "s2"
|
||
title: "Rufumleitung"
|
||
expected: "Ruf wird korrekt umgeleitet"
|
||
required: false
|
||
```
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
- **Login‑Loop / 401:** OIDC‑Konfiguration prüfen (`OIDC_PROVIDER`, Redirect‑URL `/callback.php`). Lokal ggf. `AUTH_DISABLED=true`.
|
||
- **DocBee 401/403:** `DOCBEE_USER/DOCBEE_PASS/DOCBEE_BASEURL/DOCBEE_TIME` prüfen.
|
||
- **DB‑Fehler (PDO not loaded):** Image/Extension prüfen (`PHP_EXTENSION_PDO_MYSQL=1` gesetzt? Compose).
|
||
- **Keine Schreibrechte PDF:** Volume/`fix-pdf-perms` prüfen; `PDF_STORAGE_DIR` existiert/schreibbar? `/api/health.php` ansehen.
|
||
- **GitLab‑Liste leer:** Pfad/Ref/Token prüfen; nur `.yaml/.yml` werden angezeigt.
|
||
- **Export blockiert:** Pflichtschritte haben keinen Status (📌).
|
||
|
||
---
|
||
|
||
## Sicherheitshinweise
|
||
|
||
- **AUTH_DISABLED** ausschließlich in Dev/Stage verwenden.
|
||
- DocBee‑Token wird **clientseitig** verwendet – nur in internen Netzen nutzen oder alternative Server‑Proxy‑Variante vorsehen.
|
||
- Secrets per Portainer‑Secrets/ENV setzen, nicht im Repo.
|
||
- DB‑Backups/Retention für `reports`/`steps` einplanen; PDF‑Ablage regelmäßig bereinigen/archivieren.
|
||
|
||
---
|
||
|
||
## Lizenz / Nutzung
|
||
|
||
Interne Nutzung innerhalb o‑Byte / Kundenprojekten. Anpassungen willkommen.
|