332 lines
9.3 KiB
Markdown
332 lines
9.3 KiB
Markdown
# 🚀 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.*
|