Entwicklung

Anforderungen

• Gehen Sie 1.26 oder neuer; das Modul pins die minimale Toolchain.
• Node.js 24 (siehe) .node-version).
• pnpm 9.12.2, passend zum Frontend packageManager Feld.
• jq für die synthetischen Release-Selektionstests des Installateurs.
• Docker ist für die lokale Entwicklung fakultativ und nur für die Überprüfung von Containern erforderlich.

Führen Sie alle Ziele aus dem Repository-Root aus.

Befehle

make clean Air baut das Backend automatisch neu auf und startet es neu, wenn Go source, embedded SQL, go.mod, oder go.sum Vite aktualisiert Frontend-Code über HMR, ohne das Backend neu zu starten. make dev WEB_PORT=5174 wenn der voreingestellte Frontend-Port besetzt ist.

Das Makefile läuft Air v1.67.4 durch go run; der erste Aufruf lädt und baut ihn auf. Es wird keine globale Air-Installation benötigt, und seine Abhängigkeiten bleiben außerhalb des Anwendungsmoduls. .air.toml hält temporäre Builds unter Ignoriert bin/air/ und gibt dem Server bis zu zehn Sekunden Zeit, um anmutig vor einem Neustart heruntergefahren zu werden. Entwicklungs-Backend-Builds deaktivieren CGO, passen Produktions-Builds ab und vermeiden macOS C-Linker-Deployment-Ziel-Mismatches. Rennen Tests verwenden immer noch CGO.

Konfiguration

Kopieren .env.example Exportieren Sie Variablen in Ihrer Shell oder geben Sie sie an einen einzigen Befehl:

SUBLANE_LOG_LEVEL=debug make dev
SUBLANE_ADDR=127.0.0.1:9090 ./bin/sublane

WEB_PORT Ändert nur den Frontend-Port, hört das Backend 127.0.0.1:8080 Standardmäßig, und Vite liest dasselbe SUBLANE_ADDR als Backend. Wenn eine bestehende Docker Instance oder ein anderer Prozess verwendet 8080, wählen Sie einen kostenlosen Backend-Port:

SUBLANE_ADDR=127.0.0.1:9090 make dev WEB_PORT=5174

make dev Wenn Air oder Vite gestartet wird, wird die Backend-Adresse überprüft und schlägt fehl, wenn sie besetzt ist. Dadurch wird verhindert, dass ein neues Frontend sich stillschweigend mit einem nicht verwandten oder älteren Backend verbindet, während Air nach einem Bindungsfehler weiter läuft. make dev-api und make dev-web separat, pass das gleiche SUBLANE_ADDR auf beide Befehle.

Die API Proxy muss Host bewahren ()changeOrigin: false) für die Authentifizierung gleichen Ursprungs. Beginnen Sie mit einem leeren Testdatenverzeichnis, um die Einrichtung durchzuführen, und erstellen Sie einen Administrator über das Formular mit synthetischen Anmeldeinformationen. Setzen Sie eine Arbeitsinstanz niemals zurück, indem Sie ihre Datenbank löschen.

Prüfungen

Backend-Tests umfassen Umweltvalidierung, frisch SQLite Initialisierung, einmaliges Setup/Rennen/Rollback, Mitgliederlebenszyklus, Limits pro Benutzersitzung, Disable-Time-Widerruf, rollenbasiert API Zugang, Herkunfts-/Stellenkontrollen, Tarifgrenzen, Ausfallbereitschaft und APIFrontend-Tests umfassen rollenbewusstes Routing und Menüs, Mitgliedererstellung/Statusänderungen, Einrichtungsvalidierung, Anmeldefehler, Logout und identitäre Cache-Clearing, Ablauf, Antwortvalidierung, Navigation und persistente Themen-/Sprachauswahl.

Führen Sie fokussierte Tests während der Entwicklung durch:

