StillHammer/seo-generator-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
master
seo-generator-server/GOOGLE_SHEET_VERSIONING_SPEC.md
Trouve Alexis 870cfb0340 [200~add step-by-step versioning system with Google Sheets integration 
- Add intermediate saves (v1.0-v1.4) to Generated_Articles_Versioned
  - Fix compiled_text pipeline (generatedTexts object structure)
  - Add /api/workflow-modulaire endpoint with version tracking
  - Create test-modulaire.html interface with real-time logs
  - Support parent-child linking via Parent_Article_ID
2025-09-06 16:38:20 +08:00

216 lines
7.4 KiB
Markdown
Raw Permalink Blame History

# 📊 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
```sql
-- Pseudo-requête Google Sheets
WHERE (ID = 123) OR (Parent_Article_ID = 123)
ORDER BY Version ASC
```
### Statistiques par Article
```sql
-- 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
```bash
POST /api/workflow-modulaire
Content-Type: application/json
{
"rowNumber": 2,
"selectiveStack": "standardEnhancement",
"adversarialMode": "light",
"humanSimulationMode": "standardSimulation",
"patternBreakingMode": "lightPatternBreaking",
"saveIntermediateSteps": true
}
```
### Réponse Type
```json
{
"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)
```bash
# 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
```bash
# 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
```bash
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*
Reference in New Issue View Git Blame Copy Permalink