trading-platform/orchestration/tareas/TASK-2026-02-06-ANALISIS-INTEGRAL-DOCUMENTACION/subagentes/prompts/PROMPT-SA-14.md

id	agent_id	model	type	fase	scope	mode	created
PROMPT-SA-14	SA-14	claude-sonnet-4.5	General background	FASE-3	Create US/RF/ET docs para OQI-010 (F3.9)	write	2026-02-06

PROMPT-SA-14: Create US/RF/ET Docs para OQI-010 (P2)

Contexto

Eres un agente ejecutor de documentación de requisitos. Se ha identificado un gap P2: el módulo OQI-010 (LLM & Chatbot) NO tiene documentación de User Stories, Requisitos Funcionales ni Especificaciones Técnicas.

Proyecto: trading-platform Módulo: OQI-010 - LLM & Chatbot Esquema DDL: llm (6 tablas) Backend: Services y controllers en apps/backend/src/modules/llm/ (si existe)

Objetivo: Crear 9 documentos completos usando prefijo LTI (LLM Technical Integration):

1. User Stories (3 docs): LTI-US-001, LTI-US-002, LTI-US-003
2. Requisitos Funcionales (3 docs): LTI-RF-001, LTI-RF-002, LTI-RF-003
3. Especificaciones Técnicas (3 docs): LTI-ET-001, LTI-ET-002, LTI-ET-003

Instrucciones

PASO 1: Analizar módulo OQI-010

1. Leer README de OQI-010:

   • docs/modulos-negocio/definitions/OQI-010-LLM/README.md
   • Entender alcance, funcionalidades esperadas

2. Analizar schema DDL llm:

   • Leer database/schemas/XX-llm.sql (buscar archivo correcto)
   • Identificar las 6 tablas: chatbot_conversations, chatbot_messages, chatbot_intents, etc.
   • Entender modelo de datos

3. Revisar backend (si existe):

   • Buscar apps/backend/src/services/chatbot.service.ts o similar
   • Identificar endpoints existentes

PASO 2: Definir 3 Épicas (User Stories)

Épica 1 - Conversaciones Chatbot:

• Como usuario, quiero iniciar conversaciones con el chatbot
• Como usuario, quiero enviar mensajes y recibir respuestas
• Como usuario, quiero ver historial de conversaciones

Épica 2 - Análisis de Intenciones:

• Como sistema, necesito clasificar intenciones del usuario
• Como sistema, debo generar respuestas contextuales
• Como admin, quiero entrenar/mejorar intenciones

Épica 3 - Asistencia de Trading:

• Como trader, quiero recomendaciones del chatbot basadas en mi portfolio
• Como trader, quiero análisis de mercado en lenguaje natural
• Como trader, quiero alertas personalizadas del chatbot

PASO 3: Crear 3 User Stories (LTI-US-XXX.md)

Ubicación: docs/modulos-negocio/definitions/OQI-010-LLM/user-stories/

Plantilla por User Story:

---
id: LTI-US-001
epic: Conversaciones Chatbot
module: OQI-010
priority: P1
status: draft
version: 1.0.0
date: 2026-02-06
---

# LTI-US-001: Gestión de Conversaciones con Chatbot

## Épica
Conversaciones Chatbot

## User Story
**Como** usuario autenticado
**Quiero** iniciar conversaciones con el chatbot y enviar mensajes
**Para** obtener asistencia en tiempo real sobre trading y mercados

## Criterios de Aceptación

### Escenario 1: Iniciar nueva conversación
- **Dado que** soy un usuario autenticado
- **Cuando** accedo a la interfaz del chatbot
- **Entonces** se crea automáticamente una nueva conversación
- **Y** veo un mensaje de bienvenida del chatbot
- **Y** puedo comenzar a escribir mensajes

### Escenario 2: Enviar mensaje y recibir respuesta
- **Dado que** tengo una conversación activa
- **Cuando** envío un mensaje (ej: "¿Cuál es el precio de BTC?")
- **Entonces** el mensaje se guarda en la BD
- **Y** el chatbot procesa la intención
- **Y** recibo una respuesta relevante en < 2 segundos
- **Y** la respuesta se muestra en la interfaz

