feat: complete equipment handover workflow

docs/ARCHITECTURE.md

@@ -33,7 +33,7 @@ Nginx ──► Laravel + Inertia/React
 - `app/Domain/Inventory`: cache local de ativos e consultas do catálogo.
 - `app/Domain/Reservations`: disponibilidade, estados, regras e requisições.
 - `app/Domain/Approvals`: decisões, histórico e concorrência de aprovação.
-- `app/Domain/Handovers`: entrega, devolução e incidentes (a criar).
+- `app/Domain/Operations`: entrega, devolução, faltas, atrasos e incidentes.
 - `app/Domain/Audit`: logs imutáveis pela interface.
 - `app/Integrations/SnipeIt`: cliente HTTP, DTOs, mapper e exceções da API Snipe-IT.
 
@@ -65,9 +65,13 @@ Notificações implementam `ShouldQueue`, usam `afterCommit` e seguem dois canai
 5. Antes de aprovação ou entrega, o ativo é validado novamente.
 6. Checkout/check-in usam um token operacional separado e guardam apenas a resposta necessária para auditoria.
 
+`HandoverService` mantém a ordem explícita “Snipe-IT primeiro, confirmação local depois” para cada equipamento. Uma requisição com vários itens não é apresentada como concluída se apenas parte dos movimentos for aceite: os itens confirmados preservam o seu `HandoverRecord`, os restantes mantêm o estado anterior e a requisição passa a `incident`. As escritas externas não têm retry automático porque um timeout pode ocorrer depois de o Snipe-IT executar a operação; repetir sem reconciliação poderia criar um resultado enganador.
+
+O checkout associa o ativo a um utilizador Snipe-IT. O operador confirma o ID remoto na primeira entrega e o portal guarda-o em `users.snipe_user_id` para utilizações futuras. O check-in repõe o estado e a localização habitual sincronizados do ativo. As respostas externas ficam em `handover_records.snipe_response`; tokens nunca são persistidos.
+
 Uma falha intermédia pode deixar upserts válidos das páginas anteriores, mas nunca executa a desativação global. A sincronização seguinte converge o cache. Um lock distribuído e um job único impedem duas sincronizações simultâneas.
 
