@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,95 @@
1
+ # O que NÃO fazer (armadilhas reais) e divergências entre apps
2
+
3
+ ## Armadilhas
4
+
5
+ ### Roteamento e shell
6
+ - **`id` com o `route_id` da página.** O `ComponentRoute.id` é o `router_id` (linha do roteador do
7
+ client). Com o id errado a tela simplesmente não abre (cai na home/sem permissão).
8
+ - **Tentar sobrescrever uma tela base do shell** (ex.: a home) registrando o mesmo `router_id` em
9
+ `appComponents`: o `provideShell` rejeita. Peça a opção à lib (`trismegisto`) em vez de
10
+ contornar.
11
+ - **Tela não registrada não quebra o build.** `tsconfig.app.json` compila só o que é alcançável a
12
+ partir do `main.ts`; tela tirada do `features.routes.ts` deixa de ser checada e apodrece. Ao
13
+ desregistrar algo temporariamente, comente o motivo e o critério de volta.
14
+
15
+ ### Environment e bootstrap
16
+ - **URL de callback/logoff fixa no environment.** O servidor exige `redirect_uri` absoluto e o app
17
+ pode estar sob prefixo; use `applyRuntimeEnvironment` no `main.ts`.
18
+ - **Reescrever `environment` depois do bootstrap** ou esperar que uma mutação feita em um lugar seja
19
+ vista por serviços de chunks lazy. Derive tudo no `main.ts` antes do bootstrap; valor dinâmico de
20
+ verdade vai num `InjectionToken`.
21
+ - **`provideZoneChangeDetection` duplicado** (no `bootstrapApplication` e no `appConfig`). Um só, no
22
+ `appConfig`, com `eventCoalescing: true`.
23
+ - **Remover `zone.js`** "porque tudo é OnPush". Zoneless exige migração dedicada e testada; libs de
24
+ terceiros podem depender do patch do zone.
25
+ - **`provideHttpClient()` sem `withInterceptorsFromDi()`**: o interceptor do spine que envia
26
+ `x-route-id` para a auditoria deixa de rodar, sem erro visível.
27
+ - **`new DatePipe('pt-BR')` / `| date: ...: 'pt-BR'` sem `registerLocaleData(localePt)`**: NG0701 em
28
+ runtime (o Angular só embute `en-US`).
29
+
30
+ ### Componentes e templates
31
+ - **Getter ou método devolvendo array novo para `@for`** de componentes compostos (accordion, tabs,
32
+ stepper, wizard, menu, linhas de data grid): eles rastreiam identidade dos filhos e resetam/congelam.
33
+ Sempre `computed()`.
34
+ - **`track item` ou `track $index`** em lista recriada a cada carga: re-renderiza tudo e perde estado.
35
+ Use `track item.id`.
36
+ - **Checar `changes['x']` em `ngOnChanges` depois de migrar `x` para `input()`**: signal input não
37
+ popula `SimpleChanges`; o ramo vira código morto. Use `effect()`.
38
+ - **Ícone com `(click)`** como única forma de acionar algo: não recebe foco nem teclado. Use
39
+ `<button type="button" aria-label="...">` com o ícone dentro.
40
+ - **Reimplementar foco preso/Esc em modal do DS**: já vem pronto.
41
+ - **`[disabled]` junto de `[formControl]`/`formControlName`**: use `control.disable()`.
42
+ - **`toISOString().slice(0, 10)` como data do formulário ou "hoje"**: é o dia em UTC (vira o dia seguinte à
43
+ noite no Brasil). Monte a data local.
44
+ - **Ação destrutiva sem confirmação** (excluir no clique da linha): confirme com `HermesDialogService.confirm`.
45
+ - **Credencial em `localStorage`/`sessionStorage`**: fica exposta a qualquer script. Em memória (service root).
46
+ - **`ngClass`/`ngStyle`, `*ngIf`/`*ngFor`, `@Input`/`@Output`, injeção por construtor,
47
+ `standalone: true` explícito**: formato antigo; ainda existe em telas migradas às pressas, não copie.
48
+
49
+ ### Dados
50
+ - **Ler `result.data.campo.data` sem `unwrap`**: um `status: 403/500` dentro de HTTP 200 vira "lista
51
+ vazia". Sempre `unwrap`.
52
+ - **`?? null` ou `console.error` silencioso** no lugar de estado de erro: o usuário fica sem saber que
53
+ falhou.
54
+ - **Skeleton infinito**: `subscribe` sem `error` ou `await` sem `try/finally` deixam `carregando` em `true`
55
+ quando a chamada falha. Toda carga tem estado de erro com "Tentar novamente".
56
+ - **Dado do item anterior na tela**: trocou a seleção/o filtro e a resposta antiga chegou depois da nova.
57
+ `switchMap` ou contador de sequência (ver `dados.md`).
58
+ - **Toast manual depois de mutation**: o envelope já avisou; sai duplicado. Lote usa `silenceEnvelope`.
59
+ - **`innerHTML` com `message` do backend**: é texto, não HTML.
60
+ - **Apollo/HttpClient injetado no componente** ou `graphql.config.ts` próprio do app: tudo passa pelo
61
+ service do domínio e pelo `provideGraphql` do spine.
62
+ - **`as unknown as X` em massa** para encaixar tipo gerado: corrija o `.graphql`/modelo.
63
+ - **Esquecer o codegen**: mudou `.graphql` ou schema e não rodou `npm run codegen` — o build passa
64
+ com tipos velhos ou quebra longe da causa. Gere e commite os `*.generated.ts` junto.
65
+
66
+ ### Notificações
67
+ - **`HermesToastService` sem `<hm-toast-stack />`** no componente raiz: o serviço aceita o toast e
68
+ nada aparece. O `NotificationService` do spine não tem esse problema (o layout o renderiza), mas só
69
+ existe dentro da área privada.
70
+
71
+ ### Build e entrega
72
+ - **Achar que `@defer` resolve o aviso de budget `initial`.** Não resolve (é CSS global + shell/auth).
73
+ - **Copiar `.npmrc` / credencial de registry no Dockerfile.**
74
+ - **`ng build` esperando configuração de dev**: o padrão do build é `prod`; o padrão do `serve` é
75
+ `development`.
76
+
77
+ ## Divergências encontradas entre os apps (e o padrão recomendado)
78
+
79
+ | Ponto | Variações vistas | Recomendado |
80
+ | --- | --- | --- |
81
+ | Builder | `@angular/build:*` x `@angular-devkit/build-angular:*` | `@angular/build:*` |
82
+ | Animações | `provideAnimationsAsync()` x `importProvidersFrom(BrowserAnimationsModule)` | `provideAnimationsAsync()` |
83
+ | Change detection global | `provideZoneChangeDetection` uma vez x repetido no `main.ts` | uma vez, em `app.config.ts`, com `eventCoalescing` |
84
+ | Auth | `provideAuth(environment.authorizationServer)` x `AUTH_CONFIG` + `APP_INITIALIZER` | `provideAuth` |
85
+ | Environment | `src/core/environments/` com `authorizationServer` x `src/environments/` com `auth` | `src/core/environments/`, `authorizationServer`, `GraphqlEndpoint` do spine |
86
+ | Ajuste de URL em runtime | `applyRuntimeEnvironment` x cálculo manual no `main.ts` | `applyRuntimeEnvironment` (+ só o específico do app) |
87
+ | Services | `src/app/services/<dominio>/` x dentro de `features/` | `src/app/services/<dominio>/` |
88
+ | Componentes | signals/`input()`/`inject()` x `@Input` + construtor + `standalone: true` | signals/`input()`/`inject()` |
89
+ | Notificação manual | `NotificationService` (spine) x `HermesToastService` + `hm-toast-stack` | um por app; com `HermesToastService`, monte o stack na raiz |
90
+ | `anyComponentStyle` | 4/8 kB, 16/32 kB, 24/32 kB | 16/32 kB |
91
+ | Budget `initial` | 2.1 MB x 4 MB de aviso | 4 MB aviso / 5 MB erro |
92
+ | Dockerfile | com e sem `.npmrc` copiado | sem `.npmrc` |
93
+ | Testes | apps com dezenas de specs x apps sem nenhuma | spec para toda tela nova/alterada |
94
+ | Lint | só `eslint.a11y.config.*` (sem lint principal) | ao menos o lint de a11y; lint principal é bem-vindo, separado |
95
+ | Documentação de tela | `document` com `README.md`/`ESPECIFICACAO.md` x nenhuma | `document` para telas operacionais |
@@ -0,0 +1,251 @@
1
+ # Dados: GraphQL, REST, estado, erros e notificações
2
+
3
+ Regra de ouro: **componente fala com service; service fala com o backend.** Nenhum componente injeta
4
+ `Apollo` ou `HttpClient`.
5
+
6
+ ## Configuração (uma vez por app)
7
+
8
+ `provideGraphql({ endpoints: environment.graphql })` em `core.providers.ts` cria um cliente Apollo
9
+ nomeado por entrada de `environment.graphql` (`{ namedClient, http, ws? }`). O comportamento é fixo e
10
+ igual em todo app — não há opções:
11
+
12
+ - token de sessão em `x-access-token` no HTTP e no `connection_init` do WebSocket (origem do token:
13
+ `orfeu`);
14
+ - HTTP em lote (`HttpBatchLink`) — o servidor precisa aceitar lote (`apollo`);
15
+ - `fetchPolicy: 'no-cache'` por padrão (painel de operação quer dado fresco);
16
+ - subscriptions por `graphql-ws` (só se o endpoint tem `ws`), reconexão ilimitada com backoff; 401/
17
+ 4401/4403 recria os sockets; aba que volta de segundo plano longo também;
18
+ - **toast automático do envelope** `{ status, message, data }` (ver abaixo).
19
+
20
+ Não crie `graphql.config.ts` próprio no app: essa configuração já existiu copiada em cada app e
21
+ divergiu; agora vive só no spine.
22
+
23
+ ## Service GraphQL
24
+
25
+ ```ts
26
+ import { Injectable } from '@angular/core';
27
+ import { GraphqlCallOptions, injectGraphqlClient, unwrap } from '@trismegisto/spine/graphql';
28
+ import { map } from 'rxjs';
29
+ import {
30
+ CriarPedidoDocument, ListarPedidosDocument, PedidoAtualizadoDocument,
31
+ type CriarPedidoMutationVariables, type ListarPedidosQueryVariables,
32
+ } from 'src/app/services/pedidos/pedidos.generated';
33
+
34
+ /** Operações do domínio `pedidos` (pedidos.graphql). Cada método confere o envelope com `unwrap`. */
35
+ @Injectable({ providedIn: 'root' })
36
+ export class PedidosService {
37
+ private readonly gql = injectGraphqlClient('pedidos'); // = environment.graphql.<chave>.namedClient
38
+
39
+ async listar(variables: ListarPedidosQueryVariables = {}, options?: GraphqlCallOptions) {
40
+ return unwrap((await this.gql.query(ListarPedidosDocument, variables, options)).pedidos);
41
+ }
42
+
43
+ async criar(variables: CriarPedidoMutationVariables, options?: GraphqlCallOptions) {
44
+ return unwrap((await this.gql.mutate(CriarPedidoDocument, variables, options)).criarPedido);
45
+ }
46
+
47
+ /** Eventos (subscription não tem envelope). */
48
+ aoAtualizar() {
49
+ return this.gql.subscribe(PedidoAtualizadoDocument).pipe(map((d) => d.pedidoAtualizado));
50
+ }
51
+ }
52
+ ```
53
+
54
+ - `injectGraphqlClient(nome)` precisa de contexto de injeção (campo da classe ou construtor).
55
+ - `query`/`mutate` devolvem `Promise` do `data` já tipado pelo `TypedDocumentNode` (sem `<any>`).
56
+ `subscribe` devolve `Observable` e ignora mensagens sem `data`.
57
+ - Erro de transporte ou `errors[]` do GraphQL **rejeita** a Promise.
58
+ - Repasse `options?: GraphqlCallOptions` em todo método: é por ali que a tela silencia o toast.
59
+ - Convenção de nome: método no vocabulário da tela; o service esconde nome de campo do schema.
60
+
61
+ ### O envelope e o `unwrap`
62
+
63
+ Todo GraphQL da plataforma devolve `{ status, message, data }` em cada operação raiz. **O status vem
64
+ no payload, não no HTTP**: uma resposta 200 pode trazer `status: 403`.
65
+
66
+ `unwrap(envelope)`:
67
+ - devolve `data` quando `status` é 2xx (ou texto que não seja `error`/`failed`/`failure`/`fail`, ou
68
+ ausente);
69
+ - lança `GraphqlEnvelopeError(status, message)` quando o envelope veio `null` (resolver estourou) ou o
70
+ status é de falha.
71
+
72
+ Na tela, `GraphqlEnvelopeError.status` decide o estado: 403 = sem acesso, 404 = vazio, 5xx = tentar de
73
+ novo. Ler `data` sem `unwrap` é o bug clássico de "lista vazia" onde devia aparecer "sem permissão".
74
+
75
+ Outros exports úteis: `GraphqlEnvelope<T>`, `isEnvelopeOk(status)`, `envelopesOf(data)`,
76
+ `failedEnvelopes(data)`, `wsReconnected$` (emite o `namedClient` quando o socket **reconecta** — use
77
+ para ressincronizar o que pode ter sido publicado durante a queda).
78
+
79
+ ### Toast automático do envelope
80
+
81
+ | Operação | Quando avisa |
82
+ | --- | --- |
83
+ | mutation | sempre em falha (com texto padrão se o backend não mandar `message`); em sucesso quando há `message` |
84
+ | query | só em falha, e nunca em 404 |
85
+ | subscription | nunca |
86
+
87
+ Consequências:
88
+ - **Não** dispare toast manual de sucesso/erro depois de uma mutation: sai duplicado.
89
+ - `{ silenceEnvelope: true }` quando a tela trata a falha sozinha: consulta periódica/sondagem,
90
+ gravação em lote (avise o resultado consolidado uma vez) ou fluxo que monta relatório próprio
91
+ (nesse caso o service pode devolver o envelope cru, sem `unwrap`, e documentar isso).
92
+ - No `catch` da tela, não repita a mensagem; só ajuste o estado (`error: () => undefined // o toast já saiu do envelope`).
93
+ - `message` é texto do backend: exiba como texto, nunca via `innerHTML`.
94
+
95
+ ### Fallback em consulta
96
+
97
+ Para cards de painel que devem mostrar "sem dado" em vez de erro, centralize no service:
98
+
99
+ ```ts
100
+ async function orFallback<T>(run: () => Promise<T>, fallback: T): Promise<T> {
101
+ try { return await run(); } catch { return fallback; } // o motivo já saiu no toast do envelope
102
+ }
103
+ ```
104
+
105
+ Use só em consulta; mutation sempre lança.
106
+
107
+ ### Paginação em pedaços
108
+
109
+ Listagem grande: o service expõe um `Observable` que pede página por página (`offset`/`limit`) e
110
+ emite `{ items, fetched, total, done }`; cancelar a inscrição para de pedir (flag `cancelled` no
111
+ teardown). A tela vai preenchendo a grade conforme chega.
112
+
113
+ ## Codegen
114
+
115
+ `codegen.ts` na raiz do app:
116
+
117
+ ```ts
118
+ import type { CodegenConfig } from '@graphql-codegen/cli';
119
+
120
+ const scalars = { ID: 'string', JSON: 'unknown' };
121
+
122
+ const config: CodegenConfig = {
123
+ schema: process.env['MEU_APP_GRAPHQL_URL'] ?? 'http://localhost:4000/graphql', // GraphQL local
124
+ documents: 'src/app/services/**/*.graphql',
125
+ generates: {
126
+ 'src/app/services/schema.generated.ts': {
127
+ plugins: ['typescript'],
128
+ config: { enumsAsTypes: true, scalars },
129
+ },
130
+ 'src/app/services/': {
131
+ preset: 'near-operation-file',
132
+ presetConfig: { extension: '.generated.ts', baseTypesPath: '~src/app/services/schema.generated' },
133
+ plugins: ['typescript-operations', 'typed-document-node'],
134
+ config: { scalars },
135
+ },
136
+ },
137
+ };
138
+ export default config;
139
+ ```
140
+
141
+ devDependencies: `@graphql-codegen/cli`, `near-operation-file-preset`, `typescript`,
142
+ `typescript-operations`, `typed-document-node`. Runtime: `@apollo/client`, `apollo-angular`,
143
+ `graphql`, `graphql-ws`.
144
+
145
+ - Quem muda o schema ou um `.graphql` roda `npm run codegen` com o GraphQL **local** de pé
146
+ (introspecção habilitada só em desenvolvimento) e **commita** os `*.generated.ts`. O build não gera nada.
147
+ - Um `.graphql` por domínio, ao lado do service; fragments para campos repetidos; comentário no topo
148
+ lembrando de rodar o codegen.
149
+ - Tipos de input vêm de `schema.generated.ts` (`import type { PedidoInput } ...`); modelos que a tela
150
+ usa e que não são 1:1 com o schema ficam em `<dominio>.models.ts`.
151
+ - Evite `as unknown as X` para "consertar" tipo gerado: ajuste o `.graphql` ou o modelo.
152
+
153
+ ## REST
154
+
155
+ Para o que não passa pelo GraphQL (API administrativa, upload multipart, download de binário):
156
+
157
+ ```ts
158
+ import { HttpClient, HttpErrorResponse } from '@angular/common/http';
159
+ import { Injectable, inject } from '@angular/core';
160
+ import { AuthorizationService } from '@orfeu/angular/core';
161
+ import { GraphqlEnvelope, unwrap } from '@trismegisto/spine/graphql';
162
+ import { firstValueFrom } from 'rxjs';
163
+ import { environment } from 'src/core/environments/environment';
164
+
165
+ @Injectable({ providedIn: 'root' })
166
+ export class AnexosService {
167
+ private readonly http = inject(HttpClient);
168
+ private readonly auth = inject(AuthorizationService); // @orfeu/angular/core
169
+
170
+ async enviar(pedidoId: string, arquivo: File): Promise<Anexo> {
171
+ const body = new FormData();
172
+ body.append('file', arquivo, arquivo.name);
173
+ const token = this.auth.getToken();
174
+ const headers = token ? { 'x-access-token': token } : {};
175
+ try {
176
+ return unwrap(await firstValueFrom(
177
+ this.http.post<GraphqlEnvelope<Anexo>>(`${environment.minhaApiUrl}/pedidos/${pedidoId}/anexos`, body, { headers }),
178
+ ));
179
+ } catch (err) {
180
+ if (err instanceof HttpErrorResponse) unwrap(err.error as GraphqlEnvelope<Anexo> | null);
181
+ throw err;
182
+ }
183
+ }
184
+ }
185
+ ```
186
+
187
+ - `firstValueFrom` para expor `Promise` (mesma forma dos services GraphQL).
188
+ - Se a rota REST devolve o mesmo envelope, reuse `unwrap` (inclusive no corpo do erro HTTP).
189
+ - Base URL vem do environment (e, se for derivada, do `main.ts`); nunca cravada no service.
190
+ - Tipar a resposta: `http.get<any>` é dívida, não padrão.
191
+ - Cabeçalhos de sessão/auditoria e como o backend os lê: `orfeu`.
192
+
193
+ ## Estado de carregamento e erro na tela
194
+
195
+ - Três signals por fonte: dado, `carregando`, `erro` (ou um `computed` agregando vários
196
+ `carregando`). Skeleton enquanto carrega; estado vazio distinto de estado de erro.
197
+ - **Toda carga tem saída de erro** com a ação "Tentar novamente" (que chama a mesma carga). Skeleton que
198
+ nunca some é o sintoma clássico de um destes dois:
199
+ - `subscribe({ next })` sem `error` (ou `subscribe(fn)`): o erro morre no observable e `carregando`
200
+ fica `true` para sempre;
201
+ - `await` sem `try/finally`: a exceção pula o `carregando.set(false)`.
202
+ - Service devolve `Promise` -> `async/await` com `try/catch/finally` no componente. Se precisar de
203
+ cancelamento ao sair da tela, `from(promise).pipe(takeUntilDestroyed(this.destroyRef))`.
204
+ - **Resposta atrasada não sobrescreve a atual.** Ao trocar o item selecionado ou o filtro, a resposta da
205
+ consulta anterior pode chegar depois da nova e pintar a tela com o dado errado. Descarte a velha:
206
+ `switchMap` (Observable) ou um contador de sequência (Promise). `resource()`/`rxResource()` já fazem isso.
207
+
208
+ ```ts
209
+ private seq = 0;
210
+ readonly detalhe = signal<Pedido | null>(null);
211
+ readonly carregando = signal(false);
212
+ readonly erro = signal<string | null>(null);
213
+
214
+ async abrir(id: string) {
215
+ const minha = ++this.seq; // só a última chamada pode escrever
216
+ this.carregando.set(true);
217
+ this.erro.set(null);
218
+ this.detalhe.set(null); // não mostra o item anterior enquanto carrega
219
+ try {
220
+ const d = await this.pedidos.get(id);
221
+ if (minha === this.seq) this.detalhe.set(d);
222
+ } catch (e) {
223
+ if (minha === this.seq) this.erro.set(e instanceof Error ? e.message : 'Falha ao carregar');
224
+ } finally {
225
+ if (minha === this.seq) this.carregando.set(false);
226
+ }
227
+ }
228
+ ```
229
+
230
+ ```html
231
+ @if (carregando()) {
232
+ <hm-skeleton shape="list" label="Carregando pedido" />
233
+ } @else if (erro(); as texto) {
234
+ <hm-alert variant="error" heading="Não foi possível carregar o pedido">
235
+ {{ texto }}
236
+ <hm-button actions emphasis="medium" (clicked)="abrir(idAtual())">Tentar novamente</hm-button>
237
+ </hm-alert>
238
+ } @else if (detalhe(); as d) { … }
239
+ ```
240
+ - Tempo real: subscription + `takeUntilDestroyed()`; ao `wsReconnected$`, recarregue a consulta.
241
+ - Sem store global: estado de tela fica na tela; estado compartilhado entre telas do app vai num
242
+ service `providedIn: 'root'` com signals.
243
+
244
+ ## Notificações
245
+
246
+ - Resultado de operação GraphQL: o toast do envelope já resolve (acima).
247
+ - Aviso manual (ação local, validação, operação composta): `NotificationService` de
248
+ `@trismegisto/spine/notification` (`addNotification({ timer, hermesAlertType, message })`,
249
+ `resolveAlertType(status)`) — renderizado pelo layout do shell — ou `HermesToastService` de
250
+ `@trismegisto/angular`, que exige `<hm-toast-stack />` no componente raiz. Escolha um por app.
251
+ - API e variantes dos dois: `trismegisto`.
@@ -0,0 +1,260 @@
1
+ # Estrutura, bootstrap e configuração
2
+
3
+ ## Pastas
4
+
5
+ | Pasta | Conteúdo |
6
+ | --- | --- |
7
+ | `src/main.ts` | Ajuste do environment em runtime + `bootstrapApplication(CoreComponent, appConfig)` |
8
+ | `src/core/` | `app.config.ts`, `core.providers.ts`, `core.component.ts` (raiz), `environments/`, e o que for global do app (ex.: `app.routes.ts` quando há rota pública, `news.ts` para novidades do shell) |
9
+ | `src/app/features/<tela>/` | Uma pasta por tela (componente principal, subcomponentes, modais, `README.md` de uso) |
10
+ | `src/app/features/features.routes.ts` | O mapa `router_id` -> tela lazy (ver `features.md`) |
11
+ | `src/app/services/<dominio>/` | Contrato de dados do domínio: `<dominio>.graphql`, `<dominio>.service.ts`, `<dominio>.models.ts`, `<dominio>.generated.ts` |
12
+ | `src/app/services/schema.generated.ts` | Tipos do schema GraphQL (codegen) |
13
+ | `src/shared/` | Componentes, pipes e utilitários usados por mais de uma tela do app |
14
+ | `src/assets/` | `images/logo.svg`, `images/favicon.svg`, `favicon.ico`, fontes e tema próprio (`assets/theme/`) |
15
+ | `src/testing/` | Helpers de spec (envelopes falsos, nome da operação) |
16
+
17
+ Regras:
18
+ - **Services de dados ficam em `src/app/services/`**, não dentro da pasta da tela — a tela importa o
19
+ service; o service não conhece a tela. (Há app que ainda guarda service dentro de `features/`;
20
+ não repetir.)
21
+ - Pasta de feature segue o **domínio**, em kebab-case e em inglês ou português de forma consistente no
22
+ app (`pedidos/`, `order-history/`). A URL vem do Argos, então renomear pasta não muda rota.
23
+ - Imports **sempre absolutos a partir de `src/`** (`import { X } from 'src/app/services/pedidos/pedidos.service'`),
24
+ graças a `"baseUrl": "./"` no `tsconfig.json`. Exceções do próprio Angular: `templateUrl`,
25
+ `styleUrl` e `@use` de SCSS, que são relativos ao arquivo.
26
+
27
+ ## Nomes
28
+
29
+ - Arquivos: `pedidos.component.ts|html|scss`, `pedido-modal.component.ts`, `pedidos.service.ts`,
30
+ `pedidos.models.ts`, `pedidos.graphql`, `pedidos.generated.ts`, `*.spec.ts` ao lado.
31
+ - Classes: `PedidosComponent`, `PedidoModalComponent`, `PedidosService`.
32
+ - Seletor: prefixo `app-` (`app-pedidos`); raiz `core-root`.
33
+ - Tipos de dado de modal: `PedidoModalData` (entrada) e `PedidoModalResult` (saída).
34
+
35
+ ## `main.ts`
36
+
37
+ ```ts
38
+ import { bootstrapApplication } from '@angular/platform-browser';
39
+ import { registerLocaleData } from '@angular/common';
40
+ import localePt from '@angular/common/locales/pt';
41
+ import { applyRuntimeEnvironment } from '@trismegisto/spine';
42
+
43
+ import { CoreComponent } from 'src/core/core.component';
44
+ import { appConfig } from 'src/core/app.config';
45
+ import { environment } from 'src/core/environments/environment';
46
+
47
+ // Necessário se alguma tela usa DatePipe/CurrencyPipe com 'pt-BR' (senão NG0701).
48
+ registerLocaleData(localePt);
49
+
50
+ // Callback/logoff/authority/GraphQL derivados de onde o app está rodando.
51
+ const { origin, basePath, behindProxy, unset } = applyRuntimeEnvironment(environment);
52
+
53
+ // Só se o app tiver uma URL própria além das que o spine deriva (ex.: uma API REST no mesmo prefixo).
54
+ if (behindProxy && unset(environment.minhaApiUrl)) {
55
+ environment.minhaApiUrl = `${origin}${basePath}/server`;
56
+ }
57
+
58
+ bootstrapApplication(CoreComponent, appConfig)
59
+ .then(() => document.getElementById('app-loading')?.remove())
60
+ .catch((err) => console.error(err));
61
+ ```
62
+
63
+ - `applyRuntimeEnvironment` sempre reescreve `redirectUrl` (`<origem><prefixo>/callback`) e
64
+ `postLogoutRedirectUri` (`.../logoff`). Atrás de proxy (URL sem porta) também deriva `authority` e
65
+ cada endpoint GraphQL **ainda sem valor real** (vazio ou contendo `CHANGE_ME`). URL explícita no
66
+ environment sempre ganha.
67
+ - Mexa no objeto `environment` **só aqui, antes do bootstrap**. Valor que precisa ser recalculado
68
+ depois e lido por serviços em chunks lazy vai num `InjectionToken`, não em mutação do environment.
69
+ - A remoção do `#app-loading` (definido no `index.html`) é opcional, mas recomendada.
70
+
71
+ ## `src/core/app.config.ts`
72
+
73
+ ```ts
74
+ import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
75
+ import { provideRouter } from '@angular/router';
76
+ import { provideAuth } from '@orfeu/angular/core';
77
+ import { provideUi, SpineConfig } from '@trismegisto/spine';
78
+ import { provideShell, APP_ROUTES } from '@trismegisto/spine/shell';
79
+ import { provideAutoService } from '@trismegisto/spine/auto-service';
80
+ import packageInfo from 'package.json';
81
+
82
+ import { environment } from 'src/core/environments/environment';
83
+ import { components as featuresComponents } from 'src/app/features/features.routes';
84
+ import { CORE_PROVIDERS } from 'src/core/core.providers';
85
+
86
+ const spineConfig: SpineConfig = {
87
+ clientId: environment.authorizationServer.clientId,
88
+ appName: 'Meu App',
89
+ logo: { light: 'assets/images/logo.svg', alt: 'Meu App' },
90
+ technicalDocs: !environment.production, // mostra ESPECIFICACAO.md das telas fora de produção
91
+ };
92
+
93
+ export const appConfig: ApplicationConfig = {
94
+ providers: [
95
+ provideZoneChangeDetection({ eventCoalescing: true }),
96
+ provideRouter(APP_ROUTES),
97
+ ...CORE_PROVIDERS,
98
+ provideUi(spineConfig),
99
+ provideAuth(environment.authorizationServer),
100
+ provideAutoService({ adminApi: environment.adminApi }), // só se o client usa o template de auto-serviço
101
+ provideShell({ appComponents: featuresComponents, packageInfo }),
102
+ // providers de libs de terceiros (gráficos, editor) entram aqui, com import() lazy quando der:
103
+ // provideEchartsCore({ echarts: () => import('echarts') }),
104
+ ],
105
+ };
106
+ ```
107
+
108
+ - `provideUi()` registra o catálogo de ícones e o tema; opções de tema/logo/fontes ficam na
109
+ `trismegisto`. `provideAuth()` e suas opções (ex.: `{ eagerInit: false }` para app com
110
+ página pública) ficam na `orfeu`.
111
+ - `provideZoneChangeDetection` **uma vez**, aqui. Não repita no `bootstrapApplication`.
112
+ - `import packageInfo from 'package.json'` depende de `resolveJsonModule` + `baseUrl: "./"`; o shell
113
+ usa a versão do app na tela "sobre".
114
+ - Formato legado a evitar: `{ provide: AUTH_CONFIG, useValue }` + `APP_INITIALIZER` chamando
115
+ `auth.initialize()` à mão. Use `provideAuth()`.
116
+
117
+ ## `src/core/core.providers.ts`
118
+
119
+ ```ts
120
+ import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http';
121
+ import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';
122
+ import { provideGraphql } from '@trismegisto/spine/graphql';
123
+ import { environment } from 'src/core/environments/environment';
124
+
125
+ export const CORE_PROVIDERS = [
126
+ provideAnimationsAsync(),
127
+ provideHttpClient(withInterceptorsFromDi()), // interceptor do spine: x-route-id na auditoria
128
+ provideGraphql({ endpoints: environment.graphql }), // um cliente Apollo nomeado por entrada
129
+ ];
130
+ ```
131
+
132
+ App sem GraphQL omite o `provideGraphql`. Prefira `provideAnimationsAsync()` a
133
+ `importProvidersFrom(BrowserAnimationsModule)` (carrega animações sob demanda).
134
+
135
+ ## `src/core/core.component.ts`
136
+
137
+ ```ts
138
+ import { ChangeDetectionStrategy, Component } from '@angular/core';
139
+ import { RouterOutlet } from '@angular/router';
140
+ import { ToastStackComponent } from '@trismegisto/angular';
141
+
142
+ @Component({
143
+ selector: 'core-root',
144
+ imports: [RouterOutlet, ToastStackComponent],
145
+ changeDetection: ChangeDetectionStrategy.OnPush,
146
+ // hm-toast-stack: necessário se alguma tela usa HermesToastService.
147
+ template: `<router-outlet /><hm-toast-stack />`,
148
+ })
149
+ export class CoreComponent {}
150
+ ```
151
+
152
+ Não monte modal/side panel/notificação do shell aqui: o layout do spine já os renderiza. O título da
153
+ aba vem do `index.html` (ou `Title` no componente, se precisar mudar em runtime).
154
+
155
+ ## Environments
156
+
157
+ Arquivos em `src/core/environments/`:
158
+
159
+ | Arquivo | Uso |
160
+ | --- | --- |
161
+ | `environment.config.ts` | Interfaces (`Environment`, `AuthorizationServer`) |
162
+ | `environment.ts` | Base (é o que os imports referenciam) |
163
+ | `environment.prod.ts`, `.homol.ts`, `.dev.ts`, `.local.ts` | Trocados por `fileReplacements` na configuração de build homônima |
164
+
165
+ Campos (só os nomes; os valores são de cada ambiente):
166
+
167
+ ```ts
168
+ import type { GraphqlEndpoint } from '@trismegisto/spine/graphql'; // não redeclarar
169
+
170
+ export interface AuthorizationServer {
171
+ authority: string; redirectUrl: string; postLogoutRedirectUri: string;
172
+ clientId: string; realmId: string; scope: string;
173
+ silentRenew: boolean; useRefreshToken: boolean;
174
+ }
175
+
176
+ export interface Environment {
177
+ production: boolean;
178
+ authorizationServer: AuthorizationServer;
179
+ graphql: Record<string, GraphqlEndpoint>; // { namedClient, http, ws? } por backend
180
+ adminApi: string; // API administrativa do Argos (auto-serviço)
181
+ }
182
+ ```
183
+
184
+ - A chave de `graphql` e o `namedClient` costumam ser o mesmo nome (`pedidos: { namedClient: 'pedidos', ... }`).
185
+ - Use `CHANGE_ME` em URL que deve ser derivada em runtime atrás do proxy.
186
+ - Segredo nunca entra em environment: tudo ali vai para o bundle público.
187
+ - Layout antigo `src/environments/` (fora de `core/`) e nomes de campo diferentes (`auth` em vez de
188
+ `authorizationServer`) existem em apps mais velhos; não copiar.
189
+
190
+ ## `tsconfig.json`
191
+
192
+ Base: `strict: true`, `noImplicitOverride`, `noPropertyAccessFromIndexSignature`, `noImplicitReturns`,
193
+ `noFallthroughCasesInSwitch`, `resolveJsonModule`, `isolatedModules`, `moduleResolution: "bundler"`,
194
+ `baseUrl: "./"`, `target/module: ES2022`; `angularCompilerOptions` com `strictTemplates`,
195
+ `strictInjectionParameters`, `strictInputAccessModifiers`.
196
+
197
+ `tsconfig.app.json`: `files: ["src/main.ts"]` + `include: ["src/**/*.d.ts"]`. Se o app importa `.md`
198
+ como texto, declare em `src/markdown.d.ts`:
199
+
200
+ ```ts
201
+ declare module '*.md' {
202
+ const content: string;
203
+ export default content;
204
+ }
205
+ ```
206
+
207
+ ## `angular.json` (pontos relevantes)
208
+
209
+ ```jsonc
210
+ "build": {
211
+ "builder": "@angular/build:application",
212
+ "options": {
213
+ "outputPath": "dist/meu-app",
214
+ "browser": "src/main.ts",
215
+ "polyfills": ["zone.js"],
216
+ "inlineStyleLanguage": "scss",
217
+ "assets": [{ "glob": "**/*", "input": "src/assets", "output": "assets" }],
218
+ "styles": [
219
+ "src/styles.scss",
220
+ "@trismegisto/tokens/tokens.css",
221
+ "@trismegisto/core/core.css"
222
+ ],
223
+ "loader": { ".md": "text" } // só se houver documentação por tela
224
+ },
225
+ "configurations": {
226
+ "prod": { "budgets": [ /* ver testes-build.md */ ], "outputHashing": "all",
227
+ "baseHref": "/meu-app/",
228
+ "fileReplacements": [{ "replace": "src/core/environments/environment.ts",
229
+ "with": "src/core/environments/environment.prod.ts" }] },
230
+ "homol": { "...": "idem com environment.homol.ts" },
231
+ "dev": { "optimization": false, "sourceMap": true, "...": "environment.dev.ts" },
232
+ "local": { "optimization": false, "sourceMap": true, "...": "environment.local.ts" },
233
+ "development": { "optimization": false, "sourceMap": true }
234
+ },
235
+ "defaultConfiguration": "prod"
236
+ },
237
+ "serve": { "builder": "@angular/build:dev-server", "defaultConfiguration": "development" },
238
+ "test": { "builder": "@angular/build:karma" }
239
+ ```
240
+
241
+ - Use o builder `@angular/build:*`; `@angular-devkit/build-angular:*` é o formato antigo.
242
+ - `baseHref` = prefixo sob o qual o app é servido (o `applyRuntimeEnvironment` lê de `document.baseURI`).
243
+ - `cli.cache.environment: "all"` liga o cache do CLI também no build (útil no Docker).
244
+
245
+ ## Scripts do `package.json`
246
+
247
+ ```json
248
+ "start": "ng serve --port 4200",
249
+ "dev": "ng serve --configuration=dev --port 4200 --no-hmr",
250
+ "start:local": "ng serve --configuration=local --host 0.0.0.0 --port 4200 --no-hmr",
251
+ "build": "ng build",
252
+ "build:dev": "ng build --configuration dev",
253
+ "build:homol": "ng build --configuration homol",
254
+ "test": "ng test",
255
+ "lint:a11y": "eslint --config eslint.a11y.config.js \"src/**/*.html\"",
256
+ "axe:check": "node scripts/axe-check.js",
257
+ "codegen": "graphql-codegen --config codegen.ts"
258
+ ```
259
+
260
+ Cada app usa uma porta fixa própria no dev-server para não colidir com os outros.