docs: Add comprehensive documentation for all new features
- FEATURES_OVERVIEW.md: Complete summary of all system features - ANALYTICS.md: Analytics and reporting system documentation - ODOO_INTEGRATION.md: Odoo ERP integration guide - AB_TESTING.md: A/B testing system documentation - CONTENT_RECYCLING.md: Content recycling system docs - THREAD_SERIES.md: Thread series and scheduled posts - IMAGE_TEMPLATES.md: Visual template system documentation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
297
docs/AB_TESTING.md
Normal file
297
docs/AB_TESTING.md
Normal file
@@ -0,0 +1,297 @@
|
||||
# A/B Testing
|
||||
|
||||
Sistema de pruebas A/B para optimizar contenido y maximizar engagement.
|
||||
|
||||
## Descripción
|
||||
|
||||
El A/B Testing permite comparar diferentes versiones de contenido para determinar cuál tiene mejor rendimiento. El sistema:
|
||||
|
||||
1. Crea múltiples variantes de contenido
|
||||
2. Publica cada variante
|
||||
3. Recopila métricas de cada una
|
||||
4. Determina estadísticamente el ganador
|
||||
|
||||
## Modelos de Datos
|
||||
|
||||
### ABTest
|
||||
|
||||
```python
|
||||
ABTest:
|
||||
id: int
|
||||
name: str
|
||||
description: str
|
||||
test_type: str # content, timing, hashtags, image
|
||||
|
||||
platform: str # x, threads, instagram, facebook
|
||||
status: str # draft, running, completed, cancelled
|
||||
|
||||
started_at: datetime
|
||||
ended_at: datetime
|
||||
duration_hours: int # Duración del test (default 24)
|
||||
|
||||
winning_variant_id: int (FK)
|
||||
confidence_level: float # Nivel de confianza estadística
|
||||
|
||||
min_sample_size: int # Mín impresiones por variante (default 100)
|
||||
success_metric: str # engagement_rate, likes, comments, shares
|
||||
```
|
||||
|
||||
### ABTestVariant
|
||||
|
||||
```python
|
||||
ABTestVariant:
|
||||
id: int
|
||||
test_id: int (FK -> ab_tests)
|
||||
name: str # A, B, C, D
|
||||
|
||||
content: str
|
||||
hashtags: JSON
|
||||
image_url: str
|
||||
|
||||
post_id: int (FK -> posts)
|
||||
|
||||
# Métricas
|
||||
impressions: int
|
||||
reach: int
|
||||
likes: int
|
||||
comments: int
|
||||
shares: int
|
||||
clicks: int
|
||||
engagement_rate: float
|
||||
|
||||
is_winner: bool
|
||||
published_at: datetime
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### GET /api/ab-tests/
|
||||
Lista todos los tests A/B.
|
||||
|
||||
**Parámetros:**
|
||||
- `status`: draft, running, completed, cancelled
|
||||
- `platform`: x, threads, etc.
|
||||
- `limit` (int, default=20)
|
||||
|
||||
**Respuesta:**
|
||||
```json
|
||||
{
|
||||
"tests": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Test de copies",
|
||||
"platform": "x",
|
||||
"status": "running",
|
||||
"variants": [...]
|
||||
}
|
||||
],
|
||||
"count": 5
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/ab-tests/{test_id}
|
||||
Obtiene un test específico con sus variantes.
|
||||
|
||||
### POST /api/ab-tests/
|
||||
Crea un nuevo test A/B.
|
||||
|
||||
**Body:**
|
||||
```json
|
||||
{
|
||||
"name": "Test de copies para tips",
|
||||
"platform": "x",
|
||||
"variants": [
|
||||
{
|
||||
"name": "A",
|
||||
"content": "💡 Tip: Automatiza tus procesos con IA...",
|
||||
"hashtags": ["#IA", "#Automatización"]
|
||||
},
|
||||
{
|
||||
"name": "B",
|
||||
"content": "¿Sabías que la IA puede ahorrarte 10 horas semanales?...",
|
||||
"hashtags": ["#Productividad", "#Tech"]
|
||||
}
|
||||
],
|
||||
"test_type": "content",
|
||||
"duration_hours": 24,
|
||||
"min_sample_size": 100,
|
||||
"success_metric": "engagement_rate"
|
||||
}
|
||||
```
|
||||
|
||||
**Validaciones:**
|
||||
- Mínimo 2 variantes, máximo 4
|
||||
- Cada variante debe tener contenido
|
||||
|
||||
### POST /api/ab-tests/{test_id}/start
|
||||
Inicia un test A/B.
|
||||
|
||||
**Proceso:**
|
||||
1. Crea posts para cada variante
|
||||
2. Programa publicación (escalonada cada 5 min)
|
||||
3. Cambia status a "running"
|
||||
4. Registra start_time
|
||||
|
||||
**Respuesta:**
|
||||
```json
|
||||
{
|
||||
"message": "A/B test started successfully",
|
||||
"success": true,
|
||||
"test_id": 1,
|
||||
"post_ids": [101, 102],
|
||||
"variants_count": 2
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/ab-tests/{test_id}/evaluate
|
||||
Evalúa resultados y determina ganador.
|
||||
|
||||
**Proceso:**
|
||||
1. Actualiza métricas de cada variante
|
||||
2. Verifica tamaño de muestra mínimo
|
||||
3. Ejecuta test estadístico (chi-square)
|
||||
4. Determina ganador y confianza
|
||||
5. Si duration_hours pasó, marca como completed
|
||||
|
||||
**Respuesta:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"winner": {
|
||||
"variant_id": 1,
|
||||
"name": "A",
|
||||
"engagement_rate": 4.5,
|
||||
"impressions": 1500
|
||||
},
|
||||
"runner_up": {
|
||||
"variant_id": 2,
|
||||
"name": "B",
|
||||
"engagement_rate": 3.2,
|
||||
"impressions": 1400
|
||||
},
|
||||
"confidence_level": 95.5,
|
||||
"p_value": 0.045,
|
||||
"test_status": "completed"
|
||||
}
|
||||
```
|
||||
|
||||
**Si datos insuficientes:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"status": "insufficient_data",
|
||||
"min_impressions": 50,
|
||||
"required": 100
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/ab-tests/{test_id}/results
|
||||
Obtiene resultados actuales (sin determinar ganador).
|
||||
|
||||
### POST /api/ab-tests/{test_id}/cancel
|
||||
Cancela un test en progreso.
|
||||
|
||||
## Tareas Programadas
|
||||
|
||||
### evaluate_ab_tests
|
||||
- **Frecuencia:** Cada hora
|
||||
- **Función:**
|
||||
- Busca tests en estado "running"
|
||||
- Si pasó duration_hours, evalúa y completa
|
||||
- Si no, solo actualiza métricas
|
||||
|
||||
## Tipos de Test
|
||||
|
||||
| Tipo | Descripción |
|
||||
|------|-------------|
|
||||
| `content` | Prueba diferentes textos |
|
||||
| `timing` | Prueba diferentes horarios |
|
||||
| `hashtags` | Prueba diferentes conjuntos de hashtags |
|
||||
| `image` | Prueba diferentes imágenes |
|
||||
|
||||
## Métricas de Éxito
|
||||
|
||||
| Métrica | Descripción |
|
||||
|---------|-------------|
|
||||
| `engagement_rate` | (likes + comments + shares) / impressions |
|
||||
| `likes` | Total de likes |
|
||||
| `comments` | Total de comentarios |
|
||||
| `shares` | Total de compartidos |
|
||||
| `clicks` | Total de clics (si aplica) |
|
||||
|
||||
## Análisis Estadístico
|
||||
|
||||
El sistema usa el **test chi-cuadrado** para determinar significancia estadística:
|
||||
|
||||
```python
|
||||
# Tabla de contingencia
|
||||
[
|
||||
[engagements_A, non_engagements_A],
|
||||
[engagements_B, non_engagements_B]
|
||||
]
|
||||
|
||||
chi2, p_value, dof, expected = scipy.stats.chi2_contingency(tabla)
|
||||
confidence = (1 - p_value) * 100
|
||||
```
|
||||
|
||||
### Interpretación
|
||||
|
||||
| p-value | Confianza | Interpretación |
|
||||
|---------|-----------|----------------|
|
||||
| < 0.01 | > 99% | Muy significativo |
|
||||
| < 0.05 | > 95% | Significativo |
|
||||
| < 0.10 | > 90% | Marginalmente significativo |
|
||||
| ≥ 0.10 | < 90% | No significativo |
|
||||
|
||||
## Flujo de Trabajo
|
||||
|
||||
```
|
||||
1. Crear Test (status: draft)
|
||||
↓
|
||||
2. Iniciar Test (status: running)
|
||||
- Crea posts para variantes
|
||||
- Programa publicación
|
||||
↓
|
||||
3. Esperar duración
|
||||
- Sistema recopila métricas cada 15 min
|
||||
- Evalúa cada hora
|
||||
↓
|
||||
4. Evaluar Resultados (status: completed)
|
||||
- Determina ganador estadístico
|
||||
- Calcula nivel de confianza
|
||||
```
|
||||
|
||||
## Ejemplo de Uso
|
||||
|
||||
```python
|
||||
from app.services.ab_testing_service import ab_testing_service
|
||||
|
||||
# Crear test
|
||||
test = await ab_testing_service.create_test(
|
||||
name="Test de engagement",
|
||||
platform="x",
|
||||
variants=[
|
||||
{"name": "A", "content": "Versión corta y directa"},
|
||||
{"name": "B", "content": "Versión más elaborada con detalles"}
|
||||
],
|
||||
duration_hours=48,
|
||||
min_sample_size=200
|
||||
)
|
||||
|
||||
# Iniciar
|
||||
result = await ab_testing_service.start_test(test.id)
|
||||
|
||||
# Evaluar (después de publicado)
|
||||
results = await ab_testing_service.evaluate_test(test.id)
|
||||
if results.get("winner"):
|
||||
print(f"Ganador: Variante {results['winner']['name']}")
|
||||
print(f"Confianza: {results['confidence_level']:.1f}%")
|
||||
```
|
||||
|
||||
## Mejores Prácticas
|
||||
|
||||
1. **Tamaño de muestra:** Espera al menos 100 impresiones por variante
|
||||
2. **Una variable:** Prueba solo un elemento a la vez
|
||||
3. **Duración:** Mínimo 24 horas para datos representativos
|
||||
4. **Horarios:** Publica variantes en horarios similares
|
||||
5. **Confianza:** Busca > 95% antes de tomar decisiones
|
||||
Reference in New Issue
Block a user