# 🚀 Plano de Implementação - Integração Backend Workspace

**Data**: 2026-01-26  
**Objetivo**: Integrar comunicação com backend, alimentar telas existentes e aplicar tags de status

---

## 📊 Status Atual das Telas

| Tela | Status Atual | Backend | Ação Necessária |
|------|--------------|---------|-----------------|
| Dashboard | 🚧 Em Construção | ❌ Não | Manter tag, não implementar ainda |
| Receitas | 👁️ Demo | ⚠️ Parcial | Integrar endpoints disponíveis |
| Despesas | 👁️ Demo | ⚠️ Parcial | Integrar endpoints disponíveis |
| Conciliação | ✅ Ativo | ✅ Sim | ✅ Já implementado |
| Config | 🚧 Em Construção | ❌ Não | Manter tag, não implementar ainda |

---

## 🎯 Objetivos

1. ✅ **Conciliação Bancária**: Já implementada e funcional
2. 🔄 **Receitas (Entradas)**: Integrar endpoints de boletos, clientes e serviços
3. 🔄 **Despesas (Saídas)**: Integrar endpoints de contas a pagar e extrato
4. 🚧 **Dashboard**: Manter em construção (sem backend ainda)
5. 🚧 **Configurações**: Manter em construção (sem backend ainda)

---

## 📋 Tarefas de Implementação

### ✅ Fase 1: Conciliação Bancária (COMPLETA)
- [x] Service `workspaceConciliacaoService.js` criado
- [x] Hook `useWorkspaceConciliacao.js` criado
- [x] View `ReconciliationView.jsx` integrada
- [x] Rotas implementadas:
  - `/categorias/transacoes/pendentes`
  - `/categorias/cruzamentos`
  - `/categorias/cruzamentos/detalhes`
  - `/categorias/cruzamentos/detalhes/descricao`

### 🔄 Fase 2: Receitas (Entradas) - EM PROGRESSO

#### 2.1 Criar Service de Receitas
**Arquivo**: `src/services/workspaceReceitasService.js`

**Endpoints a implementar**:
- `fetchBoletos()` → `GET /boletos/status`
- `fetchClientes()` → `GET /empresas_financeiro`
- `fetchServicos()` → `GET /servicos/list`

**Status**: ⏳ Pendente

#### 2.2 Criar Hook de Receitas
**Arquivo**: `src/features/workspace/hooks/useWorkspaceReceitas.js`

**Funcionalidades**:
- Gerenciar estado de boletos, clientes e serviços
- Loading states
- Error handling
- Filtros e busca

**Status**: ⏳ Pendente

#### 2.3 Atualizar IncomesView
**Arquivo**: `src/features/workspace/views/IncomesView.jsx`

**Mudanças**:
- Integrar `useWorkspaceReceitas`
- Substituir `MOCK_BOLETOS`, `MOCK_CLIENTS`, `MOCK_SERVICES` por dados reais
- Manter tag "Demonstração Visual" até completar todas as integrações
- Adicionar loading states

**Status**: ⏳ Pendente

### 🔄 Fase 3: Despesas (Saídas) - EM PROGRESSO

#### 3.1 Criar Service de Despesas
**Arquivo**: `src/services/workspaceDespesasService.js`

**Endpoints a implementar**:
- `fetchContasAPagar()` → `GET /contas_a_pagar/apresentar`
- `fetchExtratoSaidas()` → `GET /extrato/apresentar` (filtrado por tipoOperacao === "D")
- `fetchFluxoCaixa()` → `GET /extrato/fluxo`

**Status**: ⏳ Pendente

#### 3.2 Criar Hook de Despesas
**Arquivo**: `src/features/workspace/hooks/useWorkspaceDespesas.js`

**Funcionalidades**:
- Gerenciar estado de contas a pagar e extrato
- Cálculo de totais (planejado vs executado)
- Filtros por período
- Loading states

**Status**: ⏳ Pendente

#### 3.3 Atualizar ExpensesView
**Arquivo**: `src/features/workspace/views/ExpensesView.jsx`

**Mudanças**:
- Integrar `useWorkspaceDespesas`
- Substituir dados mock por dados reais
- Manter tag "Demonstração Visual" até completar
- Adicionar loading states

**Status**: ⏳ Pendente

### 🚧 Fase 4: Dashboard - NÃO IMPLEMENTAR AINDA

**Razão**: Backend não está completo para dashboard  
**Ação**: Manter tag "Em Construção" e placeholder atual

### 🚧 Fase 5: Configurações - NÃO IMPLEMENTAR AINDA

**Razão**: Backend não está completo para configurações  
**Ação**: Manter tag "Em Construção" e placeholder atual

---

## 🔧 Estrutura de Arquivos a Criar/Modificar

### Novos Arquivos
```
src/services/
  ├── workspaceReceitasService.js      [NOVO]
  └── workspaceDespesasService.js     [NOVO]

src/features/workspace/hooks/
  ├── useWorkspaceReceitas.js         [NOVO]
  └── useWorkspaceDespesas.js         [NOVO]
```

### Arquivos a Modificar
```
src/features/workspace/views/
  ├── IncomesView.jsx                 [MODIFICAR]
  └── ExpensesView.jsx               [MODIFICAR]

src/features/workspace/utils/
  └── backendStatus.js               [ATUALIZAR]
```

---

## 📝 Padrões de Implementação

