@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.
Files changed (90) hide show
  1. package/README.md +180 -2
  2. package/agents/revisor-deploy.md +73 -0
  3. package/agents/revisor-documentacao.md +78 -0
  4. package/agents/revisor-orfeu.md +80 -0
  5. package/agents/revisor-trismegisto.md +81 -0
  6. package/bin/install.js +252 -0
  7. package/package.json +15 -4
  8. package/skills/acropole/SKILL.md +75 -0
  9. package/skills/acropole/references/fluxos/doctor.md +55 -0
  10. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  11. package/skills/acropole/references/fluxos/revisar.md +56 -0
  12. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  13. package/skills/acropole/scripts/doctor.mjs +439 -0
  14. package/skills/angular/SKILL.md +152 -0
  15. package/skills/angular/references/armadilhas.md +95 -0
  16. package/skills/angular/references/dados.md +251 -0
  17. package/skills/angular/references/estrutura.md +260 -0
  18. package/skills/angular/references/features.md +219 -0
  19. package/skills/angular/references/testes-build.md +230 -0
  20. package/skills/angular/scripts/checar.mjs +182 -0
  21. package/skills/angular/scripts/nucleo.mjs +227 -0
  22. package/skills/apollo/SKILL.md +222 -0
  23. package/skills/apollo/references/armadilhas.md +95 -0
  24. package/skills/apollo/references/envelope-erros.md +120 -0
  25. package/skills/apollo/references/estrutura-bootstrap.md +299 -0
  26. package/skills/apollo/references/schema-resolvers.md +183 -0
  27. package/skills/apollo/references/subscriptions.md +224 -0
  28. package/skills/apollo/references/testes-build.md +180 -0
  29. package/skills/apollo/scripts/checar.mjs +160 -0
  30. package/skills/apollo/scripts/nucleo.mjs +227 -0
  31. package/skills/docker/SKILL.md +102 -0
  32. package/skills/docker/references/modelos.md +251 -0
  33. package/skills/docker/references/porques.md +282 -0
  34. package/skills/documentacao/SKILL.md +146 -0
  35. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  36. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  37. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  38. package/skills/documentacao/references/modelo-readme.md +75 -0
  39. package/skills/documentacao/scripts/checar.mjs +454 -0
  40. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  41. package/skills/express/SKILL.md +154 -0
  42. package/skills/express/references/dados.md +180 -0
  43. package/skills/express/references/estrutura.md +154 -0
  44. package/skills/express/references/middlewares.md +227 -0
  45. package/skills/express/references/rotas-erros.md +274 -0
  46. package/skills/express/references/testes-deploy.md +150 -0
  47. package/skills/express/scripts/checar.mjs +115 -0
  48. package/skills/express/scripts/nucleo.mjs +227 -0
  49. package/skills/fastapi/SKILL.md +129 -0
  50. package/skills/fastapi/references/banco.md +185 -0
  51. package/skills/fastapi/references/estrutura.md +281 -0
  52. package/skills/fastapi/references/integracoes.md +145 -0
  53. package/skills/fastapi/references/rotas-erros.md +140 -0
  54. package/skills/fastapi/references/testes-deploy.md +190 -0
  55. package/skills/fastapi/scripts/checar.mjs +108 -0
  56. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  57. package/skills/hefesto/SKILL.md +119 -0
  58. package/skills/hefesto/references/conceitos.md +131 -0
  59. package/skills/hefesto/references/diagnostico.md +70 -0
  60. package/skills/hefesto/references/fluxo.md +122 -0
  61. package/skills/hefesto/references/preparar-app.md +105 -0
  62. package/skills/orfeu/SKILL.md +162 -0
  63. package/skills/orfeu/references/angular-api.md +201 -0
  64. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  65. package/skills/orfeu/references/angular-recipes.md +474 -0
  66. package/skills/orfeu/references/angular.md +212 -0
  67. package/skills/orfeu/references/diferencas.md +56 -0
  68. package/skills/orfeu/references/node-api.md +348 -0
  69. package/skills/orfeu/references/node-armadilhas.md +158 -0
  70. package/skills/orfeu/references/node-recipes.md +534 -0
  71. package/skills/orfeu/references/node.md +204 -0
  72. package/skills/orfeu/references/python-api.md +346 -0
  73. package/skills/orfeu/references/python-recipes.md +479 -0
  74. package/skills/orfeu/references/python.md +234 -0
  75. package/skills/orfeu/scripts/checar.mjs +126 -0
  76. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  77. package/skills/trismegisto/SKILL.md +194 -0
  78. package/skills/trismegisto/references/angular-api.md +2788 -0
  79. package/skills/trismegisto/references/angular-exports.md +4020 -0
  80. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  81. package/skills/trismegisto/references/angular-types.md +492 -0
  82. package/skills/trismegisto/references/angular.md +390 -0
  83. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  84. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  85. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  86. package/skills/trismegisto/references/spine-api.md +1530 -0
  87. package/skills/trismegisto/references/spine-recipes.md +581 -0
  88. package/skills/trismegisto/references/spine.md +343 -0
  89. package/skills/trismegisto/scripts/checar.mjs +216 -0
  90. package/skills/trismegisto/scripts/nucleo.mjs +227 -0
