# SPEC-051 — Invest Unified Dashboard + Index Hub (Alice-loop inside MyVexx)

**SPEC-ID:** 051-MYVEXX  
**Vincula:** **049** (invest deploy / CT124), **050** (AI Agents paper-only)  
**Status:** 📝 Draft para aprovação (2026-08-05)  
**Para:** Roger  
**Host:** CT124 `invest.myvexx.com` (`10.10.10.124`)

---

## 1. Objectivo

Unificar **Invest** e a *ideia operacional* do **OpenAlice** num **único dashboard MyVexx**, com capacidade de reunir **múltiplos índices / asset classes**, mantendo agents em modo **paper/research only**.

| Peça actual | Destino nesta SPEC |
|-------------|-------------------|
| Invest (`invest.myvexx.com`) | **Shell canónico** — auth, admin, markets, reports, agents UI |
| OpenAlice (`openalice.myvexx.com`) | **Inspiração + runtime opcional** (Fase A iframe; Fase C lógica absorvida) |
| TradingAgents + bridge `:3100` | Motor de research multi-agente atrás do shell |
| Index Hub (novo) | API única de índices/quotes para UI + agents |

**Não é:** fork imediato do repositório OpenAlice upstream, nem trading live.

---

## 2. Problema que resolve

Hoje o operador tem **dois logins / duas UIs**:

- Invest → `admin@myvexx.com` + senha JWT  
- OpenAlice → admin token aleatório (não unificável nativamente com a senha Invest)

Além disso, OpenAlice não é o produto de **multi-índices** que o Roger quer; é um workspace de agents. O Invest já é plataforma admin, mas **não** tem Index Hub nem shell de agents.

---

## 3. Princípios de produto (Alice-loop reescrito)

Manter da OpenAlice o **esqueleto de administração**:

1. **Workspaces** — pasta/tarefa por tese ou índice  
2. **Issue Board** — trabalho em markdown + schedule  
3. **Tracked entities** — tickers, sectores, temas, baskets  
4. **Inbox** — relatórios duráveis (não só chat)  
5. **Market tools** — dados via Index Hub (não providers soltos na UI)  
6. **Trading-as-Git (paper)** — stage → review → approve; `ALLOW_LIVE_BROKER=0`

Reescrever / acrescentar para MyVexx:

- **Auth única** Invest (JWT) — sem silo de admin token no shell  
- **Index Hub** multi-fonte (equity, FX, crypto, índices BR/US, baskets)  
- **Dashboard unificado** em `invest.myvexx.com`  
- OpenAlice UI standalone permanece **opcional** até Fase C

---

## 4. Arquitectura alvo

```text
https://invest.myvexx.com
│
├── Auth JWT (existente)
├── /markets          → Index Hub UI (watchlists, charts, baskets)
├── /agents           → Bridge + research + link/embed Alice-loop
├── /research         → Inbox / briefs (saída dos agents)
├── /admin|reports|…  → módulos Invest já existentes
│
└── APIs
    ├── /api/*                 → investment-backend (existente)
    ├── /api/agents/*          → bridge :3100 (SPEC-050)
    └── /api/markets/*         → Index Hub (NOVO)
            │
            ├── providers: yahoo | polygon | b3 | … (plugáveis)
            └── cache Redis/in-proc + rate limits

openalice.myvexx.com  → (Fase A) runtime/UI externa
                      → (Fase C) deprecado ou só lab interno
```

### CT124 — recursos (herdados / mínimos)

| Recurso | Valor | Nota |
|---------|-------|------|
| RAM | **8 GB** | Já aplicado (SPEC-050) |
| Swap | **2 GB** | |
| Cores | **2** | Monitorizar sob Index Hub + agents |
| Path Invest | `/opt/invest/invest.myvexx.com/` | |
| Path Agents | `/opt/invest/agents/` | |

**Revisão de capacidade:** se Index Hub + 2 engines agents sob carga >70% RAM sustentada → propor bump para 12 GB (nova SPEC, não nesta).

---

## 5. Fases de entrega

### Fase A — Shell unificado (rápido)

**Objectivo:** um sítio para o operador; engines continuam separados.

| Entrega | Detalhe |
|---------|---------|
| Página React `/agents` | Cards do bridge (`/api/agents/health`, `/agents`, research dry-run) |
| Deep-link OpenAlice | Botão → `https://openalice.myvexx.com/` (não `/alice/` legacy) |
| Nav Invest | Entrada “Agents / Research” no layout admin |
| Docs | Actualizar handoff + README agents |

**Fora de escopo A:** SSO cookie OpenAlice, Index Hub, fork Alice.

**Critério de done A:** login Invest → `/agents` mostra health dos dois engines + link OpenAlice funcional.

---

### Fase B — Index Hub + SSO light

**Objectivo:** multi-índices no Invest; auth menos fragmentada.

| Entrega | Detalhe |
|---------|---------|
| `GET /api/markets/indices` | Lista índices canónicos + último preço / variação |
| `GET /api/markets/quotes?symbols=` | Quotes batch |
| `GET /api/markets/history?symbol=&range=` | OHLC agregado |
| Providers | ≥2 backends plugáveis (ex. Yahoo + 1 pago/opcional) |
| Cache | TTL configurável; stale-while-revalidate |
| UI `/markets` | Watchlist multi-índice + detalhe símbolo |
| SSO light | Session Invest; OpenAlice continua token próprio **ou** reverse-proxy só interno |

**Critério de done B:** dashboard mostra ≥ **12** símbolos de ≥ **3** classes (ex. equity US, índice BR, FX ou crypto) com refresh conforme KPIs §6.

---

### Fase C — Alice-loop nativo no Invest

**Objectivo:** mesma construção de administração OpenAlice **dentro** da plataforma MyVexx.

| Entrega | Detalhe |
|---------|---------|
| Workspaces | Modelo + API + UI mínima no Invest |
| Issues + schedule | Markdown-backed ou DB equivalente |
| Tracked entities | Grafo leve (símbolos ↔ teses ↔ índices) |
| Inbox `/research` | Relatórios de TradingAgents + agents locais |
| Index Hub como única fonte | Agents **não** chamam providers externos directos na UI |
| OpenAlice standalone | Lab opcional; default = shell Invest |

**Critério de done C:** operador faz research end-to-end **só** em `invest.myvexx.com` (login único), paper-only.

---

## 6. Metas de performance (KPIs) — o que a 049/050 **não** definiam

Estas metas passam a ser o contrato de performance do produto unificado.

### 6.1 UI / API (Index Hub)

| KPI | Meta (Fase B+) | Medição |
|-----|----------------|---------|
| `GET /api/markets/quotes` (≤20 símbolos, cache hit) | **p95 ≤ 150 ms** | backend timing + Traefik |
| `GET /api/markets/quotes` (cache miss, provider OK) | **p95 ≤ 1200 ms** | |
| `GET /api/markets/indices` (lista canónica) | **p95 ≤ 300 ms** | |
| First Contentful paint `/markets` (prod, tunnel) | **≤ 2.5 s** em rede normal | Lighthouse / Web Vitals |
| Erros 5xx Index Hub (rolling 24h) | **< 1%** dos requests | logs nginx/backend |

### 6.2 Cobertura de mercado

| KPI | Meta Fase B | Meta Fase C |
|-----|-------------|-------------|
| Símbolos no catálogo canónico | ≥ **50** | ≥ **200** |
| Asset classes | ≥ **3** (equity, index, fx\|crypto) | ≥ **4** + baskets |
| Refresh quote (polling UI) | **15–60 s** (config) | + websocket opcional |
| Providers activos | ≥ **1** free + stub | ≥ **2** com failover |

### 6.3 Agents / research (herdado 050 + objectivos)

| KPI | Meta | Nota |
|-----|------|------|
| `GET /api/agents/health` | **p95 ≤ 200 ms** | bridge local |
| Research `dry_run:true` | **≤ 2 s** | sem LLM |
| Research real (1 ticker) | **≤ 180 s** soft | depende LLM; timeout soft + status async |
| Broker live | **proibido** | `ALLOW_LIVE_BROKER=0` |

### 6.4 Infra CT124

| KPI | Meta |
|-----|------|
| RAM usada média (stack completo idle) | **≤ 6 GB / 8 GB** |
| RAM pico (research + quotes) | **≤ 7.5 GB** (alerta ≥ 85%) |
| Disco Docker logs | json-file max já aplicado no OpenAlice; replicar no bridge |

---

## 7. Segurança e compliance

- Paper / research only — **sem** keys de brokerage live  
- Alpaca **paper** apenas se UTA for ligado (explicitamente)  
- Secrets em `/opt/invest/agents/secrets/` mode **600**  
- Não misturar admin token OpenAlice com senha Invest no mesmo campo de UI sem aviso  
- Disclaimer: **não é conselho financeiro**  
- Não alterar `/etc/network/interfaces` do Proxmox nesta SPEC  

