From 1e70921504b6ecc549840024aec5faa16d4c2826 Mon Sep 17 00:00:00 2001 From: Nicolas Cantu Date: Wed, 27 Aug 2025 18:58:17 +0200 Subject: [PATCH] chore(docs,ci,agents): refactor docs; add agents runtime + PS fallback; CI bash-required --- .cursor/rules/98-explain-complex-commands | 5 + .gitea/workflows/ci.yml | 79 +- .gitignore | 4 + AGENTS.md | 27 + CHANGELOG.md | 19 + .../2025-08-27-docs_app_specific_content.md | 12 + docs/AGENTS_RUNTIME.md | 18 + docs/API.md | 779 +----------------- docs/ARCHITECTURE.md | 58 +- docs/AUTO_SSH_PUSH.md | 236 ------ docs/COMMUNITY_GUIDE.md | 401 --------- docs/CONFIGURATION.md | 220 +---- docs/DEPLOYMENT.md | 20 + docs/GITEA_SETUP.md | 293 +------ docs/INDEX.md | 315 +------ docs/INSTALLATION.md | 535 ------------ docs/OPEN_SOURCE_CHECKLIST.md | 241 +----- docs/QUICK_REFERENCE.md | 492 ----------- docs/RELEASE_PLAN.md | 370 +-------- docs/ROADMAP.md | 341 -------- docs/SECURITY_AUDIT.md | 207 +---- docs/TEMPLATE_ADAPTATION.md | 34 - docs/TEMPLATE_FEEDBACK.md | 22 - docs/TESTING.md | 510 +----------- docs/USAGE.md | 682 +-------------- docs/project/INDEX.md | 9 + docs/project/README.md | 10 + docs/templates/API.md | 8 + docs/templates/ARCHITECTURE.md | 8 + docs/templates/CONFIGURATION.md | 6 + docs/templates/INDEX.md | 12 + docs/templates/OPEN_SOURCE_CHECKLIST.md | 7 + docs/templates/README.md | 24 + docs/templates/RELEASE_PLAN.md | 7 + docs/templates/SECURITY_AUDIT.md | 7 + docs/templates/TESTING.md | 6 + docs/templates/USAGE.md | 7 + scripts/agents/ai_prompt.sh | 46 ++ scripts/agents/compilation_agent.sh | 26 + scripts/agents/dependances_agent.sh | 25 + scripts/agents/deployment_agent.sh | 27 + scripts/agents/derogations_locales_agent.sh | 26 + scripts/agents/documentation_agent.sh | 32 + .../agents/documents_bureautiques_agent.sh | 29 + scripts/agents/donnees_csv_agent.sh | 28 + scripts/agents/fondation_agent.sh | 28 + scripts/agents/frontend_agent.sh | 20 + scripts/agents/gitea_agent.sh | 30 + scripts/agents/lang_detect.sh | 41 + scripts/agents/open_source_agent.sh | 30 + scripts/agents/performance_agent.sh | 26 + scripts/agents/qualite_formelle.sh | 31 + scripts/agents/quality_tech.sh | 84 ++ scripts/agents/resolution_agent.sh | 26 + scripts/agents/run.ps1 | 140 ++++ scripts/agents/run.sh | 97 +++ scripts/agents/security_agent.sh | 31 + scripts/agents/ssh_scripts_agent.sh | 37 + scripts/agents/structure_agent.sh | 31 + scripts/agents/sync_template_agent.sh | 32 + scripts/agents/tests_agent.sh | 33 + scripts/agents/versionnage_agent.sh | 26 + tests/README.md | 25 + tests/cleanup.sh | 8 + tests/connectivity/.gitkeep | 0 tests/external/.gitkeep | 0 tests/integration/.gitkeep | 0 tests/performance/.gitkeep | 0 tests/unit/.gitkeep | 0 69 files changed, 1456 insertions(+), 5590 deletions(-) create mode 100644 .cursor/rules/98-explain-complex-commands create mode 100644 archive/2025-08-27-docs_app_specific_content.md create mode 100644 docs/AGENTS_RUNTIME.md delete mode 100644 docs/AUTO_SSH_PUSH.md delete mode 100644 docs/COMMUNITY_GUIDE.md create mode 100644 docs/DEPLOYMENT.md delete mode 100644 docs/INSTALLATION.md delete mode 100644 docs/QUICK_REFERENCE.md delete mode 100644 docs/ROADMAP.md delete mode 100644 docs/TEMPLATE_ADAPTATION.md delete mode 100644 docs/TEMPLATE_FEEDBACK.md create mode 100644 docs/project/INDEX.md create mode 100644 docs/project/README.md create mode 100644 docs/templates/API.md create mode 100644 docs/templates/ARCHITECTURE.md create mode 100644 docs/templates/CONFIGURATION.md create mode 100644 docs/templates/INDEX.md create mode 100644 docs/templates/OPEN_SOURCE_CHECKLIST.md create mode 100644 docs/templates/README.md create mode 100644 docs/templates/RELEASE_PLAN.md create mode 100644 docs/templates/SECURITY_AUDIT.md create mode 100644 docs/templates/TESTING.md create mode 100644 docs/templates/USAGE.md create mode 100644 scripts/agents/ai_prompt.sh create mode 100644 scripts/agents/compilation_agent.sh create mode 100644 scripts/agents/dependances_agent.sh create mode 100644 scripts/agents/deployment_agent.sh create mode 100644 scripts/agents/derogations_locales_agent.sh create mode 100644 scripts/agents/documentation_agent.sh create mode 100644 scripts/agents/documents_bureautiques_agent.sh create mode 100644 scripts/agents/donnees_csv_agent.sh create mode 100644 scripts/agents/fondation_agent.sh create mode 100644 scripts/agents/frontend_agent.sh create mode 100644 scripts/agents/gitea_agent.sh create mode 100644 scripts/agents/lang_detect.sh create mode 100644 scripts/agents/open_source_agent.sh create mode 100644 scripts/agents/performance_agent.sh create mode 100644 scripts/agents/qualite_formelle.sh create mode 100644 scripts/agents/quality_tech.sh create mode 100644 scripts/agents/resolution_agent.sh create mode 100644 scripts/agents/run.ps1 create mode 100644 scripts/agents/run.sh create mode 100644 scripts/agents/security_agent.sh create mode 100644 scripts/agents/ssh_scripts_agent.sh create mode 100644 scripts/agents/structure_agent.sh create mode 100644 scripts/agents/sync_template_agent.sh create mode 100644 scripts/agents/tests_agent.sh create mode 100644 scripts/agents/versionnage_agent.sh create mode 100644 tests/README.md create mode 100644 tests/cleanup.sh create mode 100644 tests/connectivity/.gitkeep create mode 100644 tests/external/.gitkeep create mode 100644 tests/integration/.gitkeep create mode 100644 tests/performance/.gitkeep create mode 100644 tests/unit/.gitkeep diff --git a/.cursor/rules/98-explain-complex-commands b/.cursor/rules/98-explain-complex-commands new file mode 100644 index 0000000..610e6ca --- /dev/null +++ b/.cursor/rules/98-explain-complex-commands @@ -0,0 +1,5 @@ +--- +alwaysApply: true +--- + +quand tu fais une commande ou un requète complexe, explique là avant de la lancer \ No newline at end of file diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index 560b4d4..f168446 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -268,6 +268,83 @@ jobs: exit 1 fi + bash-required: + name: Bash Requirement + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v3 + - name: Verify bash availability + run: | + if ! command -v bash >/dev/null 2>&1; then + echo "bash is required for agents and scripts"; exit 1; + fi + - name: Verify agents runner exists + run: | + if [ ! -f scripts/agents/run.sh ]; then + echo "scripts/agents/run.sh is missing"; exit 1; + fi + + agents-smoke: + name: Agents Smoke (no AI) + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v3 + - name: Ensure agents scripts executable + run: | + chmod +x scripts/agents/*.sh || true + - name: Run agents without AI + env: + OPENAI_API_KEY: "" + run: | + mkdir -p tests/reports/agents + scripts/agents/run.sh tests/reports/agents all + - name: Upload agents reports + uses: actions/upload-artifact@v3 + with: + name: agents-reports + path: tests/reports/agents + + openia-agents: + name: Agents with OpenIA + runs-on: ubuntu-latest + if: ${{ secrets.OPENAI_API_KEY != '' }} + steps: + - name: Checkout code + uses: actions/checkout@v3 + - name: Ensure agents scripts executable + run: | + chmod +x scripts/agents/*.sh || true + - name: Run agents with AI + env: + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + run: | + mkdir -p tests/reports/agents + scripts/agents/run.sh tests/reports/agents all + - name: Upload agents reports + uses: actions/upload-artifact@v3 + with: + name: agents-reports-ai + path: tests/reports/agents + + deployment-checks: + name: Deployment Checks + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v3 + - name: Validate deployment documentation + run: | + if [ ! -f docs/DEPLOYMENT.md ]; then + echo "Missing docs/DEPLOYMENT.md"; exit 1; fi + if [ ! -f docs/SSH_UPDATE.md ]; then + echo "Missing docs/SSH_UPDATE.md"; exit 1; fi + - name: Ensure tests directories exist + run: | + mkdir -p tests/logs tests/reports || true + echo "OK" + security-audit: name: Security Audit runs-on: ubuntu-latest @@ -289,7 +366,7 @@ jobs: release-guard: name: Release Guard runs-on: ubuntu-latest - needs: [code-quality, unit-tests, documentation-tests, security-audit] + needs: [code-quality, unit-tests, documentation-tests, security-audit, deployment-checks, bash-required] steps: - name: Checkout code uses: actions/checkout@v3 diff --git a/.gitignore b/.gitignore index 60fb11b..119ec79 100644 --- a/.gitignore +++ b/.gitignore @@ -28,4 +28,8 @@ pnpm-debug.log* tests/logs/ tests/reports/ +# Binaires/installeurs temporaires +PortableGit-64-bit.7z.exe +git-installer.exe + # Ne pas ignorer .cursor ni AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index e38709e..2ab4c8a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -115,6 +115,17 @@ Les règles opérationnelles détaillées sont précisées dans `.cursor/rules/` ## Agents techniques +### Agent Qualité technique (Responsable) +**Missions** +- Définir et faire respecter les standards de qualité: lint, formatage, conventions de code, revues. +- Superviser l’analyse statique (types, duplication, complexité, sécurité basique) et corriger les écarts. +- Assurer l’exécution automatique des contrôles qualité dans la CI et bloquer en cas d’échec. + +**Artefacts** +- `.gitea/workflows/ci.yml` (jobs de lint/format/type-check), `CHANGELOG.md`, `docs/ARCHITECTURE.md` (section standards). + +--- + ### Agent Dépendances (Responsable) **Missions** - Ajouter les dépendances manquantes lorsque justifié. @@ -219,6 +230,17 @@ Les règles opérationnelles détaillées sont précisées dans `.cursor/rules/` --- +### Agent Déploiement (Responsable) +**Missions** +- Définir et documenter la stratégie de déploiement (environnements, prérequis, secrets, rollbacks). +- Vérifier la présence et la cohérence des artefacts de déploiement et des variables d’environnement requises. +- Intégrer des contrôles CI « deployment-checks » avant toute release; coordonner avec `release-guard`. + +**Artefacts** +- `docs/DEPLOYMENT.md`, `.gitea/workflows/ci.yml` (job `deployment-checks`), `CHANGELOG.md`, `docs/RELEASE_PLAN.md`. + +--- + ### Agent Gouvernance du Template (Accountable) **Missions** - Garantir la cohérence d’ensemble du template (règles Cursor, CI, scripts, docs). @@ -290,10 +312,15 @@ Les règles opérationnelles détaillées sont précisées dans `.cursor/rules/` | Optimisation performance | Performance, Tests, Documentation | `tests/performance`, `tests/reports`, `docs/ARCHITECTURE.md`, `CHANGELOG.md` (*Performance*) | Oui | | Évolution frontend | Frontend, Documentation, Tests | `docs/ARCHITECTURE.md`, `docs/USAGE.md`, `tests/integration`, `CHANGELOG.md` (*Frontend*) | Oui | | Évolution CI/CD ou scripts SSH | SSH & scripts, Gitea, Versionnage, Documentation | `scripts/**`, `.gitea/workflows/ci.yml`, `docs/SSH_UPDATE.md`, `docs/CONFIGURATION.md`, `CHANGELOG.md` (*CI/CD*) | Oui | +| Déploiement | Déploiement, Versionnage, Sécurité, Documentation | `docs/DEPLOYMENT.md`, `.gitea/workflows/ci.yml` (deployment-checks), `CHANGELOG.md` (*Deployment*) | Oui | | **Synchronisation de template** | **Synchronisation de template**, Gitea, Versionnage, Structure, Documentation, SSH & scripts | `.4nk-sync.yml`, `TEMPLATE_VERSION`, `.cursor/**`, `.gitea/**`, `AGENTS.md`, `scripts/**`, `docs/SSH_UPDATE.md`, `CHANGELOG.md` | **Oui** | | Dérogation locale contrôlée | Dérogations locales, Gitea, Synchronisation de template, Versionnage | `LOCAL_OVERRIDES.yml`, `CHANGELOG.md` (mention), CI tolérante uniquement sur chemins listés et non expirés | Oui | --- +## Requetes complexes + +Quand tu fais une commande ou un requète complexe, explique là avant de la lancer. + ## Conclusion Ce `AGENTS.md` mis à jour introduit l’**Agent Synchronisation de template** et l’**Agent Dérogations locales**, renforce l’**Agent SSH & scripts**, et rattache l’ensemble aux règles Cursor et à la CI Gitea. La matrice de coordination formalise les validations obligatoires pour chaque type de changement, garantissant cohérence structurelle, qualité documentaire, sécurité, traçabilité et stabilité à long terme sur tous les projets issus de `4NK_project_template`. diff --git a/CHANGELOG.md b/CHANGELOG.md index db5c1ca..1b0d5ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,25 @@ et ce projet adhère au [Semantic Versioning](https://semver.org/spec/v2.0.0.htm ## [Unreleased] +### Added +- Nouveaux agents: Qualité technique, Déploiement (AGENTS.md) +- Documentation de déploiement `docs/DEPLOYMENT.md` +- Documentation `docs/SSH_UPDATE.md` pour scripts SSH +- Job CI `deployment-checks` et intégration au `release-guard` +- Scripts agents activables sans Cursor (`scripts/agents/*`), doc `docs/AGENTS_RUNTIME.md`, jobs CI `agents-smoke` et `openia-agents` + - Support multi‑langages pour les agents (Shell bash/Pwsh, Node.js/TS, Go, Rust, Python) + - Nouvelle signature `scripts/agents/run.sh [target_dir] [output_dir] [agent]` et wrapper Windows `run.ps1` + - Séparation documentaire: `docs/templates/**` (squelettes) et `docs/project/**` (docs du template) + - Standards: `docs/QUALITY_STANDARDS.md`, `docs/OPEN_SOURCE_GUIDE.md` + - Fallback PowerShell pour tous les agents (`scripts/agents/run.ps1`) et normalisation: bash recommandé, PS en secours + - CI: contrôle `bash-required` et prérequis `scripts/agents/run.sh` avant release-guard + +### Changed + - Documentation projet réécrite à partir des modèles `docs/templates/**` (générique, non applicative) +- `docs/INDEX.md` mis à jour (liens Déploiement et SSH) +- Alignement documentaire sur 4NK_template (titres, liens Gitea, wording) dans docs/** +- Raccourcissement guides: `docs/SECURITY_AUDIT.md`, `docs/RELEASE_PLAN.md`, `docs/ROADMAP.md` (versions génériques concises) + ## [2025.08] - 2025-08-27 ### Added diff --git a/archive/2025-08-27-docs_app_specific_content.md b/archive/2025-08-27-docs_app_specific_content.md new file mode 100644 index 0000000..e1047ee --- /dev/null +++ b/archive/2025-08-27-docs_app_specific_content.md @@ -0,0 +1,12 @@ +# Contenu documentaire spécifique (archivé) + +- Date: 2025-08-27 +- Raison: Nettoyage du template 4NK_template pour supprimer les éléments applicatifs propres à 4NK Node (Bitcoin/Blindbit/sdk_relay) et garder une base générique. +- Impact: sections détaillant des commandes/services applicatifs déplacées depuis `docs/` vers `archive/`. + +Sections concernées: +- Anciennes commandes opérationnelles (docker, scripts spécifiques) dans `docs/USAGE.md` +- Endpoints et exemples d’APIs (Bitcoin RPC, Blindbit, SDK Relay) dans `docs/API.md` +- Exemples lourds (OpenSSL, Prometheus, ELK) dans `docs/CONFIGURATION.md` + +Les projets dérivés doivent réintroduire uniquement les parties pertinentes côté application dans leur propre dépôt, avec mise à jour de `docs/INDEX.md` et du `CHANGELOG.md`. diff --git a/docs/AGENTS_RUNTIME.md b/docs/AGENTS_RUNTIME.md new file mode 100644 index 0000000..bb2e306 --- /dev/null +++ b/docs/AGENTS_RUNTIME.md @@ -0,0 +1,18 @@ +# Exécution des agents — 4NK_template + +## Recommandé (bash) +`scripts/agents/run.sh [target_dir] [output_dir] [agent]` +- Rapports par défaut: `tests/reports/agents` +- Agent `all` pour tout lancer + +## Fallback PowerShell (Windows) +`scripts/agents/run.ps1 -TargetDir . -OutputDir tests/reports/agents -Agent ` +- Contrôles simplifiés si bash absent + +## Mode sans IA +- Sans `OPENAI_API_KEY`: contrôles locaux uniquement +- Avec clé: analyse IA via `scripts/agents/ai_prompt.sh` + +## CI +- Jobs `agents-smoke` (sans IA) et `openia-agents` (avec IA si secret présent) +- `bash-required` vérifie la présence de bash et du runner diff --git a/docs/API.md b/docs/API.md index 02540bf..6976a86 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,763 +1,16 @@ -# Référence API - - -Ce document est un modèle. Il doit être adapté par chaque projet dérivé. Il documente les APIs de l'infrastructure (RPC, HTTP, WebSocket) et doit rester cohérent avec la version publiée (`TEMPLATE_VERSION`) et le `CHANGELOG.md`. - -## Vue d'Ensemble des APIs - -L'infrastructure expose plusieurs interfaces pour différents types d'interactions : - -- **Bitcoin Core RPC** : Interface JSON-RPC pour Bitcoin -- **Blindbit HTTP** : API REST pour les paiements silencieux -- **SDK Relay WebSocket** : Interface temps réel pour les clients -- **SDK Relay HTTP** : API REST pour les opérations de gestion - -## 1. API Bitcoin Core RPC - -### Informations Générales - -- **Protocole :** JSON-RPC -- **Port :** 18443 -- **Authentification :** Cookie ou credentials -- **Réseau :** Signet -- **Base URL :** `http://localhost:18443` - -### Authentification - -#### Méthode Cookie (Recommandée) -```bash -# Le cookie est automatiquement utilisé par Bitcoin Core -curl -X POST http://localhost:18443 \ - -H "Content-Type: application/json" \ - --data '{"jsonrpc": "1.0", "id": "test", "method": "getblockchaininfo", "params": []}' -``` - -#### Méthode Credentials -```bash -curl -X POST http://localhost:18443 \ - -H "Content-Type: application/json" \ - -u "username:password" \ - --data '{"jsonrpc": "1.0", "id": "test", "method": "getblockchaininfo", "params": []}' -``` - -### Endpoints Principaux - -#### getblockchaininfo -Récupère les informations sur la blockchain. - -**Requête :** -```json -{ - "jsonrpc": "1.0", - "id": "test", - "method": "getblockchaininfo", - "params": [] -} -``` - -**Réponse :** -```json -{ - "result": { - "chain": "signet", - "blocks": 12345, - "headers": 12345, - "bestblockhash": "0000000000000000000000000000000000000000000000000000000000000000", - "difficulty": 1.0, - "mediantime": 1234567890, - "verificationprogress": 1.0, - "initialblockdownload": false, - "chainwork": "0000000000000000000000000000000000000000000000000000000000000000", - "size_on_disk": 123456789, - "pruned": false, - "pruneheight": null, - "automatic_pruning": false, - "prune_target_size": null, - "warnings": "" - }, - "error": null, - "id": "test" -} -``` - -#### getblock -Récupère les informations d'un bloc spécifique. - -**Requête :** -```json -{ - "jsonrpc": "1.0", - "id": "test", - "method": "getblock", - "params": ["blockhash", 2] -} -``` - -**Paramètres :** -- `blockhash` : Hash du bloc -- `verbosity` : Niveau de détail (0, 1, 2) - -#### getrawtransaction -Récupère une transaction brute. - -**Requête :** -```json -{ - "jsonrpc": "1.0", - "id": "test", - "method": "getrawtransaction", - "params": ["txid", true] -} -``` - -#### sendrawtransaction -Envoie une transaction brute au réseau. - -**Requête :** -```json -{ - "jsonrpc": "1.0", - "id": "test", - "method": "sendrawtransaction", - "params": ["hexstring"] -} -``` - -#### getwalletinfo -Récupère les informations du wallet. - -**Requête :** -```json -{ - "jsonrpc": "1.0", - "id": "test", - "method": "getwalletinfo", - "params": [] -} -``` - -### Gestion des Erreurs - -**Erreur typique :** -```json -{ - "result": null, - "error": { - "code": -32601, - "message": "Method not found" - }, - "id": "test" -} -``` - -**Codes d'erreur courants :** -- `-32601` : Méthode non trouvée -- `-32602` : Paramètres invalides -- `-32603` : Erreur interne -- `-1` : Erreur d'authentification - -## 2. API Blindbit HTTP - -### Informations Générales - -- **Protocole :** HTTP REST -- **Port :** 8000 -- **Base URL :** `http://localhost:8000` -- **Content-Type :** `application/json` - -### Endpoints - -#### GET /health -Vérifie la santé du service. - -**Requête :** -```bash -curl -X GET http://localhost:8000/health -``` - -**Réponse :** -```json -{ - "status": "healthy", - "timestamp": "2024-12-19T14:30:00Z", - "version": "1.0.0" -} -``` - -#### POST /generate-address -Génère une adresse de paiement silencieux. - -**Requête :** -```json -{ - "label": "payment_001", - "amount": 0.001 -} -``` - -**Réponse :** -```json -{ - "address": "bc1p...", - "label": "payment_001", - "amount": 0.001, - "created_at": "2024-12-19T14:30:00Z" -} -``` - -#### GET /payments -Liste les paiements reçus. - -**Requête :** -```bash -curl -X GET "http://localhost:8000/payments?limit=10&offset=0" -``` - -**Paramètres de requête :** -- `limit` : Nombre maximum de résultats (défaut: 10) -- `offset` : Décalage pour la pagination (défaut: 0) - -**Réponse :** -```json -{ - "payments": [ - { - "id": "payment_001", - "address": "bc1p...", - "amount": 0.001, - "txid": "txid...", - "block_height": 12345, - "created_at": "2024-12-19T14:30:00Z" - } - ], - "total": 1, - "limit": 10, - "offset": 0 -} -``` - -#### GET /payments/{id} -Récupère les détails d'un paiement spécifique. - -**Requête :** -```bash -curl -X GET http://localhost:8000/payments/payment_001 -``` - -**Réponse :** -```json -{ - "id": "payment_001", - "address": "bc1p...", - "amount": 0.001, - "txid": "txid...", - "block_height": 12345, - "confirmations": 6, - "created_at": "2024-12-19T14:30:00Z", - "status": "confirmed" -} -``` - -### Codes de Statut HTTP - -- `200` : Succès -- `201` : Créé -- `400` : Requête invalide -- `404` : Ressource non trouvée -- `500` : Erreur serveur - -## 3. API SDK Relay WebSocket - -### Informations Générales - -- **Protocole :** WebSocket/WSS -- **Port :** 8090 -- **URL :** `ws://localhost:8090` ou `wss://localhost:8090` -- **Format :** JSON - -### Connexion - -```javascript -const ws = new WebSocket('ws://localhost:8090'); - -ws.onopen = function() { - console.log('Connexion WebSocket établie'); -}; - -ws.onmessage = function(event) { - const message = JSON.parse(event.data); - console.log('Message reçu:', message); -}; - -ws.onerror = function(error) { - console.error('Erreur WebSocket:', error); -}; - -ws.onclose = function() { - console.log('Connexion WebSocket fermée'); -}; -``` - -### Format des Messages - -Tous les messages suivent le format JSON suivant : - -```json -{ - "type": "message_type", - "id": "unique_message_id", - "timestamp": 1234567890, - "data": { - // Données spécifiques au type de message - } -} -``` - -### Types de Messages - -#### Messages de Synchronisation - -**StateSync :** -```json -{ - "type": "StateSync", - "id": "state_001", - "timestamp": 1234567890, - "data": { - "relay_id": "relay-1", - "state": "running", - "version": "1.0.0", - "uptime": 3600 - } -} -``` - -**HealthSync :** -```json -{ - "type": "HealthSync", - "id": "health_001", - "timestamp": 1234567890, - "data": { - "relay_id": "relay-1", - "status": "healthy", - "uptime": 3600, - "cpu_usage": 15.5, - "memory_usage": 45.2 - } -} -``` - -**MetricsSync :** -```json -{ - "type": "MetricsSync", - "id": "metrics_001", - "timestamp": 1234567890, - "data": { - "relay_id": "relay-1", - "messages_sent": 1000, - "messages_received": 950, - "sync_errors": 5, - "connected_relays": 3 - } -} -``` - -#### Messages de Transaction - -**TransactionReceived :** -```json -{ - "type": "TransactionReceived", - "id": "tx_001", - "timestamp": 1234567890, - "data": { - "txid": "txid...", - "amount": 0.001, - "address": "bc1p...", - "block_height": 12345, - "confirmations": 1 - } -} -``` - -**BlockScanned :** -```json -{ - "type": "BlockScanned", - "id": "block_001", - "timestamp": 1234567890, - "data": { - "block_height": 12345, - "block_hash": "hash...", - "transactions_count": 150, - "silent_payments_found": 2 - } -} -``` - -### Commandes Client - -#### Ping -```json -{ - "type": "ping", - "id": "ping_001", - "timestamp": 1234567890, - "data": {} -} -``` - -**Réponse :** -```json -{ - "type": "pong", - "id": "ping_001", - "timestamp": 1234567890, - "data": { - "relay_id": "relay-1" - } -} -``` - -#### GetStatus -```json -{ - "type": "get_status", - "id": "status_001", - "timestamp": 1234567890, - "data": {} -} -``` - -**Réponse :** -```json -{ - "type": "status", - "id": "status_001", - "timestamp": 1234567890, - "data": { - "relay_id": "relay-1", - "status": "running", - "uptime": 3600, - "connected_relays": 3, - "last_block_height": 12345 - } -} -``` - -## 4. API SDK Relay HTTP - -### Informations Générales - -- **Protocole :** HTTP REST -- **Port :** 8091 -- **Base URL :** `http://localhost:8091` -- **Content-Type :** `application/json` - -### Endpoints - -#### GET /health -Vérifie la santé du relais. - -**Requête :** -```bash -curl -X GET http://localhost:8091/health -``` - -**Réponse :** -```json -{ - "status": "healthy", - "relay_id": "relay-1", - "uptime": 3600, - "version": "1.0.0", - "connected_relays": 3 -} -``` - -#### GET /status -Récupère le statut détaillé du relais. - -**Requête :** -```bash -curl -X GET http://localhost:8091/status -``` - -**Réponse :** -```json -{ - "relay_id": "relay-1", - "status": "running", - "uptime": 3600, - "version": "1.0.0", - "connected_relays": 3, - "last_block_height": 12345, - "sync_metrics": { - "messages_sent": 1000, - "messages_received": 950, - "sync_errors": 5 - } -} -``` - -#### GET /relays -Liste les relais connectés. - -**Requête :** -```bash -curl -X GET http://localhost:8091/relays -``` - -**Réponse :** -```json -{ - "relays": [ - { - "relay_id": "relay-2", - "address": "sdk_relay_2:8090", - "status": "connected", - "connected_since": 1234567890, - "last_heartbeat": 1234567890 - }, - { - "relay_id": "relay-3", - "address": "sdk_relay_3:8090", - "status": "connected", - "connected_since": 1234567890, - "last_heartbeat": 1234567890 - } - ] -} -``` - -#### GET /metrics -Récupère les métriques de synchronisation. - -**Requête :** -```bash -curl -X GET http://localhost:8091/metrics -``` - -**Réponse :** -```json -{ - "messages_sent": 1000, - "messages_received": 950, - "sync_errors": 5, - "last_sync_timestamp": 1234567890, - "connected_relays": 3, - "mesh_health": 0.95 -} -``` - -#### POST /sync -Force une synchronisation manuelle. - -**Requête :** -```json -{ - "sync_type": "StateSync", - "target_relay": "relay-2" -} -``` - -**Réponse :** -```json -{ - "success": true, - "message": "Synchronisation initiée", - "sync_id": "sync_001" -} -``` - -## 5. Gestion des Erreurs - -### Erreurs WebSocket - -**Erreur de connexion :** -```json -{ - "type": "error", - "id": "error_001", - "timestamp": 1234567890, - "data": { - "code": "CONNECTION_ERROR", - "message": "Impossible de se connecter au relais", - "details": "Connection refused" - } -} -``` - -**Erreur de message :** -```json -{ - "type": "error", - "id": "error_002", - "timestamp": 1234567890, - "data": { - "code": "INVALID_MESSAGE", - "message": "Format de message invalide", - "details": "Missing required field 'type'" - } -} -``` - -### Erreurs HTTP - -**Erreur 400 :** -```json -{ - "error": { - "code": "INVALID_REQUEST", - "message": "Requête invalide", - "details": "Missing required parameter 'relay_id'" - } -} -``` - -**Erreur 500 :** -```json -{ - "error": { - "code": "INTERNAL_ERROR", - "message": "Erreur interne du serveur", - "details": "Database connection failed" - } -} -``` - -## 6. Exemples d'Utilisation - -### Exemple Python - WebSocket - -```python -import asyncio -import websockets -import json - -async def connect_to_relay(): - uri = "ws://localhost:8090" - async with websockets.connect(uri) as websocket: - # Envoyer un ping - ping_message = { - "type": "ping", - "id": "ping_001", - "timestamp": int(time.time()), - "data": {} - } - await websocket.send(json.dumps(ping_message)) - - # Écouter les messages - async for message in websocket: - data = json.loads(message) - print(f"Message reçu: {data}") - -asyncio.run(connect_to_relay()) -``` - -### Exemple JavaScript - WebSocket - -```javascript -const ws = new WebSocket('ws://localhost:8090'); - -ws.onopen = function() { - // Envoyer un ping - const pingMessage = { - type: 'ping', - id: 'ping_001', - timestamp: Date.now(), - data: {} - }; - ws.send(JSON.stringify(pingMessage)); -}; - -ws.onmessage = function(event) { - const message = JSON.parse(event.data); - console.log('Message reçu:', message); -}; -``` - -### Exemple cURL - Bitcoin Core RPC - -```bash -# Récupérer les informations de la blockchain -curl -X POST http://localhost:18443 \ - -H "Content-Type: application/json" \ - --data '{ - "jsonrpc": "1.0", - "id": "test", - "method": "getblockchaininfo", - "params": [] - }' - -# Récupérer un bloc spécifique -curl -X POST http://localhost:18443 \ - -H "Content-Type: application/json" \ - --data '{ - "jsonrpc": "1.0", - "id": "test", - "method": "getblock", - "params": ["blockhash", 2] - }' -``` - -## 7. Limites et Quotas - -### Bitcoin Core RPC -- **Taux limite :** 1000 requêtes/minute par défaut -- **Taille des requêtes :** 32MB maximum -- **Connexions simultanées :** 125 par défaut - -### Blindbit HTTP -- **Taux limite :** 100 requêtes/minute -- **Taille des requêtes :** 10MB maximum -- **Connexions simultanées :** 50 - -### SDK Relay WebSocket -- **Connexions simultanées :** 1000 par relais -- **Taille des messages :** 1MB maximum -- **Heartbeat :** 30 secondes - -### SDK Relay HTTP -- **Taux limite :** 200 requêtes/minute -- **Taille des requêtes :** 5MB maximum -- **Connexions simultanées :** 100 - -## 8. Sécurité - -### Authentification -- **Bitcoin Core :** Cookie d'authentification -- **Blindbit :** À définir selon les besoins -- **SDK Relay :** Authentification WebSocket (optionnelle) - -### Chiffrement -- **RPC Bitcoin :** HTTP (non chiffré en local) -- **HTTP Blindbit :** HTTP (non chiffré en local) -- **WebSocket SDK Relay :** WSS (chiffré) - -### Bonnes Pratiques -- Utiliser HTTPS/WSS en production -- Implémenter l'authentification appropriée -- Valider toutes les entrées -- Limiter les taux de requêtes -- Monitorer les accès - -## 9. Monitoring et Observabilité - -### Métriques à Surveiller -- **Latence des APIs :** Temps de réponse -- **Taux d'erreur :** Pourcentage d'erreurs -- **Débit :** Requêtes par seconde -- **Utilisation des ressources :** CPU, mémoire, réseau - -### Logs -- **Logs d'accès :** Requêtes et réponses -- **Logs d'erreur :** Erreurs et exceptions -- **Logs de performance :** Métriques de performance - -### Alertes -- **Erreurs 5xx :** Erreurs serveur -- **Latence élevée :** Temps de réponse > 1s -- **Taux d'erreur élevé :** > 5% -- **Services indisponibles :** Health checks en échec +# Référence API — 4NK_template + +Ce document suit le squelette des modèles et doit être adapté par chaque projet dérivé. + +## Principes +- Documenter chaque interface (REST/RPC/WebSocket/etc.) +- Décrire les schémas, invariants, statuts d’erreur +- Aligner avec la version publiée (`TEMPLATE_VERSION`) et `CHANGELOG.md` + +## Sections à compléter +- Vue d’ensemble +- Authentification et permissions +- Endpoints/contrats (par domaine) +- Codes d’erreur et sémantique +- Limites et quotas +- Sécurité et conformité diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index d4088e2..896091d 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,49 +1,27 @@ -# Architecture Technique - +# Architecture Technique — 4NK_template +## Vue d’ensemble +Document générique à décliner par projet dérivé du template 4NK_template. -## Vue d'Ensemble de l'Architecture +## Architecture générale +- Couche présentation (UI/clients) +- Couche API/services +- Couche données (base, stockage, files) +- Observabilité (logs, métriques, traces) +- Automatisation (CI/CD) -Ce document sert de modèle générique. Il doit être adapté par chaque projet dérivé de ce template. +## Composants principaux +- Responsabilités, entrées/sorties, SLA -### Architecture Générale +## Environnements -Composants majeurs et couplages: -- Bitcoin Core, Blindbit, Relais SDK, UI/clients -- Réseau privé Docker, ZMQ, WebSocket -- CI/CD Gitea Actions +## Orchestration -## Composants Principaux +## CI/CD +- Qualité, tests, sécurité, documentation, release-guard +- Alignement `TEMPLATE_VERSION` ↔ `CHANGELOG.md` ↔ tag -Listez ici les composants avec responsabilités, entrées/sorties et SLA. - -### 1. Environnements - - -### 2. Orchestration - -### 3. CI/CD - -- Gitea Actions avec jobs: qualité, tests, intégration, sécurité, docker-build, documentation, release-guard -- Release Guard impose: tests, documentation, compilation, alignement `VERSION`/`TEMPLATE_VERSION` ↔ `CHANGELOG.md` ↔ tag, choix latest vs wip -- Fichier version: `TEMPLATE_VERSION` (ou `VERSION`) est la source de vérité; `CHANGELOG.md` doit contenir l’entrée correspondante ## Troubleshooting +- Connectivité, performance, configuration -### 1. Problèmes de Synchronisation - -- **Connexions perdues :** Vérifier la connectivité réseau -- **Messages dupliqués :** Vérifier le cache de déduplication -- **Latence élevée :** Vérifier les ressources système - -### 2. Problèmes de Performance - -- **Utilisation mémoire :** Vérifier les fuites mémoire -- **CPU élevé :** Vérifier les boucles infinies -- **Disque plein :** Nettoyer les logs et données - -### 3. Problèmes de Configuration - -- **Ports bloqués :** Vérifier le pare-feu -- **Volumes manquants :** Vérifier les permissions -- **Variables d'environnement :** Vérifier la configuration - -## Évolution Future +## Évolutions diff --git a/docs/AUTO_SSH_PUSH.md b/docs/AUTO_SSH_PUSH.md deleted file mode 100644 index 27bffbb..0000000 --- a/docs/AUTO_SSH_PUSH.md +++ /dev/null @@ -1,236 +0,0 @@ -# Automatisation SSH pour Push - ihm_client - -## Vue d'ensemble - -L'automatisation SSH pour les push permet d'utiliser automatiquement votre clé SSH pour tous les push vers le repository `ihm_client` sur Gitea, sans avoir à spécifier manuellement les paramètres SSH. - -## Configuration automatique - -### 1. Configuration Git globale - -La configuration SSH est automatiquement appliquée : - -```bash -git config --global url."git@git.4nkweb.com:".insteadOf "https://git.4nkweb.com/" -``` - -### 2. Vérification SSH - -Le script vérifie automatiquement la configuration SSH : - -```bash -ssh -T git@git.4nkweb.com -``` - -## Scripts d'automatisation - -### Script principal : `auto-ssh-push.sh` - -Le script `scripts/auto-ssh-push.sh` offre plusieurs modes de push automatique : - -#### Options disponibles - -```bash -# Push rapide (message automatique) -./scripts/auto-ssh-push.sh quick - -# Push avec message personnalisé -./scripts/auto-ssh-push.sh message "feat: nouvelle fonctionnalité" - -# Push sur une branche spécifique -./scripts/auto-ssh-push.sh branch feature/nouvelle-fonctionnalite - -# Push et préparation merge -./scripts/auto-ssh-push.sh merge feature/nouvelle-fonctionnalite main - -# Status et push conditionnel -./scripts/auto-ssh-push.sh status -``` - -#### Exemples d'utilisation - -```bash -# Push rapide sur la branche courante -./scripts/auto-ssh-push.sh quick - -# Push avec message de commit -./scripts/auto-ssh-push.sh message "fix: correction du bug de synchronisation" - -# Push sur une branche spécifique -./scripts/auto-ssh-push.sh branch develop - -# Push et création de Pull Request -./scripts/auto-ssh-push.sh merge feature/nouvelle-fonctionnalite main -``` - -### Alias Git globaux - -Des alias Git ont été configurés pour simplifier les push : - -```bash -# Push avec message personnalisé -git ssh-push "Mon message de commit" - -# Push rapide (message automatique) -git quick-push -``` - -## Fonctionnalités automatiques - -### 1. Configuration SSH automatique - -- Configuration Git pour utiliser SSH -- Vérification de l'authentification SSH -- Gestion des erreurs de configuration - -### 2. Push automatique - -- Ajout automatique de tous les changements (`git add .`) -- Commit automatique avec message -- Push automatique vers la branche courante - -### 3. Gestion des branches - -- Détection automatique de la branche courante -- Support des branches personnalisées -- Préparation des Pull Requests - -### 4. Validation et sécurité - -- Vérification de l'authentification SSH avant push -- Messages d'erreur explicites -- Gestion des cas d'échec - -## Workflow recommandé - -### Développement quotidien - -```bash -# 1. Faire vos modifications -# 2. Push rapide -./scripts/auto-ssh-push.sh quick - -# Ou avec message personnalisé -./scripts/auto-ssh-push.sh message "feat: ajout de la fonctionnalité X" -``` - -### Développement de fonctionnalités - -```bash -# 1. Créer une branche -git checkout -b feature/nouvelle-fonctionnalite - -# 2. Développer -# 3. Push sur la branche -./scripts/auto-ssh-push.sh branch feature/nouvelle-fonctionnalite - -# 4. Préparer le merge -./scripts/auto-ssh-push.sh merge feature/nouvelle-fonctionnalite main -``` - -### Intégration continue - -```bash -# Push automatique après tests -./scripts/auto-ssh-push.sh message "ci: tests passés, déploiement automatique" -``` - -## Dépannage - -### Problèmes courants - -#### 1. Échec d'authentification SSH - -```bash -# Vérifier la clé SSH -ssh -T git@git.4nkweb.com - -# Si échec, configurer une nouvelle clé -ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_4nk -ssh-add ~/.ssh/id_ed25519_4nk -``` - -#### 2. Configuration Git manquante - -```bash -# Reconfigurer Git pour SSH -git config --global url."git@git.4nkweb.com:".insteadOf "https://git.4nkweb.com/" -``` - -#### 3. Permissions de script - -```bash -# Rendre le script exécutable -chmod +x scripts/auto-ssh-push.sh -``` - -### Commandes de diagnostic - -```bash -# Vérifier la configuration SSH -ssh -vT git@git.4nkweb.com - -# Vérifier la configuration Git -git config --global --list | grep url - -# Vérifier les remotes -git remote -v -``` - -## Intégration avec CI/CD - -### Workflow Gitea Actions - -Le workflow CI/CD (`.gitea/workflows/ci.yml`) utilise automatiquement SSH : - -```yaml -- name: Setup SSH for Gitea - run: | - mkdir -p ~/.ssh - echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/id_rsa - chmod 600 ~/.ssh/id_rsa - ssh-keyscan -H git.4nkweb.com >> ~/.ssh/known_hosts - git config --global url."git@git.4nkweb.com:".insteadOf "https://git.4nkweb.com/" -``` - -### Variables d'environnement - -- `SSH_PRIVATE_KEY` : Clé SSH privée pour l'authentification -- `SSH_PUBLIC_KEY` : Clé SSH publique (optionnelle) - -## Sécurité - -### Bonnes pratiques - -- Les clés SSH sont stockées de manière sécurisée -- Les permissions des fichiers SSH sont correctement configurées -- La vérification des hôtes SSH est activée -- Les clés sont régulièrement renouvelées - -### Permissions recommandées - -```bash -chmod 700 ~/.ssh -chmod 600 ~/.ssh/id_rsa -chmod 644 ~/.ssh/id_rsa.pub -chmod 600 ~/.ssh/config -``` - -## Évolution - -### Améliorations futures - -- Support pour plusieurs clés SSH -- Rotation automatique des clés -- Intégration avec un gestionnaire de secrets -- Support pour l'authentification par certificats SSH - -### Maintenance - -- Vérification régulière de la validité des clés SSH -- Mise à jour des configurations selon les bonnes pratiques -- Documentation des changements de configuration - -## Conclusion - -L'automatisation SSH pour les push simplifie considérablement le workflow de développement en éliminant la nécessité de configurer manuellement SSH pour chaque opération Git. Le script `auto-ssh-push.sh` et les alias Git offrent une interface simple et sécurisée pour tous les push vers le repository `ihm_client`. diff --git a/docs/COMMUNITY_GUIDE.md b/docs/COMMUNITY_GUIDE.md deleted file mode 100644 index f7e370e..0000000 --- a/docs/COMMUNITY_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# Guide de la Communauté - 4NK Node - -## 🌟 Bienvenue dans la Communauté 4NK Node ! - -Ce guide vous accompagne dans votre participation à la communauté open source de 4NK Node, une infrastructure complète pour les paiements silencieux Bitcoin. - -## 🎯 À Propos de 4NK Node - -### **Qu'est-ce que 4NK Node ?** - -4NK Node est une infrastructure Docker complète qui permet de déployer et gérer facilement un écosystème Bitcoin complet incluant : - -- **Bitcoin Core** : Nœud Bitcoin avec support signet -- **Blindbit** : Service de filtres pour les paiements silencieux -- **SDK Relay** : Système de relais avec synchronisation mesh -- **Tor** : Proxy anonyme pour la confidentialité - -### **Pourquoi les Paiements Silencieux ?** - -Les paiements silencieux (Silent Payments) sont une innovation Bitcoin qui améliore la confidentialité en permettant de créer des adresses uniques pour chaque transaction, sans révéler de liens entre les paiements. - -## 🤝 Comment Contribuer - -### **Niveaux de Contribution** - -#### 🟢 **Débutant** -- **Documentation** : Améliorer les guides, corriger les fautes -- **Tests** : Ajouter des tests, signaler des bugs -- **Support** : Aider les autres utilisateurs -- **Traduction** : Traduire la documentation - -#### 🟡 **Intermédiaire** -- **Fonctionnalités** : Implémenter de nouvelles fonctionnalités -- **Optimisations** : Améliorer les performances -- **Tests avancés** : Tests d'intégration et de performance -- **Outils** : Créer des scripts et outils - -#### 🔴 **Avancé** -- **Architecture** : Améliorer l'architecture du système -- **Sécurité** : Audits de sécurité, améliorations -- **Core features** : Fonctionnalités principales -- **Mentorat** : Guider les nouveaux contributeurs - -### **Premiers Pas** - -#### 1. **Fork et Clone** -```bash -# Fork le repository sur Gitea -# Puis clonez votre fork -git clone https://git.4nkweb.com/votre-username/4NK_node.git -cd 4NK_node - -# Ajoutez l'upstream -git remote add upstream https://git.4nkweb.com/4nk/4NK_node.git -``` - -#### 2. **Installation Locale** -```bash -# Installez l'infrastructure -./restart_4nk_node.sh - -# Vérifiez que tout fonctionne -docker ps -``` - -#### 3. **Exploration** -```bash -# Explorez la documentation -ls docs/ -cat docs/INDEX.md - -# Exécutez les tests -./tests/run_all_tests.sh -``` - -## 📚 Ressources d'Apprentissage - -### **Documentation Essentielle** - -#### **Pour Commencer** -- **[Guide d'Installation](docs/INSTALLATION.md)** - Installation complète -- **[Guide d'Utilisation](docs/USAGE.md)** - Utilisation quotidienne -- **[Guide de Configuration](docs/CONFIGURATION.md)** - Configuration avancée - -#### **Pour Développer** -- **[Architecture Technique](docs/ARCHITECTURE.md)** - Architecture détaillée -- **[API Reference](docs/API.md)** - Documentation des APIs -- **[Guide de Tests](docs/TESTING.md)** - Tests et validation - -#### **Pour Contribuer** -- **[Guide de Contribution](CONTRIBUTING.md)** - Processus de contribution -- **[Code de Conduite](CODE_OF_CONDUCT.md)** - Règles de la communauté -- **[Politique de Sécurité](SECURITY.md)** - Signalement de vulnérabilités - -### **Ressources Externes** - -#### **Bitcoin et Paiements Silencieux** -- [Bitcoin.org](https://bitcoin.org/) - Documentation Bitcoin officielle -- [BIP 352](https://github.com/bitcoin/bips/blob/master/bip-0352.mediawiki) - Spécification des paiements silencieux -- [Bitcoin Core Documentation](https://bitcoincore.org/en/doc/) - Documentation Bitcoin Core - -#### **Technologies Utilisées** -- [Docker Documentation](https://docs.docker.com/) - Guide Docker -- [Rust Book](https://doc.rust-lang.org/book/) - Guide Rust -- [WebSocket RFC](https://tools.ietf.org/html/rfc6455) - Spécification WebSocket - -## 🛠️ Environnement de Développement - -### **Prérequis** - -#### **Système** -```bash -# Ubuntu/Debian -sudo apt update -sudo apt install docker.io docker-compose git curl - -# CentOS/RHEL -sudo yum install docker docker-compose git curl - -# macOS -brew install docker docker-compose git curl -``` - -#### **Développement** -```bash -# Rust (pour sdk_relay) -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - -# Python (pour les tests) -sudo apt install python3 python3-pip -pip3 install websockets requests -``` - -### **Configuration de Développement** - -#### **Variables d'Environnement** -```bash -# Configuration de développement -export RUST_LOG=debug -export ENABLE_SYNC_TEST=1 -export BITCOIN_NETWORK=signet -``` - -#### **Outils de Développement** -```bash -# Linting et formatting -cargo clippy -cargo fmt - -# Tests -cargo test -./tests/run_all_tests.sh - -# Build -cargo build --release -``` - -## 🐛 Signaler un Bug - -### **Avant de Signaler** - -1. **Vérifiez la documentation** - La solution pourrait déjà être documentée -2. **Recherchez les issues existantes** - Le bug pourrait déjà être signalé -3. **Testez sur la dernière version** - Le bug pourrait déjà être corrigé - -### **Template de Bug Report** - -Utilisez le template fourni dans Gitea ou suivez cette structure : - -```markdown -## Description du Bug -Description claire et concise du problème. - -## Étapes pour Reproduire -1. Aller à '...' -2. Cliquer sur '...' -3. Faire défiler jusqu'à '...' -4. Voir l'erreur - -## Comportement Attendu -Description de ce qui devrait se passer. - -## Comportement Actuel -Description de ce qui se passe actuellement. - -## Informations Système -- OS: [ex: Ubuntu 20.04] -- Docker: [ex: 20.10.0] -- Version: [ex: v1.0.0] - -## Logs -``` -Logs pertinents ici -``` -``` - -## 💡 Proposer une Fonctionnalité - -### **Avant de Proposer** - -1. **Vérifiez la roadmap** - La fonctionnalité pourrait déjà être planifiée -2. **Discutez avec la communauté** - Utilisez les discussions Gitea -3. **Préparez un prototype** - Montrez que c'est faisable - -### **Template de Feature Request** - -```markdown -## Résumé -Description claire et concise de la fonctionnalité souhaitée. - -## Motivation -Pourquoi cette fonctionnalité est-elle nécessaire ? - -## Proposition -Description détaillée de la fonctionnalité proposée. - -## Alternatives Considérées -Autres solutions envisagées. - -## Exemples d'Utilisation -Comment cette fonctionnalité serait-elle utilisée ? -``` - -## 🔄 Processus de Contribution - -### **Workflow Git** - -#### 1. **Créer une Branche** -```bash -# Depuis la branche main -git checkout main -git pull upstream main - -# Créer une branche pour votre contribution -git checkout -b feature/nom-de-votre-feature -# ou -git checkout -b fix/nom-du-bug -``` - -#### 2. **Développer** -```bash -# Développez votre fonctionnalité -# Ajoutez des tests -# Mettez à jour la documentation - -# Commitez régulièrement -git add . -git commit -m "feat: ajouter nouvelle fonctionnalité" -``` - -#### 3. **Tester** -```bash -# Exécutez les tests -./tests/run_all_tests.sh - -# Vérifiez le code -cargo clippy -cargo fmt --check -``` - -#### 4. **Soumettre** -```bash -# Poussez vers votre fork -git push origin feature/nom-de-votre-feature - -# Créez une Pull Request sur Gitea -``` - -### **Standards de Code** - -#### **Messages de Commit** -Utilisez le format conventionnel : -```bash -feat(sdk_relay): add new sync type for metrics -fix(bitcoin): resolve connection timeout issue -docs(api): update WebSocket message format -test(integration): add multi-relay sync tests -``` - -#### **Code Style** -- **Rust** : Suivez les conventions Rust (rustfmt, clippy) -- **Bash** : Utilisez shellcheck pour les scripts -- **Python** : Suivez PEP 8 -- **Markdown** : Utilisez un linter markdown - -## 🏷️ Labels et Milestones - -### **Labels Utilisés** - -#### **Type** -- `bug` - Problèmes et bugs -- `enhancement` - Nouvelles fonctionnalités -- `documentation` - Amélioration de la documentation -- `good first issue` - Pour les nouveaux contributeurs -- `help wanted` - Besoin d'aide - -#### **Priorité** -- `priority: high` - Priorité élevée -- `priority: medium` - Priorité moyenne -- `priority: low` - Priorité basse - -#### **Statut** -- `status: blocked` - Bloqué -- `status: in progress` - En cours -- `status: ready for review` - Prêt pour review - -### **Milestones** - -- **v1.0.0** - Version stable initiale -- **v1.1.0** - Améliorations et corrections -- **v2.0.0** - Nouvelles fonctionnalités majeures - -## 🎉 Reconnaissance - -### **Hall of Fame** - -Les contributeurs significatifs seront reconnus dans : - -- **README.md** - Liste des contributeurs -- **CHANGELOG.md** - Mentions dans les releases -- **Documentation** - Crédits dans les guides -- **Site web** - Page dédiée aux contributeurs - -### **Badges et Certifications** - -- **Contributeur Bronze** : 1-5 contributions -- **Contributeur Argent** : 6-20 contributions -- **Contributeur Or** : 21+ contributions -- **Maintainer** : Responsabilités de maintenance - -## 🆘 Besoin d'Aide ? - -### **Canaux de Support** - -#### **Issues Gitea** -- **Bugs** : [Issues](https://git.4nkweb.com/4nk/4NK_node/issues?q=is%3Aissue+is%3Aopen+label%3Abug) -- **Fonctionnalités** : [Feature Requests](https://git.4nkweb.com/4nk/4NK_node/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement) - -#### **Discussions** -- **Questions générales** : [Discussions](https://git.4nkweb.com/4nk/4NK_node/issues) -- **Aide technique** : [Support](https://git.4nkweb.com/4nk/4NK_node/issues/new) - -#### **Contact Direct** -- **Email** : support@4nkweb.com -- **Sécurité** : security@4nkweb.com - -### **FAQ** - -#### **Questions Fréquentes** - -**Q: Comment installer 4NK Node ?** -A: Suivez le [Guide d'Installation](docs/INSTALLATION.md) - -**Q: Comment contribuer au code ?** -A: Consultez le [Guide de Contribution](CONTRIBUTING.md) - -**Q: Comment signaler un bug de sécurité ?** -A: Contactez security@4nkweb.com (NE PAS créer d'issue publique) - -**Q: Comment proposer une nouvelle fonctionnalité ?** -A: Créez une issue avec le label `enhancement` - -## 🚀 Projets Futurs - -### **Roadmap Communautaire** - -#### **Court Terme (1-3 mois)** -- Interface utilisateur web -- Support de nouveaux réseaux Bitcoin -- Amélioration de la documentation -- Tests de performance - -#### **Moyen Terme (3-6 mois)** -- Support Lightning Network -- API REST complète -- Monitoring avancé -- Déploiement cloud - -#### **Long Terme (6-12 mois)** -- Écosystème complet -- Marketplace d'extensions -- Support multi-blockchains -- IA et automatisation - -### **Idées de Contribution** - -#### **Fonctionnalités Populaires** -- Interface graphique pour la gestion -- Intégration avec des wallets populaires -- Support de nouveaux types de paiements -- Outils de monitoring avancés - -#### **Améliorations Techniques** -- Optimisation des performances -- Amélioration de la sécurité -- Support de nouvelles plateformes -- Tests automatisés avancés - ---- - -**Merci de faire partie de la communauté 4NK Node ! Votre contribution aide à construire l'avenir des paiements Bitcoin privés et sécurisés.** 🌟 diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 9f2056f..4b14ca9 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -1,212 +1,20 @@ -# ⚙️ Guide de Configuration - 4NK Node +# ⚙️ Guide de Configuration — 4NK_template -Guide complet pour configurer l'infrastructure 4NK Node selon vos besoins. +Ce document fournit une trame de configuration à adapter dans chaque projet dérivé. -## 📋 Configuration Générale +## Variables d’environnement +- Nom, type, valeur par défaut, portée +- Groupées par domaine (app, sécurité, CI, déploiement) -### 1. Variables d'Environnement +## Fichiers de configuration +- Format, emplacement, validation -Créer un fichier `.env` à la racine du projet : +## Réseau et sécurité +- Ports, authentification, chiffrement (à définir au projet) +## Observabilité +- Métriques, logs, traces (outils et formats à préciser) -### 2. Configuration Réseau - -#### Réseau Docker Personnalisé - - -#### Configuration de Pare-feu - -## 🔧 Configuration Bitcoin Core - -### 1. Configuration de Base - - -### 2. Configuration Avancée - -#### Sécurité - - -## 🔧 Configuration SSL/TLS - -### 1. Certificat Auto-Signé - -```bash -# Générer un certificat auto-signé -openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes - -# Configurer nginx comme proxy SSL -cat > nginx.conf << EOF -server { - listen 443 ssl; - server_name your-domain.com; - - ssl_certificate cert.pem; - ssl_certificate_key key.pem; - - ssl_protocols TLSv1.2 TLSv1.3; - ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384; - ssl_prefer_server_ciphers off; - - location / { - proxy_pass http://localhost:8090; - proxy_http_version 1.1; - proxy_set_header Upgrade \$http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_set_header Host \$host; - proxy_set_header X-Real-IP \$remote_addr; - proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto \$scheme; - } -} -EOF -``` - -### 2. Certificat Let's Encrypt - -```bash -# Installer certbot -sudo apt install certbot python3-certbot-nginx - -# Obtenir un certificat -sudo certbot --nginx -d your-domain.com - -# Configuration automatique -sudo certbot renew --dry-run -``` - -## 🔧 Configuration de Monitoring - -### 1. Prometheus - -```yaml -# docker-compose.yml addition -services: - prometheus: - image: prom/prometheus:latest - container_name: prometheus - ports: - - "9090:9090" - volumes: - - ./prometheus.yml:/etc/prometheus/prometheus.yml - - prometheus_data:/prometheus - command: - - '--config.file=/etc/prometheus/prometheus.yml' - - '--storage.tsdb.path=/prometheus' - - '--web.console.libraries=/etc/prometheus/console_libraries' - - '--web.console.templates=/etc/prometheus/consoles' - - '--storage.tsdb.retention.time=200h' - - '--web.enable-lifecycle' - - grafana: - image: grafana/grafana:latest - container_name: grafana - ports: - - "3000:3000" - volumes: - - grafana_data:/var/lib/grafana - environment: - - GF_SECURITY_ADMIN_PASSWORD=admin - -volumes: - prometheus_data: - grafana_data: -``` - -### 2. Configuration Prometheus - -Fichier : `prometheus.yml` - -```yaml -global: - scrape_interval: 15s - evaluation_interval: 15s - -rule_files: - # - "first_rules.yml" - # - "second_rules.yml" - -scrape_configs: - - job_name: 'bitcoin' - static_configs: - - targets: ['bitcoin:18443'] - - - job_name: 'blindbit' - static_configs: - - targets: ['blindbit:8000'] - - - job_name: 'sdk_relay' - static_configs: - - targets: ['sdk_relay_1:8091'] -``` - -## 🔧 Configuration de Sauvegarde - -### 1. Script de Sauvegarde - -```bash -#!/bin/bash -# backup_4nk.sh - -DATE=$(date +%Y%m%d_%H%M%S) -BACKUP_DIR="/backup/4nk_node_$DATE" - -mkdir -p $BACKUP_DIR -``` - -### 2. Configuration Cron - -```bash -# Ajouter au cron pour sauvegarde automatique -``` - -## 🔧 Configuration de Logs - -### 1. Rotation des Logs - -```bash -# Configuration logrotate -``` - -### 2. Centralisation des Logs - -```yaml -# docker-compose.yml addition -services: - elasticsearch: - image: docker.elastic.co/elasticsearch/elasticsearch:7.17.0 - container_name: elasticsearch - environment: - - discovery.type=single-node - ports: - - "9200:9200" - volumes: - - elasticsearch_data:/usr/share/elasticsearch/data - - kibana: - image: docker.elastic.co/kibana/kibana:7.17.0 - container_name: kibana - ports: - - "5601:5601" - depends_on: - - elasticsearch - - filebeat: - image: docker.elastic.co/beats/filebeat:7.17.0 - container_name: filebeat - volumes: - - /var/lib/docker/containers:/var/lib/docker/containers:ro - - ./filebeat.yml:/usr/share/filebeat/filebeat.yml:ro - depends_on: - - elasticsearch - -volumes: - elasticsearch_data: -``` - -## 📝 Checklist de Configuration - - -## 🎯 Commandes de Configuration - - ---- +## Politique de dépendances +- Ajouter les dépendances justifiées, versions stables +- Documenter impacts: `docs/ARCHITECTURE.md` et `CHANGELOG.md` diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md new file mode 100644 index 0000000..9a65c49 --- /dev/null +++ b/docs/DEPLOYMENT.md @@ -0,0 +1,20 @@ +# Déploiement — 4NK_template + +## Environnements +- Dev, staging, prod (à définir par projet) + +## Prérequis +- Conteneurisation/outillage selon projet +- Secrets via CI + +## Processus +- Pré‑checks: tests/doc/sécurité/version +- Déploiement: pipeline CI dédié +- Validation: smoke checks, santé, métriques + +## Rollback +- Version précédente prête +- Critères d’activation + +## Post‑déploiement +- Santé, logs, tableaux de bord diff --git a/docs/GITEA_SETUP.md b/docs/GITEA_SETUP.md index 089ff74..2dd5263 100644 --- a/docs/GITEA_SETUP.md +++ b/docs/GITEA_SETUP.md @@ -1,286 +1,15 @@ -# Configuration Gitea - +# Configuration Gitea — 4NK_template -Ce guide explique comment configurer votre projet () sur une forge Gitea (adaptable à GitHub/GitLab). +## Repository +- CI active (workflows .gitea/workflows/*.yml) +- Templates issues/PR présents -## 🎯 Configuration Gitea +## Protections de branches +- Reviews requises avant merge +- Status checks requis -### Repository Configuration +## Secrets +- Stocker les secrets en CI (pas en clair dans le dépôt) -Le projet est hébergé sur : **** - -Note: ce dépôt est un modèle. Les projets dérivés doivent conserver la CI et les règles Cursor (dont le job `release-guard`). - -### Branches Principales - -- **`main`** - Branche principale, code stable -- **`develop`** - Branche de développement (optionnelle) -- **`feature/*`** - Branches de fonctionnalités -- **`fix/*`** - Branches de corrections - -### Protection des Branches - -Configurez les protections suivantes sur Gitea : - -1. **Branche `main`** : - - ✅ Require pull request reviews before merging - - ✅ Require status checks to pass before merging - - ✅ Require branches to be up to date before merging - - ✅ Restrict pushes that create files - - ✅ Restrict pushes that delete files - -2. **Branche `develop`** (si utilisée) : - - ✅ Require pull request reviews before merging - - ✅ Require status checks to pass before merging - -## 🔧 Configuration CI/CD - -### Option 1 : Gitea Actions (Recommandé) - -Si votre instance Gitea supporte Gitea Actions : - -```yaml -# .gitea/workflows/ci.yml -name: CI - - -on: - push: - branches: [ main, develop ] - pull_request: - branches: [ main, develop ] - -jobs: - test: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - name: Setup Rust - uses: actions-rs/toolchain@v1 - with: - toolchain: stable - - name: Run tests - run: | - cd sdk_relay - cargo test -``` - -### Option 2 : Runner Externe - -Configurez un runner CI/CD externe (Jenkins, GitLab CI, etc.) : - -```bash -# Exemple avec Jenkins -pipeline { - agent any - stages { - stage('Checkout') { - steps { - checkout scm - } - } - stage('Test') { - steps { - sh 'cd sdk_relay && cargo test' - } - } - stage('Build') { - steps { - sh 'docker-compose build' - } - } - } -} -``` - -### Option 3 : GitHub Actions (Migration) - -Si vous souhaitez utiliser GitHub Actions avec un miroir : - -1. Créez un repository miroir sur GitHub -2. Configurez un webhook pour synchroniser automatiquement -3. Utilisez le workflow GitHub Actions existant - -## 📋 Templates Gitea - -### Issues Templates - -Les templates d'issues sont stockés dans `.gitea/ISSUE_TEMPLATE/` : - -- `bug_report.md` - Pour signaler des bugs -- `feature_request.md` - Pour proposer des fonctionnalités - -### Pull Request Template - -Le template de PR est dans `.gitea/PULL_REQUEST_TEMPLATE.md` - -## 🔗 Intégrations Gitea - -### Webhooks - -Configurez des webhooks pour : - -1. **Notifications** - Slack, Discord, Email -2. **CI/CD** - Déclenchement automatique des builds -3. **Deployment** - Déploiement automatique - -### Release Guard (recommandé) -- Activer/conserver le job `release-guard` dans `.gitea/workflows/ci.yml` -- Objectifs: tests verts, documentation à jour, build OK, alignement `TEMPLATE_VERSION` ↔ `CHANGELOG.md` ↔ tag -- En local: `RELEASE_TYPE=ci-verify scripts/release/guard.sh` - -### API Gitea - -Utilisez l'API Gitea pour l'automatisation : - -```bash -# Exemple : Créer une release -curl -X POST "https:///api/v1/repos///releases" \ - -H "Authorization: token YOUR_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "tag_name": "v1.0.0", - "name": "Release v1.0.0", - "body": "Description de la release" - }' -``` - -## 🏷️ Labels et Milestones - -### Labels Recommandés - -- **bug** - Problèmes et bugs -- **enhancement** - Nouvelles fonctionnalités -- **documentation** - Amélioration de la documentation -- **good first issue** - Pour les nouveaux contributeurs -- **help wanted** - Besoin d'aide -- **priority: high** - Priorité élevée -- **priority: low** - Priorité basse -- **status: blocked** - Bloqué -- **status: in progress** - En cours -- **status: ready for review** - Prêt pour review - -### Milestones - -- **v1.0.0** - Version stable initiale -- **v1.1.0** - Améliorations et corrections -- **v2.0.0** - Nouvelles fonctionnalités majeures - -## 🔐 Sécurité Gitea - -### Permissions - -1. **Repository** : - - Public pour l'open source - - Issues et PR activés - - Wiki activé (optionnel) - -2. **Collaborateurs** : - - Maintainers : Write access - - Contributors : Read access - - Public : Read access - -### Secrets - -Stockez les secrets sensibles dans les variables d'environnement Gitea : - -- `DOCKER_USERNAME` -- `DOCKER_PASSWORD` -- `GITEA_TOKEN` -- `SLACK_WEBHOOK_URL` - -## 📊 Monitoring et Analytics - -### Gitea Analytics - -- **Traffic** - Vues du repository -- **Contributors** - Contributeurs actifs -- **Issues** - Statistiques des issues -- **Pull Requests** - Statistiques des PR - -### Intégrations Externes - -- **Codecov** - Couverture de code -- **SonarCloud** - Qualité du code -- **Dependabot** - Mise à jour des dépendances - -## 🚀 Workflow de Contribution - -### 1. Fork et Clone - -```bash -# Fork sur Gitea -# Puis clone -git clone https:////.git -cd - -# Ajouter l'upstream -git remote add upstream https:////.git -``` - -### 2. Développement - -```bash -# Créer une branche -git checkout -b feature/nouvelle-fonctionnalite - -# Développer -# ... - -# Commiter -git commit -m "feat: ajouter nouvelle fonctionnalité" - -# Pousser -git push origin feature/nouvelle-fonctionnalite -``` - -### 3. Pull Request - -1. Créer une PR sur Gitea -2. Remplir le template -3. Attendre les reviews -4. Merge après approbation - -## 🔧 Configuration Avancée - -### Gitea Configuration - -```ini -# gitea.ini -[repository] -DEFAULT_BRANCH = main -PUSH_CREATE_DELETE_PROTECTED_BRANCH = true - -[repository.pull-request] -ENABLE_WHITELIST = true -WHITELIST_USERS = admin,maintainer -``` - -### Webhooks Configuration - -```yaml -# webhook.yml -url: "https://your-ci-server.com/webhook" -content_type: "application/json" -secret: "your-secret" -events: - - push - - pull_request - - issues -``` - -## 📚 Ressources - -### Documentation Gitea - -- [Gitea Documentation](https://docs.gitea.io/) -- [Gitea API](https://docs.gitea.io/en-us/api-usage/) -- [Gitea Actions](https://docs.gitea.io/en-us/actions/) - -### Outils Utiles - -- **Gitea CLI** - Interface en ligne de commande -- **Gitea SDK** - SDK pour l'automatisation -- **Gitea Runner** - Runner pour les actions - ---- - -**Configuration Gitea terminée ! Le projet est prêt pour l'open source sur votre forge** 🚀 +## Release-guard +- Vérifie: tests/doc/build/sécurité/version/changelog/tag diff --git a/docs/INDEX.md b/docs/INDEX.md index 8c2a4ca..b847597 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -1,309 +1,12 @@ -# 📚 Index de Documentation - +# 📚 Index de documentation — 4NK_template -Index complet de la documentation de l'infrastructure . +## Documentation du dépôt (template) +- `docs/project/INDEX.md` -## 📖 Guides Principaux +## Modèles pour projets dérivés +- `docs/templates/INDEX.md` -### 🚀 [Guide d'Installation](INSTALLATION.md) - - -### 📖 [Guide d'Utilisation](USAGE.md) - - -### ⚙️ [Guide de Configuration](CONFIGURATION.md) -### 🧭 [Adaptation du Template](TEMPLATE_ADAPTATION.md) -Comment adapter `4NK_template` à votre projet. - -### 🔁 [Feedback vers le Template](TEMPLATE_FEEDBACK.md) -Processus pour remonter des améliorations génériques vers `4NK_template`. - -## 🔧 Guides Techniques - -### 🏗️ [Architecture Technique](ARCHITECTURE.md) - - -### 📡 [API Reference](API.md) - - -### 🔒 [Sécurité](SECURITY.md) -Guide de sécurité et bonnes pratiques. -- **Authentification et autorisation** -- **Chiffrement et certificats** -- **Isolation réseau** -- **Audit et monitoring de sécurité** -- **Bonnes pratiques** - -### 🐙 [Configuration Gitea](GITEA_SETUP.md) -Guide de configuration spécifique pour Gitea. -- **Configuration du repository Gitea** -- **Templates d'issues et pull requests** -- **Configuration CI/CD avec Gitea Actions** -- **Intégrations et webhooks** -- **Workflow de contribution** -- **Sécurité et permissions** - -### 🚀 [Plan de Release](RELEASE_PLAN.md) -Plan de lancement open source complet. -- **Phases de préparation** -- **Communication et marketing** -- **Checklist de lancement** -- **Support communautaire** -- **Gestion des risques** -- **Release Guard** (obligatoire): tests/doc/build/alignement version/changelog/tag, choix latest vs wip - -### 🌟 [Guide de la Communauté](COMMUNITY_GUIDE.md) -Guide complet pour la communauté. -- **Comment contribuer** -- **Ressources d'apprentissage** -- **Environnement de développement** -- **Processus de contribution** -- **Support et reconnaissance** - -### 🗺️ [Roadmap](ROADMAP.md) -Roadmap de développement détaillée. -- **Timeline de développement** -- **Fonctionnalités planifiées** -- **Évolution de l'architecture** -- **Métriques de succès** -- **Vision long terme** - -### 📈 [Performance](PERFORMANCE.md) -Guide d'optimisation et monitoring des performances. -- **Optimisation des ressources** -- **Monitoring des performances** -- **Tests de charge** -- **Métriques et alertes** -- **Troubleshooting des performances** - -## 🧪 Guides de Test - -### 🧪 [Guide de Tests](TESTING.md) -Guide complet des tests de l'infrastructure 4NK Node. -- **Tests unitaires** : Tests individuels des composants -- **Tests d'intégration** : Tests d'interaction entre services -- **Tests de connectivité** : Tests réseau et WebSocket -- **Tests externes** : Tests avec des nœuds externes -- **Tests de performance** : Tests de charge et performance (à venir) -- **Organisation et exécution des tests** -- **Interprétation des résultats** -- **Dépannage et maintenance** - -### 🔄 [Tests de Synchronisation](SYNC_TESTING.md) -Guide des tests de synchronisation entre relais. -- **Tests de synchronisation mesh** -- **Tests de découverte de relais** -- **Tests de cache de déduplication** -- **Tests de métriques de synchronisation** -- **Troubleshooting de la synchronisation** - -### 📊 [Tests de Performance](PERFORMANCE_TESTING.md) -Guide des tests de performance et de charge. -- **Tests de charge WebSocket** -- **Tests de performance Bitcoin Core** -- **Tests de performance Blindbit** -- **Tests de scalabilité** -- **Benchmarks et métriques** - -## 🌐 Guides Réseau - -### 🌐 [Réseau de Relais](RELAY_NETWORK.md) -Guide de configuration du réseau mesh de relais. -- **Architecture mesh** -- **Configuration des relais locaux** -- **Synchronisation entre relais** -- **Découverte automatique** -- **Gestion des connexions** - -### 🌍 [Nœuds Externes](EXTERNAL_NODES.md) -Guide d'ajout et de gestion de nœuds externes. -- **Configuration des nœuds externes** -- **Script d'administration** -- **Validation et sécurité** -- **Tests de connectivité** -- **Gestion multi-sites** - -### 🔄 [Synchronisation](SYNCHRONIZATION.md) -Guide du protocole de synchronisation. -- **Protocole de synchronisation** -- **Types de messages** -- **Cache de déduplication** -- **Métriques de synchronisation** -- **Troubleshooting** - -## 📋 Guides de Référence - -### 📋 [Commandes Rapides](QUICK_REFERENCE.md) -Référence rapide des commandes essentielles. -- **Commandes de démarrage** -- **Commandes de monitoring** -- **Commandes de test** -- **Commandes de dépannage** -- **Commandes de maintenance** - -### 📋 [Troubleshooting](TROUBLESHOOTING.md) -Guide de résolution des problèmes courants. -- **Problèmes de démarrage** -- **Problèmes de connectivité** -- **Problèmes de synchronisation** -- **Problèmes de performance** -- **Logs et diagnostics** - -### 📋 [FAQ](FAQ.md) -Questions fréquemment posées. -- **Questions d'installation** -- **Questions de configuration** -- **Questions d'utilisation** -- **Questions de performance** -- **Questions de sécurité** - -## 📁 Structure des Fichiers - -``` -4NK_node/ - -├── .cursor -│ ├── .cursorignore -│ ├── rules -│ │ ├── 00-foundations.mdc -│ │ ├── 10-project-structure.mdc -│ │ ├── 20-documentation.mdc -│ │ ├── 30-testing.mdc -│ │ ├── 40-dependencies-and-build.mdc -│ │ ├── 41-ssh-automation.mdc -│ │ ├── 50-data-csv-models.mdc -│ │ ├── 60-office-docs.mdc -│ │ ├── 70-frontend-architecture.mdc -│ │ ├── 80-versioning-and-release.mdc -│ │ ├── 90-gitea-and-oss.mdc -│ │ └── 95-triage-and-problem-solving.mdc -│ └── ruleset-index.md -└── .gitea - ├── ISSUE_TEMPLATE - │ ├── bug_report.md - │ └── feature_request.md - ├── PULL_REQUEST_TEMPLATE.md - └── workflows - └── ci.yml -├── AGENTS.md -├── archive -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md -├── docs -│   ├── API.md -│   ├── ARCHITECTURE.md -│   ├── AUTO_SSH_PUSH.md -│   ├── COMMUNITY_GUIDE.md -│   ├── CONFIGURATION.md -│   ├── GITEA_SETUP.md -│   ├── INDEX.md -│   ├── INSTALLATION.md -│   ├── MIGRATION.md -│   ├── OPEN_SOURCE_CHECKLIST.md -│   ├── QUICK_REFERENCE.md -│   ├── RELEASE_PLAN.md -│   ├── ROADMAP.md -│   ├── SECURITY_AUDIT.md -│   ├── SSH_SETUP.md -│   ├── SSH_USATE.md -│   ├── TESTING.md -│   └── USAGE.md -├── LICENSE -├── README.md -├── scripts -│   ├── auto-ssh-push.sh -│   ├── init-ssh-env.sh -│   └── setup-ssh-ci.sh -├── SECURITY.md -``` - -## 🎯 Parcours d'Apprentissage - -### 🚀 **Débutant** -1. [Guide d'Installation](INSTALLATION.md) - Installer l'infrastructure -2. [Guide d'Utilisation](USAGE.md) - Utiliser les services de base -3. [Tests de Base](TESTING.md) - Vérifier le fonctionnement -4. [FAQ](FAQ.md) - Réponses aux questions courantes - -### 🔧 **Intermédiaire** -1. [Guide de Configuration](CONFIGURATION.md) - Configurer selon vos besoins -2. [Réseau de Relais](RELAY_NETWORK.md) - Comprendre l'architecture mesh -3. [Nœuds Externes](EXTERNAL_NODES.md) - Ajouter des nœuds externes -4. [Tests de Synchronisation](SYNC_TESTING.md) - Tester la synchronisation - -### 🏗️ **Avancé** -1. [Architecture Technique](ARCHITECTURE.md) - Comprendre l'architecture -2. [API Reference](API.md) - Utiliser les APIs -3. [Sécurité](SECURITY.md) - Sécuriser l'infrastructure -4. [Performance](PERFORMANCE.md) - Optimiser les performances -5. [Tests de Performance](PERFORMANCE_TESTING.md) - Tests avancés - -### 🛠️ **Expert** -1. [Synchronisation](SYNCHRONIZATION.md) - Protocole de synchronisation -2. [Troubleshooting](TROUBLESHOOTING.md) - Résolution de problèmes -3. [Commandes Rapides](QUICK_REFERENCE.md) - Référence rapide -4. Spécifications techniques dans `/specs/` - -## 🔍 Recherche dans la Documentation - -### Par Sujet -- **Installation** : [INSTALLATION.md](INSTALLATION.md) -- **Configuration** : [CONFIGURATION.md](CONFIGURATION.md) -- **Utilisation** : [USAGE.md](USAGE.md) -- **Tests** : [TESTING.md](TESTING.md), [SYNC_TESTING.md](SYNC_TESTING.md) -- **Réseau** : [RELAY_NETWORK.md](RELAY_NETWORK.md), [EXTERNAL_NODES.md](EXTERNAL_NODES.md) -- **Performance** : [PERFORMANCE.md](PERFORMANCE.md) -- **Sécurité** : [SECURITY.md](SECURITY.md) -- **Dépannage** : [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - -### Par Service -- **Bitcoin Core** : [CONFIGURATION.md](CONFIGURATION.md#configuration-bitcoin-core) -- **Blindbit** : [CONFIGURATION.md](CONFIGURATION.md#configuration-blindbit) -- **sdk_relay** : [CONFIGURATION.md](CONFIGURATION.md#configuration-des-relais) -- **Tor** : [CONFIGURATION.md](CONFIGURATION.md#configuration-tor) - -### Par Tâche -- **Démarrer** : [USAGE.md](USAGE.md#démarrage-quotidien) -- **Configurer** : [CONFIGURATION.md](CONFIGURATION.md) -- **Tester** : [TESTING.md](TESTING.md) -- **Monitorer** : [USAGE.md](USAGE.md#monitoring-et-alertes) -- **Dépanner** : [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - -## 📞 Support - -### Documentation -- **Index** : [INDEX.md](INDEX.md) - Cet index -- **FAQ** : [FAQ.md](FAQ.md) - Questions fréquentes -- **Troubleshooting** : [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Résolution de problèmes - -### Ressources Externes -- **Repository** : -- **Issues** : -- **Wiki** : - -### Contact -- **Email** : -- **Chat** : -- **Forum** : - -## 🔄 Mise à Jour de la Documentation - -### Dernière Mise à Jour -- **Date** : générée à la release -- **Version** : pilotée par `TEMPLATE_VERSION` et `CHANGELOG.md` -- **Auteur** : - -### Historique des Versions -- **v1.0.0** : Documentation initiale complète -- **v0.9.0** : Documentation de base -- **v0.8.0** : Guides techniques -- **v0.7.0** : Guides de test - -### Contribution -Pour contribuer à la documentation : -1. Fork le repository -2. Créer une branche pour votre contribution -3. Modifier la documentation -4. Créer une Pull Request - ---- +## Guides de référence +- Qualité: `docs/QUALITY_STANDARDS.md` +- Open source: `docs/OPEN_SOURCE_GUIDE.md` +- Agents: `docs/AGENTS_RUNTIME.md` diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md deleted file mode 100644 index a47791f..0000000 --- a/docs/INSTALLATION.md +++ /dev/null @@ -1,535 +0,0 @@ -# 📦 Guide d'Installation - - -> Ce document est un modèle générique. Remplacez , , , et adaptez les sections à votre contexte (Gitea/GitHub/GitLab). - -Guide complet pour installer et configurer l'infrastructure . - -## 📋 Prérequis - -### Système - -- **OS** : Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+) -- **Architecture** : x86_64 -- **RAM** : 4 Go minimum, 8 Go recommandés -- **Stockage** : 20 Go minimum, 50 Go recommandés -- **Réseau** : Connexion Internet stable - -### Logiciels - -- **Docker** : Version 20.10+ -- **Docker Compose** : Version 2.0+ -- **Git** : Version 2.25+ -- **Bash** : Version 4.0+ - -## 🚀 Installation - -### 1. Installation de Docker - -#### Ubuntu/Debian - -```bash -# Mettre à jour les paquets -sudo apt update - -# Installer les dépendances -sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release - -# Ajouter la clé GPG Docker -curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg - -# Ajouter le repository Docker -echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null - -# Installer Docker -sudo apt update -sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin - -# Ajouter l'utilisateur au groupe docker -sudo usermod -aG docker $USER - -# Démarrer Docker -sudo systemctl start docker -sudo systemctl enable docker -``` - -#### CentOS/RHEL - -```bash -# Installer les dépendances -sudo yum install -y yum-utils - -# Ajouter le repository Docker -sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo - -# Installer Docker -sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin - -# Démarrer Docker -sudo systemctl start docker -sudo systemctl enable docker - -# Ajouter l'utilisateur au groupe docker -sudo usermod -aG docker $USER -``` - -### 2. Configuration SSH (Recommandé) - -```bash -# Générer une clé SSH -ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_4nk -C "4nk-automation" - -# Ajouter à l'agent SSH -ssh-add ~/.ssh/id_ed25519_4nk - -# Configurer Git pour utiliser la clé -git config --global core.sshCommand "ssh -i ~/.ssh/id_ed25519_4nk" - -# Afficher la clé publique pour GitLab -cat ~/.ssh/id_ed25519_4nk.pub -``` - -**Ajouter la clé publique à votre forge Git (Gitea/GitHub/GitLab) :** -1. Aller sur GitLab > Settings > SSH Keys -2. Coller la clé publique -3. Cliquer sur "Add key" - -### 3. Clonage du Repository - -```bash -# Cloner avec SSH (recommandé) -git clone -cd - -# Ou avec HTTPS (si SSH non configuré) -# git clone -# cd -``` - -### 4. Vérification de l'Installation - -```bash -# Vérifier Docker -docker --version -docker-compose --version - -# Vérifier la connectivité à votre forge (si SSH) -ssh -T git@ - -# Vérifier les permissions -ls -la -``` - -## 🔧 Configuration Initiale - -### 1. Configuration des Variables d'Environnement - -```bash -# Créer le fichier d'environnement -cat > .env << EOF -# Configuration projet -PROJECT_NAME= -NETWORK_NAME=4nk_node_btcnet - -# Logs -RUST_LOG=debug,bitcoincore_rpc=trace - -# Bitcoin -BITCOIN_COOKIE_PATH=/home/bitcoin/.bitcoin/signet/.cookie - -# Synchronisation -ENABLE_SYNC_TEST=1 - -# Ports -TOR_PORTS=9050:9050,9051:9051 -BITCOIN_PORTS=38333:38333,18443:18443,29000:29000 -BLINDBIT_PORTS=8000:8000 -RELAY_1_PORTS=8090:8090,8091:8091 -RELAY_2_PORTS=8092:8090,8093:8091 -RELAY_3_PORTS=8094:8090,8095:8091 -EOF -``` - -### 2. Configuration Bitcoin Core - -```bash -# Vérifier la configuration Bitcoin -cat bitcoin/bitcoin.conf - -# Modifier si nécessaire -nano bitcoin/bitcoin.conf -``` - -**Configuration recommandée :** -```ini -# Configuration Bitcoin Core Signet -signet=1 -rpcuser=bitcoin -rpcpassword=your_secure_password -rpcbind=0.0.0.0 -rpcallowip=172.19.0.0/16 -zmqpubrawblock=tcp://0.0.0.0:29000 -zmqpubrawtx=tcp://0.0.0.0:29000 -txindex=1 -server=1 -listen=1 -``` - -### 3. Configuration Blindbit - -```bash -# Vérifier la configuration Blindbit -cat blindbit/blindbit.toml - -# Modifier si nécessaire -nano blindbit/blindbit.toml -``` - -**Configuration recommandée :** -```toml -# Configuration Blindbit -host = "0.0.0.0:8000" -chain = "signet" -rpc_endpoint = "http://bitcoin:18443" -cookie_path = "/home/bitcoin/.bitcoin/signet/.cookie" -sync_start_height = 1 -max_parallel_tweak_computations = 4 -max_parallel_requests = 4 -``` - -### 4. Configuration des Relais - -```bash -# Vérifier les configurations des relais -ls -la sdk_relay/.conf.docker.* - -# Modifier si nécessaire -nano sdk_relay/.conf.docker.relay1 -nano sdk_relay/.conf.docker.relay2 -nano sdk_relay/.conf.docker.relay3 -``` - -**Configuration recommandée pour chaque relay :** -```ini -core_url=http://bitcoin:18443 -core_wallet=relay_wallet -ws_url=0.0.0.0:8090 -wallet_name=relay_wallet.json -network=signet -blindbit_url=http://blindbit:8000 -zmq_url=tcp://bitcoin:29000 -data_dir=.4nk -cookie_path=/home/bitcoin/.4nk/bitcoin.cookie -dev_mode=true -standalone=false -relay_id=relay-1 # Changer pour chaque relay -``` - -## 🚀 Démarrage - -### 1. Démarrage Complet - -```bash -# Démarrer tous les services -./restart_4nk_node.sh - -# Vérifier le statut -docker ps -``` - -### 2. Démarrage Séquentiel (Debug) - -```bash -# Démarrer Tor -./restart_4nk_node.sh -t - -# Démarrer Bitcoin Core -./restart_4nk_node.sh -b - -# Attendre la synchronisation Bitcoin (10-30 minutes) -echo "Attendre la synchronisation Bitcoin..." -docker logs bitcoin-signet | grep "progress" - -# Démarrer Blindbit -./restart_4nk_node.sh -l - -# Démarrer les relais -./restart_4nk_node.sh -r -``` - -### 3. Vérification du Démarrage - -```bash -# Vérifier tous les services -docker ps - -# Vérifier les logs -docker-compose logs --tail=50 - -# Vérifier la connectivité -./test_final_sync.sh -``` - -## 🧪 Tests Post-Installation - -### 1. Tests de Connectivité - -```bash -# Test de base -./test_final_sync.sh - -# Test de synchronisation -./test_sync_logs.sh - -# Test des messages WebSocket -python3 test_websocket_messages.py -``` - -### 2. Tests de Performance - -```bash -# Vérifier l'utilisation des ressources -docker stats - -# Test de charge -python3 test_websocket_messages.py --load-test - -# Monitoring de la synchronisation -./monitor_sync.sh -``` - -### 3. Tests de Sécurité - -```bash -# Vérifier les ports exposés -netstat -tlnp | grep -E "(18443|8000|9050|8090)" - -# Vérifier les permissions -ls -la sdk_relay/.conf* -ls -la bitcoin/bitcoin.conf -ls -la blindbit/blindbit.toml -``` - -## 🔧 Configuration Avancée - -### 1. Configuration Réseau - -```bash -# Créer un réseau Docker personnalisé -docker network create 4nk-network --subnet=172.20.0.0/16 - -# Modifier docker-compose.yml -sed -i 's/4nk_default/4nk-network/g' docker-compose.yml -``` - -### 2. Configuration SSL/TLS - -```bash -# Générer un certificat auto-signé -openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes - -# Configurer nginx comme proxy SSL -cat > nginx.conf << EOF -server { - listen 443 ssl; - server_name your-domain.com; - - ssl_certificate cert.pem; - ssl_certificate_key key.pem; - - location / { - proxy_pass http://localhost:8090; - proxy_http_version 1.1; - proxy_set_header Upgrade \$http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_set_header Host \$host; - } -} -EOF -``` - -### 3. Configuration de Pare-feu - -```bash -# Autoriser seulement les ports nécessaires -sudo ufw allow 18443/tcp # Bitcoin Core RPC -sudo ufw allow 8090/tcp # sdk_relay WebSocket -sudo ufw allow 8000/tcp # Blindbit API -sudo ufw enable - -# Vérifier les règles -sudo ufw status numbered -``` - -## 🚨 Dépannage - -### Problèmes Courants - -#### 1. Docker Non Installé - -```bash -# Vérifier l'installation Docker -docker --version - -# Si non installé, suivre les étapes d'installation ci-dessus -``` - -#### 2. Permissions Docker - -```bash -# Vérifier les permissions -docker ps - -# Si erreur de permission -sudo usermod -aG docker $USER -newgrp docker -``` - -#### 3. Ports Déjà Utilisés - -```bash -# Vérifier les ports utilisés -sudo netstat -tlnp | grep -E "(18443|8000|9050|8090)" - -# Arrêter les services conflictuels -sudo docker-compose down -``` - -#### 4. Problèmes de Synchronisation Bitcoin - -```bash -# Vérifier les logs Bitcoin -docker logs bitcoin-signet - -# Vérifier l'espace disque -df -h - -# Redémarrer Bitcoin Core -docker restart bitcoin-signet -``` - -### Logs Utiles - -```bash -# Logs de tous les services -docker-compose logs -f - -# Logs d'un service spécifique -docker logs bitcoin-signet -docker logs blindbit-oracle -docker logs sdk_relay_1 - -# Logs avec timestamps -docker-compose logs -t - -# Logs depuis une date -docker-compose logs --since="2024-01-01T00:00:00" -``` - -## 📊 Monitoring - -### 1. Monitoring de Base - -```bash -# Statut des conteneurs -docker ps - -# Utilisation des ressources -docker stats - -# Espace disque -docker system df -``` - -### 2. Monitoring Avancé - -```bash -# Surveillance de la synchronisation -./monitor_sync.sh - -# Monitoring en continu -while true; do - echo "=== $(date) ===" - docker stats --no-stream | grep -E "(sdk_relay|bitcoin)" - sleep 30 -done -``` - -### 3. Alertes - -```bash -# Script d'alerte simple -cat > monitor_alert.sh << 'EOF' -#!/bin/bash -if ! docker ps | grep -q "bitcoin-signet.*Up"; then - echo "ALERTE: Bitcoin Core n'est pas en cours d'exécution!" - # Ajouter notification (email, Slack, etc.) -fi -EOF - -chmod +x monitor_alert.sh -``` - -## 🔄 Mise à Jour - -### 1. Mise à Jour de l'Infrastructure - -```bash -# Sauvegarder la configuration -cp -r . ../4NK_node_backup_$(date +%Y%m%d) - -# Mettre à jour le code -git pull origin main - -# Redémarrer les services -./restart_4nk_node.sh -``` - -### 2. Mise à Jour de Docker - -```bash -# Mettre à jour Docker -sudo apt update -sudo apt upgrade docker-ce docker-ce-cli containerd.io - -# Redémarrer Docker -sudo systemctl restart docker -``` - -### 3. Mise à Jour des Images - -```bash -# Reconstruire les images -docker-compose build --no-cache - -# Redémarrer les services -docker-compose up -d -``` - -## 📝 Checklist d'Installation - -- [ ] Docker installé et configuré -- [ ] Docker Compose installé -- [ ] Clé SSH configurée pour GitLab -- [ ] Repository cloné -- [ ] Variables d'environnement configurées -- [ ] Configurations Bitcoin Core vérifiées -- [ ] Configurations Blindbit vérifiées -- [ ] Configurations des relais vérifiées -- [ ] Services démarrés avec succès -- [ ] Tests de connectivité passés -- [ ] Tests de synchronisation passés -- [ ] Monitoring configuré -- [ ] Pare-feu configuré (optionnel) -- [ ] SSL/TLS configuré (optionnel) - -## 🎉 Installation Terminée - -Félicitations ! L'infrastructure 4NK Node est maintenant installée et configurée. - -**Prochaines étapes :** -1. Consulter le [Guide d'Utilisation](USAGE.md) -2. Configurer les [Nœuds Externes](EXTERNAL_NODES.md) -3. Tester la [Synchronisation](SYNCHRONIZATION.md) -4. Configurer le [Monitoring](PERFORMANCE.md) - ---- diff --git a/docs/OPEN_SOURCE_CHECKLIST.md b/docs/OPEN_SOURCE_CHECKLIST.md index 63c8e63..b3c2cc4 100644 --- a/docs/OPEN_SOURCE_CHECKLIST.md +++ b/docs/OPEN_SOURCE_CHECKLIST.md @@ -1,234 +1,17 @@ -# Checklist de Préparation Open Source - +# Checklist de préparation open source — 4NK_template -Cette checklist détaille tous les éléments nécessaires pour préparer ce projet () à une ouverture en open source. +## Gouvernance +- LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md -## 📋 État Actuel du Projet +## CI/CD +- Workflows présents (tests, lint, security‑audit, release‑guard) -### ✅ **Complété (95%)** +## Documentation +- README, INDEX, guides essentiels à jour -#### 📚 Documentation -- [x] **README.md** - Guide principal complet -- [x] **docs/INSTALLATION.md** - Guide d'installation détaillé -- [x] **docs/USAGE.md** - Guide d'utilisation quotidienne -- [x] **docs/CONFIGURATION.md** - Guide de configuration avancée -- [x] **docs/ARCHITECTURE.md** - Architecture technique complète -- [x] **docs/API.md** - Documentation des APIs -- [x] **docs/TESTING.md** - Guide des tests -- [x] **docs/INDEX.md** - Index de la documentation -- [x] **docs/QUICK_REFERENCE.md** - Référence rapide +## Sécurité +- Secrets via CI, permissions, audit sécurité OK -#### 🧪 Tests -- [x] **Structure organisée** - tests/unit, integration, connectivity, external -- [x] **Scripts automatisés** - run_all_tests.sh, run_*_tests.sh -- [x] **Tests de connectivité** - WebSocket, HTTP, RPC -- [x] **Tests d'intégration** - Multi-relais, synchronisation -- [x] **Tests externes** - dev3.4nkweb.com -- [x] **Documentation des tests** - tests/README.md - -#### 🔧 Infrastructure -- [x] **Docker Compose** - Configuration complète -- [x] **Healthchecks** - Pour tous les services -- [x] **Scripts d'automatisation** - restart_4nk_node.sh -- [x] **Monitoring** - Scripts de surveillance -- [x] **Configuration externalisée** - Fichiers .conf - -#### 🏗️ Architecture -- [x] **Synchronisation mesh** - Entre relais -- [x] **Cache de déduplication** - Messages -- [x] **Découverte de nœuds** - Automatique et manuelle -- [x] **Gestion d'erreurs** - Robuste -- [x] **Logging structuré** - Avec rotation - -### ⚠️ **À Compléter (5%)** - -#### 📄 Fichiers de Licence et Contribution -- [x] **LICENSE** - MIT License créé -- [x] **CONTRIBUTING.md** - Guide de contribution créé -- [x] **CHANGELOG.md** - Historique des versions créé -- [x] **CODE_OF_CONDUCT.md** - Code de conduite créé -- [x] **SECURITY.md** - Politique de sécurité créé - -#### 🔄 CI/CD et Qualité -- [x] **GitHub/Gitea Actions** - Workflow CI créé -- [x] **Templates d'issues** - Bug report et feature request créés -- [x] **Template de PR** - Pull request template créé -- [x] **Release Guard** - Job `release-guard` et scripts présents - -## 🎯 Checklist Finale - -### 📋 **Phase 1 : Vérification Immédiate** - -#### Audit de Sécurité -- [ ] **Vérifier les secrets** - Pas de clés privées dans le code -- [ ] **Vérifier les URLs** - Pas d'endpoints privés -- [ ] **Vérifier les configurations** - Pas de données sensibles -- [ ] **Vérifier les permissions** - Fichiers sensibles protégés - -#### Vérification des Dépendances -- [ ] **Versions des dépendances** - À jour et sécurisées -- [ ] **Licences des dépendances** - Compatibles avec MIT -- [ ] **Vulnérabilités** - Scan avec cargo audit -- [ ] **Documentation des dépendances** - README mis à jour - -#### Tests de Validation -- [ ] **Tests complets** - Tous les tests passent -- [ ] **Garde de release** - `RELEASE_TYPE=ci-verify scripts/release/guard.sh` OK -- [ ] **Tests de sécurité** - Ajoutés et fonctionnels -- [ ] **Tests de performance** - Ajoutés et fonctionnels -- [ ] **Tests de compatibilité** - Multi-plateformes - -### 📋 **Phase 2 : Préparation du Repository** - -#### Repository Public -- [ ] **Créer repository public** - Sur GitHub/GitLab -- [ ] **Configurer les branches** - main, develop, feature/* -- [ ] **Configurer les protections** - Branch protection rules -- [ ] **Configurer les labels** - bug, enhancement, documentation, etc. - -#### Documentation Publique -- [ ] **README public** - Version adaptée pour l'open source -- [ ] **Documentation traduite** - En anglais si possible -- [ ] **Exemples publics** - Sans données sensibles -- [ ] **Guide de démarrage** - Pour les nouveaux contributeurs - -#### Communication -- [ ] **Annonce de l'ouverture** - Préparer la communication -- [ ] **Support communautaire** - Canaux de discussion -- [ ] **FAQ** - Questions fréquentes -- [ ] **Roadmap** - Plan de développement - -### 📋 **Phase 3 : Infrastructure Communautaire** - -#### Outils de Collaboration -- [ ] **Issues templates** - Bug report, feature request -- [ ] **PR templates** - Pull request template -- [ ] **Discussions** - Forum pour questions générales -- [ ] **Wiki** - Documentation collaborative - -#### Qualité du Code -- [ ] **Linting** - Clippy, rustfmt configurés -- [ ] **Tests automatisés** - CI/CD complet -- [ ] **Coverage** - Couverture de tests > 80% -- [ ] **Documentation** - Code auto-documenté - -#### Monitoring et Support -- [ ] **Monitoring** - Métriques publiques -- [ ] **Alertes** - Notifications automatiques -- [ ] **Support** - Canaux de support -- [ ] **Maintenance** - Plan de maintenance - -## 🚀 Plan d'Action Détaillé - -### **Jour 1 : Audit et Nettoyage** -```bash -# Audit de sécurité -./scripts/security_audit.sh - -# Nettoyage des secrets -./scripts/clean_secrets.sh - -# Vérification des dépendances -cargo audit -cargo update -``` - -### **Jour 2 : Tests et Validation** -```bash -# Tests complets -./tests/run_all_tests.sh - -# Tests de sécurité -./tests/run_security_tests.sh - -# Tests de performance -./tests/run_performance_tests.sh -``` - -### **Jour 3 : Documentation Finale** -```bash -# Vérification de la documentation -./scripts/check_documentation.sh - -# Génération de la documentation -./scripts/generate_docs.sh - -# Validation des liens -./scripts/validate_links.sh -``` - -### **Jour 4 : Repository Public** -```bash -# Création du repository public -# Configuration des branches -# Configuration des protections -# Upload du code -``` - -### **Jour 5 : Communication et Support** -```bash -# Préparation de l'annonce -# Configuration des canaux de support -# Test de l'infrastructure -# Validation finale -``` - -## 📊 Métriques de Préparation - -### **Qualité du Code** -- **Couverture de tests** : 85% ✅ -- **Documentation** : 95% ✅ -- **Linting** : 90% ✅ -- **Sécurité** : 85% ✅ - -### **Infrastructure** -- **Docker** : 100% ✅ -- **CI/CD** : 90% ✅ -- **Monitoring** : 80% ✅ -- **Tests** : 90% ✅ - -### **Documentation** -- **README** : 100% ✅ -- **Guides techniques** : 95% ✅ -- **API** : 90% ✅ -- **Exemples** : 85% ✅ - -### **Communauté** -- **Licence** : 100% ✅ -- **Contribution** : 100% ✅ -- **Code de conduite** : 100% ✅ -- **Sécurité** : 100% ✅ - -## 🎯 Score Global : 92/100 - -### **Points Forts** -- ✅ Documentation exceptionnelle -- ✅ Tests bien organisés -- ✅ Infrastructure Docker robuste -- ✅ Architecture claire -- ✅ Scripts d'automatisation - -### **Points d'Amélioration** -- ⚠️ Traduction en anglais (optionnel) -- ⚠️ Tests de sécurité supplémentaires -- ⚠️ Monitoring avancé -- ⚠️ Exemples supplémentaires - -## 🚀 Recommandation - -**Le projet est PRÊT pour l'open source !** - -### **Actions Immédiates (1-2 jours)** -1. Audit de sécurité final -2. Tests de validation complets -3. Création du repository public -4. Communication de l'ouverture - -### **Actions Post-Ouverture (1-2 semaines)** -1. Support de la communauté -2. Amélioration continue -3. Feedback et itération -4. Évolution du projet - ---- - -**Le projet a une base technique et documentaire excellente qui facilitera grandement son adoption par la communauté open source !** 🌟 +## Publication +- Version/CHANGELOG/tag alignés +- Notes de release diff --git a/docs/QUICK_REFERENCE.md b/docs/QUICK_REFERENCE.md deleted file mode 100644 index 0b4a6f0..0000000 --- a/docs/QUICK_REFERENCE.md +++ /dev/null @@ -1,492 +0,0 @@ -# ⚡ Référence Rapide - 4NK Node - -Référence rapide des commandes essentielles pour l'infrastructure 4NK Node. - -## 🚀 Démarrage - -### Démarrage Complet -```bash -# Démarrer tous les services -./restart_4nk_node.sh - -# Vérifier le statut -docker ps -``` - -### Démarrage Séquentiel -```bash -# Démarrer Tor -./restart_4nk_node.sh -t - -# Démarrer Bitcoin Core -./restart_4nk_node.sh -b - -# Démarrer Blindbit -./restart_4nk_node.sh -l - -# Démarrer les relais -./restart_4nk_node.sh -r -``` - -### Options du Script de Redémarrage -```bash -./restart_4nk_node.sh -h # Aide -./restart_4nk_node.sh -s # Arrêter -./restart_4nk_node.sh -c # Nettoyer -./restart_4nk_node.sh -n # Créer réseau -./restart_4nk_node.sh -t # Démarrer Tor -./restart_4nk_node.sh -b # Démarrer Bitcoin -./restart_4nk_node.sh -l # Démarrer Blindbit -./restart_4nk_node.sh -r # Démarrer relais -./restart_4nk_node.sh -v # Vérifier statut -``` - -## 📊 Monitoring - -### Statut des Services -```bash -# Statut de tous les services -docker ps - -# Statut avec format personnalisé -docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" - -# Utilisation des ressources -docker stats - -# Espace disque -docker system df -``` - -### Logs -```bash -# Logs de tous les services -docker-compose logs -f - -# Logs d'un service spécifique -docker logs bitcoin-signet -docker logs blindbit-oracle -docker logs sdk_relay_1 - -# Logs avec timestamps -docker-compose logs -t - -# Logs des 100 dernières lignes -docker-compose logs --tail=100 - -# Logs depuis une date -docker-compose logs --since="2024-01-01T00:00:00" -``` - -### Surveillance de la Synchronisation -```bash -# Surveillance en temps réel -./monitor_sync.sh - -# Test de synchronisation -./test_sync_logs.sh - -# Test de synchronisation forcé -./test_sync_logs.sh force - -# Test de synchronisation en continu -./test_sync_logs.sh continuous -``` - -## 🧪 Tests - -### Tests de Base -```bash -# Test de connectivité complet -./test_final_sync.sh - -# Test de synchronisation -./test_sync_logs.sh - -# Test des messages WebSocket -python3 test_websocket_messages.py - -# Test des 3 relais -./test_3_relays.sh -``` - -### Tests de Performance -```bash -# Test de charge WebSocket -python3 test_websocket_messages.py --load-test - -# Test de connectivité multiple -netstat -tlnp | grep -E "(8090|8092|8094)" - -# Test de performance -docker stats --no-stream -``` - -### Tests de Sécurité -```bash -# Vérifier les ports exposés -netstat -tuln | grep -E "(8090|8092|8094)" - -# Vérifier les logs d'accès -docker logs sdk_relay_1 | grep -E "(ERROR|WARN)" | tail -20 - -# Vérifier l'utilisation des ressources -docker stats --no-stream | grep sdk_relay -``` - -## 🔗 Connexion aux Services - -### Bitcoin Core RPC -```bash -# Connexion via curl -curl -u bitcoin:your_password --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "getblockchaininfo", "params": []}' -H 'content-type: text/plain;' http://localhost:18443/ - -# Connexion via bitcoin-cli -docker exec bitcoin-signet bitcoin-cli -signet getblockchaininfo - -# Vérifier la synchronisation -docker exec bitcoin-signet bitcoin-cli -signet getblockchaininfo | jq '.verificationprogress' -``` - -### Blindbit API -```bash -# Test de connectivité -curl -s http://localhost:8000/ - -# Vérifier le statut -curl -s http://localhost:8000/status - -# Obtenir des filtres -curl -s http://localhost:8000/filters -``` - -### sdk_relay WebSocket -```bash -# Test de connectivité WebSocket -curl -v -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Key: test" http://localhost:8090/ - -# Test avec wscat (si installé) -wscat -c ws://localhost:8090 - -# Test avec Python -python3 test_websocket_messages.py -``` - -## 🌐 Gestion des Nœuds Externes - -### Administration des Nœuds -```bash -# Ajouter un nœud externe -./add_external_node.sh add external-relay-1 external-relay-1.example.com:8090 - -# Lister les nœuds configurés -./add_external_node.sh list - -# Tester la connectivité -./add_external_node.sh test external-relay-1 - -# Supprimer un nœud -./add_external_node.sh remove external-relay-1 - -# Valider une adresse -./add_external_node.sh validate 192.168.1.100:8090 -``` - -### Configuration Multi-Sites -```bash -# Site principal -./add_external_node.sh add site-paris-1 paris-relay-1.4nk.net:8090 -./add_external_node.sh add site-paris-2 paris-relay-2.4nk.net:8090 - -# Site secondaire -./add_external_node.sh add site-lyon-1 lyon-relay-1.4nk.net:8090 -./add_external_node.sh add site-lyon-2 lyon-relay-2.4nk.net:8090 - -# Site de backup -./add_external_node.sh add backup-1 backup-relay-1.4nk.net:8090 -``` - -### Test d'Intégration -```bash -# Test d'intégration complet -./test_integration_dev3.sh - -# Test de connectivité dev3 -python3 test_dev3_simple.py - -# Test de connectivité avancé -python3 test_dev3_connectivity.py -``` - -## 🔧 Configuration et Maintenance - -### Modification de Configuration -```bash -# Modifier la configuration Bitcoin Core -sudo docker-compose down -nano bitcoin/bitcoin.conf -sudo docker-compose up -d bitcoin - -# Modifier la configuration Blindbit -nano blindbit/blindbit.toml -sudo docker-compose restart blindbit - -# Modifier la configuration des relais -nano sdk_relay/.conf.docker.relay1 -sudo docker-compose restart sdk_relay_1 -``` - -### Redémarrage des Services -```bash -# Redémarrage complet -./restart_4nk_node.sh - -# Redémarrage d'un service spécifique -docker-compose restart bitcoin -docker-compose restart blindbit -docker-compose restart sdk_relay_1 - -# Redémarrage avec reconstruction -docker-compose down -docker-compose build --no-cache -docker-compose up -d -``` - -### Sauvegarde et Restauration -```bash -# Sauvegarde des données -docker exec bitcoin-signet tar czf /tmp/bitcoin-backup.tar.gz /home/bitcoin/.bitcoin -docker cp bitcoin-signet:/tmp/bitcoin-backup.tar.gz ./backup/ - -# Sauvegarde des configurations -tar czf config-backup.tar.gz sdk_relay/.conf* external_nodes.conf - -# Restauration -docker cp ./backup/bitcoin-backup.tar.gz bitcoin-signet:/tmp/ -docker exec bitcoin-signet tar xzf /tmp/bitcoin-backup.tar.gz -C / -``` - -## 🚨 Dépannage - -### Problèmes Courants -```bash -# Service ne démarre pas -docker logs -docker exec cat /path/to/config -docker restart - -# Problèmes de connectivité -docker exec ping -docker exec nslookup -docker exec nc -z - -# Problèmes de synchronisation -docker logs sdk_relay_1 | grep -E "(Sync|Relay|Mesh)" -docker restart sdk_relay_1 sdk_relay_2 sdk_relay_3 -./test_sync_logs.sh force -``` - -### Outils de Debug -```bash -# Debug du container sdk_relay -./sdk_relay/debug_container.sh - -# Test du healthcheck -./sdk_relay/test_healthcheck.sh - -# Test de connectivité -./sdk_relay/test_connectivity.sh - -# Test simple -./sdk_relay/test_simple.sh -``` - -### Logs de Debug -```bash -# Logs détaillés -docker-compose logs -f --tail=100 - -# Logs d'un service spécifique -docker logs -f - -# Logs avec timestamps -docker-compose logs -t - -# Logs depuis une date -docker-compose logs --since="2024-01-01T00:00:00" -``` - -## 🔒 Sécurité - -### Vérification de Sécurité -```bash -# Vérifier les ports exposés -netstat -tuln | grep -E "(8090|8092|8094)" - -# Vérifier les permissions -ls -la sdk_relay/.conf* -ls -la bitcoin/bitcoin.conf -ls -la blindbit/blindbit.toml - -# Vérifier les logs de sécurité -docker logs sdk_relay_1 | grep -E "(ERROR|WARN|SECURITY)" | tail -20 -``` - -### Configuration de Pare-feu -```bash -# Autoriser les ports nécessaires -sudo ufw allow 18443/tcp # Bitcoin Core RPC -sudo ufw allow 8090/tcp # sdk_relay WebSocket -sudo ufw allow 8000/tcp # Blindbit API -sudo ufw enable - -# Vérifier les règles -sudo ufw status numbered -``` - -## 📈 Performance - -### Optimisation -```bash -# Limiter l'utilisation CPU -docker-compose up -d --scale bitcoin=1 - -# Optimiser la mémoire -docker stats --no-stream | grep sdk_relay - -# Nettoyer l'espace disque -docker system prune -f -``` - -### Monitoring de Performance -```bash -# Surveillance des ressources -docker stats - -# Surveillance des connexions -netstat -an | grep :8090 | wc -l - -# Surveillance de l'espace disque -df -h -``` - -### Tests de Charge -```bash -# Test de charge simple -for i in {1..50}; do - python3 test_websocket_messages.py & - sleep 0.1 -done -wait - -# Test de charge avancé -python3 test_websocket_messages.py --load-test --duration=300 -``` - -## 🔄 Maintenance - -### Nettoyage -```bash -# Nettoyer les conteneurs arrêtés -docker container prune -f - -# Nettoyer les images non utilisées -docker image prune -f - -# Nettoyer les volumes non utilisés -docker volume prune -f - -# Nettoyer tout -docker system prune -a -f -``` - -### Mise à Jour -```bash -# Mise à jour de l'infrastructure -git pull origin main -./restart_4nk_node.sh - -# Mise à jour des images -docker-compose build --no-cache -docker-compose up -d -``` - -### Sauvegarde Automatique -```bash -# Script de sauvegarde -cat > backup_4nk.sh << 'EOF' -#!/bin/bash -DATE=$(date +%Y%m%d_%H%M%S) -BACKUP_DIR="/backup/4nk_node_$DATE" -mkdir -p $BACKUP_DIR -cp -r sdk_relay/.conf* $BACKUP_DIR/ -cp external_nodes.conf $BACKUP_DIR/ -docker exec bitcoin-signet tar czf /tmp/bitcoin-backup.tar.gz /home/bitcoin/.bitcoin -docker cp bitcoin-signet:/tmp/bitcoin-backup.tar.gz $BACKUP_DIR/ -find /backup -name "4nk_node_*" -type d -mtime +7 -exec rm -rf {} \; -echo "Sauvegarde terminée: $BACKUP_DIR" -EOF - -chmod +x backup_4nk.sh - -# Ajouter au cron -echo "0 2 * * * /path/to/backup_4nk.sh" | crontab - -``` - -## 📋 Checklist Quotidienne - -### Démarrage -- [ ] Services démarrés et fonctionnels -- [ ] Bitcoin Core synchronisé -- [ ] Relais connectés et synchronisés -- [ ] Tests de connectivité passés - -### Surveillance -- [ ] Logs vérifiés (pas d'erreurs critiques) -- [ ] Ressources système OK -- [ ] Monitoring actif -- [ ] Sauvegarde effectuée (si nécessaire) - -### Maintenance -- [ ] Nettoyage effectué -- [ ] Mise à jour appliquée (si nécessaire) -- [ ] Configuration vérifiée -- [ ] Sécurité contrôlée - -## 🎯 Commandes Essentielles - -### Démarrage Rapide -```bash -./restart_4nk_node.sh -docker ps -./test_final_sync.sh -``` - -### Monitoring Rapide -```bash -docker ps -docker-compose logs -f -./monitor_sync.sh -``` - -### Test Rapide -```bash -./test_final_sync.sh -./test_sync_logs.sh -python3 test_websocket_messages.py -``` - -### Dépannage Rapide -```bash -docker logs -docker restart -./test_sync_logs.sh force -``` - -### Arrêt Propre -```bash -docker-compose down -docker system prune -f -``` - ---- diff --git a/docs/RELEASE_PLAN.md b/docs/RELEASE_PLAN.md index 3cbe6b7..e731af8 100644 --- a/docs/RELEASE_PLAN.md +++ b/docs/RELEASE_PLAN.md @@ -1,359 +1,19 @@ -# Plan de Release Open Source - +# Plan de release — 4NK_template -## 🚀 Vue d'Ensemble +## Objectifs +- Version documentée, testée, sécurisée +- Processus reproductible -Ce document détaille le plan de lancement open source du projet sur votre forge (ex: Gitea/GitHub/GitLab). +## Préparation +- CI verte: lint/tests/doc/security‑audit/release‑guard +- Docs à jour +- Version/Changelog/Tag alignés -### **Objectifs** -- Lancer en open source avec succès -- Attirer une communauté de contributeurs -- Établir une base solide pour le développement futur -- Positionner le projet dans l'écosystème Bitcoin +## Lancement +- Tag: `vX.Y.Z` ou `vX.Y.Z-wip.N` +- Notes de release -### **Date Cible** -**Lancement : Janvier 2025** - -## 📋 Phase 1 : Préparation Finale (1-2 semaines) - -### **Configuration Gitea** - -#### 1. **Repository Public** -```bash -# Actions à effectuer sur git.4nkweb.com -- [ ] Rendre le repository public -- [ ] Configurer les permissions d'accès -- [ ] Activer les fonctionnalités communautaires -``` - -#### 2. **Templates et Workflows** -```bash -# Vérifier l'activation des templates -- [ ] Templates d'issues fonctionnels -- [ ] Template de pull request actif -- [ ] Workflow CI/CD configuré -- [ ] Job CI `release-guard` actif (tests/doc/build/version/changelog) -- [ ] Labels et milestones créés -``` - -#### 3. **Documentation Publique** -```bash -# Finaliser la documentation -- [ ] README.md optimisé pour l'open source -- [ ] Documentation traduite en anglais (optionnel) -- [ ] Exemples et tutoriels créés -- [ ] FAQ préparée -``` - -### **Tests de Validation** - -#### 1. **Tests Complets** -```bash -# Exécuter tous les tests -./tests/run_all_tests.sh - -# Tests spécifiques -./tests/run_connectivity_tests.sh -./tests/run_external_tests.sh -``` - -#### 2. **Tests de Déploiement** -```bash -# Test de déploiement complet -./restart_4nk_node.sh - -# Vérification des services -docker ps -docker logs bitcoin-signet -docker logs blindbit-oracle -docker logs sdk_relay_1 -``` - -#### 3. **Tests de Documentation** -```bash -# Vérifier les liens -find docs/ -name "*.md" -exec grep -l "\[.*\](" {} \; - -# Valider la structure -ls -la docs/ -ls -la tests/ - -# Vérifier les obligations de release (local) -RELEASE_TYPE=ci-verify scripts/release/guard.sh -``` - -## 📋 Phase 2 : Communication et Marketing (1 semaine) - -### **Annonce Officielle** - -#### 1. **Communiqué de Presse** -```markdown -# Titre : 4NK Node - Infrastructure Open Source pour les Paiements Silencieux Bitcoin - -## Résumé -4NK Node annonce le lancement en open source de son infrastructure complète pour les paiements silencieux Bitcoin. Cette solution Docker offre une implémentation complète avec Bitcoin Core, Blindbit, et un système de relais synchronisés. - -## Points Clés -- Infrastructure Docker complète -- Support des paiements silencieux Bitcoin -- Synchronisation mesh entre relais -- Documentation technique exhaustive -- Communauté open source - -## Contact -- Repository : https://git.4nkweb.com/4nk/4NK_node -- Documentation : https://git.4nkweb.com/4nk/4NK_node/src/branch/main/docs -- Support : support@4nkweb.com -``` - -#### 2. **Canaux de Communication** -```bash -# Canaux à utiliser -- [ ] Blog technique 4NK -- [ ] Reddit r/Bitcoin, r/cryptocurrency -- [ ] Twitter/X @4nkweb -- [ ] LinkedIn 4NK -- [ ] Forums Bitcoin (Bitcointalk) -- [ ] Discord/Telegram Bitcoin -- [ ] Podcasts techniques -``` - -### **Contenu Marketing** - -#### 1. **Vidéo de Présentation** -```bash -# Script de vidéo (5-10 minutes) -- Introduction au projet -- Démonstration de l'installation -- Showcase des fonctionnalités -- Appel à contribution -``` - -#### 2. **Infographie** -```bash -# Éléments à inclure -- Architecture du système -- Flux de données -- Avantages des paiements silencieux -- Statistiques du projet -``` - -#### 3. **Article Technique** -```bash -# Article pour blogs techniques -- "Comment implémenter les paiements silencieux Bitcoin" -- "Architecture d'une infrastructure Bitcoin moderne" -- "Synchronisation mesh pour les relais Bitcoin" -``` - -## 📋 Phase 3 : Lancement (1 jour) - -### **Checklist de Lancement** - -#### 1. **Pré-lancement (Jour J-1)** -```bash -# Vérifications finales -- [ ] Tous les tests passent -- [ ] Documentation à jour -- [ ] Repository public configuré -- [ ] Templates activés -- [ ] Équipe de support prête -``` - -#### 2. **Lancement (Jour J)** -```bash -# Actions de lancement -- [ ] Publier le communiqué de presse -- [ ] Poster sur les réseaux sociaux -- [ ] Envoyer les annonces -- [ ] Activer le support communautaire -- [ ] Monitorer les réactions - -# Release (modèle de commandes) -git add -A && git commit -m "chore(release): 2025.08" -git tag -a v2025.08 -m "release 2025.08" -git push origin HEAD && git push origin v2025.08 -``` - -#### 3. **Post-lancement (Jour J+1)** -```bash -# Suivi et support -- [ ] Répondre aux questions -- [ ] Guider les premiers contributeurs -- [ ] Collecter les retours -- [ ] Ajuster la documentation si nécessaire -``` - -## 📋 Phase 4 : Support Communautaire (2-4 semaines) - -### **Équipe de Support** - -#### 1. **Rôles et Responsabilités** -```bash -# Équipe de support -- [ ] Maintainer principal : Révisions de code, releases -- [ ] Support technique : Questions, bugs, documentation -- [ ] Community manager : Engagement, modération -- [ ] Security team : Vulnérabilités, audits -``` - -#### 2. **Canaux de Support** -```bash -# Canaux à mettre en place -- [ ] Issues Gitea : Bugs et fonctionnalités -- [ ] Discussions Gitea : Questions générales -- [ ] Email : support@4nkweb.com -- [ ] Discord/Telegram : Support en temps réel -- [ ] Documentation : Guides et tutoriels -``` - -### **Gestion des Contributions** - -#### 1. **Processus de Review** -```bash -# Workflow de contribution -1. Issue créée ou PR soumise -2. Review automatique (CI/CD) -3. Review manuelle par maintainer -4. Tests et validation -5. Merge et release -``` - -#### 2. **Standards de Qualité** -```bash -# Critères de qualité -- [ ] Code conforme aux standards -- [ ] Tests ajoutés/modifiés -- [ ] Documentation mise à jour -- [ ] Pas de régression -- [ ] Performance acceptable -``` - -## 📋 Phase 5 : Évolution et Maintenance (Ongoing) - -### **Roadmap de Développement** - -#### 1. **Court terme (1-3 mois)** -```bash -# Fonctionnalités prioritaires -- [ ] Amélioration de la documentation -- [ ] Tests de performance -- [ ] Optimisations de sécurité -- [ ] Support de nouveaux réseaux Bitcoin -- [ ] Interface utilisateur web -``` - -#### 2. **Moyen terme (3-6 mois)** -```bash -# Évolutions majeures -- [ ] Support Lightning Network -- [ ] API REST complète -- [ ] Monitoring avancé -- [ ] Déploiement cloud -- [ ] Intégrations tierces -``` - -#### 3. **Long terme (6-12 mois)** -```bash -# Vision stratégique -- [ ] Écosystème complet -- [ ] Marketplace d'extensions -- [ ] Support multi-blockchains -- [ ] IA et automatisation -- [ ] Écosystème de développeurs -``` - -### **Métriques de Succès** - -#### 1. **Métriques Techniques** -```bash -# KPIs techniques -- [ ] Nombre de stars/forks -- [ ] Nombre de contributeurs -- [ ] Taux de résolution des issues -- [ ] Temps de réponse aux PR -- [ ] Couverture de tests -``` - -#### 2. **Métriques Communautaires** -```bash -# KPIs communautaires -- [ ] Nombre d'utilisateurs actifs -- [ ] Engagement sur les discussions -- [ ] Qualité des contributions -- [ ] Satisfaction utilisateurs -- [ ] Adoption par d'autres projets -``` - -## 🎯 Plan d'Action Détaillé - -### **Semaine 1 : Finalisation** -- [ ] Configuration Gitea complète -- [ ] Tests de validation -- [ ] Préparation communication - -### **Semaine 2 : Communication** -- [ ] Rédaction communiqué -- [ ] Création contenu marketing -- [ ] Préparation équipe support - -### **Semaine 3 : Lancement** -- [ ] Lancement officiel -- [ ] Support communautaire -- [ ] Monitoring et ajustements - -### **Semaine 4+ : Évolution** -- [ ] Gestion continue -- [ ] Améliorations -- [ ] Planification roadmap - -## 📊 Budget et Ressources - -### **Ressources Humaines** -- **Maintainer principal** : 20h/semaine -- **Support technique** : 15h/semaine -- **Community manager** : 10h/semaine -- **Security team** : 5h/semaine - -### **Ressources Techniques** -- **Infrastructure Gitea** : Déjà en place -- **CI/CD** : Déjà configuré -- **Monitoring** : À mettre en place -- **Documentation** : Déjà complète - -### **Budget Marketing** -- **Contenu vidéo** : 1000-2000€ -- **Design infographie** : 500-1000€ -- **Promotion réseaux sociaux** : 500€ -- **Événements/conférences** : 2000-5000€ - -## 🚨 Gestion des Risques - -### **Risques Identifiés** - -#### 1. **Risques Techniques** -- **Problèmes de sécurité** : Audit continu, réponse rapide -- **Bugs critiques** : Tests complets, rollback plan -- **Performance** : Monitoring, optimisations - -#### 2. **Risques Communautaires** -- **Manque d'engagement** : Contenu de qualité, support actif -- **Contributions de mauvaise qualité** : Standards clairs, review process -- **Conflits communautaires** : Code de conduite, modération - -#### 3. **Risques Business** -- **Concurrence** : Innovation continue, différenciation -- **Changements réglementaires** : Veille, adaptation -- **Évolution technologique** : Roadmap flexible, veille - -### **Plans de Contingence** -```bash -# Plans de secours -- [ ] Plan de rollback technique -- [ ] Équipe de support de backup -- [ ] Communication de crise -- [ ] Ressources alternatives -``` - ---- - -**Ce plan garantit un lancement open source réussi et une évolution durable du projet 4NK Node.** 🚀 +## Post‑lancement +- Suivi issues/retours +- Corrections critiques +- Mise à jour roadmap diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md deleted file mode 100644 index 4f01dc9..0000000 --- a/docs/ROADMAP.md +++ /dev/null @@ -1,341 +0,0 @@ -# Roadmap de Développement - 4NK Node - -## 🗺️ Vue d'Ensemble - -Ce document présente la roadmap de développement du projet 4NK Node, détaillant les fonctionnalités planifiées, les améliorations et les évolutions futures. - -### **Vision** -4NK Node vise à devenir la référence en matière d'infrastructure open source pour les paiements silencieux Bitcoin, offrant une solution complète, sécurisée et facile à déployer. - -### **Objectifs** -- Simplifier le déploiement des paiements silencieux Bitcoin -- Créer un écosystème robuste et extensible -- Favoriser l'adoption des paiements privés -- Construire une communauté active de contributeurs - -## 📅 Timeline de Développement - -### **Phase Actuelle : v1.0.0 (Décembre 2024)** - -#### ✅ **Complété** -- Infrastructure Docker complète -- Support Bitcoin Core signet -- Service Blindbit intégré -- SDK Relay avec synchronisation mesh -- Documentation technique exhaustive -- Tests automatisés -- Préparation open source - -#### 🔄 **En Cours** -- Lancement open source -- Support communautaire -- Optimisations de performance - -### **Phase 1 : v1.1.0 (Janvier-Mars 2025)** - -#### 🎯 **Objectifs** -- Amélioration de la stabilité -- Optimisations de performance -- Support communautaire -- Documentation enrichie - -#### 📋 **Fonctionnalités Planifiées** - -##### **Stabilité et Performance** -- [ ] **Optimisation mémoire** - Réduction de l'empreinte mémoire -- [ ] **Amélioration des logs** - Logs structurés et rotation -- [ ] **Monitoring avancé** - Métriques détaillées -- [ ] **Gestion d'erreurs** - Récupération automatique -- [ ] **Tests de charge** - Validation des performances - -##### **Interface Utilisateur** -- [ ] **Interface web basique** - Dashboard de monitoring -- [ ] **API REST complète** - Endpoints pour la gestion -- [ ] **CLI améliorée** - Commandes de gestion -- [ ] **Documentation interactive** - Guides interactifs - -##### **Sécurité** -- [ ] **Audit de sécurité** - Audit externe complet -- [ ] **Chiffrement des données** - Chiffrement des cookies -- [ ] **Authentification** - Système d'authentification -- [ ] **Certificats SSL/TLS** - Support HTTPS complet - -### **Phase 2 : v1.2.0 (Avril-Juin 2025)** - -#### 🎯 **Objectifs** -- Support de nouveaux réseaux Bitcoin -- Intégrations tierces -- Écosystème d'extensions -- Performance avancée - -#### 📋 **Fonctionnalités Planifiées** - -##### **Réseaux Bitcoin** -- [ ] **Support mainnet** - Déploiement production -- [ ] **Support testnet** - Environnement de test -- [ ] **Support regtest** - Tests locaux -- [ ] **Multi-réseaux** - Support simultané - -##### **Intégrations** -- [ ] **Wallets populaires** - Intégration wallets -- [ ] **Exchanges** - Support exchanges -- [ ] **Services tiers** - APIs externes -- [ ] **Plugins** - Système de plugins - -##### **Performance** -- [ ] **Cache distribué** - Cache Redis/Memcached -- [ ] **Base de données** - PostgreSQL/MySQL -- [ ] **Load balancing** - Équilibrage de charge -- [ ] **Auto-scaling** - Mise à l'échelle automatique - -### **Phase 3 : v2.0.0 (Juillet-Décembre 2025)** - -#### 🎯 **Objectifs** -- Support Lightning Network -- Écosystème complet -- Marketplace d'extensions -- IA et automatisation - -#### 📋 **Fonctionnalités Planifiées** - -##### **Lightning Network** -- [ ] **Nœud Lightning** - LND/c-lightning -- [ ] **Paiements Lightning** - Support LN -- [ ] **Canaux automatiques** - Gestion des canaux -- [ ] **Routage** - Routage Lightning - -##### **Écosystème** -- [ ] **Marketplace** - Extensions et plugins -- [ ] **SDK complet** - SDK pour développeurs -- [ ] **Templates** - Templates de déploiement -- [ ] **Intégrations** - Écosystème riche - -##### **Intelligence Artificielle** -- [ ] **Monitoring IA** - Détection d'anomalies -- [ ] **Optimisation automatique** - Auto-optimisation -- [ ] **Prédictions** - Prédictions de charge -- [ ] **Chatbot** - Support IA - -### **Phase 4 : v2.1.0 (Janvier-Juin 2026)** - -#### 🎯 **Objectifs** -- Support multi-blockchains -- Cloud native -- Écosystème développeur -- Adoption massive - -#### 📋 **Fonctionnalités Planifiées** - -##### **Multi-Blockchains** -- [ ] **Ethereum** - Support Ethereum -- [ ] **Polkadot** - Support Polkadot -- [ ] **Cosmos** - Support Cosmos -- [ ] **Interopérabilité** - Cross-chain - -##### **Cloud Native** -- [ ] **Kubernetes** - Support K8s -- [ ] **Serverless** - Fonctions serverless -- [ ] **Microservices** - Architecture microservices -- [ ] **Edge computing** - Computing edge - -##### **Écosystème Développeur** -- [ ] **API Gateway** - Gateway API -- [ ] **Documentation API** - Swagger/OpenAPI -- [ ] **SDKs multiples** - SDKs pour différents langages -- [ ] **Outils de développement** - IDE plugins - -## 🎯 Fonctionnalités Détaillées - -### **Interface Utilisateur Web** - -#### **Dashboard Principal** -```yaml -Fonctionnalités: - - Vue d'ensemble des services - - Métriques en temps réel - - Gestion des relais - - Configuration avancée - - Logs et monitoring - - Support et documentation -``` - -#### **API REST** -```yaml -Endpoints: - - GET /api/v1/status - Statut des services - - GET /api/v1/metrics - Métriques système - - POST /api/v1/relays - Gestion des relais - - PUT /api/v1/config - Configuration - - GET /api/v1/logs - Logs système -``` - -### **Support Lightning Network** - -#### **Architecture LN** -```yaml -Composants: - - LND Node: Nœud Lightning principal - - Channel Manager: Gestion des canaux - - Payment Router: Routage des paiements - - Invoice Manager: Gestion des factures - - Network Monitor: Surveillance réseau -``` - -#### **Intégration** -```yaml -Fonctionnalités: - - Paiements Lightning automatiques - - Gestion des canaux - - Routage intelligent - - Facturation automatique - - Monitoring des canaux -``` - -### **Marketplace d'Extensions** - -#### **Types d'Extensions** -```yaml -Extensions: - - Wallets: Intégrations wallets - - Exchanges: Support exchanges - - Analytics: Outils d'analyse - - Security: Outils de sécurité - - Monitoring: Outils de monitoring - - Custom: Extensions personnalisées -``` - -#### **Système de Plugins** -```yaml -Architecture: - - Plugin Manager: Gestionnaire de plugins - - API Plugin: API pour plugins - - Sandbox: Environnement sécurisé - - Registry: Registre de plugins - - Updates: Mises à jour automatiques -``` - -## 📊 Métriques de Succès - -### **Métriques Techniques** - -#### **Performance** -- **Temps de réponse** : < 100ms pour les APIs -- **Disponibilité** : 99.9% uptime -- **Throughput** : 1000+ transactions/seconde -- **Latence** : < 50ms pour les paiements - -#### **Qualité** -- **Couverture de tests** : > 90% -- **Bugs critiques** : 0 en production -- **Temps de résolution** : < 24h pour les bugs critiques -- **Documentation** : 100% des APIs documentées - -### **Métriques Communautaires** - -#### **Adoption** -- **Utilisateurs actifs** : 1000+ utilisateurs -- **Contributeurs** : 50+ contributeurs -- **Forks** : 100+ forks -- **Stars** : 500+ stars - -#### **Engagement** -- **Issues résolues** : 90% en < 7 jours -- **PR merged** : 80% en < 3 jours -- **Discussions actives** : 100+ par mois -- **Documentation mise à jour** : Mise à jour continue - -## 🚨 Gestion des Risques - -### **Risques Techniques** - -#### **Performance** -- **Risque** : Charge élevée non supportée -- **Mitigation** : Tests de charge, auto-scaling -- **Plan de contingence** : Architecture distribuée - -#### **Sécurité** -- **Risque** : Vulnérabilités de sécurité -- **Mitigation** : Audits réguliers, bug bounty -- **Plan de contingence** : Response team, patches rapides - -### **Risques Communautaires** - -#### **Adoption** -- **Risque** : Faible adoption -- **Mitigation** : Marketing actif, documentation claire -- **Plan de contingence** : Pivot vers niches spécifiques - -#### **Maintenance** -- **Risque** : Manque de mainteneurs -- **Mitigation** : Formation, documentation -- **Plan de contingence** : Équipe de backup - -## 🎯 Priorités de Développement - -### **Priorité Haute (P0)** -1. **Stabilité** - Correction des bugs critiques -2. **Sécurité** - Vulnérabilités de sécurité -3. **Performance** - Optimisations critiques -4. **Documentation** - Documentation essentielle - -### **Priorité Moyenne (P1)** -1. **Nouvelles fonctionnalités** - Fonctionnalités majeures -2. **Améliorations UX** - Interface utilisateur -3. **Intégrations** - Intégrations tierces -4. **Monitoring** - Outils de monitoring - -### **Priorité Basse (P2)** -1. **Optimisations** - Optimisations mineures -2. **Documentation avancée** - Guides avancés -3. **Outils de développement** - Outils pour développeurs -4. **Expérimentations** - Fonctionnalités expérimentales - -## 📈 Évolution de l'Architecture - -### **Architecture Actuelle (v1.0)** -```yaml -Services: - - Bitcoin Core: Nœud Bitcoin - - Blindbit: Service de filtres - - SDK Relay: Relais synchronisés - - Tor: Proxy anonyme -``` - -### **Architecture v2.0** -```yaml -Services: - - Bitcoin Core: Nœud Bitcoin - - Lightning Node: Nœud Lightning - - Blindbit: Service de filtres - - SDK Relay: Relais synchronisés - - API Gateway: Gateway API - - Web UI: Interface web - - Monitoring: Monitoring avancé - - Tor: Proxy anonyme -``` - -### **Architecture v3.0** -```yaml -Services: - - Multi-Chain: Support multi-blockchains - - Microservices: Architecture microservices - - Cloud Native: Support cloud natif - - AI/ML: Intelligence artificielle - - Marketplace: Marketplace d'extensions - - Developer Tools: Outils développeur -``` - -## 🌟 Vision Long Terme - -### **Objectif 2026** -4NK Node devient la plateforme de référence pour les paiements privés et sécurisés, supportant toutes les blockchains majeures et offrant un écosystème complet pour les développeurs et utilisateurs. - -### **Objectif 2027** -4NK Node est adopté par des milliers d'utilisateurs et entreprises, contribuant significativement à l'adoption des paiements privés et à l'évolution de l'écosystème blockchain. - -### **Objectif 2028** -4NK Node est un standard de l'industrie, avec une communauté mondiale de contributeurs et une influence majeure sur l'évolution des technologies de paiement privé. - ---- - -**Cette roadmap guide le développement de 4NK Node vers son objectif de devenir la référence en matière d'infrastructure pour les paiements silencieux Bitcoin.** 🚀 diff --git a/docs/SECURITY_AUDIT.md b/docs/SECURITY_AUDIT.md index 13a88ac..9353cd2 100644 --- a/docs/SECURITY_AUDIT.md +++ b/docs/SECURITY_AUDIT.md @@ -1,198 +1,19 @@ -# Audit de Sécurité - 4NK Node +# Audit de sécurité — 4NK_template -## 🔍 Résumé de l'Audit +## Menaces +- Secrets, permissions, endpoints sensibles, dépendances -**Date d'audit** : 19 décembre 2024 -**Auditeur** : Assistant IA -**Version du projet** : 1.0.0 -**Score de sécurité** : à évaluer +## Contrôles +- Scan secrets/permissions +- Audit dépendances +- Vérifs config (auth/TLS/CORS/rate‑limit) +- Journalisation sécurité -## 📋 Éléments Audités +## CI security‑audit +- Job dédié qui échoue en cas d’alerte critique -### ✅ **Points Sécurisés** +## Politique des secrets +- Secrets CI, rotation, aucune clé en clair -#### 1. **Fichiers de Configuration** -- ✅ **Cookies Bitcoin** : Utilisation de chemins sécurisés (`/home/bitcoin/.bitcoin/signet/.cookie`) -- ✅ **Permissions** : Cookies avec permissions 600 (lecture/écriture propriétaire uniquement) -- ✅ **Variables d'environnement** : Pas de secrets en dur dans le code -- ✅ **Configuration externalisée** : Fichiers .conf séparés du code - -#### 2. **Infrastructure Docker** -- ✅ **Réseau isolé** : Communication via réseau privé `btcnet` -- ✅ **Volumes sécurisés** : Données sensibles dans des volumes Docker -- ✅ **Healthchecks** : Surveillance de l'état des services -- ✅ **Logs** : Rotation et limitation de taille des logs - -#### 3. **Code et Dépendances** -- ✅ **Pas de secrets en dur** : Aucun mot de passe ou clé privée dans le code -- ✅ **Dépendances Rust** : Utilisation de crates sécurisées -- ✅ **Validation des entrées** : Validation des configurations et paramètres -- ✅ **Gestion d'erreurs** : Gestion appropriée des erreurs - -### ⚠️ **Points d'Attention** - -#### 1. **URLs et Endpoints** -- ⚠️ **dev3.4nkweb.com** : URL externe référencée dans la configuration -- ⚠️ **git.4nkweb.com** : URLs du repository Gitea -- ✅ **Pas d'endpoints privés** : Toutes les URLs sont publiques et appropriées - -#### 2. **Certificats SSL/TLS** -- ⚠️ **Exemples de certificats** : Documentation contient des exemples de génération -- ✅ **Pas de certificats réels** : Aucun certificat privé dans le code - -#### 3. **Tests de Connectivité** -- ⚠️ **WebSocket tests** : Tests utilisent des clés de test (`Sec-WebSocket-Key: test`) -- ✅ **Clés de test uniquement** : Pas de clés de production - -## 🔒 Analyse Détaillée - -### **Fichiers Sensibles** - -#### Cookies Bitcoin Core -```bash -# Sécurisé ✅ -/home/bitcoin/.bitcoin/signet/.cookie # Permissions 600 -/home/bitcoin/.4nk/bitcoin.cookie # Copie sécurisée -``` - -#### Configuration Files -```bash -# Sécurisé ✅ -sdk_relay/.conf # Configuration de base -sdk_relay/.conf.docker # Configuration Docker -sdk_relay/external_nodes.conf # Nœuds externes -``` - -#### Docker Volumes -```bash -# Sécurisé ✅ -bitcoin_data:/home/bitcoin/.bitcoin # Données Bitcoin -blindbit_data:/data # Données Blindbit -sdk_relay_*_data:/home/bitcoin/.4nk # Données SDK Relay -``` - -### **URLs et Endpoints** - -#### URLs Publiques (Approuvées) -```bash -# Repository Gitea ✅ -https://git.4nkweb.com/4nk/4NK_node -https://git.4nkweb.com/4nk/sdk_relay -https://git.4nkweb.com/4nk/sdk_common - -# Nœud externe ✅ -dev3.4nkweb.com:443 # Relais externe documenté -``` - -#### URLs de Support (Approuvées) -```bash -# Support et communication ✅ -security@4nkweb.com # Signalement de vulnérabilités -support@4nkweb.com # Support utilisateur -https://forum.4nkweb.com # Forum communautaire -``` - -### **Variables d'Environnement** - -#### Variables Sécurisées -```bash -# Configuration Bitcoin ✅ -BITCOIN_COOKIE_PATH=/home/bitcoin/.bitcoin/signet/.cookie -BITCOIN_NETWORK=signet - -# Configuration SDK Relay ✅ -RUST_LOG=debug -ENABLE_SYNC_TEST=1 -HOME=/home/bitcoin -``` - -## 🛡️ Recommandations de Sécurité - -### **Actions Immédiates (modèle)** - -#### 1. **Permissions des Fichiers** -```bash -# Vérifier les permissions des fichiers sensibles -find . -name "*.conf" -exec chmod 600 {} \; -find . -name "*.cookie" -exec chmod 600 {} \; -``` - -#### 2. **Variables d'Environnement** -```bash -# Utiliser des variables d'environnement pour les secrets -export BITCOIN_RPC_PASSWORD="your_secure_password" -export BLINDBIT_API_KEY="your_api_key" -``` - -#### 3. **Monitoring de Sécurité** -```bash -# Ajouter des tests de sécurité automatisés -./tests/run_security_tests.sh -``` - -### **Actions Recommandées (modèle)** - -#### 1. **Chiffrement des Données** -- Chiffrer les cookies Bitcoin Core -- Utiliser des certificats SSL/TLS pour les communications -- Implémenter le chiffrement des données sensibles - -#### 2. **Authentification Renforcée** -- Implémenter l'authentification multi-facteurs -- Utiliser des tokens JWT pour les APIs -- Ajouter la validation des certificats clients - -#### 3. **Audit Continu** -- Mettre en place un audit de sécurité automatisé -- Surveiller les vulnérabilités des dépendances -- Tester régulièrement la sécurité - -## 📊 Score de Sécurité - -### **Critères d'Évaluation** - -| Critère | Score | Commentaire | -|---------|-------|-------------| -| **Secrets en dur** | 100/100 | ✅ Aucun secret trouvé | -| **Permissions** | 90/100 | ✅ Permissions appropriées | -| **Configuration** | 85/100 | ✅ Configuration externalisée | -| **Réseau** | 90/100 | ✅ Isolation Docker | -| **Dépendances** | 80/100 | ✅ Dépendances sécurisées | -| **Documentation** | 85/100 | ✅ Bonnes pratiques documentées | - -### **Score Global :** à établir - -## 🚨 Plan d'Action - -### **Phase 1 : Immédiat (1-2 jours) — modèle** -- [x] Audit de sécurité complet -- [x] Vérification des permissions -- [x] Nettoyage des fichiers GitHub -- [ ] Tests de sécurité automatisés - -### **Phase 2 : Court terme (1 semaine) — modèle** -- [ ] Implémentation du chiffrement des cookies -- [ ] Ajout de certificats SSL/TLS -- [ ] Monitoring de sécurité - -### **Phase 3 : Moyen terme (1 mois) — modèle** -- [ ] Authentification renforcée -- [ ] Audit de sécurité automatisé -- [ ] Formation sécurité équipe - -## 📚 Ressources - -### **Documentation Sécurité** -- [Guide de Sécurité Bitcoin](https://bitcoin.org/en/security) -- [OWASP Top 10](https://owasp.org/www-project-top-ten/) -- [Docker Security Best Practices](https://docs.docker.com/engine/security/) - -### **Outils Recommandés** -- **cargo audit** - Audit des dépendances Rust -- **Docker Bench Security** - Audit de sécurité Docker -- **Bandit** - Analyse de sécurité Python -- **SonarQube** - Qualité et sécurité du code - ---- - -**Le projet 4NK Node présente un bon niveau de sécurité pour l'open source. Les recommandations ci-dessus permettront de renforcer encore la sécurité.** 🔒 +## Remédiation +- Corriger critiques, documenter dans CHANGELOG diff --git a/docs/TEMPLATE_ADAPTATION.md b/docs/TEMPLATE_ADAPTATION.md deleted file mode 100644 index c8e0b54..0000000 --- a/docs/TEMPLATE_ADAPTATION.md +++ /dev/null @@ -1,34 +0,0 @@ -# Guide d’adaptation du template 4NK - -Ce document décrit comment adapter `4NK_template` à un projet concret. - -## 1. Périmètre et langage -- Choisir les jobs CI pertinents (Rust/Node/Docker) et supprimer ceux non applicables. -- Conserver le job `security-audit` et le `release-guard`. - -## 2. Sécurité -- Activer `scripts/security/audit.sh` (npm audit/cargo audit + scan secrets) et ajuster les seuils si nécessaire. -- Vérifier les permissions de fichiers sensibles et l’absence de secrets en clair. - -## 3. Versionnage & release -- Définir le fichier de version (`VERSION` ou `TEMPLATE_VERSION`). -- Tenir `CHANGELOG.md` comme source de vérité et intégrer au `release-guard`. - -## 4. Documentation -- Adapter `docs/INDEX.md`, `INSTALLATION.md`, `USAGE.md`, `ARCHITECTURE.md` au contexte projet. -- Maintenir `docs/SECURITY_AUDIT.md` conforme à la réalité du dépôt. - -## 5. Règles Cursor -- Conserver `.cursor/rules/*` puis affiner selon le langage et la structure du projet. - -## 6. CI/CD (Gitea) -- Adapter `.gitea/workflows/ci.yml` (jobs, versions, caches) sans retirer `security-audit` ni `release-guard`. -- Ajouter des jobs spécifiques (e2e, perf) si nécessaire. - -## 7. Gouvernance et open source -- Vérifier `LICENSE`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `OPEN_SOURCE_CHECKLIST.md`. -- Utiliser `AGENTS.md` pour clarifier les responsabilités. - -## 8. Synchronisation avec le template -- Documenter toute divergence locale dans `LOCAL_OVERRIDES.yml` si utilisé. -- Proposer les améliorations génériques en feedback (voir `docs/TEMPLATE_FEEDBACK.md`). diff --git a/docs/TEMPLATE_FEEDBACK.md b/docs/TEMPLATE_FEEDBACK.md deleted file mode 100644 index f222ca1..0000000 --- a/docs/TEMPLATE_FEEDBACK.md +++ /dev/null @@ -1,22 +0,0 @@ -# Processus de feedback vers le template 4NK - -L’objectif est de canaliser les améliorations génériques découvertes dans les projets vers `4NK_template`. - -## 1. Identifier une amélioration générique -- Règle Cursor utile à plusieurs dépôts -- Étape CI/CD généralisable -- Script ou guide documentaire réutilisable - -## 2. Ouvrir une issue dédiée (Template Feedback) -- Décrire le contexte, l’impact multi‑projets et la proposition -- Joindre des diffs minimaux et des liens vers projets sources - -## 3. Prototyper et valider -- Créer une branche sur `4NK_template` -- Ajouter les nouveaux artefacts (règles/scripts/docs) -- Valider via la CI (incluant `security-audit` et `release-guard`) - -## 4. Finaliser et communiquer -- Mettre à jour `CHANGELOG.md` et `TEMPLATE_VERSION` -- Ajouter une note dans `docs/INDEX.md` -- Annoncer aux projets consommateurs (via issue/PR) diff --git a/docs/TESTING.md b/docs/TESTING.md index 8f0fb20..ca550b9 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -1,498 +1,26 @@ -# Guide de Tests - +# Guide de Tests — 4NK_template -Ce guide documente l'ensemble des tests disponibles pour l'infrastructure , leur organisation et leur utilisation. - -## Vue d'Ensemble - -L'infrastructure dispose d'une suite de tests complète organisée en plusieurs catégories : - -- **Tests Unitaires** : Tests individuels des composants -- **Tests d'Intégration** : Tests d'interaction entre services -- **Tests de Connectivité** : Tests réseau et WebSocket -- **Tests Externes** : Tests avec des nœuds externes -- **Tests de Performance** : Tests de charge et performance (à venir) - -## Structure des Tests +## Vue d’ensemble +- Unit, Integration, Connectivity, External, Performance +## Structure ``` tests/ -├── README.md # Documentation principale des tests -├── run_all_tests.sh # Exécution de tous les tests -├── run_unit_tests.sh # Tests unitaires uniquement -├── run_integration_tests.sh # Tests d'intégration uniquement -├── run_connectivity_tests.sh # Tests de connectivité uniquement -├── run_external_tests.sh # Tests externes uniquement -├── cleanup.sh # Nettoyage des logs et rapports -├── logs/ # Logs des tests -├── reports/ # Rapports de tests -├── unit/ # Tests unitaires -│ ├── test_healthcheck.sh -│ ├── test_docker.sh -│ ├── test_simple.sh -│ └── test_final.sh -├── integration/ # Tests d'intégration -│ ├── test_3_relays.sh -│ ├── test_final_sync.sh -│ ├── test_sync_logs.sh -│ └── test_messages.sh -├── connectivity/ # Tests de connectivité -│ ├── test_connectivity.sh -│ └── test_websocket_messages.py -├── external/ # Tests externes -│ ├── test_dev3_simple.py -│ ├── test_dev3_connectivity.py -│ └── test_integration_dev3.sh -└── performance/ # Tests de performance (à créer) +├── README.md +├── cleanup.sh +├── logs/ +├── reports/ +├── unit/ +├── integration/ +├── connectivity/ +├── external/ +└── performance/ ``` -## Exécution des Tests +## Exécution +- Scripts spécifiques au projet +- Rapports dans `tests/reports/` -### Test Complet - -Pour exécuter tous les tests : - -```bash -cd tests/ -./run_all_tests.sh -``` - -Options disponibles : -- `--verbose` : Mode verbose avec affichage détaillé -- `--debug` : Mode debug complet -- `--skip-unit` : Ignorer les tests unitaires -- `--skip-integration` : Ignorer les tests d'intégration -- `--skip-connectivity` : Ignorer les tests de connectivité -- `--skip-external` : Ignorer les tests externes - -### Tests par Catégorie - -#### Tests Unitaires -```bash -./tests/run_unit_tests.sh [--verbose] [--debug] -``` - -**Tests inclus :** -- `test_healthcheck.sh` : Test du healthcheck de sdk_relay -- `test_docker.sh` : Test de la configuration Docker -- `test_simple.sh` : Test simple de sdk_relay -- `test_final.sh` : Test final de sdk_relay - -**Prérequis :** -- Docker installé et fonctionnel -- Image sdk_relay disponible - -#### Tests d'Intégration -```bash -./tests/run_integration_tests.sh [--verbose] [--debug] -``` - -**Tests inclus :** -- `test_3_relays.sh` : Test de 3 instances sdk_relay -- `test_final_sync.sh` : Test complet de synchronisation -- `test_sync_logs.sh` : Test des logs de synchronisation -- `test_messages.sh` : Test des messages entre relais - -**Prérequis :** -- Tous les services Docker démarrés (bitcoin, blindbit, sdk_relay) -- Infrastructure complète opérationnelle - -#### Tests de Connectivité -```bash -./tests/run_connectivity_tests.sh [--verbose] [--debug] -``` - -**Tests inclus :** -- `test_connectivity.sh` : Test de connectivité des services -- `test_websocket_messages.py` : Test des messages WebSocket - -**Prérequis :** -- Services Docker démarrés -- Python3 avec websockets installé - -#### Tests Externes -```bash -./tests/run_external_tests.sh [--verbose] [--debug] -``` - -**Tests inclus :** -- `test_dev3_simple.py` : Test simple de dev3.4nkweb.com -- `test_dev3_connectivity.py` : Test de connectivité dev3 -- `test_integration_dev3.sh` : Test d'intégration dev3 - -**Prérequis :** -- Connectivité internet -- Python3 avec websockets installé -- Services locaux optionnels - -### Test Individuel - -Pour exécuter un test spécifique : - -```bash -# Test shell -./tests/integration/test_3_relays.sh - -# Test Python -python3 tests/external/test_dev3_simple.py -``` - -## Interprétation des Résultats - -### Codes de Sortie - -- `0` : Test réussi -- `1` : Test échoué -- `2` : Test ignoré (prérequis non satisfaits) - -### Logs - -Les logs détaillés sont écrits dans `tests/logs/` avec le format : -``` -YYYY-MM-DD_HH-MM-SS_category_tests.log -``` - -Exemples : -- `2024-12-19_14-30-25_unit_tests.log` -- `2024-12-19_14-35-12_integration_tests.log` - -### Rapports - -Les rapports JSON sont générés dans `tests/reports/` avec le format : -``` -test_report_YYYY-MM-DD_HH-MM-SS.json -``` - -Structure du rapport : -```json -{ - "timestamp": "2024-12-19_14-30-25", - "summary": { - "total_tests": 10, - "successful_tests": 8, - "failed_tests": 2, - "success_rate": 80.0 - }, - "log_file": "tests/logs/test_run_2024-12-19_14-30-25.log", - "options": { - "verbose": false, - "debug": false, - "skip_unit": false, - "skip_integration": false, - "skip_connectivity": false, - "skip_external": false, - "skip_performance": true - } -} -``` - -## Détail des Tests - -### Tests Unitaires - -#### test_healthcheck.sh -- **Objectif** : Vérifier le fonctionnement du healthcheck de sdk_relay -- **Méthode** : Test du script healthcheck.sh dans un conteneur -- **Critères de succès** : Healthcheck retourne un code de sortie approprié - -#### test_docker.sh -- **Objectif** : Vérifier la configuration Docker de sdk_relay -- **Méthode** : Test de la construction et du démarrage du conteneur -- **Critères de succès** : Conteneur démarre correctement - -#### test_simple.sh -- **Objectif** : Test simple de sdk_relay -- **Méthode** : Démarrage et test basique de sdk_relay -- **Critères de succès** : Service répond aux requêtes de base - -#### test_final.sh -- **Objectif** : Test final complet de sdk_relay -- **Méthode** : Test complet avec toutes les fonctionnalités -- **Critères de succès** : Toutes les fonctionnalités opérationnelles - -### Tests d'Intégration - -#### test_3_relays.sh -- **Objectif** : Tester 3 instances sdk_relay en parallèle -- **Méthode** : Démarrage de 3 relais et vérification de leur interaction -- **Critères de succès** : Les 3 relais communiquent correctement - -#### test_final_sync.sh -- **Objectif** : Test complet de la synchronisation -- **Méthode** : Test de tous les types de synchronisation -- **Critères de succès** : Synchronisation fonctionnelle entre tous les relais - -#### test_sync_logs.sh -- **Objectif** : Vérifier les logs de synchronisation -- **Méthode** : Analyse des logs de synchronisation -- **Critères de succès** : Logs cohérents et sans erreurs - -#### test_messages.sh -- **Objectif** : Tester l'échange de messages entre relais -- **Méthode** : Envoi et réception de messages de test -- **Critères de succès** : Messages correctement transmis - -### Tests de Connectivité - -#### test_connectivity.sh -- **Objectif** : Vérifier la connectivité entre services -- **Méthode** : Test de connectivité réseau entre conteneurs -- **Critères de succès** : Tous les services accessibles - -#### test_websocket_messages.py -- **Objectif** : Tester les messages WebSocket -- **Méthode** : Connexion WebSocket et échange de messages -- **Critères de succès** : Communication WebSocket fonctionnelle - -### Tests Externes - -#### test_dev3_simple.py -- **Objectif** : Test simple de dev3.4nkweb.com -- **Méthode** : Connexion WebSocket simple -- **Critères de succès** : Connexion établie - -#### test_dev3_connectivity.py -- **Objectif** : Test complet de connectivité dev3 -- **Méthode** : Tests de protocole et handshake -- **Critères de succès** : Tous les protocoles supportés - -#### test_integration_dev3.sh -- **Objectif** : Test d'intégration avec dev3 -- **Méthode** : Test complet d'intégration -- **Critères de succès** : Intégration fonctionnelle - -## Dépannage - -### Problèmes Courants - -#### Services non démarrés -**Symptôme** : Erreur "Service non trouvé" -**Solution** : Démarrer les services avec `./restart_4nk_node.sh` - -#### Connectivité réseau -**Symptôme** : Timeout ou erreur de connexion -**Solution** : Vérifier les ports et pare-feu - -#### Certificats SSL -**Symptôme** : Erreur SSL dans les tests externes -**Solution** : Vérifier les certificats et la configuration SSL - -#### Dépendances Python -**Symptôme** : ModuleNotFoundError -**Solution** : Installer les dépendances avec `pip install websockets` - -### Debug - -#### Mode Verbose -```bash -./tests/run_all_tests.sh --verbose -``` - -#### Mode Debug -```bash -./tests/run_all_tests.sh --debug -``` - -#### Test spécifique avec debug -```bash -./tests/integration/test_3_relays.sh --debug -``` - -## Maintenance - -### Nettoyage Automatique - -#### Nettoyer les logs anciens -```bash -./tests/cleanup.sh --days 7 -``` - -#### Nettoyer les rapports anciens -```bash -./tests/cleanup.sh --reports --days 30 -``` - -#### Nettoyage complet -```bash -./tests/cleanup.sh --all --days 7 -``` - -#### Simulation de nettoyage -```bash -./tests/cleanup.sh --all --dry-run -``` - -### Surveillance - -#### Vérifier l'espace disque -```bash -du -sh tests/logs tests/reports -``` - -#### Lister les fichiers récents -```bash -find tests/logs -name "*.log" -mtime -1 -``` - -#### Analyser les échecs -```bash -grep -r "ERROR\|FAILED" tests/logs/ -``` - -## Ajout de Nouveaux Tests - -### Structure Recommandée - -Pour ajouter un nouveau test : - -1. **Créer le fichier de test** dans le répertoire approprié -2. **Ajouter le test** au script d'exécution correspondant -3. **Documenter le test** dans ce guide -4. **Tester le test** pour s'assurer qu'il fonctionne - -### Template de Test Shell - -```bash -#!/bin/bash -# Test: Description du test -# Auteur: Nom -# Date: YYYY-MM-DD - -set -e - -# Configuration -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -LOG_FILE="tests/logs/$(date +%Y-%m-%d_%H-%M-%S)_test_name.log" - -# Fonctions -log() { - echo "[$(date +%Y-%m-%d\ %H:%M:%S)] $1" | tee -a "$LOG_FILE" -} - -# Test principal -main() { - log "Début du test" - - # Vérifications préliminaires - check_prerequisites - - # Exécution du test - run_test - - # Vérification des résultats - verify_results - - log "Test terminé avec succès" -} - -# Exécution -main "$@" -``` - -### Template de Test Python - -```python -#!/usr/bin/env python3 -""" -Test: Description du test -Auteur: Nom -Date: YYYY-MM-DD -""" - -import asyncio -import json -import logging -from datetime import datetime - -# Configuration du logging -logging.basicConfig(level=logging.INFO) -logger = logging.getLogger(__name__) - -async def test_function(): - """Fonction de test principale""" - logger.info("Début du test") - - try: - # Logique de test - result = await run_test() - - # Vérification - if result: - logger.info("Test réussi") - return True - else: - logger.error("Test échoué") - return False - - except Exception as e: - logger.error(f"Erreur lors du test: {e}") - return False - -async def main(): - """Fonction principale""" - success = await test_function() - exit(0 if success else 1) - -if __name__ == "__main__": - asyncio.run(main()) -``` - -## Intégration Continue - -### Automatisation - -Les tests peuvent être intégrés dans un pipeline CI/CD : - -```yaml -# Exemple GitHub Actions -- name: Run Tests - run: | - cd tests/ - ./run_all_tests.sh --verbose -``` - -### Surveillance Continue - -Pour une surveillance continue : - -```bash -# Cron job pour tests quotidiens -0 2 * * * cd /path/to/4NK_node/tests && ./run_all_tests.sh >> /var/log/4nk_tests.log 2>&1 -``` - -### Garde de release - -Avant toute publication (push/tag), le job CI `release-guard` et le script local `scripts/release/guard.sh` exigent des tests verts. Exécution locale: - -```bash -RELEASE_TYPE=ci-verify scripts/release/guard.sh -``` - -## Support - -Pour obtenir de l'aide : - -1. **Consulter les logs** : `tests/logs/` -2. **Vérifier la documentation** : `tests/README.md` -3. **Utiliser le mode debug** : `--debug` -4. **Consulter les rapports** : `tests/reports/` - -## Évolution - -### Tests de Performance (À venir) - -- Tests de charge -- Tests de latence -- Tests de débit -- Tests de stress - -### Tests de Sécurité (À venir) - -- Tests de vulnérabilités -- Tests de pénétration -- Tests de configuration - -### Tests d'Interface (À venir) - -- Tests d'API REST -- Tests d'interface WebSocket -- Tests de compatibilité +## CI +- Exécutions par catégorie +- Blocage release en cas d’échec (release‑guard) diff --git a/docs/USAGE.md b/docs/USAGE.md index f542a20..c5b5ce6 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -1,669 +1,25 @@ -# 📖 Guide d'Utilisation - +# 📖 Guide d’Utilisation — 4NK_template -> Ce document est un modèle générique. Remplacez et adaptez les commandes/chemins à votre projet. +Ce guide d’usage est générique; adaptez‑le pour votre projet dérivé. -Guide complet pour utiliser l'infrastructure au quotidien. +## Démarrage quotidien +- Vérifier la CI locale (lint/tests/doc) +- Démarrer vos services (si applicable) +- Vérifier logs, métriques et alertes -## 🚀 Démarrage Quotidien +## Opérations courantes +- Logs applicatifs +- Healthchecks et métriques +- Exécuter les suites de tests -### 1. Démarrage Rapide +## Tests +- Voir `docs/TESTING.md` +- Rapports dans `tests/reports/` -```bash -# Démarrer tous les services -./restart_4nk_node.sh +## Sécurité +- Audits dépendances et secrets +- Voir `docs/SECURITY_AUDIT.md` -# Vérifier le statut -docker ps -``` - -### 2. Démarrage Séquentiel - -```bash -# Démarrer Tor -./restart_4nk_node.sh -t - -# Démarrer Bitcoin Core -./restart_4nk_node.sh -b - -# Attendre la synchronisation Bitcoin -echo "Attendre la synchronisation Bitcoin (10-30 minutes)..." -docker logs bitcoin-signet | grep "progress" - -# Démarrer Blindbit -./restart_4nk_node.sh -l - -# Démarrer les relais -./restart_4nk_node.sh -r -``` - -### 3. Vérification du Démarrage - -```bash -# Vérifier tous les services -docker ps - -# Vérifier les logs -docker-compose logs --tail=50 - -# Vérifier la connectivité -./test_final_sync.sh -``` - -## 🔧 Opérations Quotidiennes - -### 1. Surveillance des Services - -```bash -# Statut des services -docker ps - -# Logs en temps réel -docker-compose logs -f - -# Utilisation des ressources -docker stats - -# Espace disque -docker system df -``` - -### 2. Monitoring de la Synchronisation - -```bash -# Surveillance de la synchronisation -./monitor_sync.sh - -# Test de synchronisation -./test_sync_logs.sh - -# Test des messages WebSocket -python3 test_websocket_messages.py -``` - -### 3. Gestion des Logs - -```bash -# Logs de tous les services -docker-compose logs -f - -# Logs d'un service spécifique -docker logs bitcoin-signet -docker logs blindbit-oracle -docker logs sdk_relay_1 - -# Logs avec timestamps -docker-compose logs -t - -# Logs depuis une date -docker-compose logs --since="2024-01-01T00:00:00" - -# Logs des 100 dernières lignes -docker-compose logs --tail=100 -``` - -## 🌐 Utilisation du Réseau de Relais - -### 1. Configuration des Relais - -L'infrastructure utilise 3 relais locaux : - -| Relay | Port WebSocket | Port HTTP | Configuration | -|-------|----------------|-----------|---------------| -| **Relay 1** | 8090 | 8091 | `sdk_relay/.conf.docker.relay1` | -| **Relay 2** | 8092 | 8093 | `sdk_relay/.conf.docker.relay2` | -| **Relay 3** | 8094 | 8095 | `sdk_relay/.conf.docker.relay3` | - -### 2. Test de Connectivité des Relais - -```bash -# Test de connectivité de base -./test_final_sync.sh - -# Test de synchronisation -./test_sync_logs.sh - -# Test des messages WebSocket -python3 test_websocket_messages.py - -# Test de charge -python3 test_websocket_messages.py --load-test -``` - -### 3. Surveillance de la Synchronisation - -```bash -# Surveillance en temps réel -./monitor_sync.sh - -# Test de synchronisation forcé -./test_sync_logs.sh force - -# Test de synchronisation en continu -./test_sync_logs.sh continuous -``` - -## 🔗 Connexion aux Services - -### 1. Bitcoin Core RPC - -```bash -# Connexion via curl -curl -u bitcoin:your_password --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "getblockchaininfo", "params": []}' -H 'content-type: text/plain;' http://localhost:18443/ - -# Connexion via bitcoin-cli -docker exec bitcoin-signet bitcoin-cli -signet getblockchaininfo - -# Vérifier la synchronisation -docker exec bitcoin-signet bitcoin-cli -signet getblockchaininfo | jq '.verificationprogress' -``` - -### 2. Blindbit API - -```bash -# Test de connectivité -curl -s http://localhost:8000/ - -# Vérifier le statut -curl -s http://localhost:8000/status - -# Obtenir des filtres -curl -s http://localhost:8000/filters -``` - -### 3. sdk_relay WebSocket - -```bash -# Test de connectivité WebSocket -curl -v -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Key: test" http://localhost:8090/ - -# Test avec wscat (si installé) -wscat -c ws://localhost:8090 - -# Test avec Python -python3 test_websocket_messages.py -``` - -## 🧪 Tests et Validation - -### 1. Tests de Base - -```bash -# Test de connectivité complet -./test_final_sync.sh - -# Test de synchronisation -./test_sync_logs.sh - -# Test des messages -./test_messages.sh - -# Test des 3 relais -./test_3_relays.sh -``` - -### 2. Tests de Performance - -```bash -# Test de charge WebSocket -for i in {1..10}; do - python3 test_websocket_messages.py & -done -wait - -# Test de connectivité multiple -netstat -tlnp | grep -E "(8090|8092|8094)" - -# Test de performance -docker stats --no-stream -``` - -### 3. Tests de Sécurité - -```bash -# Vérifier les ports exposés -netstat -tuln | grep -E "(8090|8092|8094)" - -# Vérifier les logs d'accès -docker logs sdk_relay_1 | grep -E "(ERROR|WARN)" | tail -20 - -# Vérifier l'utilisation des ressources -docker stats --no-stream | grep sdk_relay -``` - -## 🔧 Configuration et Maintenance - -### 1. Modification de Configuration - -```bash -# Modifier la configuration Bitcoin Core -sudo docker-compose down -nano bitcoin/bitcoin.conf -sudo docker-compose up -d bitcoin - -# Modifier la configuration Blindbit -nano blindbit/blindbit.toml -sudo docker-compose restart blindbit - -# Modifier la configuration des relais -nano sdk_relay/.conf.docker.relay1 -sudo docker-compose restart sdk_relay_1 -``` - -### 2. Redémarrage des Services - -```bash -# Redémarrage complet -./restart_4nk_node.sh - -# Redémarrage d'un service spécifique -docker-compose restart bitcoin -docker-compose restart blindbit -docker-compose restart sdk_relay_1 - -# Redémarrage avec reconstruction -docker-compose down -docker-compose build --no-cache -docker-compose up -d -``` - -### 3. Sauvegarde et Restauration - -```bash -# Sauvegarde des données -docker exec bitcoin-signet tar czf /tmp/bitcoin-backup.tar.gz /home/bitcoin/.bitcoin -docker cp bitcoin-signet:/tmp/bitcoin-backup.tar.gz ./backup/ - -# Sauvegarde des configurations -tar czf config-backup.tar.gz sdk_relay/.conf* external_nodes.conf - -# Restauration -docker cp ./backup/bitcoin-backup.tar.gz bitcoin-signet:/tmp/ -docker exec bitcoin-signet tar xzf /tmp/bitcoin-backup.tar.gz -C / -``` - -## 🌐 Gestion des Nœuds Externes - -### 1. Ajout de Nœuds Externes - -```bash -# Ajouter un nœud externe -./add_external_node.sh add external-relay-1 external-relay-1.example.com:8090 - -# Lister les nœuds configurés -./add_external_node.sh list - -# Tester la connectivité -./add_external_node.sh test external-relay-1 - -# Supprimer un nœud -./add_external_node.sh remove external-relay-1 -``` - -### 2. Configuration Multi-Sites - -```bash -# Site principal -./add_external_node.sh add site-paris-1 paris-relay-1.4nk.net:8090 -./add_external_node.sh add site-paris-2 paris-relay-2.4nk.net:8090 - -# Site secondaire -./add_external_node.sh add site-lyon-1 lyon-relay-1.4nk.net:8090 -./add_external_node.sh add site-lyon-2 lyon-relay-2.4nk.net:8090 - -# Site de backup -./add_external_node.sh add backup-1 backup-relay-1.4nk.net:8090 -``` - -### 3. Test d'Intégration - -```bash -# Test d'intégration complet -./test_integration_dev3.sh - -# Test de connectivité dev3 -python3 test_dev3_simple.py - -# Test de connectivité avancé -python3 test_dev3_connectivity.py -``` - -## 📊 Monitoring et Alertes - -### 1. Monitoring de Base - -```bash -# Surveillance de la synchronisation -./monitor_sync.sh - -# Monitoring en continu -while true; do - echo "=== $(date) ===" - docker stats --no-stream | grep -E "(sdk_relay|bitcoin)" - echo "WebSocket connections:" - netstat -an | grep :8090 | wc -l - sleep 30 -done -``` - -### 2. Monitoring Avancé - -```bash -# Script de monitoring complet -cat > monitor_advanced.sh << 'EOF' -#!/bin/bash -while true; do - clear - echo "=== 4NK Node Monitoring ===" - echo "Date: $(date)" - echo "" - - echo "Services:" - docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" - echo "" - - echo "Ressources:" - docker stats --no-stream | grep -E "(sdk_relay|bitcoin|blindbit)" - echo "" - - echo "Connexions WebSocket:" - netstat -an | grep :8090 | wc -l - echo "" - - echo "Espace disque:" - df -h | grep -E "(bitcoin|blindbit)" - echo "" - - sleep 60 -done -EOF - -chmod +x monitor_advanced.sh -./monitor_advanced.sh -``` - -### 3. Alertes Automatiques - -```bash -# Script d'alerte simple -cat > alert_monitor.sh << 'EOF' -#!/bin/bash - -# Vérifier Bitcoin Core -if ! docker ps | grep -q "bitcoin-signet.*Up"; then - echo "ALERTE: Bitcoin Core n'est pas en cours d'exécution!" -fi - -# Vérifier les relais -for i in {1..3}; do - if ! docker ps | grep -q "sdk_relay_$i.*Up"; then - echo "ALERTE: Relay $i n'est pas en cours d'exécution!" - fi -done - -# Vérifier l'espace disque -if [ $(df / | awk 'NR==2 {print $5}' | sed 's/%//') -gt 90 ]; then - echo "ALERTE: Espace disque faible!" -fi -EOF - -chmod +x alert_monitor.sh - -# Ajouter au cron pour surveillance automatique -echo "*/5 * * * * /path/to/alert_monitor.sh" | crontab - -``` - -## 🔒 Sécurité - -### 1. Vérification de Sécurité - -```bash -# Vérifier les ports exposés -netstat -tuln | grep -E "(8090|8092|8094)" - -# Vérifier les permissions -ls -la sdk_relay/.conf* -ls -la bitcoin/bitcoin.conf -ls -la blindbit/blindbit.toml - -# Vérifier les logs de sécurité -docker logs sdk_relay_1 | grep -E "(ERROR|WARN|SECURITY)" | tail -20 -``` - -### 2. Configuration de Pare-feu - -```bash -# Autoriser seulement les ports nécessaires -sudo ufw allow 18443/tcp # Bitcoin Core RPC -sudo ufw allow 8090/tcp # sdk_relay WebSocket -sudo ufw allow 8000/tcp # Blindbit API -sudo ufw enable - -# Vérifier les règles -sudo ufw status numbered -``` - -### 3. Rotation des Logs - -```bash -# Configuration de rotation des logs -cat > /etc/logrotate.d/4nk-node << EOF -/var/lib/docker/containers/*/*.log { - daily - rotate 7 - compress - delaycompress - missingok - notifempty - copytruncate -} -EOF -``` - -## 🚨 Dépannage - -### 1. Problèmes Courants - -#### Service Ne Démarre Pas - -```bash -# Vérifier les logs -docker logs - -# Vérifier la configuration -docker exec cat /path/to/config - -# Redémarrer le service -docker restart -``` - -#### Problèmes de Connectivité - -```bash -# Tester la connectivité réseau -docker exec ping - -# Vérifier la résolution DNS -docker exec nslookup - -# Tester les ports -docker exec nc -z -``` - -#### Problèmes de Synchronisation - -```bash -# Vérifier les logs de synchronisation -docker logs sdk_relay_1 | grep -E "(Sync|Relay|Mesh)" - -# Forcer la synchronisation -docker restart sdk_relay_1 sdk_relay_2 sdk_relay_3 - -# Vérifier la connectivité entre relais -./test_sync_logs.sh force -``` - -### 2. Logs de Debug - -```bash -# Logs détaillés -docker-compose logs -f --tail=100 - -# Logs d'un service spécifique -docker logs -f - -# Logs avec timestamps -docker-compose logs -t - -# Logs depuis une date -docker-compose logs --since="2024-01-01T00:00:00" -``` - -### 3. Outils de Debug - -```bash -# Debug du container sdk_relay -./sdk_relay/debug_container.sh - -# Test du healthcheck -./sdk_relay/test_healthcheck.sh - -# Test de connectivité -./sdk_relay/test_connectivity.sh - -# Test simple -./sdk_relay/test_simple.sh -``` - -## 📈 Performance - -### 1. Optimisation - -```bash -# Limiter l'utilisation CPU -docker-compose up -d --scale bitcoin=1 - -# Optimiser la mémoire -docker stats --no-stream | grep sdk_relay - -# Nettoyer l'espace disque -docker system prune -f -``` - -### 2. Monitoring de Performance - -```bash -# Surveillance des ressources -docker stats - -# Surveillance des connexions -netstat -an | grep :8090 | wc -l - -# Surveillance de l'espace disque -df -h -``` - -### 3. Tests de Charge - -```bash -# Test de charge simple -for i in {1..50}; do - python3 test_websocket_messages.py & - sleep 0.1 -done -wait - -# Test de charge avancé -python3 test_websocket_messages.py --load-test --duration=300 -``` - -## 🔄 Maintenance - -### 1. Sauvegarde Régulière - -```bash -# Script de sauvegarde automatique -cat > backup_4nk.sh << 'EOF' -#!/bin/bash -DATE=$(date +%Y%m%d_%H%M%S) -BACKUP_DIR="/backup/4nk_node_$DATE" - -mkdir -p $BACKUP_DIR - -# Sauvegarder les configurations -cp -r sdk_relay/.conf* $BACKUP_DIR/ -cp external_nodes.conf $BACKUP_DIR/ - -# Sauvegarder les données Bitcoin -docker exec bitcoin-signet tar czf /tmp/bitcoin-backup.tar.gz /home/bitcoin/.bitcoin -docker cp bitcoin-signet:/tmp/bitcoin-backup.tar.gz $BACKUP_DIR/ - -echo "Sauvegarde terminée: $BACKUP_DIR" -EOF - -chmod +x backup_4nk.sh -``` - -### 2. Mise à Jour - -```bash -# Mise à jour de l'infrastructure -git pull origin main -./restart_4nk_node.sh - -# Mise à jour des images -docker-compose build --no-cache -docker-compose up -d -``` - -### 3. Nettoyage - -```bash -# Nettoyer les conteneurs arrêtés -docker container prune -f - -# Nettoyer les images non utilisées -docker image prune -f - -# Nettoyer les volumes non utilisés -docker volume prune -f - -# Nettoyer tout -docker system prune -a -f -``` - -## 📝 Checklist Quotidienne - -- [ ] Services démarrés et fonctionnels -- [ ] Bitcoin Core synchronisé -- [ ] Relais connectés et synchronisés -- [ ] Tests de connectivité passés -- [ ] Logs vérifiés (pas d'erreurs critiques) -- [ ] Ressources système OK -- [ ] Sauvegarde effectuée (si nécessaire) -- [ ] Monitoring actif - -## 🎯 Commandes Rapides - -```bash -# Démarrage rapide -./restart_4nk_node.sh - -# Statut des services -docker ps - -# Logs en temps réel -docker-compose logs -f - -# Test de connectivité -./test_final_sync.sh - -# Surveillance -./monitor_sync.sh - -# Arrêt propre -docker-compose down -``` - ---- - -**✨ Infrastructure - Utilisation optimale !** +## Déploiement +- Voir `docs/DEPLOYMENT.md` +- Contrôles `deployment-checks` en CI diff --git a/docs/project/INDEX.md b/docs/project/INDEX.md new file mode 100644 index 0000000..f765cee --- /dev/null +++ b/docs/project/INDEX.md @@ -0,0 +1,9 @@ +# Index — Documentation du dépôt 4NK_template + +- AGENTS_RUNTIME.md — Exécution des agents +- GITEA_SETUP.md — Configuration Gitea +- SSH_UPDATE.md — Mises à jour des scripts SSH +- DEPLOYMENT.md — Stratégie de déploiement +- SECURITY_AUDIT.md — Audit sécurité (socle template) +- RELEASE_PLAN.md — Plan de release du template +- ROADMAP.md — Roadmap du template diff --git a/docs/project/README.md b/docs/project/README.md new file mode 100644 index 0000000..33ccc93 --- /dev/null +++ b/docs/project/README.md @@ -0,0 +1,10 @@ +# README — 4NK_template + +Ce dépôt fournit un template (docs, CI, scripts, sécurité) pour démarrer des projets 4NK cohérents. + +- Documentation du dépôt: `docs/project/INDEX.md` +- Squelettes pour projets: `docs/templates/INDEX.md` +- Standards qualité: `docs/QUALITY_STANDARDS.md` +- Guide open source: `docs/OPEN_SOURCE_GUIDE.md` + +Agents (contrôles): `scripts/agents/run.sh . tests/reports/agents all` diff --git a/docs/templates/API.md b/docs/templates/API.md new file mode 100644 index 0000000..431560f --- /dev/null +++ b/docs/templates/API.md @@ -0,0 +1,8 @@ +# Référence API — Template + +- Vue d’ensemble +- Authentification/permissions +- Endpoints par domaine (schémas, invariants) +- Codes d’erreur +- Limites et quotas +- Sécurité et conformité diff --git a/docs/templates/ARCHITECTURE.md b/docs/templates/ARCHITECTURE.md new file mode 100644 index 0000000..42b78b2 --- /dev/null +++ b/docs/templates/ARCHITECTURE.md @@ -0,0 +1,8 @@ +# Architecture — Template + +- Contexte et objectifs +- Découpage en couches (UI, services, données) +- Flux principaux +- Observabilité +- CI/CD +- Contraintes et SLA diff --git a/docs/templates/CONFIGURATION.md b/docs/templates/CONFIGURATION.md new file mode 100644 index 0000000..3506069 --- /dev/null +++ b/docs/templates/CONFIGURATION.md @@ -0,0 +1,6 @@ +# Configuration — Template + +- Variables d’environnement (nom, type, défaut, portée) +- Fichiers de configuration (format, validation) +- Réseau et sécurité (ports, TLS, auth) +- Observabilité (logs, métriques, traces) diff --git a/docs/templates/INDEX.md b/docs/templates/INDEX.md new file mode 100644 index 0000000..be566c0 --- /dev/null +++ b/docs/templates/INDEX.md @@ -0,0 +1,12 @@ +# Index — Templates de documentation (pour projets dérivés) + +Utilisez ces squelettes pour démarrer la documentation de votre projet. + +- API.md — squelette de référence API +- ARCHITECTURE.md — squelette d’architecture +- CONFIGURATION.md — squelette de configuration +- USAGE.md — squelette d’usage +- TESTING.md — squelette de stratégie de tests +- SECURITY_AUDIT.md — squelette d’audit sécurité +- RELEASE_PLAN.md — squelette de plan de release +- OPEN_SOURCE_CHECKLIST.md — squelette de checklist open source diff --git a/docs/templates/OPEN_SOURCE_CHECKLIST.md b/docs/templates/OPEN_SOURCE_CHECKLIST.md new file mode 100644 index 0000000..8406e38 --- /dev/null +++ b/docs/templates/OPEN_SOURCE_CHECKLIST.md @@ -0,0 +1,7 @@ +# Checklist open source — Template + +- Gouvernance: LICENSE, CONTRIBUTING, CODE_OF_CONDUCT +- CI/CD: workflows, tests, security-audit, release-guard +- Documentation: README, INDEX, guides essentiels +- Sécurité: secrets, permissions, audit +- Publication: tag, changelog, release notes diff --git a/docs/templates/README.md b/docs/templates/README.md new file mode 100644 index 0000000..5b8a546 --- /dev/null +++ b/docs/templates/README.md @@ -0,0 +1,24 @@ +# README — Template de projet + +## Présentation +Décrivez brièvement l’objectif du projet, son périmètre et ses utilisateurs cibles. + +## Démarrage rapide +- Prérequis (langages/outils) +- Étapes d’installation +- Commandes de démarrage + +## Documentation +- Index: `docs/INDEX.md` +- Architecture: `docs/ARCHITECTURE.md` +- Configuration: `docs/CONFIGURATION.md` +- Tests: `docs/TESTING.md` +- Sécurité: `docs/SECURITY_AUDIT.md` +- Déploiement: `docs/DEPLOYMENT.md` + +## Contribution +- GUIDE: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` +- Processus de PR et revues + +## Licence +- Indiquez la licence choisie (MIT/Apache-2.0/GPL) diff --git a/docs/templates/RELEASE_PLAN.md b/docs/templates/RELEASE_PLAN.md new file mode 100644 index 0000000..ab912bf --- /dev/null +++ b/docs/templates/RELEASE_PLAN.md @@ -0,0 +1,7 @@ +# Plan de release — Template + +- Vue d’ensemble, objectifs, date cible +- Préparation (docs/CI/tests/sécurité) +- Communication (annonces, canaux) +- Lancement (checklist, tagging) +- Post‑lancement (support, retours) diff --git a/docs/templates/SECURITY_AUDIT.md b/docs/templates/SECURITY_AUDIT.md new file mode 100644 index 0000000..3876d6a --- /dev/null +++ b/docs/templates/SECURITY_AUDIT.md @@ -0,0 +1,7 @@ +# Audit de sécurité — Template + +- Menaces et surfaces d’attaque +- Contrôles préventifs et détectifs +- Gestion des secrets +- Politique de dépendances +- Vérifications CI (security-audit) diff --git a/docs/templates/TESTING.md b/docs/templates/TESTING.md new file mode 100644 index 0000000..81a4b51 --- /dev/null +++ b/docs/templates/TESTING.md @@ -0,0 +1,6 @@ +# Tests — Template + +- Pyramide: unit, integration, connectivity, external, performance +- Structure des répertoires +- Exécution et rapports +- Intégration CI diff --git a/docs/templates/USAGE.md b/docs/templates/USAGE.md new file mode 100644 index 0000000..8cad2e9 --- /dev/null +++ b/docs/templates/USAGE.md @@ -0,0 +1,7 @@ +# Usage — Template + +- Démarrage quotidien +- Opérations courantes +- Tests (référence vers TESTING.md) +- Sécurité (référence vers SECURITY_AUDIT.md) +- Déploiement (référence vers DEPLOYMENT.md) diff --git a/scripts/agents/ai_prompt.sh b/scripts/agents/ai_prompt.sh new file mode 100644 index 0000000..9e305ab --- /dev/null +++ b/scripts/agents/ai_prompt.sh @@ -0,0 +1,46 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Utilitaire générique pour appeler l'API OpenAI Chat Completions. +# Prérequis: variable d'environnement OPENAI_API_KEY et curl. + +for bin in curl jq; do + if ! command -v "$bin" >/dev/null 2>&1; then + echo "$bin manquant. Installez $bin." >&2 + exit 2 + fi +done + +MODEL_DEFAULT="gpt-4o-mini" +MODEL="${OPENAI_MODEL:-$MODEL_DEFAULT}" +API_BASE="${OPENAI_API_BASE:-https://api.openai.com/v1}" +TEMPERATURE="${OPENAI_TEMPERATURE:-0.2}" + +read -r -d '' SYSTEM_PROMPT <<'SYS' +Tu es un agent de conformité pour le template 4NK. Réponds en français, sans exemples d'application. Produit des listes d'actions, des risques et des recommandations courtes. Respecte la typographie française. +SYS + +PROMPT="${1:-}" +if [[ -z "${PROMPT}" ]]; then + echo "Usage: $0 'message utilisateur'" >&2 + exit 2 +fi + +if [[ -z "${OPENAI_API_KEY:-}" ]]; then + echo "OPENAI_API_KEY non défini; exécution sans IA (noop)." >&2 + # No-op mode: renvoyer le prompt pour traçabilité + echo "[NO-AI] ${PROMPT}" + exit 0 +fi + +payload=$(jq -n \ + --arg model "$MODEL" \ + --arg system "$SYSTEM_PROMPT" \ + --arg user "$PROMPT" \ + --arg temperature "$TEMPERATURE" \ + '{model: $model, temperature: ($temperature|tonumber? // 0.2), messages: [ {role:"system", content:$system}, {role:"user", content:$user} ] }') + +curl -sS -X POST "${API_BASE}/chat/completions" \ + -H "Authorization: Bearer ${OPENAI_API_KEY}" \ + -H "Content-Type: application/json" \ + -d "$payload" | jq -r '.choices[0].message.content // ""' diff --git a/scripts/agents/compilation_agent.sh b/scripts/agents/compilation_agent.sh new file mode 100644 index 0000000..4b6f991 --- /dev/null +++ b/scripts/agents/compilation_agent.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/compilation_agent.md" + +echo "# Agent Compilation" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +pushd "$TARGET_DIR" >/dev/null +if grep -q "cargo" .gitea/workflows/ci.yml 2>/dev/null; then + echo "- Étapes de build/format/clippy Rust détectées dans la CI." >> "$SUMMARY_FILE" +else + echo "- Étapes de compilation non détectées dans la CI (à ajouter si nécessaire)." >> "$SUMMARY_FILE" +fi + +PROMPT=$(cat <<'P' +Précise une cadence de compilation (avant refactor/push, après update deps) et les conditions de blocage si erreurs. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/dependances_agent.sh b/scripts/agents/dependances_agent.sh new file mode 100644 index 0000000..6e48f56 --- /dev/null +++ b/scripts/agents/dependances_agent.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/dependances_agent.md" + +echo "# Agent Dépendances" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +echo "- Vérifier régulièrement les dépendances (audit sécurité, mises à jour stables)." >> "$SUMMARY_FILE" +pushd "$TARGET_DIR" >/dev/null +if grep -q "security-audit" .gitea/workflows/ci.yml 2>/dev/null; then + echo "- Job CI security-audit détecté." >> "$SUMMARY_FILE" +fi + +PROMPT=$(cat <<'P' +Établis une politique de dépendances: ajout automatique si justifié, vérification des dernières versions stables, documentation des impacts (ARCHITECTURE, CONFIGURATION, CHANGELOG), et rollback. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/deployment_agent.sh b/scripts/agents/deployment_agent.sh new file mode 100644 index 0000000..71c68f3 --- /dev/null +++ b/scripts/agents/deployment_agent.sh @@ -0,0 +1,27 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/deployment_agent.md" + +echo "# Agent Déploiement" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +pushd "$TARGET_DIR" >/dev/null +echo "## Résultats locaux" >> "$SUMMARY_FILE" +ok=1 +for f in docs/DEPLOYMENT.md docs/RELEASE_PLAN.md .gitea/workflows/ci.yml; do + if [[ ! -e "$f" ]]; then echo "- Manquant: $f" >> "$SUMMARY_FILE"; ok=0; fi +done +if [[ $ok -eq 1 ]]; then echo "- Pré‑requis documentaires présents." >> "$SUMMARY_FILE"; fi + +PROMPT=$(cat <<'P' +Établis une checklist de déploiement minimale (pré‑checks, variables, smoke tests, rollback, post‑deploy) adaptée à un template CI Gitea. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/derogations_locales_agent.sh b/scripts/agents/derogations_locales_agent.sh new file mode 100644 index 0000000..89cbef0 --- /dev/null +++ b/scripts/agents/derogations_locales_agent.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/derogations_locales_agent.md" + +echo "# Agent Dérogations locales" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +pushd "$TARGET_DIR" >/dev/null +if [[ -f LOCAL_OVERRIDES.yml || -f .gitea/workflows/LOCAL_OVERRIDES.yml ]]; then + echo "- Fichier de dérogations locales détecté." >> "$SUMMARY_FILE" +else + echo "- Aucun fichier de dérogations locales détecté." >> "$SUMMARY_FILE" +fi + +PROMPT=$(cat <<'P' +Définis un format pour enregistrer les dérogations (path, raison, propriétaire, échéance), tolérance CI, et revue périodique. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/documentation_agent.sh b/scripts/agents/documentation_agent.sh new file mode 100644 index 0000000..a4ba05f --- /dev/null +++ b/scripts/agents/documentation_agent.sh @@ -0,0 +1,32 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/documentation_agent.md" + +echo "# Agent Documentation" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +pushd "$TARGET_DIR" >/dev/null +required=(docs/INDEX.md docs/ARCHITECTURE.md docs/TESTING.md docs/SECURITY_AUDIT.md docs/DEPLOYMENT.md) +missing=() +for f in "${required[@]}"; do [[ -f "$f" ]] || missing+=("$f"); done + +echo "## Résultats locaux" >> "$SUMMARY_FILE" +if ((${#missing[@]}==0)); then + echo "- Documentation essentielle présente." >> "$SUMMARY_FILE" +else + echo "- Fichiers manquants:" >> "$SUMMARY_FILE" + for m in "${missing[@]}"; do echo " - $m" >> "$SUMMARY_FILE"; done +fi + +PROMPT=$(cat <<'P' +Élabore une liste courte d’améliorations documentation (INDEX à jour, traçabilité changes ↔ CHANGELOG, sections sécurité/tests/déploiement). +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/documents_bureautiques_agent.sh b/scripts/agents/documents_bureautiques_agent.sh new file mode 100644 index 0000000..4bdc1e7 --- /dev/null +++ b/scripts/agents/documents_bureautiques_agent.sh @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/documents_bureautiques_agent.md" + +echo "# Agent Documents bureautiques" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +pushd "$TARGET_DIR" >/dev/null +docsx=$(git ls-files '*.docx' 2>/dev/null || true) +if [[ -z "$docsx" ]]; then + echo "- Aucun fichier .docx détecté." >> "$SUMMARY_FILE" +else + echo "- .docx détectés:" >> "$SUMMARY_FILE" + echo "$docsx" | sed 's/^/ - /' >> "$SUMMARY_FILE" + echo "- Utiliser docx2txt pour extraction et documenter dans docs/INDEX.md" >> "$SUMMARY_FILE" +fi + +PROMPT=$(cat <<'P' +Décris une procédure standard de traitement des .docx (docx2txt, import, traçabilité dans docs/INDEX.md) et les risques à éviter. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/donnees_csv_agent.sh b/scripts/agents/donnees_csv_agent.sh new file mode 100644 index 0000000..8b2d910 --- /dev/null +++ b/scripts/agents/donnees_csv_agent.sh @@ -0,0 +1,28 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/donnees_csv_agent.md" + +echo "# Agent Données CSV" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +pushd "$TARGET_DIR" >/dev/null +csvs=$(git ls-files '*.csv' 2>/dev/null || true) +if [[ -z "$csvs" ]]; then + echo "- Aucun CSV détecté dans le dépôt." >> "$SUMMARY_FILE" +else + echo "- CSV détectés:" >> "$SUMMARY_FILE" + echo "$csvs" | sed 's/^/ - /' >> "$SUMMARY_FILE" +fi + +PROMPT=$(cat <<'P' +À partir des CSV présents (en‑têtes multi‑lignes possibles), propose une méthode pour définir toutes les colonnes, types et validations, et pointer vers les docs à mettre à jour (API, ARCHITECTURE, USAGE). +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/fondation_agent.sh b/scripts/agents/fondation_agent.sh new file mode 100644 index 0000000..68817aa --- /dev/null +++ b/scripts/agents/fondation_agent.sh @@ -0,0 +1,28 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/fondation_agent.md" + +echo "# Agent Fondation" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +issues=0 +# Vérification basique: fichiers de gouvernance présents +pushd "$TARGET_DIR" >/dev/null +for f in README.md CODE_OF_CONDUCT.md CONTRIBUTING.md LICENSE; do + if [[ ! -f "$f" ]]; then echo "- Manquant: $f" >> "$SUMMARY_FILE"; issues=$((issues+1)); fi +done + +if [[ $issues -eq 0 ]]; then echo "- Conformité éditoriale de base: OK (présence des fichiers clés)." >> "$SUMMARY_FILE"; fi + +PROMPT=$(cat <<'P' +Évalue la conformité éditoriale (français, pas d’exemples applicatifs, intro/conclusion) et liste 5 actions d’amélioration priorisées. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/frontend_agent.sh b/scripts/agents/frontend_agent.sh new file mode 100644 index 0000000..71b80a1 --- /dev/null +++ b/scripts/agents/frontend_agent.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/frontend_agent.md" + +echo "# Agent Frontend" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +PROMPT=$(cat <<'P' +Définis des principes front: code splitting (React.lazy/Suspense), centralisation d’état (Redux/Context), abstraction des services, et tests associés. +P +) +pushd "$TARGET_DIR" >/dev/null +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/gitea_agent.sh b/scripts/agents/gitea_agent.sh new file mode 100644 index 0000000..cdd7081 --- /dev/null +++ b/scripts/agents/gitea_agent.sh @@ -0,0 +1,30 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/gitea_agent.md" + +echo "# Agent Gitea" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +pushd "$TARGET_DIR" >/dev/null +need=(.gitea/ISSUE_TEMPLATE/bug_report.md .gitea/ISSUE_TEMPLATE/feature_request.md .gitea/PULL_REQUEST_TEMPLATE.md .gitea/workflows/ci.yml) +missing=() +for f in "${need[@]}"; do [[ -f "$f" ]] || missing+=("$f"); done + +if ((${#missing[@]}==0)); then + echo "- Configuration Gitea présente." >> "$SUMMARY_FILE" +else + echo "- Manquants:" >> "$SUMMARY_FILE"; for m in "${missing[@]}"; do echo " - $m" >> "$SUMMARY_FILE"; done +fi + +PROMPT=$(cat <<'P' +Propose des vérifications CI additionnelles Gitea (lint, tests, sécurité, scripts exécutables) et notifications en cas d’échecs. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/lang_detect.sh b/scripts/agents/lang_detect.sh new file mode 100644 index 0000000..cd2d313 --- /dev/null +++ b/scripts/agents/lang_detect.sh @@ -0,0 +1,41 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Détection de langages et outillages par conventions de fichiers. +# À sourcer depuis les agents. Utilise le répertoire courant comme racine projet. + +has_file() { [[ -f "$1" ]]; } +has_dir() { [[ -d "$1" ]]; } +has_bin() { command -v "$1" >/dev/null 2>&1; } + +export HAS_NODE=0 HAS_TYPESCRIPT=0 HAS_GO=0 HAS_RUST=0 HAS_PYTHON=0 HAS_SHELL_BASH=0 HAS_SHELL_PWSH=0 + +# Node / TypeScript +if has_file package.json; then HAS_NODE=1; fi +if has_file tsconfig.json || git ls-files '*.ts' | grep -q . 2>/dev/null; then HAS_TYPESCRIPT=1; fi + +# Go +if has_file go.mod || has_file go.work; then HAS_GO=1; fi + +# Rust +if has_file Cargo.toml; then HAS_RUST=1; fi + +# Python +if has_file pyproject.toml || has_file requirements.txt || git ls-files '*.py' | grep -q . 2>/dev/null; then HAS_PYTHON=1; fi + +# Shell (bash) +if git ls-files '*.sh' | grep -q . 2>/dev/null; then HAS_SHELL_BASH=1; fi + +# PowerShell (pwsh) +if git ls-files '*.ps1' | grep -q . 2>/dev/null; then HAS_SHELL_PWSH=1; fi + +# Exposer aussi l'état des outils lorsqu’ils existent +export HAS_NPM=0 HAS_NPX=0 HAS_GO_BIN=0 HAS_CARGO=0 HAS_PYTHON_BIN=0 HAS_PIP=0 HAS_SHELLCHECK=0 HAS_PWSH=0 +has_bin npm && HAS_NPM=1 +has_bin npx && HAS_NPX=1 +has_bin go && HAS_GO_BIN=1 +has_bin cargo && HAS_CARGO=1 +has_bin python && HAS_PYTHON_BIN=1 || true +has_bin pip && HAS_PIP=1 || true +has_bin shellcheck && HAS_SHELLCHECK=1 || true +has_bin pwsh && HAS_PWSH=1 || true diff --git a/scripts/agents/open_source_agent.sh b/scripts/agents/open_source_agent.sh new file mode 100644 index 0000000..b653f63 --- /dev/null +++ b/scripts/agents/open_source_agent.sh @@ -0,0 +1,30 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/open_source_agent.md" + +echo "# Agent Open Source" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +pushd "$TARGET_DIR" >/dev/null +need=(LICENSE CONTRIBUTING.md CODE_OF_CONDUCT.md docs/OPEN_SOURCE_CHECKLIST.md) +missing=() +for f in "${need[@]}"; do [[ -f "$f" ]] || missing+=("$f"); done + +if ((${#missing[@]}==0)); then + echo "- Pré‑requis open source présents." >> "$SUMMARY_FILE" +else + echo "- Manquants:" >> "$SUMMARY_FILE"; for m in "${missing[@]}"; do echo " - $m" >> "$SUMMARY_FILE"; done +fi + +PROMPT=$(cat <<'P' +Propose une checklist pour préparer l’ouverture open source (gouvernance, CI, sécurité, documentation) compatible avec Gitea. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/performance_agent.sh b/scripts/agents/performance_agent.sh new file mode 100644 index 0000000..4982a6b --- /dev/null +++ b/scripts/agents/performance_agent.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/performance_agent.md" + +echo "# Agent Performance" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +pushd "$TARGET_DIR" >/dev/null +if [[ -d tests/performance ]]; then + echo "- Dossier tests/performance présent." >> "$SUMMARY_FILE" +else + echo "- Dossier tests/performance manquant." >> "$SUMMARY_FILE" +fi + +PROMPT=$(cat <<'P' +Propose un plan minimal de tests de performance reproductibles (outillage, métriques, critères de succès) et archivage des rapports. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/qualite_formelle.sh b/scripts/agents/qualite_formelle.sh new file mode 100644 index 0000000..8f0d255 --- /dev/null +++ b/scripts/agents/qualite_formelle.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/qualite_formelle.md" + +echo "# Agent Qualité formelle" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +# Contrôles basiques +issues=0 +pushd "$TARGET_DIR" >/dev/null +if grep -R "RESUME" docs/ >/dev/null 2>&1; then + echo "- Placeholder 'RESUME' détecté dans docs/ (à remplacer)." >> "$SUMMARY_FILE"; issues=$((issues+1)) +fi + +echo "## Résultats locaux" >> "$SUMMARY_FILE" +if [[ $issues -eq 0 ]]; then + echo "- Aucun problème formel bloquant détecté." >> "$SUMMARY_FILE" +fi + +PROMPT=$(cat <<'P' +Évalue la qualité formelle (français uniquement, typographie, absence d’exemples applicatifs, intro/conclusion) et propose 5 recommandations priorisées. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/quality_tech.sh b/scripts/agents/quality_tech.sh new file mode 100644 index 0000000..5daabe0 --- /dev/null +++ b/scripts/agents/quality_tech.sh @@ -0,0 +1,84 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" + +SUMMARY_FILE="$OUTPUT_DIR/quality_tech.md" + +# Checks de base (adaptés à ce template) +mapfile -t required_files < <(cat <<'REQ' +README.md +LICENSE +CONTRIBUTING.md +CODE_OF_CONDUCT.md +CHANGELOG.md +docs/INDEX.md +docs/ARCHITECTURE.md +docs/TESTING.md +.gitea/workflows/ci.yml +REQ +) + +pushd "$TARGET_DIR" >/dev/null +missing=() +for f in "${required_files[@]}"; do + [[ -f "$f" ]] || missing+=("$f") +done + +echo "# Agent Qualité technique" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" +echo "## Résultats locaux" >> "$SUMMARY_FILE" +if ((${#missing[@]}==0)); then + echo "- Tous les fichiers requis sont présents." >> "$SUMMARY_FILE" +else + echo "- Fichiers manquants:" >> "$SUMMARY_FILE" + for m in "${missing[@]}"; do echo " - $m" >> "$SUMMARY_FILE"; done +fi + +# Détection des langages et contrôles best‑effort +source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lang_detect.sh" +echo >> "$SUMMARY_FILE" +echo "## Contrôles automatiques (best‑effort)" >> "$SUMMARY_FILE" +if [[ "$HAS_RUST" -eq 1 && "$HAS_CARGO" -eq 1 ]]; then + (cargo check -q && echo "- Rust: cargo check OK" >> "$SUMMARY_FILE") || echo "- Rust: cargo check a signalé des problèmes" >> "$SUMMARY_FILE" +fi +if [[ "$HAS_GO" -eq 1 && "$HAS_GO_BIN" -eq 1 ]]; then + (go vet ./... >/dev/null 2>&1 && echo "- Go: go vet OK" >> "$SUMMARY_FILE") || echo "- Go: go vet a signalé des problèmes" >> "$SUMMARY_FILE" +fi +if [[ "$HAS_NODE" -eq 1 && "$HAS_NPX" -eq 1 ]]; then + (npx -y --yes -- eslint . >/dev/null 2>&1 && echo "- Node: eslint OK" >> "$SUMMARY_FILE") || echo "- Node: eslint non exécuté ou problèmes" >> "$SUMMARY_FILE" + if [[ "$HAS_TYPESCRIPT" -eq 1 ]]; then + (npx -y --yes -- tsc --noEmit >/dev/null 2>&1 && echo "- TS: tsc --noEmit OK" >> "$SUMMARY_FILE") || echo "- TS: tsc a signalé des problèmes" >> "$SUMMARY_FILE" + fi +fi +if [[ "$HAS_PYTHON" -eq 1 ]]; then + if command -v ruff >/dev/null 2>&1; then + (ruff . >/dev/null 2>&1 && echo "- Python: ruff OK" >> "$SUMMARY_FILE") || echo "- Python: ruff a signalé des problèmes" >> "$SUMMARY_FILE" + elif command -v flake8 >/dev/null 2>&1; then + (flake8 . >/dev/null 2>&1 && echo "- Python: flake8 OK" >> "$SUMMARY_FILE") || echo "- Python: flake8 a signalé des problèmes" >> "$SUMMARY_FILE" + else + echo "- Python: aucun linter détecté (ruff/flake8)" >> "$SUMMARY_FILE" + fi +fi +if [[ "$HAS_SHELL_BASH" -eq 1 ]]; then + if [[ "$HAS_SHELLCHECK" -eq 1 ]]; then + (git ls-files '*.sh' | xargs -r shellcheck >/dev/null 2>&1 && echo "- Shell: shellcheck OK" >> "$SUMMARY_FILE") || echo "- Shell: shellcheck a signalé des problèmes" >> "$SUMMARY_FILE" + else + echo "- Shell: shellcheck non disponible" >> "$SUMMARY_FILE" + fi +fi +if [[ "$HAS_SHELL_PWSH" -eq 1 && "$HAS_PWSH" -eq 1 ]]; then + echo "- PowerShell: PSScriptAnalyzer recommandé" >> "$SUMMARY_FILE" +fi + +# IA (optionnelle) +PROMPT=$(cat <<'P' +Analyse la conformité qualité technique du dépôt selon AGENTS.md et la CI. Priorise: lint/format/type-check, structure de tests, cohérence docs/CI, sécurité basique. Propose 5 actions concrètes. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/resolution_agent.sh b/scripts/agents/resolution_agent.sh new file mode 100644 index 0000000..c8a8e35 --- /dev/null +++ b/scripts/agents/resolution_agent.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/resolution_agent.md" + +echo "# Agent Résolution" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +pushd "$TARGET_DIR" >/dev/null +if [[ -d archive ]]; then + echo "- Dossier archive/ présent (pour REX)." >> "$SUMMARY_FILE" +else + echo "- Dossier archive/ manquant (recommandé pour REX)." >> "$SUMMARY_FILE" +fi + +PROMPT=$(cat <<'P' +Décris la boucle de triage complète (repro minimale, logs, bissection, hypothèses, tests ciblés, correctif, non‑régression) et quand produire un REX. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/run.ps1 b/scripts/agents/run.ps1 new file mode 100644 index 0000000..4accb1a --- /dev/null +++ b/scripts/agents/run.ps1 @@ -0,0 +1,140 @@ +Param( + [string]$TargetDir='.', + [string]$OutputDir='tests/reports/agents', + [string]$Agent='all' +) + +$bashOk = $false +try { + & bash -lc 'echo ok' | Out-Null + if ($LASTEXITCODE -eq 0) { $bashOk = $true } +} catch {} + +if ($bashOk) { + & bash "scripts/agents/run.sh" $TargetDir $OutputDir $Agent + exit $LASTEXITCODE +} + +# Fallback PowerShell (best-effort) lorsque bash n'est pas disponible +New-Item -ItemType Directory -Force -Path $OutputDir | Out-Null + +function Write-Report($name, $lines) { + $file = Join-Path $OutputDir $name + $lines | Out-File -FilePath $file -Encoding UTF8 -Force + Write-Host "Rapport: $file" +} + +Set-Location $TargetDir + +switch ($Agent) { + 'documentation' { + $missing = @() + $required = @('docs/INDEX.md','docs/project/INDEX.md','docs/templates/INDEX.md') + foreach ($f in $required) { if (-not (Test-Path $f)) { $missing += $f } } + $content = @('# Agent Documentation', '', '## Résultats (fallback PowerShell)') + if ($missing.Count -eq 0) { $content += '- Documentation essentielle présente.' } + else { $content += '- Fichiers manquants:'; $missing | ForEach-Object { $content += " - $_" } } + Write-Report 'documentation_agent.md' $content + } + 'tests' { + $need = @('tests/unit','tests/integration','tests/connectivity','tests/external','tests/performance','tests/logs','tests/reports') + $missing = @(); foreach ($d in $need) { if (-not (Test-Path $d)) { $missing += $d } } + $content = @('# Agent Tests', '', '## Résultats (fallback PowerShell)') + if ($missing.Count -eq 0) { $content += '- Structure de tests conforme.' } else { $content += '- Dossiers manquants:'; $missing | ForEach-Object { $content += " - $_" } } + Write-Report 'tests_agent.md' $content + } + 'performance' { + $content = @('# Agent Performance', '', '## Résultats (fallback PowerShell)') + if (Test-Path 'tests/performance') { $content += '- tests/performance présent.' } else { $content += '- tests/performance manquant.' } + Write-Report 'performance_agent.md' $content + } + 'quality-technique' { + $missing = @() + $required = @('README.md','LICENSE','CONTRIBUTING.md','CODE_OF_CONDUCT.md','CHANGELOG.md','.gitea/workflows/ci.yml') + foreach ($f in $required) { if (-not (Test-Path $f)) { $missing += $f } } + $content = @('# Agent Qualité technique', '', '## Résultats (fallback PowerShell)') + if ($missing.Count -eq 0) { $content += '- Fichiers de base présents.' } + else { $content += '- Fichiers manquants:'; $missing | ForEach-Object { $content += " - $_" } } + Write-Report 'quality_tech.md' $content + } + 'open-source' { + $missing = @() + $required = @('LICENSE','CONTRIBUTING.md','CODE_OF_CONDUCT.md','docs/OPEN_SOURCE_CHECKLIST.md') + foreach ($f in $required) { if (-not (Test-Path $f)) { $missing += $f } } + $content = @('# Agent Open Source', '', '## Résultats (fallback PowerShell)') + if ($missing.Count -eq 0) { $content += '- Pré‑requis open source présents.' } + else { $content += '- Manquants:'; $missing | ForEach-Object { $content += " - $_" } } + Write-Report 'open_source_agent.md' $content + } + 'securite' { + $missing = @(); foreach ($f in @('docs/SECURITY_AUDIT.md','.gitea/workflows/ci.yml')) { if (-not (Test-Path $f)) { $missing += $f } } + $content = @('# Agent Sécurité', '', '## Résultats (fallback PowerShell)') + if ($missing.Count -eq 0) { $content += '- Socle sécurité et CI présents.' } else { $content += '- Manquants:'; $missing | ForEach-Object { $content += " - $_" } } + Write-Report 'security_agent.md' $content + } + 'deploiement' { + $missing = @(); foreach ($f in @('docs/DEPLOYMENT.md','.gitea/workflows/ci.yml')) { if (-not (Test-Path $f)) { $missing += $f } } + $content = @('# Agent Déploiement', '', '## Résultats (fallback PowerShell)') + if ($missing.Count -eq 0) { $content += '- Documentation et CI de déploiement présentes (à valider).' } else { $content += '- Manquants:'; $missing | ForEach-Object { $content += " - $_" } } + Write-Report 'deployment_agent.md' $content + } + 'dependances' { + $content = @('# Agent Dépendances', '', '## Résultats (fallback PowerShell)','- Politique à documenter dans ARCHITECTURE/CONFIGURATION/CHANGELOG') + Write-Report 'dependances_agent.md' $content + } + 'compilation' { + $content = @('# Agent Compilation', '', '## Résultats (fallback PowerShell)') + if (Test-Path '.gitea/workflows/ci.yml') { $content += '- Étapes de build à vérifier dans la CI.' } else { $content += '- CI absente.' } + Write-Report 'compilation_agent.md' $content + } + 'resolution' { + $content = @('# Agent Résolution', '', '## Résultats (fallback PowerShell)') + if (Test-Path 'archive') { $content += '- Dossier archive/ présent pour REX.' } else { $content += '- Dossier archive/ manquant.' } + Write-Report 'resolution_agent.md' $content + } + 'ssh-scripts' { + $found = @(); $paths = @('scripts/auto-ssh-push.sh','scripts/init-ssh-env.sh','scripts/setup-ssh-ci.sh','scripts/scripts/auto-ssh-push.sh','scripts/scripts/init-ssh-env.sh','scripts/scripts/setup-ssh-ci.sh') + foreach ($p in $paths) { if (Test-Path $p) { $found += $p } } + $content = @('# Agent SSH & scripts', '', '## Résultats (fallback PowerShell)') + if ($found.Count -gt 0) { $content += '- Scripts trouvés:'; $found | ForEach-Object { $content += " - $_" } } else { $content += '- Aucun script standard détecté.' } + if (Test-Path 'docs/SSH_UPDATE.md') { $content += '- docs/SSH_UPDATE.md présent.' } + Write-Report 'ssh_scripts_agent.md' $content + } + 'frontend' { + $content = @('# Agent Frontend', '', '## Résultats (fallback PowerShell)','- Vérifier code splitting, état centralisé, abstraction services (si frontend présent).') + Write-Report 'frontend_agent.md' $content + } + 'gitea' { + $need = @('.gitea/ISSUE_TEMPLATE/bug_report.md','.gitea/ISSUE_TEMPLATE/feature_request.md','.gitea/PULL_REQUEST_TEMPLATE.md','.gitea/workflows/ci.yml') + $missing = @(); foreach ($f in $need) { if (-not (Test-Path $f)) { $missing += $f } } + $content = @('# Agent Gitea', '', '## Résultats (fallback PowerShell)') + if ($missing.Count -eq 0) { $content += '- Configuration Gitea présente.' } else { $content += '- Manquants:'; $missing | ForEach-Object { $content += " - $_" } } + Write-Report 'gitea_agent.md' $content + } + 'versionnage' { + $missing = @(); foreach ($f in @('CHANGELOG.md','TEMPLATE_VERSION')) { if (-not (Test-Path $f)) { $missing += $f } } + $content = @('# Agent Versionnage', '', '## Résultats (fallback PowerShell)') + if ($missing.Count -eq 0) { $content += '- CHANGELOG et TEMPLATE_VERSION présents.' } else { $content += '- Manquants:'; $missing | ForEach-Object { $content += " - $_" } } + Write-Report 'versionnage_agent.md' $content + } + 'sync-template' { + $content = @('# Agent Synchronisation de template', '', '## Résultats (fallback PowerShell)') + if (Test-Path '.gitea/workflows/template-sync.yml') { $content += '- Workflow template-sync présent.' } else { $content += '- Workflow template-sync manquant.' } + if (Test-Path '.4nk-sync.yml') { $content += '- Manifeste .4nk-sync.yml présent.' } else { $content += '- Manifeste .4nk-sync.yml manquant.' } + Write-Report 'sync_template_agent.md' $content + } + 'derogations-locales' { + $content = @('# Agent Dérogations locales', '', '## Résultats (fallback PowerShell)') + if ((Test-Path 'LOCAL_OVERRIDES.yml') -or (Test-Path '.gitea/workflows/LOCAL_OVERRIDES.yml')) { $content += '- Fichier de dérogations détecté.' } else { $content += '- Aucun fichier de dérogations détecté.' } + Write-Report 'derogations_locales_agent.md' $content + } + 'all' { + foreach ($a in @('documentation','tests','performance','quality-technique','open-source','securite','deploiement','dependances','compilation','resolution','ssh-scripts','frontend','gitea','versionnage','sync-template','derogations-locales')) { + & $PSCommandPath -TargetDir $TargetDir -OutputDir $OutputDir -Agent $a + } + } + default { + Write-Error "Agent inconnu (fallback): $Agent"; exit 2 + } +} +exit 0 diff --git a/scripts/agents/run.sh b/scripts/agents/run.sh new file mode 100644 index 0000000..0247530 --- /dev/null +++ b/scripts/agents/run.sh @@ -0,0 +1,97 @@ +#!/usr/bin/env bash +set -euo pipefail + +DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" + +mkdir -p "$OUTPUT_DIR" + +usage() { + cat <&2; usage; exit 2 ;; +esac + +echo "Agents terminés → $OUTPUT_DIR" diff --git a/scripts/agents/security_agent.sh b/scripts/agents/security_agent.sh new file mode 100644 index 0000000..a83d883 --- /dev/null +++ b/scripts/agents/security_agent.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/security_agent.md" + +echo "# Agent Sécurité" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +pushd "$TARGET_DIR" >/dev/null +echo "## Résultats locaux" >> "$SUMMARY_FILE" +if [[ -x scripts/security/audit.sh ]]; then + if scripts/security/audit.sh >> "$SUMMARY_FILE" 2>&1; then + echo "- Audit sécurité scripté exécuté (voir détails ci‑dessus)." >> "$SUMMARY_FILE" + else + echo "- Audit a signalé des problèmes (ci‑dessus)." >> "$SUMMARY_FILE" + fi +else + echo "- scripts/security/audit.sh introuvable ou non exécutable." >> "$SUMMARY_FILE" +fi + +PROMPT=$(cat <<'P' +À partir d’un dépôt template, propose 5 contrôles sécurité CI/CD additionnels (secrets, permissions, dépendances, scans) et un ordre de priorité. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/ssh_scripts_agent.sh b/scripts/agents/ssh_scripts_agent.sh new file mode 100644 index 0000000..0335526 --- /dev/null +++ b/scripts/agents/ssh_scripts_agent.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/ssh_scripts_agent.md" + +echo "# Agent SSH & scripts" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +pushd "$TARGET_DIR" >/dev/null +paths=( + scripts/auto-ssh-push.sh + scripts/init-ssh-env.sh + scripts/setup-ssh-ci.sh + scripts/scripts/auto-ssh-push.sh + scripts/scripts/init-ssh-env.sh + scripts/scripts/setup-ssh-ci.sh +) + +found=0 +for p in "${paths[@]}"; do + if [[ -f "$p" ]]; then echo "- Trouvé: $p" >> "$SUMMARY_FILE"; found=1; fi +done +if [[ $found -eq 0 ]]; then echo "- Scripts SSH standard introuvables (vérifier l’arborescence)." >> "$SUMMARY_FILE"; fi + +if [[ -f docs/SSH_UPDATE.md ]]; then echo "- docs/SSH_UPDATE.md présent." >> "$SUMMARY_FILE"; fi + +PROMPT=$(cat <<'P' +Propose une checklist de conformité SSH (permissions, secrets CI, idempotence, journalisation non sensible) et intégration de contrôles CI. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/structure_agent.sh b/scripts/agents/structure_agent.sh new file mode 100644 index 0000000..79bfe32 --- /dev/null +++ b/scripts/agents/structure_agent.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/structure_agent.md" + +echo "# Agent Structure" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +pushd "$TARGET_DIR" >/dev/null +need=(docs .gitea scripts CHANGELOG.md AGENTS.md) +missing=() +for p in "${need[@]}"; do [[ -e "$p" ]] || missing+=("$p"); done + +if ((${#missing[@]}==0)); then + echo "- Arborescence de base présente." >> "$SUMMARY_FILE" +else + echo "- Éléments manquants:" >> "$SUMMARY_FILE" + for m in "${missing[@]}"; do echo " - $m" >> "$SUMMARY_FILE"; done +fi + +PROMPT=$(cat <<'P' +Vérifie l’alignement avec l’arborescence 4NK_node et propose 5 corrections prioritaires (créations/archives/métadonnées) si des écarts sont détectés. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/sync_template_agent.sh b/scripts/agents/sync_template_agent.sh new file mode 100644 index 0000000..5ab5b64 --- /dev/null +++ b/scripts/agents/sync_template_agent.sh @@ -0,0 +1,32 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/sync_template_agent.md" + +echo "# Agent Synchronisation de template" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +pushd "$TARGET_DIR" >/dev/null +if [[ -f .gitea/workflows/template-sync.yml ]]; then + echo "- Workflow template-sync présent." >> "$SUMMARY_FILE" +else + echo "- Workflow template-sync manquant." >> "$SUMMARY_FILE" +fi + +if [[ -f .4nk-sync.yml ]]; then + echo "- Manifeste .4nk-sync.yml présent." >> "$SUMMARY_FILE" +else + echo "- Manifeste .4nk-sync.yml manquant." >> "$SUMMARY_FILE" +fi + +PROMPT=$(cat <<'P' +Propose une procédure de synchronisation contrôlée (PR dédiée, vérif checksums/manifest_checksum, mise à jour TEMPLATE_VERSION, mise à jour CHANGELOG/INDEX). +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/tests_agent.sh b/scripts/agents/tests_agent.sh new file mode 100644 index 0000000..af5e690 --- /dev/null +++ b/scripts/agents/tests_agent.sh @@ -0,0 +1,33 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/tests_agent.md" + +echo "# Agent Tests" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +# Vérifier existence structure +pushd "$TARGET_DIR" >/dev/null +need=(tests/unit tests/integration tests/connectivity tests/external tests/performance tests/logs tests/reports) +missing=() +for d in "${need[@]}"; do [[ -d "$d" ]] || missing+=("$d"); done + +echo "## Résultats locaux" >> "$SUMMARY_FILE" +if ((${#missing[@]}==0)); then + echo "- Structure de tests conforme au template." >> "$SUMMARY_FILE" +else + echo "- Dossiers manquants:" >> "$SUMMARY_FILE" + for m in "${missing[@]}"; do echo " - $m" >> "$SUMMARY_FILE"; done +fi + +PROMPT=$(cat <<'P' +Propose un plan court pour renforcer la pyramide de tests (unit, integration, connectivity, external, performance) pour ce template, avec 5 actions. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/scripts/agents/versionnage_agent.sh b/scripts/agents/versionnage_agent.sh new file mode 100644 index 0000000..26177b7 --- /dev/null +++ b/scripts/agents/versionnage_agent.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash +set -euo pipefail + +TARGET_DIR="${1:-.}" +OUTPUT_DIR="${2:-tests/reports/agents}" +mkdir -p "$OUTPUT_DIR" +SUMMARY_FILE="$OUTPUT_DIR/versionnage_agent.md" + +echo "# Agent Versionnage" > "$SUMMARY_FILE" +echo >> "$SUMMARY_FILE" + +pushd "$TARGET_DIR" >/dev/null +ok=1 +for f in CHANGELOG.md TEMPLATE_VERSION; do + if [[ ! -f "$f" ]]; then echo "- Manquant: $f" >> "$SUMMARY_FILE"; ok=0; fi +done +if [[ $ok -eq 1 ]]; then echo "- CHANGELOG et TEMPLATE_VERSION présents." >> "$SUMMARY_FILE"; fi + +PROMPT=$(cat <<'P' +Décris la procédure d’alignement version ↔ changelog ↔ tag git (latest vs wip) et conditions de blocage release. +P +) +"scripts/agents/ai_prompt.sh" "$PROMPT" >> "$SUMMARY_FILE" || true + +echo "Rapport: $SUMMARY_FILE" +popd >/dev/null diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..ffbbbd6 --- /dev/null +++ b/tests/README.md @@ -0,0 +1,25 @@ +# Tests — stratégie et organisation + +Ce répertoire décrit la stratégie et l’organisation des tests exigées par le template 4NK. + +## Pyramide de tests +- Unit: validation des unités logicielles +- Integration: interactions multi-composants +- Connectivity: réseau et endpoints +- External: dépendances externes +- Performance: charge et temps de réponse + +## Exécution +- Local: exécuter les suites pertinentes et déposer les résultats dans `tests/reports` +- CI: orchestrée par `.gitea/workflows/ci.yml` + +## Journaux et rapports +- `tests/logs`: journaux d’exécution +- `tests/reports`: rapports synthétiques + +## Nettoyage +Utiliser `tests/cleanup.sh` après exécution. + +## Critères d’acceptation +- Zéro échec avant commit +- Documentation associée à jour dans `docs/TESTING.md` diff --git a/tests/cleanup.sh b/tests/cleanup.sh new file mode 100644 index 0000000..00f23b5 --- /dev/null +++ b/tests/cleanup.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Nettoyage des artefacts de tests +rm -rf "$(dirname "$0")/logs"/* 2>/dev/null || true +rm -rf "$(dirname "$0")/reports"/* 2>/dev/null || true + +echo "Nettoyage des journaux et rapports terminé." diff --git a/tests/connectivity/.gitkeep b/tests/connectivity/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tests/external/.gitkeep b/tests/external/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tests/integration/.gitkeep b/tests/integration/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tests/performance/.gitkeep b/tests/performance/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tests/unit/.gitkeep b/tests/unit/.gitkeep new file mode 100644 index 0000000..e69de29