seo-generator-server/GOOGLE_SHEET_VERSIONING_SPEC.md

📊 SPÉCIFICATION GOOGLE SHEET POUR VERSIONING

Structure Complete pour Sauvegarde par Étapes

Date: 6 septembre 2025
Version: 2.0 avec versioning
Objectif: Tracer chaque étape du pipeline modulaire

---

🎯 CONCEPT : VERSIONING PAR ÉTAPES

Workflow de Sauvegarde

1. v1.0 - initial_generation        → Row X
2. v1.1 - selective_enhancement     → Row X+1
3. v1.2 - adversarial_enhancement   → Row X+2  
4. v1.3 - human_simulation          → Row X+3
5. v1.4 - pattern_breaking          → Row X+4
6. v2.0 - final_version             → Row X+5

Chaque version = 1 ligne complète avec le contenu compilé de cette étape.

---

📋 STRUCTURE GOOGLE SHEET REQUISE

Nom du Sheet : Generated_Articles_Versioned

Colonne	Nom	Type	Description	Exemple
A	Timestamp	DateTime	Format français DD/MM/YYYY HH:mm:ss	06/09/2025 15:42:33
B	Slug	String	Identifiant unique article	plaque-numero-maison
C	MC0	String	Mot-clé principal	plaque numero de maison
D	T0	String	Titre principal	Créer une plaque personnalisée
E	Personality	String	Personnalité IA utilisée	Marc
F	AntiDetection_Level	String	Niveau anti-détection	MVP
G	Compiled_Text	Long Text	CONTENU FINAL COMPILÉ	Texte complet organique...
H	Text_Length	Number	Longueur en caractères	4582
I	Word_Count	Number	Nombre de mots	745
J	Elements_Count	Number	Nombre d'éléments générés	16
K	LLM_Used	String	Modèle principal utilisé	claude
L	Validation_Status	String	Statut validation	completed
M	Version 🆕	String	Numéro de version	v1.0, v1.1, v2.0
N	Stage 🆕	String	Étape du pipeline	initial_generation
O	Stage_Description 🆕	String	Description détaillée étape	Génération base sans amélioration
P	Parent_Article_ID 🆕	Number	ID article parent	123 (vide pour v1.0)
Q	GPTZero_Score	Number	Score détecteur GPTZero	25
R	Originality_Score	Number	Score originalité	87
S	CopyLeaks_Score	Number	Score CopyLeaks	12
T	Human_Quality_Score	Number	Score qualité humaine	92
U	Full_Metadata_JSON	JSON	Métadonnées complètes + historique	{csvData, config, versionHistory}

---

🔄 EXEMPLE CONCRET DE DONNÉES

Article "plaque-numero-maison" - Toutes Versions

A	B	M	N	O	P	G (extract)
06/09/2025 15:42:33	plaque-numero-maison	v1.0	initial_generation	Génération base sans amélioration		Créer une plaque personnalisée...
06/09/2025 15:43:15	plaque-numero-maison	v1.1	selective_enhancement	Amélioration selective (standardEnhancement) - 12 modifications	123	Créer une plaque personnalisée élégante...
06/09/2025 15:44:02	plaque-numero-maison	v1.2	adversarial_enhancement	Amélioration adversarial (light) - 8 modifications	123	Concevoir une plaque personnalisée raffinée...
06/09/2025 15:45:12	plaque-numero-maison	v1.3	human_simulation	Simulation humaine (standardSimulation) - 15 modifications	123	Concevoir une plaque vraiment personnalisée...
06/09/2025 15:46:08	plaque-numero-maison	v1.4	pattern_breaking	Pattern Breaking (lightPatternBreaking) - 6 modifications	123	Concevoir une plaque véritablement personnalisée...
06/09/2025 15:47:21	plaque-numero-maison	v2.0	final_version	Version finale complète avec toutes améliorations	123	Concevoir une plaque véritablement personnalisée...

---

🎛️ STAGES POSSIBLES

Stage	Description	Version Typique
initial_generation	Génération de base sans amélioration	v1.0
selective_enhancement	Amélioration selective (tech/style/transitions)	v1.1
adversarial_enhancement	Amélioration adversarial (anti-détection)	v1.2
human_simulation	Simulation humaine (erreurs, fatigue, style)	v1.3
pattern_breaking	Cassage de patterns IA	v1.4
final_version	Version finale assemblée	v2.0

---

🔗 LINKAGE PARENT-ENFANT

Principe

• Article Parent (v1.0) : Parent_Article_ID = vide
• Versions Dérivées (v1.1+) : Parent_Article_ID = ID de v1.0

Retrouver toutes versions d'un article

-- Pseudo-requête Google Sheets
WHERE (ID = 123) OR (Parent_Article_ID = 123)
ORDER BY Version ASC

Statistiques par Article

-- Compter versions par article
COUNT(*) WHERE Parent_Article_ID = 123 OR ID = 123

---

📊 AVANTAGES DU SYSTÈME

✅ Traçabilité Complète

• Chaque étape du pipeline visible
• Évolution du contenu tracée
• Métriques par étape

✅ Comparaison Facile

• A/B test entre versions
• Impact de chaque amélioration
• Régression possible si nécessaire

✅ Analytics Poussés

• Efficacité par étape
• Patterns d'amélioration
• ROI des améliorations

✅ Flexibilité

• Activer/désactiver sauvegarde : saveIntermediateSteps: false
• Pipeline partiel possible
• Versioning optionnel

---

🚀 API POUR UTILISATION

Endpoint Serveur

POST /api/workflow-modulaire
Content-Type: application/json

{
  "rowNumber": 2,
  "selectiveStack": "standardEnhancement", 
  "adversarialMode": "light",
  "humanSimulationMode": "standardSimulation",
  "patternBreakingMode": "lightPatternBreaking",
  "saveIntermediateSteps": true
}

Réponse Type

{
  "success": true,
  "message": "Workflow modulaire terminé avec succès (6 versions sauvegardées)",
  "stats": {
    "versionsCreated": 6,
    "parentArticleId": 123,
    "finalArticleId": 128,
    "duration": 125000
  },
  "versionHistory": [
    {"version": "v1.0", "stage": "initial_generation", "articleId": 123},
    {"version": "v1.1", "stage": "selective_enhancement", "articleId": 124},
    {"version": "v2.0", "stage": "final_version", "articleId": 128}
  ],
  "result": {
    "parentArticleId": 123,
    "finalArticleId": 128,
    "modificationsCount": 41,
    "finalWordCount": 756
  }
}

---

🎯 COMMANDES D'UTILISATION

Via CLI (main_modulaire.js)

# Workflow complet avec sauvegarde
node lib/main_modulaire.js workflow 2 standardEnhancement light standardSimulation

# Les sauvegardes par étapes sont ACTIVÉES par défaut
# Pour désactiver : modifier saveIntermediateSteps: false dans le code

Via Serveur

# Démarrer serveur
npm start

# Utiliser endpoint API
curl -X POST http://localhost:3000/api/workflow-modulaire \
  -H "Content-Type: application/json" \
  -d '{"rowNumber": 2, "saveIntermediateSteps": true}'

---

🔧 CONFIGURATION SHEET

Permissions Requises

• Google Sheets API : Lecture/Écriture
• Service Account : Configuré dans .env
• Sheet ID : 1iA2GvWeUxX-vpnAMfVm3ZMG9LhaC070SdGssEcXAh2c

Variables Env Nécessaires

GOOGLE_SERVICE_ACCOUNT_EMAIL=your-service@project.iam.gserviceaccount.com
GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..."

---

🎯 Cette spécification permet un suivi complet de chaque étape du pipeline modulaire avec traçabilité complète et analytics détaillés.

---

Spécification générée automatiquement le 6 septembre 2025
Claude Code - Système de Versioning Modulaire