@@ -5,7 +5,7 @@ com contrato de entrada/saída, trilhas (**Pipelines**), execução assíncrona
55cron e painel Vue opcional.
66
77> Projeto em desenvolvimento. Esta versão entrega o ** Core Runner** (execução síncrona de Stages e de
8- > trilhas) e o SDK Python ** ` psrunner ` ** .
8+ > trilhas), o SDK Python ** ` psrunner ` ** e a ** persistência em PostgreSQL ** (catálogo versionado e histórico) .
99
1010## Como funciona
1111
@@ -89,17 +89,50 @@ double[] termos = result.GetStepOutput<double[]>("termos", "termos"); // depur
8989A mesma trilha pode ser definida em C# com ` AddPipeline("chave", p => p.Input(...).Step(...).Output(...)) ` .
9090Se um passo falhar, os seguintes ficam como ` Skipped ` e a execução termina ` Failed ` .
9191
92+ ## Persistência (PostgreSQL)
93+
94+ Com o pacote ` PythonScriptRunner.EntityFrameworkCore ` , Stages e trilhas passam a viver no banco (schema ` psr ` ) com
95+ versões imutáveis (rascunho → publicado → arquivado), e ** toda** execução fica registrada: passos, tentativas, cauda
96+ de stdout/stderr e arquivos (em ` bytea ` , lidos e gravados em streaming).
97+
98+ ``` csharp
99+ builder .Services
100+ .AddPythonScriptRunner ()
101+ .AddEntityFrameworkCore (o =>
102+ {
103+ o .UseNpgsql (builder .Configuration .GetConnectionString (" psr" )! ); // PostgreSQL 16+
104+ o .Retention .Artifacts = TimeSpan .FromDays (7 ); // arquivos
105+ o .Retention .Runs = TimeSpan .FromDays (90 ); // histórico
106+ });
107+ builder .Services .AddHealthChecks ().AddPythonScriptRunnerDatabase ();
108+
109+ var app = builder .Build ();
110+ await app .Services .MigratePythonScriptRunnerAsync (); // explícito; ou GeneratePythonScriptRunnerMigrationScriptAsync()
111+ ```
112+
113+ - ** Catálogo:** ` ICatalogAdmin ` cria rascunhos (concorrência otimista), publica (verifica a sintaxe com o Python
114+ declarado e trava as dependências com ` uv pip compile --generate-hashes ` ), arquiva, exclui, testa rascunhos e
115+ importa/exporta zip no formato de pasta.
116+ - ** Execuções:** ` IRunManager ` consulta (paginação keyset), cancela e reprocessa uma execução que falhou — os passos
117+ que deram certo reaproveitam as saídas e o que falhou ganha uma nova tentativa. ` RunOptions.IdempotencyKey ` devolve
118+ a mesma execução por 24 h.
119+ - ** Retenção:** o histórico é particionado (semana para execuções, dia para conteúdo de arquivos, mês para auditoria);
120+ um job de manutenção cria partições à frente e remove as antigas. Uma trilha pode encurtar a retenção.
121+ - ** Auditoria:** ações humanas (` Actor.User(...) ` ) ficam em ` psr.audit_events ` ; disparos automáticos ficam na própria execução.
122+
92123## Requisitos
93124
94125- .NET 10 SDK
95126- [ uv] ( https://docs.astral.sh/uv/ ) no PATH (cria e cacheia um ambiente Python por conjunto de dependências)
127+ - PostgreSQL 16+ apenas para o pacote de persistência (os testes usam Docker/Testcontainers)
96128
97129## Estrutura
98130
99131| Pasta | Conteúdo |
100132| -------| ----------|
101133| ` src/PythonScriptRunner.Abstractions ` | contratos públicos (tipos de campo, ` StageDefinition ` , ` RunResult ` , ` PsrFile ` , interfaces) |
102134| ` src/PythonScriptRunner.Core ` | catálogos (código e pasta), validação, ambientes uv, executor de processos, runner |
135+ | ` src/PythonScriptRunner.EntityFrameworkCore ` | PostgreSQL: catálogo versionado, histórico, arquivos, idempotência, outbox, auditoria, retenção |
103136| ` python/psrunner ` | SDK Python (` @stage ` , ` Context ` , ` File ` , ` StageError ` , ` psrunner.testing ` , CLI) |
104137| ` schemas ` | JSON Schemas do ` stage.json ` e do ` *.pipeline.json ` |
105138| ` tests ` | testes .NET (unitários e de integração com Python real) e fixtures de trilha |
@@ -109,6 +142,7 @@ Se um passo falhar, os seguintes ficam como `Skipped` e a execução termina `Fa
109142``` bash
110143dotnet build
111144dotnet test --project tests/PythonScriptRunner.Core.Tests
145+ dotnet test --project tests/PythonScriptRunner.EntityFrameworkCore.Tests # precisa de Docker
112146
113147cd python/psrunner
114148uv sync
0 commit comments