SPEC-052: document delivered sandbox + how it works + pendencies

specs/052-trade-spec-exit-to-base-sandbox/SPEC-052-TRADE-SPEC-EXIT-TO-BASE-SANDBOX.md

@@ -3,14 +3,64 @@
 **SPEC-ID:** 052-MYVEXX  
 **Vincula:** 049, 050, 051  
 **Org Forgejo:** `myvexx` (≠ ligbox)  
-**Status:** 🧪 Sandbox paper (2026-08-05)  
+**Status:** ✅ Sandbox paper operacional (actualizado 2026-08-07)  
 **Para:** Roger  
+**Runtime:** CT124 (`invest.myvexx.com`) · Bridge `:3100` · OpenAlice `:47331`
 
-## Objectivo
+---
 
-Permitir: escolher índice/crypto → Alice investiga → **spec no Invest** (alvo, alavancagem simulada, modo de saída) → motor monitoriza → ao atingir alvo **fecha e volta à conta base** (paper).
+## 1. Objectivo
 
-## Contrato da Spec (Invest)
+Escolher índice/crypto → (opcional) Alice investiga → **spec no Invest** (alvo, alavancagem simulada, modo de saída) → motor monitoriza → ao atingir alvo **fecha e volta à conta base** (paper).
+
+Fluxo:
+
+```text
+Activo → OpenAlice (investigar) → Spec no Invest/bridge
+              ↓
+     tick_live (preço real Yahoo) ou simulate
+              ↓
+   alvo +1,20%? → aviso | semi | auto_paper → conta base
+```
+
+---
+
+## 2. O que foi realizado (changelog)
+
+| Data | Entrega | Estado |
+|------|---------|--------|
+| 2026-08-05 | Motor sandbox no bridge (`sandbox.py`) | ✅ |
+| 2026-08-05 | API criar/listar/tick/simulate/confirm_close | ✅ |
+| 2026-08-05 | Testes dos 3 modos (aviso / semi / auto_paper) | ✅ |
+| 2026-08-05 | **Opção 2:** `tick_live` + `markets/quote` (Yahoo) | ✅ |
+| 2026-08-05 | UI Invest `/agents` (criar specs, OpenAlice link) | ✅ |
+| 2026-08-05 | `GET /architecture` no bridge | ✅ |
+| 2026-08-05 | Docs + Forgejo `myvexx/invest-myvexx` + vault | ✅ |
+
+### Ficheiros principais (CT124)
+
+| Path | Papel |
+|------|--------|
+| `/opt/invest/agents/bridge/main.py` | API bridge v0.2 |
+| `/opt/invest/agents/bridge/sandbox.py` | Motor de specs / saída |
+| `/opt/invest/agents/bridge/markets.py` | Quotes Yahoo (Index Hub mínimo) |
+| `/opt/invest/invest.myvexx.com/frontend/src/pages/Agents.js` | UI `/agents` |
+| `/opt/invest/agents/docs/ARCHITECTURE-INVEST-OPENALICE-OPTION2.md` | Diagrama arquitectura |
+
+### URLs
+
+| URL | Função |
+|-----|--------|
+| https://invest.myvexx.com/agents | UI specs paper |
+| https://invest.myvexx.com/api/agents/health | Health bridge |
+| https://invest.myvexx.com/api/agents/sandbox/specs | Specs API |
+| https://invest.myvexx.com/api/agents/markets/quote?symbol=NVDA | Cotação real |
+| https://openalice.myvexx.com/ | Investigação Alice |
+| https://git.spec.ligbox.com.br/myvexx/invest-myvexx | Specs no Forgejo |
+
+---
+
+## 3. Contrato da Spec (Invest / bridge)
 
 ```json
 {
@@ -21,56 +71,135 @@ Permitir: escolher índice/crypto → Alice investiga → **spec no Invest** (al
   "leverage_sim": 1.0,
   "exit_mode": "aviso|semi|auto_paper",
   "stop_pct": null,
-  "fill_timeout_sec": 300,
+  "note": "opcional"
-  "on_fill_fail": "abort_alert"
 }
 ```
 
 - `target_pct` = **+1,20%** sobre `entry_price` (lucro percentual).  
-- `leverage_sim` = factor só para P&L **simulado** (não broker live).  
+- `leverage_sim` = factor só para P&L **simulado**.  
-- `exit_mode`: ver tabela abaixo.
+- `asset_class`: `equity` | `crypto` | `index` | `fx` (aliases: BTC→BTC-USD, SPX→^GSPC, IBOV→^BVSP…).
 
-## Modos de saída (aplicar todos)
+### Estados
 
-| Modo | Comportamento sandbox |
+| Status | Significado |
-|------|------------------------|
+|--------|-------------|
+| `watching` | A monitorizar |
+| `alerted` | Alvo atingido (modo aviso) |
+| `ready_to_close` | Alvo atingido (modo semi — falta confirm) |
+| `closed_to_base` | Fechado / voltou à base |
+| `aborted` | Stop hit |
+
+---
+
+## 4. Modos de saída
+
+| Modo | Comportamento |
+|------|----------------|
 | **aviso** | Ao alvo → `alerted`; não fecha sozinho |
-| **semi** | Ao alvo → `ready_to_close`; exige `POST .../confirm_close` |
+| **semi** | Ao alvo → `ready_to_close`; `POST .../confirm_close` |
-| **auto_paper** | Ao alvo → fecha já → `closed_to_base` |
+| **auto_paper** | Ao alvo → `closed_to_base` automático |
 
-Live broker: **proibido** neste bridge (`ALLOW_LIVE_BROKER=0`).
+Live broker: **proibido** (`ALLOW_LIVE_BROKER=0`).
 
-## Constraints (o “não realista” → regras)
+---
 
