305 lines
11 KiB
Markdown
305 lines
11 KiB
Markdown
# 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.
|