### Escenario 3: Ver historial de conversaciones
- **Dado que** he tenido conversaciones previas
- **Cuando** accedo a la sección de historial
- **Entonces** veo lista de mis últimas 20 conversaciones
- **Y** puedo filtrar por fecha/tema
- **Y** puedo reabrir cualquier conversación

## Requisitos Funcionales Derivados
- RF-001: CRUD de conversaciones
- RF-002: CRUD de mensajes
- RF-003: Procesamiento de intenciones
- RF-004: Generación de respuestas

## Especificaciones Técnicas Relacionadas
- ET-001: API de conversaciones
- ET-002: Integración con LLM (OpenAI/Claude)
- ET-003: Schema `llm.chatbot_conversations` y `llm.chatbot_messages`

## Modelos de Datos Involucrados
- `llm.chatbot_conversations` (id, user_id, created_at, updated_at, status)
- `llm.chatbot_messages` (id, conversation_id, role, content, intent_id, created_at)

## Wireframes / UI
[Referencia a diseños si existen]

## Estimación
- **Complejidad:** Media
- **Story Points:** 8
- **Tiempo estimado:** 2-3 días

## Dependencias
- OQI-001 (Auth) - Requiere autenticación
- Integración con API de LLM (OpenAI/Claude API)

## Notas Técnicas
- Usar WebSocket para mensajes en tiempo real (opcional)
- Implementar rate limiting (10 mensajes/minuto por usuario)
- Mensajes almacenados para análisis posterior

---

## Historial de Cambios
| Versión | Fecha | Cambios |
|---------|-------|---------|
| 1.0.0 | 2026-02-06 | Creación inicial |

Crear 3 archivos:

1. LTI-US-001.md - Conversaciones Chatbot
2. LTI-US-002.md - Análisis de Intenciones
3. LTI-US-003.md - Asistencia de Trading

PASO 4: Crear 3 Requisitos Funcionales (LTI-RF-XXX.md)

Ubicación: docs/modulos-negocio/definitions/OQI-010-LLM/requisitos-funcionales/

Plantilla:

---
id: LTI-RF-001
module: OQI-010
category: CRUD
priority: P1
version: 1.0.0
date: 2026-02-06
---

# LTI-RF-001: CRUD de Conversaciones Chatbot

## Descripción General
El sistema debe permitir crear, leer, actualizar y eliminar conversaciones entre usuarios y el chatbot.

## Requisitos Funcionales Detallados

### RF-001.1: Crear Conversación
- **Input:** `user_id` (UUID)
- **Proceso:**
  1. Validar que usuario existe y está autenticado
  2. Crear registro en `llm.chatbot_conversations`
  3. Asignar status inicial: `active`
  4. Generar mensaje de bienvenida automático
- **Output:** Objeto `Conversation` con `id`, `user_id`, `created_at`, `status`
- **Validaciones:**
  - Usuario debe estar autenticado
  - No más de 5 conversaciones activas simultáneas por usuario

### RF-001.2: Listar Conversaciones de Usuario
- **Input:** `user_id` (UUID), `pagination` (page, limit), `filters` (date_from, date_to, status)
- **Proceso:**
  1. Consultar `llm.chatbot_conversations` WHERE `user_id = ?`
  2. Aplicar filtros y paginación
  3. Ordenar por `updated_at DESC`
- **Output:** Array de objetos `Conversation`, metadata de paginación
- **Performance:** < 200ms (p95)

### RF-001.3: Obtener Conversación por ID
- **Input:** `conversation_id` (UUID), `user_id` (UUID)
- **Proceso:**
  1. Validar que conversación existe
  2. Validar que conversación pertenece al usuario
  3. Cargar mensajes asociados (últimos 50)
- **Output:** Objeto `Conversation` con array de `Messages`
- **Errores:**
  - 404 si conversación no existe
  - 403 si usuario no es dueño

