🦀 Aquaprocess V4 — Backend Rust

Refactoring Node.js → Rust | IoT eau industrielle

---

🎯 Objectifs

Axe	Cible
Performance	Latence < 100ms traitement capteurs
Fiabilité	Type safety Rust — zéro crash runtime
Tests	80%+ coverage aquaserveur · 70%+ aquaboitier-embedded
Architecture	Clean Architecture — séparation parse / alertes / persistence

---

📦 Structure Workspace

code_refactorer/
├── Cargo.toml                     # Workspace (resolver=2, 3 membres)
├── docker-compose.base.yml        # Infrastructure de base (MariaDB + Mosquitto)
├── docker-compose.dev.yml         # Env dev complet (backend + boitier + tests)
├── test-mqtt-e2e.sh               # Tests E2E MQTT → vérification DB
├── init-db/project_v4.sql         # Schema MariaDB
├── configs/mosquitto/             # Config Mosquitto
│
├── aquashared/                    # Lib partagée (types communs)
│   └── src/lib.rs                 #   Frame, Alert, AlertType, AquaError
│
├── aquaserveur/                   # Backend serveur
│   ├── Dockerfile                 #   Multi-stage build → image prod minimale
│   └── src/
│       ├── main.rs                #   MQTT event loop (rumqttc async)
│       ├── lib.rs                 #   Module exports
│       ├── frame_parser.rs        #   Parse MPT v2 : !epoch,ext|int+flags#
│       ├── pipeline.rs            #   process_data_frame (parse → alertes)
│       ├── alert_manager.rs       #   Règles seuil + cooldown anti-spam
│       ├── config_sync.rs         #   Sync config JSON → maj_serv-{id} + ACK
│       ├── config_ack_handler.rs  #   Handler ACK config : log ok / alerte error
│       ├── mqtt/subscriber.rs     #   Router MQTT (data-*/firstco/maj_boitier_ACK-*)
│       ├── database/store.rs      #   Persistence MariaDB (sqlx async)
│       └── provisioning/          #   Handler FirstConnect (DDL dynamique)
│
└── aquaboitier-embedded/          # Backend embedded (Opossum ARM64)
    ├── Dockerfile                 #   Multi-stage build x86_64 dev (musl)
    ├── Dockerfile.prod            #   Cross-compile ARM64 (Opossum OPOS8MM)
    └── src/
        ├── main.rs
        ├── serial_parser.rs       #   Parse JSON ESP32 + build trame MPT
        └── alert_detector.rs      #   Détection alertes temp/humidité

---

🧪 Tests

Récapitulatif

Package	Total
aquashared	4
aquaserveur	129
TOTAL	133

⚠️ Cargo n'est PAS installé sur le host. Toujours lancer cargo via Docker (service rust-test).

Tests unitaires et d'intégration Rust

# ── Tous les tests aquaserveur (y compris ceux nécessitant MariaDB) ───────────
docker compose -f docker-compose.dev.yml --profile test run --rm rust-test

# ── Tests sans MariaDB (rapides, pas de DB requise) ───────────────────────────
docker compose -f docker-compose.dev.yml --profile test run --rm rust-test \
  cargo test --package aquaserveur

Les tests nécessitant MariaDB sont annotés #[ignore] et activés automatiquement par le service rust-test via --include-ignored.

Tests E2E (test-mqtt-e2e.sh)

Le script test-mqtt-e2e.sh publie de vrais messages MQTT sur le broker et vérifie les résultats directement en base de données — sans passer par le code Rust de test.

# Prérequis : docker-compose.dev.yml actif (backend + mosquitto + mariadb en cours)
cd code_refactorer/
bash test-mqtt-e2e.sh

Ce que le script couvre :

#	Scénario	Vérification
1	firstco — provisionnement boitier	boitier en DB + tables dynamiques créées
2	data-{id} — trame capteur normale	ligne insérée, aucune alerte parasite
3	maj_boitier_ACK-{id} status=ok	aucune alerte créée en DB
4	maj_boitier_ACK-{id} status=error	alerte type 15 avec value=error_detail
5	payload invalide	backend toujours running (pas de panic)

Le script utilise un boitier_id de test (9998) et nettoie automatiquement toutes les données créées via trap cleanup EXIT.

---

🐳 Infrastructure Docker

Fichiers Compose

Fichier	Rôle
docker-compose.base.yml	Infrastructure persistante (MariaDB + Mosquitto + WebDB)
docker-compose.dev.yml	Environnement dev complet (backend Rust + boîtier + profil test)

docker-compose.base.yml — Infrastructure de base

Service	Image	Ports	Rôle
mariadb	mariadb:10.6	3306:3306	Base de données principale
mosquitto	eclipse-mosquitto:2.0	1883:1883 / 9001:9001	Broker MQTT (TCP + WebSocket)
webdb	webdb/app:latest	${WEBDB_PORT:-22071}:22071	Interface web admin DB

# Démarrer l'infrastructure
docker compose -f docker-compose.base.yml up -d

# Arrêter
docker compose -f docker-compose.base.yml down

# Logs
docker compose -f docker-compose.base.yml logs -f mariadb
docker compose -f docker-compose.base.yml logs -f mosquitto

docker-compose.dev.yml — Environnement dev complet

