# Fluxos: Modulo Core - Colaboradores

---

## 2.1 Listar Colaboradores

```
Usuario
  ↓
Menu Core → Colaboradores
  ↓
GET /core/collaborator/
  ↓
CollaboratorController@index_view
  ↓
View: pages/core/collaborators/index
  ↓
AJAX automatico:
POST /core/collaborator/list
  ↓
CollaboratorController@index_list_ajax
  ↓
CoreCollaborator (LEFT JOIN core_collaborator_contracts)
CoreCollabPendingChange (pending count)
  ↓
JSON DataTables
```

**Tela inicial:** Lista de Colaboradores
**Acao do usuario:** Acessa pagina de colaboradores
**Requisicao:** `GET /core/collaborator/` + `POST /core/collaborator/list` (AJAX)
**Controller:** `CollaboratorController@index_view` + `@index_list_ajax`
**Services:** DataTables (yajra)
**Tabelas consultadas:** `core_collaborators`, `core_collaborator_contracts`, `core_collab_pending_changes`
**APIs chamadas:** Nenhuma
**Resultado esperado:** Tabela com nome, departamento, cargo, tipo contrato, status
**Possiveis erros:** Nenhum esperado

---

## 2.2 Criar Colaborador

```
Usuario
  ↓
Tela Lista Colaboradores → Botao "Novo"
  ↓
GET /core/collaborator/add/
  ↓
CollaboratorController@add_view
  ↓
APIs: MondayApiController::getExentUsers(), SlackApiController::getUsers()
  ↓
View: pages/core/collaborators/add
  ↓
Preenche formulario → Botao "Salvar"
  ↓
POST /core/collaborator/store
  ↓
CollaboratorController@store
  ↓
Validacao: name (required), email (required, unique)
  ↓
DB::beginTransaction
  ↓
CoreCollaborator::create
CoreCollaboratorContract::create
FinanceCollaboratorBankAccount::create
BucketGoogleApiController::uploadToBucket (docs: CNH, RG, CPF, CIN)
  ↓
DB::commit
  ↓
JSON {success, collaborator_id}
```

**Tela inicial:** Formulario de adicao (`pages/core/collaborators/add`)
**Acao do usuario:** Preenche dados e clica em salvar
**Requisicao:** `POST /core/collaborator/store`
**Controller:** `CollaboratorController@store`
**Services:** FormatHelper (formatacao)
**Tabelas alteradas:**
- `core_collaborators` (INSERT)
- `core_collaborator_contracts` (INSERT)
- `finance_collaborator_bank_accounts` (INSERT)
**APIs chamadas:**
- Google Cloud Storage (upload de documentos via BucketGoogleApiController)
- Monday.com (lista usuarios, ao abrir formulario)
- Slack (lista usuarios, ao abrir formulario)
**Resultado esperado:** Colaborador criado, JSON com ID, redirect para detalhes
**Possiveis erros:**
- Email duplicado → validacao 422
- Falha upload documento → rollback DB
- Monday/Slack API offline → formulario abre sem lista de usuarios (graceful)

---

## 2.3 Editar Colaborador

```
Usuario
  ↓
Lista Colaboradores → Botao Editar
  ↓
GET /core/collaborator/edit/{id}/
  ↓
CollaboratorController@edit_view
  ↓
CoreCollaborator + Contract + BankAccounts + Payments
APIs: Monday, Slack (listas)
  ↓
View: pages/core/collaborators/edit
  ↓
Altera campos → Botao "Salvar"
  ↓
POST /core/collaborator/update/{id}/
  ↓
CollaboratorController@update
  ↓
Validacao: name, email (required)
  ↓
DB::beginTransaction
  ↓
CoreCollaborator::update
CoreCollaboratorContract::update ou create
FinanceCollaboratorBankAccount::update ou create (multiplas contas)
CoreCollabPendingChange::create (se colaborador tem space_id e houve diff)
BucketGoogleApiController::uploadToBucket (novos docs)
  ↓
DB::commit
  ↓
JSON {success, collaborator_id}
```

