---
id: "US-ML-020"
title: "HISTORIA DE USUARIO"
type: "User Story"
status: "Done"
priority: "Media"
epic: "OQI-006"
project: "trading-platform"
story_points: 3
created_date: "2025-12-05"
updated_date: "2026-01-04"
---

# HISTORIA DE USUARIO

**Version:** 1.0.0
**Fecha:** 2025-12-05
**Uso:** Definicion de historia de usuario

---

## US-ML-020: Ver Fase AMD Actual en Dashboard

### Metadata

| Campo | Valor |
|-------|-------|
| **ID** | US-ML-020 |
| **Epica** | OQI-006A - Estrategia AMD y Modelos ML Avanzados |
| **Modulo** | ml-signals |
| **Prioridad** | P0 |
| **Story Points** | 8 |
| **Sprint** | Sprint 8 |
| **Estado** | Ready |
| **Asignado a** | ML-Engineer / Frontend-Developer |

---

### Historia de Usuario

**Como** trader activo de la plataforma,
**quiero** ver la fase AMD actual del mercado (Accumulation, Manipulation, Distribution o Neutral) en tiempo real,
**para** entender el contexto institucional del mercado y tomar decisiones de trading informadas.

### Descripcion Detallada

La fase AMD indica el comportamiento institucional del mercado:

- **Accumulation (Verde):** Instituciones acumulando posiciones. Buen momento para buscar entradas largas.
- **Manipulation (Amarillo/Naranja):** Stop hunting activo. Evitar operar o usar SL amplios.
- **Distribution (Rojo):** Instituciones distribuyendo. Buen momento para buscar entradas cortas.
- **Neutral (Gris):** Sin fase clara. Esperar confirmacion.

El indicador debe mostrar:
1. Fase actual con color distintivo
2. Confianza del modelo (0-100%)
3. Tiempo en la fase actual
4. Historial de fases recientes (ultimas 24h)

### Mockups/Wireframes

```
+--------------------------------------------------+
|  TRADING DASHBOARD                               |
+--------------------------------------------------+
|                                                  |
|  [CHART AREA]                                    |
|                                                  |
|  +--------------------------------------------+  |
|  | AMD PHASE                                   |  |
|  | ========================================== |  |
|  |                                            |  |
|  |  [===] ACCUMULATION                        |  |
|  |        Confidence: 78%                     |  |
|  |        Duration: 2h 15m                    |  |
|  |                                            |  |
|  |  Phase History (24h):                      |  |
|  |  [N][A][A][M][A][A][A][D][D][N][A][A]      |  |
|  |                                            |  |
|  +--------------------------------------------+  |
|                                                  |
+--------------------------------------------------+
```

---

### Criterios de Aceptacion

**Escenario 1: Visualizacion de fase actual**
```gherkin
DADO que estoy viendo el dashboard de trading
CUANDO el modelo AMDDetector procesa los datos actuales
ENTONCES veo la fase AMD actual con su color distintivo
Y veo el porcentaje de confianza (0-100%)
Y veo el tiempo que lleva en esa fase
```

**Escenario 2: Actualizacion en tiempo real**
```gherkin
DADO que estoy viendo el indicador de fase AMD
CUANDO cambia la fase del mercado
ENTONCES el indicador se actualiza en menos de 5 segundos
Y veo una animacion de transicion suave
Y escucho una notificacion sonora (si esta habilitada)
```

**Escenario 3: Historial de fases**
```gherkin
DADO que estoy viendo el indicador AMD
CUANDO quiero ver el historial de fases
ENTONCES veo las ultimas 24 horas de fases
Y cada fase se muestra como un bloque coloreado
Y puedo hacer hover para ver detalles (hora, duracion, confianza)
```

**Escenario 4: Sin datos disponibles**
```gherkin
DADO que el modelo AMDDetector no esta disponible
CUANDO intento ver la fase AMD
ENTONCES veo un mensaje "Fase no disponible"
Y el indicador muestra estado gris deshabilitado
```

### Criterios Adicionales

- [ ] Colores accesibles (WCAG AA)
- [ ] Responsive en mobile y desktop
- [ ] Tooltip con explicacion de cada fase
- [ ] Opcion para minimizar/expandir indicador
- [ ] Performance: Renderizado <100ms

---

### Tareas Tecnicas

**Backend (FastAPI):**
- [ ] BE-ML-020: Endpoint GET /api/ml/amd/current
- [ ] BE-ML-021: Endpoint GET /api/ml/amd/history?hours=24
- [ ] BE-ML-022: WebSocket para streaming de fase AMD

**ML Model:**
- [ ] ML-020: Implementar AMDDetector.predict()
- [ ] ML-021: Cache de predicciones (TTL 30s)
- [ ] ML-022: Logging de predicciones para monitoring

**Frontend:**
- [ ] FE-ML-020: Componente AMDPhaseIndicator
- [ ] FE-ML-021: Componente AMDPhaseHistory
- [ ] FE-ML-022: Store amdStore (Zustand)
- [ ] FE-ML-023: Integracion con WebSocket

**Tests:**
- [ ] TEST-ML-020: Unit tests AMDDetector
- [ ] TEST-ML-021: Integration tests API
- [ ] TEST-ML-022: E2E tests indicador

---

### Dependencias

**Depende de:**
- [ ] US-ML-001: Ver prediccion de precio - Estado: Done
- [ ] AMDDetector modelo entrenado - Estado: Pending

**Bloquea:**
- [ ] US-ML-021: Alertas de cambio de fase AMD
- [ ] US-ML-023: Senales filtradas por fase AMD

---

### Notas Tecnicas

**Endpoints involucrados:**
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /api/ml/amd/current | Obtener fase actual |
| GET | /api/ml/amd/history | Historial de fases |
| WS | /ws/ml/amd | Stream de actualizaciones |

**Entidades/Tablas:**
- `ml.amd_predictions`: Historial de predicciones AMD
- `ml.amd_transitions`: Transiciones entre fases

**Componentes UI:**
- `AMDPhaseIndicator`: Indicador principal de fase
- `AMDPhaseHistory`: Timeline de fases
- `AMDPhaseBadge`: Badge individual de fase

**Response Schema:**
```typescript
interface AMDPrediction {
  phase: 'neutral' | 'accumulation' | 'manipulation' | 'distribution';
  confidence: number;       // 0-1
  probabilities: {
    neutral: number;
    accumulation: number;
    manipulation: number;
    distribution: number;
  };
  duration_seconds: number;
  started_at: string;       // ISO 8601
  timestamp: string;        // ISO 8601
}
```

---

### Definition of Ready (DoR)

- [x] Historia claramente escrita (quien, que, por que)
- [x] Criterios de aceptacion definidos
- [x] Story points estimados
- [x] Dependencias identificadas
- [ ] AMDDetector modelo entrenado
- [x] Diseno/mockup disponible
- [x] API spec disponible

### Definition of Done (DoD)

- [ ] Codigo implementado segun criterios
- [ ] Tests unitarios escritos y pasando
- [ ] Tests de integracion pasando
- [ ] Code review aprobado
- [ ] Documentacion actualizada
- [ ] Inventarios actualizados (MASTER_INVENTORY.yml)
- [ ] Traza registrada
- [ ] QA aprobado
- [ ] Desplegado en ambiente de pruebas

---

### Historial de Cambios

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2025-12-05 | Creacion | Requirements-Analyst |

---

### Notas de Implementacion

_Pendiente de desarrollo_

### Notas de QA

_Pendiente de pruebas_

---

**Creada por:** Requirements-Analyst
**Fecha:** 2025-12-05
**Ultima actualizacion:** 2025-12-05