fix(generate-docs): schema contra Postgres descartável e PR chore(docs) [INFRA-69572] #122

Merged

tarcisio merged 1 commit from fix/INFRA-69572-generate-docs into develop

2026-10-13 18:54:19 -03:00

tmf-ia commented

2026-10-13 15:43:02 -03:00

Owner

INFRA-69572: generate-docs com schema de Postgres descartável e PR `chore(docs)`

Decisão do operador em HCOR-67289 (13/10/2026): a ORG conserta o reusável.

O que já estava na develop (TH-68786), conferido e coberto por teste novo

Detecção de mudança com arquivo novo (git add -A -- docs/ + git diff --cached).
Entrega por PR do bot para develop (branch fixa chore/auto-gen-docs-<base>, atualiza o PR aberto em vez de abrir outro, sem push na base).

O que este PR muda

Schema só de banco descartável. Chave nova docs_schema_snapshot (padrão false) no ci-config.yml. Com ela, o job sobe Postgres 16 + pgvector pelo servicos-efemeros.sh: mesma imagem do postgres_service do ci.yml (tmf/base-images/tmf-postgres-base:16-20261009-2e51884) e mesmas postgres_*. Depois roda docs_schema_migrate_cmd (padrão alembic upgrade head) em backend_path e gera o snapshot desse banco. O scripts/docs-schema-descartavel.sh recusa qualquer host que não seja o contêiner tmf-ci-svc-pg-* do run.
POSTGRES_DOCS_URL passa a ser ignorado e gera ::warning::. O valor do segredo nunca entra no ambiente do passo.
ci_config.py docs: subcomando novo que lê só as chaves do generate-docs. As postgres_* valem com postgres_service ou com docs_schema_snapshot. docs_schema_migrate_cmd sem o schema ligado reprova.
O PR e o commit do bot saem como chore(docs): [auto-gen docs] ....
O teto do job sobe de 15 para 25 min, para caber o pull do Postgres e a migração.
Atualizados o CHANGELOG (Não lançado), o guia de adoção (seção "Docs geradas", com o requisito do token), o docs/scripts.md e o ci-config.exemplo.yml.

Provas