**Tela inicial:** Formulario de edicao (`pages/core/collaborators/edit`)
**Acao do usuario:** Altera dados e salva
**Requisicao:** `POST /core/collaborator/update/{id}/`
**Controller:** `CollaboratorController@update`
**Services:** FormatHelper, BucketGoogleApiController
**Tabelas alteradas:**
- `core_collaborators` (UPDATE)
- `core_collaborator_contracts` (UPDATE ou INSERT)
- `finance_collaborator_bank_accounts` (UPDATE ou INSERT, multiplas)
- `core_collab_pending_changes` (INSERT, se diff detectado e tem space_id)
**APIs chamadas:** Google Cloud Storage (upload novos documentos)
**Resultado esperado:** Dados atualizados, change tracking registrado
**Possiveis erros:**
- Colaborador nao encontrado → redirect com erro
- Falha upload → rollback
- Validacao falha → 422

---

## 2.4 Visualizar Detalhes do Colaborador

```
Usuario
  ↓
Lista → Botao Ver
  ↓
GET /core/collaborator/details/{id}/
  ↓
CollaboratorController@details_view
  ↓
CoreCollaborator + Contract + BankAccounts + Payments
BucketGoogleApiController::buildSignedUrl (URLs documentos)
APIs: Monday (nome), Slack (nome)
  ↓
View: pages/core/collaborators/view
```

**Tela inicial:** Detalhes do Colaborador (`pages/core/collaborators/view`)
**Acao do usuario:** Clica em "Ver" na lista
**Requisicao:** `GET /core/collaborator/details/{id}/`
**Controller:** `CollaboratorController@details_view`
**Services:** FormatHelper, BucketGoogleApiController
**Tabelas consultadas:** `core_collaborators`, `core_collaborator_contracts`, `finance_collaborator_bank_accounts`, `finance_collaborator_payments`
**APIs chamadas:** Google Cloud Storage (URLs assinadas), Monday.com, Slack
**Resultado esperado:** Pagina com perfil completo do colaborador
**Possiveis erros:**
- Colaborador nao encontrado → redirect com erro
- APIs offline → dados parciais exibidos (graceful)

---

## 2.5 Ativar/Desativar Colaborador

```
Usuario
  ↓
Detalhes Colaborador → Toggle Status
  ↓
POST /core/collaborator/toggle-status/{id}/
  ↓
CollaboratorController@toggle_status
  ↓
CoreCollaborator::update(status, exent_space_status, deleted_at)
  ↓
syncStatusToSpace → POST Exent Space API /nexos/user-status
  ↓
JSON {success, status, buttonText}
```

**Tela inicial:** Detalhes do Colaborador
**Acao do usuario:** Clica em toggle de status (ativo/inativo)
**Requisicao:** `POST /core/collaborator/toggle-status/{id}/`
**Controller:** `CollaboratorController@toggle_status`
**Services:** IntegrationCredentialService, GuzzleService
**Tabelas alteradas:** `core_collaborators` (status, exent_space_status, deleted_at)
**APIs chamadas:** Exent Space API (`/nexos/user-status`)
**Resultado esperado:** Status invertido, Exent Space sincronizado
**Possiveis erros:**
- Colaborador nao encontrado → 404
- Exent Space offline → erro retornado (duplicate entry, connection refused, timeout)
- Token Space ausente → sync silenciosamente ignorado

---

## 2.6 Desativar Conta Bancaria

```
Usuario
  ↓
Edicao Colaborador → Botao Desativar Conta
  ↓
POST /core/collaborator/deactivate-account
  ↓
CollaboratorController@deactivateAccount
  ↓
FinanceCollaboratorBankAccount::update(is_active = 0)
  ↓
JSON {success}
```

