@acropole/skills 1.2.0 → 1.4.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 +4 -3
- package/package.json +4 -4
- package/skills/acropole/SKILL.md +2 -0
- package/skills/acropole/references/arquitetura.md +29 -5
- package/skills/acropole/references/fluxos/app-novo.md +4 -4
- package/skills/acropole/references/fluxos/tela-nova.md +1 -1
- package/skills/apollo/references/subscriptions.md +10 -4
- package/skills/apollo/references/testes-build.md +1 -0
- package/skills/auto-servico/SKILL.md +153 -0
- package/skills/auto-servico/references/diagnostico.md +42 -0
- package/skills/auto-servico/references/roteiros.md +63 -0
- package/skills/auto-servico/references/tools.md +108 -0
- package/skills/docker/SKILL.md +3 -0
- package/skills/docker/references/podman-local.md +73 -0
- package/skills/express/references/dados.md +3 -1
- package/skills/fastapi/SKILL.md +4 -4
- package/skills/fastapi/references/banco.md +53 -50
- package/skills/fastapi/references/estrutura.md +2 -2
- package/skills/fastapi/references/integracoes.md +8 -0
- package/skills/hefesto/SKILL.md +49 -14
- package/skills/hefesto/references/diagnostico.md +15 -5
- package/skills/hefesto/references/fluxo.md +64 -35
- package/skills/hefesto/references/mcp-diagnostico.md +44 -0
- package/skills/hefesto/references/mcp-roteiros.md +53 -0
- package/skills/hefesto/references/mcp-tools.md +94 -0
- package/skills/orfeu/SKILL.md +1 -1
- package/skills/orfeu/references/diferencas.md +1 -1
- package/skills/orfeu/references/node.md +1 -1
- package/skills/orquestracao/SKILL.md +1 -1
- package/skills/orquestracao/templates/spec.md +1 -1
- package/skills/trismegisto/SKILL.md +4 -4
- package/skills/trismegisto/references/angular-api.md +653 -507
- package/skills/trismegisto/references/angular-exports.md +541 -130
- package/skills/trismegisto/references/angular-types.md +1 -1
- package/skills/trismegisto/references/angular.md +28 -8
- package/skills/trismegisto/references/catalogo/icones.json +5 -0
- package/skills/trismegisto/references/catalogo/seletores.json +452 -31
- package/skills/trismegisto/references/catalogo/tokens.json +136 -16
- package/skills/trismegisto/references/spine-api.md +181 -44
- package/skills/trismegisto/references/spine-recipes.md +1 -1
- package/skills/trismegisto/references/spine.md +4 -3
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Catálogo de API — @trismegisto/spine
|
|
2
2
|
|
|
3
|
-
> **Gerado** por `scripts/gerar/trismegisto-spine.mjs` a partir do código-fonte da versão
|
|
3
|
+
> **Gerado** por `scripts/gerar/trismegisto-spine.mjs` a partir do código-fonte da versão 2.0.1, a cada `npm run sync` do @acropole/skills.
|
|
4
4
|
> Gerado do código-fonte do `@trismegisto/spine`. Confira a versão instalada no `package.json` do pacote em `node_modules`.
|
|
5
5
|
|
|
6
6
|
Uma seção por ponto de entrada (o `import` exato). Dentro dela: componentes (seletor, inputs/outputs),
|
|
@@ -55,18 +55,28 @@ Preferências do usuário que não são de tema (tema/família/densidade continu
|
|
|
55
55
|
|
|
56
56
|
#### `SpineQuickAccessService` · `providedIn: root`
|
|
57
57
|
|
|
58
|
-
|
|
58
|
+
Favorites and recently visited pages, shared by every consumer in the app (page bar, home screen) and persisted per client and per user in `localStorage` (`SpineUserStorage`: `<clientId>_nav_favorites_<sub>`). Recents are cleared on logout; switching users reloads both lists.
|
|
59
59
|
|
|
60
60
|
- `readonly favorites: Signal (somente leitura)`
|
|
61
61
|
- `readonly recents: Signal (somente leitura)`
|
|
62
62
|
- `isFavorite(id: string | null | undefined): boolean`
|
|
63
63
|
- `toggleFavorite(item: QuickAccessItem): void`
|
|
64
|
-
- `recordVisit(item: QuickAccessItem): void`
|
|
64
|
+
- `recordVisit(item: QuickAccessItem): void`
|
|
65
65
|
- `forgetRecent(id: string): void`
|
|
66
66
|
|
|
67
|
+
#### `SpineUserStorage` · `providedIn: root`
|
|
68
|
+
|
|
69
|
+
Chaves de `localStorage` do shell por usuário: `<clientId>_<lista>_<sub>`, com o `sub` do token da sessão. Num computador compartilhado, uma pessoa não vê os recentes/buscas/favoritos de quem entrou antes.
|
|
70
|
+
|
|
71
|
+
- `userId(): string` — `sub` do token da sessão (só leitura do payload); vazio sem sessão.
|
|
72
|
+
- `key(list: SpineUserStorageKey): string` — Chave de `localStorage` da lista para o usuário atual.
|
|
73
|
+
- `clearHistory(): void` — Apaga buscas recentes e páginas recentes do usuário (o atual ou o último visto). Favoritos ficam.
|
|
74
|
+
|
|
67
75
|
### Funções
|
|
68
76
|
|
|
69
77
|
- `function routerIdOf(route: Route | null | undefined): string | null` — `router_id` da tela (nó 'page'), aceitando o argos antigo (que só mandava `route_id`, mesmo valor).
|
|
78
|
+
- `function mergeRouteTree(routes: readonly Route[] | null | undefined): Route[]` — Funde nós IRMÃOS que apontam para o mesmo endereço (`route_redirect`), em toda a árvore.
|
|
79
|
+
- `function spineRoutesOf(view: { routes?: readonly Route[] | null } | null | undefined): Route[]` — A árvore fundida da view atual (`ViewService.currentView`) — ver `mergeRouteTree`.
|
|
70
80
|
- `function provideUi(config?: SpineConfig): EnvironmentProviders` — Registra o catálogo de ícones inteiro — o spine (header/sidebar/navegação/modal/onboarding) usa ícones de várias origens (shield, pencil, trash, floppy, chevrons...) que não vêm embutidos de graça (os componentes do hermes só registram os ícones que eles próp…
|
|
71
81
|
- `function resolveSpineLogo(logo: SpineLogoConfig | false | null | undefined): SpineLogoSources | null` — Normaliza `SpineConfig.logo`: omitido → convenção; `false`/vazio → sem imagem (`null`).
|
|
72
82
|
- `function applySpineFavicon(doc: Document, href: string): HTMLLinkElement | null` — Aponta o favicon do documento para `href`: atualiza o primeiro `<link rel="icon">` (ou `shortcut icon`) e remove os outros (senão o navegador pode continuar escolhendo um deles); sem nenhum, cria um no `<head>`. O `type` acompanha a extensão (some quando ela…
|
|
@@ -82,6 +92,7 @@ Favoritos e páginas abertas por último. Um serviço só, e não cada component
|
|
|
82
92
|
- `SPINE_DEFAULT_LOGO`: `'assets/images/logo.svg'` — Convenção quando o app não configura `logo`: `src/assets/images/logo.svg` servido em `assets/images/`.
|
|
83
93
|
- `APP_PACKAGE_INFO`: `InjectionToken<PackageInfo>`
|
|
84
94
|
- `SPINE_ADMIN_API`: `InjectionToken<string>` — Base da API do argos-admin-server (ex.: `https://exemplo.com.br/argos/admin/api`) — recursos do próprio usuário (`/me/*`, hoje os tokens de aplicação) que o painel de configurações usa. Quem chama `provideAutoService({ adminApi })` já fornece este token (é a…
|
|
95
|
+
- `SPINE_USER_STORAGE_KEYS` — Listas do shell guardadas no navegador, por usuário.
|
|
85
96
|
- `SPINE_NEWS`: `InjectionToken<readonly (readonly SpineNewsItem[])[]>` — Multi: cada chamada de `provideSpineNews` contribui com uma lista.
|
|
86
97
|
- `SPINE_MESSAGES_PT_BR`: `SpineMessages`
|
|
87
98
|
- `SPINE_MESSAGES_EN`: `SpineMessages`
|
|
@@ -221,20 +232,25 @@ interface PackageInfo {
|
|
|
221
232
|
|
|
222
233
|
#### `QuickAccessItem` (interface)
|
|
223
234
|
|
|
224
|
-
|
|
235
|
+
A page remembered by the shell, either as a favorite or as a recent visit.
|
|
225
236
|
|
|
226
237
|
```ts
|
|
227
238
|
interface QuickAccessItem {
|
|
228
|
-
/** Identidade do item: o endereço da página (`route_redirect`). */
|
|
229
239
|
readonly id: string;
|
|
230
240
|
readonly icon: string;
|
|
231
241
|
readonly displayName: string;
|
|
232
242
|
readonly redirect: string;
|
|
233
|
-
/**
|
|
243
|
+
/** Ancestor labels, top-down. `[]` = top-level page; absent = stored by an older version. */
|
|
234
244
|
readonly trail?: readonly string[];
|
|
235
245
|
}
|
|
236
246
|
```
|
|
237
247
|
|
|
248
|
+
#### `SpineUserStorageKey` (type)
|
|
249
|
+
|
|
250
|
+
```ts
|
|
251
|
+
type SpineUserStorageKey = (typeof SPINE_USER_STORAGE_KEYS)[keyof typeof SPINE_USER_STORAGE_KEYS];
|
|
252
|
+
```
|
|
253
|
+
|
|
238
254
|
#### `RuntimeEnvironmentShape` (interface)
|
|
239
255
|
|
|
240
256
|
O mínimo do `environment` de um app que dá pra derivar em tempo de execução. Estrutural de propósito (não importa o `Environment` de nenhum app): serve pra todos.
|
|
@@ -306,7 +322,7 @@ interface SpineNewsItem {
|
|
|
306
322
|
|
|
307
323
|
#### `SpineMessages` (interface)
|
|
308
324
|
|
|
309
|
-
Textos do próprio spine (cabeçalho, navegação, configurações, tour, telas do auto-serviço…), no mesmo formato do `HermesMessages` da lib: seção → chave, parâmetros nomeados (`{name}`) e plural por `PluralMessage`. Alguns textos levam marcação simples (`<b>`, `<strong>`, `<code>`) e são exibidos com `[innerHTML]` — estão indicados no comentário.
|
|
325
|
+
Textos do próprio spine (cabeçalho, navegação, configurações, tour, telas do auto-serviço…), no mesmo formato do `HermesMessages` da lib: seção → chave, parâmetros nomeados (`{name}`) e plural por `PluralMessage`. Alguns textos levam marcação simples (`<b>`, `<strong>`, `<code>`) e são exibidos com `[innerHTML]` — estão indicados no comentário. Os que têm parâmetro saem por `formatMessageHtml` (`…
|
|
310
326
|
|
|
311
327
|
_Declaração longa — veja `@trismegisto/spine` em `node_modules` (arquivo de tipos do ponto de entrada)._
|
|
312
328
|
|
|
@@ -751,6 +767,8 @@ interface AuditTopRow {
|
|
|
751
767
|
- `createRouter(clientId: string, body: any)`
|
|
752
768
|
- `updateRouter(clientId: string, id: string, body: any)`
|
|
753
769
|
- `deleteRouter(clientId: string, id: string)`
|
|
770
|
+
- `getRouterTree(clientId: string)` — Árvore do menu (header → … → página) com os router_ids de cada nó, já na ordem gravada.
|
|
771
|
+
- `reorderRouters(clientId: string, groups: RouterOrderGroup[])` — Grava a ordem de UM nível (irmãos): o índice do grupo é a ordem; cada grupo escreve `${type}_order` em todos os seus routers. Vale também para routers de template (ordem é do client).
|
|
754
772
|
- `getGroups(clientId: string)`
|
|
755
773
|
- `getGroupMembers(clientId: string, groupId: string)`
|
|
756
774
|
- `addGroupMember(clientId: string, groupId: string, userId: string, role: string | null)`
|
|
@@ -788,6 +806,7 @@ interface AuditTopRow {
|
|
|
788
806
|
- `AUTO_SERVICE_AUDIT_TEMPLATE_ROUTER_ID`: `'ad100004-0000-4000-8000-000000000001'`
|
|
789
807
|
- `AUTO_SERVICE_HOME_TEMPLATE_ROUTER_ID`: `'6a9a13db-f31b-494e-b51c-79af0ac28b60'`
|
|
790
808
|
- `AUTO_SERVICE_SCREENS`: `Readonly<Record<'home' | 'groups' | 'apps' | 'client' | 'audit', () => Promise<Type<unknown>>>>` — As 5 telas do auto-serviço, carregadas sob demanda. Cada `import()` relativo vira um chunk próprio no FESM publicado (`trismegisto-spine-auto-service-<tela>-<hash>.mjs`), que o bundler do app mantém fora do carregamento inicial. Não exporte as telas no `publi…
|
|
809
|
+
- `AUTO_SERVICE_DOCUMENTS`: `Readonly<Record<keyof typeof AUTO_SERVICE_SCREENS, RouteDocument>>` — Documentação das 5 telas (botão de documentação da barra da página e índice "Documentação do sistema"): o manual de uso (`load`) e a especificação técnica (`loadTechnical`, só com `SpineConfig.technicalDocs`). O Markdown fica em módulos `.ts` próprios em `./d…
|
|
791
810
|
|
|
792
811
|
### Tipos
|
|
793
812
|
|
|
@@ -802,6 +821,39 @@ interface AutoServiceConfig {
|
|
|
802
821
|
}
|
|
803
822
|
```
|
|
804
823
|
|
|
824
|
+
#### `RouterOrderType` (type)
|
|
825
|
+
|
|
826
|
+
Nível de um nó na árvore do menu (`GET /routers/tree`).
|
|
827
|
+
|
|
828
|
+
```ts
|
|
829
|
+
type RouterOrderType = 'header' | 'navigation' | 'menu' | 'item' | 'submenu' | 'page';
|
|
830
|
+
```
|
|
831
|
+
|
|
832
|
+
#### `RouterOrderNode` (interface)
|
|
833
|
+
|
|
834
|
+
Nó da árvore do menu: uma rota num nível, com todos os routers que passam por ela.
|
|
835
|
+
|
|
836
|
+
```ts
|
|
837
|
+
interface RouterOrderNode {
|
|
838
|
+
route_type: RouterOrderType;
|
|
839
|
+
routed_id: string;
|
|
840
|
+
route_name: string;
|
|
841
|
+
route_display_name: string | null;
|
|
842
|
+
route_icon: string | null;
|
|
843
|
+
order: number;
|
|
844
|
+
router_ids: string[];
|
|
845
|
+
children: RouterOrderNode[];
|
|
846
|
+
}
|
|
847
|
+
```
|
|
848
|
+
|
|
849
|
+
#### `RouterOrderGroup` (interface)
|
|
850
|
+
|
|
851
|
+
Um item da ordem nova de um nível (`PATCH /routers/reorder`).
|
|
852
|
+
|
|
853
|
+
```ts
|
|
854
|
+
interface RouterOrderGroup { type: RouterOrderType; router_ids: string[] }
|
|
855
|
+
```
|
|
856
|
+
|
|
805
857
|
#### `AutoServiceClient` (interface)
|
|
806
858
|
|
|
807
859
|
```ts
|
|
@@ -819,26 +871,26 @@ interface AutoServiceClient {
|
|
|
819
871
|
|
|
820
872
|
#### `GraphqlEnvelopeError` · extends Error
|
|
821
873
|
|
|
822
|
-
|
|
874
|
+
Business failure carried by an envelope. `status` is kept exactly as the backend sent it.
|
|
823
875
|
|
|
824
876
|
### Funções
|
|
825
877
|
|
|
826
|
-
- `function isEnvelopeOk(status: GraphqlEnvelope<unknown>['status']): boolean`
|
|
827
|
-
- `function unwrap<T>(envelope: GraphqlEnvelope<T> | null | undefined): T` —
|
|
828
|
-
- `function envelopesOf(data: unknown): { field: string; status: number | string; message: string; ok: boolean }[]` —
|
|
829
|
-
- `function failedEnvelopes(data: unknown, fallbackMessage: string = currentSpineMessages().graphql.serviceFailure): { field: string; status: unknown; message: string }[]` —
|
|
878
|
+
- `function isEnvelopeOk(status: GraphqlEnvelope<unknown>['status']): boolean`
|
|
879
|
+
- `function unwrap<T>(envelope: GraphqlEnvelope<T> | null | undefined): T` — Returns `data` of an ok envelope; throws `GraphqlEnvelopeError` for a missing or failed one.
|
|
880
|
+
- `function envelopesOf(data: unknown): { field: string; status: number | string; message: string; ok: boolean }[]` — First-level envelopes found in an operation's `data` (fields that carry both `status` and `message`).
|
|
881
|
+
- `function failedEnvelopes(data: unknown, fallbackMessage: string = currentSpineMessages().graphql.serviceFailure): { field: string; status: unknown; message: string }[]` — First-level fields whose status is a failure; `message` is optional here.
|
|
830
882
|
- `function injectGraphqlClient(namedClient: string): GraphqlClient` — O `GraphqlClient` do backend `namedClient` (`environment.graphql.<chave>.namedClient`). Chamar em contexto de injeção.
|
|
831
|
-
- `function provideGraphql(options: GraphqlOptions): Provider`
|
|
883
|
+
- `function provideGraphql(options: GraphqlOptions): Provider`
|
|
832
884
|
|
|
833
885
|
### Constantes e tokens
|
|
834
886
|
|
|
835
|
-
- `wsReconnected$`: `Subject<string>` —
|
|
887
|
+
- `wsReconnected$`: `Subject<string>` — Emits the `namedClient` whose socket came back after a drop (never on the first connection).
|
|
836
888
|
|
|
837
889
|
### Tipos
|
|
838
890
|
|
|
839
891
|
#### `GraphqlEnvelope` (interface)
|
|
840
892
|
|
|
841
|
-
|
|
893
|
+
Shape every root query/mutation field returns on the platform: business status travels in the payload.
|
|
842
894
|
|
|
843
895
|
```ts
|
|
844
896
|
interface GraphqlEnvelope<T> {
|
|
@@ -877,25 +929,19 @@ interface GraphqlClient {
|
|
|
877
929
|
|
|
878
930
|
#### `GraphqlEndpoint` (interface)
|
|
879
931
|
|
|
880
|
-
Um backend GraphQL do app — o tipo de `environment.graphql.<chave>` em TODO app (importar daqui, não redeclarar). Campos mutáveis de propósito: o `main.ts` pode derivar `http`/`ws` do domínio em tempo de execução antes do bootstrap.
|
|
881
|
-
|
|
882
932
|
```ts
|
|
883
933
|
interface GraphqlEndpoint {
|
|
884
|
-
|
|
934
|
+
// Mutable on purpose: the runtime environment rewrites `http`/`ws` before bootstrap.
|
|
885
935
|
namedClient: string;
|
|
886
936
|
http: string;
|
|
887
|
-
/** Sem `ws`, o cliente não tem subscription (só HTTP). */
|
|
888
937
|
ws?: string;
|
|
889
938
|
}
|
|
890
939
|
```
|
|
891
940
|
|
|
892
941
|
#### `GraphqlOptions` (interface)
|
|
893
942
|
|
|
894
|
-
Sem opções de comportamento DE PROPÓSITO: o padrão é o mesmo em todo app (lote, toast do envelope, reconexão, no-cache). O que varia entre apps é só QUAIS backends existem (`endpoints`).
|
|
895
|
-
|
|
896
943
|
```ts
|
|
897
944
|
interface GraphqlOptions {
|
|
898
|
-
/** `environment.graphql` do app: um cliente Apollo nomeado por entrada. */
|
|
899
945
|
readonly endpoints: Readonly<Record<string, GraphqlEndpoint>>;
|
|
900
946
|
}
|
|
901
947
|
```
|
|
@@ -943,7 +989,7 @@ _Sem inputs/outputs._
|
|
|
943
989
|
|
|
944
990
|
#### `spine-onboarding-overlay` — `OnboardingOverlayComponent`
|
|
945
991
|
|
|
946
|
-
|
|
992
|
+
Desenho do tour guiado: escurece a tela, recorta um holofote sobre o alvo do passo e põe o balão (título, texto, progresso e navegação) onde couber. Segue o `OnboardingService`; recalcula a cada passo e quando a janela rola ou muda de tamanho.
|
|
947
993
|
|
|
948
994
|
_Sem inputs/outputs._
|
|
949
995
|
|
|
@@ -955,7 +1001,7 @@ _Sem inputs/outputs._
|
|
|
955
1001
|
|
|
956
1002
|
#### `spine-settings-panel` — `SettingsPanelComponent`
|
|
957
1003
|
|
|
958
|
-
Painel de configurações do shell (substitui as telas do antigo módulo "Sistema"): Aparência, Região, Atalhos, Conta e Sobre, mais as seções que o app registrar com `provideSettingsSection`. Tudo vale na hora — cada controle chama o serviço que já persiste aquela preferência (tema, densidade, menu lateral, fuso).
|
|
1004
|
+
Painel de configurações do shell (substitui as telas do antigo módulo "Sistema"): Aparência, Região, Atalhos, Conta, Conta e segurança (MFA, códigos de recuperação e sessões do Argos) e Sobre, mais as seções que o app registrar com `provideSettingsSection`. Tudo vale na hora — cada controle chama o serviço que já persiste aquela preferência (tema, densidade, menu lateral, fuso).
|
|
959
1005
|
|
|
960
1006
|
_Sem inputs/outputs._
|
|
961
1007
|
|
|
@@ -967,17 +1013,17 @@ _Sem inputs/outputs._
|
|
|
967
1013
|
|
|
968
1014
|
#### `spine-docs` — `SpineDocsComponent`
|
|
969
1015
|
|
|
970
|
-
Modal de documentação: índice com busca à esquerda
|
|
1016
|
+
Modal de documentação das telas: índice (com busca) à esquerda e leitura à direita. Montado uma vez pelo `spine-layout`; abrir, fechar e o que se lê vêm todos do `SpineDocsService`.
|
|
971
1017
|
|
|
972
1018
|
_Sem inputs/outputs._
|
|
973
1019
|
|
|
974
1020
|
#### `spine-markdown` — `SpineMarkdownComponent`
|
|
975
1021
|
|
|
976
|
-
Markdown
|
|
1022
|
+
Renderiza Markdown (GFM) como HTML com a tipografia do design system. O texto é tratado como dado: o HTML gerado passa pelo DOMPurify, com o perfil restrito do spine (`SPINE_MARKDOWN_PURIFY_CONFIG`: sem `<style>`/`style`, formulários e `<iframe>`; link externo com `rel="noopener noreferrer"`), antes de chegar ao DOM.
|
|
977
1023
|
|
|
978
1024
|
| Nome | Tipo | Tipo TS | Padrão | Descrição |
|
|
979
1025
|
|---|---|---|---|---|
|
|
980
|
-
| `content` | input | `string` | `''` |
|
|
1026
|
+
| `content` | input | `string` | `''` | Markdown cru. Vazio não desenha nada. |
|
|
981
1027
|
|
|
982
1028
|
### Serviços e classes
|
|
983
1029
|
|
|
@@ -986,8 +1032,11 @@ Markdown → HTML sanitizado. O HTML vem de `innerHTML`, que o encapsulamento de
|
|
|
986
1032
|
Onboarding interativo próprio (sem dependência externa). O overlay/holofote e o balão são renderizados pelo OnboardingOverlayComponent, que escuta este serviço. Aparece uma vez por máquina (flag em localStorage), namespaced por cliente.
|
|
987
1033
|
|
|
988
1034
|
- `readonly current$: BehaviorSubject` — Passo atual (null = tour inativo). O overlay component reage a isto.
|
|
989
|
-
- `
|
|
990
|
-
- `
|
|
1035
|
+
- `readonly state$: Observable<OnboardingState>` — Fase do tour (ver `OnboardingState`). Emite o valor atual ao assinar.
|
|
1036
|
+
- `get state: OnboardingState` — Fase atual, síncrona.
|
|
1037
|
+
- `maybeStart(): void` — Dispara o tour só se ainda não foi visto nesta máquina. Chamar após o login. Quando é devido, o estado vira `pending` NA HORA (síncrono), antes da espera pelo shell — é isso que segura as novidades; quando não é, contin…
|
|
1038
|
+
- `restart(): void` — Reabre o tour manualmente (menu Ajuda), ignorando a flag. Também passa por `pending` → `running`.
|
|
1039
|
+
- `stop(): void` — Interrompe o tour (pendente ou na tela) SEM marcar como visto: o automático volta na próxima entrada. Usado quando a pessoa abre outra coisa que disputaria a tela com ele (as novidades pelo menu).
|
|
991
1040
|
- `next(): void`
|
|
992
1041
|
- `prev(): void`
|
|
993
1042
|
- `finish(): void` — Encerra o tour (concluído ou pulado) e marca como visto.
|
|
@@ -1024,21 +1073,33 @@ Tokens de aplicação pessoais (`x-app-token`) do usuário logado — `argos-adm
|
|
|
1024
1073
|
- `create(body: { badge_id: string; name: string; validity_days: number }): Promise<CreatedAppToken>`
|
|
1025
1074
|
- `revoke(id: string): Promise<void>`
|
|
1026
1075
|
|
|
1076
|
+
#### `SpineAccountSecurityService` · `providedIn: root`
|
|
1077
|
+
|
|
1078
|
+
Conta do usuário no Argos (verificação em duas etapas, códigos de recuperação, sessões) pela API da conta com Bearer: o access token da sessão do app (`@orfeu/angular`), no header `Authorization` — o mesmo jeito que o Orfeu fala com o Argos (ex.: `switchBadge`). O Argos reconhece a sessão SSO pelo `sid` do token; não há cookie envolvido. Token vencido (`401 invalid_token`): renova uma vez (`silentRenew`) e repete. `available` é falso sem `AUTH_CONFIG` utilizável.
|
|
1079
|
+
|
|
1080
|
+
- `readonly baseUrl`
|
|
1081
|
+
- `readonly available`
|
|
1082
|
+
- `overview(): Promise<AccountOverview>`
|
|
1083
|
+
- `register(methodId: string, code: string): Promise<AccountOverview>`
|
|
1084
|
+
- `remove(methodId: string): Promise<AccountOverview>`
|
|
1085
|
+
- `sessions(): Promise<{ sessions: AccountSession[] }>`
|
|
1086
|
+
- `endOtherSessions(): Promise<{ ended: number }>`
|
|
1087
|
+
|
|
1027
1088
|
#### `SpineDocsService` · `providedIn: root`
|
|
1028
1089
|
|
|
1029
|
-
|
|
1090
|
+
Estado da documentação das telas: o que está registrado em `COMPONENT_ROUTES` com `document`, filtrado pelas telas que existem na árvore da pessoa (documento de tela sem acesso nunca é oferecido), e a leitura em andamento no modal `spine-docs`.
|
|
1030
1091
|
|
|
1031
|
-
- `readonly technicalAvailable`
|
|
1092
|
+
- `readonly technicalAvailable: boolean` — Visão técnica liberada (`SpineConfig.technicalDocs`; sem configuração, só em desenvolvimento).
|
|
1032
1093
|
- `readonly isOpen: Signal (somente leitura)`
|
|
1033
1094
|
- `readonly current: Signal (somente leitura)`
|
|
1034
1095
|
- `readonly view: Signal (somente leitura)`
|
|
1035
1096
|
- `readonly content: Signal (somente leitura)`
|
|
1036
1097
|
- `readonly loading: Signal (somente leitura)`
|
|
1037
|
-
- `readonly error: computed(…)`
|
|
1098
|
+
- `readonly error: computed(…)`
|
|
1038
1099
|
- `readonly showTechnical: computed(…)`
|
|
1039
1100
|
- `readonly index: computed<DocsGroup[]>(…)`
|
|
1040
|
-
- `documentFor(routerId: string | null | undefined, sourceTemplateRouterId?: string | null): DocsEntry | null`
|
|
1041
|
-
- `openForRoute(routerId: string | null | undefined, sourceTemplateRouterId?: string | null): void`
|
|
1101
|
+
- `documentFor(routerId: string | null | undefined, sourceTemplateRouterId?: string | null): DocsEntry | null`
|
|
1102
|
+
- `openForRoute(routerId: string | null | undefined, sourceTemplateRouterId?: string | null): void`
|
|
1042
1103
|
- `openIndex(): void`
|
|
1043
1104
|
- `close(): void`
|
|
1044
1105
|
- `open(entry: DocsEntry, view: DocsView = 'usage'): Promise<void>`
|
|
@@ -1051,24 +1112,36 @@ Painel de novidades do app (ver `provideSpineNews`). Decide o que está devido
|
|
|
1051
1112
|
- `readonly slides: signal<readonly SpineNewsSlide[]>(…)` — Slides em exibição (os devidos, ou todos os vigentes quando reaberto pelo menu).
|
|
1052
1113
|
- `readonly isOpen: signal(…)`
|
|
1053
1114
|
- `readonly hasAny: computed(…)` — Há alguma novidade vigente — o item "Novidades" do menu só aparece com isto.
|
|
1054
|
-
- `scheduleOnEntry(): void` — Chamado uma vez pelo layout na entrada: abre as devidas,
|
|
1055
|
-
- `showDue(): void` —
|
|
1056
|
-
- `showAll(): void` — Reabre todas as vigentes (menu do perfil), vistas ou não.
|
|
1115
|
+
- `scheduleOnEntry(): void` — Chamado uma vez pelo layout na entrada: abre as devidas quando o tour estiver `idle` (não devido, concluído, pulado ou sem passo), mais `AFTER_TOUR_MS` para não emendar. Se o tour começar nesse intervalo, volta a espera…
|
|
1116
|
+
- `showDue(): void` — Marca como vistas todas as novidades devidas e as abre num único painel.
|
|
1117
|
+
- `showAll(): void` — Reabre todas as vigentes (menu do perfil), vistas ou não; as devidas entre elas passam a vistas. Interrompe o tour se ele estiver pendente ou na tela (ação mais recente da pessoa).
|
|
1057
1118
|
- `close(): void`
|
|
1058
1119
|
|
|
1059
1120
|
### Funções
|
|
1060
1121
|
|
|
1061
1122
|
- `function findTourTarget(selector: string): HTMLElement | null` — Primeiro elemento do seletor que está de fato na tela (tem tamanho e conteúdo). Não usa `offsetParent`: ele é `null` pra `position: fixed` (a sidebar) e pra `display: contents`, e o passo sumia do tour mesmo com o alvo visível. Com as abas vivas do workspace…
|
|
1062
1123
|
- `function provideSettingsSection(section: SpineSettingsSection): Provider` — Registra uma seção do app no painel de configurações (aparece depois das do spine, antes de "Sobre"). Pode ser chamado várias vezes, uma por seção.
|
|
1124
|
+
- `function argosAccountApi(authority: string | null | undefined, realm: string | null | undefined): string | null` — Base da API da conta no Argos: `{authority}/api/realms/{realm}/account` — o mesmo `{authority}/api` que o `@orfeu/angular` usa para o OIDC (a `authority` já traz o contexto do serviço, ex.: `https://host/argos`). Sem `authority`/`realm` (ou com o `CHANGE_ME`…
|
|
1125
|
+
- `function accountErrorCode(err: unknown): string` — Código de erro que o Argos devolveu (`{ error: 'invalid_code' }`), ou `''`.
|
|
1126
|
+
- `function sanitizeSpineMarkdownHtml(html: string): string | null` — HTML limpo pelo perfil do spine, ou `null` quando não há DOM (SSR: melhor não renderizar).
|
|
1063
1127
|
|
|
1064
1128
|
### Constantes e tokens
|
|
1065
1129
|
|
|
1066
1130
|
- `SPINE_BRAND`: `InjectionToken<Type<unknown> | null>` — Componente de marca que o header do shell desenha no lugar da imagem de `SpineConfig.logo` (tem prioridade sobre ela). Injeção em vez de projeção de conteúdo porque o `LayoutComponent` é montado pelo `Router`, não pelo template do app — não existe `<ng-conten…
|
|
1067
1131
|
- `SPINE_SETTINGS_KEYS` — Seções que o próprio spine já traz. `key` é também o valor de `?settings=` na URL.
|
|
1068
1132
|
- `SPINE_SETTINGS_SECTIONS`: `InjectionToken<SpineSettingsSection[]>`
|
|
1133
|
+
- `SPINE_MARKDOWN_PURIFY_CONFIG`: `Config` — Perfil do DOMPurify para o Markdown do spine (documentação de tela, novidades). Mais restrito que o padrão: o HTML entra no DOM do shell (sem shadow DOM), então - `<style>` e o atributo `style` ficam de fora (CSS valeria para a página inteira: esconder/redese…
|
|
1069
1134
|
|
|
1070
1135
|
### Tipos
|
|
1071
1136
|
|
|
1137
|
+
#### `OnboardingState` (type)
|
|
1138
|
+
|
|
1139
|
+
Fase do tour: `idle` (inativo: não é devido, terminou, foi pulado/interrompido ou não sobrou passo), `pending` (vai aparecer: desde o `maybeStart()`/`restart()` até o primeiro passo, enquanto espera o shell e os alvos) e `running` (um passo na tela). Quem não pode disputar a tela com o tour (o painel de novidades) espera `idle` — não um tempo fixo.
|
|
1140
|
+
|
|
1141
|
+
```ts
|
|
1142
|
+
type OnboardingState = 'idle' | 'pending' | 'running';
|
|
1143
|
+
```
|
|
1144
|
+
|
|
1072
1145
|
#### `OnboardingStep` (interface)
|
|
1073
1146
|
|
|
1074
1147
|
```ts
|
|
@@ -1199,12 +1272,74 @@ interface CreatedAppToken {
|
|
|
1199
1272
|
}
|
|
1200
1273
|
```
|
|
1201
1274
|
|
|
1275
|
+
#### `AccountMethod` (interface)
|
|
1276
|
+
|
|
1277
|
+
Um método de verificação em duas etapas, como o Argos devolve (nunca o segredo do TOTP).
|
|
1278
|
+
|
|
1279
|
+
```ts
|
|
1280
|
+
interface AccountMethod {
|
|
1281
|
+
method_id: string;
|
|
1282
|
+
/** `totp`, `email`, `sms`... (nome fixo do método no Argos). */
|
|
1283
|
+
method_name: string;
|
|
1284
|
+
active: boolean;
|
|
1285
|
+
/** E-mail/telefone mascarados. */
|
|
1286
|
+
secret?: string;
|
|
1287
|
+
}
|
|
1288
|
+
```
|
|
1289
|
+
|
|
1290
|
+
#### `AccountOverview` (interface)
|
|
1291
|
+
|
|
1292
|
+
`GET {api}/security`: métodos, política do realm, códigos de recuperação e estado da reautenticação.
|
|
1293
|
+
|
|
1294
|
+
```ts
|
|
1295
|
+
interface AccountOverview {
|
|
1296
|
+
user: { username: string; name: string | null; email: string };
|
|
1297
|
+
policy: { required: boolean };
|
|
1298
|
+
methods: AccountMethod[];
|
|
1299
|
+
recovery_codes: { remaining: number };
|
|
1300
|
+
/** Id do "método" código de recuperação (reautenticação com um código). */
|
|
1301
|
+
recovery_method_id: string;
|
|
1302
|
+
reauthenticated: boolean;
|
|
1303
|
+
reauth_expires_in: number;
|
|
1304
|
+
/** Só na resposta do cadastro do primeiro método: os códigos de recuperação, exibidos uma vez. */
|
|
1305
|
+
recovery_codes_issued?: string[];
|
|
1306
|
+
}
|
|
1307
|
+
```
|
|
1308
|
+
|
|
1309
|
+
#### `AccountSession` (interface)
|
|
1310
|
+
|
|
1311
|
+
Uma sessão (um login num navegador) e os aplicativos que a usam.
|
|
1312
|
+
|
|
1313
|
+
```ts
|
|
1314
|
+
interface AccountSession {
|
|
1315
|
+
id: string;
|
|
1316
|
+
/** A sessão deste login (a do token do app). */
|
|
1317
|
+
current: boolean;
|
|
1318
|
+
/** Outra sessão do mesmo navegador. */
|
|
1319
|
+
this_device: boolean;
|
|
1320
|
+
device: { browser?: string | null; os?: string | null; mobile: boolean; label: string };
|
|
1321
|
+
ip: string | null;
|
|
1322
|
+
created_at: string;
|
|
1323
|
+
last_seen_at: string;
|
|
1324
|
+
/** `false`: o login no Argos venceu, só o refresh de algum aplicativo segue vivo. */
|
|
1325
|
+
sso_active: boolean;
|
|
1326
|
+
clients: { client_id: string; name: string | null }[];
|
|
1327
|
+
}
|
|
1328
|
+
```
|
|
1329
|
+
|
|
1330
|
+
#### `AccountReauth` (type)
|
|
1331
|
+
|
|
1332
|
+
```ts
|
|
1333
|
+
type AccountReauth = { password: string } | { method_id: string; code: string };
|
|
1334
|
+
```
|
|
1335
|
+
|
|
1202
1336
|
#### `DocsEntry` (interface)
|
|
1203
1337
|
|
|
1204
|
-
Documento de tela
|
|
1338
|
+
Documento de uma tela que a pessoa logada pode abrir.
|
|
1205
1339
|
|
|
1206
1340
|
```ts
|
|
1207
1341
|
interface DocsEntry extends RouteDocument {
|
|
1342
|
+
/** Chave da tela (router_id ou, sem ele, o do template), sempre em minúsculas. */
|
|
1208
1343
|
readonly id: string;
|
|
1209
1344
|
readonly title: string;
|
|
1210
1345
|
readonly group: string;
|
|
@@ -1377,18 +1512,20 @@ Gate de navegação REAL (deep link, F5, `router.navigateByUrl` do painel focado
|
|
|
1377
1512
|
|
|
1378
1513
|
#### `RouteDocument` (interface)
|
|
1379
1514
|
|
|
1380
|
-
|
|
1515
|
+
Manual de uma tela, declarado no `document` da própria `ComponentRoute` (mesma chave, o router_id). Os textos são Markdown buscado só quando alguém abre a documentação: nos apps, um `import()` do `.md` com o loader `text`, de modo que o conteúdo vai no chunk lazy da tela e não no carregamento inicial.
|
|
1381
1516
|
|
|
1382
1517
|
```ts
|
|
1383
1518
|
interface RouteDocument {
|
|
1384
|
-
/** Nome no índice
|
|
1519
|
+
/** Nome da tela no índice da documentação; se faltar, usa-se o rótulo da rota na árvore do usuário. */
|
|
1385
1520
|
title?: string;
|
|
1386
|
-
/**
|
|
1521
|
+
/** Seção do índice em que a tela aparece; se faltar, usa-se o módulo de topo que a contém. */
|
|
1387
1522
|
group?: string;
|
|
1388
|
-
/**
|
|
1523
|
+
/** Texto para quem usa a tela no dia a dia (normalmente o `README.md` dela). */
|
|
1389
1524
|
load: () => Promise<string>;
|
|
1390
|
-
/**
|
|
1391
|
-
*
|
|
1525
|
+
/**
|
|
1526
|
+
* Especificação técnica, para desenvolvimento (normalmente o `ESPECIFICACAO.md`). Só aparece com
|
|
1527
|
+
* `SpineConfig.technicalDocs` ativo — por padrão, apenas em `isDevMode()`.
|
|
1528
|
+
*/
|
|
1392
1529
|
loadTechnical?: () => Promise<string>;
|
|
1393
1530
|
}
|
|
1394
1531
|
```
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Receitas — @trismegisto/spine
|
|
1
|
+
# Receitas — @trismegisto/spine 2.0.1
|
|
2
2
|
|
|
3
3
|
Padrões prontos para um app que usa o spine. Todos os componentes são standalone (importe as classes no
|
|
4
4
|
`imports`). Os componentes `hm-*` usados no conteúdo das telas são do `@trismegisto/angular` — a API deles está
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @trismegisto/spine — guia do shell
|
|
2
2
|
|
|
3
|
-
Escrito para a **API
|
|
3
|
+
Escrito para a **API 2.0.1**. Nomes exatos de cada export: `spine-api.md` (gerado do código); receitas
|
|
4
4
|
prontas: `spine-recipes.md`. O conteúdo das telas (componentes `hm-*`, tokens, formulários) é do
|
|
5
5
|
`@trismegisto/angular`: `angular.md`. Sessão, token, `PrivateGuard`, logout e troca de crachá são do
|
|
6
6
|
`@orfeu/angular` — skill **orfeu**.
|
|
@@ -220,8 +220,9 @@ tipo daqui; não o redeclare. O comportamento é fixo de propósito (sem opçõe
|
|
|
220
220
|
- token do Orfeu em `x-access-token` no HTTP e no `connection_init` do WebSocket (na raiz e em `headers`),
|
|
221
221
|
junto de `routeId`/`clientId` para a auditoria das subscriptions;
|
|
222
222
|
- HTTP em lote (`HttpBatchLink`), `fetchPolicy: 'no-cache'`, `errorPolicy` padrão (`none`);
|
|
223
|
-
- subscription por `graphql-ws`, só no navegador, reconexão ilimitada (backoff até 30 s);
|
|
224
|
-
|
|
223
|
+
- subscription por `graphql-ws`, só no navegador, reconexão ilimitada (backoff até 30 s); qualquer fechamento
|
|
224
|
+
do socket (inclusive 4401/4403) leva a reconectar com o token atual, nunca a erro na subscription; 401 de
|
|
225
|
+
HTTP ou de resolver recria os sockets; aba que volta de mais de 60 s em segundo plano também. `wsReconnected$` emite o
|
|
225
226
|
`namedClient` a cada **re**conexão — use para ressincronizar (receitas §6);
|
|
226
227
|
- **toast automático do envelope** `{ status, message, data }` de cada campo raiz: mutation avisa sempre que
|
|
227
228
|
falha (texto do catálogo se não vier `message`) e no sucesso quando o backend manda `message`; query só
|