### 1. Service Pattern
```javascript
import api from './api';
import { handleRequest, simulateLatency } from './serviceUtils';
import { MOCK_DATA } from '../features/workspace/mockData';

export const workspaceXService = {
  fetchX: (filters = {}) => handleRequest({
    mockFn: () => simulateLatency(MOCK_DATA),
    apiFn: () => {
      const params = new URLSearchParams();
      Object.entries(filters).forEach(([key, value]) => {
        if (value !== null && value !== undefined) {
          params.append(key, value);
        }
      });
      const queryString = params.toString();
      return api.get(`/endpoint${queryString ? `?${queryString}` : ''}`);
    }
  })
};
```

### 2. Hook Pattern
```javascript
import { useState, useEffect, useMemo } from 'react';
import { workspaceXService } from '@/services/workspaceXService';
import { toast } from 'sonner';

export const useWorkspaceX = () => {
  const [data, setData] = useState([]);
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState(null);

  const loadData = async (filters = {}) => {
    setIsLoading(true);
    setError(null);
    try {
      const result = await workspaceXService.fetchX(filters);
      setData(Array.isArray(result) ? result : []);
    } catch (err) {
      console.error('Erro ao carregar dados:', err);
      setError(err.message || 'Erro ao carregar dados');
      toast.error('Erro ao carregar dados');
      setData([]);
    } finally {
      setIsLoading(false);
    }
  };

  useEffect(() => {
    loadData();
  }, []);

  return {
    state: { data, isLoading, error },
    actions: { loadData }
  };
};
```

### 3. View Pattern (com StatusBadge)
```javascript
import { StatusBadge } from '../components/StatusBadge';
import { getBackendStatus } from '../utils/backendStatus';
import { useWorkspaceX } from '../hooks/useWorkspaceX';

export const XView = () => {
  const { state, actions } = useWorkspaceX();
  const status = getBackendStatus('x');

  return (
    <div>
      <StatusBadge status={status} />
      {/* Conteúdo da view */}
    </div>
  );
};
```

---

## 🏷️ Sistema de Tags

### Status "active" (✅)
- Tela com backend completo e funcional
- **Não exibe badge**
- Exemplo: Conciliação Bancária

### Status "demo" (👁️)
- Tela com dados mock ou parcialmente integrada
- **Badge azul**: "Demonstração Visual"
- Exemplo: Receitas, Despesas (até completar integração)

### Status "construction" (🚧)
- Tela sem backend ou em desenvolvimento
- **Badge amarelo**: "Em Construção"
- Exemplo: Dashboard, Configurações

---

## 🔍 Mapeamento de Rotas da Lógica Antiga

### Rotas que DEVEM ser implementadas:

#### Receitas
- ✅ `/boletos/status` → `workspaceReceitasService.fetchBoletos()`
- ✅ `/empresas_financeiro` → `workspaceReceitasService.fetchClientes()`
- ✅ `/servicos/list` → `workspaceReceitasService.fetchServicos()`

#### Despesas
- ✅ `/contas_a_pagar/apresentar` → `workspaceDespesasService.fetchContasAPagar()`
- ✅ `/extrato/apresentar` → `workspaceDespesasService.fetchExtratoSaidas()` (filtro tipoOperacao === "D")
- ✅ `/extrato/fluxo` → `workspaceDespesasService.fetchFluxoCaixa()`

### Rotas que NÃO devem ser reutilizadas:
- `/servicos_financeiro` - Sistema antigo específico
- `/vendas_realizadas` - Sistema antigo específico
- Qualquer rota não documentada acima

---

## ✅ Checklist de Implementação

### Receitas (Entradas)
- [ ] Criar `workspaceReceitasService.js`
- [ ] Implementar `fetchBoletos()`
- [ ] Implementar `fetchClientes()`
- [ ] Implementar `fetchServicos()`
- [ ] Criar `useWorkspaceReceitas.js`
- [ ] Atualizar `IncomesView.jsx`
- [ ] Testar integração
- [ ] Atualizar `backendStatus.js` quando completo

### Despesas (Saídas)
- [ ] Criar `workspaceDespesasService.js`
- [ ] Implementar `fetchContasAPagar()`
- [ ] Implementar `fetchExtratoSaidas()`
- [ ] Implementar `fetchFluxoCaixa()`
- [ ] Criar `useWorkspaceDespesas.js`
- [ ] Atualizar `ExpensesView.jsx`
- [ ] Testar integração
- [ ] Atualizar `backendStatus.js` quando completo

---

## 🎨 Componentes de Status

### StatusBadge
Já implementado em `src/features/workspace/components/StatusBadge.jsx`

**Uso**:
```jsx
<StatusBadge status="demo" />      // Badge azul
<StatusBadge status="construction" /> // Badge amarelo
<StatusBadge status="active" />     // Não exibe (null)
```

### backendStatus.js
Já implementado em `src/features/workspace/utils/backendStatus.js`

**Atualizar quando completar integração**:
```javascript
const SCREEN_STATUS_MAP = {
  dashboard: 'construction',
  entradas: 'demo',        // Mudar para 'active' quando completo
  saidas: 'demo',          // Mudar para 'active' quando completo
  conciliacao: 'active',
  config: 'construction'
};
```

---

## 📚 Referências

- Lógica antiga: Código fornecido pelo usuário
- Rotas atuais: Documentadas em `WORKSPACE_BACKEND_ROUTES.md`
- Padrões: Seguir estrutura de `workspaceConciliacaoService.js`

---

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