Skip to content

Fase 3: persistência em PostgreSQL (spec 004) - #3

Merged
net0well merged 4 commits into
mainfrom
fase-3/persistencia
Oct 20, 2026
Merged

net0well merged 4 commits into
mainfrom
fase-3/persistencia

Conversation

@net0well

Copy link
Copy Markdown
Collaborator

Resumo

Novo pacote PythonScriptRunner.EntityFrameworkCore: catálogo versionado e histórico de execuções em PostgreSQL 16+ (schema psr). Inclui também o reprocesso (AC-10) e o teste de rascunho de trilha (AC-14) da spec 003.

  • Schema: migration inicial explícita (MigratePythonScriptRunnerAsync ou script idempotente). O histórico é particionado por semana, o conteúdo de arquivos por dia e a auditoria por mês.
  • Catálogo: rascunhos com concorrência otimista (xmin). A publicação valida o contrato, verifica a sintaxe com o Python declarado e trava as dependências com uv pip compile --generate-hashes. Também cobre arquivamento, exclusão, retenção por trilha, teste de rascunho e importação/exportação em zip.
  • Histórico: toda execução síncrona é gravada, com passos, tentativas, cauda de stdout/stderr e arquivos. Os arquivos ficam em bytea, lidos e gravados em streaming.
  • Idempotência e outbox: a mesma chave devolve a mesma execução por 24 h; o outbox é escrito na mesma transação (o relay chega na Fase 4).
  • Auditoria: só ações humanas são auditadas.
  • IRunManager: consulta, listagem keyset, logs, cancelamento e reprocesso síncrono. O passo que deu certo reaproveita as saídas e o que falhou ganha a tentativa #N com cause = Reprocess.
  • Manutenção: com advisory lock, cria partições à frente, aplica retenções encurtadas, marca Failed (Expired) e remove partições antigas. O health check AddPythonScriptRunnerDatabase() acusa schema pendente e partições faltando.
  • Core:
    • o runner virou o motor público IRunEngine (decisão D-102);
    • o IRunRecorder passa a receber todas as transições;
    • o CatalogManifests ficou público.

Critérios de aceite

Spec AC Teste
004 AC-1 migração, partições, repetição e script idempotente SchemaTests
004 AC-2 sem migração: banco intocado, health "schema pending" SchemaTests
004 AC-3 a AC-9 publicação, sintaxe, dependência, imutável, conflito, arquivar, excluir CatalogAdminTests
004 AC-10 a AC-13, AC-17, AC-18 histórico, 50 MB em streaming, idempotência, keyset, rollback, auditoria RunHistoryTests
004 AC-14, AC-15, AC-19, AC-20 partições, retenção da trilha, expiração, instância única MaintenanceTests
004 AC-16 retenção maior que a global CatalogAdminTests
004 AC-21 PostgreSQL real (postgres:16-alpine via Testcontainers) todos
003 AC-10 reprocesso RunHistoryTests
003 AC-14 teste de rascunho de trilha RunHistoryTests

O CRUD de agendamentos ficou para a Fase 4 (D-101); a tabela schedules já existe.

Verificação local (Windows + Docker Desktop)

Fase Resultado
Build PASS: 0 erros, 0 avisos
Diagnósticos / antipadrões (Roslyn) PASS: 0 / 0
Testes PASS: 124/124 (98 do Core + 26 de persistência), duas rodadas seguidas
Segurança (dotnet list package --vulnerable) PASS: nenhum pacote vulnerável
Formatação PASS

Notas de implementação

  • CI: os testes de PostgreSQL rodam só no job Ubuntu, porque os runners Windows do GitHub não executam containers Linux. No Windows rodam os testes do Core.
  • xmin: as tabelas runs e step_runs não usam xmin, porque o PostgreSQL não devolve colunas de sistema de tabelas particionadas. Por isso as transições de status são UPDATE condicionais.
  • Partições: o timestamp do RunId (UUID v7) é o created_at da execução, então as consultas por id vão direto à partição.
  • Códigos de erro novos: STAGE_INVALID e IMPORT_INVALID.
  • APIs públicas para as próximas fases: IIdempotencyStore, IOutboxWriter e PsrDbContext são públicos, para a fila e o worker gravarem na mesma transação.
  • Correção no Core: o cache de lock do uv tinha uma corrida no Windows. Quando dois processos gravam o mesmo lock ao mesmo tempo, quem perde a corrida agora reaproveita o arquivo do vencedor.

🤖 Generated with Claude Code

net0well and others added 4 commits October 19, 2026 19:29
- Abstractions: ICatalogAdmin, IRunManager, IArtifactStore, IAuditWriter/IAuditReader,
  Actor, erros de domínio com códigos estáveis e IDs UUID v7 tipados.
- IRunRecorder recebe todas as transições (execução, passo, tentativa, arquivos) e
  reserva a chave de idempotência; RunResult.Deduplicated.
- IRunEngine: roda definições (rascunhos), retoma execuções que falharam e cancela
  execuções em andamento no processo.
- CatalogManifests público para importar e exportar o formato de pasta;
  IStageValidator; verificação de sintaxe e hash de ambiente no IEnvironmentManager.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- PsrDbContext no schema psr com migration inicial: histórico particionado por
  semana, conteúdo de arquivos por dia e auditoria por mês.
- Catálogo no banco: rascunhos com concorrência otimista, publicação com
  verificação de sintaxe e lock do uv, arquivamento, exclusão, teste de rascunho e
  importação/exportação em zip.
- Histórico de toda execução síncrona, arquivos em bytea com streaming,
  idempotência de 24 h, outbox transacional e auditoria de ações humanas.
- IRunManager: consulta, listagem keyset, cancelamento e reprocesso síncrono.
- Manutenção com advisory lock (partições, retenção, limpezas) e health check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… (spec 004, spec 003)

Um teste por critério de aceite da spec 004 (AC-1 a AC-20) e da spec 003
(AC-10 reprocesso, AC-14 teste de rascunho).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Os runners Windows do GitHub não executam containers Linux; no Windows rodam os
testes do Core.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@net0well
net0well merged commit be4beb5 into main Oct 20, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant