@acropole/skills 1.6.1 → 1.7.1

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 (37) hide show
  1. package/README.md +10 -8
  2. package/agents/revisor-deploy.md +9 -4
  3. package/bin/install.js +41 -9
  4. package/package.json +1 -1
  5. package/skills/acropole/SKILL.md +2 -2
  6. package/skills/acropole/references/arquitetura.md +3 -3
  7. package/skills/acropole/references/fluxos/app-novo.md +2 -2
  8. package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +51 -15
  9. package/skills/angular/SKILL.md +34 -15
  10. package/skills/angular/references/armadilhas.md +16 -6
  11. package/skills/angular/references/estrutura.md +118 -50
  12. package/skills/angular/references/testes-build.md +25 -17
  13. package/skills/auto-servico/references/roteiros.md +1 -1
  14. package/skills/auto-servico/references/tools.md +1 -1
  15. package/skills/docker/SKILL.md +17 -7
  16. package/skills/docker/references/modelos.md +23 -9
  17. package/skills/docker/references/porques.md +19 -6
  18. package/skills/hefesto/SKILL.md +53 -28
  19. package/skills/hefesto/references/conceitos.md +16 -8
  20. package/skills/hefesto/references/diagnostico.md +12 -2
  21. package/skills/hefesto/references/fluxo.md +51 -29
  22. package/skills/hefesto/references/mcp-roteiros.md +52 -9
  23. package/skills/hefesto/references/preparar-app.md +22 -6
  24. package/skills/orquestracao/SKILL.md +3 -1
  25. package/skills/orquestracao/scripts/coord.sh +10 -2
  26. package/skills/trismegisto/SKILL.md +57 -16
  27. package/skills/trismegisto/references/angular-api.md +3666 -64
  28. package/skills/trismegisto/references/angular-exports.md +8562 -2554
  29. package/skills/trismegisto/references/angular-recipes.md +315 -0
  30. package/skills/trismegisto/references/angular-types.md +92 -0
  31. package/skills/trismegisto/references/angular.md +67 -10
  32. package/skills/trismegisto/references/catalogo/icones.json +7 -0
  33. package/skills/trismegisto/references/catalogo/seletores.json +12102 -3443
  34. package/skills/trismegisto/references/catalogo/tokens.json +114 -0
  35. package/skills/trismegisto/references/spine-api.md +1113 -157
  36. package/skills/trismegisto/references/spine-recipes.md +72 -35
  37. package/skills/trismegisto/references/spine.md +54 -27
@@ -7,40 +7,66 @@ em `angular.md` e `angular-api.md`. Nomes como `MeuApp`, `principal`,
7
7
 
8
8
  ## 1. Bootstrap completo
9
9
 
10
- `src/environments/environment.ts` (valores `CHANGE_ME` são derivados em tempo de execução por
11
- `applyRuntimeEnvironment` quando o app está atrás de proxy, sem porta na URL):
10
+ Imagem única (desde a 3.1.0): um build `production` serve todos os ambientes. O `environment.ts` é **um só**
11
+ (o que não muda + URLs vazias); o que varia por ambiente fica em `src/brand/config/<ambiente>.json` e chega em
12
+ runtime como `config.json` (o deploy copia o do ambiente; no `ng serve`, `scripts/use-config.mjs <amb>`).
13
+ Detalhes de `angular.json`, scripts e Docker: skill **angular** (`references/estrutura.md`).
14
+
15
+ `src/environments/environment.ts` (URLs vazias são derivadas em tempo de execução por
16
+ `applyRuntimeEnvironment` quando o app está atrás de proxy, sem porta na URL; `redirectUrl` e
17
+ `postLogoutRedirectUri` são sempre derivados):
12
18
 
