@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.
- package/README.md +181 -2
- package/agents/revisor-deploy.md +73 -0
- package/agents/revisor-documentacao.md +78 -0
- package/agents/revisor-orfeu.md +80 -0
- package/agents/revisor-trismegisto.md +81 -0
- package/bin/install.js +252 -0
- package/package.json +15 -4
- package/skills/acropole/SKILL.md +80 -0
- package/skills/acropole/references/arquitetura.md +174 -0
- package/skills/acropole/references/fluxos/app-novo.md +34 -0
- package/skills/acropole/references/fluxos/doctor.md +55 -0
- package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
- package/skills/acropole/references/fluxos/revisar.md +56 -0
- package/skills/acropole/references/fluxos/tela-nova.md +27 -0
- package/skills/acropole/scripts/doctor.mjs +439 -0
- package/skills/angular/SKILL.md +155 -0
- package/skills/angular/references/armadilhas.md +99 -0
- package/skills/angular/references/dados.md +251 -0
- package/skills/angular/references/estrutura.md +279 -0
- package/skills/angular/references/features.md +219 -0
- package/skills/angular/references/testes-build.md +257 -0
- package/skills/angular/scripts/checar.mjs +182 -0
- package/skills/angular/scripts/nucleo.mjs +227 -0
- package/skills/apollo/SKILL.md +226 -0
- package/skills/apollo/references/armadilhas.md +99 -0
- package/skills/apollo/references/envelope-erros.md +120 -0
- package/skills/apollo/references/estrutura-bootstrap.md +310 -0
- package/skills/apollo/references/schema-resolvers.md +183 -0
- package/skills/apollo/references/subscriptions.md +224 -0
- package/skills/apollo/references/testes-build.md +181 -0
- package/skills/apollo/scripts/checar.mjs +160 -0
- package/skills/apollo/scripts/nucleo.mjs +227 -0
- package/skills/docker/SKILL.md +102 -0
- package/skills/docker/references/modelos.md +251 -0
- package/skills/docker/references/porques.md +286 -0
- package/skills/documentacao/SKILL.md +146 -0
- package/skills/documentacao/references/checklist-coerencia.md +59 -0
- package/skills/documentacao/references/ligar-app-novo.md +107 -0
- package/skills/documentacao/references/modelo-especificacao.md +51 -0
- package/skills/documentacao/references/modelo-readme.md +75 -0
- package/skills/documentacao/scripts/checar.mjs +454 -0
- package/skills/documentacao/scripts/nucleo.mjs +227 -0
- package/skills/express/SKILL.md +156 -0
- package/skills/express/references/dados.md +180 -0
- package/skills/express/references/estrutura.md +157 -0
- package/skills/express/references/middlewares.md +227 -0
- package/skills/express/references/rotas-erros.md +286 -0
- package/skills/express/references/testes-deploy.md +154 -0
- package/skills/express/scripts/checar.mjs +115 -0
- package/skills/express/scripts/nucleo.mjs +227 -0
- package/skills/fastapi/SKILL.md +132 -0
- package/skills/fastapi/references/banco.md +197 -0
- package/skills/fastapi/references/estrutura.md +325 -0
- package/skills/fastapi/references/integracoes.md +145 -0
- package/skills/fastapi/references/rotas-erros.md +140 -0
- package/skills/fastapi/references/testes-deploy.md +190 -0
- package/skills/fastapi/scripts/checar.mjs +108 -0
- package/skills/fastapi/scripts/nucleo.mjs +227 -0
- package/skills/hefesto/SKILL.md +119 -0
- package/skills/hefesto/references/conceitos.md +131 -0
- package/skills/hefesto/references/diagnostico.md +70 -0
- package/skills/hefesto/references/fluxo.md +122 -0
- package/skills/hefesto/references/preparar-app.md +105 -0
- package/skills/orfeu/SKILL.md +162 -0
- package/skills/orfeu/references/angular-api.md +201 -0
- package/skills/orfeu/references/angular-armadilhas.md +116 -0
- package/skills/orfeu/references/angular-recipes.md +474 -0
- package/skills/orfeu/references/angular.md +212 -0
- package/skills/orfeu/references/diferencas.md +56 -0
- package/skills/orfeu/references/node-api.md +354 -0
- package/skills/orfeu/references/node-armadilhas.md +158 -0
- package/skills/orfeu/references/node-recipes.md +541 -0
- package/skills/orfeu/references/node.md +204 -0
- package/skills/orfeu/references/python-api.md +346 -0
- package/skills/orfeu/references/python-recipes.md +479 -0
- package/skills/orfeu/references/python.md +240 -0
- package/skills/orfeu/scripts/checar.mjs +126 -0
- package/skills/orfeu/scripts/nucleo.mjs +227 -0
- package/skills/trismegisto/SKILL.md +194 -0
- package/skills/trismegisto/references/angular-api.md +2788 -0
- package/skills/trismegisto/references/angular-exports.md +4020 -0
- package/skills/trismegisto/references/angular-recipes.md +1883 -0
- package/skills/trismegisto/references/angular-types.md +492 -0
- package/skills/trismegisto/references/angular.md +390 -0
- package/skills/trismegisto/references/catalogo/icones.json +912 -0
- package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
- package/skills/trismegisto/references/catalogo/tokens.json +240 -0
- package/skills/trismegisto/references/spine-api.md +1530 -0
- package/skills/trismegisto/references/spine-recipes.md +581 -0
- package/skills/trismegisto/references/spine.md +343 -0
- package/skills/trismegisto/scripts/checar.mjs +216 -0
- 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.
|