T-303 - Alinhar a trilha dos dados de demonstração com a forma gravada pelo pipeline

• Componente: deploy (deploy/scripts/seed.py).
• Depende de: T-301, que cria a coluna resultado_id.
• Data máxima: 06/11/2026
• Estimativa: 2 pontos (Fibonacci)

Entregável

• Linhas de trilha dos cenários do seed com as etapas, as referências e os campos da conclusão que o pipeline grava.
• resultado_id gravado nas linhas de decisão e de sugestão.
• Linhas de interpretacao_resultado removidas da trilha do seed.
• Linha de explicacao na forma da etapa de explicação, nos cenários que gravam explicação.

Descrição

O seed grava linhas de trilha que o pipeline não produz. Elas incluem as etapas interpretacao_resultado e explicacao, fontes e elementos_implementados na geração e simulacao_id na delegação e na decisão. Uma consulta ou tela da trilha testada contra esses dados parece mais completa do que a trilha real. Esta tarefa alinha a trilha do seed com a forma que o pipeline grava depois da T-301 e da T-302.

Contexto e decisões tomadas

• As linhas vêm da lista trilhas de cada Cenario (viavel, inviavel, assercao_violada e os derivados por replace) e de TRILHA_REFERENCIAS, que diz quais ids cada etapa recebe. seed_cenario monta os ids com seed_id(cenario.chave, ...), inclusive o do resultado.
• Os cenários são de formulário e não passam por extração. Por isso nenhuma linha leva fontes.
• O nó de decisão grava encaminhamento com um dos valores sugestao_adaptacao, busca_meta, correcao_codigo ou fim (decision.py e correcao_codigo.py). Um resultado inviável leva a sugestao_adaptacao.
• A tabela explicacoes e o texto de explicação dos cenários pertencem à US05 e não mudam aqui. Só o cenário viável, e os que o copiam, gravam explicação.
• A etapa de explicação é criada pela T-317 e roda depois da decisão. A linha explicacao do seed segue a forma dela, com resultado_id e explicacao_id, para que as narrativas gravadas em explicacoes continuem ligadas à trilha. O campo desfecho_explicacao só entra no contrato com a T-316, depois desta tarefa, e não é gravado aqui.

Escopo

Dentro do escopo

• As listas trilhas dos cenários e TRILHA_REFERENCIAS em deploy/scripts/seed.py.

Fora do escopo

• A lista USUARIOS. O papel da conta [email protected] foi trocado à mão no Keycloak do staging, e rodar o seed com outra lista pode revertê-lo.
• A tabela explicacoes, as transições e as ações dos cenários.
• Novos cenários de busca da meta, de correção do código ou de derivação.

Requisitos

1. Em TRILHA_REFERENCIAS, a delegacao_worker passa a receber só regra_id. A decisao passa a receber regra_id e resultado_id, sem simulacao_id. A geracao_codigo mantém regra_id, prompt_id e codigo_gerado_id e passa a receber também simulacao_id, como a API grava. Remover a entrada de interpretacao_resultado. A explicacao passa a receber regra_id, resultado_id e explicacao_id, sem simulacao_id.
2. Na conclusão da geracao_codigo, remover fontes e elementos_implementados e acrescentar modo_geracao igual a gerado.
3. Na conclusão da confirmacao, remover fontes e usar a forma que TrilhaDaConfirmacao grava, com resumo, editado_pelo_usuario e campos_corrigidos.
4. Na conclusão da decisao, acrescentar o encaminhamento que o nó gravaria para o desfecho do cenário, conferido em decision.py, e um resumo equivalente ao do nó.
5. No cenário com sugestão, acrescentar a linha sugestao_adaptacao com resultado_id e motivo_sugestao igual a proposta. Incluir sugestao_adaptacao em TRILHA_REFERENCIAS com regra_id e resultado_id. O resultado_id resolve pela chave "resultado" de ids, pelo mesmo mecanismo das demais referências.
6. Remover as linhas interpretacao_resultado de todos os cenários. Manter a linha explicacao só nos cenários que gravam explicação, depois da decisão, com o resumo e sem desfecho_explicacao.
7. Toda conclusão gravada pelo seed deve validar contra contracts/domain/trilha-conclusao.schema.json.

Contexto técnico

• Entradas: cenários de seed.py.
• Saídas: linhas de trilhas_auditoria na forma gravada pelo pipeline.
• Componentes afetados: deploy/scripts/seed.py.
• Restrições: não alterar USUARIOS; não rodar contra o staging como parte desta tarefa.
• Referências: contracts/domain/trilha-conclusao.schema.json, codegen/app/graph/nodes/decision.py, api/src/main/java/synapse/api/job/TrilhaDaConfirmacao.java. O modo de uso do seed está no cabeçalho de seed.py.

Critérios de aceitação

• O seed roda sem erro num banco local recém-migrado com a T-301.
• Nenhuma linha gravada pelo seed tem no igual a interpretacao_resultado.
• Cada linha explicacao aponta a explicação e o resultado do próprio cenário, e nenhum cenário sem explicação tem essa linha.
• As linhas decisao e sugestao_adaptacao do seed apontam o resultado do próprio cenário.
• Toda conclusao gravada pelo seed valida contra o schema.

Definição de concluído (DoD)

• Seed executado num banco local limpo, com a consulta da trilha dos cenários conferida.
• Conclusões gravadas validadas contra o schema com jsonschema, usando as dependências de contracts/requirements.txt. O seed não tem teste automatizado.

Observações

• O seed insere com ON CONFLICT (id) DO NOTHING. Rodá-lo num banco já semeado não atualiza as linhas de trilha existentes nem remove as de interpretação e explicação. A forma nova só aparece num banco limpo, e um ambiente já semeado precisa de decisão própria antes de qualquer limpeza.
• O seed não grava busca da meta, correção do código nem derivação. A forma dessas linhas fica coberta pelos testes da T-302.