Service	Build	Profil	Rôle
mariadbv4_dev	mariadb:10.11	défaut	Base de données dev
mosquitto	eclipse-mosquitto:2.0	défaut	Broker MQTT dev
backend-dev	aquaserveur/Dockerfile	défaut	Serveur Rust MQTT+HTTP
boitier-dev	aquaboitier-embedded/Dockerfile	défaut	Boîtier embedded (sim x86_64)
rust-test	rust:1.93	test	Tests d'intégration (one-shot)

# Démarrer l'env dev (hors profil test)
docker compose -f docker-compose.dev.yml up -d

# Arrêter
docker compose -f docker-compose.dev.yml down

# Rebuild + redémarrer le backend après modifs
docker compose -f docker-compose.dev.yml build backend-dev
docker compose -f docker-compose.dev.yml up -d --no-deps backend-dev

# Logs
docker compose -f docker-compose.dev.yml logs -f backend-dev
docker compose -f docker-compose.dev.yml logs -f boitier-dev

# Status
docker compose -f docker-compose.dev.yml ps

Dockerfiles

Fichier	Base	Stages	Cible
aquaserveur/Dockerfile	rust:latest → debian:bookworm-slim	2 (builder + runtime)	Linux x86_64 serveur
aquaboitier-embedded/Dockerfile	rust:alpine × 3	3 (tester + builder + runtime)	x86_64 dev/simulation
aquaboitier-embedded/Dockerfile.prod	rust:alpine → alpine:3.19	2 (cross-builder + runtime)	ARM64 (Opossum OPOS8MM)

# Build manuel backend serveur
docker build -f aquaserveur/Dockerfile -t acqua-backend-dev:latest .

# Build boîtier dev
docker build -f aquaboitier-embedded/Dockerfile -t acqua-boitier-dev:latest .

# Build boîtier PROD ARM64 (cross-compile depuis x86_64)
docker build -f aquaboitier-embedded/Dockerfile.prod -t acqua-boitier-prod:arm64 .

# Extraire le binaire ARM64 pour déploiement
docker create --name tmp-extract acqua-boitier-prod:arm64
docker cp tmp-extract:/usr/local/bin/aquaboitier-embedded ./aquaboitier-embedded-arm64
docker rm tmp-extract

Note Mosquitto : allow_anonymous true est configuré pour le dev/LAN.
En production, désactiver et configurer l'authentification par fichier password.

---

📊 État

Module	État
Backend serveur (aquaserveur)	✅ Opérationnel — 129 tests
Lib partagée (aquashared)	✅ Opérationnel — 4 tests
Backend embedded (aquaboitier-embedded)	🔧 En cours (simulation x86_64 active)

---

📦 Dépendances clés

# [workspace.dependencies]
tokio       = "1.42"   # Runtime async (features = ["full"])
rumqttc     = "0.24"   # Client MQTT
sqlx        = "0.8"    # MariaDB async (mysql + tls-rustls)
serde       = "1.0"    # Sérialisation JSON
serde_json  = "1.0"
anyhow      = "1.0"    # Error handling apps
thiserror   = "2.0"    # Error handling libs
tokio-serial = "5.4"   # UART serial (embedded)
reqwest     = "0.12"   # HTTP (alertes serveur)
tracing     = "0.1"    # Logging structuré
# dev
proptest    = "1.4"    # Tests property-based
mockall     = "0.13"   # Mocking

Contraintes d'architecture respectées :

• aquaboitier-embedded : zéro sqlx ni reqwest ✅
• aquashared : seulement serde + thiserror + serde_json ✅
• Profile release : opt-level="z", lto=true, strip=true ✅

---

🔧 Variables d'environnement

Template : .env.example (commité) | Secrets : .env (gitignored)

Variable	Défaut	Description
DATABASE_URL	(requis)	URL connexion MariaDB sqlx
MQTT_BROKER_URL	mqtt://localhost:1883	URL broker MQTT
SERVER_HTTP_PORT	8080	Port HTTP backend
RUST_LOG	warn	Niveau de log (trace/debug/info/warn/error)
WAIT_FOR_DB	yes	Attendre MariaDB au démarrage
DB_ROOT_PASSWORD	(requis)	Mot de passe root MariaDB

---

🤝 Agents BYAN

Agent	Rôle
@rustactect	Architecte Rust — design, patterns, revue
@rust-worker	Implémenteur Rust
@ddcoach	Tests — spécifications et validation
@docktor	Expert Docker — compose, Dockerfiles, CI
@bob	PM Agile — sprints, backlog

---

📚 Documentation

Document	Chemin
User Stories EPIC-003	Mon_projet/Retour agents/Bob/epics/EPIC-003-BACKEND-SERVEUR/
Sprint status	_byan-output/implementation-artifacts/sprint-status.yaml
Session clôture EPIC-003	_byan-output/SESSION-BOB-SPRINT4-EPIC003-CLOSE-2026-03-04.md

---

CI/CD et Deploiement

La documentation complete du pipeline CI/CD, des runners self-hosted et des procedures de deploiement est dans :

runners/README.md — Guide operationnel complet

Points cles :

Branche	Pipeline	Resultat
develop	CI (check/test/security/build) → deploy DEV auto	Serveur DEV mis a jour
prod	CI (check/test/security/build) → deploy PROD auto	Serveur PROD mis a jour
PR	CI uniquement (pas de deploy)	Validation avant merge

Apres chaque deploy PROD : merge automatique prod → main (tag de version) + redeploy DEV.

Pour deployer en production :

GitHub Actions → promote-to-prod.yml → Run workflow → Branch: develop

---

Version : 4.0.0 | License : Propriétaire Aquaprocess
Maintenu par : Thomas + Copilot BYAN agents