11 KiB
11 KiB
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:
- Workspaces — pasta/tarefa por tese ou índice
- Issue Board — trabalho em markdown + schedule
- Tracked entities — tickers, sectores, temas, baskets
- Inbox — relatórios duráveis (não só chat)
- Market tools — dados via Index Hub (não providers soltos na UI)
- 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
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/interfacesdo 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
- Aprovar esta SPEC (Roger).
- Fase A: rota
/agents+ nav + cards bridge (1–2 dias). - Fase B: esqueleto Index Hub + provider Yahoo (ou equivalente) + UI
/markets+ instrumentar timings p95. - Medir KPIs §6; ajustar TTL/cache antes de mais providers.
- 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:
- Operador autentica uma vez no Invest e acede a markets + agents no mesmo shell.
- Index Hub cumpre KPIs §6.1 e cobertura §6.2 (Fase B).
- Agents permanecem paper-only (§6.3 / §7).
- Documentação (handoff + este ficheiro) reflecte URLs e estado reais.
14. Comandos de verificação (baseline)
# 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.