Corrige resolução de fuso e encerramento local do Worker

[devmnsoft]

Motivation

• Corrigir o fluxo onde o identificador de fuso retornado do banco podia ser nulo e provocava o diagnóstico de nulabilidade (CS8604) ao chamar CreateUtcRange diretamente com um string não anulável.
• Evitar bloqueio de DLLs durante desenvolvimento causado por instâncias do Worker que não encerravam corretamente, o que pode provocar erros como MSB3021/MSB3027 ao compilar novamente.
• Garantir que a cadeia de build dos testes receba o assembly de referência da API produzido pelo build correto, evitando o erro em cascata CS0006 nos projetos de teste.

Description

• Adiciona a política central TimeZonePolicy em src/Odca.Application/Tenancy/TimeZonePolicy.cs que resolve o fuso com precedência pelo valor da organização e fallback explícito da aplicação, distinguindo os casos Missing, Empty, Invalid e Unavailable.
• Atualiza ContractImportsController para resolver o TimeZoneInfo antes de criar o intervalo UTC, tratar exceções de configuração com respostas controladas ao cliente e alterar a assinatura de CreateUtcRange para receber TimeZoneInfo; arquivos principais modificados: src/Odca.Api/Controllers/ContractImportsController.cs e src/Odca.Api/appsettings.json.
• Melhora a conversão de DateOnly em instantes UTC ao rejeitar inícios inexistentes (IsInvalidTime), escolher explicitamente o primeiro instante em tempos ambíguos (IsAmbiguousTime) e validar intervalos invertidos e limites (ArgumentException para from > to).
• Refina o ciclo de vida do Worker definindo HostOptions.ShutdownTimeout (2 minutos) em src/Odca.Worker/Program.cs, tornando o helper Run do DocumentWorker cancelável e assegurando que processos-filho sejam encerrados e aguardados quando o host cancela, em src/Odca.Worker/DocumentWorker.cs.
• Adiciona scripts e suporte para desenvolvimento local: scripts/stop-local.ps1 para identificar e encerrar processos pertencentes ao checkout e ajuste em scripts/run-local.ps1 para iniciar projetos com caminhos absolutos; também atualiza README.md com procedimento Windows para diagnosticar bloqueios.
• Atualiza projetos e testes: torna DocumentWorker.Run internal e expõe o Worker a testes com InternalsVisibleTo, adiciona testes unitários/integrados novos para política de fuso, intervalos e cancelamento (tests/Odca.Domain.Tests/TimeZonePolicyTests.cs, tests/Odca.IntegrationTests/ContractImportDateRangeTests.cs, tests/Odca.IntegrationTests/DocumentWorkerCancellationTests.cs) e registra a referência ao projeto Worker em tests/Odca.IntegrationTests/Odca.IntegrationTests.csproj.

Testing

• Verificações estáticas executadas com sucesso: git diff --check passou e os JSON modificados foram validados com python3 carregando src/Odca.Api/appsettings.json e src/Odca.Worker/Properties/launchSettings.json sem erros.
• Varredura proibida por padrões (procurando workarounds como taskkill, dotnet.exe, HintPath etc.) passou sem encontrar soluções proibidas.
• Os novos testes foram adicionados ao repositório, porém a execução de dotnet restore, dotnet build e dotnet test não foi possível neste runner porque o binário dotnet não está instalado, portanto os testes não foram executados aqui.
• Comandos recomendados para validação local num ambiente com .NET instalado: dotnet restore Odca.sln --locked-mode, dotnet build Odca.sln --configuration Release --no-restore, dotnet test tests/Odca.Domain.Tests --no-build, dotnet test tests/Odca.IntegrationTests --no-build, e para diagnosticar/encerra processos Windows . ools un-local.ps1 / . ools un-local.ps1 -Force (conforme documentado no README.md).

---

Codex Task

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[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-16T22:53:46.791994Z	1cfd6f8	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.