@acropole/skills 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/README.md +181 -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 +80 -0
  9. package/skills/acropole/references/arquitetura.md +174 -0
  10. package/skills/acropole/references/fluxos/app-novo.md +34 -0
  11. package/skills/acropole/references/fluxos/doctor.md +55 -0
  12. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  13. package/skills/acropole/references/fluxos/revisar.md +56 -0
  14. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  15. package/skills/acropole/scripts/doctor.mjs +439 -0
  16. package/skills/angular/SKILL.md +155 -0
  17. package/skills/angular/references/armadilhas.md +99 -0
  18. package/skills/angular/references/dados.md +251 -0
  19. package/skills/angular/references/estrutura.md +279 -0
  20. package/skills/angular/references/features.md +219 -0
  21. package/skills/angular/references/testes-build.md +257 -0
  22. package/skills/angular/scripts/checar.mjs +182 -0
  23. package/skills/angular/scripts/nucleo.mjs +227 -0
  24. package/skills/apollo/SKILL.md +226 -0
  25. package/skills/apollo/references/armadilhas.md +99 -0
  26. package/skills/apollo/references/envelope-erros.md +120 -0
  27. package/skills/apollo/references/estrutura-bootstrap.md +310 -0
  28. package/skills/apollo/references/schema-resolvers.md +183 -0
  29. package/skills/apollo/references/subscriptions.md +224 -0
  30. package/skills/apollo/references/testes-build.md +181 -0
  31. package/skills/apollo/scripts/checar.mjs +160 -0
  32. package/skills/apollo/scripts/nucleo.mjs +227 -0
  33. package/skills/docker/SKILL.md +102 -0
  34. package/skills/docker/references/modelos.md +251 -0
  35. package/skills/docker/references/porques.md +286 -0
  36. package/skills/documentacao/SKILL.md +146 -0
  37. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  38. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  39. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  40. package/skills/documentacao/references/modelo-readme.md +75 -0
  41. package/skills/documentacao/scripts/checar.mjs +454 -0
  42. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  43. package/skills/express/SKILL.md +156 -0
  44. package/skills/express/references/dados.md +180 -0
  45. package/skills/express/references/estrutura.md +157 -0
  46. package/skills/express/references/middlewares.md +227 -0
  47. package/skills/express/references/rotas-erros.md +286 -0
  48. package/skills/express/references/testes-deploy.md +154 -0
  49. package/skills/express/scripts/checar.mjs +115 -0
  50. package/skills/express/scripts/nucleo.mjs +227 -0
  51. package/skills/fastapi/SKILL.md +132 -0
  52. package/skills/fastapi/references/banco.md +197 -0
  53. package/skills/fastapi/references/estrutura.md +325 -0
  54. package/skills/fastapi/references/integracoes.md +145 -0
  55. package/skills/fastapi/references/rotas-erros.md +140 -0
  56. package/skills/fastapi/references/testes-deploy.md +190 -0
  57. package/skills/fastapi/scripts/checar.mjs +108 -0
  58. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  59. package/skills/hefesto/SKILL.md +119 -0
  60. package/skills/hefesto/references/conceitos.md +131 -0
  61. package/skills/hefesto/references/diagnostico.md +70 -0
  62. package/skills/hefesto/references/fluxo.md +122 -0
  63. package/skills/hefesto/references/preparar-app.md +105 -0
  64. package/skills/orfeu/SKILL.md +162 -0
  65. package/skills/orfeu/references/angular-api.md +201 -0
  66. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  67. package/skills/orfeu/references/angular-recipes.md +474 -0
  68. package/skills/orfeu/references/angular.md +212 -0
  69. package/skills/orfeu/references/diferencas.md +56 -0
  70. package/skills/orfeu/references/node-api.md +354 -0
  71. package/skills/orfeu/references/node-armadilhas.md +158 -0
  72. package/skills/orfeu/references/node-recipes.md +541 -0
  73. package/skills/orfeu/references/node.md +204 -0
  74. package/skills/orfeu/references/python-api.md +346 -0
  75. package/skills/orfeu/references/python-recipes.md +479 -0
  76. package/skills/orfeu/references/python.md +240 -0
  77. package/skills/orfeu/scripts/checar.mjs +126 -0
  78. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  79. package/skills/trismegisto/SKILL.md +194 -0
  80. package/skills/trismegisto/references/angular-api.md +2788 -0
  81. package/skills/trismegisto/references/angular-exports.md +4020 -0
  82. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  83. package/skills/trismegisto/references/angular-types.md +492 -0
  84. package/skills/trismegisto/references/angular.md +390 -0
  85. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  86. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  87. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  88. package/skills/trismegisto/references/spine-api.md +1530 -0
  89. package/skills/trismegisto/references/spine-recipes.md +581 -0
  90. package/skills/trismegisto/references/spine.md +343 -0
  91. package/skills/trismegisto/scripts/checar.mjs +216 -0
  92. package/skills/trismegisto/scripts/nucleo.mjs +227 -0
