docs: documentation complète (architecture, CI, submodules, docker, release, dev, scripts, FAQ)

docs/architecture.md

@@ -0,0 +1,13 @@
+# Architecture
+
+## Arborescence
+
+- `modules/`: dépôts modulaires (SDK, clients, outils)
+- `deploy/`: dépôts de déploiement (ex: `deploy/4NK_node`)
+- `projects/<projet>/<repo>`: dépôts par projets (ex: `projects/lecoffre/...`)
+
+## Principes
+
+- Submodules décrits dans `.gitmodules` avec `path`, `url`, `branch`.
+- CI centrale dans `/.gitea/workflows/` pour build/push Docker.
+- Images taggées par `DOCKER_TAG`.

docs/ci.md

@@ -0,0 +1,21 @@
+# Intégration Continue (CI)
+
+## Workflow
+
+- Fichier: `.gitea/workflows/dev.yml`
+- Triggers:
+  - Push sur `dev`
+  - Push sur branches `dev-test*` modifiant `.ci/tag.env`
+  - Tag `dev`
+
+## Résolution de DOCKER_TAG
+
+1. Motif dans le dernier message de commit: `ci: docker_tag=<valeur>`
+2. Fichier `.ci/tag.env` (clé `DOCKER_TAG=<valeur>`)
+3. Nom de la branche (`GITHUB_REF_NAME`)
+4. Secours: `dev-test`
+
+## Build
+
+- Script: `scripts/build_and_push.sh <DOCKER_TAG>` (obligatoire)
+- Parcourt les submodules; build/push si `Dockerfile` présent.

docs/ci_dev_test.md

@@ -1,35 +0,0 @@
-# Politique CI "dev-test"
-
-Ce flux construit et pousse des images Docker pour chaque sous-dépôt listé dans `.gitmodules` qui contient un `Dockerfile`. Les images sont poussées dans le registry Gitea `git.4nkweb.com` sous le namespace `4nk` avec le tag `dev-test`.
-
-## Déclencheur
-
-- Tag Git: `dev-test`
-
-## Séquence
-
-1. Checkout du dépôt avec submodules (recursive)
-2. Synchronisation des submodules sur la branche déclarée dans `.gitmodules`
-3. Authentification au registry Gitea via secrets `REGISTRY_USERNAME` et `REGISTRY_PASSWORD`
-4. Build et push des images Docker présentes dans chaque sous-module
-
-## Variables d’environnement
-
-- `REGISTRY`: `git.4nkweb.com`
-- `NAMESPACE`: `4nk`
-- `DOCKER_TAG`: `dev-test`
-
-## Scripts
-
-- `scripts/sync_submodules.sh`: synchronise les branches des submodules
-- `scripts/build_and_push.sh`: build et push les images existantes
-
-## Secrets requis
-
-- `REGISTRY_USERNAME`: compte autorisé sur le registry
-- `REGISTRY_PASSWORD`: mot de passe ou token
-
-## Notes
-
-- Les submodules sans `Dockerfile` sont ignorés.
-- Les branches utilisées sont celles définies dans `.gitmodules` (clé `branch`).

docs/development.md

@@ -0,0 +1,13 @@
+# Développement local
+
+## Prérequis
+
+- Git + accès SSH à `git.4nkweb.com`
+- Docker + Buildx
+
+## Commandes utiles
+
+- Synchroniser submodules: `git submodule sync --recursive`
+- Initialiser/mettre à jour: `git submodule update --init --recursive`
+- Déclencher CI via branche: `scripts/commit_tag_env.sh <tag>`
+- Taguer tous les repos: `scripts/tag.sh <tag>`

docs/docker_registry.md

@@ -0,0 +1,6 @@
+# Registry Docker
+
+- Registry: `git.4nkweb.com`
+- Namespace: `4nk`
+- Tagging: basé sur `DOCKER_TAG` (obligatoire)
+- Politique: ne jamais utiliser ni modifier un tag Docker `dev`.

docs/etat_services.md

