npm package: @marcos_feitoza/personal-finance-frontend-feature-investments
Description: Este pacote contém a implementação das telas para visualização e gerenciamento de todas as contas de investimento na aplicação Personal Finance Frontend.
Latest version: 1.4.0

# Feature: Investimentos (Frontend Flutter)

Este pacote contém a implementação das telas para visualização e gerenciamento de todas as contas de investimento na aplicação Personal Finance Frontend.

## Propósito

O objetivo deste pacote é fornecer ao usuário uma interface completa para acompanhar a performance de seus investimentos, registrar novas transações (compra/venda, dividendos) e gerenciar suas contribuições RRSP.

## Conteúdo Principal

-   **`lib/screens/investment_account_screen.dart`**: Tela genérica para contas de investimento (ex: TFSA, Non-Registered, RRSP Wealthsimple), mostrando resumo e histórico de trades.
-   **`lib/screens/crypto_account_screen.dart`**: Tela específica para contas de criptomoedas, mostrando resumo e histórico de trades de cripto.
-   **`lib/screens/rrsp_sun_life_screen.dart`**: Tela específica para a conta RRSP Sun Life, focando em histórico de contribuições.
-   **`lib/screens/portfolio_screen.dart`**: Tela consolidada "Portfolio" que permite alternar entre contas (ou **All**) e ver uma tabela sintética unificada (stocks + crypto), além de registrar trades.
-   **`lib/screens/dividends_screen.dart`**: Tela consolidada "Dividends" para listar dividendos por conta (ou **All**) e registrar novos dividendos.

### Tabela sintética unificada (stocks + crypto)

As telas de investimento (stocks e crypto) usam uma tabela sintética padronizada no **core-ui**:

- `personal-finance-frontend-core-ui/lib/widgets/portfolio_summary_table.dart`

Colunas padronizadas:

- **Account**
- **Date** (primeiro BUY da posição)
- Symbol, Shares, Avg Price, Book Cost, Live Price, Market Value, Unrealized P/L, % P/L
- Account %, Portfolio %

Ela suporta **ordenação por coluna** ao clicar no header.

### Resumo de conta (Total / Available to trade)

Na tela Portfolio, existe um card no topo com:

- **Total**: valor total da conta (cash + market value)
- **Available to trade**: saldo disponível em caixa para novas operações

Em modo **All**, o resumo mostra todas as contas. Em uma conta específica, mostra apenas a conta selecionada.

---

## Como Usar (Instalação como Dependência)

Este pacote é uma dependência local para a aplicação principal (`personal-finance-frontend`).

No `pubspec.yaml` da aplicação principal, adicione a seguinte linha em `dependencies`:

```yaml
personal_finance_frontend_feature_investments:
  path: ../personal-finance-frontend-feature-investments
```

## Features

-   **Resumo do Portfólio (Sintético)**: Visão geral da performance dos ativos em cada conta de investimento, com métricas como "Book Cost", "Market Value", "Unrealized P/L", "Total Return" e percentuais de alocação.
-   **Histórico de Trades (Analítico)**: Listagem detalhada de todas as operações de compra e venda por conta.
-   **Registro de Dividendos**: Formulário para registrar dividendos recebidos.
-   **Acompanhamento de Contribuições RRSP**: Histórico e resumo das contribuições para contas RRSP.
-   **Exclusão Suave (Soft Delete)**: Funcionalidade para deletar trades e contribuições de forma segura, marcando-os como excluídos em vez de remover permanentemente.

## Como testar (manual)

### Portfolio (tela consolidada)

1) Abrir o app → Menu → Investments → **Portfolio**
2) Validar o dropdown **Account Type**:
   - **All**: form de trade fica desabilitado e a tabela lista todas as contas
   - **TFSA/RRSP/Non-Registered/Crypto**: form de trade e tabela filtram para a conta selecionada
3) Validar ordenação da tabela clicando nos headers (ex.: Account, Symbol, Market Value)
4) Criar um trade (stocks/crypto) e confirmar que o resumo e a tabela atualizam

### Coluna Date (first buy)

Validar que a coluna **Date** na tabela sintética é o **primeiro BUY** da posição por símbolo.

### Dividends (tela consolidada)

1) Abrir o app → Menu → Investments → **Dividends**
2) Validar o dropdown **Account**:
   - **All**: form de dividendos fica desabilitado e a tabela lista dividendos de todas as contas
   - **TFSA/RRSP/Non-Registered**: habilita o `DividendLogForm` e a tabela filtra para a conta selecionada
3) Validar filtro por Symbol (dropdown) e ordenação por coluna na tabela
4) Validar o card **Totals** acima da tabela:
   - Em conta específica: mostra o total do que está sendo exibido (respeita o filtro por Symbol)
   - Em All: mostra o total geral + breakdown por conta (respeita o filtro por Symbol)