@acropole/skills 0.0.0-stage → 1.0.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 +180 -2
- package/agents/revisor-deploy.md +73 -0
- package/agents/revisor-documentacao.md +78 -0
- package/agents/revisor-orfeu.md +80 -0
- package/agents/revisor-trismegisto.md +81 -0
- package/bin/install.js +252 -0
- package/package.json +15 -4
- package/skills/acropole/SKILL.md +75 -0
- package/skills/acropole/references/fluxos/doctor.md +55 -0
- package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
- package/skills/acropole/references/fluxos/revisar.md +56 -0
- package/skills/acropole/references/fluxos/tela-nova.md +27 -0
- package/skills/acropole/scripts/doctor.mjs +439 -0
- package/skills/angular/SKILL.md +152 -0
- package/skills/angular/references/armadilhas.md +95 -0
- package/skills/angular/references/dados.md +251 -0
- package/skills/angular/references/estrutura.md +260 -0
- package/skills/angular/references/features.md +219 -0
- package/skills/angular/references/testes-build.md +230 -0
- package/skills/angular/scripts/checar.mjs +182 -0
- package/skills/angular/scripts/nucleo.mjs +227 -0
- package/skills/apollo/SKILL.md +222 -0
- package/skills/apollo/references/armadilhas.md +95 -0
- package/skills/apollo/references/envelope-erros.md +120 -0
- package/skills/apollo/references/estrutura-bootstrap.md +299 -0
- package/skills/apollo/references/schema-resolvers.md +183 -0
- package/skills/apollo/references/subscriptions.md +224 -0
- package/skills/apollo/references/testes-build.md +180 -0
- package/skills/apollo/scripts/checar.mjs +160 -0
- package/skills/apollo/scripts/nucleo.mjs +227 -0
- package/skills/docker/SKILL.md +102 -0
- package/skills/docker/references/modelos.md +251 -0
- package/skills/docker/references/porques.md +282 -0
- package/skills/documentacao/SKILL.md +146 -0
- package/skills/documentacao/references/checklist-coerencia.md +59 -0
- package/skills/documentacao/references/ligar-app-novo.md +107 -0
- package/skills/documentacao/references/modelo-especificacao.md +51 -0
- package/skills/documentacao/references/modelo-readme.md +75 -0
- package/skills/documentacao/scripts/checar.mjs +454 -0
- package/skills/documentacao/scripts/nucleo.mjs +227 -0
- package/skills/express/SKILL.md +154 -0
- package/skills/express/references/dados.md +180 -0
- package/skills/express/references/estrutura.md +154 -0
- package/skills/express/references/middlewares.md +227 -0
- package/skills/express/references/rotas-erros.md +274 -0
- package/skills/express/references/testes-deploy.md +150 -0
- package/skills/express/scripts/checar.mjs +115 -0
- package/skills/express/scripts/nucleo.mjs +227 -0
- package/skills/fastapi/SKILL.md +129 -0
- package/skills/fastapi/references/banco.md +185 -0
- package/skills/fastapi/references/estrutura.md +281 -0
- package/skills/fastapi/references/integracoes.md +145 -0
- package/skills/fastapi/references/rotas-erros.md +140 -0
- package/skills/fastapi/references/testes-deploy.md +190 -0
- package/skills/fastapi/scripts/checar.mjs +108 -0
- package/skills/fastapi/scripts/nucleo.mjs +227 -0
- package/skills/hefesto/SKILL.md +119 -0
- package/skills/hefesto/references/conceitos.md +131 -0
- package/skills/hefesto/references/diagnostico.md +70 -0
- package/skills/hefesto/references/fluxo.md +122 -0
- package/skills/hefesto/references/preparar-app.md +105 -0
- package/skills/orfeu/SKILL.md +162 -0
- package/skills/orfeu/references/angular-api.md +201 -0
- package/skills/orfeu/references/angular-armadilhas.md +116 -0
- package/skills/orfeu/references/angular-recipes.md +474 -0
- package/skills/orfeu/references/angular.md +212 -0
- package/skills/orfeu/references/diferencas.md +56 -0
- package/skills/orfeu/references/node-api.md +348 -0
- package/skills/orfeu/references/node-armadilhas.md +158 -0
- package/skills/orfeu/references/node-recipes.md +534 -0
- package/skills/orfeu/references/node.md +204 -0
- package/skills/orfeu/references/python-api.md +346 -0
- package/skills/orfeu/references/python-recipes.md +479 -0
- package/skills/orfeu/references/python.md +234 -0
- package/skills/orfeu/scripts/checar.mjs +126 -0
- package/skills/orfeu/scripts/nucleo.mjs +227 -0
- package/skills/trismegisto/SKILL.md +194 -0
- package/skills/trismegisto/references/angular-api.md +2788 -0
- package/skills/trismegisto/references/angular-exports.md +4020 -0
- package/skills/trismegisto/references/angular-recipes.md +1883 -0
- package/skills/trismegisto/references/angular-types.md +492 -0
- package/skills/trismegisto/references/angular.md +390 -0
- package/skills/trismegisto/references/catalogo/icones.json +912 -0
- package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
- package/skills/trismegisto/references/catalogo/tokens.json +240 -0
- package/skills/trismegisto/references/spine-api.md +1530 -0
- package/skills/trismegisto/references/spine-recipes.md +581 -0
- package/skills/trismegisto/references/spine.md +343 -0
- package/skills/trismegisto/scripts/checar.mjs +216 -0
- package/skills/trismegisto/scripts/nucleo.mjs +227 -0
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# Logs, health, shutdown, testes e Docker
|
|
2
|
+
|
|
3
|
+
## Logger
|
|
4
|
+
|
|
5
|
+
Logger mínimo, sem dependência pesada: JSON de uma linha em produção (lido pela stack de logs),
|
|
6
|
+
colorido em dev.
|
|
7
|
+
|
|
8
|
+
```ts
|
|
9
|
+
type Ctx = Record<string, unknown>;
|
|
10
|
+
const isDev = process.env.NODE_ENV === 'dev' || process.env.NODE_ENV === 'local';
|
|
11
|
+
|
|
12
|
+
function write(level: 'info' | 'warn' | 'error', msg: string, ctx?: Ctx) {
|
|
13
|
+
const entry = { time: new Date().toISOString(), level, msg, ...ctx };
|
|
14
|
+
if (isDev) console.log(`[${entry.time}] ${level.toUpperCase()} | ${msg}${ctx ? ' ' + JSON.stringify(ctx) : ''}`);
|
|
15
|
+
else console.log(JSON.stringify(entry));
|
|
16
|
+
}
|
|
17
|
+
export const Logger = {
|
|
18
|
+
info: (m: string, c?: Ctx) => write('info', m, c),
|
|
19
|
+
warn: (m: string, c?: Ctx) => write('warn', m, c),
|
|
20
|
+
error: (m: string, c?: Ctx) => write('error', m, c),
|
|
21
|
+
};
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
- Contexto estruturado (`{ requestId, port }`), nunca concatenado na mensagem.
|
|
25
|
+
- O Orfeu já emite uma linha JSON por operação protegida (com `trace_id`) — não duplique esse log no
|
|
26
|
+
controller. Ver orfeu.
|
|
27
|
+
- Proibido logar: tokens, segredos, senhas, códigos de MFA, corpo de requisição de autenticação.
|
|
28
|
+
- Instrumentação de performance opcional por env (ex.: `GQL_PERF=1` ou limiar em ms): mede com
|
|
29
|
+
`performance.now()` e só loga acima do limiar — custo quase zero desligada.
|
|
30
|
+
|
|
31
|
+
## Health check
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
router.get('/health', async (_req, res) => {
|
|
35
|
+
const [pg, redis] = await Promise.allSettled([db.raw('SELECT 1'), cache.ping()]);
|
|
36
|
+
const postgres = pg.status === 'fulfilled' ? 'ok' : 'error';
|
|
37
|
+
const cacheSt = redis.status === 'fulfilled' ? 'ok' : 'error';
|
|
38
|
+
const status = postgres === 'ok' && cacheSt === 'ok' ? 'ok' : 'degraded';
|
|
39
|
+
res.status(status === 'ok' ? 200 : 503).json({ status, postgres, redis: cacheSt });
|
|
40
|
+
});
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
- Fica sob o prefixo da API, **sem** guard e antes dos namespaces protegidos.
|
|
44
|
+
- Cheque só o que o processo realmente usa (um serviço sem Redis não pinga Redis).
|
|
45
|
+
- Gateway que só repassa: `{ ok: true }` basta (saúde dos serviços de trás é deles).
|
|
46
|
+
- Não exponha versões, hosts ou mensagens de erro do banco.
|
|
47
|
+
|
|
48
|
+
## Graceful shutdown
|
|
49
|
+
|
|
50
|
+
```ts
|
|
51
|
+
for (const [sig, code] of [['SIGTERM', 143], ['SIGINT', 130]] as const) {
|
|
52
|
+
process.once(sig, async () => {
|
|
53
|
+
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));
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
- `flushAudit()` de **cada** `OrfeuClient` instanciado (`Promise.allSettled`).
|
|
62
|
+
- Com Apollo, `ApolloServerPluginDrainHttpServer` + dispose do servidor WebSocket (apollo).
|
|
63
|
+
- Feche também pool do Knex (`db.destroy()`) e Redis (`quit()`) se o encerramento puder demorar.
|
|
64
|
+
- Timer menor que o `stop timeout` do orquestrador (padrão 10 s).
|
|
65
|
+
- **Não** registre `process.on('uncaughtException', log)` que mantém o processo vivo; se registrar,
|
|
66
|
+
logue e `process.exit(1)`.
|
|
67
|
+
|
|
68
|
+
## Testes
|
|
69
|
+
|
|
70
|
+
Estado real: os servidores Express não têm suíte automatizada; há **smoke tests** em `scripts/` que
|
|
71
|
+
sobem os mesmos controllers num Express efêmero contra um banco de ambiente local, sem o guard
|
|
72
|
+
(autorização testada à parte):
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
const app = express();
|
|
76
|
+
const r = express.Router();
|
|
77
|
+
r.get('/events', AuditController.listEvents);
|
|
78
|
+
app.use('/audit', r);
|
|
79
|
+
app.use((err: any, _req: any, res: any, _next: any) => res.status(500).json({ error: err.message }));
|
|
80
|
+
|
|
81
|
+
const server = app.listen(0); // porta efêmera
|
|
82
|
+
const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
|
|
83
|
+
const r1 = await fetch(`${base}/audit/events?limit=2`);
|
|
84
|
+
check('lista pagina', r1.status === 200 && (await r1.json()).items.length <= 2);
|
|
85
|
+
// ... ao final: server.close(); await db.destroy(); process.exit(failures ? 1 : 0);
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Recomendado para código novo:
|
|
89
|
+
|
|
90
|
+
- `node:test` (ou vitest) + `supertest` contra o `app` exportado **sem** `listen` — por isso separe
|
|
91
|
+
"criar app" de "escutar porta".
|
|
92
|
+
- Repositórios contra Postgres real descartável (container), não mock de Knex.
|
|
93
|
+
- Validators zod testados isoladamente; casos de erro (400/401/403/404/409) por rota.
|
|
94
|
+
- Guard do Orfeu: em teste de unidade de controller, monte o router sem o guard; o comportamento de
|
|
95
|
+
autorização é coberto pelo próprio SDK.
|
|
96
|
+
|
|
97
|
+
## Docker
|
|
98
|
+
|
|
99
|
+
Multi-stage, `npm ci` com cache, `npm prune --omit=dev`, runtime enxuto, `node` como PID 1:
|
|
100
|
+
|
|
101
|
+
```dockerfile
|
|
102
|
+
FROM node:22-alpine AS build
|
|
103
|
+
WORKDIR /app
|
|
104
|
+
COPY package.json package-lock.json ./
|
|
105
|
+
RUN --mount=type=cache,target=/root/.npm,sharing=locked \
|
|
106
|
+
timeout -k 10 600 npm ci --no-audit --no-fund
|
|
107
|
+
COPY tsconfig.json ./
|
|
108
|
+
COPY src ./src
|
|
109
|
+
RUN timeout -k 10 300 npm run build \
|
|
110
|
+
&& npm prune --omit=dev --no-audit --no-fund \
|
|
111
|
+
&& find node_modules -type f \( -name '*.d.ts' -o -name '*.map' -o -name '*.md' \) ! -iname 'LICENSE*' -delete \
|
|
112
|
+
&& rm -rf node_modules/@types
|
|
113
|
+
|
|
114
|
+
FROM node:22-alpine
|
|
115
|
+
RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/corepack \
|
|
116
|
+
/usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack
|
|
117
|
+
WORKDIR /app
|
|
118
|
+
COPY --from=build /app/package.json ./
|
|
119
|
+
COPY --from=build /app/node_modules ./node_modules
|
|
120
|
+
COPY --from=build /app/dist ./dist
|
|
121
|
+
ENV NODE_ENV=prod
|
|
122
|
+
EXPOSE 3000
|
|
123
|
+
CMD ["node", "dist/index.js"]
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
- `timeout` em cada passo que baixa/compila: alguns builders só cancelam no passo seguinte e um
|
|
127
|
+
`npm ci` travado fica rodando no host.
|
|
128
|
+
- Limpeza do `node_modules` **por tipo de arquivo**, nunca por nome de pasta (há código de runtime em
|
|
129
|
+
pastas chamadas `docs`/`test`).
|
|
130
|
+
- SPA na mesma imagem: um estágio `ui-build` que gera o `dist` do Angular e
|
|
131
|
+
`ENV UI_STATIC_PATH=…`/`UI_BASE_PATH=…` no runtime.
|
|
132
|
+
- Usando `tsconfig-paths` em runtime: copie o `tsconfig.json` e defina `TS_NODE_BASEURL=./dist`.
|
|
133
|
+
- Segredos entram por env/secret do orquestrador, nunca em `ENV` do Dockerfile nem copiados na imagem.
|
|
134
|
+
|
|
135
|
+
## Armadilhas reais (consolidado)
|
|
136
|
+
|
|
137
|
+
| Sintoma | Causa | Correção |
|
|
138
|
+
| --- | --- | --- |
|
|
139
|
+
| Corpo > 100 KB dá 413 apesar de `limit: '10mb'` | dois `bodyParser.json()`, o primeiro sem limite | um parser só, com o limite |
|
|
140
|
+
| SPA servida pelo próprio processo devolve 500 nos bundles | CORS global + `Origin` de scripts ESM | CORS só no prefixo da API |
|
|
141
|
+
| POST do login bloqueado por CORS atrás do balanceador | `Origin` same-origin não está na allowlist | aceitar same-origin via `X-Forwarded-Host`/`Host` |
|
|
142
|
+
| `req.protocol` sempre `http` atrás do proxy | falta `trust proxy` | `app.set('trust proxy', true)` |
|
|
143
|
+
| `app.get('*')` quebra ao subir | Express 5 / path-to-regexp novo | `'/*splat'` + rota da raiz separada |
|
|
144
|
+
| Handler async lança e a requisição fica pendurada | Express 4 não captura promise rejeitada | Express 5, ou `try/catch`/wrapper |
|
|
145
|
+
| `req.params.x` undefined no sub-router | falta `mergeParams` | `Router({ mergeParams: true })` |
|
|
146
|
+
| Deploy espera 10 s e perde auditoria | `CMD npm start` / sem handler de SIGTERM | `CMD ["node", …]` + shutdown |
|
|
147
|
+
| Primeira query após ociosidade trava ~20 s | conexão do pool morta por NAT/firewall | `keepAlive` no driver |
|
|
148
|
+
| Imports por alias quebram só no container | `tsconfig-paths` resolvendo para `src` | `TS_NODE_BASEURL=./dist` ou resolver no build |
|
|
149
|
+
| Middleware de header derruba tudo no cold start | consulta ao banco sem `catch` | `.catch(() => valorRestritivo)` |
|
|
150
|
+
| Validação passa mas controller recebe string em vez de número | `validate()` descarta o resultado do zod | atribuir `result.data` a `req.body` |
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Verificador da skill `express`: armadilhas de servidores Express.
|
|
3
|
+
// node checar.mjs [caminhos...] [--json] (instalado: ~/.claude/skills/express/scripts/checar.mjs)
|
|
4
|
+
// Exceção: `// acropole-ignore-next-line <regra> -- motivo` na linha anterior.
|
|
5
|
+
// (Rota sem guard é do verificador da skill `orfeu`; Dockerfile/CMD é da skill `docker`.)
|
|
6
|
+
import fs from 'node:fs';
|
|
7
|
+
import path from 'node:path';
|
|
8
|
+
import { executar } from './nucleo.mjs';
|
|
9
|
+
|
|
10
|
+
const JS = ['.ts', '.js', '.mjs', '.cjs', '.mts', '.cts'];
|
|
11
|
+
const ehCodigo = (a) => JS.includes(a.ext) && !/\.(spec|test)\.[cm]?[jt]s$/.test(a.nome);
|
|
12
|
+
|
|
13
|
+
/** Versão de `express` declarada no package.json mais próximo do arquivo (ou null). */
|
|
14
|
+
const versoes = new Map();
|
|
15
|
+
function versaoExpress(arquivo) {
|
|
16
|
+
let dir = path.dirname(arquivo);
|
|
17
|
+
for (;;) {
|
|
18
|
+
if (versoes.has(dir)) return versoes.get(dir);
|
|
19
|
+
const pj = path.join(dir, 'package.json');
|
|
20
|
+
if (fs.existsSync(pj)) {
|
|
21
|
+
let v = null;
|
|
22
|
+
try {
|
|
23
|
+
const p = JSON.parse(fs.readFileSync(pj, 'utf8'));
|
|
24
|
+
v = p.dependencies?.express ?? p.devDependencies?.express ?? null;
|
|
25
|
+
} catch {
|
|
26
|
+
/* package.json inválido: sem versão */
|
|
27
|
+
}
|
|
28
|
+
versoes.set(dir, v);
|
|
29
|
+
return v;
|
|
30
|
+
}
|
|
31
|
+
const pai = path.dirname(dir);
|
|
32
|
+
if (pai === dir) return null;
|
|
33
|
+
dir = pai;
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
const regras = [
|
|
38
|
+
{
|
|
39
|
+
id: 'json-parser-duplicado',
|
|
40
|
+
resumo: 'mais de um parser JSON (express.json/bodyParser.json) no mesmo arquivo',
|
|
41
|
+
aceita: ehCodigo,
|
|
42
|
+
checar(arq) {
|
|
43
|
+
const todos = [...arq.limpo.matchAll(/\b(?:express|bodyParser)\s*\.\s*json\s*\(/g)];
|
|
44
|
+
return todos.slice(1).map((m) => ({
|
|
45
|
+
linha: arq.linhaDe(m.index),
|
|
46
|
+
mensagem: `parser JSON registrado de novo (o primeiro está na linha ${arq.linhaDe(todos[0].index)}): ele consome o corpo e o \`limit\` deste nunca vale`,
|
|
47
|
+
correcao: "registre um só: `app.use(express.json({ limit: '10mb' }))`",
|
|
48
|
+
}));
|
|
49
|
+
},
|
|
50
|
+
},
|
|
51
|
+
{
|
|
52
|
+
id: 'cors-global',
|
|
53
|
+
resumo: 'CORS aplicado no app inteiro em vez de só no prefixo da API',
|
|
54
|
+
aceita: ehCodigo,
|
|
55
|
+
checar: (arq) =>
|
|
56
|
+
[...arq.limpo.matchAll(/\bapp\s*\.\s*use\(\s*cors\w*\s*[(),]/g)].map((m) => ({
|
|
57
|
+
linha: arq.linhaDe(m.index),
|
|
58
|
+
mensagem: 'CORS global: quebra a SPA servida pelo mesmo processo (script `type="module"` manda `Origin` em same-origin)',
|
|
59
|
+
correcao: 'aplique só no prefixo: `app.use(settings.API_PREFIX, corsMiddleware, router)`',
|
|
60
|
+
})),
|
|
61
|
+
},
|
|
62
|
+
{
|
|
63
|
+
id: 'coringa-express5',
|
|
64
|
+
resumo: "rota '*' no Express 5 (não existe mais; use '/*splat')",
|
|
65
|
+
aceita: (a) => ehCodigo(a) && /^\D*5/.test(versaoExpress(a.caminho) ?? ''),
|
|
66
|
+
checar: (arq) =>
|
|
67
|
+
[...arq.limpo.matchAll(/\.\s*(?:get|use|all)\(\s*['"`](\/?\*)['"`]/g)].map((m) => ({
|
|
68
|
+
linha: arq.linhaDe(m.index),
|
|
69
|
+
mensagem: `caminho \`'${m[1]}'\`: no Express 5 (path-to-regexp 8) o coringa sem nome lança erro na subida`,
|
|
70
|
+
correcao: "use `'/*splat'` (e trate a raiz do prefixo à parte)",
|
|
71
|
+
})),
|
|
72
|
+
},
|
|
73
|
+
{
|
|
74
|
+
id: 'ordenacao-objeto-literal',
|
|
75
|
+
resumo: 'allowlist de ordenação em objeto literal lida com chave variável (`constructor` passa)',
|
|
76
|
+
aceita: (a) => ehCodigo(a) && versaoExpress(a.caminho) !== null,
|
|
77
|
+
checar(arq) {
|
|
78
|
+
const t = arq.limpo;
|
|
79
|
+
// Objetos literais com nome de ordenação: `const SORT_COLUMNS = {`, `static readonly ORDER_BY: X = {`.
|
|
80
|
+
const nomes = new Set();
|
|
81
|
+
const decl = /(?:\b(?:const|let|var)[ \t]+|^[ \t]*(?:(?:private|public|protected|static|readonly)[ \t]+)+)([A-Za-z_$][\w$]*)[ \t]*(?::[^=\n]+)?=[ \t]*(?:Object\.freeze\(\s*)?\{/gm;
|
|
82
|
+
for (const m of t.matchAll(decl)) if (/sort|order|ordena/i.test(m[1])) nomes.add(m[1]);
|
|
83
|
+
const out = [];
|
|
84
|
+
for (const nome of nomes) {
|
|
85
|
+
const n = nome.replace(/\$/g, '\\$');
|
|
86
|
+
// Já conferido com hasOwn em algum ponto do arquivo: confia.
|
|
87
|
+
if (new RegExp(`Object\\.hasOwn\\(\\s*(?:[\\w$]+\\.)*${n}\\b|\\b${n}\\s*\\.\\s*hasOwnProperty\\(|hasOwnProperty\\.call\\(\\s*(?:[\\w$]+\\.)*${n}\\b`).test(t)) continue;
|
|
88
|
+
const achar = (idx) =>
|
|
89
|
+
out.push({
|
|
90
|
+
linha: arq.linhaDe(idx),
|
|
91
|
+
mensagem: `\`${nome}\` é objeto literal: \`${nome}[x]\`/\`x in ${nome}\` aceitam chaves do protótipo (\`constructor\`, \`toString\`, \`__proto__\`) e furam a allowlist`,
|
|
92
|
+
correcao: 'use `new Map([...])` + `.get(x)` (ou confira `Object.hasOwn(obj, x)` antes de ler) — references/rotas-erros.md',
|
|
93
|
+
});
|
|
94
|
+
// NOME[expr] com expr que não é string literal nem posição de tipo (keyof/typeof/number)
|
|
95
|
+
for (const m of t.matchAll(new RegExp(`(?<![\\w$])${n}\\s*\\[\\s*([^\\]]+)\\]`, 'g'))) {
|
|
96
|
+
const expr = m[1].trim();
|
|
97
|
+
if (/^(['"`])[^'"`]*\1$/.test(expr) || /^(?:keyof|typeof|number\b)/.test(expr)) continue;
|
|
98
|
+
achar(m.index);
|
|
99
|
+
}
|
|
100
|
+
// `x in NOME` (fora de `for (const x in NOME)`)
|
|
101
|
+
for (const m of t.matchAll(new RegExp(`(?<!(?:const|let|var)\\s+)(?<![\\w$.'"\`])[\\w$][\\w$.?]*\\s+in\\s+(?:[\\w$]+\\.)*${n}(?![\\w$])`, 'g'))) {
|
|
102
|
+
achar(m.index);
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
return out;
|
|
106
|
+
},
|
|
107
|
+
},
|
|
108
|
+
];
|
|
109
|
+
|
|
110
|
+
process.exitCode = executar({
|
|
111
|
+
skill: 'express',
|
|
112
|
+
descricao: 'parser JSON duplicado, CORS global, coringa antigo no Express 5 e allowlist de ordenação em objeto literal.',
|
|
113
|
+
regras,
|
|
114
|
+
extensoes: JS,
|
|
115
|
+
});
|
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
// Núcleo dos verificadores das skills (`skills/<skill>/scripts/checar.mjs`). Sem dependências, só Node ≥ 18.
|
|
2
|
+
// FONTE ÚNICA: este arquivo é copiado para `skills/<skill>/scripts/nucleo.mjs` pelo `npm run sync`
|
|
3
|
+
// (cada skill é instalada sozinha, então leva a própria cópia). Edite aqui, nunca a cópia.
|
|
4
|
+
//
|
|
5
|
+
// Uso (pelo checar.mjs de cada skill): node checar.mjs [caminhos...] [--json]
|
|
6
|
+
// sem caminhos: a pasta atual (ignora node_modules, dist, .angular, .git, venvs e caches).
|
|
7
|
+
// saída: `arquivo:linha regra mensagem → correção`; código de saída 1 se achar algo.
|
|
8
|
+
// Exceção pontual, na linha ANTERIOR, em comentário da linguagem:
|
|
9
|
+
// // acropole-ignore-next-line <regra>[,<regra>] -- motivo
|
|
10
|
+
// Sem motivo depois de `--`, a exceção não vale.
|
|
11
|
+
import fs from 'node:fs';
|
|
12
|
+
import path from 'node:path';
|
|
13
|
+
|
|
14
|
+
const PASTAS_IGNORADAS = new Set(['node_modules', 'dist', '.angular', '.git', '.venv', 'venv', '__pycache__', '.pytest_cache', '.mypy_cache', 'coverage', '.nx', '.turbo']);
|
|
15
|
+
|
|
16
|
+
const C_LIKE = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts', '.scss', '.less']);
|
|
17
|
+
|
|
18
|
+
/** Troca cada caractere (menos quebras de linha) de `s[a..b)` por espaço. */
|
|
19
|
+
function apagar(chars, a, b) {
|
|
20
|
+
for (let i = a; i < b; i++) if (chars[i] !== '\n') chars[i] = ' ';
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** Texto com os comentários apagados (mesmo tamanho, mesmas linhas). Strings ficam. */
|
|
24
|
+
export function semComentarios(texto, ext) {
|
|
25
|
+
const c = texto.split('');
|
|
26
|
+
const n = texto.length;
|
|
27
|
+
if (ext === '.html' || ext === '.htm') {
|
|
28
|
+
for (const m of texto.matchAll(/<!--[\s\S]*?(-->|$)/g)) apagar(c, m.index, m.index + m[0].length);
|
|
29
|
+
return c.join('');
|
|
30
|
+
}
|
|
31
|
+
if (ext === '.py') {
|
|
32
|
+
for (let i = 0; i < n; i++) {
|
|
33
|
+
const ch = texto[i];
|
|
34
|
+
if (ch === '#') {
|
|
35
|
+
const fim = texto.indexOf('\n', i);
|
|
36
|
+
apagar(c, i, fim < 0 ? n : fim);
|
|
37
|
+
i = fim < 0 ? n : fim;
|
|
38
|
+
} else if (ch === '"' || ch === "'") {
|
|
39
|
+
const triplo = texto.startsWith(ch.repeat(3), i);
|
|
40
|
+
const fecha = triplo ? ch.repeat(3) : ch;
|
|
41
|
+
let j = i + fecha.length;
|
|
42
|
+
while (j < n && !texto.startsWith(fecha, j)) {
|
|
43
|
+
if (texto[j] === '\\') j++;
|
|
44
|
+
else if (!triplo && texto[j] === '\n') break;
|
|
45
|
+
j++;
|
|
46
|
+
}
|
|
47
|
+
i = j + fecha.length - 1;
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
return c.join('');
|
|
51
|
+
}
|
|
52
|
+
const barraDupla = C_LIKE.has(ext); // .css puro só tem /* */
|
|
53
|
+
for (let i = 0; i < n; i++) {
|
|
54
|
+
const ch = texto[i];
|
|
55
|
+
if (ch === '/' && texto[i + 1] === '*') {
|
|
56
|
+
const fim = texto.indexOf('*/', i + 2);
|
|
57
|
+
const f = fim < 0 ? n : fim + 2;
|
|
58
|
+
apagar(c, i, f);
|
|
59
|
+
i = f - 1;
|
|
60
|
+
} else if (barraDupla && ch === '/' && texto[i + 1] === '/' && texto[i - 1] !== ':') {
|
|
61
|
+
const fim = texto.indexOf('\n', i);
|
|
62
|
+
apagar(c, i, fim < 0 ? n : fim);
|
|
63
|
+
i = fim < 0 ? n : fim;
|
|
64
|
+
} else if (ch === '"' || ch === "'" || ch === '`') {
|
|
65
|
+
let j = i + 1;
|
|
66
|
+
while (j < n && texto[j] !== ch) {
|
|
67
|
+
if (texto[j] === '\\') j++;
|
|
68
|
+
else if (ch !== '`' && texto[j] === '\n') break;
|
|
69
|
+
j++;
|
|
70
|
+
}
|
|
71
|
+
i = j;
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
let out = c.join('');
|
|
75
|
+
// Comentário HTML dentro de template inline.
|
|
76
|
+
if (ext === '.ts') out = out.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' '));
|
|
77
|
+
return out;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Monta o objeto de arquivo que as regras recebem. */
|
|
81
|
+
export function lerArquivo(caminho, rel, raiz = path.dirname(caminho)) {
|
|
82
|
+
const texto = fs.readFileSync(caminho, 'utf8').replace(/\r\n?/g, '\n');
|
|
83
|
+
const ext = path.extname(caminho).toLowerCase();
|
|
84
|
+
const inicios = [0];
|
|
85
|
+
for (let i = 0; i < texto.length; i++) if (texto[i] === '\n') inicios.push(i + 1);
|
|
86
|
+
const linhaDe = (idx) => {
|
|
87
|
+
let lo = 0;
|
|
88
|
+
let hi = inicios.length - 1;
|
|
89
|
+
while (lo < hi) {
|
|
90
|
+
const mid = (lo + hi + 1) >> 1;
|
|
91
|
+
if (inicios[mid] <= idx) lo = mid;
|
|
92
|
+
else hi = mid - 1;
|
|
93
|
+
}
|
|
94
|
+
return lo + 1;
|
|
95
|
+
};
|
|
96
|
+
// relRaiz: relativo ao caminho pedido na linha de comando (para regras que olham pastas, ex.: tests/).
|
|
97
|
+
const relRaiz = path.relative(raiz, caminho).split(path.sep).join('/') || path.basename(caminho);
|
|
98
|
+
return { caminho, rel, relRaiz, ext, nome: path.basename(caminho), texto, limpo: semComentarios(texto, ext), linhaDe };
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** Trechos de template HTML: o arquivo `.html` inteiro ou `template: \`...\`` de um `.ts`. `{ texto, inicio }`. */
|
|
102
|
+
export function templates(arq) {
|
|
103
|
+
if (arq.ext === '.html') return [{ texto: arq.limpo, inicio: 0 }];
|
|
104
|
+
if (arq.ext !== '.ts') return [];
|
|
105
|
+
const out = [];
|
|
106
|
+
for (const m of arq.limpo.matchAll(/\btemplate\s*:\s*`/g)) {
|
|
107
|
+
const ini = m.index + m[0].length;
|
|
108
|
+
const fim = arq.limpo.indexOf('`', ini);
|
|
109
|
+
if (fim > ini) out.push({ texto: arq.limpo.slice(ini, fim), inicio: ini });
|
|
110
|
+
}
|
|
111
|
+
return out;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** Trechos de CSS: `.css`/`.scss` inteiros ou `styles: \`...\`` / `styles: [\`...\`]` de um `.ts`. */
|
|
115
|
+
export function estilos(arq) {
|
|
116
|
+
if (arq.ext === '.css' || arq.ext === '.scss' || arq.ext === '.less') return [{ texto: arq.limpo, inicio: 0 }];
|
|
117
|
+
if (arq.ext !== '.ts') return [];
|
|
118
|
+
const out = [];
|
|
119
|
+
for (const m of arq.limpo.matchAll(/\bstyles\s*:\s*\[?/g)) {
|
|
120
|
+
let i = m.index + m[0].length;
|
|
121
|
+
for (;;) {
|
|
122
|
+
while (/[\s,]/.test(arq.limpo[i] ?? '')) i++;
|
|
123
|
+
const q = arq.limpo[i];
|
|
124
|
+
if (q !== '`' && q !== "'" && q !== '"') break;
|
|
125
|
+
const fim = arq.limpo.indexOf(q, i + 1);
|
|
126
|
+
if (fim < 0) break;
|
|
127
|
+
// O conteúdo da string é CSS: apaga os /* */ dele.
|
|
128
|
+
out.push({ texto: semComentarios(arq.limpo.slice(i + 1, fim), '.css'), inicio: i + 1 });
|
|
129
|
+
i = fim + 1;
|
|
130
|
+
if (arq.limpo[m.index + m[0].length - 1] !== '[') break;
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
return out;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** Lista os arquivos a verificar: `[{ caminho, raiz }]` (raiz = o caminho pedido que o contém). */
|
|
137
|
+
export function listarArquivos(caminhos, cwd, aceita) {
|
|
138
|
+
const out = new Map();
|
|
139
|
+
let raiz = '';
|
|
140
|
+
const visitar = (p, explicito) => {
|
|
141
|
+
let st;
|
|
142
|
+
try {
|
|
143
|
+
st = fs.statSync(p);
|
|
144
|
+
} catch {
|
|
145
|
+
throw new Error(`caminho não encontrado: ${p}`);
|
|
146
|
+
}
|
|
147
|
+
if (st.isDirectory()) {
|
|
148
|
+
if (!explicito && PASTAS_IGNORADAS.has(path.basename(p))) return;
|
|
149
|
+
if (explicito) raiz = p;
|
|
150
|
+
for (const e of fs.readdirSync(p).sort()) visitar(path.join(p, e), false);
|
|
151
|
+
} else if ((explicito || aceita(p)) && !out.has(p)) out.set(p, explicito ? path.dirname(p) : raiz);
|
|
152
|
+
};
|
|
153
|
+
for (const c of caminhos.length ? caminhos : ['.']) visitar(path.resolve(cwd, c), true);
|
|
154
|
+
return [...out].filter(([p]) => aceita(p)).map(([caminho, r]) => ({ caminho, raiz: r }));
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
const IGNORE = /acropole-ignore-next-line\s+([\w,-]+)(?:\s+--(.*?))?\s*(?:\*\/|-->)?\s*$/;
|
|
158
|
+
|
|
159
|
+
/** Exceção declarada na linha anterior: `{ regras: Set, motivo }` ou null. */
|
|
160
|
+
function excecao(arq, linha) {
|
|
161
|
+
const anterior = arq.texto.split('\n')[linha - 2];
|
|
162
|
+
const m = anterior && anterior.match(IGNORE);
|
|
163
|
+
if (!m) return null;
|
|
164
|
+
return { regras: new Set(m[1].split(',').filter(Boolean)), motivo: (m[2] ?? '').trim() };
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* Roda as regras. `regras`: `[{ id, aceita(arq) => bool, checar(arq, ctx) => [{ linha, mensagem, correcao }] }]`.
|
|
169
|
+
* `preparar(arquivos, ctx)` opcional roda antes, com todos os arquivos lidos (ex.: coletar declarações).
|
|
170
|
+
*/
|
|
171
|
+
export function verificar({ regras, caminhos = [], cwd = process.cwd(), extensoes, preparar }) {
|
|
172
|
+
const aceita = (p) => extensoes.includes(path.extname(p).toLowerCase()) || extensoes.includes(path.basename(p));
|
|
173
|
+
const arquivos = listarArquivos(caminhos, cwd, aceita).map(({ caminho, raiz }) =>
|
|
174
|
+
lerArquivo(caminho, path.relative(cwd, caminho).split(path.sep).join('/') || path.basename(caminho), raiz),
|
|
175
|
+
);
|
|
176
|
+
const ctx = {};
|
|
177
|
+
if (preparar) preparar(arquivos, ctx);
|
|
178
|
+
const achados = [];
|
|
179
|
+
for (const arq of arquivos) {
|
|
180
|
+
for (const regra of regras) {
|
|
181
|
+
if (regra.aceita && !regra.aceita(arq)) continue;
|
|
182
|
+
for (const a of regra.checar(arq, ctx) ?? []) {
|
|
183
|
+
const exc = excecao(arq, a.linha);
|
|
184
|
+
let correcao = a.correcao;
|
|
185
|
+
if (exc && exc.regras.has(regra.id)) {
|
|
186
|
+
if (exc.motivo) continue;
|
|
187
|
+
correcao += ' (a exceção acropole-ignore-next-line precisa de motivo depois de "--")';
|
|
188
|
+
}
|
|
189
|
+
achados.push({ arquivo: arq.rel, linha: a.linha, regra: regra.id, mensagem: a.mensagem, correcao });
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
achados.sort((a, b) => (a.arquivo < b.arquivo ? -1 : a.arquivo > b.arquivo ? 1 : a.linha - b.linha || (a.regra < b.regra ? -1 : 1)));
|
|
194
|
+
// Mesmo achado duas vezes na mesma linha (ex.: duas cores) vira um só por regra+mensagem.
|
|
195
|
+
const unicos = [...new Map(achados.map((a) => [`${a.arquivo}:${a.linha}:${a.regra}:${a.mensagem}`, a])).values()];
|
|
196
|
+
return { arquivos: arquivos.length, achados: unicos };
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/** Ponto de entrada dos checar.mjs: lê argv, imprime e define o código de saída. */
|
|
200
|
+
export function executar({ skill, descricao, regras, extensoes, preparar, argv = process.argv.slice(2) }) {
|
|
201
|
+
if (argv.includes('--help') || argv.includes('-h')) {
|
|
202
|
+
console.log(`Verificador da skill ${skill}: ${descricao}
|
|
203
|
+
|
|
204
|
+
Uso: node checar.mjs [caminhos...] [--json]
|
|
205
|
+
sem caminhos, verifica a pasta atual (ignora node_modules, dist, .angular...).
|
|
206
|
+
Exceção (linha anterior, em comentário): acropole-ignore-next-line <regra> -- motivo
|
|
207
|
+
|
|
208
|
+
Regras:
|
|
209
|
+
${regras.map((r) => ` ${r.id.padEnd(28)} ${r.resumo}`).join('\n')}`);
|
|
210
|
+
return 0;
|
|
211
|
+
}
|
|
212
|
+
const json = argv.includes('--json');
|
|
213
|
+
const caminhos = argv.filter((a) => a !== '--json');
|
|
214
|
+
let r;
|
|
215
|
+
try {
|
|
216
|
+
r = verificar({ regras, caminhos, extensoes, preparar });
|
|
217
|
+
} catch (e) {
|
|
218
|
+
console.error(`checar (${skill}): ${e.message}`);
|
|
219
|
+
return 2;
|
|
220
|
+
}
|
|
221
|
+
if (json) console.log(JSON.stringify({ skill, arquivos: r.arquivos, achados: r.achados }, null, 2));
|
|
222
|
+
else {
|
|
223
|
+
for (const a of r.achados) console.log(`${a.arquivo}:${a.linha} ${a.regra} ${a.mensagem} → ${a.correcao}`);
|
|
224
|
+
console.log(r.achados.length ? `\n${r.achados.length} problema(s) em ${r.arquivos} arquivo(s) verificado(s).` : `Nada encontrado (${r.arquivos} arquivo(s) verificado(s)).`);
|
|
225
|
+
}
|
|
226
|
+
return r.achados.length ? 1 : 0;
|
|
227
|
+
}
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: fastapi
|
|
3
|
+
description: "Serviços Python com FastAPI da plataforma: domínios router/service/repository, settings por ambiente, SQLAlchemy síncrono + Postgres, envelope de resposta, banco por scripts SQL, chamadas a outros serviços e testes pytest. Use ao criar, alterar, revisar ou testar rota, regra, acesso a banco ou integração de um backend FastAPI. Semântica de @operation/Level/Method e orfeu_headers é da skill orfeu; serviço Node é da express; Dockerfile é da docker."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# fastapi
|
|
7
|
+
|
|
8
|
+
Serviços Python do ecossistema Acrópole: uma API FastAPI por projeto, chamada pelo gateway GraphQL
|
|
9
|
+
(ver **apollo**), protegida e auditada pelo SDK Orfeu (ver **orfeu**). Esta skill cobre
|
|
10
|
+
o *esqueleto* do serviço; detalhes do SDK (níveis, métodos, claims, `orfeu_headers`, auditoria) ficam na
|
|
11
|
+
orfeu — não duplique aqui.
|
|
12
|
+
|
|
13
|
+
> Ainda não coberto pelo padrão: Strawberry, Django e Flask (o Orfeu tem adapters para eles, mas não há
|
|
14
|
+
> serviço de referência). Para serviços Node use **express**.
|
|
15
|
+
|
|
16
|
+
> **Antes de dar por terminado:** `node scripts/checar.mjs <arquivos alterados>` (caminho relativo a esta skill: instalada, fica em `~/.claude/skills/fastapi/scripts/checar.mjs`; `--help` lista as regras, `--json` para máquina).
|
|
17
|
+
|
|
18
|
+
## Regras essenciais
|
|
19
|
+
|
|
20
|
+
1. **Python ≥ 3.11** (piso do `orfeu` e da imagem `python:3.11-slim`). FastAPI recente (≥ 0.142) e
|
|
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`.
|
|
26
|
+
3. **Estrutura por domínio**: `src/app/domains/<domínio>/{router,schemas,service,repository,models}.py`.
|
|
27
|
+
Router fino → service (regra, levanta erros do Orfeu, não conhece HTTP) → repository (SQLAlchemy, sem
|
|
28
|
+
regra). Um domínio usa outro **só pelo service**. Ver [references/estrutura.md](references/estrutura.md).
|
|
29
|
+
4. **Bootstrap**: `get_application()` em `src/main.py` cria o app com `lifespan` (abre banco/Redis,
|
|
30
|
+
inicia tarefas; fecha no `finally`), instancia `Orfeu(app=..., ...)` **depois** do `FastAPI(...)`
|
|
31
|
+
(ele embrulha o lifespan: sync das operações antes, flush da auditoria depois — não chame startup à
|
|
32
|
+
mão), adiciona CORS, chama `install_envelope(app)` e inclui o router sob `settings.api_prefix`.
|
|
33
|
+
5. **Toda rota responde no envelope** `{status, message, data}`: `return ok(dado, "Mensagem.", status)` e
|
|
34
|
+
`response_model=Envelope[TipoOut]`. Erros de negócio = `raise NotFound/Conflict/...` do `orfeu`; o
|
|
35
|
+
`install_envelope` converte tudo (inclusive 422 do Pydantic e 500 inesperado). Ver
|
|
36
|
+
[references/rotas-erros.md](references/rotas-erros.md).
|
|
37
|
+
6. **Rota protegida** = `@router.<verbo>(...)` por cima e `@operation(id="dominio:acao", level=Level.X)`
|
|
38
|
+
logo abaixo. Rota sem `@operation` passa **sem autenticação**. Ids estáveis (`tags:list`,
|
|
39
|
+
`tags:create`...). Semântica de `Level`/`Method` → orfeu.
|
|
40
|
+
7. **Status coerente nos dois lugares**: em criação use `status_code=201` no decorator **e**
|
|
41
|
+
`ok(..., 201)` — o `ok` só preenche o corpo, não o status HTTP.
|
|
42
|
+
8. **Banco**: SQLAlchemy 2 síncrono + `psycopg2-binary`, só Postgres. Engine criada no lifespan,
|
|
43
|
+
`SessionLocal` em `app.state`, sessão por requisição via `Depends(get_db)`. Rotas que usam a sessão
|
|
44
|
+
síncrona devem ser `def` (rodam no threadpool), não `async def`. Ver
|
|
45
|
+
[references/banco.md](references/banco.md).
|
|
46
|
+
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`
|
|
48
|
+
manuais. Não há Alembic nem `create_all` em produção.
|
|
49
|
+
10. **Configuração por ambiente**: `pydantic-settings` + `src/.env` (só `APP_ENV`) +
|
|
50
|
+
`src/settings/environment/.env.<APP_ENV>`; variáveis do processo vencem os arquivos. Nunca versione
|
|
51
|
+
valores reais; mantenha um `.env.example` só com nomes.
|
|
52
|
+
11. **Chamadas a outros serviços**: `httpx.AsyncClient` reaproveitado (singleton), com timeout e
|
|
53
|
+
tradução de falha para `Unavailable`. Em nome do usuário, repasse `orfeu_headers(request)`; como o
|
|
54
|
+
próprio serviço, token de app do Argos. Ver [references/integracoes.md](references/integracoes.md).
|
|
55
|
+
12. **Testes**: pytest com `pythonpath = src`, app mínimo só com o router testado + `install_envelope` +
|
|
56
|
+
SQLite em memória via `schema_translate_map`; testes que exigem Postgres real marcados `db`. Ver
|
|
57
|
+
[references/testes-deploy.md](references/testes-deploy.md).
|
|
58
|
+
|
|
59
|
+
## Esqueleto mínimo de rota
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
from typing import List
|
|
63
|
+
from uuid import UUID
|
|
64
|
+
|
|
65
|
+
from fastapi import APIRouter, Depends
|
|
66
|
+
from orfeu import Level, Method, ok
|
|
67
|
+
from orfeu.adapters.fastapi import Envelope, operation
|
|
68
|
+
from sqlalchemy.orm import Session
|
|
69
|
+
|
|
70
|
+
from app.domains.tags.schemas import TagCreate, TagOut
|
|
71
|
+
from app.domains.tags.service import TagService
|
|
72
|
+
from app.shared.dependencies import get_db
|
|
73
|
+
|
|
74
|
+
router = APIRouter(prefix="/tags", tags=["Tags"])
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
@router.get("", response_model=Envelope[List[TagOut]])
|
|
78
|
+
@operation(id="tags:list", level=Level.PROTECTED, method=Method.READ)
|
|
79
|
+
def list_tags(db: Session = Depends(get_db)):
|
|
80
|
+
return ok(TagService(db).list())
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
@router.post("", status_code=201, response_model=Envelope[TagOut])
|
|
84
|
+
@operation(id="tags:create", level=Level.PROTECTED, method=Method.WRITE)
|
|
85
|
+
def create_tag(body: TagCreate, db: Session = Depends(get_db)):
|
|
86
|
+
return ok(TagService(db).create(body.name), "Tag criada.", 201)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Armadilhas mais comuns (lista completa nas referências)
|
|
90
|
+
|
|
91
|
+
- `async def` + sessão SQLAlchemy síncrona bloqueia o event loop inteiro. Use `def`; reserve `async def`
|
|
92
|
+
para rotas que fazem `await` (httpx) e, dentro delas, mande trabalho bloqueante para
|
|
93
|
+
`run_in_threadpool`/`asyncio.to_thread`.
|
|
94
|
+
- `text(sql)` trata **qualquer** `:palavra` como bind param — inclusive em comentários e strings do SQL
|
|
95
|
+
(ex.: `-- POST /realms/:realm/...`). Script sem parâmetros: `text(sql.replace(":", r"\:"))`.
|
|
96
|
+
- Sem `method=` explícito, o Orfeu infere o método do **nome da função** (`get_`/`list_`/`fetch_`/`read_`
|
|
97
|
+
→ read; `delete_`/`remove_`/`destroy_` → delete; contém `stream`/`subscribe`/`watch`/`listen` → stream;
|
|
98
|
+
resto → write): renomear a função muda a permissão exigida. Os serviços atuais dependem disso; em
|
|
99
|
+
código novo passe `method=Method.X` explícito (regra da orfeu).
|
|
100
|
+
- Proxy reverso que encaminha o path completo (sem strip): o serviço precisa montar rotas **e**
|
|
101
|
+
`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.
|
|
106
|
+
- Campo de settings não declarado entrando via `extra="allow"` (ex.: porta) funciona por acaso — declare
|
|
107
|
+
todo campo usado.
|
|
108
|
+
- Tarefa em segundo plano não pode usar a sessão da requisição (já fechada): abra outra a partir de
|
|
109
|
+
`app.state.SessionLocal`.
|
|
110
|
+
- `CMD` do container com `exec uvicorn ...` — sem `exec`, o `sh` vira PID 1, não repassa SIGTERM e todo
|
|
111
|
+
stop espera o timeout.
|
|
112
|
+
|
|
113
|
+
## Índice de referências
|
|
114
|
+
|
|
115
|
+
| Arquivo | Conteúdo |
|
|
116
|
+
|---|---|
|
|
117
|
+
| [references/estrutura.md](references/estrutura.md) | Árvore do projeto, responsabilidades por camada, `main.py`, settings/env (nomes), dependências |
|
|
118
|
+
| [references/rotas-erros.md](references/rotas-erros.md) | Convenção de rotas e ids, `@operation`, Pydantic (entrada/saída, camelCase), envelope, erros e status |
|
|
119
|
+
| [references/banco.md](references/banco.md) | Engine/sessão, models e schemas do Postgres, transações, SQL cru, `database/` com build.py e migrations, armadilhas |
|
|
120
|
+
| [references/integracoes.md](references/integracoes.md) | Clientes HTTP, `orfeu_headers`, token de app, Redis, tarefas em segundo plano, collectors, logs |
|
|
121
|
+
| [references/testes-deploy.md](references/testes-deploy.md) | pytest (SQLite em memória, Postgres com savepoint, fakes do Orfeu), Dockerfile, uvicorn, `.dockerignore` |
|
|
122
|
+
|
|
123
|
+
## Skills relacionadas
|
|
124
|
+
|
|
125
|
+
- **orfeu** — `@operation`, `Level`/`Method`, claims em `request.state.user`, `orfeu_headers`,
|
|
126
|
+
auditoria e erros do envelope.
|
|
127
|
+
- **apollo** — o gateway GraphQL que chama este serviço (envelope → resolvers).
|
|
128
|
+
- **express** — equivalente para serviços Node/Express.
|
|
129
|
+
- **angular** / **trismegisto** — front que consome o gateway.
|