social-media-automation/docs/THREAD_SERIES.md

# Thread Series

Sistema para crear y publicar hilos de múltiples posts conectados.

## Descripción

Los Thread Series permiten:
- Crear contenido largo dividido en posts conectados
- Generar hilos con IA
- Programar publicación escalonada
- Mantener cadena de respuestas (reply chain)

## Modelos de Datos

### ThreadSeries

```python
ThreadSeries:
    id: int
    name: str
    description: str
    topic: str

    platform: str  # x, threads

    # Configuración de programación
    schedule_type: str  # sequential, timed
    interval_minutes: int  # Tiempo entre posts (default 5)
    start_time: datetime

    # Estado
    total_posts: int
    posts_published: int
    status: str  # draft, scheduled, publishing, completed, paused, cancelled

    # Reply chain
    first_platform_post_id: str  # ID del primer post (para replies)

    # IA
    ai_generated: bool
    generation_prompt: str

    hashtags: JSON  # Hashtags comunes
```

### ThreadPost

```python
ThreadPost:
    id: int
    series_id: int (FK -> thread_series)
    sequence_number: int  # 1, 2, 3...

    content: str
    image_url: str

    post_id: int (FK -> posts)

    # Para reply chain
    platform_post_id: str
    reply_to_platform_id: str

    scheduled_at: datetime
    status: str  # pending, scheduled, published, failed
    error_message: str
    published_at: datetime
```

## API Endpoints

### GET /api/threads/
Lista todas las series.

**Parámetros:**
- `status`: draft, scheduled, publishing, completed
- `platform`: x, threads
- `limit` (int, default=20)

### GET /api/threads/{series_id}
Obtiene una serie con todos sus posts.

**Respuesta:**
```json
{
    "id": 1,
    "name": "Hilo sobre IA",
    "topic": "Inteligencia Artificial",
    "platform": "x",
    "status": "scheduled",
    "total_posts": 5,
    "posts_published": 0,
    "start_time": "2025-02-01T10:00:00",
    "interval_minutes": 5,
    "posts": [
        {
            "id": 1,
            "sequence_number": 1,
            "content": "🧵 Hilo: Todo sobre IA...",
            "status": "scheduled",
            "scheduled_at": "2025-02-01T10:00:00"
        },
        {
            "id": 2,
            "sequence_number": 2,
            "content": "1/ La IA está transformando...",
            "status": "scheduled",
            "scheduled_at": "2025-02-01T10:05:00"
        }
    ]
}
```

### POST /api/threads/
Crea una serie manualmente.

**Body:**
```json
{
    "name": "Tips de productividad",
    "platform": "x",
    "posts": [
        {"content": "🧵 Hilo: 5 tips para ser más productivo"},
        {"content": "1/ Usa la técnica Pomodoro..."},
        {"content": "2/ Elimina distracciones..."},
        {"content": "3/ Prioriza con Eisenhower..."},
        {"content": "4/ Automatiza tareas repetitivas..."},
        {"content": "5/ Revisa tu progreso diario..."}
    ],
    "description": "Tips de productividad para profesionales",
    "schedule_type": "sequential",
    "interval_minutes": 3,
    "hashtags": ["#Productividad", "#Tips"]
}
```

**Validaciones:**
- Mínimo 2 posts, máximo 20
- Platform requerido

### POST /api/threads/generate
Genera un hilo con IA.

**Body:**
```json
{
    "topic": "Cómo empezar con inteligencia artificial",
    "platform": "x",
    "num_posts": 5,
    "style": "educational",
    "name": "Intro a IA"  // Opcional: si se incluye, guarda la serie
}
```

**Estilos disponibles:**
- `educational`: Contenido informativo y didáctico
- `storytelling`: Formato narrativo
- `tips`: Lista de consejos prácticos

**Respuesta (sin name):**
```json
{
    "message": "Thread generated (not saved)",
    "generated_posts": [
        {"sequence": 1, "content": "🧵 Te explico qué es la IA..."},
        {"sequence": 2, "content": "1/ La IA es..."}
    ],
    "count": 5
}
```

**Respuesta (con name):**
```json
{
    "message": "Thread generated and saved",
    "series": {...},
    "generated_posts": [...]
}
```

### POST /api/threads/{series_id}/schedule
Programa una serie para publicación.

**Body (opcional):**
```json
{
    "start_time": "2025-02-01T10:00:00"
}
```

Si no se especifica, inicia en 5 minutos.

**Proceso:**
1. Crea posts reales para cada ThreadPost
2. Programa cada uno con el intervalo configurado
3. Cambia status a "scheduled"

**Respuesta:**
```json
{
    "message": "Series scheduled successfully",
    "success": true,
    "series_id": 1,
    "start_time": "2025-02-01T10:00:00",
    "posts_scheduled": 5
}
```

### POST /api/threads/{series_id}/publish-next
Publica manualmente el siguiente post de la serie.

### POST /api/threads/{series_id}/cancel
Cancela una serie y sus posts programados.

## Tareas Programadas

### check_thread_schedules
- **Frecuencia:** Cada minuto
- **Función:**
  - Busca ThreadPosts programados para ahora
  - Encola tarea de publicación
  - Actualiza estado

### update_thread_post_status
- **Trigger:** Después de publicar un post
- **Función:**
  - Actualiza estado del ThreadPost
  - Guarda platform_post_id (para reply chain)
  - Actualiza progreso de la serie
  - Marca serie como completed si todos publicados

## Tipos de Programación

| Tipo | Descripción |
|------|-------------|
| `sequential` | Posts uno tras otro con intervalo fijo |
| `timed` | Posts en horarios específicos (próximamente) |

## Reply Chain

Para que los posts aparezcan como respuestas:

1. Se publica el primer post
2. Se guarda su `platform_post_id`
3. Los siguientes posts se publican como respuesta al anterior
4. Cada uno guarda su `reply_to_platform_id`

```
Post 1 (original)
  └── Post 2 (reply to 1)
       └── Post 3 (reply to 2)
            └── Post 4 (reply to 3)
```

## Ejemplo de Uso

```python
from app.services.thread_service import thread_service

# Crear serie manual
series = await thread_service.create_series(
    name="Tips de Python",
    platform="x",
    posts_content=[
        {"content": "🧵 Hilo: 5 tips de Python que debes conocer"},
        {"content": "1/ List comprehensions..."},
        {"content": "2/ F-strings..."},
        {"content": "3/ Context managers..."},
        {"content": "4/ Generators..."},
        {"content": "5/ Decorators..."}
    ],
    interval_minutes=3
)

# Generar con IA
result = await thread_service.generate_thread_with_ai(
    topic="Beneficios de la automatización",
    platform="threads",
    num_posts=5,
    style="storytelling"
)

# Programar
await thread_service.schedule_series(
    series_id=series.id,
    start_time=datetime(2025, 2, 1, 10, 0)
)

# Ver estado
series = await thread_service.get_series(series.id)
print(f"Publicados: {series['posts_published']}/{series['total_posts']}")
```

## Flujo Completo

```
1. Crear Serie
   - Manual: Proporcionar posts
   - IA: Generar con prompt
        ↓
2. Revisar y Editar
   - Verificar contenido
   - Ajustar hashtags
        ↓
3. Programar
   - Establecer start_time
   - Crear posts reales
        ↓
4. Publicación Automática
   - Celery Beat cada minuto
   - Publica posts programados
   - Mantiene reply chain
        ↓
5. Completado
   - Todos los posts publicados
   - Status: completed
```

## Mejores Prácticas

1. **Primer post atractivo:** El 1/5 o 🧵 debe captar atención
2. **Numeración clara:** "1/", "2/" o "1.", "2."
3. **Intervalos cortos:** 3-5 minutos mantienen engagement
4. **Último post con CTA:** Llamado a la acción al final
5. **Hashtags solo al final:** No saturar cada post
6. **Máximo 10-15 posts:** Hilos muy largos pierden audiencia

## Plataformas Soportadas

| Plataforma | Reply Chain | Notas |
|------------|-------------|-------|
| X (Twitter) | ✅ | Ideal para threads |
| Threads | ✅ | Buen soporte |
| Instagram | ❌ | No soporta threads |
| Facebook | ❌ | No soporta threads |