Wegwichtel/docs/agents/AGENTS.md

# Agent-Anweisungen für Wegwichtel

Diese Datei vor jeder Änderung am Projekt lesen. Sie gilt für das gesamte
Repository. Da sie unter `docs/agents/` liegt, muss ihr Pfad in Übergaben und
Agent-Aufträgen ausdrücklich genannt werden; eine automatische Suche nach
einer `AGENTS.md` im Projektverzeichnis findet sie dort nicht.

## Ablage der Dokumentation

- Markdown mit Agent-Anweisungen, Entwicklungsvorgaben und offenen
  Entwicklungsaufgaben ausschließlich unter `docs/agents/` ablegen.
- Markdown für Anwender und Betrieb ausschließlich direkt unter `docs/` ablegen.
- Keine eigenen Markdown-Dateien im Projektverzeichnis oder neben Werkzeugen
  und ausgelieferten Bibliotheken anlegen. Links nach Umzügen aktualisieren.
- Bei Übergaben die relevanten Markdown-Dateien im Repository mit ihren
  aktuellen Pfaden ausdrücklich nennen, insbesondere diese Datei sowie
  `docs/agents/I18N.md`, `docs/agents/GPX-Aufzeichnung.md` und
  `docs/agents/TODO-MODERATION.md`.

# Wegwichtel: Sprache der App

GPX-Änderungen berücksichtigen `GPX-Aufzeichnung.md`: Stationen sind `wpt`,
Aufzeichnungen sind `trkpt`, der Server normalisiert zu `rtept`. Fehlende
Koordinaten bleiben gespeichert und bearbeitbar; keine Ersatzkoordinaten erfinden.
Die GPX-Dateien sind die einzige Quelle der Routenpunkte und berechneten
Routenwerte. SQLite speichert davon nur Min-/Max-Grenzen für die Näheresuche.
Schemaänderungen immer auch mit der Startprüfung an einer vorhandenen,
frisch erzeugten Testdatenbank prüfen.

Diese Vorgabe des Nutzers gilt für alle künftigen Änderungen an der Oberfläche.
Die App richtet sich an Grundschulkinder und Menschen ohne technische Vorkenntnisse.

- Schreibe kurze, verständliche Sätze. Sprich die Nutzer mit „du“ an.
- Erkläre, was eine Aktion bewirkt und was als Nächstes zu tun ist.
- Verwende durchgängig „Strecke“, „Station“, „Meine Entwürfe“ und „für unterwegs speichern“.
- Technische Begriffe wie GPX, JSON, Cache, API, OPFS, IndexedDB, Local Storage,
  Server, Token oder interne Feldnamen gehören nicht in Bedienungstexte,
  Hilfe, Statusmeldungen, Dateiauswahl-Beschreibungen oder vorgelesene Beschriftungen.
- Bezeichne einen Wegexport als „Weg als Datei herunterladen“. Erkläre bei Bedarf,
  dass die Datei für eine andere Wander-App gedacht ist und keine Bilder oder Ton enthält.
- Verwende „Bilder und Tonaufnahmen“ statt „Medien“, „Zur Prüfung senden“ statt „Upload“
  und „auf diesem Gerät“ statt „lokal im Browser“.
- Fehlermeldungen nennen das Problem und einen verständlichen nächsten Schritt.
  Zeige keine rohen Fehler aus dem Betriebssystem, Netzwerkantworten oder Dateipfade.
- Vereinfache auch Hilfen zu Daten und Speicher. Behalte wichtige Angaben zu
  Löschung, Erlaubnissen, Grenzen und Speicher-Schätzungen bei. Mache keine
  Zusicherungen, die die App nicht einhalten kann.
- Rechtliche Texte dürfen notwendige Rechtsbegriffe behalten. Erkläre sie einfach;
  ändere dabei nicht die Bedeutung, Verantwortlichen oder Kontaktdaten.
- Fachliche Details für Entwicklung und Betrieb gehören in Projekt-Dokumentation
  und Code-Kommentare. Code-Bezeichner, Dateiformate und Schnittstellen bleiben fachlich präzise.
- Prüfe neue Texte und angepasste Text-Erwartungen in den vorhandenen Tests.

## Kontaktadresse

