mtcli-tradehistory 1.0.0
Plugin do mtcli
Requires Python: <3.14,>=3.10

# mtcli-tradehistory

Plugin **mtcli** para exibir o **histórico de negócios (trades/deals)** executados pelo usuário em um pregão, utilizando a **API oficial do MetaTrader 5**.

O foco do plugin é **pós-trade, auditoria e leitura cronológica**, com saída **100% textual**, adequada para terminal e leitores de tela (NVDA / JAWS).

---

## Funcionalidades

- Exibe todos os **deals executados** no pregão
- Filtro por:
  - Data do pregão
  - Ativo (símbolo)
- Informações exibidas:
  - Horário do negócio
  - Tipo (BUY / SELL)
  - Preço
  - Volume
  - Resultado financeiro (P&L)
  - Identificador da posição
- Arquitetura **MVC**
- Saída textual simples e acessível
- Controle explícito de **fuso horário do servidor MT5**

---

## Estrutura do projeto

```

mtcli-tradehistory/
├── README.md
├── pyproject.toml
└── mtcli_tradehistory/
├── **init**.py
├── cli.py          # Interface CLI (Click)
├── conf.py         # Configurações do plugin
├── controller.py  # Regras de orquestração
├── model.py       # Acesso à API MetaTrader5
└── view.py        # Saída textual no terminal

````

---

## Instalação

Clone o repositório e instale em modo editável:

```bash
git clone https://github.com/seu-usuario/mtcli-tradehistory.git
cd mtcli-tradehistory
pip install -e .
````

Requisitos:

* Python 3.10+
* MetaTrader 5 instalado
* Biblioteca `MetaTrader5` configurada corretamente

---

## Uso

### Pregão do dia atual

```bash
mt th
```

### Pregão específico

```bash
mt th --date 2026-01-09
```

### Pregão + ativo

```bash
mt th --date 2026-01-09 --symbol WING26
```

---

## Configuração

As configurações podem ser feitas via:

* variáveis de ambiente
* arquivo padrão do `mtcli`

### `SERVER_TZ_OFFSET` (OBRIGATÓRIO)

Define o **fuso horário do servidor da corretora**.

> ⚠️ A API do MetaTrader 5 **não informa o fuso do servidor**.
> Por isso, este valor deve ser configurado explicitamente.

Exemplos:

| Servidor | Valor |
| -------- | ----- |
| UTC      | `0`   |
| UTC+3    | `3`   |
| UTC-3    | `-3`  |

Exemplo via variável de ambiente:

```bash
set SERVER_TZ_OFFSET=0
```

Ou no arquivo de configuração:

```ini
[DEFAULT]
server_tz_offset = 0
```

---

## Sobre horários (importante)

* `deal.time` retornado pelo MT5 está no **horário do servidor**
* Não é UTC
* Não é horário local do sistema
* A API **não fornece o fuso automaticamente**

Este plugin:

* Assume o fuso do servidor via `SERVER_TZ_OFFSET`
* Não aplica conversões implícitas do sistema operacional
* Exibe horários **previsíveis e auditáveis**

---

## Acessibilidade

* Saída 100% textual
* Sem cores, gráficos ou formatações visuais complexas
* Compatível com leitores de tela (NVDA, JAWS)
* Ideal para uso em terminal (CMD, PowerShell, WSL)

---

## O que este plugin NÃO faz

* Não exibe gráficos
* Não interpreta estratégia
* Não calcula estatísticas avançadas (winrate, expectancy)
* Não substitui relatórios do MT5

Ele **mostra os fatos**: negócios executados, em ordem cronológica.

---

## Evoluções possíveis

* Agrupamento por posição (entrada → saída → resultado)
* Resumo do pregão (P&L total, nº trades, winrate)
* Exportação CSV
* Opções `--server-time` / `--local-time`
* Integração com outros plugins mtcli (VWAP, Market Profile)

---

## Licença

GPL License

---

## Autor

Valmir França
Trader | Desenvolvedor Python | mtcli