### RF-001.4: Actualizar Conversación
- **Input:** `conversation_id`, `updates` (status, metadata)
- **Proceso:** Update en `llm.chatbot_conversations`
- **Output:** Objeto `Conversation` actualizado

### RF-001.5: Eliminar Conversación (Soft Delete)
- **Input:** `conversation_id`, `user_id`
- **Proceso:**
  1. Validar permisos
  2. Actualizar `status = 'deleted'`
  3. Mantener registros en BD (auditoría)
- **Output:** Confirmación de eliminación

## Reglas de Negocio
1. Las conversaciones se archivan automáticamente después de 30 días de inactividad
2. Usuarios free: máximo 10 conversaciones/mes
3. Usuarios premium: ilimitado
4. Mensajes se retienen por 1 año

## Casos de Prueba
1. **TC-001.1:** Crear conversación con usuario válido → Success
2. **TC-001.2:** Crear conversación sin autenticación → Error 401
3. **TC-001.3:** Listar conversaciones vacías → Array vacío
4. **TC-001.4:** Acceder conversación de otro usuario → Error 403
5. **TC-001.5:** Soft delete conversación → status='deleted'

## Especificaciones Técnicas Relacionadas
- ET-001: API Endpoints `/api/v1/chatbot/conversations`
- ET-003: Schema DDL `llm.chatbot_conversations`

---

## Historial de Cambios
| Versión | Fecha | Cambios |
|---------|-------|---------|
| 1.0.0 | 2026-02-06 | Creación inicial |

Crear 3 archivos:

1. LTI-RF-001.md - CRUD Conversaciones
2. LTI-RF-002.md - Procesamiento de Intenciones
3. LTI-RF-003.md - Generación de Respuestas con LLM

PASO 5: Crear 3 Especificaciones Técnicas (LTI-ET-XXX.md)

Ubicación: docs/modulos-negocio/definitions/OQI-010-LLM/especificaciones-tecnicas/

Plantilla:

---
id: LTI-ET-001
module: OQI-010
category: API
priority: P1
version: 1.0.0
date: 2026-02-06
---

# LTI-ET-001: API de Conversaciones Chatbot

## Resumen
Especificación técnica de los endpoints REST para gestión de conversaciones chatbot.

## Endpoints

### 1. POST /api/v1/chatbot/conversations
**Descripción:** Crear nueva conversación

