# Fluxos: Modulo Finance - Pagamentos a Colaboradores

---

## 11.1 Criar Pagamento Recorrente

```
Usuario
  ↓
Finance → Pagamentos → Recorrencia → Botao "Novo"
  ↓
GET /finance/payments/collaborator/recurrence/add
  ↓
PaymentsController@collaborators_recurrence_add
  ↓
CoreCollaborator (ordenado por nome)
  ↓
View: pages/finance/payments/collaborators/add_recurrence
  ↓
Seleciona colaborador, conta bancaria, descricao, valor, prioridade
  ↓
POST /finance/payments/collaborator/recurrence/store
  ↓
PaymentsController@collaborators_recurrence_store
  ↓
Validacao: collaborator_id (exists), bank_account_id (exists, ativo, com PIX),
  reference_description, value, priority (1-3)
  ↓
DB::beginTransaction
  ↓
FinancePaymentsCollaboratorRecurrence::create
  ↓
DB::commit
  ↓
JSON {success, data, redirect}
```

**Tela inicial:** Formulario de novo pagamento recorrente
**Acao do usuario:** Define colaborador, conta, valor e prioridade
**Requisicao:** `POST /finance/payments/collaborator/recurrence/store`
**Controller:** `PaymentsController@collaborators_recurrence_store`
**Tabelas alteradas:** `finance_payments_collab_recurrence` (INSERT)
**Tabelas consultadas:** `core_collaborators`, `finance_collaborator_bank_accounts`, `core_collaborator_contracts`
**Resultado esperado:** Item de pagamento recorrente criado, incluido no proximo snapshot
**Possiveis erros:**
- Conta bancaria sem PIX → validacao falha
- Colaborador inexistente → 422

---

## 11.2 Editar/Desativar Pagamento Recorrente

```
POST /finance/payments/collaborator/recurrence/update
  ↓
Validacao: id (exists), value, reference_description, bank_id (exists), priority (1-3)
  ↓
FinancePaymentsCollaboratorRecurrence::update
  ↓
JSON {success}

POST /finance/payments/collaborator/recurrence/cancel
  ↓
Validacao: id (exists), action (disable/enable)
  ↓
FinancePaymentsCollaboratorRecurrence::update(status toggle)
  ↓
JSON {success}
```

---

## 11.3 Visualizar Snapshot de Pagamentos

```
Usuario
  ↓
Finance → Pagamentos → Snapshots → Lista
  ↓
GET /finance/payments/collaborator/snapshot/recurrence
  ↓
PaymentsController@snapshot_view
  ↓
View: pages/finance/payments/collaborators/snapshot/index
  ↓
AJAX: POST .../list/ajax
  ↓
FinancePaymentCollabSnapshot (tipo recurrence ou award)
  ↓
Seleciona snapshot → Ver detalhes
  ↓
GET /finance/payments/collaborator/snapshot/recurrence/view/{id}
  ↓
PaymentsController@snapshot_details_view
  ↓
View: pages/finance/payments/collaborators/snapshot/view
  ↓
AJAX: POST .../items/ajax/{id}
  ↓
PaymentsController@snapshot_items_ajax
  ↓
FinancePaymentCollabSnapshotItem (com collaborator, transacao, contrato, NF, comprovantes)
  ↓
JSON DataTables (com URLs assinadas para comprovantes)
```

**Tela inicial:** Lista de Snapshots → Detalhes
**Acao do usuario:** Navega pelos snapshots e visualiza itens
**APIs chamadas:** Google Cloud Storage (URLs assinadas para comprovantes)

---

## 11.4 Editar Item do Snapshot

```
Usuario
  ↓
Detalhes Snapshot → Editar item
  ↓
POST /finance/payments/collaborator/snapshot/recurrence/item/update
  ↓
PaymentsController@snapshot_recurrence_item_update
  ↓
Validacao: item_id (exists), value, reference_description, priority (1-3)
Validacao: snapshot em 'draft', antes do lock_date, item em 'draft'
  ↓
FinancePaymentCollabSnapshotItem::update(value, reference_description, priority)
  ↓
JSON {success, data}
```

**Tela inicial:** Detalhes do Snapshot
**Acao do usuario:** Altera valor, descricao ou prioridade de um item
**Requisicao:** `POST .../item/update`
**Controller:** `PaymentsController@snapshot_recurrence_item_update`
**Tabelas alteradas:** `finance_payment_collab_snapshot_items` (UPDATE)
**Possiveis erros:**
- Snapshot nao esta em draft → erro
- Apos lock_date → erro
- Item nao esta em draft → erro

---

## 11.5 Cancelar Item do Snapshot

```
POST .../item/cancel
  ↓
PaymentsController@snapshot_recurrence_item_cancel
  ↓
Validacao: snapshot em 'draft'
  ↓
FinancePaymentCollabSnapshotItem::update(status='cancelled')
SnapshotStatusService::closeIfCompletedForSnapshot
  ↓
JSON {success, snapshot_closed}
```

**Tabelas alteradas:** `finance_payment_collab_snapshot_items` (status='cancelled')
**Services:** SnapshotStatusService (verifica se todos itens finalizados → fecha snapshot)

---

## 11.6 Restaurar Item Cancelado

```
POST .../item/restore
  ↓
PaymentsController@snapshot_recurrence_item_restore
  ↓
Validacao: snapshot em 'draft', item em 'cancelled', antes do lock_date
  ↓
FinancePaymentCollabSnapshotItem::update(status='draft')
  ↓
JSON {success}
```

**Tabelas alteradas:** `finance_payment_collab_snapshot_items` (status='draft')