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.