release: promove develop pra produção (Automation Contract v1/v1.1/v1.2, object storage Garage, guardrails arquiteturais, separação EEG no frontend) #79

Merged

jhony75 merged 23 commits from develop into main 2026-09-22 09:33:48 -03:00

Conversation 0 Commits 23 Files changed 81 +2633 -293

jhony75 commented 2026-09-22 09:27:05 -03:00

Owner

Copy link

O que é

Promove pra produção tudo que já está validado em develop -- 9 PRs de features/fix/docs acumuladas desde a última promoção (PR #69).

Principais mudanças

• Automation Contract v1 (#70): POST /api/automation/runs -- ingestão normalizada de resultado de teste externo, outcome fechado, idempotência real via índice único no banco, Automation Discovery (UNMAPPED/MAPPED/IGNORED), M2M via Authentik.
• Automation Contract v1.1 (#73): test_environment no run, metrics livre por resultado, categoria TIMEOUT em failure_classification.
• Automation Contract v1.2 (#75): steps opcional -- múltiplas ações por caso de teste, cada uma com seu próprio outcome. Outcome CONDITIONAL_PASS ("aprovado com ressalvas"), compartilhado com execução manual.
• Guardrails arquiteturais P0 (#73): test_architecture.py trava automation/orchestration nunca importarem um do outro nem modules/eeg_reports, e fecha um vazamento real (Report.eeg_profile acessado fora do extension point em 4 arquivos Core).
• Object storage — Garage (#76): anexos novos (Attachment/RunAttachment) podem ir pro Garage (S3-compatível, self-hosted) em vez de BLOB no banco, quando as env vars GARAGE_* estão configuradas. Sem elas, comportamento idêntico a hoje. Histórico de anexos existentes não é migrado (decisão deliberada).
• Separação Core/EEG no frontend + requisitos vinculados (#77): ReportForm/ReportDetail/ReportList não embutem mais o vocabulário EEG diretamente (extraído pra EegProfileFields.tsx); Library.tsx mostra requisitos vinculados a cada cenário.
• fix: Storybook travava num spinner infinito por causa do X-Frame-Options global (#74).
• fix: patch de segurança do SO na imagem do backend, CVEs CRITICAL em perl-base (#72).
• docs: correção de referências desatualizadas a Basic Auth (#71); decisão sobre import de JUnit XML -- fica com adapter externo, não com o Cockpit (#78).

Migrations

5 migrations novas rodam no deploy (automáticas, via alembic upgrade head no boot): Automation Contract v1 (outcome restrito + idempotência + runner secret + badge automação), métricas em test_run_steps, automation_outcome em test_run_scenarios, storage_key em images/run_images. Todas aditivas (colunas nullable ou índice novo) -- nenhuma quebra dado existente, testadas com upgrade→downgrade→upgrade + alembic check sem drift.

Pendências conhecidas (não bloqueiam esta PR)

• GARAGE_* no .env de produção: sem essas 5 variáveis, anexos novos continuam BLOB automaticamente (sem erro) -- confirme que já foram adicionadas se quiser que produção use o Garage desde já.
• Migração do histórico de anexos (BLOB→Garage) e limpeza de objeto órfão no delete: deliberadamente fora de escopo, ver docs/KNOWN_LIMITATIONS.md.
• RBAC/autorização granular via grupos do Authentik: desbloqueado (infra pronta), ainda não implementado.

Verificação

• git merge-tree entre main e develop: sem conflitos (main não tem nenhum commit fora de develop desde a última promoção).
• Backend: 274/274 testes, migrations testadas com round-trip completo.
• Frontend: tsc/lint/163 testes/build limpos.
• docs.sh build --strict: limpo.
• Verificado manualmente em dev (deploy automático de develop já validou boa parte disso ao vivo).

🤖 Generated with Claude Code

## O que é Promove pra produção tudo que já está validado em `develop` -- 9 PRs de features/fix/docs acumuladas desde a última promoção (PR #69). ## Principais mudanças - **Automation Contract v1** (#70): `POST /api/automation/runs` -- ingestão normalizada de resultado de teste externo, outcome fechado, idempotência real via índice único no banco, Automation Discovery (UNMAPPED/MAPPED/IGNORED), M2M via Authentik. - **Automation Contract v1.1** (#73): `test_environment` no run, `metrics` livre por resultado, categoria `TIMEOUT` em `failure_classification`. - **Automation Contract v1.2** (#75): `steps` opcional -- múltiplas ações por caso de teste, cada uma com seu próprio outcome. Outcome `CONDITIONAL_PASS` ("aprovado com ressalvas"), compartilhado com execução manual. - **Guardrails arquiteturais P0** (#73): `test_architecture.py` trava `automation`/`orchestration` nunca importarem um do outro nem `modules/eeg_reports`, e fecha um vazamento real (`Report.eeg_profile` acessado fora do extension point em 4 arquivos Core). - **Object storage — Garage** (#76): anexos novos (`Attachment`/`RunAttachment`) podem ir pro Garage (S3-compatível, self-hosted) em vez de BLOB no banco, quando as env vars `GARAGE_*` estão configuradas. Sem elas, comportamento idêntico a hoje. Histórico de anexos existentes **não é migrado** (decisão deliberada). - **Separação Core/EEG no frontend + requisitos vinculados** (#77): `ReportForm`/`ReportDetail`/`ReportList` não embutem mais o vocabulário EEG diretamente (extraído pra `EegProfileFields.tsx`); `Library.tsx` mostra requisitos vinculados a cada cenário. - **fix:** Storybook travava num spinner infinito por causa do `X-Frame-Options` global (#74). - **fix:** patch de segurança do SO na imagem do backend, CVEs `CRITICAL` em `perl-base` (#72). - **docs:** correção de referências desatualizadas a Basic Auth (#71); decisão sobre import de JUnit XML -- fica com adapter externo, não com o Cockpit (#78). ## Migrations 5 migrations novas rodam no deploy (automáticas, via `alembic upgrade head` no boot): Automation Contract v1 (outcome restrito + idempotência + runner secret + badge automação), métricas em `test_run_steps`, `automation_outcome` em `test_run_scenarios`, `storage_key` em `images`/`run_images`. Todas aditivas (colunas nullable ou índice novo) -- nenhuma quebra dado existente, testadas com upgrade→downgrade→upgrade + `alembic check` sem drift. ## Pendências conhecidas (não bloqueiam esta PR) - **`GARAGE_*` no `.env` de produção**: sem essas 5 variáveis, anexos novos continuam BLOB automaticamente (sem erro) -- confirme que já foram adicionadas se quiser que produção use o Garage desde já. - Migração do histórico de anexos (BLOB→Garage) e limpeza de objeto órfão no delete: deliberadamente fora de escopo, ver `docs/KNOWN_LIMITATIONS.md`. - RBAC/autorização granular via grupos do Authentik: desbloqueado (infra pronta), ainda não implementado. ## Verificação - `git merge-tree` entre `main` e `develop`: sem conflitos (main não tem nenhum commit fora de develop desde a última promoção). - Backend: 274/274 testes, migrations testadas com round-trip completo. - Frontend: `tsc`/lint/163 testes/build limpos. - `docs.sh build --strict`: limpo. - Verificado manualmente em dev (deploy automático de `develop` já validou boa parte disso ao vivo). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jhony75 added 23 commits 2026-09-22 09:27:05 -03:00

feat: Automation Contract v1 -- outcome restrito, idempotencia real, M2M ... 086ed36850

Formaliza o contrato de automacao do QA Cockpit (ingestao, Automation
Discovery, Runner Contract) com as mudancas confirmadas com o usuario:

- outcome de ingestao restrito aos 5 valores terminais (PASS/FAIL/ERROR/
  BLOCKED/SKIPPED), rejeitando PENDING/RUNNING com 422
- external_run_id passa a ser obrigatorio (era opcional) -- e a chave de
  idempotencia junto com source
- idempotencia agora garantida por indice unico parcial em test_runs
  (nao so checagem em app), com tratamento de IntegrityError pra corrida
  entre requisicoes concorrentes
- Runner.secret opcional (M2M Cockpit -> Runner via Authorization: Bearer),
  nunca exposto pela API (RunnerOut so expoe has_secret)
- M2M automacao -> Cockpit nao precisou de mudanca de codigo -- a service
  account qa-cockpit-automation do Authentik ja chega pelos mesmos headers
  que services/identity.py le desde o item 14
- badge de automacao (is_automated) em AuditLogEntry, Report.reviewer/
  approved_by e TestRun.executed_by, calculado a partir do grupo
  qa-cockpit-automations

Documentacao nova: docs/AUTOMATION_CONTRACT.md (referencia externa com
exemplos HTTP completos) + ADR-0015, com nota de esclarecimento no ADR-0012
(proposta diferente, nao implementada) e atualizacoes em API.md/
ARCHITECTURE.md/BACKLOG.md/KNOWN_LIMITATIONS.md refletindo que o forward-auth
via Authentik ja esta ativo em prod e dev (PRs #67/#68/#69).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Merge pull request 'feat: Automation Contract v1 -- outcome restrito, idempotência real, M2M' (#70) from feature/automation-contract-v1 into develop ... b9f0450d37

Reviewed-on: #70

docs: corrige referencias desatualizadas a Basic Auth e ADRs faltando na nav ... 23eafab630

Auditoria pos-merge da PR #70 encontrou documentacao que ainda descrevia
Basic Auth como o mecanismo ativo pro frontend/API (substituido por
forward-auth via Authentik desde as PRs #67/#68/#69) -- corrigido em
AI_HANDOFF.md, API_PLAYGROUND.md, BRUNO.md, DEPLOYMENT.md e
DOCKER_ENVIRONMENTS.md, deixando claro que o servico de docs continua
com Basic Auth (nao mudou).

Tambem corrigido: ADR-0014/ADR-0015 nao apareciam nem no indice
(docs/adr/README.md) nem na navegacao publicada (mkdocs.yml), e
AUTOMATION_CONTRACT.md nao estava em lugar nenhum da nav -- ficariam
invisiveis no site publicado. ADR-0014 ganhou uma nota de atualizacao
esclarecendo que a infra ja foi plugada (o texto original descrevia o
estado de antes).

Build estrito do mkdocs (--strict) validado localmente, sem erros.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Merge pull request 'docs: corrige referências desatualizadas a Basic Auth e ADRs faltando na nav' (#71) from docs/automation-contract-followup into develop ... cfba1c3561

Reviewed-on: #71

fix: aplica patches de seguranca do SO na imagem do backend ... 3c4c6c2c9e

O ultimo push em develop (merge da PR #71) falhou no scan de vulnerabilidades
(Trivy) do job "Build e publicacao de imagens" -- 3 CVEs CRITICAL recem-
publicadas em perl-base (2026-13221, 2026-42496, 2026-8376), todas ja com
correcao no repositorio do Debian. Nao tem relacao com o conteudo da PR (so
docs) -- e a imagem base python:3.12-slim que fica congelada no patch-level
de quando essa camada foi baixada pela ultima vez, sem nunca rodar apt-get
upgrade.

Fix padrao: roda apt-get update && apt-get upgrade -y logo apos o FROM, antes
de qualquer outra camada. Frontend/docs nao precisam do mesmo fix -- os dois
tem estagio final em nginx:alpine (nao Debian), so o backend publica uma
imagem final Debian-based.

Nao foi possivel validar a build localmente (Docker Desktop nao esta
rodando neste ambiente) -- a propria CI (build + scan Trivy) e quem confirma.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

feat: guardrails arquiteturais P0 + Automation Contract v1.1 (test_environment, metrics, TIMEOUT) ... 10910f0874

Fecha os dois P0 da auditoria observacional (docs/audits/AUTOMATION_ORCHESTRATION_AUDIT.md,
secao 12): test_architecture.py agora trava automation/orchestration nunca
importarem um do outro nem modules/eeg_reports, e o vazamento real do
relacionamento Report.eeg_profile fora do extension point (services/reports.py,
modules/reporting e modules/reports, schemas.py) foi corrigido via
eeg_extension.extra_joinedload()/to_schema().

Evolucao aditiva do Automation Contract (v1.1, nenhum payload v1 quebra):
test_environment no run, metrics livre (JSON) por resultado, e categoria
TIMEOUT em failure_classification. Migration 9e05b21add43.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Merge pull request 'fix: aplica patches de segurança do SO na imagem do backend' (#72) from fix/backend-image-security-patches into develop ... 286e8765a9

Reviewed-on: #72

fix: remove link quebrado pro audit doc não commitado em docs/BACKLOG.md ... ca1236c9c8

O link markdown apontava pra docs/audits/AUTOMATION_ORCHESTRATION_AUDIT.md,
que é intencionalmente não commitado (auditoria observacional, o usuário
decide se/quando publicar) -- quebrava o build do site de docs em modo
--strict (mkdocs aborta em qualquer link morto).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Merge remote-tracking branch 'origin/develop' into feature/architecture-guardrails-contract-v1-1 038bcd0bf7

fix: Storybook trava num spinner infinito por causa do X-Frame-Options global ... de143db3ee

O Storybook carrega a própria pré-visualização (iframe.html) num <iframe> na
mesma origem -- é assim que o "manager" dele sempre funcionou. O
X-Frame-Options: DENY do bloco server (linha 9, protege o app contra
clickjacking) era herdado por location /storybook/ e bloqueava esse
auto-frame (confirmado: GET /storybook/iframe.html retornava 200 mas o
navegador recusava renderizar, ERR_BLOCKED_BY_RESPONSE + "Refused to display
... because it set X-Frame-Options to deny" no console).

location /storybook/ ganhou seus próprios add_header, com SAMEORIGIN em vez
de DENY -- permite esse self-frame e continua bloqueando framing por
terceiros. Repete os outros 3 headers de segurança porque add_header do
nginx não herda do bloco pai quando a location redeclara qualquer um.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Merge pull request 'feat: guardrails arquiteturais P0 + Automation Contract v1.1 (test_environment, metrics, TIMEOUT)' (#73) from feature/architecture-guardrails-contract-v1-1 into develop ... d5c122505e

Reviewed-on: #73

Merge pull request 'fix: Storybook trava num spinner infinito por causa do X-Frame-Options global' (#74) from fix/storybook-frame-options into develop ... 101751a71a

Reviewed-on: #74

feat: Automation Contract v1.2 -- multiplos passos por resultado e outcome CONDITIONAL_PASS ... dda74c67ca

Motivado por uma necessidade real (validacao de manufatura, em desenho
agora): AutomationResultIn ganha um campo opcional `steps`, permitindo
reportar varias acoes por caso de teste (cada uma com seu proprio
outcome/duration_ms/failure_classification/message/evidence/metrics) em vez
do unico passo sintetico do v1/v1.1. Sem `steps`, comportamento identico ao
que ja existia.

Novo outcome CONDITIONAL_PASS ("aprovado com ressalvas") -- vocabulario
compartilhado entre automacao e execucao manual (schemas.StepOutcome),
decisao explicita do usuario. O outcome de um result nunca e recalculado a
partir do "pior status vence" dos steps -- quem chama a API decide o
veredito final. Isso exigiu TestRunScenario.automation_outcome (migration
1e03ec5658f9) pra _dedup_response nao divergir do outcome_counts da
ingestao original quando um result tem varios passos.

Verificado manualmente na UI (dev server local): ingestao multi-step +
CONDITIONAL_PASS, edicao manual de um passo pra CONDITIONAL_PASS, e
persistencia apos reload -- tudo funcionando ponta a ponta.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

feat: object storage (Garage) para anexos novos, sem migrar historico ... 7c544d10a2

Attachment/Image e RunAttachment ganham storage_key (nullable) -- anexos
novos podem ser gravados no Garage (S3-compativel, self-hosted, disponivel
na VPS) em vez de BLOB no banco. services/object_storage.py isola o client
boto3 (mesmo padrao de ai_client.py/hubspot_client.py); sem as 5 env vars
GARAGE_* configuradas, decode_and_store continua gravando BLOB
automaticamente -- comportamento de dev/teste inalterado. Nenhum ponto de
LEITURA mudou (attachment.data continua igual em todo lugar), so a escrita
decide onde os bytes ficam.

Duas decisoes de produto confirmadas com o usuario antes de implementar:
(1) sem migracao automatica do historico -- anexos existentes continuam
BLOB pra sempre; (2) bucket compartilhado entre dev e prod (decisao de
infra temporaria), isolado via prefixo de key por ENVIRONMENT
(development/attachments/<uuid> vs production/...). Ver ADR-0016.

Migration 995241f5ea8d (storage_key nullable + images.data vira nullable).
Testado com um smoke test unico contra o Garage real (upload, download,
delete de limpeza) -- credenciais nunca commitadas, so env vars inline no
shell durante o teste.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

feat: termina separacao Core/EEG no frontend + requisitos vinculados na Biblioteca ... 19e6caba82

Vazamento EEG residual no frontend (equivalente do que ja foi fechado no
backend): ReportForm/ReportDetail/ReportList embutiam direto patient code
e canais Photic/Cardio/Video. Extraido pra EegProfileFields.tsx (campos
editaveis, modo leitura, resumo textual, normalizacao) -- os 3 componentes
genericos so repassam o objeto `eeg` adiante agora, sem interpretar nome de
campo nenhum. Mesmo espirito do eeg_extension do backend, sem precisar de
injecao de dependencia formal (unico consumidor por enquanto).

Requisitos vinculados agora aparecem tambem em Library.tsx (chips
clicaveis, navegam pra /requisitos/:id) -- estava deliberadamente adiado.
ScenarioTemplateOut ganhou requirements: List[ScenarioRequirementRef], de
graca via o backref que ja existia (Requirement.scenario_templates) --
nenhuma migration, nenhuma mudanca no vinculo em si, so exposicao. Gestao
do vinculo continua só via RequirementDetail.

Verificado manualmente na UI (dev server local): criar/editar report com
canais EEG, listagem mostrando canais, cenario vinculado a requisito
aparecendo na Biblioteca e navegacao ate RequirementDetail -- tudo
funcionando ponta a ponta.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs: resolve item de import JUnit XML -- responsabilidade fica com adapter externo ... ae11aca009

Decisao explicita do usuario: manter o principio ja documentado em
docs/ARCHITECTURE.md (Cockpit nunca le JUnit/pytest/Playwright diretamente).
As perguntas de produto originais deste item ja foram resolvidas de
qualquer forma pelo Automation Contract, que nao existia quando o item foi
escrito -- nada a fazer neste repositorio, a traducao fica por conta de um
adapter externo (ex. neurosync-qe-uploader).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Merge pull request 'feat: Automation Contract v1.2 -- múltiplos passos por resultado e outcome CONDITIONAL_PASS' (#75) from feature/automation-contract-v1.2-multistep into develop ... a4b90c7fc9

Reviewed-on: #75

Merge remote-tracking branch 'origin/develop' into feature/eeg-frontend-separation-linked-requirements ... df2fb82448

# Conflicts:
#	docs/BACKLOG.md

Merge remote-tracking branch 'origin/develop' into feature/object-storage-garage ... 3c9fe27463

# Conflicts:
#	.forgejo/workflows/ci.yml
#	backend/modules/automation/router.py
#	backend/tests/test_api_smoke.py
#	docs/BACKLOG.md

Merge pull request 'feat: object storage (Garage) para anexos novos, sem migrar histórico' (#76) from feature/object-storage-garage into develop ... e1990f36f5

Reviewed-on: #76

Merge remote-tracking branch 'origin/develop' into feature/eeg-frontend-separation-linked-requirements ... f00ede3721

# Conflicts:
#	docs/BACKLOG.md

Merge pull request 'feat: termina separação Core/EEG no frontend + requisitos vinculados na Biblioteca' (#77) from feature/eeg-frontend-separation-linked-requirements into develop ... 28a7fe4dcf

Reviewed-on: #77

Merge pull request 'docs: resolve item de import JUnit XML -- responsabilidade fica com adapter externo' (#78) from docs/junit-xml-import-decision into develop ... 4028de1995

Reviewed-on: #78

jhony75 merged commit db077e1b14 into main 2026-09-22 09:33:48 -03:00

jhony75 referenced this pull request from a commit 2026-09-22 09:33:49 -03:00

Merge pull request 'release: promove develop pra produção (Automation Contract v1/v1.1/v1.2, object storage Garage, guardrails arquiteturais, separação EEG no frontend)' (#79) from develop into main

jhony75 referenced this pull request 2026-10-14 16:11:25 -03:00

release: promove develop pra produção (metrics na run v1.3, Runner Contract 429/422/dedup, imagens em itens de Validação Técnica, envio ao HubSpot) #83

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

jhony75/eeg-qa!79

No description provided.