115 lines
7.8 KiB
Markdown
115 lines
7.8 KiB
Markdown
---
|
||
name: web-feature-iteration
|
||
description: "Web-Features bauen, Revert bei Ablehnung."
|
||
version: 1.0.0
|
||
author: Agent A (Deployer)
|
||
platforms: [linux]
|
||
---
|
||
|
||
# Web-Feature-Iteration (inkrementell für diesen Nutzer)
|
||
|
||
Governs how to extend or feature-up an existing interactive web page/app for this
|
||
user. Learnt the hard way 2026-08-04 on TicTacToe (3D-Relaunch 3× rejected, full revert).
|
||
|
||
## Trigger
|
||
|
||
- "Neue Funktion einbauen" / "Erweiterung" / "Mach mal 3D / Animation / X dazu"
|
||
- Erweitern einer **laufenden, bereits spielbaren/nutzbaren** Seite
|
||
|
||
---
|
||
|
||
## Kerngesetz: lieber klein + funktionierend als schick + kaputt
|
||
|
||
Aus der TicTacToe-Session (Nutzer lehnte 3-Mal ab):
|
||
1. **Minimaler Eingriff zuerst.** Wenn eine Seite funktioniert (z. B. spielbares
|
||
TicTacToe mit Minimax), baue eine kleine, isolierte Erweiterung — nicht einen
|
||
glänzenden Redesign (3D-Canvas, neue Engine). Der Nutzer bevorzugt funktionierend vor flashy.
|
||
2. **Kritik ist wertvoll — Match auf Nutzer-Mehrwert.** Gegen einen perfekten
|
||
Minimax-Gegner ist "Wer beginnt (X/O)" (≈5 Zeilen, 0 Risiko) mehr wert als
|
||
Schwierigkeitsstufen, die die perfekte Engine anfassen. Frag: "Was ist die kleinste
|
||
Änderung mit dem größten echten Nutzen?"
|
||
3. **Sauberer Revert erwartet.** Wenn der Nutzer "Komplett zurück" / "Geht gar nicht"
|
||
sagt: sofort den letzten bekannten funktionierenden Stand wiederherstellen (Backup
|
||
`index-original.html.bak`), tote Assets (geladene lib/) entfernen, über HTTPS verifizieren.
|
||
Erwartung: Was nichts bringt, wird zurückgenommen, nicht "repariert bis es gefällt".
|
||
|
||
## Effektiver 3D/Visual-Anstupser (aus TicTacToe)
|
||
|
||
- Hat der Nutzer 3D/Visual-Wunsch, aber die **Interaktion bleibt die Wahrheit**:
|
||
Wenn ein 3D-Canvas das präzise Klicken unmöglich macht (perspektivisches Klick-Mapping),
|
||
lehnt der Nutzer ab. Behalte die **präzise 2D-/Affordance-Schicht** (echte anklickbare
|
||
Zellen statt Canvas-Koordinaten) und rendere die Deko (3D-Steine) DARUNTER/separat.
|
||
- Pauschale "Glanz"-Erweiterungen (permanente Board-Rotation) machen Spiele unspielbar — vermeiden.
|
||
|
||
## Reusable Technik-Pitfalls (Three.js)
|
||
|
||
- **`BoxGeometry` hat KEINE `.rotation`-Eigenschaft** (nur `Object3D`: Mesh/Group).
|
||
`geometry.rotation.z = x` → `TypeError: Cannot set properties of undefined (setting 'z')`.
|
||
Fix: `geometry.rotateZ(angle)` (BufferGeometry-Methode) oder die Geometrie in ein Mesh
|
||
packen und das Mesh rotation zulassen.
|
||
- **Diagnose:** isoliert im Browser `new THREE.X()` testen; den größten Fehler in kleine
|
||
Schritte zerlegen (Material vs. Geometrie vs. Group) statt die ganze Funktion zu raten.
|
||
|
||
### ⚠️ Chart.js/CDN-Abhängigkeit vermeiden — statisches CSS statt JS-Diagramm
|
||
|
||
Chart.js von CDN (cdn.jsdelivr.net) lädt auf mobilen Browsern oft nicht oder
|
||
verzögert. Die `canvas` bleibt dann leer — die Seite sieht aus wie ein
|
||
dunkles Nichts. Sub-Agenten können nicht prüfen ob das Chart lädt (kein
|
||
Browser-Zugriff).
|
||
|
||
**Fix: Chart.js durch statische CSS-Balken ersetzen.**
|
||
```css
|
||
.chart-bar { background: linear-gradient(to top, #4ade80, rgba(74,222,128,0.2)); height: 100%; }
|
||
```
|
||
- Kein JS, kein CDN, kein Fallback nötig → immer sichtbar
|
||
- Keine mobilen Lade-Probleme
|
||
- Null zusätzliche Ladezeit
|
||
- Sub-Agenten können den Code im Review sehen
|
||
|
||
**Entscheidungsregel:** Wenn ein Diagramm nur Daten-Status zeigt (keine
|
||
Interaktion nötig), ist CSS die bessere Wahl. Nur wenn der Nutzer aktiv
|
||
zoomen/filtern/hovern muss, lohnt sich Chart.js/Canvas.
|
||
|
||
## Verifikation (immer)
|
||
|
||
1. Erst SELBST im echten Browser testen (Seite laden, 1 Spielzug, KI-Antwort, `js_errors` leer),
|
||
nicht nur `curl` Status 200 behaupten.
|
||
2. **Kontrast-Check auf der Live-URL:** `curl` allein erkennt keine CSS-Fehler.
|
||
Prüfe: Sind alle Texte auf hellen Hintergründen lesbar? `--muted` auf `--surface` kann
|
||
wie schwarz auf schwarz wirken (WCAG-AA 4.5:1 erforderlich). Wenn Browser nicht verfügbar:
|
||
Hex-Farben gegeneinander halten oder Sub-Agenten den Code visuell prüfen lassen.
|
||
3. **Nach Deploy: Team-Review über die LIVE-Seite per Sub-Agent, nicht nur den Code.**
|
||
Nutzer-Vorgabe (hart): "Ihr müsst euch wieder gegengecheckt haben." Nach bestandenem
|
||
technischen Check (HTTP 200 + nginx-t) einen Review-Task mit **eingebettetem Seiteninhalt**
|
||
(HTML + CSS) an einen Sub-Agenten schicken. Sub-Agenten können keine externen URLs laden.
|
||
4. **Nach Revert:** gleicher Browser-Test, damit die wiederhergestellte Seite wirklich läuft.
|
||
|
||
## Team-Gegenprüfung ist PFLICHT — nie solo bauen (Nutzer-Grundsatz, 2026-08-09)
|
||
|
||
Der Nutzer verlangt es hart (für Alle Ebenen der Arbeit, nicht nur Code): **"Ihr müsst euch wieder gegengecheckt haben; manche Dinge findet man nur im Team."** Mehrfach baute ich ein Backend/Daten-Gerüst allein → der Nutzer fand jedes Mal echte Fehler, die ein Review gefunden hätte. Lektionen:
|
||
|
||
- **Daten UND Backend review-en lassen, nicht nur Roh-Daten vom Team holen.** Reine "Schätzwerte einholen" ist kein Gegenchenken. Code, Logik, URL-Formate und Generierung gehören dem Team zum Review vorgelegt.
|
||
- Sub-Agenten-Review ist wertvoll, aber **nicht immer live-verifiziert**: Ein Sub-Agent bestätigte mir das tote `reiseauskunft.bahn.de`-Format aus "Wissen", ohne es zu testen → shippen gab `DNS_PROBE_FAILED`. **Jede URL-/Endpoint-Empfehlung eines Sub-Agenten vor dem Einbau selbst mit curl/browser prüfen** (DNS + HTTP + ob Parameter wirklich wirken), nicht nur dem Format-Urteil vertrauen.
|
||
- Wenn der Nutzer systematisch Fehler findet, stoppe und führe eine Review-Runde durch, statt einzeln weiterzubauen.
|
||
|
||
## Daten-Generierungs-Pitfalls (mehrstufige Listen/Filter)
|
||
|
||
Aus der 3-Ebenen-Zugsuche (urlaub.perfekt-ohne-en.de, Flask+SQLite):
|
||
|
||
- **Sortier-Filter schneidet sichtbare Kategorien ab.** Sortiert man Ziele nach Distanz und nimmt `[:N]`, bleiben NUR die nächsten (z. B. nur "unter 5h") — ferne 5-7h/>7h-Ziele "verschwinden". Fix: **je Kategorie** (unter5h / 5-7h / über7h) separat die repräsentativsten N Ziele nehmen, damit alle Kategorien in jeder Liste vertreten bleiben.
|
||
- **Kategorie aus dem berechneten Wert ableiten, nicht aus einer geplanten Bandbreite.** Wenn Label und berechnete Zeit auseinanderlaufen (z. B. Kategorie "5-7h" aber Zeit ~3h), ist das ein Review-findbarer Inkonsistenz-Bug. Einheit: `kategorie = f(berechne_zeit)`.
|
||
- **Platzhalter vermeiden.** Pauschale Dummy-Werte (z. B. alle Einwohner=150000) sind Datenfehler — der Nutzer merkt, dass keine echten kleinen Städte drin sind. Entweder echte Werte oder NULL/"k.A.", nie plausible Dummy-Zahl.
|
||
- Wenn eine Städte-/Ziel-Datenbank auf viele Einträge skaliert (190+ Städte, 10000+ Verbindungen): **generiere deterministisch** aus einer Referenzliste + Distanz-Logik, statt manuell jede Zuordnung zu erfinden. Mit klarer Kategorie- und Zeit-Ableitung.
|
||
|
||
## Flask+SQLite für dynamische, user-gepflegte Daten (statt statischer Seiten)
|
||
|
||
Bei mehrstufiger Navigation (Ebenen, Klick-Weiterleitung mit `/2/<slug>`-URLs) und vielen Datensätzen: **Backend + SQLite** schlägt statische Generierung.
|
||
- Eine Datenänderung = eine DB-UPDATE, alle abhängigen Seiten/PDFs aktualisieren sich — statisch wäre ein Full-Rebuild von tausenden Dateien.
|
||
- Isolate Semantik: URL-Route `/2/<slug>` zuverlässig machen (Bindestriche↔Umlaute: `osnabrueck`, auch `koln`-Formen, mit mehrstufiger Kandidaten-Rücktranskription).
|
||
- PDF on-demand (wkhtmltopdf) statt vorab für jede Kombination.
|
||
- Deploy: systemd-Service + nginx reverse_proxy auf `127.0.0.1:<port>` (Muster wie das sshportal-Backend); statische/Server-Reload-Cache: **nach Template-/Code-Änderung Restart**, sonst rendert die laufende App veraltete Templates (äußerte sich als "Kategorie fehlt trotz Fix").
|
||
|
||
## Support-Dateien
|
||
- `references/tic-tac-toe-revert-2026-08-04.md` — Revert-Chronologie + 3D-Gotcha-Detail.
|
||
- `references/urlaub-3-ebenen-zugsuche-2026-08-09.md` — Mehrstufige Zugsuche: DB-Deep-Link-Deadends, 25k/10k-Schwellen-Umbau, Kategorien-Generator-Prinzip.
|