@@ -0,0 +1,155 @@
1
+ ---
2
+ name: angular
3
+ description: "Arquitetura de apps Angular da plataforma (22+, standalone, shell spine): estrutura de pastas, bootstrap, registro de tela por router_id, serviços GraphQL/REST com unwrap, signals, formulários, testes e build. Use ao criar ou alterar um app Angular, a parte de rotas/estado/dados de uma tela, um serviço de dados ou o build. A parte visual da tela (componentes hm-*, tokens, tema, ícones) é da skill trismegisto — numa tela nova use as duas; login/sessão/token é da orfeu."
4
+ ---
5
+
6
+ # angular
7
+
8
+ Como os apps Angular da plataforma são montados e como uma tela nova entra neles. Vale para apps
9
+ **Angular 22+, standalone, com o shell `@trismegisto/spine`** e autenticação via `@orfeu/angular`
10
+ contra o Argos.
11
+
12
+ Skills vizinhas (não duplicar o conteúdo delas aqui):
13
+
14
+ | Assunto | Skill |
15
+ | --- | --- |
16
+ | Componentes `hm-*`, tema, tokens `--hm-*`, ícones, layout/shell/sidebar, modal, catálogo de mensagens | `trismegisto` |
17
+ | Sessão, login/callback, `provideAuth`, guards, token e cabeçalhos (`x-access-token`), auditoria | `orfeu` |
18
+ | O servidor GraphQL que o app consome (schema, envelope `{ status, message, data }`, resolvers) | `apollo` |
19
+ | Backends REST em Node / Python | `express` / `fastapi` |
20
+
21
+ Ainda não coberto por nenhuma skill: React, Strawberry, Fastify, Django, Flask.
22
+
23
+ > **Antes de dar por terminado:** `node scripts/checar.mjs <arquivos alterados>` (caminho relativo a esta skill: instalada, fica em `~/.claude/skills/angular/scripts/checar.mjs`; `--help` lista as regras, `--json` para máquina).
24
+ >
25
+ > **Mexeu numa tela ou rota?** Rode também a skill `documentacao`: revise o README da tela e registre a revisão.
26
+
27
+ ## Mapa rápido de um app
28
+
29
+ ```
30
+ meu-app/
31
+ ├── angular.json # builder @angular/build:application, configs prod/dev/homol/local/development
32
+ ├── codegen.ts # graphql-codegen (tipos + TypedDocumentNode), roda à mão
33
+ ├── Dockerfile # estágios dev / build / site (só o /dist estático)
34
+ ├── eslint.a11y.config.js # regras de acessibilidade de template (angular-eslint)
35
+ ├── tsconfig.json # strict, paths src/* e package.json (sem baseUrl), resolveJsonModule
36
+ └── src/
37
+ ├── main.ts # applyRuntimeEnvironment(environment) + bootstrapApplication
38
+ ├── index.html # lang="pt-BR", favicon, tela #app-loading
39
+ ├── styles.scss # só estilos globais do app, com tokens --hm-*
40
+ ├── core/ # app.config.ts, core.providers.ts, core.component.ts, environments/
41
+ ├── app/
42
+ │ ├── features/ # uma pasta por tela + features.routes.ts (mapa router_id -> tela lazy)
43
+ │ └── services/ # <dominio>/<dominio>.graphql|.service.ts|.models.ts|.generated.ts
44
+ ├── shared/ # componentes/utilitários reaproveitados entre telas do app
45
+ └── assets/ # imagens (logo.svg, favicon), fontes, tema próprio do app
46
+ ```
47
+
48
+ Detalhes e exemplos completos: [references/estrutura.md](references/estrutura.md).
49
+
50
+ ## Regras essenciais
51
+
52
+ **Bootstrap** (`src/core/`)
53
+ - `main.ts` chama `applyRuntimeEnvironment(environment)` (de `@trismegisto/spine`) **antes** do
54
+ `bootstrapApplication`: deriva `redirectUrl`/`postLogoutRedirectUri` da origem atual e, atrás do
55
+ proxy, `authority` e endpoints GraphQL ainda com `CHANGE_ME`. Não grave URL de callback fixa.
56
+ - `app.config.ts`: `provideZoneChangeDetection({ eventCoalescing: true })` (uma vez só),
57
+ `provideRouter(APP_ROUTES)`, `...CORE_PROVIDERS`, `provideUi(spineConfig)`, `provideAuth(...)`,
58
+ `provideAutoService(...)` se o client usa auto-serviço, `provideShell({ appComponents, packageInfo })`.
59
+ - `core.providers.ts`: `provideAnimationsAsync()`, `provideHttpClient(withInterceptorsFromDi())`
60
+ (obrigatório: ativa o interceptor do spine que manda `x-route-id` para a auditoria) e
61
+ `provideGraphql({ endpoints: environment.graphql })`.
62
+ - `zone.js` continua nos `polyfills`. Zoneless só com migração dedicada e testada.
63
+
64
+ **Telas** (`src/app/features/`)
65
+ - Toda tela é registrada em `features.routes.ts` como `ComponentRoute` com `id` = **`router_id`** da
66
+ linha do roteador do client no Argos (não o `route_id` da página) e `load` lazy. A URL vem do Argos,
67
+ não do nome da pasta. Ver [references/features.md](references/features.md).
68
+ - Componentes standalone (sem `standalone: true`, já é o padrão), `ChangeDetectionStrategy.OnPush`,
69
+ `inject()` em vez de construtor, `input()`/`output()`/`model()`, `viewChild()` etc.
70
+ - Estado local em `signal()`; derivado em `computed()`; efeito colateral em `effect()`; valor
71
+ derivado e editável que reseta com a fonte em `linkedSignal()`. Nunca `mutate`.
72
+ - Templates com `@if`/`@for`/`@switch`/`@let`; `@for` sempre com `track item.id`; `[class.x]`/
73
+ `[style.x]` em vez de `ngClass`/`ngStyle`.
74
+ - Formulários reativos (`FormGroup`/`FormControl` com `nonNullable: true`). Desabilitar campo é
75
+ `control.disable()`, nunca `[disabled]` junto de `[formControl]`/`formControlName`. Data de formulário
76
+ em horário local (`toISOString()` é UTC: depois das 21h em UTC-3 vira o dia seguinte).
77
+ - Ação destrutiva (excluir, revogar, sobrescrever) pede confirmação (`HermesDialogService.confirm`).
78
+ - Credencial nunca em `localStorage`/`sessionStorage`; se precisar guardar, em memória (service root).
79
+
80
+ **Dados** (`src/app/services/<dominio>/`)
81
+ - Componente nunca fala com Apollo/HttpClient direto: fala com um service `providedIn: 'root'`.
82
+ - GraphQL: `private readonly gql = injectGraphqlClient('<namedClient>')` +
83
+ `unwrap((await this.gql.query(Doc, vars, options)).campo)`. Documentos tipados pelo codegen
84
+ (`<dominio>.graphql` -> `<dominio>.generated.ts`, commitados).
85
+ - O toast do envelope é automático (mutation sempre; query só em falha não-404; subscription nunca).
86
+ Não repita toast manual; em lote use `{ silenceEnvelope: true }` e avise uma vez.
87
+ - Falha vira `GraphqlEnvelopeError` (com `status`): trate como estado de erro da tela, não como lista
88
+ vazia. **Toda carga tem estado de erro com "Tentar novamente"**; `subscribe` sem `error` e `await` sem
89
+ `try/finally` deixam o skeleton girando para sempre.
90
+ - Trocou o item selecionado ou o filtro: descarte a resposta atrasada (`switchMap` ou contador de
91
+ sequência). Ver [references/dados.md](references/dados.md).
92
+
93
+ **Build e qualidade**
94
+ - Build de produção: `ng build --configuration prod` (é a `defaultConfiguration`, então `ng build`
95
+ basta). Outras: `dev`, `homol`, `local` (troca o `environment.ts` por `fileReplacements`) e
96
+ `development` (só para `ng serve`).
97
+ - `angular.json` > `styles`: `src/styles.scss`, `@trismegisto/tokens/tokens.css`,
98
+ `@trismegisto/core/core.css`.
99
+ - Testes: Karma + Jasmine (`@angular/build:karma`, `ng test`), com specs fixos do core (`app.config`,
100
+ `core.providers`, `environments`, `features.routes`). Acessibilidade: `lint:a11y` e `axe:check`, com os
101
+ mesmos arquivos em todo app. Ver [references/testes-build.md](references/testes-build.md).
102
+ - Padrão do app inteiro (pastas do repo, portas, ambientes, scripts, saúde dos backends):
103
+ skill `acropole` (`references/arquitetura.md`).
104
+
105
+ ## Receita: tela nova "pedidos"
106
+
107
+ 1. Cadastre a rota/roteador do client no Argos (painel administrativo, aba de roteadores do client) e
108
+ anote o `router_id`.
109
+ 2. Escreva as operações em `src/app/services/pedidos/pedidos.graphql` e rode `npm run codegen` com o
110
+ GraphQL local de pé.
111
+ 3. Crie `src/app/services/pedidos/pedidos.service.ts` (`injectGraphqlClient` + `unwrap`).
112
+ 4. Crie `src/app/features/pedidos/pedidos.component.ts` (OnPush, signals, componentes `hm-*`).
113
+ 5. Registre em `features.routes.ts`:
114
+ ```ts
115
+ {
116
+ id: '<router_id>',
117
+ load: () => import('src/app/features/pedidos/pedidos.component').then(m => m.PedidosComponent),
118
+ document: { load: () => import('src/app/features/pedidos/README.md').then(m => m.default) }, // opcional
119
+ },
120
+ ```
121
+ 6. Nada muda em `app.config.ts`: o `provideShell` mescla as telas do app com as da lib.
122
+ 7. O `features.routes.spec.ts` confere que todo `load()` resolve e que os `id` são UUID únicos (sem
123
+ diferenciar maiúsculas) — [references/testes-build.md](references/testes-build.md).
124
+
125
+ ## Armadilhas reais (resumo)
126
+
127
+ - **`router_id` x `route_id`**: o `id` do `ComponentRoute` é o `router_id`. Usar o id da página faz a
128
+ tela nunca abrir. `route_id`/`component` no `ComponentRoute` são campos **deprecated** (ainda lidos).
129
+ - **Getter/método alimentando `@for`** de componentes compostos (accordion, tabs, stepper, data grid):
130
+ devolve array novo a cada ciclo e quebra expandir/recolher. Use `computed()`.
131
+ - **`input()` não popula `ngOnChanges`**: `changes['x']` vira código morto; reaja com `effect()`.
132
+ - **`new DatePipe('pt-BR')`** sem `registerLocaleData(localePt)` no `main.ts` lança NG0701.
133
+ - **`HermesToastService` sem `<hm-toast-stack />`** montado uma vez no componente raiz: o toast é
134
+ aceito e nunca aparece. (O `NotificationService` do spine já é renderizado pelo layout.)
135
+ - **`provideHttpClient()` sem `withInterceptorsFromDi()`** perde o `x-route-id` da auditoria.
136
+ - **Mensagem do backend** (`message` do envelope) é texto: nunca via `innerHTML`.
137
+ - **`@defer`** encolhe chunks de telas lazy, mas **não** resolve aviso de budget `initial` (o grosso
138
+ é o CSS global do DS e o shell/auth carregados antes de qualquer rota).
139
+ - **`tsconfig.app.json` com `files: ["src/main.ts"]`**: só compila o que é alcançável a partir das
140
+ rotas. Tela fora do `features.routes.ts` não quebra o build — e apodrece em silêncio.
141
+ - **`.npmrc` copiado no Dockerfile** grava credencial na imagem; os pacotes vêm do npm público.
142
+
143
+ Lista completa com contexto: [references/armadilhas.md](references/armadilhas.md).
144
+
145
+ ## Referências
146
+
147
+ - [references/estrutura.md](references/estrutura.md) — pastas, `main.ts`, `app.config.ts`,
148
+ `core.providers.ts`, environments, `tsconfig`, `angular.json`, convenções de nome e imports.
149
+ - [references/features.md](references/features.md) — registro no shell, rotas próprias/públicas,
150
+ documentação por tela, anatomia de componente, signals, templates, formulários, a11y, i18n.
151
+ - [references/dados.md](references/dados.md) — GraphQL (`injectGraphqlClient`, `unwrap`, envelope,
152
+ subscriptions), codegen, REST, estado de carregamento/erro, notificações.
153
+ - [references/testes-build.md](references/testes-build.md) — specs (TestBed + Apollo falso), lint de
154
+ acessibilidade, axe, configurações de build, budgets, Docker.
155
+ - [references/armadilhas.md](references/armadilhas.md) — o que NÃO fazer e divergências entre apps.
@@ -0,0 +1,99 @@
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` tipado como `AuthConfig` do `@orfeu/angular`, `GraphqlEndpoint` do spine |
86
+ | Campos de login | interface própria com `silentRenew`/`useRefreshToken`/`postLogoutRedirectUri`/`responseType` | só o `AuthConfig` (os outros a lib não lê) |
87
+ | Imports absolutos | `baseUrl: "./"` (+ `ignoreDeprecations: "6.0"`) x `paths` | `paths` com `src/*` e `package.json`, sem `baseUrl` |
88
+ | Scripts | apps sem `start:homol`, com `start:prod`, `dev` sem `--configuration=dev` | o mesmo conjunto em todo app (`references/estrutura.md`) |
89
+ | Ferramentas de a11y | `@angular-eslint/*` avulsos, `@axe-core/puppeteer`, três `axe-check` diferentes | `angular-eslint` + `axe-core` com versão exata; `axe-check.js` e `eslint.a11y.config.js` idênticos |
90
+ | Ajuste de URL em runtime | `applyRuntimeEnvironment` x cálculo manual no `main.ts` | `applyRuntimeEnvironment` (+ só o específico do app) |
91
+ | Services | `src/app/services/<dominio>/` x dentro de `features/` | `src/app/services/<dominio>/` |
92
+ | Componentes | signals/`input()`/`inject()` x `@Input` + construtor + `standalone: true` | signals/`input()`/`inject()` |
93
+ | Notificação manual | `NotificationService` (spine) x `HermesToastService` + `hm-toast-stack` | um por app; com `HermesToastService`, monte o stack na raiz |
94
+ | `anyComponentStyle` | 4/8 kB, 16/32 kB, 24/32 kB | 16/32 kB |
95
+ | Budget `initial` | 2.1 MB x 4 MB de aviso | 4 MB aviso / 5 MB erro |
96
+ | Dockerfile | com e sem `.npmrc` copiado | sem `.npmrc` |
97
+ | Testes | apps com dezenas de specs x apps sem nenhuma | spec para toda tela nova/alterada |
98
+ | Lint | só `eslint.a11y.config.*` (sem lint principal) | ao menos o lint de a11y; lint principal é bem-vindo, separado |
99
+ | 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`.