**Request:**
```typescript
// Headers
Authorization: Bearer {jwt_token}

// Body (vacío - user_id se extrae del token)

Response 201:

{
  "success": true,
  "data": {
    "id": "uuid",
    "user_id": "uuid",
    "status": "active",
    "created_at": "2026-02-06T10:00:00Z",
    "updated_at": "2026-02-06T10:00:00Z",
    "message_count": 1  // mensaje de bienvenida
  }
}

Errores:

• 401: No autenticado
• 429: Rate limit excedido (max 5 conversaciones simultáneas)

---

2. GET /api/v1/chatbot/conversations

Descripción: Listar conversaciones del usuario

Query Params:

• page (int, default: 1)
• limit (int, default: 20, max: 100)
• status (string, enum: active|archived|deleted)
• date_from (ISO 8601)
• date_to (ISO 8601)

Response 200:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "status": "active",
      "created_at": "...",
      "updated_at": "...",
      "last_message_preview": "Hello! How can I...",
      "message_count": 15
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "total_pages": 3
  }
}

---

3. GET /api/v1/chatbot/conversations/:id

Descripción: Obtener conversación con mensajes

Path Params:

• id (UUID)

Query Params:

• messages_limit (int, default: 50)

Response 200:

{
  "success": true,
  "data": {
    "id": "uuid",
    "user_id": "uuid",
    "status": "active",
    "created_at": "...",
    "messages": [
      {
        "id": "uuid",
        "role": "user",
        "content": "What's the price of BTC?",
        "intent_id": "uuid",
        "created_at": "..."
      },
      {
        "id": "uuid",
        "role": "assistant",
        "content": "The current price of Bitcoin is...",
        "created_at": "..."
      }
    ]
  }
}

Errores:

• 404: Conversación no encontrada
• 403: No tienes permiso para acceder a esta conversación

---

[Continuar con otros endpoints: POST messages, DELETE, etc.]

Modelos TypeScript

// apps/backend/src/types/chatbot.types.ts

export interface Conversation {
  id: string;  // UUID
  user_id: string;  // UUID
  status: 'active' | 'archived' | 'deleted';
  created_at: Date;
  updated_at: Date;
  message_count?: number;
}

export interface Message {
  id: string;
  conversation_id: string;
  role: 'user' | 'assistant' | 'system';
  content: string;
  intent_id?: string;
  metadata?: Record<string, any>;
  created_at: Date;
}

export interface CreateConversationResponse {
  success: boolean;
  data: Conversation;
}

// [Otros tipos...]

Seguridad

• Todos los endpoints requieren autenticación JWT
• Rate limiting: 60 requests/minuto por usuario
• Validación de ownership: solo puedes acceder a tus conversaciones

Performance

• GET /conversations: < 200ms (p95)
• POST /conversations: < 300ms (p95)
• GET /conversations/🆔 < 400ms (p95) - incluye mensajes

Testing

# Unit tests
npm run test -- chatbot.service.spec.ts

# Integration tests
npm run test:e2e -- chatbot.e2e.spec.ts

---

Historial de Cambios

Versión	Fecha	Cambios
1.0.0	2026-02-06	Creación inicial

**Crear 3 archivos:**
1. `LTI-ET-001.md` - API de Conversaciones
2. `LTI-ET-002.md` - Integración con LLM Provider (OpenAI/Claude)
3. `LTI-ET-003.md` - Schema DDL y Migraciones

## Restricciones

- **MODO WRITE:** Crear 9 nuevos archivos (3 US + 3 RF + 3 ET)
- Crear subdirectorios si no existen: `user-stories/`, `requisitos-funcionales/`, `especificaciones-tecnicas/`
- Usar información real del schema `llm` (analizar DDL primero)
- Mantener consistencia en IDs y referencias cruzadas

## Output Esperado

```markdown
## Archivos Creados: 9

### User Stories (3)
1. `LTI-US-001.md` - Conversaciones Chatbot (~200 líneas)
2. `LTI-US-002.md` - Análisis de Intenciones (~180 líneas)
3. `LTI-US-003.md` - Asistencia de Trading (~220 líneas)

### Requisitos Funcionales (3)
1. `LTI-RF-001.md` - CRUD Conversaciones (~250 líneas)
2. `LTI-RF-002.md` - Procesamiento Intenciones (~200 líneas)
3. `LTI-RF-003.md` - Generación Respuestas LLM (~230 líneas)

### Especificaciones Técnicas (3)
1. `LTI-ET-001.md` - API Conversaciones (~350 líneas)
2. `LTI-ET-002.md` - Integración LLM (~280 líneas)
3. `LTI-ET-003.md` - Schema DDL (~200 líneas)

## Estructura Creada

docs/modulos-negocio/definitions/OQI-010-LLM/ ├── README.md (existente) ├── user-stories/ │ ├── LTI-US-001.md │ ├── LTI-US-002.md │ └── LTI-US-003.md ├── requisitos-funcionales/ │ ├── LTI-RF-001.md │ ├── LTI-RF-002.md │ └── LTI-RF-003.md └── especificaciones-tecnicas/ ├── LTI-ET-001.md ├── LTI-ET-002.md └── LTI-ET-003.md

## Validación
✅ 9 archivos creados con contenido completo
✅ Referencias cruzadas consistentes (US ↔ RF ↔ ET)
✅ Basado en schema DDL real `llm`
✅ Formato markdown válido
✅ Front-matter YAML en todos los archivos
✅ Total: ~1,910 líneas de documentación

Compromiso: Crear 9 documentos completos y consistentes para OQI-010 con prefijo LTI.