@acropole/skills 0.0.0-stage → 1.0.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 +180 -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 +75 -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 +152 -0
- package/skills/angular/references/armadilhas.md +95 -0
- package/skills/angular/references/dados.md +251 -0
- package/skills/angular/references/estrutura.md +260 -0
- package/skills/angular/references/features.md +219 -0
- package/skills/angular/references/testes-build.md +230 -0
- package/skills/angular/scripts/checar.mjs +182 -0
- package/skills/angular/scripts/nucleo.mjs +227 -0
- package/skills/apollo/SKILL.md +222 -0
- package/skills/apollo/references/armadilhas.md +95 -0
- package/skills/apollo/references/envelope-erros.md +120 -0
- package/skills/apollo/references/estrutura-bootstrap.md +299 -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 +180 -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 +282 -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 +154 -0
- package/skills/express/references/dados.md +180 -0
- package/skills/express/references/estrutura.md +154 -0
- package/skills/express/references/middlewares.md +227 -0
- package/skills/express/references/rotas-erros.md +274 -0
- package/skills/express/references/testes-deploy.md +150 -0
- package/skills/express/scripts/checar.mjs +115 -0
- package/skills/express/scripts/nucleo.mjs +227 -0
- package/skills/fastapi/SKILL.md +129 -0
- package/skills/fastapi/references/banco.md +185 -0
- package/skills/fastapi/references/estrutura.md +281 -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 +348 -0
- package/skills/orfeu/references/node-armadilhas.md +158 -0
- package/skills/orfeu/references/node-recipes.md +534 -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 +234 -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,282 @@
|
|
|
1
|
+
# O porquê de cada decisão
|
|
2
|
+
|
|
3
|
+
## Imagem base
|
|
4
|
+
|
|
5
|
+
| Uso | Base | Por quê |
|
|
6
|
+
| --- | --- | --- |
|
|
7
|
+
| Runtime Node | `node:22-alpine` | ~50 MB a menos que `slim`; o runtime só precisa de `node` + JS puro |
|
|
8
|
+
| Build do Angular | `node:22-slim` | esbuild, sass e outros binários opcionais publicam builds glibc; em Alpine (musl) às vezes caem para fallback lento ou falham |
|
|
9
|
+
| Python | `python:3.12-slim` | as dependências vêm como wheel `manylinux` (glibc). Em Alpine o pip compila tudo do fonte: build lento e imagem maior |
|
|
10
|
+
| Site final | `scratch` | só transporta arquivos; não há processo |
|
|
11
|
+
|
|
12
|
+
- Fixe a versão maior (`node:22`, `python:3.12`): `latest` muda sem aviso e quebra build antigo
|
|
13
|
+
(rollback que não builda mais).
|
|
14
|
+
- Pacote nativo do Node com binário glibc pré-compilado (ex.: alguns drivers) não carrega em Alpine:
|
|
15
|
+
use `node:22-slim` no build **e** no runtime desse app.
|
|
16
|
+
|
|
17
|
+
## Multi-stage
|
|
18
|
+
|
|
19
|
+
O estágio de build tem compilador TypeScript, devDependencies, cache, código-fonte. O final copia só
|
|
20
|
+
`dist` + `node_modules` de produção. Ganhos: imagem menor (pull mais rápido em cada deploy), menos
|
|
21
|
+
superfície de ataque (sem ferramenta de build para um invasor usar) e nada do código-fonte/testes
|
|
22
|
+
em produção.
|
|
23
|
+
|
|
24
|
+
Uma instalação só: `npm ci` completo no build, `npm prune --omit=dev` depois do `tsc`, e o runtime
|
|
25
|
+
copia o `node_modules` pronto. Instalar de novo no estágio final dobra o tempo e pode resolver versões
|
|
26
|
+
diferentes se o lock não for usado. A limpeza por tipo de arquivo (`.d.ts`, `.map`, `.md`) reduz
|
|
27
|
+
bastante (medido ~118 → ~70 MB num gateway GraphQL) sem tocar em código: apagar por nome de pasta
|
|
28
|
+
(`docs/`, `test/`) quebra pacote que tem código de runtime nessas pastas.
|
|
29
|
+
|
|
30
|
+
Remover npm/yarn/corepack do runtime economiza ~20 MB e impede o `CMD npm start` por engano.
|
|
31
|
+
|
|
32
|
+
## Cache de dependências
|
|
33
|
+
|
|
34
|
+
Cada instrução gera uma camada; uma camada é reaproveitada se a instrução e tudo que ela copia não
|
|
35
|
+
mudaram — e invalida todas as seguintes.
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
COPY package.json package-lock.json ./ ← muda raramente
|
|
39
|
+
RUN npm ci ← reaproveitado enquanto o lock não muda
|
|
40
|
+
COPY . . ← muda a cada commit
|
|
41
|
+
RUN npm run build
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Com `COPY . .` antes do `npm ci`, qualquer commit reinstala tudo.
|
|
45
|
+
|
|
46
|
+
- **`npm ci`** e não `npm install`: instala exatamente o lockfile, apaga `node_modules` antes,
|
|
47
|
+
falha se `package.json` e lock divergirem (melhor quebrar no build do que subir versão diferente
|
|
48
|
+
da testada). Lockfile no repo é obrigatório.
|
|
49
|
+
- **`--mount=type=cache,target=/root/.npm`**: o cache de download fica no host do builder, fora da
|
|
50
|
+
imagem. Mesmo quando o lock muda, só o que é novo é baixado. `sharing=locked` evita dois builds
|
|
51
|
+
simultâneos corrompendo o cache. Como o cache não vai para a camada, `--no-cache-dir` (pip) é
|
|
52
|
+
desnecessário.
|
|
53
|
+
- **`--prefer-offline`**: usa o que está no cache sem revalidar cada pacote no registry (rede lenta
|
|
54
|
+
ou com proxy).
|
|
55
|
+
- **`--no-audit --no-fund`**: chamadas de rede e saída que não servem num build.
|
|
56
|
+
- **Cache do Angular** (`.angular/cache` montado + `cli.cache.environment: "all"`): partes que não
|
|
57
|
+
mudaram não são recompiladas.
|
|
58
|
+
- **ARG depois do install**: um `ARG` vira variável de ambiente de todos os `RUN` seguintes e entra na
|
|
59
|
+
chave de cache deles. `ARG CONFIGURATION` antes do `npm ci` faz cada ambiente reinstalar tudo.
|
|
60
|
+
- **Contexto pequeno** (`.dockerignore`): `.git` e `node_modules` locais mudam sempre e invalidam o
|
|
61
|
+
`COPY . .`, além de inflar o envio do contexto.
|
|
62
|
+
|
|
63
|
+
## Sem credencial na imagem
|
|
64
|
+
|
|
65
|
+
Tudo que entra por `COPY`, `ARG` ou `ENV` fica recuperável por quem puxa a imagem:
|
|
66
|
+
- arquivo copiado e apagado num `RUN` seguinte continua na camada anterior;
|
|
67
|
+
- `ARG` aparece em `history` (o valor usado em cada `RUN`);
|
|
68
|
+
- `ENV` aparece em `inspect` e no ambiente do container.
|
|
69
|
+
|
|
70
|
+
Por isso: sem `COPY .npmrc`, sem `ARG NPM_TOKEN`, sem `ENV PIP_INDEX_URL=https://user:senha@...`.
|
|
71
|
+
As libs da plataforma são públicas, o build não precisa de credencial nenhuma. Se um dia precisar de
|
|
72
|
+
registry privado: `RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci` (o segredo existe só
|
|
73
|
+
durante aquele `RUN`, não vai para camada).
|
|
74
|
+
|
|
75
|
+
## Segredo sem valor padrão
|
|
76
|
+
|
|
77
|
+
`ENV AGENT_TOKEN=changeme` (ou `os.getenv("AGENT_TOKEN", "changeme")`, `process.env.X ?? 'dev-secret'`) parece
|
|
78
|
+
inofensivo — "em produção a variável é cadastrada". Mas se o cadastro faltar, o serviço sobe **aceitando um
|
|
79
|
+
segredo que está no repositório e na imagem pública**, e ninguém percebe. O padrão é o inverso:
|
|
80
|
+
|
|
81
|
+
- nenhum segredo (token, senha, chave, `secret` do Orfeu) tem valor no Dockerfile nem no código;
|
|
82
|
+
- o serviço lê o segredo na subida e **falha no boot** sem ele, com mensagem que diz qual variável falta
|
|
83
|
+
(settings com campo obrigatório no Pydantic, zod `.min(1)` no Node);
|
|
84
|
+
- valor de desenvolvimento fica no `.env.local` (fora da imagem pelo `.dockerignore`), nunca como default.
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
# ERRADO: sobe com o segredo de exemplo se a variável não vier
|
|
88
|
+
AGENT_TOKEN = os.getenv("AGENT_TOKEN", "changeme")
|
|
89
|
+
|
|
90
|
+
# CERTO: sem a variável, o processo para na subida
|
|
91
|
+
AGENT_TOKEN = os.environ.get("AGENT_TOKEN", "")
|
|
92
|
+
if not AGENT_TOKEN:
|
|
93
|
+
raise RuntimeError("AGENT_TOKEN não definido: configure a variável no ambiente do container")
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Variáveis de ambiente por arquivo, não no argv
|
|
97
|
+
|
|
98
|
+
Quem **roda** containers por código (agente de deploy, script de CI) não monta `podman run -e K=V ...`
|
|
99
|
+
com os valores na linha de comando: o argv aparece em `ps` para qualquer usuário do host, em logs de
|
|
100
|
+
comando e em mensagens de erro que repetem o comando. Use `--env-file` com um arquivo temporário:
|
|
101
|
+
|
|
102
|
+
- criado com permissão **600** (`tempfile.mkstemp`, `fs.mkdtempSync` + `writeFileSync(..., { mode: 0o600 })`);
|
|
103
|
+
- apagado no `finally` (com ou sem erro), logo depois do `run` — o CLI lê o arquivo do lado do cliente e
|
|
104
|
+
manda as variáveis resolvidas ao engine, então ele só precisa existir durante o comando;
|
|
105
|
+
- validado antes de gravar: nome de variável sem espaço/`=`, valor sem quebra de linha (o formato do
|
|
106
|
+
`--env-file` é uma variável por linha, sem escape — uma quebra viraria outra variável).
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
@contextmanager
|
|
110
|
+
def env_file(pares):
|
|
111
|
+
conteudo = linhas_validadas(pares) # valida antes de criar qualquer arquivo
|
|
112
|
+
fd, caminho = tempfile.mkstemp(prefix="deploy-env-", suffix=".env") # 600
|
|
113
|
+
try:
|
|
114
|
+
with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as fh:
|
|
115
|
+
fh.write(conteudo)
|
|
116
|
+
yield caminho
|
|
117
|
+
finally:
|
|
118
|
+
with suppress(FileNotFoundError):
|
|
119
|
+
os.remove(caminho)
|
|
120
|
+
|
|
121
|
+
with env_file(env.items()) as caminho:
|
|
122
|
+
subprocess.run(["podman", "run", "-d", "--env-file", caminho, imagem], check=True)
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## Nome que vira caminho: validar e conter
|
|
126
|
+
|
|
127
|
+
Serviço que recebe um nome (app, ambiente, serviço) e usa como pasta para clonar, gravar `.env` ou
|
|
128
|
+
`rmtree` precisa de duas defesas, **antes** de qualquer escrita ou remoção:
|
|
129
|
+
|
|
130
|
+
1. **Nome**: só `[A-Za-z0-9._-]`, sem começar com `.` (`.` e `..` apontam para a própria raiz ou para o
|
|
131
|
+
pai), conferido com `fullmatch` — `re.match(r"...$")` aceita `"api\n"`.
|
|
132
|
+
2. **Contenção**: `alvo = (raiz / nome).resolve()` e exija `raiz.resolve() in alvo.parents` (nem a própria
|
|
133
|
+
raiz, nem fora dela, nem via symlink). Sem isso, `service=".."` faz o `rmtree` apagar o pai da raiz.
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
def caminho_dentro(raiz: str, nome: str) -> Path:
|
|
137
|
+
if not re.fullmatch(r"[A-Za-z0-9._-]+", nome) or nome.startswith("."):
|
|
138
|
+
raise ValueError(f"nome inválido: {nome!r}")
|
|
139
|
+
base = Path(raiz).resolve()
|
|
140
|
+
alvo = (base / nome).resolve()
|
|
141
|
+
if alvo == base or base not in alvo.parents:
|
|
142
|
+
raise ValueError(f"nome inválido: {nome!r}")
|
|
143
|
+
return alvo
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
## Scripts `.sh` com fim de linha LF
|
|
147
|
+
|
|
148
|
+
Script de entrypoint ou de build salvo com CRLF (editado no Windows, `core.autocrlf=true`) quebra no
|
|
149
|
+
container: `/bin/sh^M: bad interpreter` ou `$'\r': command not found`. Fixe no repositório, não na máquina
|
|
150
|
+
de cada um:
|
|
151
|
+
|
|
152
|
+
```gitattributes
|
|
153
|
+
# .gitattributes — scripts rodam em Linux
|
|
154
|
+
*.sh text eol=lf
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## Sinais, PID 1 e forma exec
|
|
158
|
+
|
|
159
|
+
No `stop`, o engine manda **SIGTERM ao PID 1** do container, espera o prazo (10 s no Podman/Docker)
|
|
160
|
+
e manda SIGKILL. O que precisa acontecer nesse intervalo: parar de aceitar conexões, terminar as
|
|
161
|
+
requisições em andamento, **enviar a fila de auditoria do Orfeu** (`flushAudit()` / shutdown do
|
|
162
|
+
lifespan), fechar pool de banco.
|
|
163
|
+
|
|
164
|
+
| CMD | PID 1 | SIGTERM chega ao app? |
|
|
165
|
+
| --- | --- | --- |
|
|
166
|
+
| `CMD ["node", "dist/index.js"]` | node | sim |
|
|
167
|
+
| `CMD node dist/index.js` (shell form) | `/bin/sh -c` | não: o sh não repassa |
|
|
168
|
+
| `CMD ["npm", "start"]` | npm | não confiável: o npm não repassa como deveria e ainda soma um processo |
|
|
169
|
+
| `CMD ["sh", "-c", "uvicorn ..."]` | sh | não |
|
|
170
|
+
| `CMD ["sh", "-c", "exec uvicorn ..."]` | uvicorn (o `exec` substitui o sh) | sim |
|
|
171
|
+
|
|
172
|
+
Sintoma do erro: todo deploy/stop demora exatamente o prazo (10 s) e termina com código 137;
|
|
173
|
+
auditoria das últimas requisições não chega.
|
|
174
|
+
|
|
175
|
+
**Node como PID 1** não ganha as ações padrão do kernel para sinais: sem handler, SIGTERM e SIGINT
|
|
176
|
+
são **ignorados**. O app precisa de `process.once('SIGTERM', ...)` com timer de segurança
|
|
177
|
+
(`setTimeout(...).unref()`) menor que o prazo do stop. Alternativa: um init mínimo (`tini`,
|
|
178
|
+
`--init`) — dispensável quando o app trata o sinal e não cria processos filhos (o init também colhe
|
|
179
|
+
zumbis). Uvicorn trata SIGTERM sozinho e executa o shutdown do lifespan.
|
|
180
|
+
|
|
181
|
+
`sh -c` só é necessário para expandir variável (`$PORT`). Com porta fixa, use a forma exec pura.
|
|
182
|
+
|
|
183
|
+
## Usuário não-root
|
|
184
|
+
|
|
185
|
+
Root no container é root no host em caso de fuga do container (em engine rootful) e pode escrever em
|
|
186
|
+
qualquer lugar da imagem. Com `USER`:
|
|
187
|
+
- as imagens `node` já têm o usuário `node` (uid 1000); em `python:slim`, crie um
|
|
188
|
+
(`useradd --system`);
|
|
189
|
+
- portas abaixo de 1024 exigem privilégio — use 3000/8000 etc. (o Caddy é quem fica na 443);
|
|
190
|
+
- arquivos copiados como root continuam legíveis; pasta em que o app **escreve** precisa de
|
|
191
|
+
`COPY --chown=...` ou `RUN chown`;
|
|
192
|
+
- coloque `USER` depois dos `RUN` que precisam de root (remover npm, `apt-get`, `useradd`).
|
|
193
|
+
|
|
194
|
+
## HEALTHCHECK
|
|
195
|
+
|
|
196
|
+
Faz o engine marcar o container como `healthy`/`unhealthy` (visível no inventário e em `ps`).
|
|
197
|
+
- Use o que já existe na imagem: `wget` (busybox) no Alpine; `python -c urllib...` no slim — não
|
|
198
|
+
instale `curl` só para isso.
|
|
199
|
+
- Chame `127.0.0.1`, não o domínio, e inclua o prefixo do app no path.
|
|
200
|
+
- `--start-period` cobre a subida (conexões, registro no Argos).
|
|
201
|
+
- **Podman/Buildah** gravam `HEALTHCHECK` apenas em imagem formato `docker`; no formato OCI (padrão)
|
|
202
|
+
a instrução é descartada com aviso. E o deploy não espera `healthy` para concluir. Na prática o
|
|
203
|
+
`/health` do app é o que importa: é ele que você consulta depois do deploy (ver **hefesto**).
|
|
204
|
+
|
|
205
|
+
## Porta
|
|
206
|
+
|
|
207
|
+
`ENV PORT=<porta>` + `EXPOSE <porta>` + o app lendo `PORT` e escutando em `0.0.0.0`. Escutar em
|
|
208
|
+
`127.0.0.1` só aceita conexões vindas de dentro do próprio container: o proxy na rede do servidor
|
|
209
|
+
recebe conexão recusada (502). `EXPOSE` não publica nada, só documenta; quem publica é o `-p` do
|
|
210
|
+
deploy. A porta do `ENV PORT` precisa bater com a cadastrada na plataforma.
|
|
211
|
+
|
|
212
|
+
## ARG x ENV, build x runtime
|
|
213
|
+
|
|
214
|
+
| | Quando é lido | Fica na imagem | Use para |
|
|
215
|
+
| --- | --- | --- | --- |
|
|
216
|
+
| `ARG` | só durante o build | no histórico | o que muda o artefato: `CONFIGURATION` do Angular |
|
|
217
|
+
| `ENV` no Dockerfile | build e runtime | sim | padrões não sensíveis: `PORT`, `NODE_ENV`, `PYTHONUNBUFFERED`, caminhos internos |
|
|
218
|
+
| variável no deploy (`--env-file`/`-e`) | runtime | não | tudo que muda por ambiente ou é segredo: banco, URLs, identidade no Argos — segredo **sem** valor padrão no Dockerfile |
|
|
219
|
+
|
|
220
|
+
A mesma imagem deve poder rodar em qualquer ambiente trocando só as variáveis de runtime. A exceção
|
|
221
|
+
é o site Angular: o navegador não lê variável de ambiente do servidor, então endpoints e `baseHref`
|
|
222
|
+
entram no build (`CONFIGURATION`), e por isso há uma imagem por ambiente.
|
|
223
|
+
|
|
224
|
+
## `.dockerignore`
|
|
225
|
+
|
|
226
|
+
- **`.git`**: o clone raso ainda tem a pasta `.git`; sem ignorar, o `COPY . .` leva o histórico para
|
|
227
|
+
a imagem.
|
|
228
|
+
- **`node_modules`, `.venv`**: as do host são de outro sistema operacional (binários nativos de
|
|
229
|
+
Windows/macOS) e sobrescreveriam as instaladas no build pelo `COPY . .`.
|
|
230
|
+
- **`dist`, `.angular`, `coverage`, caches**: artefatos locais que só invalidam cache.
|
|
231
|
+
- **`.env`, `.env.*` (menos `.env.example`)**: segredo local fora da imagem. Efeito colateral
|
|
232
|
+
desejado: no container o app **só** lê configuração do ambiente; se ele carrega
|
|
233
|
+
`.env.<APP_ENV>`, o arquivo não existe e cada valor precisa ser cadastrado como variável. Um app
|
|
234
|
+
que "funciona local e não sobe no container" geralmente é isso.
|
|
235
|
+
- **`tests`** (Python) e o próprio `Dockerfile`: não rodam em produção.
|
|
236
|
+
- Só o `.dockerignore` da **raiz do contexto** vale; em contexto com `ui/` + `server/`, use padrões
|
|
237
|
+
`**/`.
|
|
238
|
+
|
|
239
|
+
## `timeout -k` nos passos longos
|
|
240
|
+
|
|
241
|
+
O builder (Podman/Buildah) só verifica cancelamento entre passos. Se um `npm ci` ou `ng build` trava
|
|
242
|
+
(rede, proxy), o cliente desiste mas o passo continua rodando no host do builder indefinidamente.
|
|
243
|
+
`timeout -k 10 600 npm ci` manda SIGTERM aos 600 s e SIGKILL 10 s depois — o build falha com
|
|
244
|
+
mensagem em vez de travar. Valores típicos: 600 s para download, 300 s para compilar.
|
|
245
|
+
|
|
246
|
+
## Angular: estágio final `scratch` com `/dist`
|
|
247
|
+
|
|
248
|
+
A plataforma não roda um servidor web por app: o Caddy de cada servidor já está lá e serve os
|
|
249
|
+
arquivos com `file_server` (e fallback de SPA). A imagem é só o **pacote versionado** do build:
|
|
250
|
+
vai para o registry com tag e versão como qualquer outra, permite rollback e auditoria do que está
|
|
251
|
+
publicado, e o Talos extrai `/dist` sem nunca executá-la. Daí as convenções:
|
|
252
|
+
- estágio chamado `site` (é o `--target`);
|
|
253
|
+
- conteúdo em `/dist` na raiz;
|
|
254
|
+
- `CMD ["unused"]` porque criar um container exige comando no manifesto, e `scratch` não tem shell.
|
|
255
|
+
|
|
256
|
+
Ser o último estágio faz um `build` sem `--target` produzir a imagem `site`; para rodar o
|
|
257
|
+
dev-server localmente, `target: dev`. Budgets do `angular.json` com `maximumError` estourado fazem o
|
|
258
|
+
`ng build` falhar e, com ele, o build da imagem: reduza o bundle inicial em vez de subir o limite
|
|
259
|
+
(ver **angular**).
|
|
260
|
+
|
|
261
|
+
## Python: `exec uvicorn` e workers
|
|
262
|
+
|
|
263
|
+
- `exec`: ver "Sinais". O uvicorn recebe o SIGTERM, para de aceitar conexões, espera as em andamento
|
|
264
|
+
e roda o shutdown do lifespan (onde o Orfeu envia a auditoria pendente).
|
|
265
|
+
- `PYTHONUNBUFFERED=1`: sem ele o stdout é bufferizado e os logs aparecem atrasados ou se perdem
|
|
266
|
+
quando o processo é morto.
|
|
267
|
+
- **`--workers N`** cria N processos, cada um com o app inteiro e **o lifespan inteiro**: tudo que o
|
|
268
|
+
startup dispara (agendador, coletor, consumidor de fila, `asyncio.create_task` em loop) roda N
|
|
269
|
+
vezes — escrita duplicada, chamadas externas em dobro, locks disputados. Também multiplica
|
|
270
|
+
memória e conexões de banco, e caches/rate limits em memória ficam por processo.
|
|
271
|
+
- Padrão: **um processo por container**; para escalar, mais réplicas (workers do Hefesto) — e, se
|
|
272
|
+
houver tarefa em background, separe o papel (`APP_ROLE=api` com réplicas, um único processo de
|
|
273
|
+
tarefas) ou proteja cada ciclo com lock distribuído. Ver **fastapi** e **hefesto**.
|
|
274
|
+
|
|
275
|
+
## Podman/Buildah x Docker
|
|
276
|
+
|
|
277
|
+
O build da plataforma usa `podman build` (Buildah). Para o Dockerfile, as diferenças que importam:
|
|
278
|
+
- `RUN --mount=type=cache|secret` funciona nos dois;
|
|
279
|
+
- estágios independentes rodam em paralelo com `--jobs` — vale separar build da UI e do servidor em
|
|
280
|
+
estágios sem dependência entre si;
|
|
281
|
+
- `HEALTHCHECK` só é gravado no formato `docker` (ver acima);
|
|
282
|
+
- o `.dockerignore` (ou `.containerignore`) da raiz do contexto é respeitado.
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: documentacao
|
|
3
|
+
description: "Documentação das telas Angular ligadas ao shell @trismegisto/spine: README.md de uso e ESPECIFICACAO.md técnica por tela, a ligação no campo document do features.routes.ts, o loader .md e o registro de revisão. Use ao criar ou alterar uma tela, rota ou componente de feature Angular, ao revisar a documentação de uma tela e antes de dar uma tela por terminada. Estrutura e rotas do app são da skill angular; a interface (hm-*), da trismegisto."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# documentacao — manual de cada tela
|
|
7
|
+
|
|
8
|
+
Cada tela do app tem um manual que abre pelo botão de documentação da barra da página (spine). O texto
|
|
9
|
+
mora **ao lado do componente**, é markdown cru e vai no chunk lazy da própria tela. Esta skill diz como
|
|
10
|
+
escrever esse manual, como ligá-lo na rota e como garantir que ele continua dizendo a verdade quando a
|
|
11
|
+
tela muda.
|
|
12
|
+
|
|
13
|
+
Divisão de trabalho: registro da tela, `router_id` e build são da skill **angular**; componentes e
|
|
14
|
+
rótulos da interface, da **trismegisto**. Aqui fica só o que é documentação.
|
|
15
|
+
|
|
16
|
+
> **Antes de dar por terminado:** `node scripts/checar.mjs <pasta-do-app>` (caminho relativo a esta skill: instalada, fica em `~/.claude/skills/documentacao/scripts/checar.mjs`; `--help` lista as regras, `--json` para máquina).
|
|
17
|
+
|
|
18
|
+
## 1. A regra
|
|
19
|
+
|
|
20
|
+
**Mudou a tela, revise a doc.** Mexeu em `.ts`, `.html` ou `.scss` da pasta de uma feature documentada:
|
|
21
|
+
|
|
22
|
+
1. Releia o `README.md` (e a `ESPECIFICACAO.md`, se houver) com a tela nova na cabeça.
|
|
23
|
+
2. **Atualize** se mudou algo que o usuário vê (ação, rótulo, coluna, filtro, estado, mensagem,
|
|
24
|
+
permissão) ou algo que a especificação descreve (origem dos dados, regra, o que a tela decide).
|
|
25
|
+
Refatoração interna, troca de estilo sem efeito visível e teste novo não pedem mudança no texto.
|
|
26
|
+
3. **Registre a revisão**: `node scripts/checar.mjs <app> --registrar-revisao <pasta-da-feature>`.
|
|
27
|
+
|
|
28
|
+
O registro de revisão grava em `src/app/features/.documentacao.json` o hash dos `.ts`/`.html`/`.scss` da pasta
|
|
29
|
+
(sem `.spec.ts`, sem `.md`, CRLF normalizado) — e também da pasta do documento, quando a tela é um
|
|
30
|
+
invólucro que reaproveita a lista de outra pasta e o README mora lá. Service ou componente compartilhado
|
|
31
|
+
fora dessas pastas não entra: aí quem pega é o `revisor-documentacao`. Na próxima mudança o hash muda e o verificador acusa
|
|
32
|
+
`documentacao-desatualizada` até alguém revisar de novo. **Registre a revisão só depois de revisar de verdade** —
|
|
33
|
+
registrar para calar o verificador é deixar a doc mentir com aval.
|
|
34
|
+
|
|
35
|
+
O `.documentacao.json` é commitado junto com a mudança da tela; num PR, a linha alterada nele mostra que a
|
|
36
|
+
doc foi revista.
|
|
37
|
+
|
|
38
|
+
## 2. O padrão
|
|
39
|
+
|
|
40
|
+
Na pasta da tela (`src/app/features/<tela>/`):
|
|
41
|
+
|
|
42
|
+
| Arquivo | Para quem | Obrigatório |
|
|
43
|
+
| --- | --- | --- |
|
|
44
|
+
| `README.md` | quem **usa** a tela | sim |
|
|
45
|
+
| `ESPECIFICACAO.md` | quem **desenvolve** (aba "Especificação técnica", só com `technicalDocs`) | não |
|
|
46
|
+
|
|
47
|
+
**`README.md`**, em português, curto, na voz de quem opera:
|
|
48
|
+
|
|
49
|
+
- `# <nome da tela>` — o mesmo nome do menu;
|
|
50
|
+
- uma ou duas frases dizendo para que a tela serve;
|
|
51
|
+
- `## Como usar` em passos numerados (ou lista curta), com os rótulos **exatamente** como aparecem na
|
|
52
|
+
tela, em negrito: "Clique em **Novo pedido**", "na aba **Faturados**";
|
|
53
|
+
- tabela de status ou legenda quando a tela mostra estados, cores ou ícones com significado;
|
|
54
|
+
- uma dica final em `>` (o erro mais comum, o que acontece de irreversível, onde fica o cadastro).
|
|
55
|
+
|
|
56
|
+
Modelo comentado: `references/modelo-readme.md`.
|
|
57
|
+
|
|
58
|
+
**`ESPECIFICACAO.md`**, quando há regra que não cabe no manual: origem dos dados (serviço, query,
|
|
59
|
+
tabela), regras de negócio, **o que a tela decide e o que fica com o servidor** (permissão, validação
|
|
60
|
+
final, cálculo). Modelo: `references/modelo-especificacao.md`.
|
|
61
|
+
|
|
62
|
+
O renderizador do spine é markdown GFM sanitizado: títulos, listas, tabelas, citação, código e links
|
|
63
|
+
funcionam; HTML cru é filtrado, imagem e link relativo para outro `.md` não resolvem. Detalhes no modelo.
|
|
64
|
+
|
|
65
|
+
## 3. A ligação
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
// src/app/features/features.routes.ts
|
|
69
|
+
{
|
|
70
|
+
id: '<router_id>',
|
|
71
|
+
load: () => import('src/app/features/pedidos/pedidos.component').then(m => m.PedidosComponent),
|
|
72
|
+
document: {
|
|
73
|
+
load: () => import('src/app/features/pedidos/README.md').then(m => m.default),
|
|
74
|
+
loadTechnical: () => import('src/app/features/pedidos/ESPECIFICACAO.md').then(m => m.default), // se existir
|
|
75
|
+
},
|
|
76
|
+
},
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
E no app, uma vez só:
|
|
80
|
+
|
|
81
|
+
- `angular.json`: `"loader": { ".md": "text" }` em `build.options` **e** em `test.options` (senão o
|
|
82
|
+
teste de rotas não consegue importar o README);
|
|
83
|
+
- `src/markdown.d.ts` com `declare module '*.md' { const content: string; export default content; }`;
|
|
84
|
+
- um teste de rotas que chama `document.load()`/`loadTechnical()` de cada rota e confere texto não vazio.
|
|
85
|
+
|
|
86
|
+
Passo a passo para um app que ainda não tem nada disso: `references/ligar-app-novo.md`.
|
|
87
|
+
|
|
88
|
+
## 4. O verificador
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
node scripts/checar.mjs <pasta-do-app> # ou o próprio features.routes.ts
|
|
92
|
+
node scripts/checar.mjs <pasta-do-app> --json
|
|
93
|
+
node scripts/checar.mjs <pasta-do-app> --registrar-revisao pedidos # depois de revisar; ou --registrar-revisao todas
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
| Regra | O que acusa |
|
|
97
|
+
| --- | --- |
|
|
98
|
+
| `rota-sem-documento` | rota com `load` de tela e sem `document` |
|
|
99
|
+
| `documento-inexistente` | `import()` de `.md` (inclusive `loadTechnical`) para arquivo que não existe |
|
|
100
|
+
| `especificacao-desligada` | `ESPECIFICACAO.md` na pasta da tela, rota sem `loadTechnical` |
|
|
101
|
+
| `readme-fora-do-padrao` | README vazio, sem `# ` ou sem `## Como usar` |
|
|
102
|
+
| `rotulo-inexistente` | "clique em **X**", "botão **X**", "aba **X**" cujo texto não está nos templates da pasta |
|
|
103
|
+
| `md-sem-loader` | `document` sem loader `.md` no build/test ou sem a declaração `*.md` |
|
|
104
|
+
| `documentacao-desatualizada` | tela documentada fora do `.documentacao.json` ou com hash diferente |
|
|
105
|
+
|
|
106
|
+
Fluxo de uso:
|
|
107
|
+
|
|
108
|
+
1. Rode o verificador sobre o app depois de mexer numa tela.
|
|
109
|
+
2. Regras estruturais (as seis primeiras): corrija o que ele apontou.
|
|
110
|
+
3. `documentacao-desatualizada`: abra a tela e a doc lado a lado e siga `references/checklist-coerencia.md`
|
|
111
|
+
(ou peça ao subagente `revisor-documentacao`, que faz essa leitura e diz o que mudar).
|
|
112
|
+
4. Atualize o texto se for o caso e só então registre a revisão da feature.
|
|
113
|
+
|
|
114
|
+
Exceção consciente, na linha anterior e sempre com motivo:
|
|
115
|
+
|
|
116
|
+
```ts
|
|
117
|
+
// acropole-ignore-next-line rota-sem-documento -- tela de diagnóstico, só para quem mantém o app
|
|
118
|
+
load: () => import('./interna/interna.component').then(m => m.InternaComponent),
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
```md
|
|
122
|
+
<!-- acropole-ignore-next-line rotulo-inexistente -- o botão é do shell, não da tela -->
|
|
123
|
+
> Use o botão **Favoritar** da barra da página.
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
O verificador nunca escreve nada sem `--registrar-revisao`, e com ele escreve só o `.documentacao.json`.
|
|
127
|
+
|
|
128
|
+
## 5. Armadilhas
|
|
129
|
+
|
|
130
|
+
- **Rótulo inventado.** O README é lido com a tela aberta ao lado: botão que não existe com aquele nome
|
|
131
|
+
faz a pessoa procurar à toa. Copie o texto do template, não do nome do método.
|
|
132
|
+
- **Duas rotas na mesma pasta** (ex.: visão completa e visão de operador): a pasta tem um registro de revisão só,
|
|
133
|
+
mas cada rota precisa do próprio `document` — o mesmo README pode servir as duas, com a diferença
|
|
134
|
+
explicada nele.
|
|
135
|
+
- **Doc descrevendo permissão como regra da tela.** Quem pode ver ou fazer é decidido no servidor; o
|
|
136
|
+
README diz o efeito ("só aparecem as aplicações dos seus grupos"), a especificação diz onde é decidido.
|
|
137
|
+
- **Caminho de menu** ("Infraestrutura > Origens") não é rótulo da tela: fica em negrito sem "clique em".
|
|
138
|
+
|
|
139
|
+
## 6. Referências
|
|
140
|
+
|
|
141
|
+
| Arquivo | Quando ler |
|
|
142
|
+
| --- | --- |
|
|
143
|
+
| `references/modelo-readme.md` | Ao escrever ou reescrever o manual de uma tela |
|
|
144
|
+
| `references/modelo-especificacao.md` | Quando a tela tem regra, origem de dados ou divisão tela/servidor que valha registrar |
|
|
145
|
+
| `references/checklist-coerencia.md` | Ao revisar uma doc contra a tela (antes de registrar a revisão) |
|
|
146
|
+
| `references/ligar-app-novo.md` | App que ainda não tem documentação de tela (loader, `markdown.d.ts`, teste de rotas, primeiro registro de revisão) |
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Checklist de coerência: a doc ainda descreve a tela?
|
|
2
|
+
|
|
3
|
+
Use quando o verificador acusar `documentacao-desatualizada` ou ao revisar uma tela à mão. Abra lado a
|
|
4
|
+
lado: o template (`.html` ou `template:` inline) e o `.ts` da pasta da feature, e o `README.md`/
|
|
5
|
+
`ESPECIFICACAO.md`. Quando possível, olhe o que mudou (`git diff` da pasta) antes de reler tudo.
|
|
6
|
+
|
|
7
|
+
## 1. Ações
|
|
8
|
+
|
|
9
|
+
- [ ] Todo botão, item de menu e ação de linha citado no README existe, com o mesmo rótulo.
|
|
10
|
+
- [ ] Ação nova que a pessoa precisa conhecer (principalmente as destrutivas ou irreversíveis) está no
|
|
11
|
+
README.
|
|
12
|
+
- [ ] Ação removida saiu do README.
|
|
13
|
+
- [ ] A ordem dos passos ainda é a ordem possível na tela (ex.: o seletor de projeto continua antes da lista).
|
|
14
|
+
|
|
15
|
+
## 2. Rótulos e textos
|
|
16
|
+
|
|
17
|
+
- [ ] Nome da tela no `#` igual ao do menu.
|
|
18
|
+
- [ ] Abas, seções, títulos de modal e campos citados batem com o template (maiúsculas incluídas).
|
|
19
|
+
- [ ] Mensagens citadas (aviso, confirmação, estado vazio) ainda são essas.
|
|
20
|
+
|
|
21
|
+
## 3. Estados
|
|
22
|
+
|
|
23
|
+
- [ ] Tabela de status/legenda tem exatamente os estados que a tela mostra (rótulo e significado).
|
|
24
|
+
- [ ] Estados de carregamento, vazio e erro descritos (se o README fala deles) batem com o template.
|
|
25
|
+
- [ ] Cores ou ícones com significado citados ainda são os mesmos.
|
|
26
|
+
|
|
27
|
+
## 4. Colunas e filtros
|
|
28
|
+
|
|
29
|
+
- [ ] Colunas citadas existem; coluna nova importante está explicada.
|
|
30
|
+
- [ ] Filtros e busca: campos pesquisados ("por nome, tag ou status") são os que o código filtra de fato.
|
|
31
|
+
- [ ] Ordenação padrão e paginação, se citadas, conferem.
|
|
32
|
+
|
|
33
|
+
## 5. Permissões e visões
|
|
34
|
+
|
|
35
|
+
- [ ] Diferença entre visões (operador, administrador, somente leitura) descrita como efeito.
|
|
36
|
+
- [ ] Ação que passou a depender de permissão está mencionada ("só aparece para quem...").
|
|
37
|
+
- [ ] Nada no README promete que a tela barra algo que só o servidor barra.
|
|
38
|
+
|
|
39
|
+
## 6. Especificação (se existir)
|
|
40
|
+
|
|
41
|
+
- [ ] Origem dos dados: serviço, query/mutation ou rota continuam os que o `.ts` chama.
|
|
42
|
+
- [ ] Regras descritas ainda são as aplicadas (validações, limites, intervalos de atualização).
|
|
43
|
+
- [ ] "O que a tela decide / o que fica com o servidor" continua verdadeiro.
|
|
44
|
+
- [ ] Está ligada na rota (`loadTechnical`).
|
|
45
|
+
|
|
46
|
+
## 7. Decisão
|
|
47
|
+
|
|
48
|
+
| Situação | O que fazer |
|
|
49
|
+
| --- | --- |
|
|
50
|
+
| Mudança só interna (refatoração, estilo sem efeito visível, tipagem) | Nada no texto; registre a revisão |
|
|
51
|
+
| Mudou algo visível ou descrito | Atualize o README/ESPECIFICACAO; depois registre a revisão |
|
|
52
|
+
| Dúvida se a mudança é visível | Rode a tela ou pergunte; não registre a revisão no escuro |
|
|
53
|
+
| A doc estava errada antes da mudança | Corrija também; o registro de revisão atesta a doc inteira, não só o diff |
|
|
54
|
+
|
|
55
|
+
Registro da revisão, depois de revisar:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
node <skill documentacao>/scripts/checar.mjs <pasta-do-app> --registrar-revisao <pasta-da-feature>
|
|
59
|
+
```
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# Ligar a documentação de telas num app
|
|
2
|
+
|
|
3
|
+
Para um app Angular com `@trismegisto/spine` que ainda não tem documentação de tela. Uma vez por app;
|
|
4
|
+
depois, cada tela nova só precisa do README e do `document` na rota.
|
|
5
|
+
|
|
6
|
+
## 1. Loader `.md` no `angular.json`
|
|
7
|
+
|
|
8
|
+
Importar um `.md` precisa devolver o texto cru. Nos dois targets, em `options`:
|
|
9
|
+
|
|
10
|
+
```json
|
|
11
|
+
"build": {
|
|
12
|
+
"builder": "@angular/build:application",
|
|
13
|
+
"options": {
|
|
14
|
+
"loader": { ".md": "text" }
|
|
15
|
+
}
|
|
16
|
+
},
|
|
17
|
+
"test": {
|
|
18
|
+
"builder": "@angular/build:karma",
|
|
19
|
+
"options": {
|
|
20
|
+
"loader": { ".md": "text" }
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Sem o do `test`, o build passa e o teste de rotas quebra ao importar o README. Com o builder
|
|
26
|
+
`@angular/build:unit-test` (que herda as opções do `buildTarget`), basta o do build.
|
|
27
|
+
|
|
28
|
+
## 2. Declaração de tipo
|
|
29
|
+
|
|
30
|
+
`src/markdown.d.ts` (precisa estar coberto pelo `include`/`files` do `tsconfig.app.json` e do
|
|
31
|
+
`tsconfig.spec.json`; em `src/` normalmente já está):
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
// Loader `.md: "text"` (angular.json): importar um .md devolve o texto cru — documentação das telas.
|
|
35
|
+
declare module '*.md' {
|
|
36
|
+
const content: string;
|
|
37
|
+
export default content;
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## 3. Rota com `document`
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
{
|
|
45
|
+
id: '<router_id>',
|
|
46
|
+
load: () => import('src/app/features/pedidos/pedidos.component').then(m => m.PedidosComponent),
|
|
47
|
+
document: {
|
|
48
|
+
load: () => import('src/app/features/pedidos/README.md').then(m => m.default),
|
|
49
|
+
// loadTechnical: () => import('src/app/features/pedidos/ESPECIFICACAO.md').then(m => m.default),
|
|
50
|
+
// title/group: opcionais; sem eles valem o nome da rota e o módulo da árvore do Argos
|
|
51
|
+
},
|
|
52
|
+
},
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
O `import()` precisa ser literal (o bundler gera o chunk a partir dele). Não monte o caminho em
|
|
56
|
+
variável. O texto só é baixado quando alguém abre a documentação.
|
|
57
|
+
|
|
58
|
+
A aba técnica aparece conforme `provideUi({ technicalDocs })` (padrão `isDevMode()`).
|
|
59
|
+
|
|
60
|
+
## 4. Teste de rotas
|
|
61
|
+
|
|
62
|
+
Em `src/app/features/features.routes.spec.ts`, ao lado das conferências de `id` e `load`:
|
|
63
|
+
|
|
64
|
+
```ts
|
|
65
|
+
it('documentação (README e especificação técnica) carrega como texto não vazio', async () => {
|
|
66
|
+
for (const route of components.filter(c => c.document)) {
|
|
67
|
+
const doc = route.document!;
|
|
68
|
+
const readme = await doc.load();
|
|
69
|
+
expect(typeof readme).withContext(route.id ?? '').toBe('string');
|
|
70
|
+
expect(readme.trim().length).withContext(route.id ?? '').toBeGreaterThan(0);
|
|
71
|
+
if (doc.loadTechnical) {
|
|
72
|
+
expect((await doc.loadTechnical()).trim().length).withContext(route.id ?? '').toBeGreaterThan(0);
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
});
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## 5. Primeiro registro de revisão
|
|
79
|
+
|
|
80
|
+
Escreva os READMEs (`modelo-readme.md`), rode o verificador até sobrar só
|
|
81
|
+
`documentacao-desatualizada`, revise cada doc contra a tela (`checklist-coerencia.md`) e registre a revisão:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
node <skill documentacao>/scripts/checar.mjs <pasta-do-app>
|
|
85
|
+
node <skill documentacao>/scripts/checar.mjs <pasta-do-app> --registrar-revisao todas
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Isso cria `src/app/features/.documentacao.json` (chaves ordenadas, uma por pasta de tela documentada).
|
|
89
|
+
Commite junto. A partir daí, cada mudança numa tela documentada volta a acusar até a doc ser revista.
|
|
90
|
+
|
|
91
|
+
## 6. Telas sem documentação de propósito
|
|
92
|
+
|
|
93
|
+
Tela técnica ou interna que não precisa de manual: marque a rota com a exceção, com motivo:
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
// acropole-ignore-next-line rota-sem-documento -- tela de diagnóstico, só para quem mantém o app
|
|
97
|
+
load: () => import('./interna/interna.component').then(m => m.InternaComponent),
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## 7. Opcional: no CI ou num hook
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
node <skill documentacao>/scripts/checar.mjs <pasta-do-app> --json
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Sai com código 1 quando acha algo. Num PR, uma tela alterada sem a linha correspondente do
|
|
107
|
+
`.documentacao.json` alterada é sinal de que a doc não foi revista.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Modelo de ESPECIFICACAO de tela
|
|
2
|
+
|
|
3
|
+
A `ESPECIFICACAO.md` é para quem **desenvolve** ou dá suporte à tela. Aparece na aba "Especificação
|
|
4
|
+
técnica" do modal de documentação, que o spine só mostra com `SpineConfig.technicalDocs` (padrão: fora
|
|
5
|
+
de produção). É opcional: escreva quando houver regra, origem de dados ou divisão tela/servidor que não
|
|
6
|
+
seja óbvia lendo o componente.
|
|
7
|
+
|
|
8
|
+
Existindo o arquivo, ligue-o na rota com `loadTechnical` — o verificador acusa
|
|
9
|
+
`especificacao-desligada` se ele estiver na pasta e fora da rota.
|
|
10
|
+
|
|
11
|
+
## Esqueleto
|
|
12
|
+
|
|
13
|
+
```md
|
|
14
|
+
# <Nome da tela> — especificação técnica
|
|
15
|
+
|
|
16
|
+
## Origem dos dados
|
|
17
|
+
|
|
18
|
+
| Dado | Fonte |
|
|
19
|
+
| --- | --- |
|
|
20
|
+
| <Lista de pedidos> | <serviço/GraphQL `vendas`, query `pedidos`> |
|
|
21
|
+
| <Totais do cabeçalho> | <calculados na tela a partir da lista> |
|
|
22
|
+
|
|
23
|
+
## Regras
|
|
24
|
+
|
|
25
|
+
- <Regra de negócio que a tela aplica ou exibe, com o caso de borda.>
|
|
26
|
+
- <Ordenação padrão, paginação, limite, atualização automática (intervalo).>
|
|
27
|
+
|
|
28
|
+
## O que a tela decide
|
|
29
|
+
|
|
30
|
+
- <Só apresentação: filtros, aba, seleção, quais modais abrir.>
|
|
31
|
+
|
|
32
|
+
## O que fica com o servidor
|
|
33
|
+
|
|
34
|
+
- <Permissão (quem vê, quem executa), validação final, cálculo oficial, auditoria.>
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## O que entra e o que não entra
|
|
38
|
+
|
|
39
|
+
| Entra | Não entra |
|
|
40
|
+
| --- | --- |
|
|
41
|
+
| serviço, query/mutation, rota REST, tabela de origem | passo a passo de uso (é do README) |
|
|
42
|
+
| regra de negócio e caso de borda que a tela trata | segredo, credencial, URL interna, IP |
|
|
43
|
+
| o que a tela decide e o que só o servidor decide | código copiado do componente |
|
|
44
|
+
| eventos/subscriptions e intervalos de atualização | histórico de mudanças (é do git) |
|
|
45
|
+
| dependência de outra tela ou cadastro | nome de pessoa ou equipe |
|
|
46
|
+
|
|
47
|
+
A seção **"o que a tela decide / o que fica com o servidor"** é a mais útil: evita que alguém "corrija"
|
|
48
|
+
uma permissão escondendo um botão no front, e diz onde procurar quando o comportamento muda.
|
|
49
|
+
|
|
50
|
+
Caminho de arquivo do backend pode aparecer (ajuda quem vai mexer), mas fica velho fácil: prefira o nome
|
|
51
|
+
do módulo ou da operação.
|