# Documentação do Workspace

Consulte este arquivo para informações completas sobre o ambiente Workspace do Integra Finance (PRALOG).

---

## Visão Geral

O **Workspace** é o ambiente principal de gestão financeira do sistema, oferecendo uma interface unificada para gerenciamento de receitas, despesas e conciliação bancária. O ambiente foi desenvolvido seguindo o design premium do Prafrota, utilizando a paleta azul (#26b1c7) como cor de identidade visual.

---

## Arquitetura

### Estrutura de Componentes

```
src/features/workspace/
├── components/
│   ├── WorkspaceLayout.jsx      # Container principal do ambiente
│   ├── WorkspaceSidebar.jsx     # Sidebar de navegação
│   ├── WorkspaceGuard.jsx       # Proteção de rotas
│   └── WorkspaceSidebar.css     # Estilos da sidebar
├── views/
│   ├── LoginView.jsx            # Tela de login
│   ├── IncomesView.jsx          # Tela de receitas (legado)
│   ├── ExpensesView.jsx         # Tela de despesas (legado)
│   └── ReconciliationView.jsx   # Tela de conciliação (legado)
└── index.jsx                    # Exports públicos
```

### Integração com Financeiro V2

O Workspace utiliza os módulos do **financeiro-v2** para renderizar as telas principais:

- **Receitas (Entradas)**: `ContasReceberView` (`src/features/financeiro-v2/views/contas-receber/ContasReceberView.jsx`)
- **Despesas (Saídas)**: `ContasPagarView` (`src/features/financeiro-v2/views/contas-pagar/ContasPagarView.jsx`)
- **Conciliação**: `ConciliacaoView` (`src/features/financeiro-v2/views/conciliacao-v2/ConciliacaoView.jsx`)

---

## Módulos Principais

### 1. Receitas (Entradas)

**Componente**: `ContasReceberView`

**Sub-módulos**:
- **Cruzamento**: Visualização cruzada de entradas planejadas vs executadas
- **Entradas Planejadas**: Gestão de estimativas (quotes)
- **Boletos**: Gestão de boletos e faturas
- **Clientes**: Cadastro e gestão de clientes
- **Serviços**: Catálogo de serviços oferecidos

**Hooks utilizados**:
- `useContasReceber` (`src/features/financeiro-v2/hooks/useContasReceber.js`)

**Funcionalidades**:
- Criação e edição de estimativas
- Gestão de clientes com painel detalhado
- Catálogo de serviços (CRUD)
- Visualização de boletos com filtros e ações
- Cruzamento de dados planejados vs executados

### 2. Despesas (Saídas)

**Componente**: `ContasPagarView`

**Sub-módulos**:
- **Fornecedores**: Cadastro e gestão de fornecedores
- **Despesas**: Registro e gestão de despesas
- **Cruzamento de Despesas**: Comparação entre planejado vs executado

**Hooks utilizados**:
- `useContasPagar` (`src/features/financeiro-v2/hooks/useContasPagar.js`)

**Funcionalidades**:
- Cadastro de fornecedores com informações completas
- Registro de despesas com lançamentos contábeis (diário)
- Upload de recibos
- Filtros por status (Faturável, Não Faturável, Pendente, Pago)
- Visualização de cruzamento com gráficos comparativos

### 3. Conciliação Bancária

**Componente**: `ConciliacaoView`

**Sub-módulos**:
- **Transações Conciliadas**: Navegação hierárquica (Caixas → Categorias → Regras → Transações)
- **Não Categorizadas**: Transações pendentes de categorização
- **Gerenciamento**: Gestão de caixas, categorias e regras

**Hooks utilizados**:
- `useConciliacaoV2` (`src/features/financeiro-v2/hooks/useConciliacaoV2.js`)

**Funcionalidades**:
- Navegação hierárquica com gráficos dinâmicos
- Categorização automática via regras
- Gestão de caixas financeiras
- Gestão de categorias e regras de conciliação
- Visualização de transações não categorizadas

---

## Componentes Principais

### WorkspaceLayout

**Arquivo**: `src/features/workspace/components/WorkspaceLayout.jsx`

**Responsabilidades**:
- Container principal do ambiente
- Gerenciamento de tema (dark/light mode)
- Controle de sidebar (colapsada/expandida)
- Renderização condicional de telas baseado em `activeScreen`
- Header simplificado com breadcrumb

**Estados**:
- `activeScreen`: Tela atual ('entradas', 'saidas', 'conciliacao', 'config', 'dashboard')
- `isSidebarCollapsed`: Estado da sidebar
- `isDarkMode`: Modo escuro/claro

### WorkspaceSidebar

**Arquivo**: `src/features/workspace/components/WorkspaceSidebar.jsx`

**Responsabilidades**:
- Navegação lateral com menu hierárquico
- Busca de itens do menu
- Expansão/colapso de grupos
- Integração com logo iTGUYS
- Animações com Framer Motion

**Estrutura do Menu**:
- Dashboard
- Financeiro
  - Receitas (Entradas)
  - Despesas (Saídas)
  - Conciliação Bancária
- Ajustes

### WorkspaceGuard

**Arquivo**: `src/features/workspace/components/WorkspaceGuard.jsx`

**Responsabilidades**:
- Proteção de rotas do Workspace
- Redirecionamento para login se não autenticado
- Validação de acesso ao ambiente

---

## Fluxo de Dados

### Estado Global

O Workspace utiliza hooks específicos do financeiro-v2 para gerenciar estado:

1. **useContasReceber**: Gerencia estado de receitas
   - Clientes, serviços, entradas planejadas, boletos
   - KPIs (total recebido, pendente, geral)

2. **useContasPagar**: Gerencia estado de despesas
   - Fornecedores, despesas, cruzamento
   - KPIs (total pago, pendente, atrasado)

3. **useConciliacaoV2**: Gerencia estado de conciliação
   - Transações conciliadas, não categorizadas
   - Caixas, categorias, regras

### Mock Data

Atualmente, os dados são mockados nos próprios hooks:
- `MOCK_CLIENTS`, `MOCK_SERVICES`, `MOCK_BOLETOS` em `useContasReceber`
- `MOCK_FORNECEDORES`, `MOCK_DESPESAS` em `useContasPagar`
- Dados de conciliação em `useConciliacaoV2`

**Próximo passo**: Migração para API real (ver schemas em `WORKSPACE_DATABASE_SCHEMAS.md`)

---

## Estilização

### Tema

- **Cor Principal**: `#26b1c7` (azul iTGUYS)
- **Modo Escuro**: Padrão (dark mode ativado por padrão)
- **Fonte**: Lato (font-lato)

### Componentes Visuais

- **Sidebar**: Largura 280px (expandida) / 100px (colapsada)
- **Header**: Altura fixa 64px (h-16)
- **Painéis Detalhados**: 50% da viewport width em desktop (`md:w-[50vw]`)
- **Backdrop**: Transparente em desktop para permitir interação com tabela

---

## Acessos de Desenvolvimento

- **URL Base**: `https://dev.workspace.itguys.com.br`
- **URL Plataforma**: `https://dev.workspace.itguys.com.br/plataforma/workspace`
- **Usuário**: `financeiro@pralog.com.br`
- **Senha**: `123Mudar`

---

## Dependências

### Internas
- `@/features/financeiro-v2` - Módulo financeiro v2
- `@/components/ui` - Componentes Shadcn UI
- `@/lib/utils` - Utilitários (cn, etc.)

### Externas
- `react` - Framework base
- `react-router-dom` - Roteamento
- `framer-motion` - Animações
- `lucide-react` - Ícones
- `recharts` - Gráficos (via financeiro-v2)

---

## Próximos Passos

1. **Integração com API**: Substituir mocks por chamadas reais à API
2. **Validações**: Implementar validações de formulários
3. **Testes**: Adicionar testes unitários e de integração
4. **Performance**: Otimizar renderizações e carregamento de dados
5. **Documentação de API**: Documentar endpoints necessários

---

*Documentação mantida pelo Documentation Agent. Última atualização: 2026-01-24*