feat(compras): jornada física de devolução de itens rejeitados

[devmnsoft]

Motivation

• Entregar a jornada operativa de devolução física para itens rejeitados (rascunho → expedição → entrega/cancelamento) preservando o tratamento administrativo já existente.
• Corrigir problemas de concorrência e idempotência no fluxo de divergências do recebimento para evitar deadlocks e resultados inconsistentes.
• Fornecer APIs e telas funcionais para preparar, expedir, acompanhar e confirmar devoluções sem introduzir efeitos financeiros ou alteração do estoque disponível.

Description

• Adiciona migration 20260924210000_compras_devolucao_fisica.sql que cria as tabelas compras_empresarial_devolucao, compras_empresarial_devolucao_item, compras_empresarial_devolucao_evento e compras_empresarial_devolucao_idempotencia, índices, constraints de estado/datas/quantidade e seeds de permissões, e atualiza o manifest.json e scripts consolidados.
• Implementa DevolucaoCompraRepository e registra IDevolucaoCompraRepository/IDevolucaoCompraApplicationService em DependencyInjection, com lógica transacional para reserva de saldo rejeitado, validação de saldo elegível, bloqueio estável de agregado e itens, e controle idempotente (request_hash v2).
• Introduz DevolucaoCompraApplicationService e contratos (ComprasContracts.cs) e expõe endpoints API/Web para central, criação/edição de rascunho, detalhe, expedição, confirmação de entrega, cancelamento e exportação CSV, além de views Razor para index, nova e detalhe.
• Corrige DivergenciaRecebimentoRepository para usar ordem de locks consistente, aplicar pg_advisory_xact_lock na chave idempotente, oferecer HashV2 (mantendo compatibilidade com hashes legados) e enriquecer eventos com campos (resultado, justificativa, responsável anterior/novo).
• Garante que expedição não baixa estoque disponível, que entrega só é permitida após expedição, que cancelamento de rascunho libera reserva e que todas as operações são idempotentes e versionadas (versão otimista).
• Atualiza script_completo* e manifest.json com a migration e regera artefatos consolidados usados pelo pipeline de migrations.

Testing

• PASS — python3 -m json.tool database/postgres/migrations/manifest.json validated the manifest JSON.
• PASS — bash scripts/check-migration-catalog.sh ran static validation and checksum/catalog checks (semantic execution on PostgreSQL reported as BLOCKED by gate).
• PASS — bash scripts/validate-compras-schema-contracts.sh validated SQL contracts relevant to compras.
• PASS — git diff --check showed no whitespace/patch errors and commit succeeded (feat(compras): implementar devolução física de rejeitados).
• BLOCKED — dotnet build sigov.runtime.slnf --no-restore could not be executed because the .NET SDK is not available in the environment.
• BLOCKED — full migration apply, transactional concurrency tests and end-to-end UI verification requiring psql + PostgreSQL 16 and the .NET runtime are omitted for lack of runtime infrastructure.

---

Codex Task

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
🔒 Security Review	✅ Completed 2026-09-24T23:09:07.964574Z	894a178	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.