13
19
  ```ts
14
20
  import type { GraphqlEndpoint } from '@trismegisto/spine/graphql';
15
21
 
16
22
  export const environment = {
17
- production: false,
18
- adminApi: 'https://auth.exemplo.com/argos/admin/api',
23
+ production: false, // true vem do config.json de homol/prod
24
+ adminApi: '',
19
25
  authorizationServer: {
20
- authority: 'https://auth.exemplo.com/argos',
26
+ authority: '',
21
27
  realmId: '<realmId do app no Argos>',
22
28
  clientId: '<clientId do app no Argos>',
23
- redirectUrl: 'CHANGE_ME', // derivado: <origem><base href>/callback
24
- postLogoutRedirectUri: 'CHANGE_ME', // derivado: <origem><base href>/logoff
29
+ redirectUrl: '', // derivado: <origem><base href>/callback
30
+ postLogoutRedirectUri: '', // derivado: <origem><base href>/logoff
25
31
  scope: 'openid profile email offline_access',
26
32
  },
27
33
  graphql: {
28
- principal: { namedClient: 'principal', http: 'CHANGE_ME', ws: 'CHANGE_ME' },
34
+ principal: { namedClient: 'principal', http: '', ws: '' },
29
35
  } satisfies Record<string, GraphqlEndpoint>,
30
36
  };
31
37
  ```
32
38
 
39
+ `src/brand/config/homol.json` (só o que muda; mesclado chave a chave, arrays e valores simples substituem):
40
+
41
+ ```json
42
+ {
43
+ "production": true,
44
+ "adminApi": "https://homol.exemplo.com/argos/admin/api",
45
+ "authorizationServer": { "authority": "https://homol.exemplo.com/argos" }
46
+ }
47
+ ```
48
+
33
49
  `src/main.ts`:
34
50
 
35
51
  ```ts
52
+ import { isDevMode } from '@angular/core';
36
53
  import { bootstrapApplication } from '@angular/platform-browser';
37
- import { applyRuntimeEnvironment } from '@trismegisto/spine';
38
- import { AppComponent } from './app/app.component';
39
- import { appConfig } from './app/app.config';
54
+ import { applyRuntimeEnvironment, loadRuntimeConfig } from '@trismegisto/spine';
40
55
  import { environment } from './environments/environment';
41
56
 
42
- applyRuntimeEnvironment(environment);
43
- bootstrapApplication(AppComponent, appConfig).catch((err) => console.error(err));
57
+ // Sem top-level await (Zone.js): encadeie. required: !isDevMode() — não environment.production, que só fica
58
+ // certo depois do config.json.
59
+ loadRuntimeConfig(environment, { required: !isDevMode() })
60
+ .then(async () => {
61
+ applyRuntimeEnvironment(environment); // DEPOIS do config.json, ANTES do bootstrap
62
+ // Import dinâmico: app.config lê o environment ao carregar (clientId, URLs).
63
+ const [{ appConfig }, { AppComponent }] = await Promise.all([
64
+ import('./app/app.config'),
65
+ import('./app/app.component'),
66
+ ]);
67
+ return bootstrapApplication(AppComponent, appConfig);
68
+ })
69
+ .catch((err) => console.error(err));
44
70
  ```
45
71
 
46
72
  `src/app/app.config.ts`:
@@ -91,7 +117,11 @@ export class AppComponent {}
91
117
  `angular.json` (trechos de `architect.build.options`):
92
118
 
93
119
  ```json
94
- "assets": [{ "glob": "**/*", "input": "src/assets", "output": "assets" }],
120
+ "assets": [
121
+ { "glob": "**/*", "input": "src/assets", "output": "assets" },
122
+ { "glob": "*.json", "input": "src/brand/config", "output": "brand/config" },
123
+ { "glob": "config.json", "input": "src", "output": "/" }
124
+ ],
95
125
  "styles": [
96
126
  "node_modules/@trismegisto/tokens/dist/tokens.css",
97
127
  "node_modules/@trismegisto/core/dist/core.css",
@@ -471,7 +501,7 @@ export class ResumosSettingsComponent {
471
501
  ```
472
502
 
473
503
  As seções do app aparecem depois das do spine e antes de "Sobre". Não repita as chaves de `SPINE_SETTINGS_KEYS`
474
- (`aparencia`, `acessibilidade`, `regiao`, `atalhos`, `ajuda`, `notificacoes`, `dados`, `conta`, `mfa`, `sessoes`,
504
+ (`aparencia`, `acessibilidade`, `regiao`, `atalhos`, `ajuda`, `notificacoes`, `dados`, `conta`, `mfa`, `sessoes`, `grupos`,
475
505
  `sobre`; `seguranca` é alias antigo de `mfa`). Abrir por código: `inject(SpineSettingsService).open('resumos')`.
476
506
 
477
507
  Antes de criar seção própria, veja se o spine já oferece (`SpineConfig.features`, `references/spine.md` §3.2):
@@ -480,25 +510,13 @@ inatividade, tela inicial, crachá padrão, atividade da conta e agente de IA ta
480
510
 
481
511
  ## 11. Novidades da versão
482
512
 
483
- ```ts
484
- import { provideSpineNews } from '@trismegisto/spine';
485
-
486
- provideSpineNews([
487
- {
488
- id: 'equipes-2026-10', // trocar o id faz reaparecer para todo mundo
489
- until: '2026-12-31', // opcional: some depois desta data
490
- slides: [
491
- {
492
- title: 'Equipes',
493
- text: 'Agora dá para organizar pessoas em equipes.',
494
- illustration: { icon: 'users', satellites: [{ icon: 'user', label: 'Membros' }] },
495
- },
496
- ],
497
- },
498
- ]),
499
- ```
500
-
501
- Abre sozinha uma vez por navegador (depois do tour) e fica no menu do perfil enquanto vigente.
513
+ Não ficam no código: quem administra o app cadastra no Argos (tela **Novidades** do auto-serviço, na raiz do menu, ou
514
+ a aba Novidades do cliente no painel central). Três tipos: **informativo** (só texto), **implementação** (abertura e a
515
+ lista "O que mudou") e **alteração** (antes e agora, lado a lado). Mais título, resumo, publicação (no futuro =
516
+ agendada), validade e público (grupos de acesso; vazio = todos). O spine lê de `argos-admin /me/news` com
517
+ `SPINE_ADMIN_API` (o `provideAutoService` já fornece): avisa uma vez por novidade na entrada, mostra "Novidades (N)" no
518
+ menu do perfil e o card do Início, e o painel lista por mês, com busca, "Não lidas" e "Favoritas" (no navegador).
519
+ Abrir por código: `inject(SpineNewsService).showAll()`.
502
520
 
503
521
  ## 12. Marca em componente
504
522
 
@@ -538,7 +556,26 @@ Trocar em tempo de execução (lib + spine juntos): `inject(HermesI18nService).s
538
556
  `inject(SpinePreferencesService).setLanguage('es')` para também salvar a escolha da pessoa. Ler um texto do
539
557
  spine em código: `inject(SPINE_MESSAGES).header.search`.
540
558
 
541
- ## 14. Testes de tela
559
+ ## 14. Tela com formulário: alterações não salvas e skip link
560
+
561
+ ```ts
562
+ // app.config.ts
563
+ provideUi({ clientId, features: { skipLink: true, unsavedChanges: true } }),
564
+ ```
565
+ ```ts
566
+ import { registerSpineUnsavedChanges } from '@trismegisto/spine/layout';
567
+
568
+ export class PedidoPage {
569
+ readonly form = new FormGroup({ /* … */ });
570
+ readonly #alteracoes = registerSpineUnsavedChanges(() => this.form.dirty); // presa à aba desta tela
571
+ salvar(): void { /* … grava; depois */ this.form.markAsPristine(); }
572
+ }
573
+ ```
574
+ No spine, use `registerSpineUnsavedChanges` (não o `hermesUnsavedChangesGuard` nas rotas): quem fecha a tela é a aba
575
+ do workspace, não a navegação. O resto do formulário segue `angular-recipes.md` §41 (resumo de erros, indicador de
576
+ salvamento, anúncio).
577
+
578
+ ## 15. Testes de tela
542
579
 
543
580
  As telas não dependem do layout: teste-as isoladas, trocando os serviços do spine por dublês.
544
581
 
@@ -9,7 +9,7 @@ O spine é o **esqueleto pronto** de um app Angular: cabeçalho (marca, busca de
9
9
  tema, perfil), menu lateral montado da árvore de rotas do servidor de autorização (Argos), área de trabalho
10
10
  em abas (`hm-workspace`), barra da página (título, descrição, trilha, favoritar, copiar link, documentação),
11
11
  telas de login/callback/saída/sem permissão/bloqueado, modal, painel lateral e toasts por serviço, painel
12
- de configurações, tour de boas-vindas, novidades e atalhos de teclado. O app entrega **só as telas**; o resto
12
+ de configurações, novidades e atalhos de teclado. O app entrega **só as telas**; o resto
13
13
  vem do spine.
14
14
 
15
15
  Ele fica na ponta da cadeia `tokens ← icons ← primitives ← core ← angular ← spine` e é **acoplado à
@@ -29,7 +29,7 @@ Se as telas tiverem documentação (`document.load` com `import('./README.md')`)
29
29
 
30
30
  | Import | Para quê |
31
31
  |---|---|
32
- | `@trismegisto/spine` | `provideUi`, `SpineConfig`/`SPINE_CONFIG`, `Route` + `routerIdOf`, `applyRuntimeEnvironment`, `SPINE_ADMIN_API`, `provideSpineNews`, i18n (`SPINE_MESSAGES`, `provideSpineMessages`, catálogos), `ThemeService`, `DensityService`, `ThemePresetService`, `SpinePreferencesService`, `SpineQuickAccessService`, logo/favicon (`SpineLogoConfig`, `resolveSpineLogo`, `applySpineFavicon`) |
32
+ | `@trismegisto/spine` | `provideUi`, `SpineConfig`/`SPINE_CONFIG`, `Route` + `routerIdOf`, `applyRuntimeEnvironment`, `SPINE_ADMIN_API`, i18n (`SPINE_MESSAGES`, `provideSpineMessages`, catálogos), `ThemeService`, `DensityService`, `ThemePresetService`, `SpinePreferencesService`, `SpineQuickAccessService`, logo/favicon (`SpineLogoConfig`, `resolveSpineLogo`, `applySpineFavicon`) |
33
33
  | `@trismegisto/spine/shell` | `APP_ROUTES`, `PUBLIC_ROUTES`, `PRIVATE_ROUTES`, `provideShell`, `ShellOptions`, telas públicas e de estado |
34
34
  | `@trismegisto/spine/routing` | `ComponentRoute`, `RouteDocument`, `COMPONENT_ROUTES`, `ViewGuard`, `RouteIdInterceptor` + `ROUTE_ID_HEADER`/`CLIENT_ID_HEADER`, `LoggerService`, `ComponentDistributorService`, resolução de cadeia (`resolveRouteChain`, `findFirstNavigable`…) |
35
35
  | `@trismegisto/spine/layout` | `LayoutComponent` (`spine-layout`), `SPINE_BRAND`, `provideSettingsSection`, `SpineSettingsService`, `SpineDocsService`, `SpineNewsService`, `OnboardingService`, `ShortcutService` e as peças do layout |
@@ -45,23 +45,40 @@ Se as telas tiverem documentação (`document.load` com `import('./README.md')`)
45
45
  ### 3.1 `main.ts`
46
46
 
47
47
  ```ts
48
+ import { isDevMode } from '@angular/core';
48
49
  import { bootstrapApplication } from '@angular/platform-browser';
49
- import { applyRuntimeEnvironment } from '@trismegisto/spine';
50
- import { AppComponent } from './app/app.component';
51
- import { appConfig } from './app/app.config';
50
+ import { applyRuntimeEnvironment, loadRuntimeConfig } from '@trismegisto/spine';
52
51
  import { environment } from './environments/environment';
53
52
 
54
- applyRuntimeEnvironment(environment); // ANTES do bootstrap
55
- bootstrapApplication(AppComponent, appConfig).catch((err) => console.error(err));
53
+ // Sem top-level await (Zone.js): encadeie. required: !isDevMode() — não environment.production, que só fica
54
+ // certo depois do config.json.
55
+ loadRuntimeConfig(environment, { required: !isDevMode() })
56
+ .then(async () => {
57
+ applyRuntimeEnvironment(environment); // DEPOIS do config.json, ANTES do bootstrap
58
+ // Import dinâmico: app.config lê o environment ao carregar (clientId, URLs).
59
+ const [{ appConfig }, { AppComponent }] = await Promise.all([
60
+ import('./app/app.config'),
61
+ import('./app/app.component'),
62
+ ]);
63
+ return bootstrapApplication(AppComponent, appConfig);
64
+ })
65
+ .catch((err) => console.error(err));
56
66
  ```
57
67
 
68
+ `loadRuntimeConfig(environment, { file?, required? })` (3.1.0; do `@trismegisto/primitives`, reexportado aqui)
69
+ busca `config.json` (ou `file`) relativo ao `<base href>` e o mescla no `environment` (objetos chave a chave;
70
+ arrays e valores simples substituem). É o que permite **uma imagem por versão**: o build não sabe o ambiente, o
71
+ deploy põe ao lado do `index.html` a cópia de `src/brand/config/<ambiente>.json`. Com `required`, falta ou JSON
72
+ inválido rejeita a promise e o app não sobe; sem, só avisa. App sem o shell (ex.: tela de login que é o próprio
73
+ provedor OAuth) importa direto do `@trismegisto/primitives` e não usa `applyRuntimeEnvironment`.
74
+
58
75
  `applyRuntimeEnvironment(environment)` deriva do endereço em que o app está rodando:
59
76
  - **sempre:** `authorizationServer.redirectUrl = <origem><base href>/callback` e
60
77
  `postLogoutRedirectUri = <origem><base href>/logoff` (o servidor exige `redirect_uri` absoluto e o app pode
61
78
  viver sob um prefixo);
62
79
  - **sem porta na URL** (atrás de proxy reverso): `authority = <origem>/argos` e cada endpoint GraphQL **ainda
63
80
  sem valor** (vazio ou contendo `CHANGE_ME`) vira `<origem><base href>/graphql` (HTTP e WS). URL explícita no
64
- environment sempre vence.
81
+ environment (inclusive vinda do `config.json`) sempre vence.
65
82
  Devolve `{ origin, basePath, behindProxy, unset }` para o que for específico do app.
66
83
 
67
84
  ### 3.2 `app.config.ts`
@@ -97,8 +114,9 @@ export const appConfig: ApplicationConfig = {
97
114
 
98
115
  O que cada provider faz:
99
116
 
100
- - **`provideUi(config?: SpineConfig)`** — registra o catálogo de ícones **inteiro** (`HERMES_ICONS`; o app
101
- não precisa de `provideHermesIcons`), aplica tema/família/densidade/fonte no `<body>` (`ThemeService`),
117
+ - **`provideUi(config?: SpineConfig)`** — registra os ícones do próprio spine (`SPINE_ICONS`) e carrega o catálogo
118
+ inteiro **sob demanda** (`provideHermesIconLoader`, desde a 3.3.1): ícone do app não registrado aparece quando o
119
+ chunk chega (para desenhar já no 1º quadro, `provideHermesIcons(...)` com os do app); aplica tema/família/densidade/fonte no `<body>` (`ThemeService`),
102
120
  fornece `SPINE_CONFIG` e usa `hermes_<clientId>` como prefixo de **todas** as chaves salvas (tema, menu
103
121
  lateral, abas do workspace, idioma, fuso, novidades, favoritos…): apps na mesma origem não misturam
104
122
  preferências. Aplica `favicon` no bootstrap se configurado. Opções de `SpineConfig`:
@@ -118,13 +136,15 @@ O que cada provider faz:
118
136
 
119
137
  | Campo | O que liga |
120
138
  |---|---|
121
- | `aiAgent: { servers: SpineMcpServer[] }` | Sessões › "Conectar um agente de IA": token de aplicação + `.mcp.json` pronto (precisa de `SPINE_ADMIN_API`) |
139
+ | `mcpConnect: { servers: SpineMcpServer[] }` | Sessões › "Conectar um agente de IA": token de aplicação + `.mcp.json` pronto (precisa de `SPINE_ADMIN_API`). `onlyBadges`/`exceptBadges` em cada servidor (nome do badge) mostram só os servidores do nível da pessoa; com um só, sem seletor |
122
140
  | `accountActivity: true` | MFA › "Atividade da conta": entradas e tentativas que falharam (últimos 90 dias) |
123
141
  | `idleTimeout: true \| { min?, max? }` | Conta › "Encerrar por inatividade" (com `max`, some o "Nunca") |
124
142
  | `startPage: true` | Conta › "Tela inicial" depois do login: início, um favorito ou a última tela |
125
143
  | `defaultBadge: true` | Conta › "Crachá padrão" (nível de acesso do login, guardado no Argos) |
126
144
  | `notices: { types: SpineNoticeType[] }` | seção Notificações: liga/desliga cada tipo de aviso e o aviso do navegador; o app emite com `SpineNoticesService.notify(tipo, { title, body?, url?, intent? })` (`@trismegisto/spine/layout`) |
127
145
  | `accountPreferences: true` | guarda as preferências (aparência, região, acessibilidade, favoritos, tela inicial…) também na conta do Argos |
146
+ | `skipLink: true` | link "Pular para o conteúdo" (`hm-skip-link`) como primeira parada do Tab, levando à área de trabalho |
147
+ | `unsavedChanges: true` | aviso de alterações não salvas: a tela registra com `registerSpineUnsavedChanges(() => form.dirty)` (`@trismegisto/spine/layout`, num campo da classe); fechar a aba/painel dela ou trocar de tela dentro dela pergunta antes, e o navegador avisa ao recarregar |
128
148
 
129
149
  - **`provideRouter(APP_ROUTES)`** — `APP_ROUTES` = `PUBLIC_ROUTES` (`/login`, `/callback`, `/logoff`,
130
150
  `/blocked`, `''` → `login`) + `{ path: '', component: LayoutComponent, canActivate/canActivateChild:
@@ -140,10 +160,16 @@ O que cada provider faz:
140
160
  se um `id` do app repetir um id das telas base do shell.
141
161
  - **`provideAutoService({ adminApi })`** — liga as 6 telas do auto-serviço (Início, Grupos, Aplicações,
142
162
  Cliente, Auditoria, Tentativas de login) pelo `source_template_router_id` do template do Argos, todas **lazy**, e fornece
143
- `SPINE_ADMIN_API` (usado também pelo painel de configurações para os tokens de aplicação). O app não declara
144
- nada disso em `features.routes.ts`: basta o client estar vinculado ao template de auto-serviço no Argos.
145
- Sem auto-serviço, o painel de configurações ainda pode listar tokens se o app fornecer
146
- `{ provide: SPINE_ADMIN_API, useValue: environment.adminApi }`; sem isso, essa parte se esconde.
163
+ `SPINE_ADMIN_API` (usado também pelo painel de configurações para os tokens de aplicação e para a seção
164
+ **Grupos**). O app não declara nada disso em `features.routes.ts`: basta o client estar vinculado ao template de
165
+ auto-serviço no Argos. Sem auto-serviço, o painel de configurações ainda pode listar tokens e grupos se o app
166
+ fornecer `{ provide: SPINE_ADMIN_API, useValue: environment.adminApi }`; sem isso, essas partes se escondem.
167
+ - **Seção Grupos** (desde a 3.2.0, `?settings=grupos`): vem pronta, sem nada no app. Lista os grupos da aplicação
168
+ logada de que a pessoa é membro (argos-admin `/me/groups`); cada um abre a tela de membros. A **função** no grupo
169
+ (não o crachá) decide: Administrador inclui como Administrador, Editor ou membro, troca funções e remove qualquer
170
+ um menos a si mesmo; Editor inclui e remove só membros sem função; o membro sem função só vê. A regra é do
171
+ argos-admin; a seção some sem grupo nenhum ou com um argos-admin que ainda não tem a rota. A lista de membros é
172
+ carregada inteira em páginas de 200 do servidor, uma depois da outra, com a busca local (desde a 3.3.4).
147
173
  - **`provideGraphql({ endpoints })`** — um cliente Apollo nomeado por backend (seção 6).
148
174
 
149
175
  ### 3.3 Componente raiz
@@ -154,9 +180,9 @@ export class AppComponent {}
154
180
  ```
155
181
 
156
182
  Só isso. O tema já está no `<body>`: **não** ponha `hermesTheme`, `hm-header`, `hm-sidebar` nem
157
- `hm-toast-stack` no app — o `spine-layout` já monta cabeçalho, aviso de conexão, menu, workspace,
158
- `spine-notification`, `spine-modal`, `spine-side-panel`, painel de atalhos, configurações, documentação,
159
- novidades e tour.
183
+ `hm-toast-stack` no app — o `spine-layout` já monta cabeçalho, aviso de conexão, menu, workspace, a pilha de
184
+ toasts (`hm-toast-stack`, onde saem o `NotificationService` e o `HermesToastService`), `spine-modal`,
185
+ `spine-side-panel`, painel de atalhos, configurações, documentação e novidades.
160
186
 
161
187
  ### 3.4 Sessão e aviso de conexão (`@orfeu/angular`)
162
188
 
@@ -223,8 +249,8 @@ O interceptor **não** põe o token. Nas APIs REST do app, mande `x-access-token
223
249
  ## 6. GraphQL (`@trismegisto/spine/graphql`)
224
250
 
225
251
  ```ts
226
- // environment.ts
227
- graphql: { principal: { namedClient: 'principal', http: 'CHANGE_ME', ws: 'CHANGE_ME' } }
252
+ // environment.ts (vazio = derivado atrás do proxy; URL explícita vem do config.json do ambiente)
253
+ graphql: { principal: { namedClient: 'principal', http: '', ws: '' } }
228
254
  // app.config.ts
229
255
  provideGraphql({ endpoints: environment.graphql })
230
256
  ```
@@ -266,7 +292,7 @@ async listTeams() {
266
292
 
267
293
  | Preciso de… | Use |
268
294
  |---|---|
269
- | Toast | `NotificationService.addNotification({ timer, hermesAlertType, message, hermesAlertClosable? })` (`@trismegisto/spine/notification`). `timer` em segundos; `hermesAlertType` = `AlertType` ou um status HTTP (vira tipo por faixa). A mensagem passa por redação de segredos. `processErrorNotification()` = erro genérico do catálogo |
295
+ | Toast | `NotificationService.addNotification({ timer, hermesAlertType, message, hermesAlertClosable? })` (`@trismegisto/spine/notification`). `timer` em segundos; `hermesAlertType` = `AlertType` ou um status HTTP (vira tipo por faixa). A mensagem passa por redação de segredos e sai na pilha de toasts do `HermesToastService` (3.3.0; antes era uma coluna de `hm-alert` à parte). `processErrorNotification()` = erro genérico do catálogo |
270
296
  | Modal com componente | `ModalService.open<R, D>({ title, component, data, size: 'sm'\|'md'\|'lg'\|'xl', closable, showActions })` → `Observable<R \| null>` (`null` = cancelado/substituído). O componente implementa `ModalContent` (`getResult()`, `isValid?()`), recebe `data` por `readonly data = input<D>()` e o botão Confirmar fica desabilitado enquanto `isValid()` for falso. Só um aberto por vez |
271
297
  | Modal só texto | `ModalService.open({ title, text })` |
272
298
  | Painel lateral | `SidePanelService.open(...)` — mesma API (`SidePanelContent` = `ModalContent`), `size` aceita também `'full'` |
@@ -274,7 +300,7 @@ async listTeams() {
274
300
  | Diálogo de confirmação simples | `HermesDialogService.confirm(...)` do `@trismegisto/angular` (não precisa do spine) |
275
301
  | Abrir configurações | `SpineSettingsService.open(SPINE_SETTINGS_KEYS.appearance)` ou link `?settings=aparencia` |
276
302
  | Abrir documentação | `SpineDocsService.openIndex()` / `openForRoute(routerId)` |
277
- | Reabrir tour / novidades | `OnboardingService.restart()` / `SpineNewsService.showAll()` |
303
+ | Reabrir novidades | `SpineNewsService.showAll()` (tour guiado de uma tela: `hm-tour`, do `@trismegisto/angular`; o spine não tem tour próprio) |
278
304
  | Fuso e idioma da pessoa | `SpinePreferencesService.effectiveTimeZone()` (sinal; IANA) e `language()`; também `hourCycle()`, `weekStart()`, `textScale()`, `motion()` |
279
305
  | Avisar a pessoa de um acontecimento | `SpineNoticesService.notify('tipo', { title, body?, url? })` com o tipo declarado em `SpineConfig.features.notices` — respeita o liga/desliga de Configurações › Notificações |
280
306
  | Página atual | `LoggerService.page`, `.routerId`, `.routeId` (`@trismegisto/spine/routing`) |
@@ -329,7 +355,7 @@ sozinho no painel `?`. Não reuse essas combinações.
329
355
  2. **Telas sempre lazy.** `ComponentRoute.load` é `() => import('./x.component').then((m) => m.X)`. Nunca
330
356
  importe a classe de uma tela estaticamente em `features.routes.ts`, `app.config.ts` ou serviço global.
331
357
  Um `features.routes.spec.ts` confere que todo `load()` resolve e que os `id` são UUID únicos, sem
332
- diferenciar maiúsculas (receitas §14).
358
+ diferenciar maiúsculas (receitas §15).
333
359
  3. **Auditoria e auto-serviço continuam lazy.** Não importe `@trismegisto/spine/audit` em código do bundle
334
360
  inicial (só em rota/`import()`/`@defer`). As telas do auto-serviço nem são exportadas; não tente
335
361
  alcançá-las por caminho interno. (O pacote confere isso no próprio build com `scripts/check-lazy.mjs`: um
@@ -338,7 +364,7 @@ sozinho no painel `?`. Não reuse essas combinações.
338
364
  4. **`COMPONENT_ROUTES` é `multi`.** Contribua pelo `provideShell` (ou com `{ provide: COMPONENT_ROUTES,
339
365
  useValue: [...], multi: true }`). Sem `multi: true` o Angular lança erro de provider inconsistente.
340
366
  5. **Id da tela = `router_id`** (`routerIdOf`). `routed_id`/`web.routes.route_id` não acha componente; é o que
341
- vai no `X-Route-Id`. `ComponentRoute.route_id`/`component` são nomes antigos depreciados (use `id`/`load`).
367
+ vai no `X-Route-Id`. `ComponentRoute.route_id`/`component` saíram na 3.3.1 (use `id`/`load`).
342
368
  6. **Uma cópia do `@orfeu/angular`.** App e spine precisam resolver o mesmo pacote; duas cópias (versões
343
369
  diferentes, `file:` duplicado, SDK antigo no app) dão `NullInjectorError` em `AUTH_CONFIG` ou uma segunda
344
370
  sessão. Confira com `npm ls @orfeu/angular`.
@@ -350,11 +376,12 @@ sozinho no painel `?`. Não reuse essas combinações.
350
376
  troca de aba (`keepAlive`): recarregue dados por ação da pessoa, `wsReconnected$` ou sinal, não por
351
377
  `ngOnInit` a cada visita.
352
378
  10. **Envelope GraphQL sempre por `unwrap`.** Não confie no HTTP 200.
353
- 11. **Detecção de mudanças:** os apps de referência usam `provideZoneChangeDetection`; parte do shell ainda usa
354
- a estratégia `Eager` e `NgZone`. Funcionamento sem zone.js não é garantido.
379
+ 11. **Detecção de mudanças:** desde a 3.3.1 todo o shell é `OnPush` (os apps de referência usam
380
+ `provideZoneChangeDetection`). Tela e componente aberto no `ModalService`/`SidePanelService` ficam sob pai
381
+ `OnPush`: estado que muda depois de `await`/`subscribe` vai em signal (ou `markForCheck()`).
355
382
  12. **Documentação de tela** é markdown cru importado como texto (loader `.md: "text"`); o texto vai no chunk
356
383
  da tela e o índice só lista telas que a pessoa enxerga.
357
- 13. **Chaves salvas** usam o `clientId`: trocar o `clientId` de um app "zera" tema, abas, favoritos e tour.
384
+ 13. **Chaves salvas** usam o `clientId`: trocar o `clientId` de um app "zera" tema, abas, favoritos e novidades vistas.
358
385
  14. **Logo** é arquivo do app (`src/assets/images/logo.svg` por convenção), legível sobre o fundo escuro do
359
386
  cabeçalho **nos dois temas**; marca em componente via `SPINE_BRAND` (sem link/botão dentro).
360
387