# 🗺️ Mapeamento de Rotas do Backend - Workspace

**Data**: 2026-01-26  
**Objetivo**: Documentar todas as rotas disponíveis no backend e mapear quais telas possuem integração

---

## 📋 Status das Telas

| Tela | Status | Backend | Observações |
|------|--------|---------|-------------|
| **Dashboard** | 🚧 Em Construção | ❌ Não | Aguardando consolidação de dados |
| **Receitas (Entradas)** | 👁️ Demonstração Visual | ⚠️ Parcial | Alguns endpoints disponíveis |
| **Despesas (Saídas)** | 👁️ Demonstração Visual | ⚠️ Parcial | Alguns endpoints disponíveis |
| **Conciliação Bancária** | ✅ Ativo | ✅ Sim | Rotas completas disponíveis |
| **Configurações** | 🚧 Em Construção | ❌ Não | Módulo em desenvolvimento |

---

## 🔌 Rotas de Conciliação Bancária (✅ Implementadas)

### Transações Pendentes
```
GET /categorias/transacoes/pendentes
```
**Descrição**: Retorna todas as transações que ainda não foram conciliadas  
**Status**: ✅ Implementado em `workspaceConciliacaoService.fetchPendentes()`  
**Uso**: Tab "Pendências" na `ReconciliationView`

**Resposta esperada**:
```json
[
  {
    "id": 1,
    "data": "2025-01-15",
    "descricao": "PIX RECEBIDO - CLIENTE XYZ",
    "valor": 1500.00,
    "tipo": "C"
  }
]
```

### Cruzamentos
```
GET /categorias/cruzamentos?caixinha={id}&mes={mes}&ano={ano}
```
**Descrição**: Retorna cruzamentos de transações com filtros opcionais  
**Status**: ✅ Implementado em `workspaceConciliacaoService.fetchCruzamentos()`  
**Uso**: Tab "Cruzamento" na `ReconciliationView`

**Parâmetros de Query**:
- `caixinha` (opcional): ID da caixinha
- `mes` (opcional): Mês (1-12)
- `ano` (opcional): Ano (ex: 2025)

**Exemplos**:
- `/categorias/cruzamentos?caixinha=1`
- `/categorias/cruzamentos?mes=10`
- `/categorias/cruzamentos?ano=2025`
- `/categorias/cruzamentos?caixinha=1&mes=10&ano=2025`

### Detalhes de Cruzamentos
```
GET /categorias/cruzamentos/detalhes?caixinha={id}&mes={mes}&ano={ano}
```
**Descrição**: Retorna detalhes expandidos dos cruzamentos  
**Status**: ✅ Implementado em `workspaceConciliacaoService.fetchCruzamentosDetalhes()`  
**Uso**: Visualização detalhada de cruzamentos

### Detalhes por Descrição
```
GET /categorias/cruzamentos/detalhes/descricao?caixinha={id}&mes={mes}&ano={ano}&descricao={texto}
```
**Descrição**: Busca cruzamentos filtrados por descrição  
**Status**: ✅ Implementado em `workspaceConciliacaoService.fetchCruzamentosDetalhesDescricao()`  
**Uso**: Busca de transações específicas

---

## 📊 Rotas de Receitas (Entradas) - ⚠️ Parcial

### Boletos
```
GET /boletos/status
```
**Descrição**: Lista todos os boletos com seus status  
**Status**: ⚠️ Endpoint disponível, mas não integrado no Workspace  
**Uso**: Tab "Boletos" na `IncomesView`

**Nota**: A lógica antiga mostra que este endpoint retorna:
```json
{
  "Boletos_GET": {
    "cobrancas": [
      {
        "cobranca": {
          "codigoSolicitacao": "...",
          "dataEmissao": "...",
          "dataVencimento": "...",
          "valorNominal": 1000.00,
          "situacao": "RECEBIDO",
          "pagador": { "nome": "..." }
        }
      }
    ]
  }
}
```

### Clientes/Empresas
```
GET /empresas_financeiro
```
**Descrição**: Lista todas as empresas/clientes  
**Status**: ⚠️ Endpoint disponível, mas não integrado no Workspace  
**Uso**: Tab "Clientes" na `IncomesView`

