@acropole/skills 1.0.0 → 1.2.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 -2
- package/bin/install.js +4 -3
- package/package.json +2 -2
- package/skills/acropole/SKILL.md +9 -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/orquestracao/SKILL.md +118 -0
- package/skills/orquestracao/references/paralelismo.md +48 -0
- package/skills/orquestracao/scripts/coord.sh +131 -0
- package/skills/orquestracao/templates/permissoes-argos.sql +28 -0
- package/skills/orquestracao/templates/plan.md +45 -0
- package/skills/orquestracao/templates/spec.md +54 -0
- package/skills/orquestracao/templates/tasks.md +21 -0
- package/skills/trismegisto/references/angular-exports.md +143 -143
|
@@ -8,8 +8,9 @@
|
|
|
8
8
|
Dockerfile
|
|
9
9
|
.dockerignore
|
|
10
10
|
.env.example só NOMES das variáveis
|
|
11
|
-
requirements.txt dependências de runtime (o que a imagem instala)
|
|
12
|
-
requirements-dev.txt -r requirements.txt + pytest (+ pytest-asyncio se houver teste async)
|
|
11
|
+
requirements.txt dependências DIRETAS de runtime, versão exata (o que a imagem instala)
|
|
12
|
+
requirements-dev.txt -r requirements.txt + pytest + poethepoet (+ pytest-asyncio se houver teste async)
|
|
13
|
+
pyproject.toml SÓ os atalhos do poe (start:local/dev/homol, test); nada de dependência aqui
|
|
13
14
|
pytest.ini testpaths = tests · pythonpath = src
|
|
14
15
|
src/
|
|
15
16
|
main.py get_application() + `app = get_application()`
|
|
@@ -17,7 +18,7 @@
|
|
|
17
18
|
settings/
|
|
18
19
|
__init__.py reexporta AppSettings
|
|
19
20
|
settings.py AppSettings (pydantic-settings) + carga dos .env
|
|
20
|
-
environment/.env.<APP_ENV>
|
|
21
|
+
environment/.env.<APP_ENV> NÃO versionados; environment/.env.example (só nomes) versionado
|
|
21
22
|
core/
|
|
22
23
|
config.py get_app_settings() com @lru_cache
|
|
23
24
|
connections/
|
|
@@ -68,7 +69,11 @@ def catalog_service(request: Request, db: Session = Depends(get_db)) -> CatalogS
|
|
|
68
69
|
return CatalogService(db, getattr(request.state, "user", None))
|
|
69
70
|
```
|
|
70
71
|
|
|
71
|
-
`request.state.user` é preenchido pelo middleware do Orfeu (detalhes na orfeu)
|
|
72
|
+
`request.state.user` é preenchido pelo middleware do Orfeu (detalhes na orfeu, `references/python.md`): é um
|
|
73
|
+
**`TokenClaims`** (objeto, não `dict` — `.sub`, `.groups`, `.realm_id`, `.exp`, `.raw` com o JWT); `None` quando quem
|
|
74
|
+
chamou usou `x-api-token` (a identidade está em `request.state.api_token`); ausente em rota `public`/`optional`
|
|
75
|
+
anônima. Nome do usuário: `user.raw.get("preferred_username") or user.sub`. Nunca `user.get(...)` (500).
|
|
76
|
+
Sempre `getattr(request.state, "user", None)`.
|
|
72
77
|
|
|
73
78
|
## `main.py`
|
|
74
79
|
|
|
@@ -148,26 +153,32 @@ Pontos de atenção:
|
|
|
148
153
|
aguardadas com `suppress(asyncio.CancelledError)`.
|
|
149
154
|
- Middlewares adicionados por último ficam mais externos. Middleware de trace/tempo que deve envolver
|
|
150
155
|
tudo é adicionado depois do CORS.
|
|
151
|
-
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
(quem lê o log de homologação vê que a verificação está desligada):
|
|
156
|
+
- **Nunca `urllib3.disable_warnings(...)` no processo inteiro**: esconde também o caso perigoso (o
|
|
157
|
+
autorizador sem verificação). Prefira configurar a CA (`SSL_CERT_FILE`/`REQUESTS_CA_BUNDLE`). Se o serviço
|
|
158
|
+
fala de propósito com destinos de CA interna (`verify=False`, ex.: appliances de rede), troque o
|
|
159
|
+
silenciamento por **um aviso por host**, registrado uma vez na subida (`main.py` e entrada de collector):
|
|
156
160
|
|
|
157
161
|
```python
|
|
158
|
-
# core/
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
162
|
+
# core/logging.py
|
|
163
|
+
def warn_insecure_requests_once() -> None:
|
|
164
|
+
import warnings
|
|
165
|
+
from urllib3.exceptions import InsecureRequestWarning
|
|
166
|
+
warnings.filterwarnings("once", category=InsecureRequestWarning) # o texto traz o host: 1 aviso por host
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
- **TLS do autorizador desligado é opt-out explícito, com aviso.** `AUTHORIZER_TLS_VERIFY` (default `True`)
|
|
170
|
+
existe só para CA interna fora do bundle. Desligado, o serviço loga um `warning` na subida e o `/health`
|
|
171
|
+
devolve `data: {"tls_verify": false}` — a monitoração vê, não fica escondido:
|
|
172
|
+
|
|
173
|
+
```python
|
|
174
|
+
# main.py, logo depois de settings = get_app_settings()
|
|
166
175
|
if not settings.authorizer_tls_verify:
|
|
167
|
-
logger.warning("
|
|
176
|
+
logger.warning("AUTHORIZER_TLS_VERIFY=false: o certificado do Argos NÃO é verificado (inclusive o JWKS).")
|
|
168
177
|
```
|
|
169
178
|
|
|
170
|
-
|
|
179
|
+
Recusar a subida em produção exige um sinal confiável de ambiente: `APP_ENV` é digitado à mão no deploy e
|
|
180
|
+
não serve como trava. Só adote a recusa quando a plataforma injetar o ambiente. Vale igual para todo
|
|
181
|
+
`*_TLS_VERIFY` de outro destino.
|
|
171
182
|
|
|
172
183
|
## Roteador raiz (`app/__init__.py`)
|
|
173
184
|
|
|
@@ -183,11 +194,13 @@ router.include_router(tags_router) # cada router de domínio tem o próprio pre
|
|
|
183
194
|
|
|
184
195
|
@router.get("/health")
|
|
185
196
|
def health():
|
|
186
|
-
|
|
197
|
+
# tls_verify:false só quando a verificação do certificado do Argos está desligada
|
|
198
|
+
from core.config import get_app_settings
|
|
199
|
+
return ok(data=None if get_app_settings().authorizer_tls_verify else {"tls_verify": False}, message="ok")
|
|
187
200
|
```
|
|
188
201
|
|
|
189
|
-
`/health` sem `@operation` é público de propósito (healthcheck do orquestrador)
|
|
190
|
-
|
|
202
|
+
`/health` sem `@operation` é público de propósito (healthcheck do orquestrador) e fica sob o `api_prefix`
|
|
203
|
+
(`/<projeto>/server/health`). Obrigatório em todo serviço, com teste.
|
|
191
204
|
|
|
192
205
|
## Settings e variáveis de ambiente
|
|
193
206
|
|
|
@@ -215,18 +228,26 @@ class AppSettings(BaseSettings):
|
|
|
215
228
|
def configure_logging(self) -> None: ...
|
|
216
229
|
```
|
|
217
230
|
|
|
218
|
-
- Ambientes: `local`, `dev`, `homol`, `prod` (
|
|
231
|
+
- Ambientes: **só** `local`, `dev`, `homol`, `prod` (o enum tem exatamente esses quatro). Sem `APP_ENV`, `local`;
|
|
232
|
+
arquivo `.env.<APP_ENV>` ausente (container) é ignorado, sem quebrar a subida.
|
|
219
233
|
- `get_app_settings()` com `@lru_cache` em `core/config.py`; nunca instancie `AppSettings()` solto.
|
|
220
234
|
- **Declare todo campo usado.** Depender de `extra="allow"` para ler, por exemplo, a porta faz o código
|
|
221
235
|
funcionar só enquanto a variável existir no ambiente, sem default nem validação.
|
|
222
|
-
- `fastapi_kwargs` põe `docs_url`, `openapi_url` e `redoc_url` sob `api_prefix` — e **
|
|
223
|
-
|
|
224
|
-
|
|
236
|
+
- `fastapi_kwargs` põe `docs_url`, `openapi_url` e `redoc_url` sob `api_prefix` — e **liga os três só em
|
|
237
|
+
`local`** (seguro por padrão: `dev`, `homol` e `prod` desligados; `API_DOCS=true/false` força). O
|
|
238
|
+
`/openapi.json` entrega o mapa inteiro da API (rotas, parâmetros, modelos) a quem chegar, e o `/docs` ainda
|
|
239
|
+
carrega script de CDN:
|
|
225
240
|
|
|
226
241
|
```python
|
|
242
|
+
api_docs: Optional[bool] = None # API_DOCS
|
|
243
|
+
|
|
244
|
+
@property
|
|
245
|
+
def docs_enabled(self) -> bool:
|
|
246
|
+
return self.api_docs if self.api_docs is not None else self.app_env == AppEnvTypes.local
|
|
247
|
+
|
|
227
248
|
@property
|
|
228
249
|
def fastapi_kwargs(self) -> dict:
|
|
229
|
-
docs = self.
|
|
250
|
+
docs = self.docs_enabled
|
|
230
251
|
return {
|
|
231
252
|
"debug": self.debug,
|
|
232
253
|
"title": "meu-servico",
|
|
@@ -236,16 +257,17 @@ class AppSettings(BaseSettings):
|
|
|
236
257
|
}
|
|
237
258
|
```
|
|
238
259
|
|
|
239
|
-
Teste
|
|
260
|
+
Teste parametrizado (`tests/test_api_docs.py`): `local` ligado; `dev`/`homol`/`prod` desligados (`None`);
|
|
261
|
+
`API_DOCS` força nos dois sentidos.
|
|
240
262
|
|
|
241
263
|
Nomes de variáveis usados (sem valores):
|
|
242
264
|
|
|
243
265
|
| Grupo | Variáveis |
|
|
244
266
|
|---|---|
|
|
245
|
-
| Ambiente | `APP_ENV`, `DEBUG`, `PORT`, `API_PREFIX`, `ALLOWED_HOSTS` |
|
|
267
|
+
| Ambiente | `APP_ENV`, `DEBUG`, `PORT`, `API_PREFIX`, `ALLOWED_HOSTS`, `API_DOCS` |
|
|
246
268
|
| Orfeu/Argos | `AUTHORIZER_URL`, `REALM_ID`, `APP_ID`, `APP_SECRET`, `AUTHORIZER_TLS_VERIFY`, `ARGOS_ADMIN_SERVER_URL` (se chamar o admin do Argos) |
|
|
247
269
|
| Postgres | `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `MIN_CONNECTION_COUNT`, `MAX_CONNECTION_COUNT` |
|
|
248
|
-
| Redis | `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB` (+ timeouts/prefixo de canal se usar pub/sub
|
|
270
|
+
| Redis | `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB` (índice próprio do app — dois apps nunca no mesmo índice do mesmo Redis), + timeouts/prefixo `<app>:` de canal se usar pub/sub |
|
|
249
271
|
| Processo | `APP_ROLE` (`all`/`api`/`collector`) quando há collectors — ver integracoes.md |
|
|
250
272
|
|
|
251
273
|
Serviço com **vários bancos** usa o padrão de prefixo: `DB_ENTRIES=<nome1>,<nome2>` e, para cada nome,
|
|
@@ -255,27 +277,49 @@ com um banco, `DB_*` + `get_db`.
|
|
|
255
277
|
|
|
256
278
|
## Dependências
|
|
257
279
|
|
|
258
|
-
`requirements.txt`
|
|
280
|
+
`requirements.txt` = **dependências diretas** (o que o código importa), cada uma com **versão exata** — build
|
|
281
|
+
reproduzível, sem pacote morto e sem `pip freeze` de ambiente inteiro. As transitivas o pip resolve. Para
|
|
282
|
+
atualizar: troque a versão, recrie o ambiente do zero e rode a suíte.
|
|
259
283
|
|
|
260
284
|
```
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
redis
|
|
271
|
-
|
|
285
|
+
# Dependências DIRETAS (o que o código importa), com versão exata.
|
|
286
|
+
fastapi==0.142.2
|
|
287
|
+
uvicorn[standard]==0.54.0 # [standard]: uvloop + httptools (HTTP mais rápido no Linux)
|
|
288
|
+
orfeu[fastapi]==1.0.0
|
|
289
|
+
pydantic-settings==2.15.0
|
|
290
|
+
python-dotenv==1.2.4
|
|
291
|
+
loguru==0.7.3
|
|
292
|
+
SQLAlchemy==2.1.3
|
|
293
|
+
psycopg2-binary==2.9.13
|
|
294
|
+
redis==8.1.0 # se usar Redis
|
|
295
|
+
httpx==0.28.1
|
|
296
|
+
python-multipart==0.0.32 # só se houver upload (Form/File)
|
|
272
297
|
```
|
|
273
298
|
|
|
299
|
+
`requirements-dev.txt`: `-r requirements.txt`, `pytest==…`, `poethepoet==…` (e `pytest-asyncio==…` se
|
|
300
|
+
houver teste async). Os serviços de um mesmo ecossistema usam **as mesmas versões** das libs em comum.
|
|
301
|
+
|
|
302
|
+
Atalhos de execução no `pyproject.toml` (só `[tool.poe.tasks]`, sem `[project]`/Poetry):
|
|
303
|
+
|
|
304
|
+
```toml
|
|
305
|
+
[tool.poe.tasks."start:local"]
|
|
306
|
+
cmd = "uvicorn main:app --host 0.0.0.0 --port 8000 --reload"
|
|
307
|
+
cwd = "src"
|
|
308
|
+
env = { APP_ENV = "local" }
|
|
309
|
+
# idem start:dev e start:homol (APP_ENV=dev/homol)
|
|
310
|
+
|
|
311
|
+
[tool.poe.tasks.test]
|
|
312
|
+
cmd = "python -m pytest"
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
`poe start:homol` escolhe o ambiente pelo comando, como os `npm run start:<ambiente>` do Node — sem editar o
|
|
316
|
+
`src/.env`. Serviço que sobe processo filho (collector) fica **sem** `--reload` (o reload duplicaria o filho).
|
|
317
|
+
|
|
274
318
|
Divergências observadas e recomendação:
|
|
275
319
|
|
|
276
320
|
| Tema | Visto | Recomendado |
|
|
277
321
|
|---|---|---|
|
|
278
|
-
| Gerenciador | `requirements.txt`
|
|
322
|
+
| Gerenciador | `requirements.txt` sem versão, ou congelado com transitivas e pacotes mortos, + `pyproject.toml` Poetry paralelo | **pip**: diretas com versão exata; `pyproject.toml` só com o poe; nada de Poetry/`poetry.lock` |
|
|
279
323
|
| Python | 3.11 na imagem; local rodando 3.14 | piso 3.11; teste local na mesma menor da imagem quando possível |
|
|
280
324
|
| Pasta | `server/` (2) vs `fastapi/` (1) | `server/` |
|
|
281
325
|
| Imports diretos | pacote importado no código que só vinha como dependência transitiva (já corrigido num serviço) | declare no requirements tudo que o código importa diretamente |
|
|
@@ -18,8 +18,8 @@ introspecção (60 s; inativo 10 s), parâmetros do lote de auditoria e campos d
|
|
|
18
18
|
| Timeouts das chamadas ao Argos | só a auditoria tem (10 s); token do serviço, sync, operações e introspecção **sem timeout** | 10 s em todas (introspecção: 5 s) |
|
|
19
19
|
| Erro de rede na subida | erro cru do `fetch` (não é `OrfeuError`) | embrulhado: `OrfeuAuthError` / `OrfeuSyncError` / `OrfeuError` |
|
|
20
20
|
| Quem chama a subida | o app: `client.startup()` / `OrfeuClient.create()` depois de declarar as rotas; Nest: `OrfeuModule.forRootAsync` | FastAPI: automático no lifespan (`Orfeu(app, ...)`); Flask e Django: **na construção**, síncrono; Strawberry: o app chama `startup_async()` no lifespan |
|
|
21
|
-
| Permissões (`allowed_groups`) |
|
|
22
|
-
| `fetchOperations` / `fetch_operations` com token do serviço vencido (401) |
|
|
21
|
+
| Permissões (`allowed_groups`) | revalidadas a cada 60 s por padrão (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1; opção `permissionsRefresh`); antes, só na subida ou em `fetchOperations()` manual | idem (`permissions_refresh`); antes, só na subida ou em `fetch_operations()` manual |
|
|
22
|
+
| `fetchOperations` / `fetch_operations` com token do serviço vencido (401) | reautentica uma vez e repete (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1); antes lançava `OrfeuError` | idem (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1) |
|
|
23
23
|
| Reautenticação automática no 401 | só na auditoria e na introspecção | idem |
|
|
24
24
|
| Inferência de `Method` sem `method` explícito | pelo **último segmento do id** após `:` (`tasks:list` → `read`); Apollo: pelo tipo raiz (Query → `read`, Mutation → `write`/`delete`, Subscription → `stream`) | pelo **nome da função** (`get_`/`list_`/... → `read`) |
|
|
25
25
|
| Convenção de id nos exemplos | `recurso:acao` | `recurso.acao` |
|
|
@@ -38,7 +38,7 @@ introspecção (60 s; inativo 10 s), parâmetros do lote de auditoria e campos d
|
|
|
38
38
|
| Classes de erro | 401 do `createGuard` é `Error` comum; não existe `OrfeuUnauthorizedError` | existe `OrfeuUnauthorizedError` (e as negações também são `PermissionError`) |
|
|
39
39
|
| WebSocket negado | Apollo/graphql-ws: `GraphQLError` | FastAPI: fecha com **1008** antes do `accept` |
|
|
40
40
|
| Envelope de resposta do app | não existe no SDK | `install_envelope(app)`, `ok`/`fail`, `NotFound`, `Conflict`… |
|
|
41
|
-
| Flush da auditoria no encerramento |
|
|
41
|
+
| Flush da auditoria no encerramento | `await client.close()` no SIGTERM do app (para a recarga + flush; `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1) — Fastify/Nest/Apollo fazem sozinhos; antes, `flushAudit()` manual | automático no shutdown do lifespan (FastAPI); Flask `orfeu.shutdown()`/`atexit`; Django `atexit` |
|
|
42
42
|
| Log de operação padrão | uma linha JSON no **stdout** (`jsonLineLogger`); `logger: false` desliga | `logging` padrão (`orfeu.operation`), **sem handler**: sem configurar, as linhas INFO não aparecem; `JsonLogFormatter` opcional |
|
|
43
43
|
| `traceparent` repassado | flags propagadas como chegaram | só o bit *sampled* é propagado |
|
|
44
44
|
| `orfeuHeaders` / `orfeu_headers` fora de operação protegida | Express/Fastify: funciona em qualquer rota que passou pela captura global (mesmo sem guard); Nest: só em método com `@Operation`; Apollo: com o plugin/contexto instalado | devolve `{}` fora de chamada guardada |
|
|
@@ -32,7 +32,11 @@ class OrfeuClient {
|
|
|
32
32
|
startup(): Promise<void>;
|
|
33
33
|
authenticate(): Promise<void>;
|
|
34
34
|
syncOperations(): Promise<void>;
|
|
35
|
-
fetchOperations(): Promise<
|
|
35
|
+
fetchOperations(): Promise<boolean>; // true se o catálogo mudou; reautentica uma vez no 401
|
|
36
|
+
refreshOperations(): Promise<boolean>; // revalidação (If-None-Match); nunca lança; true = sucesso
|
|
37
|
+
startPermissionsRefresh(): void; stopPermissionsRefresh(): void;
|
|
38
|
+
readonly lastPermissionsSyncAt: Date | null; readonly permissionsStale: boolean;
|
|
39
|
+
close(timeoutMs?: number): Promise<void>; // para a recarga + flushAudit
|
|
36
40
|
validateToken(token: string): Promise<TokenClaims>;
|
|
37
41
|
validateAppToken(token: string): Promise<TokenClaims>;
|
|
38
42
|
validateApiToken(token: string, identifier: string, method: string): Promise<ApiTokenClaims | null>;
|
|
@@ -56,7 +60,9 @@ class OrfeuClient {
|
|
|
56
60
|
| `checkPermission(claims, id, method)` | usa o cache do `fetchOperations()`: operação desconhecida → `false`; `public` → `true`; `private`/`optional` → `claims.groups.length > 0`; `protected` → algum grupo em `allowed_groups`. |
|
|
57
61
|
| `operationIdOf(id, method)` | UUID da operação no Argos (depois do `fetchOperations()`), para logs. |
|
|
58
62
|
| `recordAudit(event)` | põe um evento na fila (no-op com `audit: false`). Nunca bloqueia. |
|
|
59
|
-
| `flushAudit(timeoutMs = 3000)` | envia o que estiver na fila, esperando no máximo `timeoutMs`.
|
|
63
|
+
| `flushAudit(timeoutMs = 3000)` | envia o que estiver na fila, esperando no máximo `timeoutMs`. |
|
|
64
|
+
| `close(timeoutMs = 3000)` | (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1) para a recarga de permissões e faz o `flushAudit`. Use no encerramento. |
|
|
65
|
+
| `permissionsRefresh` (opção) | (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1) `true` (padrão: 60 s, ±20%), `false` ou `{ enabled, intervalMs, jitter }`. O `startup()` agenda a recarga; timer com `unref()`. |
|
|
60
66
|
|
|
61
67
|
### Tipos de identidade
|
|
62
68
|
|
|
@@ -30,8 +30,8 @@ constantes; em TypeScript, variáveis `string` precisam do tipo `Level`/`Method`
|
|
|
30
30
|
## 401 / 403 inesperados
|
|
31
31
|
|
|
32
32
|
**403 para todo mundo numa operação nova `protected`.** A operação acabou de ser sincronizada e ainda não tem
|
|
33
|
-
grupos em `allowed_groups` no Argos. Libere os grupos no Argos
|
|
34
|
-
(reinício ou `fetchOperations()` periódico — `node-recipes.md` §10).
|
|
33
|
+
grupos em `allowed_groups` no Argos. Libere os grupos no Argos; com `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1 o serviço recarrega sozinho em até
|
|
34
|
+
~1 min (antes: reinício ou `fetchOperations()` periódico — `node-recipes.md` §10).
|
|
35
35
|
|
|
36
36
|
**403 em `private` para um usuário logado.** `private`/`optional` exigem **pelo menos um grupo** na claim
|
|
37
37
|
`groups`. Usuário sem grupo no client/badge recebe 403.
|
|
@@ -41,7 +41,7 @@ registrado tarde, módulo carregado com `import()` dinâmico): ela não está no
|
|
|
41
41
|
`checkPermission` devolve `false` (só `public` escapa). Declare tudo antes do `startup()`.
|
|
42
42
|
|
|
43
43
|
**Permissão mudou no Argos e o serviço não percebeu.** O catálogo com `allowed_groups` é lido no `startup()`.
|
|
44
|
-
|
|
44
|
+
Com `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1 a recarga é automática; antes, recarregue com `fetchOperations()` (reautenticando se der 401). Grupos do **usuário** mudam quando o token dele
|
|
45
45
|
é renovado.
|
|
46
46
|
|
|
47
47
|
**401 com token válido.**
|
|
@@ -127,7 +127,7 @@ descartados do evento, mas continuam no log).
|
|
|
127
127
|
|
|
128
128
|
## Auditoria e log
|
|
129
129
|
|
|
130
|
-
**Eventos perdidos ao reiniciar.** Faltou `await client.flushAudit()` no SIGTERM (`node-recipes.md` §11).
|
|
130
|
+
**Eventos perdidos ao reiniciar.** Faltou `await client.close()` (ou `flushAudit()` em versão antiga) no SIGTERM (`node-recipes.md` §11).
|
|
131
131
|
|
|
132
132
|
**Aviso `[orfeu] authorizer has no audit endpoint (404); auditing paused for 10 min`.** O Argos não tem a
|
|
133
133
|
ingestão de auditoria; a fila é descartada e o SDK tenta de novo depois. Se a auditoria não é desejada:
|
|
@@ -146,7 +146,7 @@ export class ClientesController {
|
|
|
146
146
|
módulo do app. Métodos sem `@Operation` continuam **abertos** — confira todos.
|
|
147
147
|
- `OrfeuClient` é injetável (`constructor(private readonly orfeu: OrfeuClient) {}`) para `checkPermission`,
|
|
148
148
|
`flushAudit` etc.
|
|
149
|
-
- Encerramento: `app.enableShutdownHooks()` e, num provider, `async onApplicationShutdown() { await this.orfeu.flushAudit(); }`.
|
|
149
|
+
- Encerramento: `app.enableShutdownHooks()`; o `OrfeuModule` para a recarga e envia a auditoria no `onModuleDestroy` (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1). Antes, num provider, `async onApplicationShutdown() { await this.orfeu.flushAudit(); }`.
|
|
150
150
|
|
|
151
151
|
## 4. Apollo Server (HTTP + WebSocket)
|
|
152
152
|
|
|
@@ -400,19 +400,24 @@ async function startOrfeu(): Promise<void> {
|
|
|
400
400
|
}
|
|
401
401
|
}
|
|
402
402
|
|
|
403
|
-
// grupos liberados (allowed_groups) só são lidos no startup: recarregue de tempos em tempos
|
|
404
|
-
async function refreshPermissions(): Promise<void> {
|
|
405
|
-
try {
|
|
406
|
-
await client.fetchOperations();
|
|
407
|
-
} catch {
|
|
408
|
-
await client.authenticate(); // token do serviço vence; fetchOperations não reautentica sozinho
|
|
409
|
-
await client.fetchOperations();
|
|
410
|
-
}
|
|
411
|
-
}
|
|
412
|
-
setInterval(() => { refreshPermissions().catch((e) => console.warn('[app] permissões não recarregadas', e)); }, 5 * 60_000).unref();
|
|
413
403
|
```
|
|
414
404
|
|
|
415
405
|
Um `OrfeuAuthError` com HTTP 401 na subida quase sempre é `APP_ID`/`APP_SECRET` errados; repetir não resolve.
|
|
406
|
+
HTTP 400 `invalid_request` no `/apps/token` é `APP_ID` que não é UUID ou `APP_SECRET` **vazio** (variável não preenchida).
|
|
407
|
+
|
|
408
|
+
**Permissões atualizadas** (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1): o client revalida sozinho o catálogo com os grupos liberados a cada 60 s
|
|
409
|
+
(±20%), com `If-None-Match` (304 quando nada mudou), troca o catálogo de uma vez, reautentica no 401 e, se o Argos
|
|
410
|
+
estiver fora, mantém o catálogo anterior (`permissionsStale` vira `true` depois de 5 ciclos sem sucesso). Liberar ou
|
|
411
|
+
**revogar** um grupo no Argos vale em até ~1 min, sem reiniciar. Ajuste ou desligue no construtor:
|
|
412
|
+
|
|
413
|
+
```ts
|
|
414
|
+
const client = new OrfeuClient({ /* … */, permissionsRefresh: { intervalMs: 60_000, jitter: 0.2 } }); // ou false
|
|
415
|
+
client.lastPermissionsSyncAt; // Date | null — último sucesso
|
|
416
|
+
client.permissionsStale; // true após 5 intervalos sem sucesso (bom para o /health, sem derrubar)
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
Versão anterior a essa: as permissões só eram lidas no `startup()` — recarregue com `fetchOperations()` num
|
|
420
|
+
`setInterval` (`unref()`), chamando `authenticate()` antes de repetir quando der 401 (o token do serviço vence).
|
|
416
421
|
|
|
417
422
|
## 11. Encerramento sem perder eventos
|
|
418
423
|
|
|
@@ -420,13 +425,15 @@ Um `OrfeuAuthError` com HTTP 401 na subida quase sempre é `APP_ID`/`APP_SECRET`
|
|
|
420
425
|
for (const signal of ['SIGTERM', 'SIGINT'] as const) {
|
|
421
426
|
process.once(signal, async () => {
|
|
422
427
|
server.close(); // para de aceitar conexões
|
|
423
|
-
await client.
|
|
428
|
+
await client.close(5_000); // para a recarga de permissões e envia a fila de auditoria (máx. 5 s)
|
|
424
429
|
process.exit(0);
|
|
425
430
|
});
|
|
426
431
|
}
|
|
427
432
|
```
|
|
428
433
|
|
|
429
434
|
Em container sem init, o processo Node é o PID 1 e só termina no SIGTERM se tratar o sinal (como acima).
|
|
435
|
+
`close()` existe a partir de `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1; antes, `flushAudit()` (não havia recarga para parar). Fastify (`fastify.close()`),
|
|
436
|
+
Nest (`app.close()`) e o `orfeuPlugin` do Apollo (`server.stop()`) já chamam o encerramento do client sozinhos.
|
|
430
437
|
|
|
431
438
|
## 12. Testes
|
|
432
439
|
|
|
@@ -51,6 +51,7 @@ A lib **não lê variáveis de ambiente**. Tudo entra pelo construtor (`Orfeu(..
|
|
|
51
51
|
| `secret` | sim | Segredo do backend, em texto puro. Nunca no código: venha de variável de ambiente/cofre. |
|
|
52
52
|
| `tls_verify` | não, só por nome (`*`) | `True` (padrão). `False` desliga a verificação TLS **só** nas chamadas ao Argos (certificado autoassinado em desenvolvimento). Não é global. |
|
|
53
53
|
| `audit` | não, só por nome | `True` (padrão), `False` (desliga a auditoria) ou `AuditOptions(...)` (ajusta lote/buffer). |
|
|
54
|
+
| `permissions_refresh` | não, só por nome (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1) | `True` (padrão: revalida o catálogo com os grupos liberados a cada 60 s ±20%, com `If-None-Match`; mantém o anterior se o Argos cair), `False` ou `PermissionsRefreshOptions(enabled, interval_s, jitter)`. Django: `ORFEU_PERMISSIONS_REFRESH`. |
|
|
54
55
|
|
|
55
56
|
Django: settings `ORFEU_AUTHORIZER_URL`, `ORFEU_REALM_ID`, `ORFEU_APP_ID`, `ORFEU_SECRET` (obrigatórios —
|
|
56
57
|
sem eles o middleware levanta `RuntimeError`), `ORFEU_TLS_VERIFY` e `ORFEU_AUDIT` (opcionais).
|
|
@@ -84,8 +85,8 @@ async def list_items(request: Request):
|
|
|
84
85
|
```
|
|
85
86
|
|
|
86
87
|
- `Orfeu(app, ...)` instala um middleware ASGI e **embrulha o lifespan** do app: no startup roda
|
|
87
|
-
token do app → JWKS → sync das operações → busca das operações com grupos
|
|
88
|
-
auditoria. Funciona com `lifespan=` e com `on_startup`. Não chame nada no seu lifespan.
|
|
88
|
+
token do app → JWKS → sync das operações → busca das operações com grupos (e, com `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1, agenda a recarga
|
|
89
|
+
periódica delas); no shutdown para a recarga e faz o flush da auditoria (`client.close()`). Funciona com `lifespan=` e com `on_startup`. Não chame nada no seu lifespan.
|
|
89
90
|
- O startup **falha** (e o app não sobe) se o Argos recusar as credenciais (`OrfeuAuthError`), o sync falhar
|
|
90
91
|
(`OrfeuSyncError`), o JWKS não vier (`OrfeuError`) ou **nenhuma** `@operation` estiver registrada
|
|
91
92
|
(`OrfeuConfigError`). Não há retentativa: o Argos precisa estar acessível no boot.
|
|
@@ -133,6 +134,11 @@ O que o handler FastAPI recebe (`request.state` / `websocket.state`):
|
|
|
133
134
|
|
|
134
135
|
Por isso, em `public`/`optional` leia com `getattr(request.state, "user", None)`.
|
|
135
136
|
|
|
137
|
+
`TokenClaims` é um **objeto** (dataclass), não um `dict`: `user.sub`, `user.realm_id`, `user.groups`, `user.exp` e
|
|
138
|
+
`user.raw` (o JWT decodificado inteiro). Nome/e-mail do usuário estão em `raw`:
|
|
139
|
+
`user.raw.get("preferred_username") or user.raw.get("email") or user.sub`. `user.get(...)` lança
|
|
140
|
+
`AttributeError: 'TokenClaims' object has no attribute 'get'` (500 na rota).
|
|
141
|
+
|
|
136
142
|
## 6. Respostas, erros e status
|
|
137
143
|
|
|
138
144
|
| Situação | Resposta |
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: orquestracao
|
|
3
|
+
description: Orquestra uma mudança grande do pedido à entrega no estilo spec-driven — especificação do contrato nas camadas (server, GraphQL, Angular, banco, Argos), plano em itens Txx, execução por vários agentes/sessões em paralelo com reserva atômica de itens (scripts/coord.sh), verificação com provas e fechamento. Use quando o pedido atravessa mais de uma camada ou mais de um app, quando for dividir trabalho entre subagentes ou sessões paralelas, quando o usuário pedir "spec", "plano", "SDD", "paraleliza", "orquestra", ou quando houver uma lista de itens Txx a distribuir entre workers.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# orquestracao
|
|
7
|
+
|
|
8
|
+
Leva uma mudança grande do pedido à entrega, com vários agentes trabalhando ao mesmo tempo sem pisar um no outro.
|
|
9
|
+
Esta skill diz **o que fazer, em que ordem e como dividir**; o **como** de cada camada está nas skills da stack
|
|
10
|
+
(`angular`, `trismegisto`, `apollo`, `express`, `fastapi`, `orfeu`, `docker`, `hefesto`, `documentacao`) e o desenho
|
|
11
|
+
do app inteiro na skill `acropole` (`references/arquitetura.md`). Carregue a skill da camada antes de mexer nela.
|
|
12
|
+
|
|
13
|
+
Responda em português. Pergunte só o que é decisão do usuário (escopo, nível de acesso, regra de negócio, apagar algo);
|
|
14
|
+
o resto resolva com o padrão e diga o que escolheu.
|
|
15
|
+
|
|
16
|
+
## Ordem de dependência de uma mudança
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
server/ (regra, banco, envelope, @operation) → graphql/ (repasse, operation()) → angular/ (tela, service, toast)
|
|
20
|
+
↘ database/ (schema, seed, migration) Argos (operações, permissões, rotas) ↙
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Onde fica cada coisa (no repositório do app)
|
|
24
|
+
|
|
25
|
+
| O quê | Onde | Git |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| Itens de trabalho (Txx) e protocolo dos workers | `docs/sdd/tasks.md` (de `templates/tasks.md`) | versionado |
|
|
28
|
+
| Pendências e decisões em aberto | `docs/sdd/pending.md` | versionado |
|
|
29
|
+
| Specs | `docs/sdd/specs/<tema>.md` (de `templates/spec.md`) | versionado |
|
|
30
|
+
| Planos para vários agentes | `docs/sdd/plans/<tema>.md` (de `templates/plan.md`) | versionado |
|
|
31
|
+
| Travas de coordenação | `.sdd/coord/` (criado pelo `coord.sh`) | **fora do git** |
|
|
32
|
+
|
|
33
|
+
`coord.sh` = `bash <pasta desta skill>/scripts/coord.sh` (instalada: `~/.claude/skills/orquestracao/scripts/coord.sh`,
|
|
34
|
+
ou `./.claude/skills/...` com `--project`). Ele acha a raiz pelo git da pasta atual; `coord.sh init` cria a lista e põe
|
|
35
|
+
`.sdd/` no `.gitignore`. Trabalho que atravessa vários repositórios: uma lista por repositório, ou `COORD_ROOT` apontando
|
|
36
|
+
para uma pasta comum (e `COORD_TASKS` para a lista).
|
|
37
|
+
|
|
38
|
+
## Fase 0 — Contexto (antes de qualquer arquivo)
|
|
39
|
+
|
|
40
|
+
1. README/`CLAUDE.md` do repositório e das pastas que vai tocar.
|
|
41
|
+
2. `docs/sdd/pending.md` e `docs/sdd/tasks.md`: o pedido pode já estar descrito ou bloqueado por uma decisão.
|
|
42
|
+
3. Trabalho em andamento: `coord.sh status` (e `coord.sh stale` para reserva parada/órfã). Não mexa em
|
|
43
|
+
arquivo/recurso reservado por outro worker.
|
|
44
|
+
4. O domínio mais parecido já existente nas camadas: ele é o molde.
|
|
45
|
+
5. `git status` de cada repositório envolvido: mudança pendente que não é sua não entra no seu commit.
|
|
46
|
+
|
|
47
|
+
## Fase 1 — Especificação (o quê)
|
|
48
|
+
|
|
49
|
+
`docs/sdd/specs/<tema>.md` a partir de `templates/spec.md`. Define o **contrato**, não o código: comportamento
|
|
50
|
+
observável; rotas do server (método, caminho, entrada, `data`, operação e nível, mensagens e erros); campos do GraphQL e
|
|
51
|
+
canais; telas, ações e toasts do Angular (`router_id` se tela nova); dados; Argos (operações, níveis, grupos, tokens,
|
|
52
|
+
rotas liberadas); fora do escopo, restrições e critérios de aceite verificáveis. Um nome por domínio nas camadas
|
|
53
|
+
(`pedidos` / `pedidos` / `pedidos:*`). Mostre ao usuário quando houver decisão dele dentro; senão siga.
|
|
54
|
+
|
|
55
|
+
## Fase 2 — Plano (como, em itens)
|
|
56
|
+
|
|
57
|
+
- Itens `Txx` (próximo número livre) em `docs/sdd/tasks.md`: `- [ ] **Txx** · <camada/domínio> — <alteração> (data)`.
|
|
58
|
+
**Um item = uma entrega verificável**, de preferência uma camada de um domínio (ou um app, numa mudança entre apps).
|
|
59
|
+
- Ordem: server → GraphQL → Angular → banco/Argos → fechamento. Itens de pastas **disjuntas** podem ir em paralelo.
|
|
60
|
+
- Trabalho para vários agentes: `docs/sdd/plans/<tema>.md` (de `templates/plan.md`) com decisões tomadas, mapa de
|
|
61
|
+
nomes, dependências, arquivos compartilhados e uma seção "Registro" por item.
|
|
62
|
+
|
|
63
|
+
## Fase 3 — Execução (um ou vários workers)
|
|
64
|
+
|
|
65
|
+
Para cada item:
|
|
66
|
+
|
|
67
|
+
1. Reservar: `coord.sh register` (uma vez por sessão) → `coord.sh claim <worker> Txx` → `coord.sh check <worker> Txx`
|
|
68
|
+
responde `OK` → só então implementar.
|
|
69
|
+
2. Implementar seguindo a skill da camada.
|
|
70
|
+
3. Provas da camada (Fase 4) passando.
|
|
71
|
+
4. Registrar no plano (seção do item) ou na resposta: o que mudou, provas, o que ficou para o usuário.
|
|
72
|
+
5. `coord.sh done <worker> Txx` e `[x]` na linha. Bloqueado: `coord.sh release`. Ao encerrar: `coord.sh unregister`.
|
|
73
|
+
|
|
74
|
+
Como dividir entre subagentes/sessões, o que vai no prompt de cada um e os recursos que travam (dev server segurando
|
|
75
|
+
`node_modules`, banco e Redis compartilhados, git): [references/paralelismo.md](references/paralelismo.md).
|
|
76
|
+
|
|
77
|
+
## Fase 4 — Verificação (provas, não impressão)
|
|
78
|
+
|
|
79
|
+
| Camada | Prova |
|
|
80
|
+
|---|---|
|
|
81
|
+
| server | `pytest` inteiro (ambiente recriado do zero se mudou dependência) |
|
|
82
|
+
| GraphQL | `tsc --noEmit`, `vitest`, `build`; todo campo com `operation()` |
|
|
83
|
+
| Angular | codegen sem erro, `ng test`, `ng build`, `lint:a11y` |
|
|
84
|
+
| banco | `python build.py` e a suíte da pasta (PGlite) |
|
|
85
|
+
| ponta a ponta | serviços locais de pé com o código novo; o usuário valida no navegador |
|
|
86
|
+
|
|
87
|
+
Relate falha como falha, com a saída. Teste que depende de dado/ambiente externo (Redis real, equipamento): diga qual e
|
|
88
|
+
por quê; rode-o isolado antes de concluir que a mudança quebrou algo (carga de várias suítes em paralelo derruba teste de
|
|
89
|
+
tempo).
|
|
90
|
+
|
|
91
|
+
## Fase 5 — Argos (permissões e telas)
|
|
92
|
+
|
|
93
|
+
- O sync do Orfeu cria as operações novas e **desativa** as que o app não declara mais; **não dá permissão**.
|
|
94
|
+
`protected` precisa de permissão por grupo; **token de API (`x-api-token`) precisa de permissão em qualquer nível**;
|
|
95
|
+
operação renomeada perde as permissões da antiga (`templates/permissoes-argos.sql` leva para a nova).
|
|
96
|
+
- Tela nova: rota e roteador do client **e** a liberação do roteador para os grupos (sem ela o menu vem vazio);
|
|
97
|
+
`router_id` no `features.routes.ts`. Client novo: redirect URIs (inclusive `localhost`) e acesso dos grupos.
|
|
98
|
+
- Banco de produção: só leitura. Quem aplica migration é o usuário, no deploy.
|
|
99
|
+
|
|
100
|
+
## Fase 6 — Fechamento
|
|
101
|
+
|
|
102
|
+
- `docs/sdd/pending.md`: apague o resolvido; registre o que ficou (decisões do usuário, dívidas) com **o quê / onde /
|
|
103
|
+
o que falta**.
|
|
104
|
+
- README/`CLAUDE.md` que mudaram de verdade; variáveis de ambiente novas (lista para o deploy).
|
|
105
|
+
- Relatório ao usuário: o que foi feito, provas (números), o que é dele (validar no navegador, Argos, deploy, commits).
|
|
106
|
+
|
|
107
|
+
## Regras que não se quebram
|
|
108
|
+
|
|
109
|
+
- **Sem commit nem push** sem pedido explícito (vale só para aquele pedido). Commit, quando pedido: confira antes o
|
|
110
|
+
`git status` — mudança de outra pessoa ou pasta que o projeto não versiona por combinado não entra sem confirmação;
|
|
111
|
+
um commit por repositório, mensagem no padrão do repositório.
|
|
112
|
+
- Working tree compartilhado: nunca `git reset/stash/clean/checkout -- .`.
|
|
113
|
+
- Banco, Redis e serviços compartilhados não recebem dado de teste: SQLite em memória, Redis falso, mocks.
|
|
114
|
+
- Credencial nunca em código, log ou resposta; ao mexer em `.env`, não imprima valores. Segredo gerado para o usuário
|
|
115
|
+
vai para arquivo fora de qualquer repositório.
|
|
116
|
+
- Processo do usuário (dev server, Argos local) não se derruba sem pedir; diga qual processo e por quê.
|
|
117
|
+
- Mudança fora do escopo do item (outro repositório, desenho novo): proponha antes de fazer.
|
|
118
|
+
- Ações reais em servidores/containers (deploy, rollback, restart) não se testam contra ambiente real: mocks.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Paralelismo: subagentes, sessões e recursos compartilhados
|
|
2
|
+
|
|
3
|
+
## Quando paralelizar
|
|
4
|
+
|
|
5
|
+
- **Pode** ir em paralelo: itens em pastas disjuntas (o `server/` de um app e o `angular/` de outro; libs diferentes;
|
|
6
|
+
documentação × código), validações independentes (a suíte de cada app), leitura/levantamento.
|
|
7
|
+
- **Não** vai em paralelo: dois agentes no mesmo arquivo, item que depende da saída de outro (o codegen do front precisa
|
|
8
|
+
do schema do GraphQL), qualquer coisa que mexa no mesmo `package.json`/lockfile ao mesmo tempo.
|
|
9
|
+
- Tarefa pequena e sequencial: faça você mesmo; subagente começa sem contexto e custa caro para reconstruí-lo.
|
|
10
|
+
|
|
11
|
+
## Subagente (Agent/Task) — o prompt é tudo o que ele sabe
|
|
12
|
+
|
|
13
|
+
Inclua sempre:
|
|
14
|
+
|
|
15
|
+
1. **Objetivo e escopo fechado**: repositório e pastas que pode tocar; o que **não** pode (outros repositórios, pastas
|
|
16
|
+
que o projeto não versiona, `.env` de verdade).
|
|
17
|
+
2. **Contexto mínimo**: onde está a spec/plano, o domínio molde, as skills a seguir (nome), comandos de teste/venv.
|
|
18
|
+
3. **Decisões já tomadas** (o subagente não deve reabrir) e **o que deixar para o usuário**.
|
|
19
|
+
4. **Provas exigidas**: quais suítes rodar e que tudo passe; o que fazer se uma falha não for dele.
|
|
20
|
+
5. **Proibições**: sem commit/push/publicação/bump; sem `git reset/stash/clean`; sem dado de teste em recurso real.
|
|
21
|
+
6. **Formato do relatório**: arquivos alterados, decisões, números das suítes, o que não deu para fazer, riscos.
|
|
22
|
+
|
|
23
|
+
Rode em segundo plano quando houver outra coisa útil a fazer; não faça em paralelo o mesmo trabalho dele. Complemento do
|
|
24
|
+
usuário no meio do caminho: mande para o subagente (mensagem) em vez de recomeçar. O relatório dele é pista: confira os
|
|
25
|
+
pontos críticos (rode a suíte) antes de dar como feito.
|
|
26
|
+
|
|
27
|
+
## Sessões paralelas (vários terminais/agentes no mesmo working tree)
|
|
28
|
+
|
|
29
|
+
- Cada sessão: `coord.sh register` → um item por vez (`claim`/`check`/`done`) → `unregister` ao sair.
|
|
30
|
+
- Reserva parada: `coord.sh stale [horas]`. Worker que morreu sem `unregister`: `coord.sh orphans --release` devolve os
|
|
31
|
+
itens dele (confira antes que a sessão realmente acabou).
|
|
32
|
+
- Trabalho entre repositórios: `COORD_ROOT=<pasta comum> COORD_TASKS=<lista>` em todas as sessões.
|
|
33
|
+
|
|
34
|
+
## Recursos que travam (e como contornar sem derrubar o usuário)
|
|
35
|
+
|
|
36
|
+
| Recurso | Sintoma | O que fazer |
|
|
37
|
+
|---|---|---|
|
|
38
|
+
| Dev server (`ng serve`, `nodemon`, `uvicorn --reload`) rodando | `EBUSY`/`EPERM` no `npm install` (Windows trava `.node`/`sass-embedded`) | `npm install --package-lock-only` (lock e `package.json` certos, `node_modules` depois); avise para reiniciar |
|
|
39
|
+
| Dependência trocada com processo de pé | `uvicorn --reload` antigo + pacote novo = erro estranho (`'Config' object has no attribute ...`); `nodemon` compilou antes do install | reiniciar o processo (Ctrl+C e subir de novo); não é bug do código |
|
|
40
|
+
| Processo órfão (pai morreu) | porta ocupada, código antigo respondendo | listar processo + pai (PowerShell `Get-CimInstance Win32_Process`, `ps -o ppid`); encerrar só com o ok do usuário |
|
|
41
|
+
| Banco/Redis compartilhado | teste "falha" por dado ausente ou sujo | teste isolado com SQLite/Redis falso; teste que lê dado real é ambiental — diga isso |
|
|
42
|
+
| Git | dois agentes commitando | commit só por caminho, um repositório por vez, sem `add -A` cego |
|
|
43
|
+
| CPU | suítes em paralelo derrubam teste de tempo | rode o teste que falhou isolado antes de concluir |
|
|
44
|
+
|
|
45
|
+
## Validação em lote (vários apps)
|
|
46
|
+
|
|
47
|
+
Dispare as suítes de cada app em paralelo (um processo por app, saída em arquivo), depois resuma em tabela
|
|
48
|
+
(app → testes/build → resultado). Falhou um: rode isolado, leia o erro, separe "quebrou com a mudança" de "ambiental".
|