et le développement

Besoins

• Go 1.26 ou plus récent; le module épingle la chaîne d'outils minimale.
• Node.js 24 (voir .node-version).
• pnpm 9.12.2, correspondant à la façade packageManager sur le terrain.
• jq pour les tests de sélection synthétique de l'installateur.
• Docker est facultatif pour le développement local et nécessaire uniquement pour la vérification du conteneur.

Exécutez toutes les cibles Make à partir de la racine du dépôt.

Commandes

make clean ne supprime pas la base de données ou les dépendances. Air reconstruise et redémarre automatiquement le moteur lorsque Go source, SQL embarqué, go.modou go.sum modifications. Vite met à jour le code frontend via HMR sans redémarrer le moteur. Utilisation make dev WEB_PORT=5174 lorsque le port frontend par défaut est occupé.

Le Makefile exécute Air v1.67.4 à travers go run; la première invocation le télécharge et le construit. Aucune installation Air globale n'est nécessaire, et ses dépendances restent en dehors du module d'application. .air.toml garde les constructions temporaires sous ignorées bin/air/ et donne au serveur jusqu'à dix secondes pour l'arrêt gracieuse avant un redémarrage. Le moteur de développement construit désactiver CGO, la production correspondante construit et évite les erreurs de déploiement de linker macOS C. Les tests de course utilisent toujours CGO.

Configuration

Copier .env.example n'active pas. Exportez des variables dans votre shell ou fournissez-les à une seule commande :

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

WEB_PORT ne change que le port frontend. Le moteur écoute sur 127.0.0.1:8080 par défaut, et Vite lit la même SUBLANE_ADDR comme moteur. Si un existant Docker instance ou un autre processus utilise 8080, choisissez un port d'arrière-plan gratuit:

SUBLANE_ADDR=127.0.0.1:9090 make dev WEB_PORT=5174

make dev vérifie l'adresse du moteur avant de démarrer Air ou Vite et échoue si elle est occupée. Cela empêche une nouvelle façade de se connecter silencieusement à un moteur non lié ou plus ancien alors qu'Air continue de fonctionner après une défaillance de liaison. make dev-api et make dev-web séparément, passez la même SUBLANE_ADDR aux deux commandes.

Les API proxy doit préserver Host (changeOrigin: false) pour l'authentification d'origine identique. Commencez par un répertoire de données de test vide pour exercer la configuration et créer un administrateur à travers le formulaire en utilisant des identifiants synthétiques. Ne réinitialisez jamais une instance de travail en supprimant sa base de données.

Essais

Les tests backend couvrent la validation de l'environnement, frais SQLite initialisation, configuration/course/retour unique, cycle de vie des membres, limites de session par utilisateur, révocation du temps de désactivation, fonction API l'accès, les contrôles d'origine/de corps, les limites de taux, l'échec de préparation, et APILes tests frontend couvrent le routage et les menus role-aware, les modifications de création/état des membres, la validation de configuration, les erreurs de connexion, la déconnection et la suppression de cache cross-identity, l'expiration, la validation de réponse, la navigation et la sélection persistante de thèmes/langue. Utilisez uniquement des appareils synthétiques et des bases de données temporaires.

Exécuter des tests ciblés pendant le développement:

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

La vérification du navigateur devrait couvrir les plans de bureau et les plans étroits, la navigation mobile, le rechargement de la route directe, les changements de langue, les thèmes de lumière/dark/système et un moteur déconnecté.

Codex essais d'adaptateurs

Les tests d'adaptateur n'utilisent jamais un compte réel. Ils injectent des faux locaux en amont à travers une couture de transport pendant que la sélection de la production reste fixe. Codex CLI avec une configuration temporaire isolée et une sortie de modèle synthétique:

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

La suite de test normale saute ce test client externe opt-in. Ne pas lire l'existant d'un développeur auth.json ou porte-clés pour les tests. L'acceptation du fournisseur et du bureau en direct nécessite un compte explicitement autorisé; enregistrez ces résultats séparément de la couverture du protocole.

Ajout de traductions

1. Ajouter une clé anglaise dans web/src/locales/en.ts.
2. Ajouter la même clé dans web/src/locales/zh.ts et chaque local supplémentaire JSON Préserver les variables d'interpolation et fournir les catégories plurielles requises par chaque langue.
3. Utilisation useTranslation() et t() dans les composants, y compris les étiquettes ARIA.
4. Exécuter pnpm --dir web typecheck et d'inspecter les traductions plus longues sur le bureau et les largeurs étroites. Vérifier la disposition de droite à gauche arabe et garder le code et les identifiants de gauche à droite.

Les langues prises en charge sont l'anglais, le chinois simplifié, le chinois traditionnel, le japonais, le coréen, l'espagnol, le français, l'allemand, le portugais, le russe et l'arabe. content/docs/ et les traductions en content/<locale>/, avec des limaces correspondantes, la navigation localisée, la recherche et les exportations de Markdown. De nouvelles traductions sont assistées par machine et ont besoin d'un examen par haut-parleur natif.

