# Módulos de Gestão Financeira e de Caixa

Este documento descreve os módulos de gestão financeira e de caixa implementados para a plataforma SaaS de barbearias.

## Visão Geral

O sistema financeiro inclui:
- **Gestão de Caixa**: Controle de abertura/fechamento, suplementos e retiradas
- **Pedidos**: Sistema completo de vendas com múltiplos itens e pagamentos
- **Financeiro**: Receitas, despesas, transferências, contas a receber/pagar
- **Auditoria**: Rastreamento completo de todas as operações financeiras

## Estrutura dos Módulos

### 1. Gestão de Caixa (CashController)

#### Endpoints Principais

- `POST /api/cash/open` - Abrir caixa
- `POST /api/cash/close` - Fechar caixa
- `GET /api/cash/status` - Status atual do caixa
- `GET /api/cash/history` - Histórico de operações do caixa
- `POST /api/cash/{id}/supplement` - Adicionar suplemento
- `POST /api/cash/{id}/withdraw` - Retirar dinheiro

#### Exemplo de Abertura de Caixa
```json
POST /api/cash/open
{
  "opening_balance": 100.00,
  "notes": "Abertura do dia"
}
```

### 2. Sistema de Pedidos (OrderController)

#### Endpoints Principais

- `POST /api/orders` - Criar pedido
- `GET /api/orders` - Listar pedidos
- `GET /api/orders/{id}` - Detalhes do pedido
- `POST /api/orders/{id}/cancel` - Cancelar pedido
- `POST /api/orders/{id}/complete` - Completar pedido
- `POST /api/orders/{id}/payments` - Adicionar pagamento

#### Exemplo de Criação de Pedido
```json
POST /api/orders
{
  "customer_name": "João Silva",
  "customer_phone": "11999999999",
  "items": [
    {
      "service_id": 1,
      "quantity": 1,
      "unit_price": 25.00,
      "discount": 0.00
    }
  ],
  "payments": [
    {
      "payment_method_id": 1,
      "amount": 25.00
    }
  ]
}
```

### 3. Gestão Financeira (FinancialController)

#### Endpoints Principais

- `POST /api/financial/income` - Registrar receita
- `POST /api/financial/expense` - Registrar despesa
- `POST /api/financial/transfer` - Transferência entre contas
- `POST /api/financial/receivables` - Criar conta a receber
- `POST /api/financial/payables` - Criar conta a pagar
- `GET /api/financial/balance` - Balanço financeiro
- `GET /api/financial/cash-flow` - Fluxo de caixa
- `GET /api/financial/transactions` - Listar transações

#### Exemplo de Registro de Receita
```json
POST /api/financial/income
{
  "amount": 150.00,
  "description": "Serviço de corte de cabelo",
  "category_id": 1,
  "bank_account_id": 1,
  "date": "2024-01-15"
}
```

#### Exemplo de Conta a Receber
```json
POST /api/financial/receivables
{
  "description": "Serviço para cliente VIP",
  "amount": 200.00,
  "due_date": "2024-02-15",
  "customer_name": "Maria Santos",
  "category_id": 2
}
```

## Modelos de Dados

### Principais Tabelas

1. **cash_registers** - Registra caixas
2. **cash_openings** - Aberturas de caixa
3. **cash_closings** - Fechamentos de caixa
4. **orders** - Pedidos de venda
5. **order_items** - Itens dos pedidos
6. **order_payments** - Pagamentos dos pedidos
7. **financial_transactions** - Todas as transações financeiras
8. **accounts_receivable** - Contas a receber
9. **accounts_payable** - Contas a pagar
10. **financial_categories** - Categorias financeiras
11. **bank_accounts** - Contas bancárias
12. **financial_audit_log** - Log de auditoria

## Serviços Implementados

### CashService
- Gerenciamento completo do ciclo de vida do caixa
- Validações de estado e saldo
- Suplementos e retiradas com auditoria

### OrderService
- Processamento de pedidos com múltiplos itens
- Gestão de pagamentos parciais
- Cálculos automáticos de totais e descontos
- Integração com métodos de pagamento

### FinancialService
- Registro de receitas e despesas
- Transferências entre contas
- Gestão de contas a receber/pagar
- Relatórios financeiros
- Reversão de transações com auditoria

## Segurança e Auditoria

- **Multi-tenant**: Isolamento completo por empresa
- **Auditoria**: Todas as operações são logadas
- **Validações**: Regras de negócio rigorosas
- **Transações**: Operações atômicas para consistência
- **Autenticação**: Controle de acesso baseado em roles

## Integração com Celcoin

O sistema financeiro integra-se com o gateway de pagamentos Celcoin existente:
- Transações são registradas automaticamente
- Reconciliação automática de pagamentos
- Webhooks processados e auditados
- Sincronização bidirecional

## Próximos Passos

1. **Testes**: Criar suítes de teste unitários e de integração
2. **Dashboard**: Interface web para visualização dos dados
3. **Relatórios**: Geração de relatórios avançados (PDF, Excel)
4. **Notificações**: Alertas para pagamentos vencidos
5. **API Externa**: Endpoints para integração com ERPs
6. **Mobile**: App mobile para gestão financeira

## Considerações Técnicas

- **PHP 8+** com arquitetura MVC customizada
- **PDO** para acesso a dados com prepared statements
- **Transações** para garantir consistência
- **PSR-4** autoloading
- **Middleware** para autenticação e autorização
- **JSON API** para comunicação frontend/backend