---
id: PROMPT-SA-14
agent_id: SA-14
model: claude-sonnet-4.5
type: General background
fase: FASE-3
scope: Create US/RF/ET docs para OQI-010 (F3.9)
mode: write
created: 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:**

```markdown
---
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:**

```markdown
---
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:**

```markdown
---
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:**
```typescript
{
  "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:**
```typescript
{
  "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:**
```typescript
{
  "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

```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/:id: < 400ms (p95) - incluye mensajes

## Testing
```bash
# 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.