trading-platform/docs/02-definicion-modulos/OQI-006-ml-signals/epicas/historias-usuario/US-ML-020-ver-fase-amd.md

id	title	type	status	priority	epic	project	story_points	created_date	updated_date
US-ML-020	HISTORIA DE USUARIO	User Story	Done	Media	OQI-006	trading-platform	3	2025-12-05	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

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

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

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

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:

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)

• Historia claramente escrita (quien, que, por que)
• Criterios de aceptacion definidos
• Story points estimados
• Dependencias identificadas
• AMDDetector modelo entrenado
• Diseno/mockup disponible
• 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