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 . 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.