# Quickstart: Streaming híbrido en chat de conversación

**Feature**: `003-chat-streaming`

## Prerequisites

- Laravel 12 + `ia_agent` running locally
- Angular `ChatFront` dev server or built assets served
- LLM configured (`LLM_PROVIDER`, API keys)
- JWT login operativo

## Environment

```env
# Optional — default true after implement
AGENT_STREAMING_ENABLED=true

LLM_PROVIDER=openai
OPENAI_CHAT_MODEL=gpt-4o-mini
OPENAI_REQUEST_TIMEOUT=120
```

## Start services

```powershell
php artisan serve
cd ChatFront; npm start
```

## Manual test — stream (texto)

1. Login en SPA → `/assistant`
2. Enviar mensaje de **solo texto** (sin adjunto)
3. Verificar:
   - Aparece bubble assistant (no spinner «pensando…» estático)
   - Mensaje de estado («Analizando…», «Consultando datos…») antes del texto
   - Texto crece progresivamente
   - Al terminar, mensaje persistido al recargar página

### curl (SSE)

```powershell
$token = "YOUR_JWT"
curl -N -X POST "http://127.0.0.1:8000/api/v1/chat/message/stream" `
  -H "Authorization: Bearer $token" `
  -H "Content-Type: application/json" `
  -H "Accept: text/event-stream" `
  -d '{"message":"Hola, cuantos clientes tenemos?"}'
```

Expected output (interleaved):
```
data: {"type":"status","phase":"analyzing","message":"Analizando tu pregunta…"}

data: {"type":"status","phase":"querying","message":"Consultando datos…"}

data: {"type":"chunk","content":"Actualmente "}
...
data: {"type":"done","assistant_id":123,"content":"..."}
```

## Manual test — adjunto (sync, sin regresión)

1. Adjuntar PDF o JPG + mensaje
2. Verificar flujo síncrono: spinner hasta respuesta completa
3. `POST /api/v1/chat/message` (multipart) — sin cambios

## Verify against spec

| Scenario | Expected |
|----------|----------|
| SC-001 | Primer `status` o `chunk` en UI < 2 s |
| SC-002 | Pregunta BD muestra estados antes de tokens |
| SC-003 | Contenido final = fila `chat_messages` assistant |
| SC-004 | Adjunto funciona igual que antes |
| SC-005 | Simular corte red → error UI; user message guardado; no assistant parcial |

## nginx (production)

If responses appear buffered, add to location:

```nginx
proxy_buffering off;
proxy_cache off;
chunked_transfer_encoding on;
```

PHP: ensure `output_buffering = Off` or flush in stream callback (documented in plan).

## Run tests

```powershell
php artisan test --filter=ChatStream
cd ChatFront; npm test -- --include=**/chat-api.service.spec.ts
```

(Tests added during `/speckit-implement`.)

## Next steps

1. `/speckit-tasks` — generate `tasks.md`
2. `/speckit-implement` — backend SSE + frontend conversation component