@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,279 @@
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 `"paths": { "src/*": ["./src/*"], "package.json": ["./package.json"] }` no `tsconfig.json`
25
+ (**sem `baseUrl`**: deprecado no TypeScript 6 e removido no 7 — não silencie com `ignoreDeprecations`).
26
+ Exceções do próprio Angular: `templateUrl`, `styleUrl` e `@use` de SCSS, que são relativos ao arquivo.
27
+
28
+ ## Nomes
29
+
30
+ - Arquivos: `pedidos.component.ts|html|scss`, `pedido-modal.component.ts`, `pedidos.service.ts`,
31
+ `pedidos.models.ts`, `pedidos.graphql`, `pedidos.generated.ts`, `*.spec.ts` ao lado.
32
+ - Classes: `PedidosComponent`, `PedidoModalComponent`, `PedidosService`.
33
+ - Seletor: prefixo `app-` (`app-pedidos`); raiz `core-root`.
34
+ - Tipos de dado de modal: `PedidoModalData` (entrada) e `PedidoModalResult` (saída).
35
+
36
+ ## `main.ts`
37
+
38
+ ```ts
39
+ import { bootstrapApplication } from '@angular/platform-browser';
40
+ import { registerLocaleData } from '@angular/common';
41
+ import localePt from '@angular/common/locales/pt';
42
+ import { applyRuntimeEnvironment } from '@trismegisto/spine';
43
+
44
+ import { CoreComponent } from 'src/core/core.component';
45
+ import { appConfig } from 'src/core/app.config';
46
+ import { environment } from 'src/core/environments/environment';
47
+
48
+ // Necessário se alguma tela usa DatePipe/CurrencyPipe com 'pt-BR' (senão NG0701).
49
+ registerLocaleData(localePt);
50
+
51
+ // Callback/logoff/authority/GraphQL derivados de onde o app está rodando.
52
+ const { origin, basePath, behindProxy, unset } = applyRuntimeEnvironment(environment);
53
+
54
+ // Só se o app tiver uma URL própria além das que o spine deriva (ex.: uma API REST no mesmo prefixo).
55
+ if (behindProxy && unset(environment.minhaApiUrl)) {
56
+ environment.minhaApiUrl = `${origin}${basePath}/server`;
57
+ }
58
+
59
+ bootstrapApplication(CoreComponent, appConfig)
60
+ .then(() => document.getElementById('app-loading')?.remove())
61
+ .catch((err) => console.error(err));
62
+ ```
63
+
64
+ - `applyRuntimeEnvironment` sempre reescreve `redirectUrl` (`<origem><prefixo>/callback`) e
65
+ `postLogoutRedirectUri` (`.../logoff`). Atrás de proxy (URL sem porta) também deriva `authority` e
66
+ cada endpoint GraphQL **ainda sem valor real** (vazio ou contendo `CHANGE_ME`). URL explícita no
67
+ environment sempre ganha.
68
+ - Mexa no objeto `environment` **só aqui, antes do bootstrap**. Valor que precisa ser recalculado
69
+ depois e lido por serviços em chunks lazy vai num `InjectionToken`, não em mutação do environment.
70
+ - A remoção do `#app-loading` (definido no `index.html`) é opcional, mas recomendada.
71
+
72
+ ## `src/core/app.config.ts`
73
+
74
+ ```ts
75
+ import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
76
+ import { provideRouter } from '@angular/router';
77
+ import { provideAuth } from '@orfeu/angular/core';
78
+ import { provideUi, SpineConfig } from '@trismegisto/spine';
79
+ import { provideShell, APP_ROUTES } from '@trismegisto/spine/shell';
80
+ import { provideAutoService } from '@trismegisto/spine/auto-service';
81
+ import packageInfo from 'package.json';
82
+
83
+ import { environment } from 'src/core/environments/environment';
84
+ import { components as featuresComponents } from 'src/app/features/features.routes';
85
+ import { CORE_PROVIDERS } from 'src/core/core.providers';
86
+
87
+ const spineConfig: SpineConfig = {
88
+ clientId: environment.authorizationServer.clientId,
89
+ appName: 'Meu App',
90
+ logo: { light: 'assets/images/logo.svg', alt: 'Meu App' },
91
+ technicalDocs: !environment.production, // mostra ESPECIFICACAO.md das telas fora de produção
92
+ };
93
+
94
+ export const appConfig: ApplicationConfig = {
95
+ providers: [
96
+ provideZoneChangeDetection({ eventCoalescing: true }),
97
+ provideRouter(APP_ROUTES),
98
+ ...CORE_PROVIDERS,
99
+ provideUi(spineConfig),
100
+ provideAuth(environment.authorizationServer),
101
+ provideAutoService({ adminApi: environment.adminApi }), // só se o client usa o template de auto-serviço
102
+ provideShell({ appComponents: featuresComponents, packageInfo }),
103
+ // providers de libs de terceiros (gráficos, editor) entram aqui, com import() lazy quando der:
104
+ // provideEchartsCore({ echarts: () => import('echarts') }),
105
+ ],
106
+ };
107
+ ```
108
+
109
+ - `provideUi()` registra o catálogo de ícones e o tema; opções de tema/logo/fontes ficam na
110
+ `trismegisto`. `provideAuth()` e suas opções (ex.: `{ eagerInit: false }` para app com
111
+ página pública) ficam na `orfeu`.
112
+ - `provideZoneChangeDetection` **uma vez**, aqui. Não repita no `bootstrapApplication`.
113
+ - `import packageInfo from 'package.json'` depende de `resolveJsonModule` + o `paths` de `package.json`; o
114
+ shell usa a versão do app na tela "sobre".
115
+ - Formato legado a evitar: `{ provide: AUTH_CONFIG, useValue }` + `APP_INITIALIZER` chamando
116
+ `auth.initialize()` à mão. Use `provideAuth()`.
117
+
118
+ ## `src/core/core.providers.ts`
119
+
120
+ ```ts
121
+ import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http';
122
+ import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';
123
+ import { provideGraphql } from '@trismegisto/spine/graphql';
124
+ import { environment } from 'src/core/environments/environment';
125
+
126
+ export const CORE_PROVIDERS = [
127
+ provideAnimationsAsync(),
128
+ provideHttpClient(withInterceptorsFromDi()), // interceptor do spine: x-route-id na auditoria
129
+ provideGraphql({ endpoints: environment.graphql }), // um cliente Apollo nomeado por entrada
130
+ ];
131
+ ```
132
+
133
+ App sem GraphQL omite o `provideGraphql`. Prefira `provideAnimationsAsync()` a
134
+ `importProvidersFrom(BrowserAnimationsModule)` (carrega animações sob demanda).
135
+
136
+ ## `src/core/core.component.ts`
137
+
138
+ ```ts
139
+ import { ChangeDetectionStrategy, Component } from '@angular/core';
140
+ import { RouterOutlet } from '@angular/router';
141
+ import { ToastStackComponent } from '@trismegisto/angular';
142
+
143
+ @Component({
144
+ selector: 'core-root',
145
+ imports: [RouterOutlet, ToastStackComponent],
146
+ changeDetection: ChangeDetectionStrategy.OnPush,
147
+ // hm-toast-stack: necessário se alguma tela usa HermesToastService.
148
+ template: `<router-outlet /><hm-toast-stack />`,
149
+ })
150
+ export class CoreComponent {}
151
+ ```
152
+
153
+ Não monte modal/side panel/notificação do shell aqui: o layout do spine já os renderiza. O título da
154
+ aba vem do `index.html` (ou `Title` no componente, se precisar mudar em runtime).
155
+
156
+ ## Environments
157
+
158
+ Arquivos em `src/core/environments/`:
159
+
160
+ | Arquivo | Uso |
161
+ | --- | --- |
162
+ | `environment.config.ts` | Interface `Environment` |
163
+ | `environment.ts` | Base (é o que os imports referenciam) |
164
+ | `environment.prod.ts`, `.homol.ts`, `.dev.ts`, `.local.ts` | Trocados por `fileReplacements` na configuração de build homônima |
165
+
166
+ Campos (só os nomes; os valores são de cada ambiente):
167
+
168
+ ```ts
169
+ import type { AuthConfig } from '@orfeu/angular'; // não redeclarar
170
+ import type { GraphqlEndpoint } from '@trismegisto/spine/graphql'; // não redeclarar
171
+
172
+ export interface Environment {
173
+ production: boolean;
174
+ authorizationServer: AuthConfig; // authority, realmId, clientId, redirectUrl, scope
175
+ graphql: Record<string, GraphqlEndpoint>; // { namedClient, http, ws? } por backend
176
+ adminApi: string; // API administrativa do Argos (auto-serviço)
177
+ }
178
+ ```
179
+
180
+ - O tipo do login é o `AuthConfig` da própria lib. Campos que ela não lê (`silentRenew`, `useRefreshToken`,
181
+ `postLogoutRedirectUri`, `responseType`) não entram no environment: são configuração morta — a renovação
182
+ é automática e o `applyRuntimeEnvironment` cuida de callback/logoff.
183
+ - Um arquivo por ambiente, **só** `local`, `dev`, `homol` e `prod`; `environment.ts` é igual ao `local`.
184
+
185
+ - A chave de `graphql` e o `namedClient` costumam ser o mesmo nome (`pedidos: { namedClient: 'pedidos', ... }`).
186
+ - Use `CHANGE_ME` em URL que deve ser derivada em runtime atrás do proxy.
187
+ - Segredo nunca entra em environment: tudo ali vai para o bundle público.
188
+ - Layout antigo `src/environments/` (fora de `core/`) e nomes de campo diferentes (`auth` em vez de
189
+ `authorizationServer`) existem em apps mais velhos; não copiar.
190
+ - `src/core/environments/environments.spec.ts` confere que os cinco arquivos têm as mesmas chaves, que só o
191
+ `prod` é `production`, que `environment.ts` é igual ao `local`, client/realm iguais em todos e nenhuma URL
192
+ com barra final.
193
+
194
+ ## `tsconfig.json`
195
+
196
+ Base: `strict: true`, `noImplicitOverride`, `noPropertyAccessFromIndexSignature`, `noImplicitReturns`,
197
+ `noFallthroughCasesInSwitch`, `resolveJsonModule`, `isolatedModules`, `moduleResolution: "bundler"`,
198
+ `target/module: ES2022`, e os imports absolutos por `paths` (sem `baseUrl`):
199
+
200
+ ```jsonc
201
+ "paths": { "src/*": ["./src/*"], "package.json": ["./package.json"] },
202
+ ```
203
+
204
+ `angularCompilerOptions` com `strictTemplates`, `strictInjectionParameters`, `strictInputAccessModifiers`.
205
+ TypeScript na mesma major em todos os apps (`~6.0`).
206
+
207
+ `tsconfig.app.json`: `files: ["src/main.ts"]` + `include: ["src/**/*.d.ts"]`. Se o app importa `.md`
208
+ como texto, declare em `src/markdown.d.ts`:
209
+
210
+ ```ts
211
+ declare module '*.md' {
212
+ const content: string;
213
+ export default content;
214
+ }
215
+ ```
216
+
217
+ ## `angular.json` (pontos relevantes)
218
+
219
+ ```jsonc
220
+ "build": {
221
+ "builder": "@angular/build:application",
222
+ "options": {
223
+ "outputPath": "dist/meu-app",
224
+ "browser": "src/main.ts",
225
+ "polyfills": ["zone.js"],
226
+ "inlineStyleLanguage": "scss",
227
+ "assets": [{ "glob": "**/*", "input": "src/assets", "output": "assets" }],
228
+ "styles": [
229
+ "src/styles.scss",
230
+ "@trismegisto/tokens/tokens.css",
231
+ "@trismegisto/core/core.css"
232
+ ],
233
+ "loader": { ".md": "text" } // só se houver documentação por tela
234
+ },
235
+ "configurations": {
236
+ "prod": { "budgets": [ /* ver testes-build.md */ ], "outputHashing": "all",
237
+ "baseHref": "/meu-app/",
238
+ "fileReplacements": [{ "replace": "src/core/environments/environment.ts",
239
+ "with": "src/core/environments/environment.prod.ts" }] },
240
+ "homol": { "...": "idem com environment.homol.ts" },
241
+ "dev": { "optimization": false, "sourceMap": true, "...": "environment.dev.ts" },
242
+ "local": { "optimization": false, "sourceMap": true, "...": "environment.local.ts" },
243
+ "development": { "optimization": false, "sourceMap": true }
244
+ },
245
+ "defaultConfiguration": "prod"
246
+ },
247
+ "serve": { "builder": "@angular/build:dev-server", "defaultConfiguration": "development" },
248
+ "test": { "builder": "@angular/build:karma" }
249
+ ```
250
+
251
+ - Use o builder `@angular/build:*`; `@angular-devkit/build-angular:*` é o formato antigo.
252
+ - `baseHref` = prefixo sob o qual o app é servido (o `applyRuntimeEnvironment` lê de `document.baseURI`).
253
+ - `cli.cache.environment: "all"` liga o cache do CLI também no build (útil no Docker).
254
+
255
+ ## Scripts do `package.json`
256
+
257
+ Os mesmos scripts, na mesma ordem, em todo app (só a porta muda):
258
+
259
+ ```json
260
+ "ng": "ng",
261
+ "start": "ng serve --port 4200",
262
+ "dev": "ng serve --configuration=dev --port 4200 --no-hmr",
263
+ "start:local": "ng serve --configuration=local --host 0.0.0.0 --port 4200 --no-hmr",
264
+ "start:homol": "ng serve --configuration=homol --host 0.0.0.0 --port 4200 --no-hmr",
265
+ "build": "ng build",
266
+ "build:dev": "ng build --configuration dev",
267
+ "build:homol": "ng build --configuration homol",
268
+ "watch": "ng build --watch --configuration development",
269
+ "test": "ng test",
270
+ "lint:a11y": "eslint --config eslint.a11y.config.js \"src/**/*.html\"",
271
+ "axe:check": "node scripts/axe-check.js",
272
+ "codegen": "graphql-codegen --config codegen.ts"
273
+ ```
274
+
275
+ Ferramentas com versão exata nos `devDependencies`, iguais entre os apps: `angular-eslint`, `eslint`,
276
+ `typescript-eslint`, `axe-core`, `puppeteer` (nada de `@angular-eslint/*` avulsos nem `@axe-core/puppeteer`).
277
+ Script de serve com configuração inexistente no `angular.json` quebra só quando alguém roda: confira.
278
+
279
+ Cada app usa uma porta fixa própria no dev-server para não colidir com os outros.
@@ -0,0 +1,219 @@
1
+ # Telas (features): registro no shell e anatomia
2
+
3
+ O shell (`@trismegisto/spine/shell`) monta login, callback, layout, menu e guard de rota privada a
4
+ partir da árvore de navegação que o Argos devolve para o usuário. O app só diz **qual componente
5
+ abre para cada roteador** do client. Como o shell resolve URL, menu e permissão: `trismegisto`.
6
+ Guards e sessão: `orfeu`.
7
+
8
+ ## `src/app/features/features.routes.ts`
9
+
10
+ ```ts
11
+ import { ComponentRoute } from '@trismegisto/spine/routing';
12
+
13
+ // id = router_id (linha do roteador do client no Argos), NUNCA o route_id da página.
14
+ // A URL de cada tela vem do Argos, não do nome da pasta.
15
+ export const components: ComponentRoute[] = [
16
+ {
17
+ // Vendas > Pedidos
18
+ id: '00000000-0000-0000-0000-000000000001',
19
+ load: () => import('src/app/features/pedidos/pedidos.component').then(m => m.PedidosComponent),
20
+ document: {
21
+ load: () => import('src/app/features/pedidos/README.md').then(m => m.default),
22
+ loadTechnical: () => import('src/app/features/pedidos/ESPECIFICACAO.md').then(m => m.default),
23
+ },
24
+ },
25
+ ];
26
+ ```
27
+
28
+ Campos de `ComponentRoute`:
29
+
30
+ | Campo | Uso |
31
+ | --- | --- |
32
+ | `id` | `router_id` da tela |
33
+ | `load` | `() => Promise<Type>` — sempre `import()` dinâmico (um chunk por tela) |
34
+ | `document` | Opcional. `load` = manual de uso (`README.md`, quem opera); `loadTechnical` = especificação (`ESPECIFICACAO.md`, só aparece com `SpineConfig.technicalDocs`). `title`/`group` opcionais para o índice |
35
+ | `source_template_router_id` | Para pacotes plugáveis que casam com qualquer client clonado de um template (é o que o `provideAutoService` usa; app comum não precisa) |
36
+ | `route_id`, `component` | **Deprecated** — formato antigo de `id`/`load`, ainda aceito. Não usar em código novo |
37
+
38
+ Documentação por tela exige `"loader": { ".md": "text" }` no `angular.json` e o `markdown.d.ts`.
39
+
40
+ Comente cada entrada com o caminho no menu (`Navegação > Menu > Página`) — o UUID sozinho não diz
41
+ nada a quem lê.
42
+
43
+ ### Fluxo para uma tela nova
44
+
45
+ 1. No painel administrativo do Argos, crie a rota e o roteador do client (aba de roteadores do client).
46
+ 2. Copie o `router_id` gerado.
47
+ 3. Crie a tela em `src/app/features/<tela>/` e registre em `components`.
48
+ 4. Nenhuma mudança em `app.config.ts`: `provideShell({ appComponents })` mescla com as telas da lib.
49
+
50
+ Telas do **auto-serviço** (rotas, grupos, acessos do próprio client) vêm de `provideAutoService` e
51
+ se auto-registram; não declare `router_id` para elas.
52
+
53
+ ## Rotas próprias fora do Argos (página pública)
54
+
55
+ Quando o app precisa de uma rota estática (ex.: vitrine pública em `/`), componha as rotas à mão em
56
+ `src/core/app.routes.ts` com as mesmas peças do shell, em vez de usar `APP_ROUTES` pronto:
57
+
58
+ ```ts
59
+ import { Routes } from '@angular/router';
60
+ import { PrivateGuard } from '@orfeu/angular/core';
61
+ import { LayoutComponent } from '@trismegisto/spine/layout';
62
+ import { PRIVATE_ROUTES, PUBLIC_ROUTES } from '@trismegisto/spine/shell';
63
+
64
+ export const APP_ROUTES: Routes = [
65
+ { path: '', pathMatch: 'full',
66
+ loadComponent: () => import('src/app/features/vitrine/vitrine.component').then(m => m.VitrineComponent) },
67
+ ...PUBLIC_ROUTES, // login, callback, logoff...
68
+ { path: '', component: LayoutComponent,
69
+ canActivate: [PrivateGuard], canActivateChild: [PrivateGuard], children: PRIVATE_ROUTES },
70
+ { path: '**', redirectTo: '' },
71
+ ];
72
+ ```
73
+
74
+ A rota pública vem primeiro (com `pathMatch: 'full'`) e é `loadComponent` lazy. Nesse caso,
75
+ `provideAuth(..., { eagerInit: false })` evita travar o primeiro render de visitante anônimo
76
+ (detalhes em `orfeu`).
77
+
78
+ ## Anatomia de um componente de tela
79
+
80
+ ```ts
81
+ import { ChangeDetectionStrategy, Component, computed, inject, signal } from '@angular/core';
82
+ import { ButtonComponent, DataGridColumn, DataGridComponent } from '@trismegisto/angular';
83
+ import { PedidosService } from 'src/app/services/pedidos/pedidos.service';
84
+ import type { Pedido } from 'src/app/services/pedidos/pedidos.models';
85
+
86
+ @Component({
87
+ selector: 'app-pedidos',
88
+ imports: [ButtonComponent, DataGridComponent],
89
+ templateUrl: './pedidos.component.html',
90
+ styleUrl: './pedidos.component.scss',
91
+ changeDetection: ChangeDetectionStrategy.OnPush,
92
+ })
93
+ export class PedidosComponent {
94
+ private readonly pedidos = inject(PedidosService);
95
+
96
+ readonly itens = signal<Pedido[]>([]);
97
+ readonly carregando = signal(false);
98
+ readonly erro = signal<string | null>(null);
99
+ readonly total = computed(() => this.itens().length);
100
+
101
+ readonly colunas: readonly DataGridColumn<Pedido>[] = [
102
+ { key: 'numero', title: 'Número', value: (p) => p.numero },
103
+ { key: 'cliente', title: 'Cliente', value: (p) => p.cliente },
104
+ ];
105
+ readonly rowId = (p: Pedido): string => p.id;
106
+
107
+ constructor() {
108
+ void this.carregar();
109
+ }
110
+
111
+ async carregar(): Promise<void> {
112
+ this.carregando.set(true);
113
+ this.erro.set(null);
114
+ try {
115
+ this.itens.set(await this.pedidos.listar());
116
+ } catch (e) {
117
+ this.erro.set(e instanceof Error ? e.message : 'Falha ao carregar');
118
+ } finally {
119
+ this.carregando.set(false);
120
+ }
121
+ }
122
+ }
123
+ ```
124
+
125
+ Os componentes `hm-*` usados no template (data grid, botão, modal...) e suas APIs estão na
126
+ `trismegisto`.
127
+
128
+ ### Regras de componente
129
+
130
+ - Standalone; **não** escreva `standalone: true` (padrão desde a v20).
131
+ - `changeDetection: ChangeDetectionStrategy.OnPush` em todo componente de tela/feature.
132
+ - `inject()` em vez de injeção por construtor.
133
+ - `input()`, `input.required()`, `output()`, `model()` (two-way) em vez de `@Input`/`@Output`.
134
+ - `viewChild()`, `viewChildren()`, `contentChild()`, `contentChildren()` em vez dos decorators.
135
+ - Host bindings no objeto `host` do decorator, nunca `@HostBinding`/`@HostListener`.
136
+ - Template e estilos externos com caminho relativo; template inline só para componente pequeno.
137
+ - `NgOptimizedImage` para imagens estáticas (não serve para base64 inline).
138
+ - Componente pequeno e de responsabilidade única: modal, painel de detalhe e card complexo viram
139
+ componentes próprios na pasta da tela.
140
+
141
+ ### Estado com signals
142
+
143
+ - `signal()` para estado local; `computed()` para derivado (nunca `effect()` + signal para calcular valor).
144
+ - `effect()` só para efeito colateral (sincronizar com API não-signal, DOM imperativo, log).
145
+ - `linkedSignal()` para estado editável derivado de outro que deve resetar quando a fonte muda
146
+ (ex.: item selecionado que reseta quando a lista recarrega).
147
+ - `set`/`update`, nunca `mutate`.
148
+ - Observable que alimenta template: `toSignal()` ou `async` pipe. Assinatura manual dentro do
149
+ componente: `takeUntilDestroyed()` (em vez de `Subject` + `ngOnDestroy`).
150
+
151
+ ### Templates
152
+
153
+ - `@if`, `@for`, `@switch`, `@let` (não `*ngIf`/`*ngFor`).
154
+ - `@for (p of itens(); track p.id)` — track por id estável, não pelo objeto nem `$index`. `track p` só serve
155
+ para lista de valores primitivos (strings, números); com objeto, cada recarga traz objetos novos e o
156
+ Angular recria todas as linhas (perde foco, expansão e seleção). O verificador acusa `track-objeto-inteiro`.
157
+ - `[class.ativo]="cond"` / `[style.width.%]="pct"` em vez de `ngClass`/`ngStyle`.
158
+ - Nada de lógica pesada no template; nada de getter/método que devolve array novo alimentando `@for`
159
+ (use `computed()`).
160
+ - Não assuma globais (`new Date()`) no template; exponha pelo componente.
161
+ - `@defer (on viewport)` para regiões pesadas abaixo da dobra (gráficos, abas secundárias, modais
162
+ raros) dentro de uma tela lazy — reduz o chunk daquela tela.
163
+
164
+ ## Formulários
165
+
166
+ Reactive Forms, sempre tipados:
167
+
168
+ ```ts
169
+ import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
170
+
171
+ readonly form = new FormGroup({
172
+ cliente: new FormControl('', { nonNullable: true, validators: [Validators.required] }),
173
+ quantidade: new FormControl(1, { nonNullable: true, validators: [Validators.min(1)] }),
174
+ });
175
+ ```
176
+
177
+ - Ligação por `[formControl]`/`formControlName`. Os campos `hm-*` (input, select, textarea, checkbox)
178
+ funcionam com Reactive Forms; detalhes de cada um (e qual não associa `<label for>`) na
179
+ `trismegisto`.
180
+ - Validação de texto obrigatório que aceite só espaços em branco: validador próprio com `trim()`.
181
+ - Modal com formulário: o componente de conteúdo recebe `data = input.required<XModalData>()`,
182
+ expõe `isValid()` e `getResult()` (contrato `ModalContent<T>` do `@trismegisto/spine/modal`); a tela
183
+ abre com `ModalService.open<Result, Data>({ title, component, data })` e trata o resultado.
184
+ - `[(ngModel)]` só em formulário legado de rascunho mutável; não use em código novo.
185
+ - **Desabilitar campo de formulário reativo é pelo controle**: `control.disable()`/`enable()` (num `effect()`
186
+ quando depende de signal), nunca `[disabled]` no mesmo elemento que `[formControl]`/`formControlName` — o
187
+ Angular avisa no console e o controle continua habilitado no modelo (entra no `value` e na validação).
188
+ Regra `disabled-com-form-control` do verificador.
189
+ - **Data de formulário é data local.** `toISOString()` converte para UTC: `d.toISOString().slice(0, 10)` (ou
190
+ `.split('T')[0]`) dá o dia seguinte depois das 21h em UTC-3 e desloca a data escolhida no calendário.
191
+ Monte `AAAA-MM-DD` com `getFullYear()`/`getMonth()`/`getDate()` (ou `formatDate(d, 'yyyy-MM-dd', locale)`);
192
+ `toISOString()` só para instante (timestamp) ou data que já é UTC de propósito (`Date.UTC`). Regra
193
+ `data-utc-em-formulario`.
194
+
195
+ ## Ações destrutivas e dados sensíveis
196
+
197
+ - **Excluir, revogar, desligar, sobrescrever** pedem confirmação antes de chamar o serviço
198
+ (`HermesDialogService.confirm({ heading, message, danger: true })` → `Promise<boolean>`; ver
199
+ `trismegisto`). O botão leva `intent="danger"`. Nada de exclusão num clique só, nem em ação de linha.
200
+ - **Credencial nunca em `localStorage`/`sessionStorage`** (token, senha, segredo, chave de API): qualquer
201
+ script da página lê. O token do usuário fica com o `@orfeu/angular`, em memória; outro valor sensível que
202
+ precise durar entre telas fica em memória, num service `providedIn: 'root'` com signal. O verificador da
203
+ skill `orfeu` acusa (`token-em-storage`).
204
+
205
+ ## Acessibilidade
206
+
207
+ - Meta: passar no axe e em WCAG AA (foco, contraste, ARIA).
208
+ - Ação clicável é `<button type="button">` (ou `hm-button`/`hm-icon-button`), nunca ícone com
209
+ `(click)`: ícone não recebe foco nem teclado. Botão só com ícone leva `aria-label`.
210
+ - Modal do DS já faz foco preso, retorno de foco e Esc; não reimplemente.
211
+ - Rode `npm run lint:a11y` nos templates alterados (ver `testes-build.md`).
212
+
213
+ ## i18n
214
+
215
+ - Os apps são **monolíngues em pt-BR**: textos direto no template, `<html lang="pt-BR">`. Não há
216
+ `$localize`/`i18n=`/Transloco nos apps hoje.
217
+ - Datas, números e moeda: `registerLocaleData(localePt)` no `main.ts` e pipes com `'pt-BR'`.
218
+ - Mensagens do próprio shell (login, erros do GraphQL) vêm do catálogo de mensagens do spine
219
+ (`trismegisto`); não duplique esses textos no app.