### Serviços
```
GET /servicos/list
```
**Descrição**: Lista todos os serviços cadastrados  
**Status**: ⚠️ Endpoint disponível, mas não integrado no Workspace  
**Uso**: Tab "Serviços" na `IncomesView`

---

## 💸 Rotas de Despesas (Saídas) - ⚠️ Parcial

### Contas a Pagar
```
GET /contas_a_pagar/apresentar
```
**Descrição**: Lista todas as contas a pagar planejadas  
**Status**: ⚠️ Endpoint disponível, mas não integrado no Workspace  
**Uso**: Visualização de despesas planejadas na `ExpensesView`

### Extrato (Saídas)
```
GET /extrato/apresentar
```
**Descrição**: Lista todas as transações do extrato bancário  
**Status**: ⚠️ Endpoint disponível, mas não integrado no Workspace  
**Uso**: Visualização de despesas executadas na `ExpensesView`

**Filtro**: Apenas transações com `tipoOperacao === "D"` (Débito)

---

## ⚙️ Rotas de Configuração - 🚧 Em Construção

### Categorias
```
GET /categorias/apresentar
POST /categorias/create
POST /categorias/edit
DELETE /categorias/apresentar/{id}
```
**Status**: ⚠️ Endpoints disponíveis, mas não integrados no Workspace  
**Uso**: Tab "Configurações" > "Categorias" na `ReconciliationView`

### Regras
```
GET /regras/apresentar
POST /regra/create
POST /regras/edit
```
**Status**: ⚠️ Endpoints disponíveis, mas não integrados no Workspace  
**Uso**: Tab "Configurações" > "Regras de Importação" na `ReconciliationView`

### Caixinhas
```
GET /caixinhas/apresentar
POST /caixinha/create
POST /caixinha/edit
```
**Status**: ⚠️ Endpoints disponíveis, mas não integrados no Workspace  
**Uso**: Tab "Configurações" > "Mapeamento de Caixas" na `ReconciliationView`

---

## 🔐 Rotas de Autenticação - ✅ Implementadas

### Login (Primeiro Passo)
```
POST /auth
Body: { username, password, Passo: 1, data_envio }
```
- `data_envio`: data atual em `YYYY-M-D` (ex.: `2026-1-26`).
- Resposta `200` + `token` → autenticação completa; armazena token e redireciona.
- Resposta `200` + `Result_Forme === "Autenticação"` → exige 2FA; exibe painel de código (6 dígitos).

**Status**: ✅ Implementado em `src/features/workspace/hooks/useWorkspaceAuth.js` (`handleFirstLogin`)  
**Uso**: `LoginView` (Workspace)

### Login (Segundo Passo - 2FA)
```
POST /auth
Body: { username, password, code_secret, Passo: 2 }
```
- `code_secret`: código de 6 dígitos.
- Resposta `200` + `token` → sucesso; armazena token e redireciona para `/plataforma/workspace`.

**Status**: ✅ Implementado em `useWorkspaceAuth.handleSecondLogin()`  
**Uso**: `LoginView` (segunda etapa)

---

## 📈 Rotas de Dashboard - 🚧 Em Construção

### Saldo
```
GET /saldo
```
**Descrição**: Retorna saldo bancário atual  
**Status**: ⚠️ Endpoint disponível, mas não integrado no Workspace  
**Uso**: Dashboard principal

### Fluxo de Caixa
```
GET /extrato/fluxo
```
**Descrição**: Retorna dados de fluxo de caixa mensal/anual  
**Status**: ⚠️ Endpoint disponível, mas não integrado no Workspace  
**Uso**: Dashboard principal

### Boletos (Resumo)
```
GET /boletos/status
```
**Descrição**: Resumo de boletos para dashboard  
**Status**: ⚠️ Endpoint disponível, mas não integrado no Workspace  
**Uso**: Dashboard principal

---

## 🎯 Plano de Implementação

### Fase 1: Conciliação Bancária (✅ Completo)
- [x] Rotas de pendentes implementadas
- [x] Rotas de cruzamentos implementadas
- [x] Rotas de detalhes implementadas
- [x] Hooks criados (`useWorkspaceConciliacao`)
- [x] Service criado (`workspaceConciliacaoService`)

