docs/api_reqs.md

# Documento de Especificaciones Técnicas: Munger Intelligence Engine API

**Versión:** 1.0  
**Tecnologías:** Node.js, Next.js (App Router), TypeScript, yahoo-finance2  
**Despliegue:** Hugging Face Spaces (Docker)  

---

## 1. Resumen del Proyecto

El "Munger Intelligence Engine" es una API de análisis financiero diseñada para automatizar la estrategia de inversión de Charlie Munger: comprar empresas de "alta calidad" cuando cotizan cerca de su media móvil de 200 semanas (200-WMA). El sistema debe realizar descargas diarias, filtrar por capitalización de mercado y gestionar estados de señales en tiempo real.

---

## 2. Definición de la Watchlist e Ingesta de Datos

### 2.1 Segmentación por Capitalización (Market Cap)

El sistema debe ignorar cualquier activo que no cumpla con los umbrales de seguridad institucional:

* **Elite Compounders (Mega Cap):** > $100B. Empresas con fosos económicos globales.
* **Blue Chips (Large Cap):** > $10B. Estándar mínimo de liquidez y estabilidad para la estrategia.

### 2.2 Estrategia de Descarga Paralelizada (Batching)

Para optimizar el rendimiento y evitar bloqueos de IP/Rate Limiting de Yahoo Finance:

* **Tamaño de Lote (Batch):** 50 tickers por iteración.
* **Concurrencia:** Utilizar `Promise.all` para procesar los 50 tickers de cada lote simultáneamente.
* **Frecuencia:** Descarga diaria automatizada de `quote` y `quoteSummary`.

---

## 3. Lógica del Motor de Análisis (Munger Strategy)

Cada ticker debe ser evaluado bajo tres filtros secuenciales:

1. **Filtro Fundamental (Calidad):**
    * **ROE (Return on Equity):** > 15% (Mínimo), > 25% (Excelente).
    * **Debt/Equity:** < 50% (Mínimo), < 15% (Ideal).
2. **Filtro Técnico (Valor):**
    * **200-WMA:** Media móvil simple de los últimos 200 cierres semanales.
    * **Gatillo (Trigger):** Precio Actual $\leq$ (200-WMA * 1.05).
3. **Margen de Seguridad:** Diferencia porcentual entre el Precio Actual y el Target Mean de analistas.

---

## 4. Gestión de Estados por Ticker

El sistema debe mantener un estado persistente para cada ticker en la base de datos o archivo de estado en Hugging Face:

| Estado | Descripción |
| :--- | :--- |
| `SCANNING` | Iniciando descarga de datos de `yahoo-finance2`. |
| `FILTERING` | Validando Market Cap y métricas de calidad (ROE/Deuda). |
| `TECHNICAL_EVAL` | Calculando posición respecto a la 200-WMA. |
| `SIGNAL_READY` | Activo listo para compra o seguimiento activo. |
| `ERROR` | Fallo en la ingesta de datos o ticker no encontrado. |

---

## 5. Especificación de Endpoints de la API

### `GET /api/v1/health`

* **Propósito:** Monitorización del sistema y estado de las APIs externas.
* **Response:** JSON con `status`, `last_sync_timestamp` y `api_latency`.

### `POST /api/v1/sync`

* **Propósito:** Disparador del ciclo de descarga diaria (vía Cron).
* **Lógica:** Ejecuta el procesamiento por lotes (50 tickers) usando `Promise.all`.
* **Payload:** `{ "force": boolean, "segments": ["mega", "large"] }`.

### `GET /api/v1/signals`

* **Propósito:** Listar oportunidades activas para el Dashboard.
* **Filtros:** Por `sector`, `munger_score` (0-100) y `upside`.
* **Response:** Array de objetos `MungerStock`.

### `GET /api/v1/ticker/:id`

* **Propósito:** Deep Dive de un activo específico.
* **Response:** Detalle completo incluyendo `quoteSummary`, histórico de WMA y catalizadores fundamentales.

### `GET /api/v1/portfolio`

* **Propósito:** Estado de las posiciones actuales en Alpaca (Paper Trading).
* **Response:** Equity total, P&L de posiciones y "Días de Disciplina" (tiempo sin trades impulsivos).

---

## 6. Despliegue en Hugging Face Spaces

* **Docker Image:** Base `node:20-slim`.
* **Persistencia:** Utilizar **HF Datasets** o **R2 de Cloudflare** para evitar pérdida de datos por reinicio del Space.
* **Variables de Entorno:** `ALPACA_KEY`, `ALPACA_SECRET`, `HF_TOKEN`.