@acropole/skills 1.0.0 → 1.1.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.
@@ -31,14 +31,15 @@ process.on('unhandledRejection', (reason) => console.error('unhandledRejection:'
31
31
  - **Atenção ao ESM**: o `import builder` é avaliado ANTES do `dotenv.config()` (imports estáticos sobem
32
32
  primeiro). Nada no grafo de imports pode ler `process.env` em escopo de módulo — leia dentro de funções.
33
33
 
34
- ## `src/core/builder.ts` (padrão recomendado)
34
+ ## `src/core/builder.ts` (padrão)
35
35
 
36
36
  ```ts
37
+ import compression from 'compression';
37
38
  import express from 'express';
38
39
  import cors from 'cors';
39
40
  import { makeExecutableSchema } from '@graphql-tools/schema';
40
41
  import { expressMiddleware } from '@as-integrations/express4';
41
- import { OrfeuClient } from '@orfeu/node';
42
+ import { OrfeuClient, OrfeuConfigError } from '@orfeu/node';
42
43
  import { assertSchemaSecured, orfeuWsContext, secureResolvers } from '@orfeu/node/apollo';
43
44
 
44
45
  import { BASE_SCHEMA } from './schema/index.js';
@@ -51,13 +52,15 @@ import { ExtendedSchema } from '../web/config/schemas/schemas.extends.js';
51
52
  import type { GraphQLContext } from './context/context.types.js';
52
53
 
53
54
  export default async (settings: NodeJS.ProcessEnv) => {
55
+ const tlsVerify = settings.AUTH_TLS_VERIFY !== 'false'; // opt-out; prefira NODE_EXTRA_CA_CERTS com a CA do ambiente
54
56
  const orfeu = new OrfeuClient({
55
57
  authorizerUrl: settings.AUTHORIZER_URL!,
56
58
  realmId: settings.REALM_ID!,
57
59
  appId: settings.APP_ID!,
58
60
  secret: settings.APP_SECRET!,
59
- tlsVerify: settings.AUTH_TLS_VERIFY !== 'false', // opt-out; só para CA fora do bundle do Node
61
+ tlsVerify,
60
62
  });
63
+ if (!tlsVerify) console.warn('AUTH_TLS_VERIFY=false: o certificado do Argos NÃO é verificado (inclusive o JWKS).');
61
64
 
62
65
  // 1) schema seguro ANTES do startup (o startup sincroniza as operações registradas com o Argos)
63
66
  const extended = new ExtendedSchema();
@@ -66,12 +69,27 @@ export default async (settings: NodeJS.ProcessEnv) => {
66
69
  });
67
70
  const schema = makeExecutableSchema({ typeDefs: [...BASE_SCHEMA, ...extended.typeDefs], resolvers });
68
71
  assertSchemaSecured(schema);
69
- await orfeu.startup();
70
72
 
71
- // 2) módulos (clientes REST) — criados aqui, depois do dotenv
73
+ // 2) Orfeu: sobe e NEGA tudo até conectar, com nova tentativa de espera crescente (5 s → 30 s).
74
+ // Erro de configuração (OrfeuConfigError) não melhora tentando de novo: derruba a subida.
75
+ const status = { orfeuReady: false };
76
+ const startOrfeu = async (attempt = 1): Promise<void> => {
77
+ try {
78
+ await orfeu.startup();
79
+ status.orfeuReady = true;
80
+ } catch (err: any) {
81
+ if (err instanceof OrfeuConfigError) throw err;
82
+ const delay = Math.min(5_000 * 2 ** (attempt - 1), 30_000);
83
+ console.warn(`Orfeu indisponível (tentativa ${attempt}); operações negadas; nova tentativa em ${delay / 1000}s`);
84
+ setTimeout(() => void startOrfeu(attempt + 1), delay).unref();
85
+ }
86
+ };
87
+ await startOrfeu();
88
+
89
+ // 3) módulos (clientes REST) — criados aqui, depois do dotenv
72
90
  const appMods = await AppModules.start(settings);
73
91
 
74
- // 3) servidores: o MESMO path no HTTP e no WS
92
+ // 4) servidores: o MESMO path no HTTP e no WS
75
93
  const graphqlPath = settings.GRAPHQL_PATH ?? '/graphql';
76
94
  const app = express();
77
95
  const http = new HttpServer(app);
@@ -81,9 +99,15 @@ export default async (settings: NodeJS.ProcessEnv) => {
81
99
  const apollo = new ApolloServer(schema, http.server, ws.serverCleanup, orfeu);
82
100
  await apollo.server.start();
83
101
 
84
- app.get('/health', (_req, res) => { res.status(200).json({ ok: true }); }); // probe sem auth (aqui o startup já passou)
102
+ // probe sem auth (rota Express, fora do Orfeu): 503 enquanto o Orfeu não conecta, 200 depois
103
+ app.get('/health', (_req, res) => {
104
+ const tls = tlsVerify ? {} : { tls_verify: false };
105
+ if (!status.orfeuReady) { res.status(503).json({ status: 'starting', orfeu: 'unavailable', ...tls }); return; }
106
+ res.status(200).json({ ok: true, ...tls });
107
+ });
85
108
  app.use(
86
109
  graphqlPath,
110
+ compression(), // JSON comprime 70–85%: padrão, não otimização opcional
87
111
  cors<cors.CorsRequest>(),
88
112
  express.json({ limit: '2mb' }),
89
113
  expressMiddleware(apollo.server, {
@@ -94,11 +118,12 @@ export default async (settings: NodeJS.ProcessEnv) => {
94
118
  const port = Number(settings.PORT ?? 3000);
95
119
  http.server.listen(port, () => console.log(`GraphQL → http://localhost:${port}${graphqlPath}`));
96
120
 
97
- // 4) encerramento: node é PID 1 no container; sem handler o stop espera o SIGKILL
121
+ // 5) encerramento: node é PID 1 no container; sem handler o stop espera o SIGKILL.
122
+ // Encerramento completo sai com 0; estourar o teto de 8 s sai com 1 (o orquestrador distingue).
98
123
  for (const signal of ['SIGTERM', 'SIGINT'] as const) {
99
124
  process.once(signal, async () => {
100
- setTimeout(() => process.exit(0), 8_000).unref();
101
- await orfeu.flushAudit().catch(() => undefined); // envia o resto da fila de auditoria
125
+ setTimeout(() => process.exit(1), 8_000).unref();
126
+ await orfeu.close().catch(() => undefined); // para a recarga de permissões + envia a fila de auditoria (SDK antigo: flushAudit())
102
127
  await apollo.server.stop().catch(() => undefined); // drain: fecha HTTP e WS
103
128
  process.exit(0);
104
129
  });
@@ -114,38 +139,24 @@ Pontos:
114
139
  - `@orfeu/node` `^1.0.1` no `package.json` (a 1.0.0 aceitava `orfeuUser` forjado pelo `connectionParams`).
115
140
  O contexto do WS (`ws-context.ts`, com a allowlist) está em [subscriptions.md](subscriptions.md).
116
141
 
117
- ### Orfeu fora do ar na subida: cair ou subir negando
118
-
119
- Decisão do builder, explícita e comentada no código — **nunca** um "modo degradado" que libera tudo:
120
-
121
- | Escolha | Quando | Como |
122
- | --- | --- | --- |
123
- | **Cai** (`exit 1`) | padrão; o orquestrador reinicia e o deploy mostra a falha | `await orfeu.startup()` sem `catch`; o `index.ts` faz `process.exit(1)` |
124
- | **Sobe negando tudo** | o gateway tem rotas públicas que precisam ficar no ar, ou o Argos cai com frequência | `startup()` em segundo plano com nova tentativa; até conectar, as operações não públicas são negadas (o catálogo está vazio) |
125
-
126
- Se subir, o `/health` responde **503 até o Orfeu conectar** — senão o deploy e o monitoramento veem
127
- "saudável" um serviço que nega toda requisição:
142
+ ### Orfeu fora do ar na subida: sobe negando (padrão)
128
143
 
129
- ```ts
130
- let orfeuPronto = false;
131
- const startOrfeu = async (attempt = 1): Promise<void> => {
132
- try { await orfeu.startup(); orfeuPronto = true; }
133
- catch (err: any) {
134
- console.warn(`Orfeu indisponível (tentativa ${attempt}); nova tentativa em 30s:`, err.message);
135
- setTimeout(() => void startOrfeu(attempt + 1), 30_000).unref();
136
- }
137
- };
138
- void startOrfeu(); // não bloqueia a subida
144
+ Padrão único dos gateways — **nunca** um "modo degradado" que libera tudo, e também não cair em loop:
139
145
 
140
- app.get('/health', (_req, res) => {
141
- res.status(orfeuPronto ? 200 : 503).json({ ok: orfeuPronto, orfeu: orfeuPronto ? 'up' : 'connecting' });
142
- });
143
- ```
146
+ - O servidor **sobe** e o `/health` responde **503** (`{ status: 'starting', orfeu: 'unavailable' }`) até o
147
+ `startup()` completar; toda operação não pública é negada (401 sem token, 401/403 com token — sem JWKS e sem
148
+ catálogo sincronizado) e nenhuma chega ao backend.
149
+ - Nova tentativa com espera crescente: 5 s, 10 s, 20 s, depois a cada 30 s. Volta sozinho quando o Argos volta,
150
+ sem loop de restart do container.
151
+ - `OrfeuConfigError` (ex.: nenhuma operação registrada) **derruba** a subida: o `index.ts` sai com 1.
152
+ - O 503 não deve reiniciar o container: se o orquestrador tiver healthcheck ativo, ele precisa tolerar a subida.
153
+ - Teste obrigatório (`tests/integration/builder-falha.test.ts`): com o Orfeu fora, o servidor escuta, `/health`
154
+ dá 503, toda operação é negada sem chegar ao backend, e após a nova tentativa `/health` passa a 200.
144
155
 
145
156
  O `secureResolvers` e o `assertSchemaSecured` continuam **antes** de qualquer tentativa (o catálogo precisa
146
157
  estar registrado quando o `startup()` sincronizar).
147
158
 
148
- - `compression()` antes do Apollo vale a pena quando há respostas grandes (JSON comprime 70–85%).
159
+ - `compression()` antes do Apollo em todo gateway (JSON comprime 70–85%; respostas de vários MB caem para centenas de KB).
149
160
 
150
161
  ## `src/core/server/*.ts`
151
162
 
@@ -83,20 +83,20 @@ Validação focada: rode os testes do que mudou e `npm run typecheck`.
83
83
 
84
84
  ## Build
85
85
 
86
- Duas formas em uso — escolha uma por servidor e mantenha o `typecheck`:
87
-
88
- | Forma | Script | Observação |
89
- | --- | --- | --- |
90
- | `tsc` (recomendada para servidores novos) | `"build": "tsc"` | `module`/`moduleResolution: NodeNext`, `strict: true`, imports relativos com `.js` |
91
- | `esbuild` bundle | `esbuild src/index.ts --bundle --platform=node --format=esm --packages=external --target=es2022 --sourcemap --outfile=dist/index.js` | rápido; **não** checa tipos → `"typecheck": "tsc --noEmit"` obrigatório |
86
+ Padrão: **`typecheck` + bundle com esbuild** no mesmo script de build. O esbuild gera um arquivo só em
87
+ milissegundos (build de imagem mais rápido, subida sem resolver centenas de módulos) mas **não** checa tipos —
88
+ por isso o `build` roda o `tsc --noEmit` antes, e um erro de tipo nunca chega à imagem. Código que lê arquivo
89
+ relativo ao `dist/` em runtime (`readFileSync`, `__dirname`) quebra no bundle: confira antes de migrar.
92
90
 
93
91
  ```json
94
92
  {
95
93
  "type": "module",
96
94
  "scripts": {
97
95
  "dev": "cross-env NODE_ENV=local tsx watch src/index.ts",
96
+ "start": "cross-env NODE_ENV=local tsx src/index.ts",
98
97
  "start:local": "cross-env NODE_ENV=local tsx watch src/index.ts",
99
- "build": "tsc",
98
+ "start:homol": "cross-env NODE_ENV=homol tsx watch src/index.ts",
99
+ "build": "npm run typecheck && esbuild src/index.ts --bundle --platform=node --format=esm --packages=external --target=es2022 --tsconfig=tsconfig.json --sourcemap --outfile=dist/index.js",
100
100
  "typecheck": "tsc --noEmit",
101
101
  "start:prod": "node dist/index.js",
102
102
  "test": "vitest run"
@@ -105,8 +105,9 @@ Duas formas em uso — escolha uma por servidor e mantenha o `typecheck`:
105
105
  ```
106
106
 
107
107
  `tsconfig`: `target ES2022`, `module NodeNext`, `strict`, `esModuleInterop`, `skipLibCheck`, `outDir dist`,
108
- `rootDir src`. Alias `src/*` só se o build resolver (esbuild resolve; `tsc` puro **não** reescreve alias —
109
- em `tsc` use imports relativos).
108
+ `rootDir src`. Imports relativos com `.js` (o esbuild também resolveria alias `src/*`, mas relativo funciona
109
+ igual no `tsx`, no `vitest` e no `tsc`). Dependências com faixa explícita da versão em uso (`^16.14.2`, não
110
+ `^16`); `@types/node` na major do Node da imagem (`node:22` → `^22`).
110
111
 
111
112
  ## Migração Apollo Server 4 → 5
112
113
 
@@ -159,9 +160,9 @@ CMD ["node", "dist/index.js"]
159
160
  | `PORT` | porta HTTP/WS |
160
161
  | `GRAPHQL_PATH` | path do GraphQL **e** do WS (`/graphql`, ou `/<app>/graphql` atrás de proxy) |
161
162
  | `AUTHORIZER_URL`, `REALM_ID`, `APP_ID`, `APP_SECRET` | `OrfeuClient` (app registrado no Argos) |
162
- | `AUTH_TLS_VERIFY` | `false` só se a CA do Argos não está no bundle do Node |
163
+ | `AUTH_TLS_VERIFY` | `false` só se a CA do Argos não está no bundle do Node (prefira `NODE_EXTRA_CA_CERTS`); loga aviso e aparece no `/health` |
163
164
  | `PLATFORM_SERVICE_URL` (ou `<SERVICO>_URL`) | `baseURL` dos módulos REST |
164
- | `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB`, `REDIS_CHANNEL_PREFIX` | pub/sub |
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 |
165
166
  | `REDIS_CLUSTER`, `REDIS_HOSTS` | modo cluster |
166
167
  | `GRAPHQL_INTROSPECTION` | `true` só onde se roda o codegen |
167
168
 
@@ -198,6 +198,10 @@ Faz o engine marcar o container como `healthy`/`unhealthy` (visível no inventá
198
198
  instale `curl` só para isso.
199
199
  - Chame `127.0.0.1`, não o domínio, e inclua o prefixo do app no path.
200
200
  - `--start-period` cobre a subida (conexões, registro no Argos).
201
+ - Gateway GraphQL responde **503** no `/health` enquanto o Orfeu não conecta (sobe negando tudo e tenta de
202
+ novo): `unhealthy` nesse período é informação, não motivo para reiniciar. Docker/Podman puros só marcam o
203
+ estado; se o orquestrador reinicia container `unhealthy`, dê `--start-period`/`--retries` folgados para não
204
+ transformar Argos fora do ar em loop de restart.
201
205
  - **Podman/Buildah** gravam `HEALTHCHECK` apenas em imagem formato `docker`; no formato OCI (padrão)
202
206
  a instrução é descartada com aviso. E o deploy não espera `healthy` para concluir. Na prática o
203
207
  `/health` do app é o que importa: é ele que você consulta depois do deploy (ver **hefesto**).
@@ -46,11 +46,13 @@ Skills relacionadas (não duplicamos o conteúdo delas):
46
46
  9. **Chamadas a outros serviços repassam credencial e trace** (`orfeuHeaders(ctx)` dentro do contexto
47
47
  do Orfeu; repasse explícito dos headers nas rotas que não passam por ele). Nunca gere um span
48
48
  próprio que ninguém audita.
49
- 10. **Graceful shutdown** em `SIGTERM`/`SIGINT`: timer de segurança `unref()`, `flushAudit()` do
50
- Orfeu, `server.close()`. No container o `node` é PID 1 e roda direto (`CMD ["node", …]`), nunca via
51
- `npm start`.
49
+ 10. **Graceful shutdown** em `SIGTERM`/`SIGINT`: timer de segurança `unref()` (8 s, sai com **1**),
50
+ `flushAudit()` do Orfeu, `server.close()` (sai com **0**). No container o `node` é PID 1 e roda direto
51
+ (`CMD ["node", …]`), nunca via `npm start`.
52
52
  11. **Health check** em `GET <prefixo>/health`: verifica as dependências reais (`SELECT 1`, `PING`) com
53
- `Promise.allSettled` e responde `200`/`503` com o estado de cada uma.
53
+ `Promise.allSettled` e responde `200`/`503` com o estado de cada uma (+ `tls_verify: false` quando
54
+ `AUTH_TLS_VERIFY=false`). **Swagger (`<prefixo>/docs`) só com `API_DOCS`**, que por padrão liga só em
55
+ `NODE_ENV=local`. Padrão do app inteiro: skill `acropole` (`references/arquitetura.md`).
54
56
  12. **Logs JSON de uma linha** em produção (`{ time, level, msg, ...ctx }`), coloridos só em dev;
55
57
  nunca logar token, senha, segredo ou corpo de requisição de autenticação.
56
58
  13. **Rota escopada por recurso pai** (`/:clientId/...`) confere a posse de **todo** id da URL e do corpo
@@ -86,9 +88,9 @@ export default async (settings: EnvConfig) => {
86
88
  const server = await Server.start(settings);
87
89
  for (const sig of ['SIGTERM', 'SIGINT'] as const) {
88
90
  process.once(sig, async () => {
89
- setTimeout(() => process.exit(0), 8_000).unref();
90
- await orfeuClient.flushAudit().catch(() => undefined);
91
- server.http.close(() => process.exit(0));
91
+ setTimeout(() => process.exit(1), 8_000).unref(); // teto estourado = falha (1)
92
+ await orfeuClient.close().catch(() => undefined); // recarga de permissões + auditoria (SDK antigo: flushAudit())
93
+ server.http.close(() => process.exit(0)); // encerramento completo = 0
92
94
  });
93
95
  }
94
96
  return server;
@@ -131,7 +131,10 @@ Variáveis recorrentes (só nomes): `API_PREFIX`, `PORT`/`AGENT_PORT`, `DB_*`, `
131
131
  `SMTP_*`, `UI_STATIC_PATH`, `UI_BASE_PATH`, `GRAPHQL_PATH`, `GRAPHQL_INTROSPECTION`.
132
132
 
133
133
  - `AUTH_TLS_VERIFY=false` existe só para ambiente com certificado autoassinado; é opção **escopada ao
134
- client do Orfeu**, nunca `NODE_TLS_REJECT_UNAUTHORIZED=0` global.
134
+ client do Orfeu**, nunca `NODE_TLS_REJECT_UNAUTHORIZED=0` global. Desligada, loga um aviso na subida e
135
+ aparece como `tls_verify: false` no `/health`. Prefira `NODE_EXTRA_CA_CERTS` com a CA do ambiente.
136
+ - `API_DOCS` (opcional): liga/desliga o Swagger; sem ela, só em `NODE_ENV=local`.
137
+ - `@types/node` na major do Node da imagem (`node:22` → `^22`).
135
138
  - Booleans de env: compare com string (`v !== 'false'`), não `Boolean(v)` (`"false"` é truthy).
136
139
  - Arquivos `.env` cifrados (dotenvx) podem ir ao repositório; a chave de decifrar fica fora dele.
137
140
  Arquivo de `.env` em texto puro nunca é versionado.
@@ -271,4 +271,16 @@ export function decodeCursor(raw: string) {
271
271
  ## Documentação
272
272
 
273
273
  OpenAPI em `src/config/openapi.ts` servido por `swagger-ui-express` em `<prefixo>/docs`, com um CSP
274
- próprio para essa rota (o CSP global da API é `default-src 'none'`).
274
+ próprio para essa rota (o CSP global da API é `default-src 'none'`). **Só monte a rota com `config.API_DOCS`**:
275
+ o mapa da API não fica exposto sem autenticação nos ambientes publicados.
276
+
277
+ ```ts
278
+ // config/index.ts (zod): sem API_DOCS, liga só em NODE_ENV=local (o container roda com outro NODE_ENV)
279
+ API_DOCS: z.enum(['true', 'false']).optional()
280
+ .transform((v) => (v === undefined ? process.env.NODE_ENV === 'local' : v === 'true')),
281
+
282
+ // router.ts
283
+ if (config.API_DOCS) router.use('/docs', cspDaDocumentacao, swaggerUi.serve, swaggerUi.setup(openApiSpec));
284
+ ```
285
+
286
+ Teste do config: `NODE_ENV=dev`/`test` → `false`; `local` → `true`; `API_DOCS` força nos dois sentidos.
@@ -36,7 +36,8 @@ router.get('/health', async (_req, res) => {
36
36
  const postgres = pg.status === 'fulfilled' ? 'ok' : 'error';
37
37
  const cacheSt = redis.status === 'fulfilled' ? 'ok' : 'error';
38
38
  const status = postgres === 'ok' && cacheSt === 'ok' ? 'ok' : 'degraded';
39
- res.status(status === 'ok' ? 200 : 503).json({ status, postgres, redis: cacheSt });
39
+ const tls = config.AUTH_TLS_VERIFY ? {} : { tls_verify: false }; // TLS do autorizador desligado: visível
40
+ res.status(status === 'ok' ? 200 : 503).json({ status, postgres, redis: cacheSt, ...tls });
40
41
  });
41
42
  ```
42
43
 
@@ -48,16 +49,19 @@ router.get('/health', async (_req, res) => {
48
49
  ## Graceful shutdown
49
50
 
50
51
  ```ts
51
- for (const [sig, code] of [['SIGTERM', 143], ['SIGINT', 130]] as const) {
52
+ for (const sig of ['SIGTERM', 'SIGINT'] as const) {
52
53
  process.once(sig, async () => {
53
54
  Logger.info('Encerrando', { signal: sig });
54
- setTimeout(() => process.exit(code), 8_000).unref(); // garantia se algo segurar o close
55
- try { await orfeuClient.flushAudit(); } catch (err: any) { Logger.warn('flushAudit falhou', { message: err?.message }); }
56
- httpServer.close(() => process.exit(code));
55
+ setTimeout(() => process.exit(1), 8_000).unref(); // teto estourado = falha
56
+ try { await orfeuClient.close(); } catch (err: any) { Logger.warn('encerramento do Orfeu falhou', { message: err?.message }); } // SDK antigo: flushAudit()
57
+ httpServer.close(() => process.exit(0)); // encerramento completo = sucesso
57
58
  });
58
59
  }
59
60
  ```
60
61
 
62
+ - Mesma convenção em todo serviço Node do ecossistema: **0** quando drenou, **1** quando o teto estourou —
63
+ o orquestrador distingue parada limpa de travamento (o 143/130 do shell não diz se a drenagem completou).
64
+
61
65
  - `flushAudit()` de **cada** `OrfeuClient` instanciado (`Promise.allSettled`).
62
66
  - Com Apollo, `ApolloServerPluginDrainHttpServer` + dispose do servidor WebSocket (apollo).
63
67
  - Feche também pool do Knex (`db.destroy()`) e Redis (`quit()`) se o encerramento puder demorar.
@@ -19,10 +19,9 @@ orfeu — não duplique aqui.
19
19
 
20
20
  1. **Python ≥ 3.11** (piso do `orfeu` e da imagem `python:3.11-slim`). FastAPI recente (≥ 0.142) e
21
21
  Starlette 1.x: **só `lifespan`** — `on_event`/`add_event_handler` não existem mais.
22
- 2. **Dependências em `requirements.txt` + `requirements-dev.txt`** (`-r requirements.txt` + `pytest`).
23
- É o que o Dockerfile instala. Não mantenha `pyproject.toml` do Poetry em paralelo (divergência real:
24
- um serviço tinha os dois e o pyproject listava drivers que a imagem já não instalava). Fixe
25
- `orfeu[fastapi]` numa versão exata ou faixa `>=1.0,<2`.
22
+ 2. **Dependências em `requirements.txt` + `requirements-dev.txt`**: só as **diretas**, cada uma com
23
+ **versão exata** (`fastapi==0.142.2`), `uvicorn[standard]`. É o que o Dockerfile instala. `pyproject.toml`
24
+ só com os atalhos do `poe` (`start:local|dev|homol`, `test`) — nada de Poetry em paralelo.
26
25
  3. **Estrutura por domínio**: `src/app/domains/<domínio>/{router,schemas,service,repository,models}.py`.
27
26
  Router fino → service (regra, levanta erros do Orfeu, não conhece HTTP) → repository (SQLAlchemy, sem
28
27
  regra). Um domínio usa outro **só pelo service**. Ver [references/estrutura.md](references/estrutura.md).
@@ -44,7 +43,7 @@ orfeu — não duplique aqui.
44
43
  síncrona devem ser `def` (rodam no threadpool), não `async def`. Ver
45
44
  [references/banco.md](references/banco.md).
46
45
  9. **Schema do banco fora do ORM**: pasta `database/` irmã do serviço com `manifest.yml` + `scripts/
47
- {delete,create,insert}` + `build.py` (gera `output/build.sql`, `--exec` aplica) + `migrations/NNN-*.sql`
46
+ {bootstrap,delete,create,insert,migrations}` + `build.py` (gera `output/build.sql`, `--exec` aplica) + `scripts/migrations/NNN-*.sql`
48
47
  manuais. Não há Alembic nem `create_all` em produção.
49
48
  10. **Configuração por ambiente**: `pydantic-settings` + `src/.env` (só `APP_ENV`) +
50
49
  `src/settings/environment/.env.<APP_ENV>`; variáveis do processo vencem os arquivos. Nunca versione
@@ -99,12 +98,16 @@ def create_tag(body: TagCreate, db: Session = Depends(get_db)):
99
98
  código novo passe `method=Method.X` explícito (regra da orfeu).
100
99
  - Proxy reverso que encaminha o path completo (sem strip): o serviço precisa montar rotas **e**
101
100
  `docs_url`/`openapi_url`/`redoc_url` sob `api_prefix` (`/<projeto>/server`).
102
- - `/docs`, `/openapi.json` e `/redoc` ligados em produção expõem o mapa da API: `fastapi_kwargs` passa
103
- `None` nos três quando `APP_ENV=prod` ([references/estrutura.md](references/estrutura.md)).
104
- - `AUTHORIZER_TLS_VERIFY=false` (TLS do autorizador desligado) só fora de produção, com `warning` no log;
105
- em `prod` as settings recusam subir.
101
+ - `/docs`, `/openapi.json` e `/redoc` expõem o mapa da API: ligados **só em `APP_ENV=local`** (`API_DOCS`
102
+ força); `fastapi_kwargs` passa `None` nos três fora disso ([references/estrutura.md](references/estrutura.md)).
103
+ - `AUTHORIZER_TLS_VERIFY=false` (TLS do autorizador desligado): `warning` na subida e `tls_verify: false` no
104
+ `/health`. `urllib3.disable_warnings` no processo inteiro esconde isso — use aviso uma vez por host.
105
+ - `/health` (envelope `ok(message="ok")` sob o `api_prefix`) em todo serviço. Padrão do app inteiro (pastas,
106
+ portas, ambientes, scripts): skill `acropole` (`references/arquitetura.md`).
106
107
  - Campo de settings não declarado entrando via `extra="allow"` (ex.: porta) funciona por acaso — declare
107
108
  todo campo usado.
109
+ - `request.state.user` é o `TokenClaims` do Orfeu (objeto: `.sub`, `.groups`, `.raw`), não `dict`: `.get()` dá
110
+ 500. Nome em `user.raw.get("preferred_username")`; com `x-api-token` o user é `None` (`request.state.api_token`).
108
111
  - Tarefa em segundo plano não pode usar a sessão da requisição (já fechada): abra outra a partir de
109
112
  `app.state.SessionLocal`.
110
113
  - `CMD` do container com `exec uvicorn ...` — sem `exec`, o `sh` vira PID 1, não repassa SIGTERM e todo
@@ -132,22 +132,34 @@ execução aborta num script que nem tem parâmetros. Soluções:
132
132
 
133
133
  ## Pasta `database/` (build do schema)
134
134
 
135
+ Mesma estrutura em todo app, ao lado de `angular/`, `graphql/` e `server/`. `build.py`, `tools/`, `tests/` (menos
136
+ `test_app.py`), `.gitignore`, `pytest.ini` e `requirements*.txt` são **idênticos byte a byte** entre os apps:
137
+ mudança neles vale para todos (copie para os outros e rode a suíte de cada um). O que é do app fica só em
138
+ `manifest.yml`, `env/`, `scripts/`, `tests/test_app.py` e nas seções "Schemas" e "Particularidades" do
139
+ `CLAUDE.md` da pasta. Um teste de estrutura falha se aparecer pasta ou arquivo fora do padrão.
140
+
135
141
  ```
136
142
  database/
137
- manifest.yml ordem dos arquivos por fase: delete / create / insert
138
- build.py scripts/ → output/build.sql; --exec aplica; --reset inclui delete; --seed só insert
143
+ manifest.yml ordem dos arquivos por fase: delete / create / insert (insert pode ser [] num app novo)
144
+ build.py scripts/ → output/build.sql; --exec aplica; --reset inclui delete; --seed só insert;
145
+ --bootstrap cria role+database (lê a senha do ambiente, nunca grava)
139
146
  requirements.txt python-dotenv, PyYAML, SQLAlchemy, psycopg2-binary
140
- env/.env(.example) POSTGRESQL_HOST, POSTGRESQL_PORT, POSTGRESQL_USER, POSTGRESQL_PASSWORD, POSTGRESQL_DATABASE
147
+ env/.env(.example) POSTGRESQL_HOST/PORT/DATABASE/USER/PASSWORD (+ POSTGRESQL_SUPERUSER(_PASSWORD) do bootstrap)
141
148
  scripts/
142
- bootstrap/ CREATE DATABASE/ROLE — manual, uma vez, fora do build (não roda em transação)
143
- delete/ DROP SCHEMA ... CASCADE — só com --reset (dev/homol/CI)
144
- create/<schema>/NN-*.sql forma FINAL das tabelas (CREATE TABLE sem IF NOT EXISTS)
145
- insert/<schema>/*.sql seed idempotente
146
- migrations/NNN-descricao.sql histórico de ALTER aplicado manualmente em banco existente
147
- output/build.sql gerado; não editar
148
- tools/ (opcional) comparação de bancos, só leitura
149
+ bootstrap/00-create-db.sql CREATE ROLE <app> + CREATE DATABASE <app> + REVOKE CONNECT FROM PUBLIC;
150
+ senha só por variável do psql (:'role_password'), nunca literal
151
+ delete/reset.sql DROP SCHEMA IF EXISTS <schemas> CASCADE — só com --reset (dev/homol/CI)
152
+ create/<schema>/NN-*.sql forma FINAL das tabelas (CREATE TABLE sem IF NOT EXISTS)
153
+ insert/<schema>/<tabela>.sql seed idempotente, um arquivo por tabela
154
+ migrations/NNN-descricao.sql histórico de ALTER aplicado manualmente (subpasta = DDL de outro banco)
155
+ output/build.sql gerado e versionado (um teste confere que está em dia); não editar
156
+ tools/ sync_from_db.py (regera insert/ de um banco) e compare_db.py (compara dois bancos)
157
+ tests/ pytest sem rede nem banco real; tests/pg = PGlite (Postgres em memória) para os testes de SQL
149
158
  ```
150
159
 
160
+ App novo começa com o schema criado e sem tabela, seed nem migration: os testes compartilhados aceitam isso
161
+ (pulam as checagens que dependem de tabela/migration) e passam a valer a partir da primeira.
162
+
151
163
  Uso:
152
164
 
153
165
  ```bash
@@ -162,7 +174,7 @@ Regras:
162
174
  - `create/` sem `IF NOT EXISTS` (exceto `CREATE SCHEMA`): rodar duas vezes sem `--reset` falha de
163
175
  propósito — impede aplicar create em banco vivo por engano.
164
176
  - **Toda mudança de schema em produção = duas coisas**: editar `create/` para a forma final **e** escrever
165
- `migrations/NNN-*.sql` com o `ALTER` real (cabeçalho com data, dependência e aviso se destrutivo; tudo
177
+ `scripts/migrations/NNN-*.sql` com o `ALTER` real (cabeçalho com data, dependência e aviso se destrutivo; tudo
166
178
  numa transação). `build.py` não aplica migrations.
167
179
  - Seed: `ON CONFLICT ... DO NOTHING` para dado que a UI edita (não sobrescreve); `ON CONFLICT (pk) DO
168
180
  UPDATE` com UUID literal para dado de referência controlado pelo código. Conflito sempre na PK ou numa
@@ -179,7 +191,7 @@ Divergências observadas:
179
191
 
180
192
  | Tema | Visto | Recomendado |
181
193
  |---|---|---|
182
- | Migrations | em `database/migrations/` (2 serviços) vs `server/migrations/` misturando SQL e script Python (1) | `database/migrations/NNN-*.sql`; scripts de dados pontuais em `database/tools/` |
194
+ | Migrations | fora de `database/` ou misturando SQL e script Python | `database/scripts/migrations/NNN-*.sql`; scripts de dados pontuais em `database/tools/` |
183
195
  | `build.py` | versões com e sem `--seed`, relatório de erro e `newline=""` | a versão completa acima |
184
196
  | Seed | `DO NOTHING` por nome vs `DO UPDATE` por PK literal | regra da lista acima |
185
197
  | Commit | no repository (todos) | `flush` no repository, `commit` no service quando a operação tem várias escritas |