### Fase 2: Receitas (Entradas) - ⚠️ Em Progresso
- [ ] Criar `workspaceReceitasService.js`
- [ ] Implementar `fetchBoletos()`
- [ ] Implementar `fetchClientes()`
- [ ] Implementar `fetchServicos()`
- [ ] Criar hook `useWorkspaceReceitas`
- [ ] Atualizar `IncomesView` para usar dados reais
- [ ] Manter tag "Demonstração Visual" até completar

### Fase 3: Despesas (Saídas) - ⚠️ Em Progresso
- [ ] Criar `workspaceDespesasService.js`
- [ ] Implementar `fetchContasAPagar()`
- [ ] Implementar `fetchExtratoSaidas()`
- [ ] Criar hook `useWorkspaceDespesas`
- [ ] Atualizar `ExpensesView` para usar dados reais
- [ ] Manter tag "Demonstração Visual" até completar

### Fase 4: Configurações - 🚧 Planejado
- [ ] Criar `workspaceConfigService.js`
- [ ] Implementar CRUD de Categorias
- [ ] Implementar CRUD de Regras
- [ ] Implementar CRUD de Caixinhas
- [ ] Criar hooks específicos
- [ ] Atualizar tab "Config" na `ReconciliationView`
- [ ] Manter tag "Em Construção" até completar

### Fase 5: Dashboard - 🚧 Planejado
- [ ] Criar `workspaceDashboardService.js`
- [ ] Implementar `fetchSaldo()`
- [ ] Implementar `fetchFluxoCaixa()`
- [ ] Implementar `fetchResumoBoletos()`
- [ ] Criar hook `useWorkspaceDashboard`
- [ ] Atualizar `WorkspaceLayout` (tela dashboard)
- [ ] Manter tag "Em Construção" até completar

---

## 📝 Notas de Implementação

### Padrão de Service
Todos os services devem seguir o padrão:
```javascript
import api from './api';
import { handleRequest, simulateLatency } from './serviceUtils';
import { MOCK_DATA } from '../features/workspace/mockData';

export const workspaceXService = {
  fetchX: () => handleRequest({
    mockFn: () => simulateLatency(MOCK_DATA),
    apiFn: () => api.get('/endpoint')
  })
};
```

### Padrão de Hook
Todos os hooks devem seguir o padrão:
```javascript
import { useState, useEffect } from 'react';
import { workspaceXService } from '@/services/workspaceXService';

export const useWorkspaceX = () => {
  const [data, setData] = useState([]);
  const [isLoading, setIsLoading] = useState(false);
  
  const loadData = async () => {
    setIsLoading(true);
    try {
      const result = await workspaceXService.fetchX();
      setData(Array.isArray(result) ? result : []);
    } catch (err) {
      console.error('Erro:', err);
    } finally {
      setIsLoading(false);
    }
  };
  
  useEffect(() => {
    loadData();
  }, []);
  
  return { data, isLoading, loadData };
};
```

### Tags de Status
- **✅ Ativo**: Tela com backend completo - sem badge
- **👁️ Demonstração Visual**: Tela com dados mock - badge azul
- **🚧 Em Construção**: Tela sem backend - badge amarelo

---

## 🔄 Rotas da Lógica Antiga (Referência)

### Rotas que DEVEM ser implementadas:
1. `/boletos/status` - Status de boletos
2. `/empresas_financeiro` - Lista de empresas/clientes
3. `/servicos/list` - Lista de serviços
4. `/contas_a_pagar/apresentar` - Contas a pagar
5. `/extrato/apresentar` - Extrato bancário
6. `/categorias/apresentar` - Categorias
7. `/regras/apresentar` - Regras
8. `/caixinhas/apresentar` - Caixinhas
9. `/saldo` - Saldo bancário
10. `/extrato/fluxo` - Fluxo de caixa

### Rotas que NÃO devem ser reutilizadas (específicas do sistema antigo):
- `/servicos_financeiro` - Sistema antigo
- `/vendas_realizadas` - Sistema antigo
- Qualquer rota que não esteja documentada acima

---

*Documento criado em 2026-01-26 para guiar a implementação da integração backend no ambiente Workspace.*