**Tela inicial:** Edicao de Colaborador
**Acao do usuario:** Clica em desativar conta bancaria
**Requisicao:** `POST /core/collaborator/deactivate-account` com `{account_id}`
**Controller:** `CollaboratorController@deactivateAccount`
**Services:** Nenhum
**Tabelas alteradas:** `finance_collaborator_bank_accounts` (is_active = 0)
**APIs chamadas:** Nenhuma
**Resultado esperado:** Conta bancaria desativada
**Possiveis erros:**
- Conta nao encontrada → 404
- Conta principal (main_account) → 400 (nao pode desativar)

---

## 2.7 Aprovar Alteracao Pendente (Exent Space)

```
Usuario
  ↓
Detalhes Colaborador → Aba Alteracoes → Botao Aprovar
  ↓
POST /core/collaborator/changes/approve/{id}
  ↓
CollaboratorController@changes_approve
  ↓
DB::beginTransaction
  ↓
CoreCollabPendingChange → status = 'approved'
CoreCollaborator::update (aplica new_info)
FinanceCollaboratorBankAccount::update ou create (se dados bancarios)
BucketGoogleApiController::deleteFile (doc antigo)
BucketGoogleApiController::renameFile (staging → final)
syncProfileToSpace → POST Exent Space /nexos/profile-sync (action: accepted)
CoreMailService::sendCoreTemplate('collab_change_approved')
  ↓
DB::commit
  ↓
JSON {success}
```

**Tela inicial:** Detalhes do Colaborador (modal alteracoes)
**Acao do usuario:** Visualiza diff e clica "Aprovar"
**Requisicao:** `POST /core/collaborator/changes/approve/{id}`
**Controller:** `CollaboratorController@changes_approve`
**Services:** BucketGoogleApiController, CoreMailService, IntegrationCredentialService, GuzzleService
**Tabelas alteradas:**
- `core_collab_pending_changes` (status → approved)
- `core_collaborators` (UPDATE com novos dados)
- `finance_collaborator_bank_accounts` (UPDATE ou INSERT)
**APIs chamadas:**
- Google Cloud Storage (delete old, rename new)
- Exent Space API (sync aprovacao)
- SMTP (email de aprovacao)
**Resultado esperado:** Alteracao aplicada ao colaborador, email enviado, Space sincronizado
**Possiveis erros:**
- Change ja processada → erro
- Falha no GCS → rollback
- Email falha → best-effort (nao bloqueia)

---

## 2.8 Rejeitar Alteracao Pendente

```
Usuario
  ↓
Detalhes Colaborador → Aba Alteracoes → Botao Rejeitar
  ↓
POST /core/collaborator/changes/reject/{id}
  ↓
CollaboratorController@changes_reject
  ↓
Validacao: reason (required, max 255)
  ↓
DB::beginTransaction
  ↓
CoreCollabPendingChange → status = 'rejected', rejected_reason
BucketGoogleApiController::deleteFile (docs em staging)
CoreMailService::sendCoreTemplate('collab_change_rejected')
syncProfileToSpace → POST Exent Space /nexos/profile-sync (action: rejected)
  ↓
DB::commit
  ↓
JSON {success}
```

**Tela inicial:** Detalhes do Colaborador (modal alteracoes)
**Acao do usuario:** Preenche motivo e clica "Rejeitar"
**Requisicao:** `POST /core/collaborator/changes/reject/{id}`
**Controller:** `CollaboratorController@changes_reject`
**Services:** BucketGoogleApiController, CoreMailService, IntegrationCredentialService, GuzzleService
**Tabelas alteradas:** `core_collab_pending_changes` (status → rejected, reason)
**APIs chamadas:** Google Cloud Storage (delete staging), Exent Space, SMTP
**Resultado esperado:** Alteracao rejeitada, email enviado, Space notificado
**Possiveis erros:**
- Motivo ausente → 422
- Change ja processada → erro
- Email falha → abort com rollback