go test ./internal/server -run TestRoutesAndAssetBoundary -count=1
pnpm --dir web test src/App.test.tsx

Die Überprüfung des Browsers sollte sich auf Desktop- und schmale Layouts, mobile Navigation, direktes Strecken-Reload, Sprachänderungen, Hell-Dunkel-System-Themen und ein getrenntes Backend erstrecken. Unit-Tests ersetzen diese Prüfungen nicht.

Codex Adapterprüfungen

Die Adapter-Tests verwenden niemals ein echtes Konto. Sie injizieren lokale gefälschte Upstreams durch eine Transportnaht, während die Auswahl des Produktionsendpunkts festgelegt bleibt. Codex CLI mit isolierter temporärer Konfiguration und synthetischer Modellausgabe:

SUBLANE_TEST_CODEX=1 go test ./internal/server -run TestCodexCLIProtocol -count=1 -v

Die normale Test-Suite überspringt diesen Opt-in-Test für externe Kunden. auth.json Live-Anbieter und Desktop-Akzeptanz erfordern ein ausdrücklich autorisiertes Konto; notieren Sie diese Ergebnisse getrennt von der Protokollabdeckung.

Hinzufügen von Übersetzungen

1. Fügen Sie einen englischen Schlüssel hinzu web/src/locales/en.ts.
2. Fügen Sie den gleichen Schlüssel hinzu web/src/locales/zh.ts und jedes weitere Locale JSON Wörterbuch: Interpolationsvariablen bewahren und die für jede Sprache erforderlichen Mehrfachkategorien angeben.
3. Verwendung useTranslation() und t() in Komponenten, einschließlich ARIA-Etiketten.
4. Lauf pnpm --dir web typecheck und längere Übersetzungen auf dem Desktop und in schmalen Breiten prüfen; arabisches Rechts-Links-Layout überprüfen und Code und Identifikatoren von links nach rechts halten.

Unterstützte Sprachen sind Englisch, Vereinfachtes Chinesisch, Traditionelles Chinesisch, Japanisch, Koreanisch, Spanisch, Französisch, Deutsch, Portugiesisch, Russisch und Arabisch. Zusätzliche Anwendungswörterbücher werden bei Bedarf geladen. content/docs/ und Übersetzungen in content/<locale>/, mit passenden Slugs, lokalisierter Navigation, Suche und Markdown-Exporten. Neue Übersetzungen sind maschinell unterstützt und müssen von Muttersprachlern überprüft werden.

UI-Präferenzen sind lokal für den Browser. Sie sind keine Teameinstellungen und werden nicht geschrieben SQLite.

HTTP Routen und Datenbankanfragen

HTTP Routen verwenden Chi mit Standard net/http Handler. Ressourcen registrieren ihre eigenen Get, Head, Post, und Patch Handler im Inneren Route Gruppen. Hinzufügen von Verwaltungsrouten zum Administrator-geschützten Router in internal/server/server.goÖffentliche Authentifizierung und persönliche Schlüsselrouten sind explizite Ausnahmen. Sitzung, Rolle und Gateway-Träger-Authentifizierung laufen über Router-Ebene Use, Schutz von Methodenfehlern und unbekannten Pfaden sowie übereinstimmenden Endpunkten. With für die Ursprungsvalidierung und -drosselung; keine Wiedereinführung von Methoden- oder Pfadversandschaltern in den Handlern.

Jeder Subrouter installiert JSON NotFound und MethodNotAllowed Handler. Der 405 Handler ist Allow von Chis registrierten Routen durch MatchGesundheitschecks, Systemstatus und statische Assets registrieren HEAD ausdrücklich; andere APIs behalten ihre deklarierten Methoden bei. Das SPA ist nur für GET/HEAD an der Wurzel registriert und kann nicht mit reservierten Daten umgehen. API Ausweichmanöver.