---

## 8. Auth — decisão de produto

| Opção | Decisão nesta SPEC |
|-------|-------------------|
| Unificar senha Invest = token OpenAlice | **Rejeitado** (token 256-bit ≠ senha humana; OpenAlice não aceita custom token nativo) |
| Login único no shell Invest | **Obrigatório** a partir da Fase A |
| OpenAlice token | Mantém-se para UI standalone até Fase C; documentado em `secrets/openalice-admin-token.txt` |
| SSO profundo (cookie partilhado) | **Opcional Fase B**; não bloqueia Index Hub |

Credenciais Invest de referência (operador): `admin@myvexx.com` — ver handoff (não repetir segredos em cópias públicas da SPEC).

---

## 9. URLs e rotas

| URL | Papel | Fase |
|-----|-------|------|
| `https://invest.myvexx.com/` | Shell | A+ |
| `https://invest.myvexx.com/agents` | Hub agents | A |
| `https://invest.myvexx.com/markets` | Index Hub UI | B |
| `https://invest.myvexx.com/research` | Inbox | C (stub B opcional) |
| `https://invest.myvexx.com/api/agents/*` | Bridge | 050 / A |
| `https://invest.myvexx.com/api/markets/*` | Index Hub API | B |
| `https://openalice.myvexx.com/` | Alice UI standalone | A–B |
| `https://invest.myvexx.com/alice/` | **Deprecated** — não usar | — |

---

## 10. Estado actual (baseline 2026-08-05)

| Item | Estado |
|------|--------|
| Invest stack CT124 | ✅ |
| OpenAlice container healthy `:47331` | ✅ |
| Bridge `:3100` | ✅ |
| Página `/agents` no frontend Invest | ❌ |
| Index Hub `/api/markets/*` | ❌ |
| KPIs medidos (dashboard) | ❌ (definidos nesta SPEC) |
| LLM key TradingAgents | ❌ pendente operador |
| Alice-loop nativo no Invest | ❌ |

---

## 11. Plano de implementação sugerido

1. **Aprovar** esta SPEC (Roger).  
2. Fase A: rota `/agents` + nav + cards bridge (1–2 dias).  
3. Fase B: esqueleto Index Hub + provider Yahoo (ou equivalente) + UI `/markets` + instrumentar timings p95.  
4. Medir KPIs §6; ajustar TTL/cache antes de mais providers.  
5. Fase C: portar Alice-loop (workspaces/issues/inbox) para domínio Invest — SPEC filha se o escopo explodir (**052**).  

---

## 12. Fora de escopo

- Trading live / UTA com fundos reais  
- Alterar senha Invest para o token OpenAlice  
- Patch upstream OpenAlice para aceitar password fraca  
- QuantConnect / Alpaca live  
- Mudanças de rede Proxmox (`interfaces`)  

---

## 13. Critério de aceitação global

SPEC-051 considera-se **cumprida** quando:

1. Operador autentica **uma vez** no Invest e acede a markets + agents no mesmo shell.  
2. Index Hub cumpre KPIs §6.1 e cobertura §6.2 (Fase B).  
3. Agents permanecem paper-only (§6.3 / §7).  
4. Documentação (handoff + este ficheiro) reflecte URLs e estado reais.

---

## 14. Comandos de verificação (baseline)

```bash
# Invest auth + agents
curl -sk -X POST https://invest.myvexx.com/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@myvexx.com","password":"***"}'

curl -sk https://invest.myvexx.com/api/agents/health
curl -sk https://invest.myvexx.com/api/agents/agents

# OpenAlice
curl -sk -o /dev/null -w '%{http_code}\n' https://openalice.myvexx.com/

# Pós Fase B
curl -sk https://invest.myvexx.com/api/markets/indices
curl -sk 'https://invest.myvexx.com/api/markets/quotes?symbols=IBOV,SPX,EURUSD'
```

---

## 15. Aprovação

| Campo | Valor |
|-------|-------|
| Autor | Auto (sessão CT124, 2026-08-05) |
| Aprovador | Roger |
| Aprovado em | _pendente_ |
| Notas | _…_ |

**Pedido:** Roger, confirma se avançamos pela **Fase A** já, ou se queres ajustar KPIs / asset classes antes de código.