@acropole/skills 1.3.0 → 1.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -3
- package/package.json +3 -3
- package/skills/acropole/SKILL.md +1 -0
- package/skills/acropole/references/arquitetura.md +29 -5
- package/skills/acropole/references/fluxos/app-novo.md +4 -4
- package/skills/apollo/references/subscriptions.md +10 -4
- package/skills/apollo/references/testes-build.md +1 -0
- package/skills/docker/SKILL.md +3 -0
- package/skills/docker/references/podman-local.md +73 -0
- package/skills/express/references/dados.md +3 -1
- package/skills/fastapi/SKILL.md +4 -4
- package/skills/fastapi/references/banco.md +53 -50
- package/skills/fastapi/references/estrutura.md +2 -2
- package/skills/fastapi/references/integracoes.md +8 -0
- package/skills/hefesto/SKILL.md +49 -14
- package/skills/hefesto/references/diagnostico.md +15 -5
- package/skills/hefesto/references/fluxo.md +64 -35
- package/skills/hefesto/references/mcp-diagnostico.md +44 -0
- package/skills/hefesto/references/mcp-roteiros.md +53 -0
- package/skills/hefesto/references/mcp-tools.md +94 -0
- package/skills/orfeu/SKILL.md +1 -1
- package/skills/orfeu/references/diferencas.md +1 -1
- package/skills/orfeu/references/node.md +1 -1
- package/skills/orquestracao/SKILL.md +1 -1
- package/skills/orquestracao/templates/spec.md +1 -1
- package/skills/trismegisto/SKILL.md +2 -2
- package/skills/trismegisto/references/angular-api.md +7 -5
- package/skills/trismegisto/references/angular-exports.md +12 -1
- package/skills/trismegisto/references/angular.md +10 -0
- package/skills/trismegisto/references/catalogo/seletores.json +8 -0
- package/skills/trismegisto/references/spine-api.md +148 -9
- package/skills/trismegisto/references/spine-recipes.md +1 -1
- package/skills/trismegisto/references/spine.md +1 -1
package/README.md
CHANGED
|
@@ -21,7 +21,7 @@ Cada skill cobre uma parte da stack e elas se complementam (a `orquestracao` enc
|
|
|
21
21
|
| `express` | Servidores Node com Express: middlewares, rotas REST, erros, Knex, shutdown | "cria a rota REST de upload no servidor Node" |
|
|
22
22
|
| `fastapi` | Serviços Python com FastAPI: domínios, settings, SQLAlchemy, envelope, pytest | "adiciona o domínio de faturas no serviço Python" |
|
|
23
23
|
| `docker` | Dockerfile e `.dockerignore` (Angular estático, Node, Python): multi-stage, CMD exec, não-root, healthcheck | "escreve o Dockerfile desse serviço", "o container demora a parar" |
|
|
24
|
-
| `hefesto` | Deploy pela plataforma Hefesto: aplicação, ambientes, variáveis, deploy/redeploy, rollback, diagnóstico | "prepara esse app para subir no Hefesto", "o deploy falhou" |
|
|
24
|
+
| `hefesto` | Deploy pela plataforma Hefesto: aplicação, ambientes, variáveis, deploy/redeploy, rollback, diagnóstico, e o MCP de deploy (hefesto-mcp) para um agente de IA | "prepara esse app para subir no Hefesto", "o deploy falhou", "faz o redeploy do pedidos-api em homol pelo MCP" |
|
|
25
25
|
| `orquestracao` | Mudança grande do pedido à entrega (spec → plano em itens Txx → execução por vários agentes/sessões com reserva atômica via `coord.sh` → provas → Argos → fechamento) e como paralelizar com subagentes | "faz a spec e o plano", "paraleliza entre agentes", "distribui esses itens" |
|
|
26
26
|
| `auto-servico` | MCP do auto-serviço do Argos (argos-mcp): configurar um agente de IA (uma conexão por aplicação, `x-app-token`, escopos), roteiros das tools (tela, acesso, permissões) e diagnóstico | "configura o agente para usar o MCP do Argos", "publica a tela pelo MCP" |
|
|
27
27
|
| `documentacao` | Manual das telas Angular: `README.md`/`ESPECIFICACAO.md` ligados no `document` da rota, loader `.md`, revisão da doc a cada mudança da tela (registro de revisão em `.documentacao.json`) | "documenta a tela de pedidos", "a doc dessa tela ainda vale?" |
|
|
@@ -128,7 +128,7 @@ fonte do Trismegisto) copia para `skills/<skill>/scripts/nucleo.mjs`. Fixtures d
|
|
|
128
128
|
|
|
129
129
|
### Build e release
|
|
130
130
|
|
|
131
|
-
No disco, este repo fica em `astra/packages/acropole` (`github.com/
|
|
131
|
+
No disco, este repo fica em `astra/packages/acropole` (`github.com/konvndor/acropole`, branch `master`).
|
|
132
132
|
|
|
133
133
|
```bash
|
|
134
134
|
scripts/build-publish.sh build # npm test + npm pack -> tarballs/acropole-skills-<versão>.tgz (fora do git)
|
|
@@ -150,7 +150,7 @@ Trusted Publishing (OIDC, sem `NPM_TOKEN` no repositório), e ninguém cria tag
|
|
|
150
150
|
|
|
151
151
|
**Environment `release`.** O job de publicação usa o environment `release`, criado no GitHub **sem regras de
|
|
152
152
|
proteção** (repo privado em conta Free, sem *Required reviewers*). Ele existe porque é o nome cadastrado no
|
|
153
|
-
Trusted Publisher do npm (dono `
|
|
153
|
+
Trusted Publisher do npm (dono `konvndor`, repositório `acropole`, workflow `release.yml`, environment `release`):
|
|
154
154
|
o npm só aceita o token OIDC vindo dele. A aprovação é o clique em *Run workflow*.
|
|
155
155
|
|
|
156
156
|
**Primeira publicação (1.0.0).** O Trusted Publisher só pode ser usado depois que o pacote existe no npm, então a
|
package/package.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@acropole/skills",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "Skills e revisores para Claude Code: Angular, Apollo, Express, FastAPI, Trismegisto, Orfeu, Docker, deploy no Hefesto, documentação das telas e
|
|
3
|
+
"version": "1.4.0",
|
|
4
|
+
"description": "Skills e revisores para Claude Code: Angular, Apollo, Express, FastAPI, Trismegisto, Orfeu, Docker, deploy no Hefesto, documentação das telas e os MCPs do auto-serviço do Argos e de deploy do Hefesto. Instale com: npx @acropole/skills",
|
|
5
5
|
"bin": { "acropole-skills": "bin/install.js" },
|
|
6
6
|
"files": ["bin", "skills", "agents"],
|
|
7
7
|
"engines": { "node": ">=18" },
|
|
8
8
|
"license": "MIT",
|
|
9
|
-
"repository": { "type": "git", "url": "git+https://github.com/
|
|
9
|
+
"repository": { "type": "git", "url": "git+https://github.com/konvndor/acropole.git" },
|
|
10
10
|
"keywords": ["claude", "claude-code", "skill", "skills", "angular", "apollo", "graphql", "express", "fastapi", "trismegisto", "orfeu", "docker", "hefesto", "deploy", "documentacao", "documentation", "markdown", "agents", "code-review", "mcp", "argos"],
|
|
11
11
|
"scripts": {
|
|
12
12
|
"bump": "node scripts/bump.mjs",
|
package/skills/acropole/SKILL.md
CHANGED
|
@@ -60,6 +60,7 @@ acima e pergunte.
|
|
|
60
60
|
| Dockerfile, imagem, container, `.dockerignore` | docker (+ express/fastapi/angular para a parte de deploy da stack) |
|
|
61
61
|
| deploy, publicar o serviço, Hefesto, ambiente | hefesto → docker |
|
|
62
62
|
| agente de IA no Argos, MCP do auto-serviço, `.mcp.json`/`x-app-token` para um agente, "publica a tela/dá acesso pelo MCP" | auto-servico |
|
|
63
|
+
| agente de IA no Hefesto, MCP de deploy, "faz o deploy/redeploy pelo MCP", "por que o deploy falhou" com as tools do hefesto-mcp | hefesto |
|
|
63
64
|
| "revisa", "confere", antes de abrir PR | este fluxo `revisar` |
|
|
64
65
|
| versões desalinhadas, "não sobe", configuração estranha | este fluxo `doctor` |
|
|
65
66
|
|
|
@@ -11,7 +11,7 @@ decisões que valem para todas as camadas. Divergiu de um app para outro? Este a
|
|
|
11
11
|
├── angular/ front: Angular 22 + @trismegisto/* + @orfeu/angular
|
|
12
12
|
├── graphql/ gateway: Apollo Server sobre Express + @orfeu/node — só repassa para o server
|
|
13
13
|
├── server/ API e regra de negócio: FastAPI + orfeu[fastapi] + SQLAlchemy
|
|
14
|
-
├── database/
|
|
14
|
+
├── database/ migrations do Postgres com Alembic + seed de ambiente (estrutura idêntica entre os apps)
|
|
15
15
|
├── compose/ (opcional) docker-compose da stack num host
|
|
16
16
|
└── README.md componentes, portas, como rodar, padrões seguidos e pendências
|
|
17
17
|
```
|
|
@@ -41,13 +41,21 @@ navegador ──> angular (estático) ──GraphQL HTTP/WS──> graphql ─
|
|
|
41
41
|
|
|
42
42
|
## 3. Caminhos, proxy e portas
|
|
43
43
|
|
|
44
|
+
**Regra: toda aplicação vive dentro do próprio contexto.** Tudo do app `<app>` fica sob `/<app>` (o Hefesto sob
|
|
45
|
+
`/hefesto`, o Argos sob `/argos`), em todo ambiente, inclusive no compose local.
|
|
46
|
+
|
|
44
47
|
| Camada | Caminho público | Prefixo no código |
|
|
45
48
|
| --- | --- | --- |
|
|
46
49
|
| angular | `/<app>/` | `baseHref` das configurações de build |
|
|
47
50
|
| graphql | `/<app>/graphql` (HTTP **e** WebSocket) | `GRAPHQL_PATH` |
|
|
48
51
|
| server | `/<app>/server` | `api_prefix` (rotas, `/health` e documentação) |
|
|
52
|
+
| mcp | `/<app>/mcp` | `API_PREFIX` |
|
|
49
53
|
|
|
50
54
|
- O proxy encaminha o caminho **completo** (sem strip): cada serviço responde sob o próprio prefixo.
|
|
55
|
+
- O padrão do código (ex.: `api_prefix = "/api"`) **não é contexto**: é só um valor para rodar isolado. Compose,
|
|
56
|
+
`.env.<ambiente>` e deploy definem o prefixo do app (`API_PREFIX: /<app>/server`), e as URLs internas entre
|
|
57
|
+
serviços usam o mesmo caminho (`http://<app>-server:8010/<app>/server`). Nunca "conserte" uma URL quebrada
|
|
58
|
+
trocando o contexto por `/api`; antes de mudar um caminho, veja o padrão do repo (README, testes, config do MCP).
|
|
51
59
|
- Atrás do proxy, o front deriva callback, logoff, authority e URLs ainda `CHANGE_ME` da própria origem
|
|
52
60
|
(`applyRuntimeEnvironment`); URL explícita no environment sempre ganha.
|
|
53
61
|
- Cada app tem **uma porta fixa e única por camada** no desenvolvimento local, registrada no README da raiz,
|
|
@@ -63,7 +71,21 @@ chaves de outro (cache, dedup de eventos, `FLUSHDB` de teste):
|
|
|
63
71
|
- canais de pub/sub e chaves sempre com o prefixo do app (`<app>:…`) — pub/sub ignora o índice (`PUBLISH` vale
|
|
64
72
|
para o servidor inteiro), então o prefixo é o que isola as subscriptions;
|
|
65
73
|
- o índice de cada app por ambiente fica registrado no README da raiz do app; ao criar um app, escolha um índice
|
|
66
|
-
livre conferindo os outros apps do mesmo ambiente (`.env.<ambiente>`), não "o próximo número"
|
|
74
|
+
livre conferindo os outros apps do mesmo ambiente (`.env.<ambiente>`), não "o próximo número";
|
|
75
|
+
- **OBRIGATÓRIO: toda conexão ao Redis é nomeada** (`CLIENT SETNAME`). O `maxclients` vale para todos os apps
|
|
76
|
+
juntos, e sem nome o `CLIENT LIST` (campo `name=`) e o redis_exporter não dizem **qual app** abre quantas
|
|
77
|
+
conexões — achar quem estoura o teto vira adivinhação. É só o nome: não é ACL nem usuário por app.
|
|
78
|
+
- Convenção `<app>-<componente>[-<papel>]`, sem espaços (o Redis recusa o `SETNAME` e a conexão não abre):
|
|
79
|
+
`pedidos-server`, `pedidos-graphql-publisher`, `pedidos-graphql-subscriber`, `argos-auth`.
|
|
80
|
+
- Variável `REDIS_CLIENT_NAME` sobrescreve o nome (padrão no código = `<app>-<componente>`); quando há papel,
|
|
81
|
+
ele é sufixado: `${REDIS_CLIENT_NAME}-publisher`. Vazio = padrão; com espaço, a subida falha.
|
|
82
|
+
- **ioredis**: opção `connectionName` em cada `new Redis(...)` — vale também com Sentinel (é a conexão com o
|
|
83
|
+
master); no Cluster, em `redisOptions.connectionName`; conexão extra (`duplicate()`, subscriber) recebe o
|
|
84
|
+
nome do papel (`` client.duplicate({ connectionName: `${base}-subscriber` }) ``).
|
|
85
|
+
- **redis-py**: `client_name=` no `redis.ConnectionPool(...)` — vale para todas as conexões do pool (e para
|
|
86
|
+
o `pubsub()`, que tira a conexão do mesmo pool).
|
|
87
|
+
- Um teste prova o nome padrão e a sobrescrita por `REDIS_CLIENT_NAME`; a variável vai no `.env.example`.
|
|
88
|
+
- **Conexão ao Redis sem nome é defeito de revisão**, igual a um índice repetido.
|
|
67
89
|
|
|
68
90
|
## 4. Ambientes
|
|
69
91
|
|
|
@@ -74,7 +96,7 @@ Só **`local`**, **`dev`**, **`homol`** e **`prod`** — em toda camada, com o m
|
|
|
74
96
|
| angular | `--configuration <ambiente>` (build/serve) | `src/core/environments/environment.<ambiente>.ts` (versionados, sem segredo); `environment.ts` = `local` |
|
|
75
97
|
| graphql | `NODE_ENV` (`cross-env` nos scripts) | `src/settings/environment/.env.<ambiente>` (não versionados) + `.env.example` |
|
|
76
98
|
| server | `APP_ENV` (comando, `poe start:<ambiente>` ou `src/.env`) | `src/settings/environment/.env.<ambiente>` (não versionados) + `.env.example` |
|
|
77
|
-
| database |
|
|
99
|
+
| database | `-x env=<ambiente>` / `poe migrate <ambiente>` (padrão `local`) | `env/.env.<ambiente>` (não versionados) + `env/.env.example` |
|
|
78
100
|
|
|
79
101
|
- Em container nenhum arquivo `.env` existe (o `.dockerignore` tira): as variáveis vêm do deploy. Arquivo
|
|
80
102
|
ausente não pode quebrar a subida.
|
|
@@ -139,7 +161,7 @@ do Dockerfile falha com `package.json` e lock divergentes.
|
|
|
139
161
|
| angular | `start`, `dev`, `start:local`, `start:homol`, `build` (prod), `build:dev`, `build:homol`, `watch`, `test`, `lint:a11y`, `axe:check`, `codegen` |
|
|
140
162
|
| graphql | `dev`, `start`, `start:local`, `start:homol`, `build` (typecheck + esbuild), `typecheck`, `start:prod`, `test` |
|
|
141
163
|
| server | `poe start:local`, `poe start:dev`, `poe start:homol`, `poe test` |
|
|
142
|
-
| database | `
|
|
164
|
+
| database | `poe migrate <ambiente>`, `poe status <ambiente>`, `poe nova "<descrição>"`, `poe bootstrap <ambiente>`, `poe seed <ambiente>`, `poe seed-regerar <ambiente>`, `poe test` |
|
|
143
165
|
|
|
144
166
|
## 10. Testes mínimos
|
|
145
167
|
|
|
@@ -148,7 +170,7 @@ do Dockerfile falha com `package.json` e lock divergentes.
|
|
|
148
170
|
| angular | `app.config.spec`, `core.providers.spec`, `environments.spec`, `core.component.spec`, `features.routes.spec` (UUID único, `load()` standalone, documento carregável) + spec de toda tela nova/alterada |
|
|
149
171
|
| graphql | `builder.test` (subida, path, CORS, introspecção desligada, lote, 400 de sintaxe, 401/403 antes do resolver, encerramento), `builder-falha.test` (Orfeu fora → 503 → 200; campo sem `operation()` não sobe), `builder-padroes.test`, `shutdown.test` (teto → 1), `resolvers.test` (tabela campo → chamada REST) |
|
|
150
172
|
| server | `test_health`, `test_api_docs` (só `local`; `API_DOCS` força), testes de domínio com SQLite em memória |
|
|
151
|
-
| database | suíte compartilhada
|
|
173
|
+
| database | suíte compartilhada: migrations do zero, de novo sem efeito, `stamp`, migration nova numerada, confirmação em prod, seed (idempotente, regerar estável) — num Postgres em memória (PGlite por socket) |
|
|
152
174
|
|
|
153
175
|
Validação antes de entregar: suíte e build de cada camada alterada (`ng test` + `ng build`; `vitest` +
|
|
154
176
|
`typecheck` + `build`; `pytest` em ambiente recriado do zero quando dependência mudou).
|
|
@@ -166,6 +188,8 @@ Validação antes de entregar: suíte e build de cada camada alterada (`ng test`
|
|
|
166
188
|
- [ ] Pastas `angular/`, `graphql/`, `server/`, `database/` e README da raiz com portas e pendências
|
|
167
189
|
- [ ] Só `local`/`dev`/`homol`/`prod`; `.env.example` em cada backend; nenhum `.env` versionado
|
|
168
190
|
- [ ] `REDIS_DB` próprio por ambiente (nenhum outro app no mesmo índice) e prefixo `<app>:` nas chaves/canais
|
|
191
|
+
- [ ] Toda conexão ao Redis nomeada (`<app>-<componente>[-<papel>]`, `REDIS_CLIENT_NAME`; `connectionName` no ioredis, `client_name` no `ConnectionPool` do redis-py), com teste e no `.env.example`
|
|
192
|
+
- [ ] Tudo sob o contexto `/<app>` (front, graphql, server, mcp), também no compose: `API_PREFIX`/`GRAPHQL_PATH` definidos, URLs internas com o prefixo, nada em `/api` genérico
|
|
169
193
|
- [ ] Gateway sobe negando com `/health` 503 → 200; server com `/health` sob o prefixo
|
|
170
194
|
- [ ] Encerramento 0/1 com teto de 8 s; `CMD` em forma exec
|
|
171
195
|
- [ ] Documentação de API só em `local`; TLS desligado avisado; sem `disable_warnings` global
|
|
@@ -19,14 +19,14 @@ app de origem — e depois remova o que for específico dele. Copiar do zero de
|
|
|
19
19
|
| 1 | **Esqueleto** `angular/`, `graphql/`, `server/`, `database/` + `.gitignore` da raiz, copiados da base sem artefatos nem domínio | acropole | `arquitetura.md` §1 |
|
|
20
20
|
| 2 | **Front**: nome do projeto no `angular.json` (`outputPath`, `buildTarget`), `baseHref` `/<app>/`, porta nos scripts, `package.json` (nome, versão `0.1.0`), environments dos quatro ambientes com o client/realm do app e o cliente GraphQL `<app>` (`CHANGE_ME` onde a URL deve ser derivada atrás do proxy), `features.routes.ts` vazio com o exemplo comentado, `styles.scss` mínimo, título/`lang="pt-BR"` no `index.html`, `axe-routes.config.json` com a porta e o caminho base. Tire dependências que só a base usava (editor, gráficos) | angular + trismegisto | angular `references/estrutura.md`, `references/testes-build.md` |
|
|
21
21
|
| 3 | **Specs fixos do front** (`app.config`, `core.providers`, `environments`, `core.component`, `features.routes`) ajustados ao app | angular | angular `references/testes-build.md` |
|
|
22
|
-
| 4 | **Gateway**: `AppModules` e `ExtendedSchema` vazios (base `_health` público, `_noop` privado em Mutation **e** Subscription — o GraphQL não aceita tipo raiz vazio), porta, `GRAPHQL_PATH`, prefixo `<app>:` nos canais, mensagens do `response.ts`, `.env.example` com o app do gateway no Argos | apollo + orfeu | apollo `references/estrutura-bootstrap.md` |
|
|
22
|
+
| 4 | **Gateway**: `AppModules` e `ExtendedSchema` vazios (base `_health` público, `_noop` privado em Mutation **e** Subscription — o GraphQL não aceita tipo raiz vazio), porta, `GRAPHQL_PATH`, prefixo `<app>:` nos canais, conexões Redis nomeadas por papel (`<app>-graphql-publisher`/`-subscriber`, `REDIS_CLIENT_NAME`), mensagens do `response.ts`, `.env.example` com o app do gateway no Argos | apollo + orfeu | apollo `references/estrutura-bootstrap.md` |
|
|
23
23
|
| 5 | **Testes do gateway**: manter os genéricos (subida, autorização com `_noop`, falha de subida, padrões, encerramento), tabela de rotas REST vazia, tirar os de domínio | apollo | apollo `references/testes-build.md` |
|
|
24
|
-
| 6 | **Server**: settings só com Argos, Postgres, Redis e `api_docs` (`api_prefix` `/<app>/server`, porta), `AppSettings`/base declarativa do schema `<app>`, router raiz só com `/health`, `main.py` sem tarefas da base, `.env.example` com o app do server, `pyproject.toml` (poe) com a porta | fastapi + orfeu | fastapi `references/estrutura.md` |
|
|
24
|
+
| 6 | **Server**: settings só com Argos, Postgres, Redis (com `redis_client_name` = `<app>-server`, `client_name` no `ConnectionPool`) e `api_docs` (`api_prefix` `/<app>/server`, porta), `AppSettings`/base declarativa do schema `<app>`, router raiz só com `/health`, `main.py` sem tarefas da base, `.env.example` com o app do server, `pyproject.toml` (poe) com a porta | fastapi + orfeu | fastapi `references/estrutura.md` |
|
|
25
25
|
| 7 | **Testes do server**: `conftest` com a base do app, `test_health`, `test_api_docs` | fastapi | fastapi `references/testes-deploy.md` |
|
|
26
|
-
| 8 | **Banco**: `
|
|
26
|
+
| 8 | **Banco**: `database/` copiada da base (Alembic) com o nome do app em `ambiente.py`, `bootstrap.sql` e `env/.env.example`; `0001_linha_de_base` só com o `CREATE SCHEMA`; `seed/` vazio; seções "Schemas"/"Particularidades" do `CLAUDE.md` da pasta; `poe test` | fastapi | fastapi `references/banco.md` |
|
|
27
27
|
| 9 | **Dockerfiles** das três camadas com as portas novas e o caminho do build do front | docker | docker `references/modelos.md` |
|
|
28
28
|
| 10 | **README da raiz**: componentes e portas, cadastro no Argos (IDs públicos), como rodar, padrões, pendências | acropole | `arquitetura.md` |
|
|
29
|
-
| 11 | **Validação**: instalar e rodar tudo — `ng test` + `ng build` + `lint:a11y`; `vitest` + `typecheck` + `build`; ambiente Python novo + `pytest`; `pytest` do banco (
|
|
29
|
+
| 11 | **Validação**: instalar e rodar tudo — `ng test` + `ng build` + `lint:a11y`; `vitest` + `typecheck` + `build`; ambiente Python novo + `pytest`; `pytest` do banco (migrations num Postgres em memória); importar o `main.py` com variáveis fictícias. Procure no app novo o nome da base (`grep -ri`) e o que sobrar de domínio | acropole | `arquitetura.md` §10 |
|
|
30
30
|
|
|
31
31
|
Fora do código (diga ao usuário no fim): **redirect URIs** do client no Argos (`<origem>/<app>/callback` e
|
|
32
32
|
`/logoff`, inclusive `localhost` para o desenvolvimento), **acesso** dos grupos ao client e cada roteador privado
|
|
@@ -99,8 +99,11 @@ export function wsContextParams(
|
|
|
99
99
|
import { RedisPubSub } from 'graphql-redis-subscriptions';
|
|
100
100
|
import { Redis } from 'ioredis';
|
|
101
101
|
|
|
102
|
-
|
|
102
|
+
// Toda conexão nomeada (CLIENT SETNAME) por papel: `meuapp-graphql-publisher` / `-subscriber` no CLIENT LIST.
|
|
103
|
+
function options(role: 'publisher' | 'subscriber') {
|
|
104
|
+
const base = process.env.REDIS_CLIENT_NAME?.trim() || 'meuapp-graphql';
|
|
103
105
|
return {
|
|
106
|
+
connectionName: `${base}-${role}`,
|
|
104
107
|
host: process.env.REDIS_HOST,
|
|
105
108
|
port: Number(process.env.REDIS_PORT ?? 6379),
|
|
106
109
|
password: process.env.REDIS_PASSWORD || undefined,
|
|
@@ -120,8 +123,8 @@ let instance: RedisPubSub | undefined;
|
|
|
120
123
|
/** Criado no primeiro uso: em escopo de módulo leria process.env antes do dotenv.config(). */
|
|
121
124
|
export function getPubSub(): RedisPubSub {
|
|
122
125
|
if (!instance) {
|
|
123
|
-
const publisher = new Redis(options());
|
|
124
|
-
const subscriber = new Redis(options());
|
|
126
|
+
const publisher = new Redis(options('publisher'));
|
|
127
|
+
const subscriber = new Redis(options('subscriber'));
|
|
125
128
|
throttleErrors(publisher, 'publisher');
|
|
126
129
|
throttleErrors(subscriber, 'subscriber');
|
|
127
130
|
instance = new RedisPubSub({ publisher, subscriber });
|
|
@@ -133,9 +136,12 @@ export const channel = (name: string) => `${process.env.REDIS_CHANNEL_PREFIX ??
|
|
|
133
136
|
```
|
|
134
137
|
|
|
135
138
|
- Instância Redis compartilhada → **prefixo de canal** por app, igual no publicador e no gateway.
|
|
139
|
+
- **Conexão sem `connectionName` é defeito** (acropole `arquitetura.md` §3.1): sem ele não dá para saber, no
|
|
140
|
+
`CLIENT LIST`/redis_exporter, quem abre as conexões. `REDIS_CLIENT_NAME` sobrescreve a base; o papel continua
|
|
141
|
+
sufixado. Um teste confere os dois nomes e a sobrescrita.
|
|
136
142
|
- `REDIS_DB` diferente entre publicador e gateway = eventos que nunca chegam, sem erro. Redis Cluster só tem
|
|
137
143
|
o db 0.
|
|
138
|
-
- Para Cluster: `new Redis.Cluster(nodes, { redisOptions: { password } })` escolhido por variável
|
|
144
|
+
- Para Cluster: `new Redis.Cluster(nodes, { redisOptions: { password, connectionName } })` escolhido por variável
|
|
139
145
|
(`REDIS_CLUSTER=true`, `REDIS_HOSTS=h1:p,h2:p`).
|
|
140
146
|
- Sem o listener de `error`, Redis fora do ar em dev inunda o console com "Unhandled error event".
|
|
141
147
|
|
|
@@ -164,6 +164,7 @@ CMD ["node", "dist/index.js"]
|
|
|
164
164
|
| `PLATFORM_SERVICE_URL` (ou `<SERVICO>_URL`) | `baseURL` dos módulos REST |
|
|
165
165
|
| `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB`, `REDIS_CHANNEL_PREFIX` | pub/sub; `REDIS_DB` próprio do app (nunca o mesmo de outro app no mesmo Redis), igual ao do server do app |
|
|
166
166
|
| `REDIS_CLUSTER`, `REDIS_HOSTS` | modo cluster |
|
|
167
|
+
| `REDIS_CLIENT_NAME` | base do nome das conexões (`CLIENT SETNAME`), padrão `<app>-graphql`; o papel é sufixado (`-publisher`/`-subscriber`) — ver subscriptions.md |
|
|
167
168
|
| `GRAPHQL_INTROSPECTION` | `true` só onde se roda o codegen |
|
|
168
169
|
|
|
169
170
|
`.env.*` fora do git (`.gitignore`), com `.env.example` só com nomes. Variáveis que o gateway não usa (banco,
|
package/skills/docker/SKILL.md
CHANGED
|
@@ -93,6 +93,8 @@ background no lifespan: cada worker do uvicorn roda o lifespan inteiro e a taref
|
|
|
93
93
|
| Segredo visível em `ps aux` no host | `podman run -e SEGREDO=...` montado por código; use `--env-file` temporário |
|
|
94
94
|
| `/bin/sh^M: bad interpreter` / `$'\r': command not found` | `.sh` com CRLF; falta `*.sh text eol=lf` no `.gitattributes` |
|
|
95
95
|
| HEALTHCHECK ignorado com aviso no build | Podman/Buildah em formato OCI (padrão); só o formato `docker` grava |
|
|
96
|
+
| Podman no Windows: todo container falha com `controller pids is not available` | VM do WSL sem o controlador `pids`; ver `references/podman-local.md` |
|
|
97
|
+
| Podman no Windows: socket montado vira pasta vazia (`/mnt/c/run/...`) | compose rodado pelo cliente do Windows; rode dentro da VM (`references/podman-local.md`) |
|
|
96
98
|
|
|
97
99
|
## Índice de referências
|
|
98
100
|
|
|
@@ -100,3 +102,4 @@ background no lifespan: cada worker do uvicorn roda o lifespan inteiro e a taref
|
|
|
100
102
|
| --- | --- |
|
|
101
103
|
| `references/modelos.md` | Dockerfiles comentados: Angular (dev/build/site), Node (Express/Apollo), Node servindo SPA + API, Python (FastAPI, com e sem compilação); `.dockerignore` por stack |
|
|
102
104
|
| `references/porques.md` | Cada decisão explicada: base, multi-stage, cache, `npm ci`, credenciais, segredo sem default, `--env-file`, nome que vira caminho, `.sh` em LF, sinais e PID 1, exec form, não-root, HEALTHCHECK, porta, ARG x ENV, `.dockerignore`, `timeout`, scratch no Angular, workers do uvicorn, Podman x Docker |
|
|
105
|
+
| `references/podman-local.md` | Subir as stacks com Podman Machine no Windows (WSL): cgroups, portas, compose dentro da VM, rede e DNS |
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Podman local no Windows (Podman Machine sobre WSL)
|
|
2
|
+
|
|
3
|
+
Como subir as stacks (Argos, Hefesto, workers) numa máquina Windows com Podman, e o que quebra no caminho. Tudo
|
|
4
|
+
aqui foi encontrado subindo a plataforma inteira do zero; cada item tem o sintoma para achar pela mensagem de erro.
|
|
5
|
+
|
|
6
|
+
## Máquina
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
podman machine init --cpus 4 --memory 6144 --now
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
- **Rootless** (o padrão). No rootful sobre WSL as portas publicadas não chegam ao Windows: o rootful publica por
|
|
13
|
+
NAT, sem socket ouvindo, e o encaminhamento do WSL só enxerga sockets. A rede em modo usuário
|
|
14
|
+
(`--user-mode-networking`) também não resolveu, e ligar e desligar essa opção apagou o `/etc/resolv.conf` da VM
|
|
15
|
+
(resolvido com `wsl --shutdown` e `podman machine start`).
|
|
16
|
+
- **Controlador `pids`**: a VM do WSL não o delega aos containers. Sem ajuste, **todo** container falha com
|
|
17
|
+
`crun: controller 'pids' is not available`. Desligue o limite nos dois lados, porque o cliente do Windows manda o
|
|
18
|
+
limite padrão no pedido, e reinicie a máquina para o serviço da API reler a configuração:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
# Windows: %APPDATA%\containers\containers.conf.d\50-pids.conf
|
|
22
|
+
# VM: /etc/containers/containers.conf.d/50-pids.conf (podman machine ssh + sudo)
|
|
23
|
+
[containers]
|
|
24
|
+
pids_limit = 0 # -1 não funciona; tem que ser 0
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
- **Portas baixas** (o Caddy do Talos usa 80/443): `net.ipv4.ip_unprivileged_port_start=80` em
|
|
28
|
+
`/etc/sysctl.d/` dentro da VM.
|
|
29
|
+
- **Socket do Podman** para quem dispara containers (ciclope, talos): `/run/user/1000/podman/podman.sock`
|
|
30
|
+
(confirme o uid com `id -u` na VM).
|
|
31
|
+
|
|
32
|
+
## Compose
|
|
33
|
+
|
|
34
|
+
- **Rode o compose de dentro da VM** quando ele monta caminho absoluto (o socket no ciclope e no talos, o
|
|
35
|
+
`/etc/hostname`). O cliente do Windows trata `/run/...` como caminho do Windows (vira `/mnt/c/run/...`), e o socket
|
|
36
|
+
montado aparece no container como **pasta vazia** (`connection refused`). O repositório fica acessível na VM em
|
|
37
|
+
`/mnt/c/Users/...`:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
podman machine ssh "sudo dnf -y install podman-compose"
|
|
41
|
+
podman machine ssh "cd '/mnt/c/Users/<você>/.../apps/hefesto/compose' && podman-compose --in-pod false up -d"
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
- **`--in-pod false`** no podman-compose. O padrão agrupa os serviços num pod, e criar o cgroup do pod falha nessa
|
|
45
|
+
VM (`unable to create pod cgroup ... was already loaded or has a fragment file`).
|
|
46
|
+
- O `podman machine ssh` no Windows grava a chave do host num arquivo **`NUL`** no diretório atual (bug do Podman).
|
|
47
|
+
Não commite: apague pelo caminho exato (`rm -- caminho/NUL`), porque `find` não lista nomes reservados.
|
|
48
|
+
- O Git Bash converte argumentos que começam com `/` em caminho do Windows (`-w /srv` vira `C:/Program Files/Git/srv`).
|
|
49
|
+
Use `MSYS_NO_PATHCONV=1` nesses comandos.
|
|
50
|
+
|
|
51
|
+
## Rede e DNS
|
|
52
|
+
|
|
53
|
+
- Do container para um serviço publicado no host: `host.containers.internal` (o equivalente do
|
|
54
|
+
`host.docker.internal`).
|
|
55
|
+
- Um nome que precisa resolver **tanto nos containers quanto no engine** (ex.: o registry, usado no push e no
|
|
56
|
+
pull pelo engine e na API pelo hefesto-server): conecte o container do registry à rede do compose e, na VM, aponte
|
|
57
|
+
o nome para `127.0.0.1` no `/etc/hosts`. Nesse caso, impeça os containers de herdarem o `/etc/hosts` da VM, senão
|
|
58
|
+
o nome resolve para `127.0.0.1` também dentro deles:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
# VM: /etc/containers/containers.conf.d/60-hosts.conf
|
|
62
|
+
[containers]
|
|
63
|
+
base_hosts_file = "none"
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
- Cookies `Secure` (SSO do Argos) funcionam em `http://localhost` no navegador, que trata localhost como contexto
|
|
67
|
+
seguro. Em script (requests, curl), é preciso reenviá-los à mão.
|
|
68
|
+
|
|
69
|
+
## Contexto das aplicações
|
|
70
|
+
|
|
71
|
+
Também no compose local, cada serviço fica no próprio contexto (`/hefesto/server`, `/argos/...`): defina o
|
|
72
|
+
`API_PREFIX` do serviço e use o mesmo caminho nas URLs internas. Ver a regra em
|
|
73
|
+
`../../acropole/references/arquitetura.md` (seção 3).
|
|
@@ -151,7 +151,9 @@ Padrão adotado (genérico):
|
|
|
151
151
|
## Cache
|
|
152
152
|
|
|
153
153
|
Redis (`ioredis`) num módulo singleton iniciado antes do servidor; usado para rate limit, sessões
|
|
154
|
-
curtas e pub/sub.
|
|
154
|
+
curtas e pub/sub. Toda conexão é nomeada (obrigatório, acropole `arquitetura.md` §3.1): `connectionName:
|
|
155
|
+
process.env.REDIS_CLIENT_NAME?.trim() || '<app>-<componente>'` em todos os modos (standalone, Sentinel, e
|
|
156
|
+
`redisOptions` no Cluster), e a conexão de assinante (`duplicate()`) com o papel sufixado (`-subscriber`). Cache em memória com TTL curto (ex.: 30 s) é aceitável para listas pequenas lidas a
|
|
155
157
|
cada requisição (allowlist de CORS), sabendo que cada réplica tem o seu.
|
|
156
158
|
|
|
157
159
|
## Chamadas a outros serviços
|
package/skills/fastapi/SKILL.md
CHANGED
|
@@ -42,9 +42,9 @@ orfeu — não duplique aqui.
|
|
|
42
42
|
`SessionLocal` em `app.state`, sessão por requisição via `Depends(get_db)`. Rotas que usam a sessão
|
|
43
43
|
síncrona devem ser `def` (rodam no threadpool), não `async def`. Ver
|
|
44
44
|
[references/banco.md](references/banco.md).
|
|
45
|
-
9. **Schema do banco fora do
|
|
46
|
-
|
|
47
|
-
|
|
45
|
+
9. **Schema do banco fora do serviço, com Alembic**: pasta `database/` irmã do serviço, migrations em SQL em
|
|
46
|
+
`migrations/versions/NNNN_*.py` (`poe nova`, `poe migrate <ambiente>`), seed de ambiente em `seed/` e
|
|
47
|
+
`bootstrap.py` para role+database. O serviço não migra nada e não há `create_all` em produção.
|
|
48
48
|
10. **Configuração por ambiente**: `pydantic-settings` + `src/.env` (só `APP_ENV`) +
|
|
49
49
|
`src/settings/environment/.env.<APP_ENV>`; variáveis do processo vencem os arquivos. Nunca versione
|
|
50
50
|
valores reais; mantenha um `.env.example` só com nomes.
|
|
@@ -119,7 +119,7 @@ def create_tag(body: TagCreate, db: Session = Depends(get_db)):
|
|
|
119
119
|
|---|---|
|
|
120
120
|
| [references/estrutura.md](references/estrutura.md) | Árvore do projeto, responsabilidades por camada, `main.py`, settings/env (nomes), dependências |
|
|
121
121
|
| [references/rotas-erros.md](references/rotas-erros.md) | Convenção de rotas e ids, `@operation`, Pydantic (entrada/saída, camelCase), envelope, erros e status |
|
|
122
|
-
| [references/banco.md](references/banco.md) | Engine/sessão, models e schemas do Postgres, transações, SQL cru, `database/` com
|
|
122
|
+
| [references/banco.md](references/banco.md) | Engine/sessão, models e schemas do Postgres, transações, SQL cru, `database/` com Alembic (migrations, seed, ambientes), armadilhas |
|
|
123
123
|
| [references/integracoes.md](references/integracoes.md) | Clientes HTTP, `orfeu_headers`, token de app, Redis, tarefas em segundo plano, collectors, logs |
|
|
124
124
|
| [references/testes-deploy.md](references/testes-deploy.md) | pytest (SQLite em memória, Postgres com savepoint, fakes do Orfeu), Dockerfile, uvicorn, `.dockerignore` |
|
|
125
125
|
|
|
@@ -5,8 +5,8 @@
|
|
|
5
5
|
- **Postgres apenas.** O ramo MSSQL (`mssql+pyodbc`, ODBC driver na imagem) foi removido de todos os
|
|
6
6
|
serviços; não reintroduza sem consumidor real.
|
|
7
7
|
- **SQLAlchemy 2.x síncrono** + **`psycopg2-binary`** (`postgresql+psycopg2`). Sem asyncpg, sem ORM async.
|
|
8
|
-
- **
|
|
9
|
-
|
|
8
|
+
- **Schema versionado com Alembic numa pasta `database/` irmã do serviço** (abaixo), com migrations em SQL, e
|
|
9
|
+
nunca `create_all` em produção: `create_all` só nos testes (SQLite). O serviço não roda migration nenhuma.
|
|
10
10
|
- Um *schema* Postgres por área do projeto (`deploy`, `requests`, `catalogo`...), não `public`.
|
|
11
11
|
|
|
12
12
|
## Engine e sessão (`core/connections/database/events.py`)
|
|
@@ -81,8 +81,8 @@ class Tag(CatalogoBase):
|
|
|
81
81
|
|
|
82
82
|
- PK `UUID` chamada `<entidade>_id`; `TIMESTAMPTZ` (`DateTime(timezone=True)`); `TEXT` em vez de
|
|
83
83
|
`VARCHAR(n)` salvo regra real.
|
|
84
|
-
- O model espelha o
|
|
85
|
-
|
|
84
|
+
- O model espelha o schema das migrations de `database/migrations/versions/` — o SQL é a fonte da verdade; a
|
|
85
|
+
migration que muda uma tabela vem no mesmo PR que muda o model.
|
|
86
86
|
- Desativação lógica (`active=false`) quando há FK apontando, em vez de apagar.
|
|
87
87
|
- Constante do schema exportada (`CATALOGO_SCHEMA`) para os testes usarem `schema_translate_map`.
|
|
88
88
|
|
|
@@ -130,68 +130,71 @@ execução aborta num script que nem tem parâmetros. Soluções:
|
|
|
130
130
|
especial do psycopg2 e precisa de `%%`);
|
|
131
131
|
- query com parâmetros e um `:` literal: escape só esse (`'10\:30'`) ou passe o literal como parâmetro.
|
|
132
132
|
|
|
133
|
-
## Pasta `database/` (
|
|
133
|
+
## Pasta `database/` (migrations com Alembic)
|
|
134
134
|
|
|
135
|
-
Mesma estrutura em todo app, ao lado de `angular/`, `graphql/` e `server/`.
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
`
|
|
139
|
-
|
|
135
|
+
Mesma estrutura em todo app (Python ou Node: o argos também), ao lado de `angular/`, `graphql/` e `server/`. O
|
|
136
|
+
schema é versionado com **Alembic**, sem models: cada migration é SQL. O Alembic grava em cada banco (tabela
|
|
137
|
+
`alembic_version`) a última que rodou e aplica só as que faltam. `ambiente.py`, `bootstrap.py`, `seed.py`,
|
|
138
|
+
`migrations/env.py`, `migrations/util.py`, o template, `alembic.ini`, `pyproject.toml` e `tests/` são iguais entre os
|
|
139
|
+
apps, a menos do nome do app, das schemas e das tabelas de referência/fora do seed.
|
|
140
140
|
|
|
141
141
|
```
|
|
142
142
|
database/
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
tests/ pytest sem rede nem banco real; tests/pg = PGlite (Postgres em memória) para os testes de SQL
|
|
143
|
+
alembic.ini sem conexão (vem do ambiente); script_location = migrations, revision_environment = true
|
|
144
|
+
ambiente.py env/.env.<local|dev|homol|prod> (fora do git) ou variáveis do processo; DATABASE_URL vence
|
|
145
|
+
migrations/
|
|
146
|
+
env.py -x env=<ambiente> (padrão local); transação única + advisory lock; prod pede confirmação
|
|
147
|
+
(-x confirmar=sim no pipeline); numera as novas em sequência (0002, 0003...)
|
|
148
|
+
util.py executar_sql / executar_arquivo: SQL direto no driver (':' não vira parâmetro)
|
|
149
|
+
script.py.mako modelo de migration nova (upgrade com executar_sql; downgrade opcional)
|
|
150
|
+
versions/0001_linha_de_base.py + .sql schema inicial + dados de referência; 0002_..., 0003_...
|
|
151
|
+
bootstrap.sql + .py CREATE ROLE/DATABASE <app> + REVOKE CONNECT FROM PUBLIC; senha por :'role_password'
|
|
152
|
+
seed.py + seed/ cadastros de ambiente, NN-<schema>.<tabela>.sql (ver abaixo) -- não são migrations
|
|
153
|
+
env/.env.example POSTGRESQL_HOST/PORT/DATABASE/USER/PASSWORD (+ POSTGRESQL_SUPERUSER(_PASSWORD) do bootstrap)
|
|
154
|
+
pyproject.toml atalhos do poe
|
|
155
|
+
requirements*.txt alembic, python-dotenv, SQLAlchemy, psycopg2-binary (+ pytest, poethepoet)
|
|
156
|
+
tests/ migrations e seed de verdade num Postgres em memória (tests/pg: PGlite exposto por socket)
|
|
158
157
|
```
|
|
159
158
|
|
|
160
|
-
|
|
161
|
-
(pulam as checagens que dependem de tabela/migration) e passam a valer a partir da primeira.
|
|
162
|
-
|
|
163
|
-
Uso:
|
|
159
|
+
Uso (venv ativa):
|
|
164
160
|
|
|
165
161
|
```bash
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
162
|
+
poe migrate homol # alembic -x env=homol upgrade head
|
|
163
|
+
poe status prod # alembic -x env=prod current
|
|
164
|
+
poe historico # alembic history
|
|
165
|
+
poe nova "adiciona coluna x" # cria migrations/versions/<próximo número>_adiciona_coluna_x.py
|
|
166
|
+
poe bootstrap homol # role+database, uma vez por servidor Postgres (superuser do env)
|
|
167
|
+
poe seed homol # aplica seed/ num ambiente novo, depois do migrate
|
|
168
|
+
poe seed-regerar prod # regrava seed/ a partir do banco (sessão só de leitura)
|
|
169
|
+
poe test
|
|
170
170
|
```
|
|
171
171
|
|
|
172
172
|
Regras:
|
|
173
173
|
|
|
174
|
-
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
174
|
+
- **Mudança de schema = uma migration nova**, com o SQL que roda num banco que já tem dado (`ALTER TABLE ...`,
|
|
175
|
+
`CREATE INDEX ...`, `UPDATE` de dado de referência), dentro de `executar_sql`. Nunca edite migration que já rodou
|
|
176
|
+
em algum banco: corrija com outra. `downgrade` é opcional (deixe o `raise` se voltar não faz sentido).
|
|
177
|
+
- As migrations conectam como o **usuário do app** (o role do bootstrap): tabela nova já nasce dele.
|
|
178
|
+
- **Ordem do deploy**: `poe migrate <ambiente>` antes de subir a versão do serviço que usa a coluna nova. Migration
|
|
179
|
+
destrutiva (DROP) só depois que nenhuma versão no ar lê o que ela remove.
|
|
180
|
+
- **Dado de referência** (o que o código usa por id: status, tipos, etapas) vai por migration. **Cadastro de
|
|
181
|
+
ambiente** (clients, apps, origins...) vai no seed: `INSERT ... ON CONFLICT (pk) DO UPDATE`, gerado por
|
|
182
|
+
`poe seed-regerar` (nunca à mão), aplicado numa transação só. Histórico/log (builds, tentativas de login,
|
|
183
|
+
auditoria) não entra em nenhum dos dois.
|
|
184
|
+
- **Nunca dado real de pessoa no seed** (login, nome, e-mail, vínculo federado, MFA, membro de grupo), em nenhum app:
|
|
185
|
+
usuário de seed é fictício (`usuarioNN`, `usuarioNN@exemplo.com`) ou o dono do ambiente. O `seed-regerar` a partir de
|
|
186
|
+
produção traz pessoas reais de volta: reverta as tabelas de identidade e confira o diff antes de commitar. Dado
|
|
187
|
+
pessoal no histórico só sai reescrevendo o histórico.
|
|
188
|
+
- Segredo no seed só cifrado pelo serviço (ex.: `enc:v2:` do hefesto) ou em hash; um teste recusa o que estiver em
|
|
189
|
+
claro.
|
|
190
|
+
- Banco que já existia antes do Alembic: `alembic -x env=<ambiente> stamp 0001` uma vez (marca a linha de base sem
|
|
191
|
+
executar), depois `poe migrate` normalmente.
|
|
192
|
+
- App novo: `0001_linha_de_base` só com os `CREATE SCHEMA`; seed vazio.
|
|
189
193
|
|
|
190
194
|
Divergências observadas:
|
|
191
195
|
|
|
192
196
|
| Tema | Visto | Recomendado |
|
|
193
197
|
|---|---|---|
|
|
194
|
-
| Migrations | fora de `database
|
|
195
|
-
| `build.py` | versões com e sem `--seed`, relatório de erro e `newline=""` | a versão completa acima |
|
|
198
|
+
| Migrations | fora de `database/`, ou o serviço migrando na subida | Alembic em `database/migrations/versions/`, rodado por `poe migrate` antes do deploy |
|
|
196
199
|
| Seed | `DO NOTHING` por nome vs `DO UPDATE` por PK literal | regra da lista acima |
|
|
197
200
|
| Commit | no repository (todos) | `flush` no repository, `commit` no service quando a operação tem várias escritas |
|
|
@@ -267,7 +267,7 @@ Nomes de variáveis usados (sem valores):
|
|
|
267
267
|
| Ambiente | `APP_ENV`, `DEBUG`, `PORT`, `API_PREFIX`, `ALLOWED_HOSTS`, `API_DOCS` |
|
|
268
268
|
| Orfeu/Argos | `AUTHORIZER_URL`, `REALM_ID`, `APP_ID`, `APP_SECRET`, `AUTHORIZER_TLS_VERIFY`, `ARGOS_ADMIN_SERVER_URL` (se chamar o admin do Argos) |
|
|
269
269
|
| Postgres | `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `MIN_CONNECTION_COUNT`, `MAX_CONNECTION_COUNT` |
|
|
270
|
-
| Redis | `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB` (índice próprio do app — dois apps nunca no mesmo índice do mesmo Redis), + timeouts/prefixo `<app>:` de canal se usar pub/sub |
|
|
270
|
+
| Redis | `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB` (índice próprio do app — dois apps nunca no mesmo índice do mesmo Redis), `REDIS_CLIENT_NAME` (nome das conexões, padrão `<app>-server`; ver integracoes.md), + timeouts/prefixo `<app>:` de canal se usar pub/sub |
|
|
271
271
|
| Processo | `APP_ROLE` (`all`/`api`/`collector`) quando há collectors — ver integracoes.md |
|
|
272
272
|
|
|
273
273
|
Serviço com **vários bancos** usa o padrão de prefixo: `DB_ENTRIES=<nome1>,<nome2>` e, para cada nome,
|
|
@@ -285,7 +285,7 @@ atualizar: troque a versão, recrie o ambiente do zero e rode a suíte.
|
|
|
285
285
|
# Dependências DIRETAS (o que o código importa), com versão exata.
|
|
286
286
|
fastapi==0.142.2
|
|
287
287
|
uvicorn[standard]==0.54.0 # [standard]: uvloop + httptools (HTTP mais rápido no Linux)
|
|
288
|
-
orfeu[fastapi]==1.
|
|
288
|
+
orfeu[fastapi]==1.2.0
|
|
289
289
|
pydantic-settings==2.15.0
|
|
290
290
|
python-dotenv==1.2.4
|
|
291
291
|
loguru==0.7.3
|
|
@@ -91,10 +91,18 @@ pool = redis.ConnectionPool(
|
|
|
91
91
|
socket_connect_timeout=..., socket_timeout=...,
|
|
92
92
|
health_check_interval=30, # testa conexão ociosa antes de reusar
|
|
93
93
|
retry_on_timeout=True,
|
|
94
|
+
client_name=s.redis_client_name, # CLIENT SETNAME em toda conexão do pool (padrão "<app>-server")
|
|
94
95
|
)
|
|
95
96
|
app.state.redis = redis.Redis(connection_pool=pool)
|
|
96
97
|
```
|
|
97
98
|
|
|
99
|
+
- **Toda conexão nomeada (obrigatório, acropole `arquitetura.md` §3.1).** `redis_client_name: str =
|
|
100
|
+
"<app>-server"` nas settings (env `REDIS_CLIENT_NAME`, sem espaços — valide; vazio = padrão) e `client_name` no
|
|
101
|
+
`ConnectionPool`: vale para todas as conexões do pool, inclusive `pubsub()`. É o que aparece no campo `name=`
|
|
102
|
+
do `CLIENT LIST` e no redis_exporter para achar quem estoura o `maxclients`. Conexão fora do pool (`redis.Redis(
|
|
103
|
+
host=...)` solto, um worker) também leva `client_name`, com papel sufixado (`<app>-server-worker`). Teste:
|
|
104
|
+
`pool.connection_kwargs["client_name"]` com o padrão e com `REDIS_CLIENT_NAME` definido.
|
|
105
|
+
|
|
98
106
|
- Dependência `get_redis(request)` em `shared/dependencies.py` (um serviço usa `app.state.redis`, outro
|
|
99
107
|
`app.state.redis_client` — escolha `redis`).
|
|
100
108
|
- Instância compartilhada entre projetos → **prefixo de chave/canal** por projeto, configurável.
|