Schreibe mit dem Namen SQL Queries internal/storage/queries/, gruppiert nach Domain. sqlc.yaml verwendet die konsolidierte Initialisierung SQL als Schema und generiert internal/storage/db/. Lauf make generate Nach dem Ändern von Abfragen das Schema oder die Generatorkonfiguration Commit SQL und generiert Go together; nie generierte Dateien manuell bearbeiten. WithTx(tx), und konvertieren Sie Zeilen in öffentliche Antworttypen.

Die Makefile Pins sqlc zu v1.31.1 und läuft es durch go run; der erste Aufruf lädt das Tool herunter und baut es. Go kann eine kompatible Toolchain für den Generator herunterladen. Keine globale sqlc-Installation, Cloud-Service oder Datenbankverbindung ist für die Generierung erforderlich. Generatorabhängigkeiten bleiben außerhalb des Modulabhängigkeitsgraphen der Anwendung. Generierte Dateien sind versioniert, so dass gewöhnliche Go-Builds und Produktionscontainer sqlc nicht benötigen. make check, einschließlich CI, läuft make generate-check veralteten generierten Code zurückzuweisen, ohne ihn umzuschreiben.

Änderung des Prerelease-Schemas

Bewahren Sie bestehende Dateien in internal/storage/migrations/ einschließlich 001_schema.sql unverändert auf. Fügen Sie geordnete additive Migrationen hinzu und aktualisieren Sie Abfragen in internal/storage/queries/. Beim Start werden fehlende Migrationen auf unterstützte Datenbanken angewendet; die frühe inkompatible Struktur mit 001_settings.sql wird abgelehnt. Führen Sie make generate, make generate-check und relevante Speichertests aus. sqlc prüft die Struktur, migriert aber keine laufende Datenbank.

Fehlerbehebung

• Backend Root Returns frontend_not_built: Verwenden Sie Vite auf Port 5173 für die Entwicklung oder laufen make build und beginnen bin/sublane.
• Frontend zeigt einen Verbindungsfehler: Bestätigen Sie, dass der Go-Prozess ausgeführt wird und der Vite-Proxy auf die konfigurierte Adresse verweist.
• Bereits genutzter Port: WEB_PORT steuert Vite; SUBLANE_ADDR das Backend und seinen Vite-Proxy steuert, z.B. eine kostenlose Backend-Adresse wählt, SUBLANE_ADDR=127.0.0.1:9090 make dev WEB_PORT=5174Beenden Sie nicht zusammenhängende Prozesse.
• Go Downloads einer Toolchain: Dies wird erwartet, wenn das installierte Go älter ist als go.mod erfordert.
• Docker Build kann nicht verbinden: Starten Sie Ihre Docker Motor, dann laufen docker compose -f docker.compose.yaml config --quiet und docker compose -f docker.compose.yaml -f docker.compose.build.yaml build.
• Sprache oder Thema bleibt geändert: Präferenzen werden bewusst im lokalen Browserspeicher gespeichert. Ändern Sie sie in Präferenzen, um Standardwerte wiederherzustellen.

Instandhaltung

Bleiben go.sum und web/pnpm-lock.yaml Versionskontrolliertes Ausführen von Abhängigkeits-Upgrades als separate Änderungen und Bewahren von Lizenzhinweisen von Drittanbietern Kopieren Sie keinen neueren Shadcn-Admin-Baum über lokale Komponenten, ohne die Änderungen an Lokalisierung, Benennung und Zugänglichkeit zu überprüfen.

Verpackungs- und Freigabekontrollen

Siehe Einsatz für Behälterrauchprüfungen und Freigabevorgänge für die tag-getriggerte Pipeline. make test umfasst die integrierten Node-Release-Metadatentests und die Veröffentlichungstests für temporäre Repositorys; make lint CI baut und testet Container auf beiden nativen Linux-Architekturen, dann veröffentlicht der Release-Workflow genau diese getesteten Bilder und extrahiert ihre Binärdateien.