-1. Alvo % = trigger, não garantia de fill.  
+## 5. Como funciona (passo a passo)
-2. Alavancagem = simulada até paper broker explícito.  
-3. Auto só em paper; live = degrau futuro + gate humano.  
-4. Spec no Invest/bridge = fonte da verdade (Alice lê, não inventa).  
-5. Equity vs crypto = mesmo contrato, adapters depois.  
-6. Polling sandbox; websocket = Fase B+.
 
-## API sandbox (bridge `:3100`)
+1. Login em `invest.myvexx.com` → menu **Agents / Specs**.  
+2. (Opcional) **Abrir OpenAlice** e investigar o activo.  
+3. **Cotação real → entrada** (Yahoo via bridge).  
+4. Definir alvo `%`, alavancagem sim, modo de saída → **Criar spec paper**.  
+5. **tick_live** = puxa preço real e aplica regras; **simulate** = sobe preço artificial até ao alvo.  
+6. Se `semi` → **confirm_close**. Se `auto_paper` → já fica `closed_to_base`.
+
+### API (Traefik strip `/api/agents` → bridge `:3100`)
 
 | Método | Path | Função |
 |--------|------|--------|
+| GET | `/health` | Saúde + contagem specs |
+| GET | `/architecture` | Diagrama/fluxo opção 2 |
+| GET | `/markets/quote?symbol=&asset_class=` | Preço real Yahoo |
 | POST | `/sandbox/specs` | Criar spec |
 | GET | `/sandbox/specs` | Listar |
 | GET | `/sandbox/specs/{id}` | Detalhe |
-| POST | `/sandbox/specs/{id}/tick` | Actualizar preço (manual) |
+| POST | `/sandbox/specs/{id}/tick` | Preço manual |
-| POST | `/sandbox/specs/{id}/simulate` | Simular path até alvo |
+| POST | `/sandbox/specs/{id}/tick_live` | **Opção 2** — preço real |
+| POST | `/sandbox/specs/{id}/simulate` | Path artificial até alvo |
 | POST | `/sandbox/specs/{id}/confirm_close` | Semi: confirmar fecho |
 
-Traefik: `https://invest.myvexx.com/api/agents/sandbox/...` (strip `/api/agents`).
+### Teste rápido (CLI)
 
-## Critério de done (sandbox)
+```bash
+# cotação
+curl -sk 'https://invest.myvexx.com/api/agents/markets/quote?symbol=NVDA'
 
-1. Criar spec NVDA alvo 1,20% modo `auto_paper`.  
+# criar + tick real
-2. `simulate` sobe preço ≥ +1,20%.  
+curl -sk -X POST https://invest.myvexx.com/api/agents/sandbox/specs \
-3. Estado final `closed_to_base` + `pnl_pct` ≥ 1,20.  
+  -H 'Content-Type: application/json' \
-4. Modos `aviso` e `semi` testados no mesmo motor.
+  -d '{"symbol":"NVDA","entry_price":221.0,"target_pct":1.20,"exit_mode":"aviso"}'
 
-## Fora de escopo 052
+curl -sk -X POST https://invest.myvexx.com/api/agents/sandbox/specs/<ID>/tick_live
+```
 
-- Ordem live / UTA funded  
+---
-- UI React completa `/agents` (pode seguir em paralelo Fase A 051)  
+
-- Fork profundo OpenAlice (bridge consome specs; Alice UI depois)
+## 6. Arquitectura (opção 2)
+
+```text
+invest.myvexx.com/agents
+        │ /api/agents/*
+        ▼
+Bridge :3100 ── markets/quote (Yahoo)
+        │       sandbox motor (alvo / saída)
+        │       research TradingAgents (opcional)
+        ▼
+OpenAlice :47331 — investigação / workspace (paper)
+```
+
+Detalhe: `ARCHITECTURE-INVEST-OPENALICE-OPTION2.md`.
+
+---
+
+## 7. Constraints
+
+1. Alvo % = trigger, não garantia de fill.  
+2. Alavancagem = simulada (não broker).  
+3. Auto só em paper; live = futuro + gate humano.  
+4. Spec no Invest/bridge = fonte da verdade.  
+5. Equity/crypto = mesmo contrato; adapters depois.  
+6. Polling / tick manual; websocket = depois.
+
+---
+
+## 8. Critério de done — sandbox (cumprido)
+
+| # | Critério | Resultado |
+|---|----------|-----------|
+| 1 | Spec NVDA alvo 1,20% `auto_paper` | ✅ |
+| 2 | `simulate` ≥ +1,20% | ✅ `closed_to_base` |
+| 3 | Modos `aviso` e `semi` | ✅ |
+| 4 | `tick_live` com preço Yahoo | ✅ |
+| 5 | UI `/agents` | ✅ |
+
+---
+
+## 9. Pendente / próximo (fora do done 052)
+
+| Item | Notas |
+|------|--------|
+| LLM key TradingAgents | Research real (`dry_run:false`) |
+| OpenAlice Claude/Codex OAuth | Agents a falar no container |
+| Monitor automático (cron/loop) | Hoje tick é manual na UI |
+| Alice ler spec via bridge | Sync Invest → workspace Alice |
+| Index Hub completo (051 Fase B) | Histórico OHLC, +providers, cache KPI |
+| SSO cookie OpenAlice | Ainda token admin separado |
+| Paper broker real (Alpaca paper) | Só se ligar UTA — nunca live |
+| Live trading | **Fora de escopo** até SPEC explícita |
+
+---
+
+## 10. Fora de escopo permanente (até nova SPEC)
+
+- Ordem live / UTA com fundos reais  
+- Unificar senha Invest = token OpenAlice  
+- Patch OpenAlice para password fraca