-Referências oficiais usadas para o contrato: [autenticação da API](https://snipe-it.readme.io/reference/authenticating-with-the-api), [listagem de hardware](https://snipe-it.readme.io/reference/hardware-list) e [limites/paginação](https://snipe-it.readme.io/reference/api-throttling).
+Referências oficiais usadas para o contrato: [autenticação da API](https://snipe-it.readme.io/reference/authenticating-with-the-api), [listagem de hardware](https://snipe-it.readme.io/reference/hardware-list), [limites/paginação](https://snipe-it.readme.io/reference/api-throttling), [checkout de hardware](https://snipe-it.readme.io/reference/hardware-checkout), [check-in de hardware](https://snipe-it.readme.io/reference/hardware-checkin) e [formato de erros da API](https://snipe-it.readme.io/reference/api-overview).
 
 ## Segurança
 

docs/DECISIONS.md

@@ -9,7 +9,7 @@ Usar Laravel 13 com React/TypeScript através de Inertia no mesmo projeto. Mant
 
 ## ADR-002 — PostgreSQL como garantia de conflitos
 
-**Data:** 2026-08-04  
+**Data:** 2026-08-04
 **Estado:** aceite
 
 Usar PostgreSQL e períodos semiabertos `[início, fim)`. A lógica aplicacional melhora a mensagem ao utilizador; uma restrição de exclusão GiST garante que concorrência ou um erro aplicacional não cria sobreposição bloqueante.
@@ -69,3 +69,12 @@ A autorização HTTP e a verificação no serviço exigem perfil de aprovador ou
 **Estado:** aceite
 
 Notificações funcionais são colocadas na fila apenas depois da confirmação da transação e enviadas por email e caixa interna. A submissão e uma resposta a esclarecimentos notificam aprovadores ativos; decisões e substituições notificam o requisitante. Uma substituição não altera automaticamente a decisão: exige justificação, equipamento livre da mesma categoria, bloqueio de ambas as linhas, novo item `held` e preservação do item original como `cancelled` para auditoria.
+
+## ADR-011 — Escritas Snipe-IT sem retry e reconciliação explícita
+
+**Data:** 2026-08-04
+**Estado:** aceite
+
+Checkout e check-in usam um token operacional distinto do token de leitura e nunca escrevem diretamente na base de dados do Snipe-IT. Cada equipamento é movimentado remotamente antes de o respetivo `reservation_item` e `handover_record` serem confirmados localmente. Escritas não têm retry automático: uma falha de ligação ou HTTP 5xx pode ser posterior à execução remota e a repetição cega não é segura. Numa operação com vários itens, sucessos confirmados são preservados e uma falha posterior coloca a requisição em `incident`, com IDs concluídos, item falhado e erro em auditoria. O operador reconcilia o ativo no Snipe-IT e repete apenas o movimento ainda pendente.
+
+O checkout é dirigido a `checkout_to_type=user`; o ID remoto confirmado pelo operador é guardado em `users.snipe_user_id`. O check-in usa o estado e a localização habitual provenientes da última sincronização. Esta opção segue os contratos oficiais de [checkout](https://snipe-it.readme.io/reference/hardware-checkout), [check-in](https://snipe-it.readme.io/reference/hardware-checkin) e o comportamento documentado de [erros em HTTP 200](https://snipe-it.readme.io/reference/api-overview).

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;

docs/RUNBOOK.md

@@ -30,6 +30,8 @@ curl -I -H 'Origin: http://localhost:8000' http://localhost:5173/@vite/client
 curl -I -H 'Origin: http://localhost:8000' http://localhost:5173/resources/js/app.tsx
 ```
 
+Para executar a validação backend use `docker compose exec app composer test`, não `php artisan test` diretamente. O script isola as variáveis de teste das variáveis `local` injetadas pelo Docker Compose e evita que jobs únicos deixem locks no Redis de desenvolvimento.
+
 Ambos devem responder com estado 200 e `Access-Control-Allow-Origin: http://localhost:8000`. Reiniciar o serviço com `docker compose restart node` se o ficheiro `public/hot` estiver desatualizado.
 
 Confirmar também que o HTML inicial já contém conteúdo SSR:
@@ -57,13 +59,14 @@ Definir no ambiente, sem colocar tokens no repositório:
 ```dotenv
 SNIPE_IT_URL=https://inventario.exemplo.pt
 SNIPE_IT_READ_TOKEN=
+SNIPE_IT_OPERATIONAL_TOKEN=
 SNIPE_IT_TIMEOUT=10
 SNIPE_IT_PAGE_SIZE=100
 SNIPE_IT_RETRIES=3
 SNIPE_IT_RETRY_DELAY_MS=250
 ```
 
-O token deve pertencer a uma conta técnica com acesso apenas de leitura aos ativos. A aplicação acrescenta `/api/v1` automaticamente quando a URL não o contém.
+O token de leitura deve pertencer a uma conta técnica com acesso apenas de leitura aos ativos. O token operacional deve ser separado e ter apenas as permissões necessárias para checkout/check-in. A aplicação acrescenta `/api/v1` automaticamente quando a URL não o contém.
 
 Operações:
 
@@ -80,6 +83,28 @@ docker compose exec app php artisan schedule:list
 
 Administradores podem testar a ligação, iniciar uma execução e consultar as últimas dez sincronizações em `http://localhost:8000/administracao/snipe-it`. Uma execução falhada mantém o último catálogo válido e não desativa registos ausentes. Consultar `sync_runs`, os logs do worker e o painel antes de repetir.
 
+## Entregas, devoluções e reconciliação
+
+Utilizadores com perfil `inventory_operator` ou `administrator` acedem a `http://localhost:8000/operacoes`. A fila inclui as reservas do dia e todos os processos entregues, atrasados, devolvidos ou com incidente ainda pendente. O campo inicial aceita referência, nome, email, etiqueta, ID Snipe-IT ou a saída de um leitor QR/código de barras configurado como teclado.
+
+Procedimento de entrega:
+
+1. preparar a requisição;
+2. confirmar fisicamente todos os equipamentos e o estado à saída;
+3. confirmar o ID do destinatário no Snipe-IT;
+4. registar a entrega e verificar a mensagem de sucesso;
+5. se existir erro, não voltar a submeter antes de consultar o estado do ativo no Snipe-IT.
+
+Procedimento de devolução:
+
+1. localizar a requisição ou ler a etiqueta;
+2. verificar equipamento, acessórios, danos e localização;
+3. registar a devolução;
+4. criar um incidente e bloqueio temporal quando o ativo não deva voltar ao catálogo;
+5. concluir o processo apenas depois de todos os itens estarem devolvidos.
+
+Uma operação parcial fica em `incident`. Consultar `handover_records` para movimentos confirmados e os eventos `reservation.delivery_failed`/`reservation.return_failed` em `audit_logs`. Comparar cada item com o estado atual no Snipe-IT; corrigir apenas os itens ainda `ready` ou `delivered`. Não alterar estados diretamente na base de dados nem repetir em bloco, porque as escritas externas são deliberadamente não idempotentes e não têm retry automático.
+
 ## Ciclo de vida das pré-reservas
 
 As requisições pendentes têm, por defeito, um prazo de decisão de 48 horas. O scheduler coloca a expiração na fila a cada cinco minutos. Para operar ou diagnosticar manualmente: