feat: complete equipment handover workflow

docs/PROJECT_STATUS.md

@@ -1,7 +1,7 @@
 # Estado do projeto e handoff
 
 **Atualizado em:** 4 de agosto de 2026  
-**Fase:** Fases 1, 2, 3 e 4 concluídas
+**Fase:** Fases 1 a 5 concluídas; próxima entrega: Fase 6
 **Último agente:** Codex
 
 ## Resultado disponível
@@ -34,44 +34,51 @@
 - Resposta auditada do requisitante a esclarecimentos, com regresso a `pending_approval` e novo prazo de 48 horas.
 - Substituição de equipamento apenas por ativo livre da mesma categoria, mantendo a pré-reserva e todo o histórico.
 - Fila de aprovação com filtros por referência, requisitante, categoria e período, incluindo histórico de ações.
+- Cliente Snipe-IT operacional com token separado, checkout para utilizador, check-in para a localização habitual e validação de erros transportados em HTTP 200.
+- Área diária do operador protegida pelo perfil `inventory_operator`/`administrator`, com leitura por scanner-teclado ou pesquisa de referência, requisitante, etiqueta e ID Snipe-IT.
+- Preparação, entrega, devolução e conclusão com máquina de estados, condição física, observações, operador, destinatário e resposta externa em `handover_records`.
+- Associação persistente entre o utilizador do portal e o respetivo ID no Snipe-IT, confirmada durante uma entrega bem-sucedida.
+- Tratamento explícito de falhas parciais: movimentos já aceites são preservados, a requisição passa a `incident` e a falha fica em `audit_logs` para reconciliação.
+- Registo de falta, atraso e incidente; um incidente pode criar um bloqueio temporal do equipamento que entra imediatamente no motor de disponibilidade.
 
 ## Limites conhecidos
 
 - A integração está implementada e testada contra respostas simuladas; falta configurar e validar URL, versão e token da instância institucional. Até lá, o catálogo utiliza dados fictícios do seeder.
 - Microsoft Entra ID ainda não está implementado; as variáveis de ambiente já estão definidas.
-- Entrega e devolução têm tabelas preparadas, mas ainda não possuem ações ou interface.
 - As notificações estão implementadas com Mailpit em desenvolvimento; falta validar SMTP institucional antes do piloto.
-- As políticas de autorização finas ainda não foram ligadas às rotas; nesta fase todas as rotas funcionais exigem utilizador autenticado, verificado e ativo.
 - O calendário atual é a vista mensal pessoal do MVP; vistas diária, semanal, global e por equipamento/categoria/localização ficam para as áreas operacional e administrativa.
+- O leitor operacional aceita scanners QR/código de barras que funcionem como teclado. A leitura direta pela câmara do navegador ainda não foi adicionada.
+- Uma falha depois de o Snipe-IT confirmar um movimento e antes do commit local é uma transação distribuída ambígua; não existe retry automático de escritas. O operador deve reconciliar pelos registos Snipe-IT e `audit_logs` conforme o runbook.
 
 ## Próxima tarefa recomendada
 
-Implementar a **Fase 5 — entrega e devolução**:
+Implementar a **Fase 6 — administração e relatórios**:
 
-1. abrir `app/Integrations/SnipeIt/SnipeItClient.php` e acrescentar checkout/check-in com o token operacional separado;
-2. criar `app/Domain/Handovers/Services/HandoverService.php` com entrega e devolução transacionais;
-3. criar área do operador para reservas do dia, pesquisa por referência/utilizador e confirmação do estado físico;
-4. tratar falhas parciais da API Snipe-IT sem declarar entrega/devolução concluída;
-5. implementar incidentes, atrasos e bloqueios associados a dano;
-6. testar API simulada, autorização, idempotência e auditoria;
-7. atualizar este documento e o changelog.
+1. criar a área administrativa de utilizadores, perfis e associação ao ID Snipe-IT;
+2. tornar configuráveis as políticas de antecedência, duração, margens, estados e categorias;
+3. criar calendário global e relatórios de utilização, atrasos, incidentes e ativos mais requisitados;
+4. adicionar exportação CSV/XLSX e filtros por período, categoria, departamento e estado;
+5. criar consulta de auditoria apenas de leitura para o perfil `auditor`;
+6. adicionar métricas operacionais e gestão de modelos de email;
+7. cobrir autorização, exportações e agregações com testes e atualizar toda a documentação.
 
 ## Testes da última sessão
 
 Validação concluída em 4 de agosto de 2026:
 
 - `docker compose exec -T app composer test`: passou;
-- Laravel Pint: 111 ficheiros sem desvios;
-- PHPStan/Larastan nível 7: 84 ficheiros, zero erros;
-- Pest: 70 testes passaram, 340 asserções e 2 testes de registo ignorados por a funcionalidade estar deliberadamente desativada;
+- Laravel Pint: 117 ficheiros sem desvios;
+- PHPStan/Larastan nível 7: 89 ficheiros, zero erros;
+- Pest: 79 testes passaram, 412 asserções e 2 testes de registo ignorados por a funcionalidade estar deliberadamente desativada;
 - TypeScript (`tsc --noEmit`): passou;
 - ESLint: passou;
 - Prettier: passou;
-- Vite: builds cliente e SSR concluídos, 2308 módulos cliente e 97 módulos SSR transformados;
+- Vite: builds cliente e SSR concluídos, 2309 módulos cliente e 98 módulos SSR transformados;
 - PostgreSQL 17: `migrate:fresh --seed` concluído, incluindo extensão `btree_gist` e restrição de exclusão temporal;
 - PostgreSQL 17: migration incremental do marcador `last_seen_sync_run_id` aplicada com sucesso;
 - PostgreSQL 17: nenhuma migration pendente; comando de expiração executado e agendamentos horário/a cada cinco minutos confirmados;
 - PostgreSQL 17: migration `notifications` aplicada com sucesso;
+- PostgreSQL 17: migration `snipe_user_id` aplicada e fluxo operacional exercitado contra API simulada;
 - smoke test HTTP: `/login` respondeu com estado 200 através do Nginx;
 - Vite em Docker: URL pública, HMR e CORS verificados em `localhost:5173`; corrigida a página em branco causada pela publicação anterior de `0.0.0.0:5173`;
 - Inertia SSR: renderização do login validada através do serviço `node`; corrigido o componente de mensagens flash que usava `usePage()` fora do contexto Inertia;