@acropole/skills 1.0.0 → 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 +2 -1
- package/package.json +1 -1
- package/skills/acropole/SKILL.md +8 -3
- package/skills/acropole/references/arquitetura.md +174 -0
- package/skills/acropole/references/fluxos/app-novo.md +34 -0
- package/skills/acropole/references/fluxos/tela-nova.md +1 -1
- package/skills/angular/SKILL.md +6 -3
- package/skills/angular/references/armadilhas.md +5 -1
- package/skills/angular/references/estrutura.md +33 -14
- package/skills/angular/references/testes-build.md +31 -4
- package/skills/apollo/SKILL.md +12 -8
- package/skills/apollo/references/armadilhas.md +5 -1
- package/skills/apollo/references/estrutura-bootstrap.md +47 -36
- package/skills/apollo/references/testes-build.md +12 -11
- package/skills/docker/references/porques.md +4 -0
- package/skills/express/SKILL.md +9 -7
- package/skills/express/references/estrutura.md +4 -1
- package/skills/express/references/rotas-erros.md +13 -1
- package/skills/express/references/testes-deploy.md +9 -5
- package/skills/fastapi/SKILL.md +12 -9
- package/skills/fastapi/references/banco.md +24 -12
- package/skills/fastapi/references/estrutura.md +87 -43
- package/skills/orfeu/references/diferencas.md +3 -3
- package/skills/orfeu/references/node-api.md +8 -2
- package/skills/orfeu/references/node-armadilhas.md +4 -4
- package/skills/orfeu/references/node-recipes.md +19 -12
- package/skills/orfeu/references/python.md +8 -2
- package/skills/trismegisto/references/angular-exports.md +143 -143
package/README.md
CHANGED
|
@@ -13,7 +13,7 @@ Cada skill cobre uma parte da stack e elas se complementam: numa tela Angular en
|
|
|
13
13
|
|
|
14
14
|
| Skill | Assunto | Exemplo de pedido que a dispara |
|
|
15
15
|
| --- | --- | --- |
|
|
16
|
-
| `acropole` | Porta de entrada
|
|
16
|
+
| `acropole` | Porta de entrada e padrão arquitetural dos apps (pastas, ambientes, saúde, segurança, dependências, scripts, testes); fluxos `app-novo`, `tela-nova`, `endpoint-novo`, `revisar`, `doctor` | `/acropole`, "cria a estrutura do app novo", "esse app segue o padrão?" |
|
|
17
17
|
| `angular` | Estrutura dos apps Angular, bootstrap com o spine, telas por `router_id`, serviços GraphQL, signals, testes, build | "cria a tela de pedidos no app de vendas" |
|
|
18
18
|
| `trismegisto` | Interface com o design system (`@trismegisto/*`, componentes `hm-*`, tokens `--hm-*`, tema, ícones, a11y) e o shell spine | "troca essa tabela por um data grid", "o botão some no tema escuro" |
|
|
19
19
|
| `orfeu` | SDK Orfeu: login/sessão no front, operações e níveis no backend, auditoria, `traceparent`, propagação entre serviços | "protege essa rota", "o usuário toma 403", "audita a exclusão" |
|
|
@@ -45,6 +45,7 @@ O Claude Code chama o revisor quando a tarefa bate com a descrição dele; você
|
|
|
45
45
|
| Comando | O que faz |
|
|
46
46
|
| --- | --- |
|
|
47
47
|
| `/acropole` | Lê `package.json`/`pyproject.toml`/`requirements.txt`, identifica a stack e sugere 2–3 fluxos. Não executa nada sozinho |
|
|
48
|
+
| `/acropole app-novo` | Estrutura inicial no padrão: `angular/`, `graphql/`, `server/`, `database/` copiados de um app de referência, sem domínio, com specs fixos, `/health`, ambientes e README; tudo testado |
|
|
48
49
|
| `/acropole tela-nova` | Argos (`router_id`) → `features.routes` → `.graphql` + codegen → service → componente `hm-*` → operação no backend → testes |
|
|
49
50
|
| `/acropole endpoint-novo` | Rota/resolver (fastapi, express ou apollo) + operação do Orfeu + propagação de headers + auditoria + teste |
|
|
50
51
|
| `/acropole revisar [caminho]` | Roda os verificadores sobre o diff/arquivos e chama os revisores. Relata; não corrige sem pedido |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@acropole/skills",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "Skills e revisores para Claude Code: Angular, Apollo, Express, FastAPI, Trismegisto, Orfeu, Docker, deploy no Hefesto e documentação das telas. Instale com: npx @acropole/skills",
|
|
5
5
|
"bin": { "acropole-skills": "bin/install.js" },
|
|
6
6
|
"files": ["bin", "skills", "agents"],
|
package/skills/acropole/SKILL.md
CHANGED
|
@@ -1,19 +1,23 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: acropole
|
|
3
|
-
description: Porta de entrada das skills da Acrópole — descobre a stack do projeto (Angular + Trismegisto, Apollo, Express, FastAPI, Orfeu, Docker/Hefesto), sugere o fluxo certo e encadeia as skills na ordem — tela nova, endpoint novo, revisão com os verificadores e os subagentes revisores, e diagnóstico (doctor)
|
|
3
|
+
description: Porta de entrada das skills da Acrópole e dono do padrão arquitetural dos apps (pastas angular/graphql/server/database, ambientes, saúde e subida, encerramento, segurança, dependências, scripts e testes iguais em todo app) — descobre a stack do projeto (Angular + Trismegisto, Apollo, Express, FastAPI, Orfeu, Docker/Hefesto), sugere o fluxo certo e encadeia as skills na ordem — app novo, tela nova, endpoint novo, revisão com os verificadores e os subagentes revisores, e diagnóstico (doctor). Use quando o usuário chamar /acropole, pedir "por onde começo", "qual skill uso", um app ou estrutura nova, "segue o padrão?", uma tela ou endpoint de ponta a ponta, uma revisão geral, ou um diagnóstico de versões/configuração do projeto.
|
|
4
4
|
user-invocable: true
|
|
5
|
-
argument-hint: "[tela-nova | endpoint-novo | revisar | doctor] [alvo]"
|
|
5
|
+
argument-hint: "[app-novo | tela-nova | endpoint-novo | revisar | doctor] [alvo]"
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# acropole — fluxos entre as skills
|
|
9
9
|
|
|
10
10
|
As skills da Acrópole cobrem uma parte da stack cada uma. Esta skill não repete regra de nenhuma
|
|
11
|
-
delas: diz **qual** convocar, **em que ordem**, e onde estão os verificadores e os revisores
|
|
11
|
+
delas: diz **qual** convocar, **em que ordem**, e onde estão os verificadores e os revisores — e guarda o
|
|
12
|
+
**padrão arquitetural** que vale para o app inteiro: [references/arquitetura.md](references/arquitetura.md)
|
|
13
|
+
(pastas, fluxo entre camadas, caminhos/portas, ambientes, subida/saúde/encerramento, segurança, desempenho,
|
|
14
|
+
dependências, scripts, testes mínimos, pendências e checklist). Divergência entre apps se resolve por ele.
|
|
12
15
|
|
|
13
16
|
## Comandos
|
|
14
17
|
|
|
15
18
|
| Comando | O que faz | Playbook |
|
|
16
19
|
| --- | --- | --- |
|
|
20
|
+
| `/acropole app-novo [nome]` | Estrutura inicial de um app no padrão (angular, graphql, server, database), sem domínio, tudo subindo e testado | [references/fluxos/app-novo.md](references/fluxos/app-novo.md) |
|
|
17
21
|
| `/acropole tela-nova [nome]` | Tela Angular de ponta a ponta: Argos → rota → GraphQL → service → componente `hm-*` → operação no backend → testes | [references/fluxos/tela-nova.md](references/fluxos/tela-nova.md) |
|
|
18
22
|
| `/acropole endpoint-novo [recurso]` | Endpoint/resolver no backend com operação do Orfeu, propagação de headers, auditoria e teste | [references/fluxos/endpoint-novo.md](references/fluxos/endpoint-novo.md) |
|
|
19
23
|
| `/acropole revisar [caminho]` | Roda os verificadores das skills sobre o diff/arquivos e chama os subagentes revisores; só relata | [references/fluxos/revisar.md](references/fluxos/revisar.md) |
|
|
@@ -43,6 +47,7 @@ acima e pergunte.
|
|
|
43
47
|
|
|
44
48
|
| No pedido aparece… | Skills, nesta ordem |
|
|
45
49
|
| --- | --- |
|
|
50
|
+
| app novo, estrutura do projeto, "segue o padrão?", pastas/portas/ambientes, divergência entre apps | `references/arquitetura.md` (+ o fluxo `app-novo` para criar) |
|
|
46
51
|
| tela, página, listagem, formulário, modal, menu, rota do app | angular → trismegisto → orfeu → documentacao |
|
|
47
52
|
| manual/README da tela, documentação desatualizada, `ESPECIFICACAO.md` | documentacao |
|
|
48
53
|
| botão, cor, tema, ícone, densidade, `hm-*`, `--hm-*`, acessibilidade de tela | trismegisto (+ angular se mexer em estrutura) |
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# Padrão arquitetural dos apps
|
|
2
|
+
|
|
3
|
+
O que todo app da plataforma tem, igual entre eles. As skills de cada stack (**angular**, **apollo**,
|
|
4
|
+
**express**, **fastapi**, **docker**, **hefesto**) detalham o código; aqui fica o desenho do app inteiro e as
|
|
5
|
+
decisões que valem para todas as camadas. Divergiu de um app para outro? Este arquivo é o desempate.
|
|
6
|
+
|
|
7
|
+
## 1. Um repositório por app, sempre as mesmas pastas
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
<app>/
|
|
11
|
+
├── angular/ front: Angular 22 + @trismegisto/* + @orfeu/angular
|
|
12
|
+
├── graphql/ gateway: Apollo Server sobre Express + @orfeu/node — só repassa para o server
|
|
13
|
+
├── server/ API e regra de negócio: FastAPI + orfeu[fastapi] + SQLAlchemy
|
|
14
|
+
├── database/ schema, seed e migrations do Postgres (estrutura idêntica entre os apps)
|
|
15
|
+
├── compose/ (opcional) docker-compose da stack num host
|
|
16
|
+
└── README.md componentes, portas, como rodar, padrões seguidos e pendências
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
- Nomes de pasta fixos (`server/`, nunca `fastapi/` ou `api/`): ferramentas, deploy e as próprias skills
|
|
20
|
+
contam com eles. App só com parte da stack omite a pasta, não renomeia.
|
|
21
|
+
- Cada pasta tem o próprio `.gitignore` (da stack dela), `Dockerfile` e `.dockerignore`. A raiz só ignora
|
|
22
|
+
estado de ferramenta e de editor.
|
|
23
|
+
- Um serviço que é de fato outro produto (agente de build, agente de deploy) vive em repositório próprio.
|
|
24
|
+
|
|
25
|
+
## 2. Fluxo entre as camadas
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
navegador ──> angular (estático) ──GraphQL HTTP/WS──> graphql ──REST + orfeuHeaders──> server ──> Postgres
|
|
29
|
+
▲ │
|
|
30
|
+
└──── Redis pub/sub (canais <app>:*) ◄┘
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- O **front** só fala com o gateway (e com a API administrativa do Argos, para o auto-serviço do shell).
|
|
34
|
+
- O **gateway** não tem regra nem banco: cada operação é `operation(Level.X, …)` do Orfeu e repassa ao server
|
|
35
|
+
com `orfeuHeaders(ctx)` (credencial, `traceparent`, `x-route-id`, `x-client-id`). Respostas no envelope
|
|
36
|
+
`{ status, message, data }`.
|
|
37
|
+
- O **server** tem a regra, o banco e as integrações; publica eventos no Redis, que o gateway entrega às
|
|
38
|
+
subscriptions. Rota protegida = `@operation`.
|
|
39
|
+
- **Argos** autentica todas as camadas: um *client* para o front e um *app* para cada backend (gateway e
|
|
40
|
+
server), no mesmo realm. Os IDs (não segredos) ficam nos environments do front e nos `.env.example`.
|
|
41
|
+
|
|
42
|
+
## 3. Caminhos, proxy e portas
|
|
43
|
+
|
|
44
|
+
| Camada | Caminho público | Prefixo no código |
|
|
45
|
+
| --- | --- | --- |
|
|
46
|
+
| angular | `/<app>/` | `baseHref` das configurações de build |
|
|
47
|
+
| graphql | `/<app>/graphql` (HTTP **e** WebSocket) | `GRAPHQL_PATH` |
|
|
48
|
+
| server | `/<app>/server` | `api_prefix` (rotas, `/health` e documentação) |
|
|
49
|
+
|
|
50
|
+
- O proxy encaminha o caminho **completo** (sem strip): cada serviço responde sob o próprio prefixo.
|
|
51
|
+
- Atrás do proxy, o front deriva callback, logoff, authority e URLs ainda `CHANGE_ME` da própria origem
|
|
52
|
+
(`applyRuntimeEnvironment`); URL explícita no environment sempre ganha.
|
|
53
|
+
- Cada app tem **uma porta fixa e única por camada** no desenvolvimento local, registrada no README da raiz,
|
|
54
|
+
para vários apps rodarem juntos sem colisão. A porta do container é a mesma variável (`PORT`) que o código lê.
|
|
55
|
+
|
|
56
|
+
## 3.1 Redis compartilhado: um índice por app
|
|
57
|
+
|
|
58
|
+
O Redis de um ambiente costuma ser **o mesmo para vários apps**. Para um app não ler, sobrescrever nem apagar as
|
|
59
|
+
chaves de outro (cache, dedup de eventos, `FLUSHDB` de teste):
|
|
60
|
+
|
|
61
|
+
- cada app tem o **próprio `REDIS_DB`** (índice 0–15) em cada ambiente — **dois apps nunca usam o mesmo índice**
|
|
62
|
+
no mesmo Redis; gateway e server do **mesmo** app usam o mesmo índice (é por ele que conversam);
|
|
63
|
+
- canais de pub/sub e chaves sempre com o prefixo do app (`<app>:…`) — pub/sub ignora o índice (`PUBLISH` vale
|
|
64
|
+
para o servidor inteiro), então o prefixo é o que isola as subscriptions;
|
|
65
|
+
- o índice de cada app por ambiente fica registrado no README da raiz do app; ao criar um app, escolha um índice
|
|
66
|
+
livre conferindo os outros apps do mesmo ambiente (`.env.<ambiente>`), não "o próximo número".
|
|
67
|
+
|
|
68
|
+
## 4. Ambientes
|
|
69
|
+
|
|
70
|
+
Só **`local`**, **`dev`**, **`homol`** e **`prod`** — em toda camada, com o mesmo nome.
|
|
71
|
+
|
|
72
|
+
| Camada | Escolha do ambiente | Arquivos |
|
|
73
|
+
| --- | --- | --- |
|
|
74
|
+
| angular | `--configuration <ambiente>` (build/serve) | `src/core/environments/environment.<ambiente>.ts` (versionados, sem segredo); `environment.ts` = `local` |
|
|
75
|
+
| graphql | `NODE_ENV` (`cross-env` nos scripts) | `src/settings/environment/.env.<ambiente>` (não versionados) + `.env.example` |
|
|
76
|
+
| server | `APP_ENV` (comando, `poe start:<ambiente>` ou `src/.env`) | `src/settings/environment/.env.<ambiente>` (não versionados) + `.env.example` |
|
|
77
|
+
| database | — | `env/.env` (não versionado) + `env/.env.example` |
|
|
78
|
+
|
|
79
|
+
- Em container nenhum arquivo `.env` existe (o `.dockerignore` tira): as variáveis vêm do deploy. Arquivo
|
|
80
|
+
ausente não pode quebrar a subida.
|
|
81
|
+
- Variável do processo vence arquivo (`override=False`, `dotenv` sem override).
|
|
82
|
+
- `NODE_ENV`/`APP_ENV` **não são trava de segurança**: são digitados no deploy e o Dockerfile do Node fixa
|
|
83
|
+
`NODE_ENV=dev`. Decisão de segurança "só em produção" precisa de sinal injetado pela plataforma.
|
|
84
|
+
|
|
85
|
+
## 5. Subida, saúde e encerramento
|
|
86
|
+
|
|
87
|
+
| | graphql | server | front |
|
|
88
|
+
| --- | --- | --- | --- |
|
|
89
|
+
| Argos/Orfeu fora na subida | **sobe negando** tudo; nova tentativa 5 s → 10 s → 20 s → 30 s; `OrfeuConfigError` derruba (saída 1) | o adapter faz o sync no lifespan; falha derruba a subida | — |
|
|
90
|
+
| `/health` | `503 {status:'starting', orfeu:'unavailable'}` até o Orfeu conectar; depois `200 {ok:true}` | `<api_prefix>/health` → envelope `ok(message="ok")` | — |
|
|
91
|
+
| TLS do Argos desligado | aviso na subida + `tls_verify: false` no `/health` | idem (`data: {tls_verify: false}`) | — |
|
|
92
|
+
| SIGTERM/SIGINT | `close()` (ou `flushAudit()` no SDK antigo) + `apollo.server.stop()`; sai **0**; teto de 8 s sai **1** | uvicorn como PID 1 (`exec`), lifespan fecha banco/Redis | — |
|
|
93
|
+
|
|
94
|
+
- Nunca um "modo degradado" que libera sem autorização. Nunca `/health` 200 num serviço que nega tudo.
|
|
95
|
+
- O 503 da subida é informação para a monitoração: healthcheck que reinicia container precisa tolerá-lo
|
|
96
|
+
(`--start-period`/`--retries`), senão Argos fora vira loop de restart.
|
|
97
|
+
- Express (APIs do próprio IdP e afins): `/health` checa as dependências reais (`SELECT 1`, `PING`) e mesma
|
|
98
|
+
convenção de saída 0/1.
|
|
99
|
+
|
|
100
|
+
## 6. Segurança
|
|
101
|
+
|
|
102
|
+
- **Documentação de API** (`/docs`, `/openapi.json`, `/redoc`, Swagger) **só em `local`** por padrão, em todo
|
|
103
|
+
backend; `API_DOCS=true/false` força. O mapa da API não fica aberto nos ambientes publicados.
|
|
104
|
+
- **TLS** do autorizador: verificação ligada; desligar é opt-out explícito (`AUTH_TLS_VERIFY` /
|
|
105
|
+
`AUTHORIZER_TLS_VERIFY`), escopado ao client do Orfeu, com aviso e visível no `/health`. Prefira apontar a CA
|
|
106
|
+
(`NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`). Nada de `NODE_TLS_REJECT_UNAUTHORIZED=0` nem
|
|
107
|
+
`urllib3.disable_warnings` no processo inteiro (destino com CA interna: aviso **uma vez por host**).
|
|
108
|
+
- **Segredo** nunca no front (environment vai para o bundle), nunca com valor padrão, nunca na imagem
|
|
109
|
+
(`.npmrc`, `.env`). `.env.example` só com nomes e IDs públicos.
|
|
110
|
+
- **Front sem recurso de terceiros** em tempo de execução (CDN de imagem, fonte ou script): expõe o IP do
|
|
111
|
+
usuário e faz requisição a cada tela — principalmente na tela de login.
|
|
112
|
+
- Credencial do usuário nunca em `localStorage`/`sessionStorage`.
|
|
113
|
+
|
|
114
|
+
## 7. Desempenho
|
|
115
|
+
|
|
116
|
+
- **Gateway**: `compression()` antes do Apollo; build = `tsc --noEmit` + **esbuild** em bundle único (rápido de
|
|
117
|
+
buildar e de subir). Clientes (Redis, axios) criados uma vez, dentro do builder.
|
|
118
|
+
- **Server**: `uvicorn[standard]` (uvloop + httptools); rotas com sessão síncrona em `def` (threadpool);
|
|
119
|
+
clientes HTTP reaproveitados.
|
|
120
|
+
- **Front**: telas lazy (`load: () => import(…)`), `provideAnimationsAsync()`, `OnPush` + signals, sem
|
|
121
|
+
biblioteca pesada no bundle inicial (`import()` sob demanda).
|
|
122
|
+
|
|
123
|
+
## 8. Dependências
|
|
124
|
+
|
|
125
|
+
| Camada | Regra |
|
|
126
|
+
| --- | --- |
|
|
127
|
+
| angular | Angular e TypeScript na mesma major em todos os apps; ferramentas (`angular-eslint`, `eslint`, `typescript-eslint`, `axe-core`, `puppeteer`) com versão exata; pacotes do npm público, sem `.npmrc` com credencial |
|
|
128
|
+
| graphql / express | faixa explícita da versão em uso (`^16.14.2`, nunca `^16`); `cross-env` e `@types/node` na mesma major em todos (o `@types/node` na major do Node da imagem) |
|
|
129
|
+
| server | `requirements.txt` só com dependências **diretas**, versão exata; `requirements-dev.txt` com pytest e poethepoet; `pyproject.toml` só com tarefas do poe; mesmas versões das libs comuns entre os apps |
|
|
130
|
+
| database | `requirements*.txt` idênticos entre os apps |
|
|
131
|
+
|
|
132
|
+
Pacote sem uso sai (inclusive `@types/*` de lib que já traz tipos). Lockfile sempre em sincronia: o `npm ci`
|
|
133
|
+
do Dockerfile falha com `package.json` e lock divergentes.
|
|
134
|
+
|
|
135
|
+
## 9. Scripts
|
|
136
|
+
|
|
137
|
+
| Camada | Scripts (mesmo conjunto em todo app) |
|
|
138
|
+
| --- | --- |
|
|
139
|
+
| angular | `start`, `dev`, `start:local`, `start:homol`, `build` (prod), `build:dev`, `build:homol`, `watch`, `test`, `lint:a11y`, `axe:check`, `codegen` |
|
|
140
|
+
| graphql | `dev`, `start`, `start:local`, `start:homol`, `build` (typecheck + esbuild), `typecheck`, `start:prod`, `test` |
|
|
141
|
+
| server | `poe start:local`, `poe start:dev`, `poe start:homol`, `poe test` |
|
|
142
|
+
| database | `python build.py [--exec\|--reset\|--seed\|--bootstrap]`, `python -m pytest` |
|
|
143
|
+
|
|
144
|
+
## 10. Testes mínimos
|
|
145
|
+
|
|
146
|
+
| Camada | Obrigatório |
|
|
147
|
+
| --- | --- |
|
|
148
|
+
| angular | `app.config.spec`, `core.providers.spec`, `environments.spec`, `core.component.spec`, `features.routes.spec` (UUID único, `load()` standalone, documento carregável) + spec de toda tela nova/alterada |
|
|
149
|
+
| graphql | `builder.test` (subida, path, CORS, introspecção desligada, lote, 400 de sintaxe, 401/403 antes do resolver, encerramento), `builder-falha.test` (Orfeu fora → 503 → 200; campo sem `operation()` não sobe), `builder-padroes.test`, `shutdown.test` (teto → 1), `resolvers.test` (tabela campo → chamada REST) |
|
|
150
|
+
| server | `test_health`, `test_api_docs` (só `local`; `API_DOCS` força), testes de domínio com SQLite em memória |
|
|
151
|
+
| database | suíte compartilhada (estrutura, build, migrations, PGlite) + `test_app.py` |
|
|
152
|
+
|
|
153
|
+
Validação antes de entregar: suíte e build de cada camada alterada (`ng test` + `ng build`; `vitest` +
|
|
154
|
+
`typecheck` + `build`; `pytest` em ambiente recriado do zero quando dependência mudou).
|
|
155
|
+
|
|
156
|
+
## 11. Pendências conhecidas do padrão
|
|
157
|
+
|
|
158
|
+
- **Permissões só lidas na subida** (SDK antigo): com `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1 os serviços revalidam sozinhos os grupos liberados a cada
|
|
159
|
+
~60 s (`If-None-Match`/ETag no Argos, 304 quando nada mudou) e o encerramento usa `client.close()`. Ao atualizar o
|
|
160
|
+
SDK num app, troque `flushAudit()` por `close()` no SIGTERM e confira se o `/health` deve mostrar `permissionsStale`.
|
|
161
|
+
- **Recusar TLS desligado em produção** depende de a plataforma injetar o ambiente no container (sinal
|
|
162
|
+
confiável); até lá, aviso + `/health`.
|
|
163
|
+
|
|
164
|
+
## 12. Checklist de conformidade (revisão de um app)
|
|
165
|
+
|
|
166
|
+
- [ ] Pastas `angular/`, `graphql/`, `server/`, `database/` e README da raiz com portas e pendências
|
|
167
|
+
- [ ] Só `local`/`dev`/`homol`/`prod`; `.env.example` em cada backend; nenhum `.env` versionado
|
|
168
|
+
- [ ] `REDIS_DB` próprio por ambiente (nenhum outro app no mesmo índice) e prefixo `<app>:` nas chaves/canais
|
|
169
|
+
- [ ] Gateway sobe negando com `/health` 503 → 200; server com `/health` sob o prefixo
|
|
170
|
+
- [ ] Encerramento 0/1 com teto de 8 s; `CMD` em forma exec
|
|
171
|
+
- [ ] Documentação de API só em `local`; TLS desligado avisado; sem `disable_warnings` global
|
|
172
|
+
- [ ] `compression()` no gateway; build typecheck + esbuild; `uvicorn[standard]`
|
|
173
|
+
- [ ] Dependências no formato da seção 8; scripts da seção 9; testes da seção 10
|
|
174
|
+
- [ ] Front: `tsconfig` com `paths` (sem `baseUrl`), environment tipado com `AuthConfig`, nenhum CDN externo
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Fluxo: app novo
|
|
2
|
+
|
|
3
|
+
Estrutura inicial de um app no padrão da plataforma — front, gateway, server e banco, sem domínio nenhum,
|
|
4
|
+
tudo subindo e testado. O desenho completo (pastas, ambientes, saúde, segurança, scripts, testes) está em
|
|
5
|
+
[../arquitetura.md](../arquitetura.md); este fluxo diz a ordem e de onde vem cada peça.
|
|
6
|
+
|
|
7
|
+
Antes de começar, confirme com o usuário: nome do app (vira caminho `/<app>/`, schema do banco e prefixo dos
|
|
8
|
+
canais Redis), quais camadas ele terá, e se o app já está cadastrado no Argos (client do front + um app para o
|
|
9
|
+
gateway e outro para o server, no mesmo realm dos outros). **Não invente ID**: peça o client e os apps, ou
|
|
10
|
+
leia o cadastro que o usuário indicar. Pergunte também as portas locais livres (uma por camada) e escolha um
|
|
11
|
+
`REDIS_DB` livre em cada ambiente (nenhum outro app no mesmo índice — `arquitetura.md` §3.1).
|
|
12
|
+
|
|
13
|
+
**Base**: copie de um app que já segue o padrão (o mais completo disponível), **sem** `node_modules`,
|
|
14
|
+
`dist`, `.angular`, `.venv`, `__pycache__`, `.env`/`.env.*`, `output/`, pasta de domínio, migrations e seeds do
|
|
15
|
+
app de origem — e depois remova o que for específico dele. Copiar do zero de memória gera divergência.
|
|
16
|
+
|
|
17
|
+
| # | Passo | Skill | Onde |
|
|
18
|
+
| --- | --- | --- | --- |
|
|
19
|
+
| 1 | **Esqueleto** `angular/`, `graphql/`, `server/`, `database/` + `.gitignore` da raiz, copiados da base sem artefatos nem domínio | acropole | `arquitetura.md` §1 |
|
|
20
|
+
| 2 | **Front**: nome do projeto no `angular.json` (`outputPath`, `buildTarget`), `baseHref` `/<app>/`, porta nos scripts, `package.json` (nome, versão `0.1.0`), environments dos quatro ambientes com o client/realm do app e o cliente GraphQL `<app>` (`CHANGE_ME` onde a URL deve ser derivada atrás do proxy), `features.routes.ts` vazio com o exemplo comentado, `styles.scss` mínimo, título/`lang="pt-BR"` no `index.html`, `axe-routes.config.json` com a porta e o caminho base. Tire dependências que só a base usava (editor, gráficos) | angular + trismegisto | angular `references/estrutura.md`, `references/testes-build.md` |
|
|
21
|
+
| 3 | **Specs fixos do front** (`app.config`, `core.providers`, `environments`, `core.component`, `features.routes`) ajustados ao app | angular | angular `references/testes-build.md` |
|
|
22
|
+
| 4 | **Gateway**: `AppModules` e `ExtendedSchema` vazios (base `_health` público, `_noop` privado em Mutation **e** Subscription — o GraphQL não aceita tipo raiz vazio), porta, `GRAPHQL_PATH`, prefixo `<app>:` nos canais, mensagens do `response.ts`, `.env.example` com o app do gateway no Argos | apollo + orfeu | apollo `references/estrutura-bootstrap.md` |
|
|
23
|
+
| 5 | **Testes do gateway**: manter os genéricos (subida, autorização com `_noop`, falha de subida, padrões, encerramento), tabela de rotas REST vazia, tirar os de domínio | apollo | apollo `references/testes-build.md` |
|
|
24
|
+
| 6 | **Server**: settings só com Argos, Postgres, Redis e `api_docs` (`api_prefix` `/<app>/server`, porta), `AppSettings`/base declarativa do schema `<app>`, router raiz só com `/health`, `main.py` sem tarefas da base, `.env.example` com o app do server, `pyproject.toml` (poe) com a porta | fastapi + orfeu | fastapi `references/estrutura.md` |
|
|
25
|
+
| 7 | **Testes do server**: `conftest` com a base do app, `test_health`, `test_api_docs` | fastapi | fastapi `references/testes-deploy.md` |
|
|
26
|
+
| 8 | **Banco**: `bootstrap` (role e database `<app>`), `delete/reset.sql`, `create/<app>/01-core.sql` só com `CREATE SCHEMA`, `manifest.yml` com `insert: []`, `env/.env.example`, `test_app.py`, seções "Schemas"/"Particularidades" do `CLAUDE.md` da pasta; `python build.py` para gerar `output/build.sql` | fastapi | fastapi `references/banco.md` |
|
|
27
|
+
| 9 | **Dockerfiles** das três camadas com as portas novas e o caminho do build do front | docker | docker `references/modelos.md` |
|
|
28
|
+
| 10 | **README da raiz**: componentes e portas, cadastro no Argos (IDs públicos), como rodar, padrões, pendências | acropole | `arquitetura.md` |
|
|
29
|
+
| 11 | **Validação**: instalar e rodar tudo — `ng test` + `ng build` + `lint:a11y`; `vitest` + `typecheck` + `build`; ambiente Python novo + `pytest`; `pytest` do banco (PGlite); importar o `main.py` com variáveis fictícias. Procure no app novo o nome da base (`grep -ri`) e o que sobrar de domínio | acropole | `arquitetura.md` §10 |
|
|
30
|
+
|
|
31
|
+
Fora do código (diga ao usuário no fim): **redirect URIs** do client no Argos (`<origem>/<app>/callback` e
|
|
32
|
+
`/logoff`, inclusive `localhost` para o desenvolvimento), **acesso** dos grupos ao client e cada roteador privado
|
|
33
|
+
**liberado** para esses acessos (sem essa liberação o login funciona e o menu vem vazio), permissões das operações para os grupos, URLs reais de
|
|
34
|
+
`homol`/`prod` quando houver deploy, e o `PRODUCT.md` do front quando o escopo do produto estiver definido.
|
|
@@ -9,7 +9,7 @@ schema.
|
|
|
9
9
|
|
|
10
10
|
| # | Passo | Skill | Onde |
|
|
11
11
|
| --- | --- | --- | --- |
|
|
12
|
-
| 1 | **Roteador no Argos**: cadastrar o roteador do client (com descrição) e anotar o `router_id`. É feito no painel do Argos pelo usuário — peça o id, não crie por código | angular | `SKILL.md` "Receita: tela nova", `references/features.md` |
|
|
12
|
+
| 1 | **Roteador no Argos**: cadastrar o roteador do client (com descrição), **liberá-lo para os grupos** que devem ver a tela (roteador privado sem liberação não aparece no menu) e anotar o `router_id`. É feito no painel do Argos pelo usuário — peça o id, não crie por código | angular | `SKILL.md` "Receita: tela nova", `references/features.md` |
|
|
13
13
|
| 2 | **Operação no backend** que a tela vai chamar (Query/Mutation ou rota REST), com operação do Orfeu, `Method` explícito, `Level` e auditoria. Se ainda não existe, rode antes o fluxo [endpoint-novo](endpoint-novo.md) | apollo / fastapi / express + orfeu | ver endpoint-novo |
|
|
14
14
|
| 3 | **Documento GraphQL** em `src/app/services/<dominio>/<dominio>.graphql` + `npm run codegen` com o GraphQL local de pé (gera `<dominio>.generated.ts`, commitado) | angular | `references/dados.md` |
|
|
15
15
|
| 4 | **Service** `providedIn: 'root'` com `injectGraphqlClient` + `unwrap`; erro vira estado da tela | angular | `SKILL.md` "Dados", `references/dados.md` |
|
package/skills/angular/SKILL.md
CHANGED
|
@@ -32,7 +32,7 @@ meu-app/
|
|
|
32
32
|
├── codegen.ts # graphql-codegen (tipos + TypedDocumentNode), roda à mão
|
|
33
33
|
├── Dockerfile # estágios dev / build / site (só o /dist estático)
|
|
34
34
|
├── eslint.a11y.config.js # regras de acessibilidade de template (angular-eslint)
|
|
35
|
-
├── tsconfig.json # strict, baseUrl
|
|
35
|
+
├── tsconfig.json # strict, paths src/* e package.json (sem baseUrl), resolveJsonModule
|
|
36
36
|
└── src/
|
|
37
37
|
├── main.ts # applyRuntimeEnvironment(environment) + bootstrapApplication
|
|
38
38
|
├── index.html # lang="pt-BR", favicon, tela #app-loading
|
|
@@ -96,8 +96,11 @@ Detalhes e exemplos completos: [references/estrutura.md](references/estrutura.md
|
|
|
96
96
|
`development` (só para `ng serve`).
|
|
97
97
|
- `angular.json` > `styles`: `src/styles.scss`, `@trismegisto/tokens/tokens.css`,
|
|
98
98
|
`@trismegisto/core/core.css`.
|
|
99
|
-
- Testes: Karma + Jasmine (`@angular/build:karma`, `ng test`)
|
|
100
|
-
`axe:check
|
|
99
|
+
- Testes: Karma + Jasmine (`@angular/build:karma`, `ng test`), com specs fixos do core (`app.config`,
|
|
100
|
+
`core.providers`, `environments`, `features.routes`). Acessibilidade: `lint:a11y` e `axe:check`, com os
|
|
101
|
+
mesmos arquivos em todo app. Ver [references/testes-build.md](references/testes-build.md).
|
|
102
|
+
- Padrão do app inteiro (pastas do repo, portas, ambientes, scripts, saúde dos backends):
|
|
103
|
+
skill `acropole` (`references/arquitetura.md`).
|
|
101
104
|
|
|
102
105
|
## Receita: tela nova "pedidos"
|
|
103
106
|
|
|
@@ -82,7 +82,11 @@
|
|
|
82
82
|
| Animações | `provideAnimationsAsync()` x `importProvidersFrom(BrowserAnimationsModule)` | `provideAnimationsAsync()` |
|
|
83
83
|
| Change detection global | `provideZoneChangeDetection` uma vez x repetido no `main.ts` | uma vez, em `app.config.ts`, com `eventCoalescing` |
|
|
84
84
|
| Auth | `provideAuth(environment.authorizationServer)` x `AUTH_CONFIG` + `APP_INITIALIZER` | `provideAuth` |
|
|
85
|
-
| Environment | `src/core/environments/` com `authorizationServer` x `src/environments/` com `auth` | `src/core/environments/`, `authorizationServer`, `GraphqlEndpoint` do spine |
|
|
85
|
+
| Environment | `src/core/environments/` com `authorizationServer` x `src/environments/` com `auth` | `src/core/environments/`, `authorizationServer` tipado como `AuthConfig` do `@orfeu/angular`, `GraphqlEndpoint` do spine |
|
|
86
|
+
| Campos de login | interface própria com `silentRenew`/`useRefreshToken`/`postLogoutRedirectUri`/`responseType` | só o `AuthConfig` (os outros a lib não lê) |
|
|
87
|
+
| Imports absolutos | `baseUrl: "./"` (+ `ignoreDeprecations: "6.0"`) x `paths` | `paths` com `src/*` e `package.json`, sem `baseUrl` |
|
|
88
|
+
| Scripts | apps sem `start:homol`, com `start:prod`, `dev` sem `--configuration=dev` | o mesmo conjunto em todo app (`references/estrutura.md`) |
|
|
89
|
+
| Ferramentas de a11y | `@angular-eslint/*` avulsos, `@axe-core/puppeteer`, três `axe-check` diferentes | `angular-eslint` + `axe-core` com versão exata; `axe-check.js` e `eslint.a11y.config.js` idênticos |
|
|
86
90
|
| Ajuste de URL em runtime | `applyRuntimeEnvironment` x cálculo manual no `main.ts` | `applyRuntimeEnvironment` (+ só o específico do app) |
|
|
87
91
|
| Services | `src/app/services/<dominio>/` x dentro de `features/` | `src/app/services/<dominio>/` |
|
|
88
92
|
| Componentes | signals/`input()`/`inject()` x `@Input` + construtor + `standalone: true` | signals/`input()`/`inject()` |
|
|
@@ -21,8 +21,9 @@ Regras:
|
|
|
21
21
|
- Pasta de feature segue o **domínio**, em kebab-case e em inglês ou português de forma consistente no
|
|
22
22
|
app (`pedidos/`, `order-history/`). A URL vem do Argos, então renomear pasta não muda rota.
|
|
23
23
|
- Imports **sempre absolutos a partir de `src/`** (`import { X } from 'src/app/services/pedidos/pedidos.service'`),
|
|
24
|
-
graças a `"
|
|
25
|
-
`
|
|
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.
|
|
26
27
|
|
|
27
28
|
## Nomes
|
|
28
29
|
|
|
@@ -109,8 +110,8 @@ export const appConfig: ApplicationConfig = {
|
|
|
109
110
|
`trismegisto`. `provideAuth()` e suas opções (ex.: `{ eagerInit: false }` para app com
|
|
110
111
|
página pública) ficam na `orfeu`.
|
|
111
112
|
- `provideZoneChangeDetection` **uma vez**, aqui. Não repita no `bootstrapApplication`.
|
|
112
|
-
- `import packageInfo from 'package.json'` depende de `resolveJsonModule` + `
|
|
113
|
-
usa a versão do app na tela "sobre".
|
|
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".
|
|
114
115
|
- Formato legado a evitar: `{ provide: AUTH_CONFIG, useValue }` + `APP_INITIALIZER` chamando
|
|
115
116
|
`auth.initialize()` à mão. Use `provideAuth()`.
|
|
116
117
|
|
|
@@ -158,41 +159,50 @@ Arquivos em `src/core/environments/`:
|
|
|
158
159
|
|
|
159
160
|
| Arquivo | Uso |
|
|
160
161
|
| --- | --- |
|
|
161
|
-
| `environment.config.ts` |
|
|
162
|
+
| `environment.config.ts` | Interface `Environment` |
|
|
162
163
|
| `environment.ts` | Base (é o que os imports referenciam) |
|
|
163
164
|
| `environment.prod.ts`, `.homol.ts`, `.dev.ts`, `.local.ts` | Trocados por `fileReplacements` na configuração de build homônima |
|
|
164
165
|
|
|
165
166
|
Campos (só os nomes; os valores são de cada ambiente):
|
|
166
167
|
|
|
167
168
|
```ts
|
|
169
|
+
import type { AuthConfig } from '@orfeu/angular'; // não redeclarar
|
|
168
170
|
import type { GraphqlEndpoint } from '@trismegisto/spine/graphql'; // não redeclarar
|
|
169
171
|
|
|
170
|
-
export interface AuthorizationServer {
|
|
171
|
-
authority: string; redirectUrl: string; postLogoutRedirectUri: string;
|
|
172
|
-
clientId: string; realmId: string; scope: string;
|
|
173
|
-
silentRenew: boolean; useRefreshToken: boolean;
|
|
174
|
-
}
|
|
175
|
-
|
|
176
172
|
export interface Environment {
|
|
177
173
|
production: boolean;
|
|
178
|
-
authorizationServer:
|
|
174
|
+
authorizationServer: AuthConfig; // authority, realmId, clientId, redirectUrl, scope
|
|
179
175
|
graphql: Record<string, GraphqlEndpoint>; // { namedClient, http, ws? } por backend
|
|
180
176
|
adminApi: string; // API administrativa do Argos (auto-serviço)
|
|
181
177
|
}
|
|
182
178
|
```
|
|
183
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
|
+
|
|
184
185
|
- A chave de `graphql` e o `namedClient` costumam ser o mesmo nome (`pedidos: { namedClient: 'pedidos', ... }`).
|
|
185
186
|
- Use `CHANGE_ME` em URL que deve ser derivada em runtime atrás do proxy.
|
|
186
187
|
- Segredo nunca entra em environment: tudo ali vai para o bundle público.
|
|
187
188
|
- Layout antigo `src/environments/` (fora de `core/`) e nomes de campo diferentes (`auth` em vez de
|
|
188
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.
|
|
189
193
|
|
|
190
194
|
## `tsconfig.json`
|
|
191
195
|
|
|
192
196
|
Base: `strict: true`, `noImplicitOverride`, `noPropertyAccessFromIndexSignature`, `noImplicitReturns`,
|
|
193
197
|
`noFallthroughCasesInSwitch`, `resolveJsonModule`, `isolatedModules`, `moduleResolution: "bundler"`,
|
|
194
|
-
`
|
|
195
|
-
|
|
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`).
|
|
196
206
|
|
|
197
207
|
`tsconfig.app.json`: `files: ["src/main.ts"]` + `include: ["src/**/*.d.ts"]`. Se o app importa `.md`
|
|
198
208
|
como texto, declare em `src/markdown.d.ts`:
|
|
@@ -244,17 +254,26 @@ declare module '*.md' {
|
|
|
244
254
|
|
|
245
255
|
## Scripts do `package.json`
|
|
246
256
|
|
|
257
|
+
Os mesmos scripts, na mesma ordem, em todo app (só a porta muda):
|
|
258
|
+
|
|
247
259
|
```json
|
|
260
|
+
"ng": "ng",
|
|
248
261
|
"start": "ng serve --port 4200",
|
|
249
262
|
"dev": "ng serve --configuration=dev --port 4200 --no-hmr",
|
|
250
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",
|
|
251
265
|
"build": "ng build",
|
|
252
266
|
"build:dev": "ng build --configuration dev",
|
|
253
267
|
"build:homol": "ng build --configuration homol",
|
|
268
|
+
"watch": "ng build --watch --configuration development",
|
|
254
269
|
"test": "ng test",
|
|
255
270
|
"lint:a11y": "eslint --config eslint.a11y.config.js \"src/**/*.html\"",
|
|
256
271
|
"axe:check": "node scripts/axe-check.js",
|
|
257
272
|
"codegen": "graphql-codegen --config codegen.ts"
|
|
258
273
|
```
|
|
259
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
|
+
|
|
260
279
|
Cada app usa uma porta fixa própria no dev-server para não colidir com os outros.
|
|
@@ -41,6 +41,20 @@ describe('features.routes', () => {
|
|
|
41
41
|
importar a classe estaticamente.
|
|
42
42
|
- Com `document`, confira também que `document.load()` devolve texto não vazio.
|
|
43
43
|
|
|
44
|
+
### Specs fixos do core (todo app tem)
|
|
45
|
+
|
|
46
|
+
| Spec | Confere |
|
|
47
|
+
| --- | --- |
|
|
48
|
+
| `src/core/app.config.spec.ts` | Monta os providers num `createEnvironmentInjector` filho do TestBed (sem bootstrap; filtra o `CORE_PROVIDERS[0]`, as animações) e lê os tokens: `SPINE_CONFIG` (clientId, appName, logo), `ROUTES` contém `APP_ROUTES`, `AUTH_CONFIG` = `environment.authorizationServer` e `AUTH_OPTIONS.eagerInit`, `AUTO_SERVICE_CONFIG`/`SPINE_ADMIN_API`, `COMPONENT_ROUTES` com as telas do app + `BASE_COMPONENTS`, `APP_PACKAGE_INFO` |
|
|
49
|
+
| `src/core/core.providers.spec.ts` | São três (animações, HttpClient, GraphQL); `ANIMATION_MODULE_TYPE` = `BrowserAnimations`; o HttpClient passa pelos interceptors do DI; um cliente Apollo por endpoint do environment (`PLATFORM_ID` = `server` para não abrir WebSocket) |
|
|
50
|
+
| `src/core/environments/environments.spec.ts` | Mesmas chaves nos cinco arquivos, só `prod` é `production`, `environment.ts` = `local`, client/realm iguais, URLs sem barra final |
|
|
51
|
+
| `src/core/core.component.spec.ts` | Título da aba |
|
|
52
|
+
| `src/app/features/features.routes.spec.ts` | Ids UUID únicos (sem diferenciar maiúsculas), todo `load()` standalone, documentação carregável |
|
|
53
|
+
|
|
54
|
+
Teste de initializer que mexe em login (`provideAppInitializer`): troque `AuthorizationService` e `Title`
|
|
55
|
+
por dublês no injetor, rode os `APP_INITIALIZER` com `runInInjectionContext` e confira o efeito — inclusive
|
|
56
|
+
quando o login falha (o título não pode depender do login).
|
|
57
|
+
|
|
44
58
|
### Componente que usa service GraphQL: Apollo falso
|
|
45
59
|
|
|
46
60
|
O `injectGraphqlClient` chama `apollo.use(nome).query(...)` e espera um Observable. Substitua o
|
|
@@ -148,10 +162,23 @@ quando a associação é feita em runtime pelo componente: confira o DOM renderi
|
|
|
148
162
|
|
|
149
163
|
### axe no navegador
|
|
150
164
|
|
|
151
|
-
`scripts/axe-check.js` (puppeteer +
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
165
|
+
`scripts/axe-check.js` é **o mesmo arquivo em todo app** (puppeteer + `axe-core`). Lê as telas do
|
|
166
|
+
`features.routes.ts` (cada `{ id, load }`, pelo `id:` e o `.then(m => m.X)`), cruza com o `routeIdToPath` do
|
|
167
|
+
`axe-routes.config.json` (na raiz do app) e roda o axe em `staticRoutes` + nas telas com path conhecido;
|
|
168
|
+
avisa das que não têm. As URLs vêm do Argos em runtime: o `routeIdToPath` é preenchido navegando logado.
|
|
169
|
+
|
|
170
|
+
```json
|
|
171
|
+
{
|
|
172
|
+
"baseUrl": "http://localhost:4200/meu-app/",
|
|
173
|
+
"staticRoutes": ["/login", "/home", "/no-permission"],
|
|
174
|
+
"routeIdToPath": {}
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
- `baseUrl` = origem **e** caminho base do `start:local` (o `baseHref` da configuração `local`); as rotas
|
|
179
|
+
são resolvidas a partir dele (`/login` → `…/meu-app/login`). Sem o caminho base, o axe audita a página 404.
|
|
180
|
+
- Rotas logadas exigem `AXE_STORAGE_STATE=<json com cookies/localStorage>`; sem ele, o que redireciona para
|
|
181
|
+
`/login` é relatado como "sem auth", não como violação. `AXE_FAIL_ON` (padrão `serious`) define a saída 1.
|
|
155
182
|
|
|
156
183
|
## Build
|
|
157
184
|
|
package/skills/apollo/SKILL.md
CHANGED
|
@@ -78,15 +78,19 @@ Domínios com os mesmos nomes do serviço de trás e do front. Detalhes e códig
|
|
|
78
78
|
7. **Introspecção só com `GRAPHQL_INTROSPECTION=true`** (no `.env.local` de quem roda o codegen), nunca
|
|
79
79
|
derivada de `NODE_ENV`. `allowBatchedHttpRequests: true` sempre (o front envia em lote).
|
|
80
80
|
8. **Encerramento**: o `node` é PID 1 no container — trate `SIGTERM`/`SIGINT`: `orfeu.flushAudit()`,
|
|
81
|
-
`apollo.server.stop()` (o plugin de drain fecha HTTP e WS)
|
|
81
|
+
`apollo.server.stop()` (o plugin de drain fecha HTTP e WS); sai com **0** ao completar e com **1** se
|
|
82
|
+
estourar o teto de 8 s.
|
|
82
83
|
9. Tudo que lê `process.env` em escopo de módulo quebra (ESM roda imports antes do `dotenv.config`): crie
|
|
83
84
|
clientes (Redis, axios) **dentro** do builder ou de forma preguiçosa.
|
|
84
|
-
10. **Orfeu fora do ar na subida
|
|
85
|
-
|
|
86
|
-
|
|
85
|
+
10. **Orfeu fora do ar na subida: sobe negando** (padrão único). O servidor sobe, `/health` responde **503**
|
|
86
|
+
até o Orfeu conectar, toda operação não pública é negada e o `startup()` é tentado de novo com espera
|
|
87
|
+
crescente (5 s → 30 s). `OrfeuConfigError` derruba a subida. Nunca um modo que libera sem autorização
|
|
87
88
|
([references/estrutura-bootstrap.md](references/estrutura-bootstrap.md)).
|
|
88
89
|
11. **Contexto é do servidor, não do cliente**: nada de `ctx.orfeuUser` gravado à mão (usuário validado por
|
|
89
90
|
fora entra por `trustUser`) nem `connectionParams` espalhado no contexto do WebSocket.
|
|
91
|
+
12. **`compression()` antes do Apollo** em todo gateway, e `AUTH_TLS_VERIFY=false` (se existir) com aviso na
|
|
92
|
+
subida e `tls_verify: false` no `/health`. Padrão completo do app (pastas, portas, scripts, saúde):
|
|
93
|
+
skill `acropole` (`references/arquitetura.md`).
|
|
90
94
|
|
|
91
95
|
## Esqueleto de um recurso
|
|
92
96
|
|
|
@@ -187,10 +191,10 @@ A autorização é **por campo** (preguiçosa), não na conexão. Canais Redis c
|
|
|
187
191
|
## Comandos
|
|
188
192
|
|
|
189
193
|
```bash
|
|
190
|
-
npm run dev # tsx watch, NODE_ENV=local
|
|
191
|
-
npm run build #
|
|
194
|
+
npm run dev # tsx watch, NODE_ENV=local (também start:local / start:homol)
|
|
195
|
+
npm run build # typecheck + esbuild --bundle → dist/index.js (um arquivo, em milissegundos)
|
|
192
196
|
npm run start:prod # node dist/index.js
|
|
193
|
-
npm run typecheck # tsc --noEmit
|
|
197
|
+
npm run typecheck # tsc --noEmit
|
|
194
198
|
npx vitest run # unitários
|
|
195
199
|
```
|
|
196
200
|
|
|
@@ -205,7 +209,7 @@ variáveis de ambiente e logs: [references/testes-build.md](references/testes-bu
|
|
|
205
209
|
- Contexto do WS sem `App` → `ctx.App` indefinido só nas subscriptions.
|
|
206
210
|
- `connectionParams` espalhado no contexto do WS → cliente forja chaves do `ctx` (com `@orfeu/node` 1.0.0,
|
|
207
211
|
até o usuário).
|
|
208
|
-
- Orfeu fora na subida com `/health` em 200 → o deploy vê saudável um gateway que nega tudo.
|
|
212
|
+
- Orfeu fora na subida com `/health` em 200 → o deploy vê saudável um gateway que nega tudo (o padrão é 503).
|
|
209
213
|
- Campo novo sem `operation()` → servidor não sobe (correto); campo reaproveitando função → erro de marca dupla.
|
|
210
214
|
- Esquecer `resolve` na subscription → `null` (o resolver padrão procura a chave com o nome do campo).
|
|
211
215
|
- Envelope sem `data` anulável ou sem `Response` no nome → codegen/`unwrap` do front quebram.
|
|
@@ -32,7 +32,11 @@ Cada item aconteceu em servidor GraphQL de verdade. Formato: sintoma → causa
|
|
|
32
32
|
- **"Modo degradado" que libera tudo quando o Argos está fora** → nunca; tente o `startup()` de novo em
|
|
33
33
|
segundo plano e mantenha negado até conectar.
|
|
34
34
|
- **Serviço "saudável" negando tudo** → subiu sem o Orfeu (startup em segundo plano) e o `/health` dizia
|
|
35
|
-
200 → enquanto o Orfeu não conecta, `/health` responde 503
|
|
35
|
+
200 → enquanto o Orfeu não conecta, `/health` responde 503 (padrão: sobe negando, nova tentativa 5 s → 30 s).
|
|
36
|
+
- **Loop de restart com o Argos fora** → gateway que cai (`exit 1`) quando o `startup()` falha → suba negando
|
|
37
|
+
e tente de novo; só `OrfeuConfigError` (configuração errada) derruba a subida.
|
|
38
|
+
- **Encerramento por teto saindo com 0** → o orquestrador não distingue drenagem completa de travamento →
|
|
39
|
+
`exit(0)` ao completar, `exit(1)` no teto de 8 s.
|
|
36
40
|
- **401 em todo campo depois de atualizar o `@orfeu/node` para 1.0.1** → o `context()` gravava
|
|
37
41
|
`orfeuUser` à mão → `trustUser(ctx, claims)`, ou deixe o `orfeuPlugin` capturar a credencial.
|
|
38
42
|
- **Validação de token duplicada no `context()`** (montando `{ token, user }` à mão) → diverge do guard e
|