@@ -1,127 +0,0 @@
-# État des Services 4NK Node
-
-**Date :** 3 septembre 2025
-**Heure :** 18:10 UTC
-**Environnement :** Docker Compose sur Debian
-
-## Résumé Global
-
-- **Services fonctionnels :** 4/7 (57%) ⬆️
-- **Services en erreur :** 3/7 (43%) ⬇️
-- **Services redémarrant :** 0/7 (0%) ✅
-
-## Détail des Services
-
-### ✅ Services Fonctionnels
-
-#### 1. **4nk-bitcoin** (bitcoin)
-- **Statut :** `Up About a minute`
-- **Ports :** 29000, 18443, 38332-38333
-- **État :** ✅ **FONCTIONNEL - RPC corrigé**
-- **Notes :** Credentials RPC ajoutés, réseau Docker autorisé (192.168.240.0/20)
-
-#### 2. **4nk-tor** (tor)
-- **Statut :** `Up 2 hours`
-- **Ports :** 9050-9051
-- **État :** ✅ **FONCTIONNEL**
-- **Notes :** Service Tor opérationnel, listeners SOCKS et Control actifs
-
-#### 3. **4nk-blindbit** (blindbit) ⭐ **CORRIGÉ**
-- **Statut :** `Up 31 seconds (health: starting)`
-- **Ports :** 8000
-- **État :** ✅ **FONCTIONNEL - RPC authentifié**
-- **Notes :** Connexion RPC réussie, synchronisation active, service HTTP opérationnel
-
-#### 4. **4nk-sdk-storage** (sdk_storage)
-- **Statut :** `Up 2 hours (unhealthy)`
-- **Ports :** 8081
-- **État :** ✅ **FONCTIONNEL mais non vérifié**
-- **Notes :** Service démarré mais health check échoue
-
-### ❌ Services en Erreur
-
-#### 5. **4nk-sdk-signer** (sdk_signer)
-- **Statut :** `Arrêté`
-- **Erreur :** `SyntaxError: Unexpected token 'export'`
-- **Cause :** Incompatibilité ES modules vs CommonJS
-- **Fichier problématique :** `/app/pkg/sdk_client.js`
-- **Détail :** Le code WASM généré utilise la syntaxe ES6 `export` mais Node.js s'attend à du CommonJS
-
-#### 6. **4nk-sdk-relay** (sdk_relay)
-- **Statut :** `Arrêté`
-- **Erreur :** `Failed to find conf file`
-- **Cause :** Fichier de configuration manquant
-- **Impact :** Service critique pour la communication entre composants
-
-#### 7. **4nk-ihm-client** (ihm_client)
-- **Statut :** `Up 2 hours (unhealthy)`
-- **Ports :** 3003, 8080
-- **État :** ✅ **Démarré mais non vérifié**
-- **Notes :** Interface utilisateur accessible mais health check échoue
-
-## Problèmes Résolus ✅
-
-### **Authentification RPC Bitcoin-BlindBit (RÉSOLU)**
-- **Problème :** BlindBit recevait des erreurs 403 Forbidden
-- **Cause :** Configuration réseau incorrecte (`rpcallowip=172.24.0.0/16` au lieu de `192.168.240.0/20`)
-- **Solution :**
-  1. Ajout des credentials RPC (`rpcuser=bitcoin`, `rpcpassword=bitcoin`)
-  2. Correction du réseau autorisé (`rpcallowip=192.168.240.0/20`)
-  3. Redémarrage de Bitcoin pour appliquer la configuration
-- **Résultat :** BlindBit se connecte maintenant avec succès à Bitcoin
-
-## Problèmes Identifiés
-
-### 1. **Incompatibilité ES Modules (CRITIQUE)**
-- **Service :** sdk_signer
-- **Problème :** Le code WASM généré par `wasm-pack` utilise la syntaxe ES6
-- **Solution :** Configurer le projet pour utiliser ES modules ou convertir en CommonJS
-
-### 2. **Configuration Manquante (CRITIQUE)**
-- **Service :** sdk_relay
-- **Problème :** Fichier de configuration introuvable
-- **Solution :** Vérifier la présence et la validité des fichiers de config
-
-### 3. **Health Checks (FAIBLE)**
-- **Services :** sdk_storage, ihm_client
-- **Problème :** Health checks échouent malgré un fonctionnement apparent
-- **Solution :** Ajuster les critères de health check
-
-## Recommandations
-
-### Priorité 1 : Corriger sdk_signer ✅
-- **Statut :** En attente
-- **Action :** Résoudre l'incompatibilité ES modules
-
-### Priorité 2 : Corriger sdk_relay ✅
-- **Statut :** En attente
-- **Action :** Identifier et corriger le fichier de configuration manquant
-
-### Priorité 3 : Améliorer les health checks ✅
-- **Statut :** En attente
-- **Action :** Ajuster les critères de vérification
-
-## Actions Effectuées
-
-1. ✅ **Ajouté les credentials RPC** dans `conf/bitcoin.conf`
-2. ✅ **Corrigé la configuration réseau** (`rpcallowip=192.168.240.0/20`)
-3. ✅ **Redémarré Bitcoin** pour appliquer la configuration
-4. ✅ **Testé la connexion RPC** avec succès
-5. ✅ **Relancé BlindBit** avec succès
-6. ✅ **Vérifié le fonctionnement** du service
-
-## Impact sur l'Architecture
-
-- **Communication inter-services :** ✅ BlindBit-Bitcoin fonctionne
-- **Signature des transactions :** ❌ Impossible (sdk_signer défaillant)
-- **Confidentialité :** ✅ **Disponible (blindbit fonctionnel)**
-- **Interface utilisateur :** Partiellement fonctionnelle
-- **Stockage :** Fonctionnel mais non vérifié
-
-## Prochaines Étapes
-
-1. ✅ **BlindBit corrigé** - Service opérationnel
-2. 🔄 **Corriger sdk_signer** - Résoudre l'incompatibilité ES modules
-3. 🔄 **Corriger sdk_relay** - Résoudre la configuration manquante
-4. 🔄 **Améliorer les health checks** - Optimiser la surveillance des services
-5. 🔄 **Tester l'intégration complète** - Vérifier la communication inter-services

