testes/.agent/project/WORKSPACE_BACKEND_IMPLEMENTATION.md

🚀 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)

• Service workspaceConciliacaoService.js criado
• Hook useWorkspaceConciliacao.js criado
• View ReconciliationView.jsx integrada
• 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

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

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)

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:

<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:

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.