Les préférences de l'interface utilisateur sont locales au navigateur. Ils ne sont pas des paramètres d'équipe et ne sont pas écrits à SQLite.

HTTP itinéraires et requêtes de bases de données

HTTP itinéraires utilisent chi avec standard net/http Les ressources enregistrent leurs propres Get, Head, Postet Patch manipulateurs à l'intérieur Route groupes. Ajouter des itinéraires de gestion au routeur protégé par l'administrateur dans internal/server/server.go. L'authentification publique et les itinéraires à clé personnelle sont des exceptions explicites. L'authentification de la session, du rôle et de la passerelle passe par le niveau du routeur Use, protéger les erreurs de méthode et les chemins inconnus ainsi que les paramètres correspondants. With ne pas réintroduire la méthode ou les commutateurs d'expédition de chemin dans les gestionnaires.

Chaque sous-routeur installe JSON NotFound et MethodNotAllowed Le gestionnaire 405 dérive Allow des itinéraires enregistrés de chi Match, sans utiliser les gestionnaires d'applications. Contrôles de santé, statut du système et actifs statiques enregistrer explicitement HEAD; d'autres API conservent leurs méthodes déclarées. Le SPA est enregistré uniquement pour GET/HEAD à la racine et ne peut pas gérer réservé API Les retombées.

Ecrire les requêtes SQL dans internal/storage/queries/, regroupés par domaine. sqlc.yaml utilise le SQL d'initialisation consolidée comme son schéma et génère internal/storage/db/. Courez make generate après avoir modifié les requêtes, le schéma ou la configuration du générateur. Commit SQL et généré Go ensemble; jamais modifier manuellement les fichiers générés. WithTx(tx), et convertir les lignes en types de réponse publique.

Le Makefile pins sqlc à v1.31.1 et l'exécute go run; la première invocation télécharge et construit l'outil. Go peut télécharger une chaîne d'outils compatible pour le générateur. Aucune installation globale sqlc, service cloud, ou connexion de base de données est nécessaire pour la génération. Les dépendances génératrices restent en dehors du graphique de dépendance module de l'application. Les fichiers générés sont en version, de sorte que les constructions Go ordinaires et les conteneurs de production n'ont pas besoin de sqlc. make check, y compris CI , make generate-check de rejeter le code généré par l'impasse sans le réécrire.

Modification du schéma de prélibération

Conservez les fichiers existants de internal/storage/migrations/, dont 001_schema.sql. Ajoutez des migrations incrémentales ordonnées et mettez à jour les requêtes de internal/storage/queries/. Le démarrage applique les migrations manquantes aux bases compatibles ; l’ancienne structure incompatible identifiée par 001_settings.sql est refusée. Exécutez make generate, make generate-check et les tests de stockage concernés. sqlc valide la structure mais ne migre pas la base en cours d’exécution.

Dépannage

• Retour de racine de moteur frontend_not_built: utiliser Vite sur le port 5173 pour le développement, ou courir make build et commencer bin/sublane.
• Frontend montre une défaillance de connexion : confirmer que le processus Go est en cours d'exécution et les points proxy de Vite à l'adresse configurée.
• Port déjà utilisé: WEB_PORT contrôle Vite; SUBLANE_ADDR contrôle le moteur et son mandataire Vite. Choisissez une adresse de moteur gratuite, par exemple SUBLANE_ADDR=127.0.0.1:9090 make dev WEB_PORT=5174. Ne pas mettre fin à des processus non liés.
• Allez télécharger une chaîne d'outils: ceci est attendu lorsque le Go installé est plus ancien que go.mod demande.
• Docker build ne peut pas se connecter : commencer votre Docker moteur, puis tourner docker compose -f docker.compose.yaml config --quiet et docker compose -f docker.compose.yaml -f docker.compose.build.yaml build.
• Changement de langue ou de thème : Les préférences sont délibérément stockées dans le stockage local du navigateur. Changez-les dans les préférences pour restaurer les défauts.

Entretien

Gardez go.sum et web/pnpm-lock.yaml Exécuter des mises à jour de dépendance comme des modifications séparées et préserver les avis de licence tiers. Ne copiez pas un arbre Shadcn Admin plus récent sur les composants locaux sans examiner les changements de localisation, de nommage et d'accessibilité.

Contrôles d'emballage et de libération

Voir déploiement pour les essais de fumée dans les réservoirs et opérations de mainlevée pour le pipeline déclenché par l'étiquette. make test comprend les tests intégrés des métadonnées de diffusion de nœuds et les tests temporaires de publication de dépôts; make lint CI construit et teste des conteneurs sur les deux architectures Linux natives, puis le workflow de publication publie les images testées et extrait leurs binaires. Aucune identification de registre n'est utilisée dans les vérifications de pull-request.