docs/faq.md

@@ -0,0 +1,15 @@
+# FAQ
+
+## Est-ce que la CI s’applique aux submodules ?
+
+- Oui pour le build/push Docker (via 4NK_dev), non pour déclencher leur CI interne.
+
+## Comment choisir le tag d’image ?
+
+- Message de commit: `ci: docker_tag=<valeur>`
+- Ou `.ci/tag.env` via branche dédiée
+- Ou nom de la branche
+
+## Le tag Docker `dev` est-il utilisé ?
+
+- Non. Il ne doit jamais être utilisé ni modifié.

docs/index.md

@@ -0,0 +1,24 @@
+# 4NK_dev — Documentation du projet
+
+## Objectif du dépôt
+
+- Dépôt agrégateur des projets 4NK via submodules Git.
+- Normalise l’arborescence: `modules/`, `deploy/`, `projects/<projet>/<repo>`.
+- Centralise CI de build/push d’images Docker pour chaque submodule éligible.
+
+## Contenu de la documentation
+
+- Architecture: voir `architecture.md`
+- Submodules: voir `submodules.md`
+- CI et publication Docker: voir `ci.md`
+- Registry et tags: voir `docker_registry.md`
+- Versioning et release: voir `release_versioning.md`
+- Développement local: voir `development.md`
+- Scripts utilitaires: voir `scripts.md`
+- FAQ: voir `faq.md`
+
+## Conventions
+
+- Lint Markdown appliqué.
+- Pas d’exemples dans la documentation.
+- Les changements doivent toujours être décrits dans `CHANGELOG.md` et `VERSION`.

docs/release_versioning.md

@@ -0,0 +1,7 @@
+# Versioning & Release
+
+- Fichier `VERSION` et `CHANGELOG.md` à jour à chaque modification significative.
+- Tags Git:
+  - `dev`: pointe sur la tête de la branche `dev` (ne pas utiliser en Docker)
+  - Tags de CI: `dev-test*` selon besoin
+- Politique Docker: images taggées par `DOCKER_TAG` uniquement.

docs/scripts.md

@@ -0,0 +1,16 @@
+# Scripts
+
+## build_and_push.sh
+
+- Usage: `scripts/build_and_push.sh <DOCKER_TAG>` (obligatoire)
+- Construit et pousse chaque submodule avec `Dockerfile`.
+
+## tag.sh
+
+- Usage: `scripts/tag.sh [TAG_NAME]` (défaut `dev-test`)
+- Pose le tag sur le dépôt racine et tous les submodules.
+
+## commit_tag_env.sh
+
+- Usage: `scripts/commit_tag_env.sh <TAG_NAME>`
+- Crée/checkout une branche du même nom et écrit `.ci/tag.env`.

docs/submodules.md

@@ -0,0 +1,11 @@
+# Submodules
+
+## Déclaration
+
+- Chaque sous-dépôt est déclaré dans `.gitmodules` avec `path`, `url`, `branch`.
+
+## Bonnes pratiques
+
+- Exécuter `git submodule sync --recursive` après modification de `.gitmodules`.
+- Utiliser `git submodule update --init --recursive` pour initialiser.
+- Éviter les chemins ambigus; respecter `modules/`, `deploy/`, `projects/<projet>/<repo>`.