Document project rules and development setup

2026-07-18 15:32:20 +02:00
parent b09f208ef3
commit d72aae696f
2 changed files with 99 additions and 0 deletions
@@ -0,0 +1,54 @@
+# Arkteos — règles de contribution
+
+## Périmètre
+
+Ce dépôt prépare l'intégration custom Home Assistant `arkteos` pour une PAC
+Arkteos Zuran 4. L'intégration est strictement en lecture seule.
+
+## Connexion réseau
+
+- Se connecter exclusivement au proxy TCP de l'addon Home Assistant séparé.
+- Ne jamais établir de connexion directe avec la PAC.
+- Le port de référence du proxy est `9641`; il doit rester configurable.
+- Ne jamais émettre d'octet, de commande ou d'acquittement vers le proxy sans
+  preuve explicite que ce comportement est requis et sans décision explicite.
+
+## Référence protocolaire
+
+- La source de vérité actuelle est `references/arkteos_nodered_flow.json`.
+- `references/proxy_protocol_notes.md` documente le contexte connu.
+- Préserver chaque champ décodé par le flow Node-RED de référence.
+- Ne pas déduire de champ, d'offset, d'unité, d'encodage ou de règle de
+  découpage TCP qui ne soit pas démontré par ces références ou par des captures
+  de trames versionnées.
+- Toute nouvelle connaissance du protocole doit citer sa source et être testée
+  avec une capture anonymisée ou un cas de test reproduisible.
+
+## Changements
+
+- Ne supprimer aucune ligne, commentaire, test ou fichier existant sans
+  justification explicite de l'utilisateur.
+- Avant chaque modification, indiquer les fichiers ou zones concernés et la
+  raison du changement; après modification, récapituler ce qui a été fait.
+- Expliquer la zone concernée et présenter le diff avant toute modification
+  importante.
+- Préserver les fichiers de référence et ne jamais les réécrire pour adapter
+  l'intégration.
+
+## Validation
+
+- Ajouter des tests unitaires pour chaque règle de parsing introduite.
+- Exécuter les tests après chaque modification fonctionnelle.
+- Tester les données tronquées, concaténées et inconnues avant de considérer
+  la gestion du flux TCP comme fiable.
+- Vérifier que les plateformes Home Assistant exposées ne permettent aucune
+  action d'écriture.
+
+## Architecture et dépôt
+
+- Séparer le parsing, le transport TCP et le code des entités Home Assistant.
+- Ne jamais versionner d'identifiant, d'adresse IP, de jeton, de mot de passe
+  ni de capture privée.
+- Préférer des commits petits et facilement relisibles.
+- Créer les commits nécessaires et indiquer explicitement quand la branche est
+  prête à être poussée.