@@ -0,0 +1,299 @@
1
+ # Estrutura e bootstrap
2
+
3
+ O servidor é **Apollo Server montado no Express** (`expressMiddleware`), não o modo standalone: o mesmo
4
+ `http.Server` serve o GraphQL (HTTP), o WebSocket das subscriptions e, quando preciso, rotas REST auxiliares
5
+ (upload, proxy de arquivo). Express em si: **express**.
6
+
7
+ ## `src/index.ts`
8
+
9
+ ```ts
10
+ console.time('Server | Load Time');
11
+
12
+ import * as dotenv from 'dotenv';
13
+ dotenv.config({ path: `src/settings/environment/.env.${process.env.NODE_ENV ?? 'local'}` });
14
+
15
+ import builder from './core/builder.js';
16
+
17
+ try {
18
+ await builder(process.env);
19
+ } catch (error) {
20
+ console.error('Falha na subida:', error);
21
+ process.exit(1); // sem isto o processo fica de pé sem servir nada
22
+ }
23
+ console.timeEnd('Server | Load Time');
24
+
25
+ process.on('unhandledRejection', (reason) => console.error('unhandledRejection:', reason));
26
+ ```
27
+
28
+ - `NODE_ENV` com padrão (`?? 'local'`): sem ele o dotenv procura `.env.undefined`.
29
+ - No container o `.env.*` não é copiado (só `dist/`): as variáveis vêm do ambiente do container e o
30
+ `dotenv.config` simplesmente não acha o arquivo — é o esperado.
31
+ - **Atenção ao ESM**: o `import builder` é avaliado ANTES do `dotenv.config()` (imports estáticos sobem
32
+ primeiro). Nada no grafo de imports pode ler `process.env` em escopo de módulo — leia dentro de funções.
33
+
34
+ ## `src/core/builder.ts` (padrão recomendado)
35
+
36
+ ```ts
37
+ import express from 'express';
38
+ import cors from 'cors';
39
+ import { makeExecutableSchema } from '@graphql-tools/schema';
40
+ import { expressMiddleware } from '@as-integrations/express4';
41
+ import { OrfeuClient } from '@orfeu/node';
42
+ import { assertSchemaSecured, orfeuWsContext, secureResolvers } from '@orfeu/node/apollo';
43
+
44
+ import { BASE_SCHEMA } from './schema/index.js';
45
+ import { HttpServer } from './server/http.server.js';
46
+ import { WsServer } from './server/ws.server.js';
47
+ import { ApolloServer } from './server/apollo.server.js';
48
+ import { wsContextParams } from './context/ws-context.js';
49
+ import { AppModules } from '../web/config/index.js';
50
+ import { ExtendedSchema } from '../web/config/schemas/schemas.extends.js';
51
+ import type { GraphQLContext } from './context/context.types.js';
52
+
53
+ export default async (settings: NodeJS.ProcessEnv) => {
54
+ const orfeu = new OrfeuClient({
55
+ authorizerUrl: settings.AUTHORIZER_URL!,
56
+ realmId: settings.REALM_ID!,
57
+ appId: settings.APP_ID!,
58
+ secret: settings.APP_SECRET!,
59
+ tlsVerify: settings.AUTH_TLS_VERIFY !== 'false', // opt-out; só para CA fora do bundle do Node
60
+ });
61
+
62
+ // 1) schema seguro ANTES do startup (o startup sincroniza as operações registradas com o Argos)
63
+ const extended = new ExtendedSchema();
64
+ const resolvers = secureResolvers(orfeu, extended.resolvers, {
65
+ onForbidden: () => ({ status: 403, message: 'Você não tem permissão para esta operação.', data: null }),
66
+ });
67
+ const schema = makeExecutableSchema({ typeDefs: [...BASE_SCHEMA, ...extended.typeDefs], resolvers });
68
+ assertSchemaSecured(schema);
69
+ await orfeu.startup();
70
+
71
+ // 2) módulos (clientes REST) — criados aqui, depois do dotenv
72
+ const appMods = await AppModules.start(settings);
73
+
74
+ // 3) servidores: o MESMO path no HTTP e no WS
75
+ const graphqlPath = settings.GRAPHQL_PATH ?? '/graphql';
76
+ const app = express();
77
+ const http = new HttpServer(app);
78
+ // extra do WS: módulos + só a allowlist do connectionParams (nunca `...connectionParams`)
79
+ const ws = new WsServer(http.server, schema,
80
+ orfeuWsContext(orfeu, (ctx) => ({ App: appMods, ...wsContextParams(ctx) })), graphqlPath);
81
+ const apollo = new ApolloServer(schema, http.server, ws.serverCleanup, orfeu);
82
+ await apollo.server.start();
83
+
84
+ app.get('/health', (_req, res) => { res.status(200).json({ ok: true }); }); // probe sem auth (aqui o startup já passou)
85
+ app.use(
86
+ graphqlPath,
87
+ cors<cors.CorsRequest>(),
88
+ express.json({ limit: '2mb' }),
89
+ expressMiddleware(apollo.server, {
90
+ context: async ({ req }): Promise<GraphQLContext> => ({ App: appMods, req }),
91
+ }),
92
+ );
93
+
94
+ const port = Number(settings.PORT ?? 3000);
95
+ http.server.listen(port, () => console.log(`GraphQL → http://localhost:${port}${graphqlPath}`));
96
+
97
+ // 4) encerramento: node é PID 1 no container; sem handler o stop espera o SIGKILL
98
+ for (const signal of ['SIGTERM', 'SIGINT'] as const) {
99
+ 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
102
+ await apollo.server.stop().catch(() => undefined); // drain: fecha HTTP e WS
103
+ process.exit(0);
104
+ });
105
+ }
106
+ };
107
+ ```
108
+
109
+ Pontos:
110
+
111
+ - O contexto HTTP só precisa de `{ App, req }`: os campos `orfeu*` (credencial, trace, routeId/clientId) são
112
+ preenchidos pelo `orfeuPlugin` no `didResolveOperation`. Não valide token no `context` — a validação é
113
+ por campo, no `secureResolvers`.
114
+ - `@orfeu/node` `^1.0.1` no `package.json` (a 1.0.0 aceitava `orfeuUser` forjado pelo `connectionParams`).
115
+ O contexto do WS (`ws-context.ts`, com a allowlist) está em [subscriptions.md](subscriptions.md).
116
+
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:
128
+
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
139
+
140
+ app.get('/health', (_req, res) => {
141
+ res.status(orfeuPronto ? 200 : 503).json({ ok: orfeuPronto, orfeu: orfeuPronto ? 'up' : 'connecting' });
142
+ });
143
+ ```
144
+
145
+ O `secureResolvers` e o `assertSchemaSecured` continuam **antes** de qualquer tentativa (o catálogo precisa
146
+ estar registrado quando o `startup()` sincronizar).
147
+
148
+ - `compression()` antes do Apollo vale a pena quando há respostas grandes (JSON comprime 70–85%).
149
+
150
+ ## `src/core/server/*.ts`
151
+
152
+ ```ts
153
+ // http.server.ts
154
+ import http from 'node:http';
155
+ import type { Express } from 'express';
156
+ export class HttpServer {
157
+ public server: http.Server;
158
+ constructor(app: Express) { this.server = http.createServer(app); }
159
+ }
160
+ ```
161
+
162
+ ```ts
163
+ // ws.server.ts (graphql-ws 5: 'graphql-ws/lib/use/ws'; graphql-ws 6: 'graphql-ws/use/ws')
164
+ import { WebSocketServer } from 'ws';
165
+ import { useServer } from 'graphql-ws/lib/use/ws';
166
+ import type { GraphQLSchema } from 'graphql';
167
+ import type http from 'node:http';
168
+
169
+ export class WsServer {
170
+ public server: WebSocketServer;
171
+ public serverCleanup: ReturnType<typeof useServer>;
172
+ constructor(httpServer: http.Server, schema: GraphQLSchema, context: (ctx: any) => Promise<unknown>, path: string) {
173
+ this.server = new WebSocketServer({ server: httpServer, path });
174
+ // `as any`: sob NodeNext o @types/ws pode resolver duas vezes (import/require) e o TS vê dois tipos distintos
175
+ this.serverCleanup = useServer({ schema, context }, this.server as any);
176
+ }
177
+ }
178
+ ```
179
+
180
+ ```ts
181
+ // apollo.server.ts (Apollo Server 5)
182
+ import { ApolloServer as ApolloBase } from '@apollo/server';
183
+ import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
184
+ import { orfeuPlugin } from '@orfeu/node/apollo';
185
+ import type { OrfeuClient } from '@orfeu/node';
186
+ import type { GraphQLSchema } from 'graphql';
187
+ import type http from 'node:http';
188
+ import type { GraphQLContext } from '../context/context.types.js';
189
+
190
+ export class ApolloServer {
191
+ public server: ApolloBase<GraphQLContext>;
192
+ constructor(schema: GraphQLSchema, httpServer: http.Server,
193
+ wsCleanup: { dispose: () => void | Promise<void> }, orfeu: OrfeuClient) {
194
+ this.server = new ApolloBase<GraphQLContext>({
195
+ schema,
196
+ allowBatchedHttpRequests: true, // o front usa HttpBatchLink
197
+ introspection: process.env.GRAPHQL_INTROSPECTION === 'true', // só para o codegen local
198
+ plugins: [
199
+ ApolloServerPluginDrainHttpServer({ httpServer }),
200
+ orfeuPlugin(orfeu),
201
+ { async serverWillStart() { return { async drainServer() { await wsCleanup.dispose(); } }; } },
202
+ ],
203
+ });
204
+ }
205
+ }
206
+ ```
207
+
208
+ ## Contexto tipado
209
+
210
+ ```ts
211
+ // src/core/context/context.types.ts
212
+ import type { Request } from 'express';
213
+ import type { OrfeuContext } from '@orfeu/node/apollo';
214
+ import type { AppModules } from '../../web/config/index.types.js';
215
+
216
+ export type GraphQLContext = OrfeuContext & { App: AppModules; req?: Request };
217
+ ```
218
+
219
+ - No HTTP `req` existe; no WS não (há `connectionParams`). Use `req?` ou um tipo separado para
220
+ subscriptions.
221
+ - O usuário validado fica em `ctx.orfeuUser` **depois** do guard do campo — não leia no `context()`.
222
+ - Evite o padrão antigo de montar `metadata = { token, user }` à mão no contexto validando o token com
223
+ `orfeu.validateToken`: duplica o trabalho do `secureResolvers` e diverge dele. Se o contexto realmente
224
+ precisa de um usuário validado por fora (sem credencial crua), ele entra por `trustUser(ctx, claims)`;
225
+ `ctx.orfeuUser = ...` gravado à mão responde 401 desde o `@orfeu/node` 1.0.1 (skill **orfeu**).
226
+
227
+ ## `AppModules` (composição)
228
+
229
+ ```ts
230
+ // src/web/config/index.ts
231
+ import { TagsModule } from '../tags/modules/index.js';
232
+ import { OrdersModule } from '../orders/modules/index.js';
233
+ import type { AppModules as IAppModules } from './index.types.js';
234
+
235
+ export class AppModules implements IAppModules {
236
+ constructor(public Tags: TagsModule, public Orders: OrdersModule) {}
237
+ static async start(settings: NodeJS.ProcessEnv): Promise<AppModules> {
238
+ return new AppModules(new TagsModule(settings), new OrdersModule(settings));
239
+ }
240
+ }
241
+ ```
242
+
243
+ `index.types.ts` declara só a interface (`Tags: TagsModule; ...`) e existe para quebrar o ciclo de import
244
+ entre `context.types.ts` e os módulos. Um módulo por domínio, nome em PascalCase igual ao do domínio
245
+ (`ctx.App.Orders`).
246
+
247
+ ## `ExtendedSchema` (composição do schema)
248
+
249
+ ```ts
250
+ // src/web/config/schemas/schemas.extends.ts
251
+ import merge from 'lodash/merge.js';
252
+ import type { IResolvers } from '@graphql-tools/utils';
253
+ import { Level } from '@orfeu/node';
254
+ import { operation } from '@orfeu/node/apollo';
255
+ import { JSONScalar } from '../../../core/schema/scalars.js';
256
+ import { TAGS_SCHEMA, TAGS_RESOLVERS } from '../../tags/schemas/index.js';
257
+ import { ORDERS_SCHEMA, ORDERS_RESOLVERS } from '../../orders/schemas/index.js';
258
+
259
+ export class ExtendedSchema {
260
+ public typeDefs: string[] = [
261
+ `#graphql
262
+ extend type Query { _health: String! }
263
+ `,
264
+ ...TAGS_SCHEMA,
265
+ ...ORDERS_SCHEMA,
266
+ ];
267
+ public resolvers: IResolvers = merge(
268
+ { JSON: JSONScalar, Query: { _health: operation(Level.PUBLIC, () => 'ok') } },
269
+ TAGS_RESOLVERS,
270
+ ORDERS_RESOLVERS,
271
+ );
272
+ }
273
+ ```
274
+
275
+ `BASE_SCHEMA` declara os tipos raiz vazios (`type Query`, `type Mutation`, `type Subscription`) e os
276
+ scalars. Se `Mutation` ou `Subscription` acabar sem nenhum campo, o schema não valida: remova o tipo raiz
277
+ vazio do `BASE_SCHEMA` ou adicione um campo real (evite campos `_noop` só para tapar).
278
+
279
+ ## Rotas REST ao lado do GraphQL
280
+
281
+ Upload de arquivo e leitura de binário (imagem) **não** passam pelo Apollo (evita `graphql-upload`). Monte um
282
+ `express.Router()` na base do path (`/app/graphql` → `/app`), faça proxy em stream para o serviço de trás e
283
+ repasse os headers do Orfeu com uma função própria (não há `OrfeuContext` fora do Apollo):
284
+
285
+ ```ts
286
+ import type { Request } from 'express';
287
+ import { ACCESS_TOKEN_HEADER, APP_TOKEN_HEADER, CLIENT_ID_HEADER, ROUTE_ID_HEADER, TRACEPARENT_HEADER } from '@orfeu/node';
288
+
289
+ export function passthroughHeaders(req: Request): Record<string, string> {
290
+ const out: Record<string, string> = {};
291
+ const get = (n: string) => { const v = req.headers[n]; return (Array.isArray(v) ? v[0] : v)?.trim() || undefined; };
292
+ for (const n of [ACCESS_TOKEN_HEADER, APP_TOKEN_HEADER]) { const v = get(n); if (v) { out[n] = v; break; } }
293
+ for (const n of [TRACEPARENT_HEADER, ROUTE_ID_HEADER, CLIENT_ID_HEADER]) { const v = get(n); if (v) out[n] = v; }
294
+ return out;
295
+ }
296
+ ```
297
+
298
+ O `traceparent` vai sem span novo (o gateway não audita essas rotas). Detalhes de proxy/stream:
299
+ **express**.
@@ -0,0 +1,183 @@
1
+ # Schema, resolvers e módulos
2
+
3
+ ## SDL-first, em TypeScript
4
+
5
+ - O schema é **SDL** (não code-first), escrito em template strings com o marcador `#graphql` (realce de
6
+ sintaxe e o GraphQL do VS Code reconhecem). Não há `.graphql` no servidor — os `.graphql` com as
7
+ **operações** ficam no front (ver **angular**).
8
+ - `makeExecutableSchema({ typeDefs, resolvers })` de `@graphql-tools/schema` junta tudo.
9
+ - Cada arquivo de recurso exporta `schema: string[]` e `resolvers`. Mantenha o `schema` como **array** (permite
10
+ `...spread` sem caso especial) e use `schema: string[] = []` quando não houver nada — não `[``]`.
11
+
12
+ ## Organização por domínio
13
+
14
+ ```
15
+ web/orders/
16
+ modules/index.ts OrdersModule (REST)
17
+ schemas/
18
+ order/queries.ts extend type Query { ... } + tipos de leitura + resolvers.Query
19
+ order/mutations.ts extend type Mutation { ... } + inputs + resolvers.Mutation
20
+ order/subscriptions.ts extend type Subscription { ... } + resolvers.Subscription
21
+ order/index.ts reexporta com nomes únicos
22
+ index.ts ORDERS_SCHEMA / ORDERS_RESOLVERS
23
+ ```
24
+
25
+ ```ts
26
+ // order/index.ts
27
+ export { schema as ORDER_QUERIES_SCHEMA, resolvers as ORDER_QUERIES_RESOLVERS } from './queries.js';
28
+ export { schema as ORDER_MUTATIONS_SCHEMA, resolvers as ORDER_MUTATIONS_RESOLVERS } from './mutations.js';
29
+ export { schema as ORDER_SUBSCRIPTIONS_SCHEMA, resolvers as ORDER_SUBSCRIPTIONS_RESOLVERS } from './subscriptions.js';
30
+
31
+ // schemas/index.ts
32
+ import merge from 'lodash/merge.js';
33
+ import * as O from './order/index.js';
34
+ export const ORDERS_SCHEMA = [...O.ORDER_QUERIES_SCHEMA, ...O.ORDER_MUTATIONS_SCHEMA, ...O.ORDER_SUBSCRIPTIONS_SCHEMA];
35
+ export const ORDERS_RESOLVERS = merge({}, O.ORDER_QUERIES_RESOLVERS, O.ORDER_MUTATIONS_RESOLVERS, O.ORDER_SUBSCRIPTIONS_RESOLVERS);
36
+ ```
37
+
38
+ - `merge` **sempre com `{}` como primeiro argumento** — `merge(a, b)` muta `a`.
39
+ - Importe `lodash/merge.js` (ESM + NodeNext) ou `import pkg from 'lodash'; const { merge } = pkg;`. Não
40
+ `import { merge } from 'lodash'` (CommonJS sem export nomeado em ESM).
41
+ - Tipos compartilhados entre domínios (ex.: `Environment`, tipos de um inventário comum) vão num domínio
42
+ `shared/` que entra primeiro no `ExtendedSchema`. Tipos de outro domínio podem ser estendidos
43
+ (`extend type Pool { ... }`), mas isso cria acoplamento de ordem — prefira tipos próprios.
44
+
45
+ ## Convenções de SDL
46
+
47
+ | Item | Convenção |
48
+ | --- | --- |
49
+ | Campo raiz | camelCase, verbo + recurso: `listOrders`, `getOrder`, `createOrder`, `updateOrder`, `deleteOrder`; subscription: `orderChanged` / `subscribeOrderX` |
50
+ | Remoção | começa com `delete`/`remove`/`destroy` (vira método `delete` no Orfeu) |
51
+ | Retorno de Query/Mutation | `<Nome>Response!` (não-nulo), gerado por `envelopeType` |
52
+ | `data` do envelope | **sempre anulável** (`data: Order`, `data: [Order!]`) — falha devolve `data: null` |
53
+ | Inputs | `input CreateOrderInput`, `input UpdateOrderInput` (campos opcionais no update) |
54
+ | Remoção sem retorno | `envelopeType('MutationResult', 'ID')` reaproveitado |
55
+ | Nomes de campo | os mesmos que o serviço de trás devolve (snake_case ou camelCase, o que vier) — o gateway não renomeia |
56
+ | Docs | string de descrição no SDL (`"..."` ou `"""..."""`) nos campos raiz; aparece no codegen |
57
+
58
+ Declare cada `envelopeType(...)` **uma vez** no schema inteiro (tipo duplicado quebra o `makeExecutableSchema`).
59
+
60
+ ## Scalars
61
+
62
+ ```ts
63
+ // core/schema/scalars.ts
64
+ import { GraphQLScalarType, Kind, type ValueNode } from 'graphql';
65
+
66
+ function parseLiteral(ast: ValueNode): unknown {
67
+ switch (ast.kind) {
68
+ case Kind.STRING: case Kind.BOOLEAN: return ast.value;
69
+ case Kind.INT: case Kind.FLOAT: return Number(ast.value);
70
+ case Kind.OBJECT: return Object.fromEntries(ast.fields.map((f) => [f.name.value, parseLiteral(f.value)]));
71
+ case Kind.LIST: return ast.values.map(parseLiteral);
72
+ default: return null;
73
+ }
74
+ }
75
+
76
+ export const JSONScalar = new GraphQLScalarType({
77
+ name: 'JSON',
78
+ description: 'Valor JSON arbitrário (payloads dinâmicos).',
79
+ serialize: (v) => v, parseValue: (v) => v, parseLiteral,
80
+ });
81
+ ```
82
+
83
+ `scalar JSON` no `BASE_SCHEMA` + `JSON: JSONScalar` nos resolvers. Use `JSON` só para payload realmente
84
+ dinâmico — tipo explícito dá codegen útil no front. Datas trafegam como `String` ISO 8601.
85
+
86
+ ## Resolvers
87
+
88
+ ```ts
89
+ createOrder: operation(Level.PRIVATE, (_: unknown, { input }: { input: CreateOrderInput }, ctx: GraphQLContext) =>
90
+ forward(() => ctx.App.Orders.create(input, ctx))),
91
+ ```
92
+
93
+ - Uma linha: `operation(nível, (parent, args, ctx) => forward(() => ctx.App.<Dominio>.<metodo>(..., ctx)))`.
94
+ - O resolver **traduz argumentos** (GraphQL camelCase → query string do serviço, omitindo vazios) e mais
95
+ nada. Sem `try/catch` próprio (o `forward` cuida), sem texto de mensagem, sem transformar `data`.
96
+ - Exceção aceitável: remodelar um payload que o serviço publica num formato que o GraphQL não expressa
97
+ (ex.: dicionário `{ chave: valor }` → lista `[{ key, value }]`), de preferência numa função pura testada.
98
+ - Tipar `args` e `ctx` (`GraphQLContext`). `any` em `ctx` esconde o erro de `ctx.App` ausente no WS.
99
+ - Resolver de campo de tipo (não raiz) não passa pelo Orfeu e não precisa de `operation()`; evite fazer
100
+ chamada remota nele (N+1) — peça o dado já montado ao serviço de trás.
101
+
102
+ ## Módulos (clientes dos serviços de trás)
103
+
104
+ ```ts
105
+ import axios, { type AxiosInstance } from 'axios';
106
+ import { orfeuHeaders, type OrfeuForwardSource } from '@orfeu/node';
107
+
108
+ export class OrdersModule {
109
+ private http: AxiosInstance;
110
+ constructor(settings: NodeJS.ProcessEnv) {
111
+ this.http = axios.create({ baseURL: settings.PLATFORM_SERVICE_URL, timeout: 30_000 });
112
+ }
113
+ async create(body: unknown, caller: OrfeuForwardSource) {
114
+ const { data } = await this.http.post('/orders', body, { headers: orfeuHeaders(caller) });
115
+ return data; // envelope do serviço
116
+ }
117
+ async remove(orderId: string, caller: OrfeuForwardSource) {
118
+ const { data } = await this.http.delete(`/orders/${encodeURIComponent(orderId)}`, { headers: orfeuHeaders(caller) });
119
+ return data;
120
+ }
121
+ }
122
+ ```
123
+
124
+ - `axios.create` **no construtor** (depois do dotenv), `baseURL` de variável de ambiente.
125
+ - Último parâmetro sempre `caller: OrfeuForwardSource` — o próprio `ctx`. `orfeuHeaders(ctx)` envia a
126
+ credencial recebida (`x-access-token` → `x-app-token` → `x-api-token`), o `traceparent` com o span DESTE
127
+ salto e `x-route-id`/`x-client-id`. Sem isso o serviço de trás grava a ação como entrada nova e a auditoria
128
+ aparece partida em dois traces. Detalhes: **orfeu**.
129
+ - `encodeURIComponent` em id que vai no path.
130
+ - Um módulo pode agrupar vários sub-recursos do mesmo prefixo REST (uma classe com seções), desde que siga
131
+ o mesmo serviço de trás.
132
+ - Status de negócio que **não** é erro mas vem como 4xx (ex.: 422 com a lista de achados em `data`): aceite
133
+ com `validateStatus` só naquela chamada:
134
+
135
+ ```ts
136
+ const { data } = await this.http.post(`/orders/${id}/publish`, {}, {
137
+ headers: orfeuHeaders(caller),
138
+ validateStatus: (s) => (s >= 200 && s < 300) || s === 422,
139
+ });
140
+ ```
141
+
142
+ - **TLS**: não desligue a verificação (`rejectUnauthorized: false`) no agente HTTP. Se a CA é interna,
143
+ configure `NODE_EXTRA_CA_CERTS`. Proxy de saída só por variável de ambiente e só onde for necessário.
144
+ - Header de trace próprio (`x-trace-id` com `AsyncLocalStorage`) é legado: o trace é o `traceparent` do
145
+ Orfeu. Não crie um segundo mecanismo.
146
+
147
+ ## Filtros
148
+
149
+ - Filtros como **argumentos opcionais** do campo (`listOrders(status: String, from: String, to: String)`) ou
150
+ um `input OrderFilters` quando passam de três ou quatro.
151
+ - O resolver/módulo monta `params` só com o que veio preenchido (`null`, `undefined` e `''` não vão).
152
+ - Renomeie para o nome do serviço no módulo (`from` → `from_` quando o Python reserva a palavra).
153
+ - Arrays em query string: o padrão do axios é `key[]=a&key[]=b`; FastAPI espera `key=a&key=b` — use
154
+ `paramsSerializer: { indexes: null }` no `axios.create`.
155
+ - Filtro de **escopo do usuário** (só os itens do time dele) é do serviço de trás, que lê o token — o
156
+ gateway não decide visibilidade.
157
+
158
+ ## Paginação
159
+
160
+ Padrão offset/limit, envelope com página:
161
+
162
+ ```graphql
163
+ extend type Query {
164
+ "Mais novos primeiro; a tela pede páginas até completar `total`."
165
+ listOrders(filters: OrderFilters, offset: Int, limit: Int): OrdersPageResponse!
166
+ }
167
+ type OrdersPage { items: [Order!]!, total: Int!, offset: Int! }
168
+ ```
169
+
170
+ ```ts
171
+ listOrders: operation(Level.PRIVATE, (_: unknown, { filters, offset, limit }: ListArgs, ctx: GraphQLContext) =>
172
+ forward(() => ctx.App.Orders.list(filters, offset ?? 0, limit ?? 50, ctx))),
173
+ ```
174
+
175
+ Padrão no resolver (`offset ?? 0`, `limit ?? 50`); o teto do `limit` é imposto pelo serviço de trás. Listas
176
+ pequenas (cadastros) podem devolver tudo (`data: [Order!]`) sem página. Cursor não é usado hoje.
177
+
178
+ ## Módulos fora do HTTP (subscriptions)
179
+
180
+ Se uma subscription precisa chamar o serviço de trás (ex.: buscar o escopo do usuário), o `ctx.App` precisa
181
+ existir no contexto do WS — passe `App` no `extra` do `orfeuWsContext` (ver
182
+ [estrutura-bootstrap.md](estrutura-bootstrap.md)). Instanciar o módulo à parte, de forma preguiçosa, também
183
+ funciona, mas duplica clientes.