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:
334
docs/THREAD_SERIES.md
Normal file
334
docs/THREAD_SERIES.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user