Melhorias Aplicação Ti- Govtech

## Visão Geral Atual
- **Backend Laravel 10** com Sanctum, Jobs/Queues e foco em api rest; cliente principal é um front separado que consome `routes/api.php`, controladores em `app/Http/Controllers`. 
```13:58:routes/api.php
Route::middleware('auth:sanctum')->group(function () {
    Route::post('approve-bidding', [ApproveBiddingController::class, 'approveBidding']);
    Route::prefix('customers')->group(function () {
        Route::post('save', [CustomerController::class, 'save']);
        // ...
```
- **Domínios implementados**: autenticação (login/logout, reset via código), cadastro/gestão de clientes, criação/importação de licitações, aprovação pelo cliente, geração de relatórios e auditoria automática de mudanças.
- **Integrações externas**: api vps para buscar licitações, n8n para disparo de e-mails, dropbox para armazenamento de documentos processados após download/extração.
- **Infraestrutura**: Docker + Supervisor (4 workers), comandos artisan para inicializar/renovar tokens do Dropbox, documentação operacional em `DEPLOY_UPDATES.md` e `DROPBOX_FEATURE_SETUP.md`. Filas configuradas para processar downloads e uploads assíncronos.

## Fluxos Principais
- **Autenticação & Usuários**: login concentra-se em `AuthController`/`AuthService`; tokens Sanctum, revogação, reset com código temporário; `Usercontroller` expõe crud com perfis `collaborator`/`customer`.
- **Clientes**: `CustomerController` oferece CRUD com filtros, inativação, logs detalhados via `AuditLog` e `GenericObserver`; campos com casts e helpers em `CustomerModel`.
- **Licitações**: criação manual, importação em massa pela `BiddingSearchService`, deduplicação por cliente, geração automática de registros para múltiplos clientes, campos de status de aprovação.
- **Aprovação**: endpoints alteram `chrStatusAprove`, registram aprovador e data; há referência faltante ao modelo `ApproveBiddingModel` que precisa ser criado ou removido.
- **Processamento documental**: `Processdocumentjob` baixa links enviados via `/api/licitacao/processar`, extrai zip/rar/7z, filtra extensões aceitas, envia ao dropbox e atualiza metadados da licitação; tokens são criptografados em `dropboxtoken`.
- **Relatórios**: `biddingReport` monta dataset para front a partir de filtros (datas, clientes).

## Pontos Técnicos Relevantes
- Banco recente (migrations 2025) com tabelas `biddings`, `customers`, `documents_processing_links`, `documents_dropbox_tokens`; filas usam conexão database por padrão.
- Configurações sensíveis no `.env` (`DROPBOX_*`, `QUEUE_CONNECTION`, `SANCTUM`, `N8N webhook`); documentação orienta a iniciar tokens via `php artisan dropbox:init`.
- Testes ainda padrão do Laravel, sem cobertura funcional; pipeline ci/cd não presente no repositório local (mencionado em docs).
- Falta o arquivo `App\Models\ApproveBidding\ApproveBiddingModel`; é preciso criá-lo ou ajustar o serviço antes de acionar as rotinas de aprovação.

## Melhorias Desejadas (briefing para novo DEV)

**Gestão pós-aprovação estilo Asana**
- Transformar licitações aprovadas em “projetos” com etapas, subtarefas, comentários, anexos, deadlines e responsáveis.
- Estruturar endpoints e modelos para tarefas, seções e relacionamentos (similar ao schema do Asana), com histórico e notificações.
- Permitir atualização de status/percentual, anexos adicionais e checklists operacionais.

**Módulo Analytics & Painéis**
- Construir camada de indicadores: metas por período, vitórias, valores faturados, conversão por cliente/segmento, SLA de aprovação.
- Expor endpoint(s) para dashboards agregando dados por cliente, equipe, status; prever filtros dinâmicos para front gerar gráficos.
- Criar estrutura de armazenagem (ou views materializadas) para cálculos pesados e histórico.

**Integrações & Automação (N8N / Asana / Webhooks)**
- Abrir APIs internas para eventos (licitação criada, aprovação, mudanças de tarefa) com webhooks gerenciáveis; N8N será orquestrador.
- Implementar conectores REST para Asana (sincronizar projetos/tarefas) e padronizar payloads; permitir gatilhos bidirecionais.
- Documentar endpoints, autenticação e mapeamento de campos para facilitar automações futuras.

**Suporte Multiempresa (SaaS)**
- Introduzir tenant separation: chave `tenant_id` em todas as entidades relevantes, com políticas de acesso e middleware para isolar dados.
- Criar gestão de empresas: provisionamento, limites, convites de usuários, billing futuro; ajustar autenticação para contexto multi-tenant.
- Garantir que integrações (Dropbox, Asana, e-mail) possam ser configuradas por empresa (ex.: Tokens por tenant).

**Arquitetura & Boas Práticas**
- Mapear e criar `ApproveBiddingModel` ou refatorar o serviço de aprovação.
- Cobertura de testes para fluxos críticos (auth, geração de licitações, job de processamento).
- Revisar logs e observabilidade para suportar múltiplas empresas (correlação com tenant/projeto).
- Planejar migrações de schema para suportar novos módulos (tarefas, analytics) e escalabilidade (filas, caches).

## Próximos Passos Recomendados
- Validar setup local: `composer install`, `.env`, `php artisan migrate --seed`, configurar Dropbox/N8N sandbox.
- Criar backlog técnico: 1) multi-tenant base, 2) regularizar aprovação (`ApproveBiddingModel`), 3) módulo de gestão de tarefas, 4) analytics, 5) integrações/N8N.
- Definir contratos de API para novos módulos e alinhá-los com o time de frontend/automação.
- Revisar infraestrutura para suportar aumento de carga: filas (Redis), monitoramento, deploy automatizado.
- Estabelecer estratégia de testes e documentação (OpenAPI/Collection) para facilitar onboarding e futuras entregas.