tests/generate-docs: 29 testes, com controles do comportamento antigo e ponta a ponta. O schema-snapshot.md que nunca existiu vira PR chore(docs) para develop, com develop e main intactas. Controle negativo: com a guarda de host removida, 5 testes falham.
tests/ci-config: chaves novas, regras cruzadas e o CLI docs.
Suíte inteira (tests/*/) verde na imagem tmf-ci-python:3.12-20261009-2e51884.
Prova real local: tmf-postgres-base descartável, create extension vector + tabela fictícia, dump_db_schema.py do HelpCor pelo docs-schema-descartavel.sh. Resultado: docs/arquitetura/schema-snapshot.md gerado com a tabela.

Não provado aqui

O servicos-efemeros.sh up dentro do job do generate-docs no runner. É o mesmo script e a mesma imagem do job backend do ci.yml, mas só a primeira rodada num produto prova.

Adoção nos produtos (fora deste PR)

HelpCor, Hub, TMF9, Fina e Priceshow passam POSTGRES_DOCS_URL. Para voltar a ter schema, cada um declara docs_schema_snapshot: true (e, se preciso, docs_schema_migrate_cmd) no ci-config.yml e remove o segredo.

🤖 Generated with Claude Code

https://claude.ai/code/session_017QrAM1chSgVpSwDrKJVLVn

## INFRA-69572: generate-docs com schema de Postgres descartável e PR `chore(docs)` Decisão do operador em HCOR-67289 (13/10/2026): a ORG conserta o reusável. ### O que já estava na develop (TH-68786), conferido e coberto por teste novo - Detecção de mudança com arquivo novo (`git add -A -- docs/` + `git diff --cached`). - Entrega por PR do bot para `develop` (branch fixa `chore/auto-gen-docs-<base>`, atualiza o PR aberto em vez de abrir outro, sem push na base). ### O que este PR muda 1. **Schema só de banco descartável.** Chave nova `docs_schema_snapshot` (padrão `false`) no `ci-config.yml`. Com ela, o job sobe Postgres 16 + pgvector pelo `servicos-efemeros.sh`: mesma imagem do `postgres_service` do `ci.yml` (`tmf/base-images/tmf-postgres-base:16-20261009-2e51884`) e mesmas `postgres_*`. Depois roda `docs_schema_migrate_cmd` (padrão `alembic upgrade head`) em `backend_path` e gera o snapshot desse banco. O `scripts/docs-schema-descartavel.sh` recusa qualquer host que não seja o contêiner `tmf-ci-svc-pg-*` do run. 2. **`POSTGRES_DOCS_URL` passa a ser ignorado** e gera `::warning::`. O valor do segredo nunca entra no ambiente do passo. 3. **`ci_config.py docs`**: subcomando novo que lê só as chaves do generate-docs. As `postgres_*` valem com `postgres_service` **ou** com `docs_schema_snapshot`. `docs_schema_migrate_cmd` sem o schema ligado reprova. 4. O PR e o commit do bot saem como `chore(docs): [auto-gen docs] ...`. 5. O teto do job sobe de 15 para 25 min, para caber o pull do Postgres e a migração. 6. Atualizados o CHANGELOG (Não lançado), o guia de adoção (seção "Docs geradas", com o requisito do token), o `docs/scripts.md` e o `ci-config.exemplo.yml`. ### Provas - `tests/generate-docs`: 29 testes, com controles do comportamento antigo e ponta a ponta. O `schema-snapshot.md` que nunca existiu vira PR `chore(docs)` para `develop`, com `develop` e `main` intactas. Controle negativo: com a guarda de host removida, 5 testes falham. - `tests/ci-config`: chaves novas, regras cruzadas e o CLI `docs`. - Suíte inteira (`tests/*/`) verde na imagem `tmf-ci-python:3.12-20261009-2e51884`. - Prova real local: `tmf-postgres-base` descartável, `create extension vector` + tabela fictícia, `dump_db_schema.py` do HelpCor pelo `docs-schema-descartavel.sh`. Resultado: `docs/arquitetura/schema-snapshot.md` gerado com a tabela. ### Não provado aqui - O `servicos-efemeros.sh up` dentro do job do generate-docs no runner. É o mesmo script e a mesma imagem do job backend do `ci.yml`, mas só a primeira rodada num produto prova. ### Adoção nos produtos (fora deste PR) HelpCor, Hub, TMF9, Fina e Priceshow passam `POSTGRES_DOCS_URL`. Para voltar a ter schema, cada um declara `docs_schema_snapshot: true` (e, se preciso, `docs_schema_migrate_cmd`) no `ci-config.yml` e remove o segredo. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_017QrAM1chSgVpSwDrKJVLVn

tmf-ia added 1 commit

2026-10-13 15:43:02 -03:00

fix(generate-docs): schema contra Postgres descartável e PR chore(docs) [INFRA-69572]

PR checks (ci-shared) / testes (pull_request) Successful in 4m51s

Details

ca613a5c0d

- docs_schema_snapshot (padrão false) sobe Postgres 16 + pgvector no job pelo
  servicos-efemeros.sh (mesma imagem/postgres_* do job backend), roda
  docs_schema_migrate_cmd (padrão alembic upgrade head) e gera o snapshot dele;
- docs-schema-descartavel.sh recusa host que não seja o tmf-ci-svc-pg-* do run;
- POSTGRES_DOCS_URL ignorado com :⚠️:; ci_config.py docs;
- PR/commit do bot como chore(docs): [auto-gen docs] ...;
- teste ponta a ponta: arquivo novo em docs/ vira PR para develop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017QrAM1chSgVpSwDrKJVLVn

tmf-ia requested review from tarcisio

2026-10-13 15:43:03 -03:00