Die eingerichtete Kontaktadresse für Wegwichtel ist `info@wegwichtel.de`.
Sie gilt für App-Kontakt, technische Fragen, Rechtefragen, Datenschutzanfragen,
Widerruf und Entfernung von Aufnahmen. In Rechtstexten statisch einsetzen.
Schul- und Behördenadressen bleiben die Kontakte der jeweiligen Stellen.

## Texte und Übersetzungen

- Alle eigenen Bedienungstexte liegen zentral in der Klasse `WegwichtelTexts`
  in `public/js/texts-de.js`. Keine neuen sichtbaren Texte direkt in HTML oder
  Funktionscode schreiben.
- Ausnahme: Impressum, Datenschutzerklärung und Nutzungsvereinbarung bleiben ausschließlich statisch
  auf Deutsch in `public/index.html` und tragen `lang="de"`. Ihre Texte und
  Kontaktangaben gehören nicht in Sprachdateien und erhalten keine i18n-Attribute.
  Auch ihre Dialogüberschriften bleiben beim Sprachwechsel auf Deutsch.
- Das HTML enthält daraus erzeugte deutsche Standardtexte, damit Beschriftungen
  vor dem Laden der Skripte vorhanden sind. Nach Änderungen am Textkatalog
  `node scripts/localize-html.js` ausführen und `public/index.html` mit ablegen.
  Diese erzeugten Texte nicht von Hand ändern; die i18n-Attribute bleiben erhalten.
- JavaScript bezieht Texte über `Wegwichtel.I18n.t(textKey, variables)`.
  HTML verwendet `data-i18n` bzw. `data-i18n-aria-label`, `data-i18n-title`,
  `data-i18n-placeholder` und `data-i18n-alt`.
- Zahlen und Namen sind Platzhalter; ganze Sätze übersetzen, keine Sätze aus
  deutschen Wortteilen zusammensetzen. Für Mengen Einzahl und Mehrzahl verwenden.
- Nutzerinhalte wie Streckennamen, Beschreibungen und Aufnahmen nicht automatisch
  übersetzen oder verändern. Interne Fehlerdiagnosen dürfen technisch bleiben;
  die sichtbare Meldung muss verständlich sein.
- Sprachdateien heißen `public/js/texts-<Sprache>.js` und verwenden dieselbe
  generische Klasse `WegwichtelTexts`. Sie registrieren sich in `TextCatalogs`.
  Die App lädt Deutsch und Englisch und wählt anhand von `navigator.languages`
  bzw. `navigator.language`. Fehlende Übersetzungen fallen auf den ersten
  geladenen Katalog zurück (in der App Deutsch).
- Verwende kurze, stabile englische Funktionsschlüssel wie `app.no-route` oder
  `bootstrap-loader.error.start-error`. Schlüssel nicht aus dem deutschen Text
  ableiten. Startmeldungen in `bootstrap-loader.steps` nach Schritt gruppieren.
- Deutsch und Englisch enthalten dieselben Schlüssel, Platzhalter und Pluralformen.
  Texte in beiden Sprachen einfach und sinngemäß schreiben. Sprachwechsel aktualisieren feste Beschriftungen;
  bereits erzeugte dynamische Ansichten bei Bedarf neu rendern.

## Ausrichtung von Bedienelementen

Button-Gruppen in Strecken- und Stationslisten am rechten Kartenrand ausrichten.
Icon-Buttons bekommen einheitliche Breiten, Höhen und Abstände, auch wenn sie
inaktiv sind. Titel dürfen umbrechen und verändern die Button-Spalten nicht.
Die Bedienflächen bleiben mindestens 44 × 44 Pixel groß.

## Lokale Bilder und Tonaufnahmen erst bei Bedarf laden

Beim Öffnen oder Speichern einer Strecke und beim Umordnen von Stationen
nur Metadaten lesen. Keine Dateien aller Stationen hydratisieren.
Dateireferenzen bzw. IndexedDB-Dateien erst beim Bearbeiten oder Aufrufen
der jeweiligen Station lesen. Der Upload liest die benötigten Dateien direkt.
Temporäre Blob-URLs beim Verlassen der Ansicht freigeben; verspätete
Ladeergebnisse dürfen eine andere Station oder geschlossene Ansicht nicht ändern.

## Stationsorte in der Routenberechnung

Beim Hochladen und erneuten Berechnen sowohl aufgezeichnete Wegpositionen als
auch `wpt` mit gültigen Koordinaten berücksichtigen. Stationsanker dürfen nicht
durch die GPS-Clusterbildung wegfallen. Nur gültige Koordinaten einbeziehen;
Stationen ohne Standort bleiben bearbeitbar. Berechnete Stationsanker im GPX
kennzeichnen und bei Verschieben/Löschen ersetzen, statt veraltete Orte zu behalten.
Rätsel-Stationen sind für später in `docs/agents/TODO-RAETSEL-STATIONEN.md` vorgemerkt.

## Pipeline und SonarQube nach einem Check-in überwachen

Verbindlicher Arbeitsablauf des Nutzers, vereinbart am 5. Oktober 2026:

- Sobald der Nutzer einen neuen Check-in meldet, den aktuellen Repository-Stand
  und den zugehörigen Commit ermitteln und den passenden Pipeline-Lauf unter
  https://git.shettereck.com/IT-Works/Wegwichtel/actions verfolgen.
- Während der aktiven Chatsitzung bis zum Abschluss prüfen und bei längeren
  Wartezeiten kurze Statusmeldungen geben. Keine dauerhafte Überwachung außerhalb
  der Sitzung behaupten; dafür wäre eine gesonderte Automatisierung erforderlich.
- Bei Coverage- oder Testfehlern die Ausgabe auswerten, die Ursachen korrigieren
  und die betroffenen Tests und Coverage-Prüfungen lokal ausführen. Keine Tests
  abschwächen oder Grenzwerte senken, nur um die Pipeline grün zu machen.
- Bei einem fehlgeschlagenen SonarQube Quality Gate den Bericht abrufen:
  POST https://sqube.shettereck.com/sqexport/api/export
  mit Content-Type: application/json und JSON {"projectKey":"Wegwichtel"}.
  Optional kann filename angegeben werden. Das SonarQube-Token ist serverseitig
  gesetzt; kein clientseitiges SonarQube-Token ist erforderlich.
- Der Export-Zugang erfordert Authorization: Bearer <Agententoken>. Das Token
  wird vor dem Export-Tool von Nginx geprüft. Zugang ist getestet: gültiges Token
  ergibt 200, ungültiges Token 403, ohne Token erfolgt die Browser-Anmeldung.
  Geheimnisse nicht in Repository, Dokumentation, Archive oder Testausgaben
  aufnehmen. In einer neuen Sitzung den Zugang über einen dafür vorgesehenen
  sicheren Kanal bereitstellen, falls er dort nicht bereits verfügbar ist.
- Die Revision der SonarQube-Analyse mit dem gemeldeten Commit vergleichen.
  Ein abgeschlossener Scanner-Lauf bedeutet nicht automatisch, dass der Bericht
  bereits die neue Analyse enthält. Bei einer älteren Revision erneut abrufen.
- Findings und die Ursachen des fehlgeschlagenen Gates korrigieren und passende
  Tests ausführen. Security Hotspots fachlich bewerten; notwendige manuelle
  Bewertungen klar benennen und nicht als bereits erledigt ausgeben.
- Korrigierte Versionen als Archiv vollständiger Dateien mit Projektpfaden
  liefern, damit der Nutzer sie ins Projekt kopieren und per VS Code vergleichen
  kann. Nur Änderungen gegenüber dem aktuellen Online-Repository aufnehmen.
  public/images/group-symbols und 3rdparty nur aufnehmen, wenn dort neue oder
  tatsächlich geänderte Dateien vorliegen. Erforderliche Löschungen separat nennen.
- Ohne gesonderten Auftrag keine Änderungen ins Online-Repository pushen oder
  deployen. Nach dem nächsten Check-in den Ablauf für dessen Commit wiederholen.
- In jeder Übergabezusammenfassung diesen Ablauf, die Actions-URL, den Export-
  Endpunkt, die Authentifizierung ohne Tokenwert und den Pfad
  docs/agents/AGENTS.md ausdrücklich nennen. Die weiteren relevanten Dateien
  unter docs/agents/ ebenfalls mit aktuellen Pfaden aufführen.

Bestätigter Ausgangsstand am 5. Oktober 2026: Commit
49a9de0355c81b4f109c165762068a66046cf003; Scanner-Lauf 1345 / Nummer 110
 erfolgreich; Quality Gate OK; alle 121 Findings CLOSED/FIXED; beide Security
Hotspots REVIEWED/SAFE. Dieser Stand ist eine historische Referenz und ersetzt
nicht die Prüfung einer neuen Analyse.