@acropole/skills 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/README.md +181 -2
  2. package/agents/revisor-deploy.md +73 -0
  3. package/agents/revisor-documentacao.md +78 -0
  4. package/agents/revisor-orfeu.md +80 -0
  5. package/agents/revisor-trismegisto.md +81 -0
  6. package/bin/install.js +252 -0
  7. package/package.json +15 -4
  8. package/skills/acropole/SKILL.md +80 -0
  9. package/skills/acropole/references/arquitetura.md +174 -0
  10. package/skills/acropole/references/fluxos/app-novo.md +34 -0
  11. package/skills/acropole/references/fluxos/doctor.md +55 -0
  12. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  13. package/skills/acropole/references/fluxos/revisar.md +56 -0
  14. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  15. package/skills/acropole/scripts/doctor.mjs +439 -0
  16. package/skills/angular/SKILL.md +155 -0
  17. package/skills/angular/references/armadilhas.md +99 -0
  18. package/skills/angular/references/dados.md +251 -0
  19. package/skills/angular/references/estrutura.md +279 -0
  20. package/skills/angular/references/features.md +219 -0
  21. package/skills/angular/references/testes-build.md +257 -0
  22. package/skills/angular/scripts/checar.mjs +182 -0
  23. package/skills/angular/scripts/nucleo.mjs +227 -0
  24. package/skills/apollo/SKILL.md +226 -0
  25. package/skills/apollo/references/armadilhas.md +99 -0
  26. package/skills/apollo/references/envelope-erros.md +120 -0
  27. package/skills/apollo/references/estrutura-bootstrap.md +310 -0
  28. package/skills/apollo/references/schema-resolvers.md +183 -0
  29. package/skills/apollo/references/subscriptions.md +224 -0
  30. package/skills/apollo/references/testes-build.md +181 -0
  31. package/skills/apollo/scripts/checar.mjs +160 -0
  32. package/skills/apollo/scripts/nucleo.mjs +227 -0
  33. package/skills/docker/SKILL.md +102 -0
  34. package/skills/docker/references/modelos.md +251 -0
  35. package/skills/docker/references/porques.md +286 -0
  36. package/skills/documentacao/SKILL.md +146 -0
  37. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  38. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  39. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  40. package/skills/documentacao/references/modelo-readme.md +75 -0
  41. package/skills/documentacao/scripts/checar.mjs +454 -0
  42. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  43. package/skills/express/SKILL.md +156 -0
  44. package/skills/express/references/dados.md +180 -0
  45. package/skills/express/references/estrutura.md +157 -0
  46. package/skills/express/references/middlewares.md +227 -0
  47. package/skills/express/references/rotas-erros.md +286 -0
  48. package/skills/express/references/testes-deploy.md +154 -0
  49. package/skills/express/scripts/checar.mjs +115 -0
  50. package/skills/express/scripts/nucleo.mjs +227 -0
  51. package/skills/fastapi/SKILL.md +132 -0
  52. package/skills/fastapi/references/banco.md +197 -0
  53. package/skills/fastapi/references/estrutura.md +325 -0
  54. package/skills/fastapi/references/integracoes.md +145 -0
  55. package/skills/fastapi/references/rotas-erros.md +140 -0
  56. package/skills/fastapi/references/testes-deploy.md +190 -0
  57. package/skills/fastapi/scripts/checar.mjs +108 -0
  58. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  59. package/skills/hefesto/SKILL.md +119 -0
  60. package/skills/hefesto/references/conceitos.md +131 -0
  61. package/skills/hefesto/references/diagnostico.md +70 -0
  62. package/skills/hefesto/references/fluxo.md +122 -0
  63. package/skills/hefesto/references/preparar-app.md +105 -0
  64. package/skills/orfeu/SKILL.md +162 -0
  65. package/skills/orfeu/references/angular-api.md +201 -0
  66. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  67. package/skills/orfeu/references/angular-recipes.md +474 -0
  68. package/skills/orfeu/references/angular.md +212 -0
  69. package/skills/orfeu/references/diferencas.md +56 -0
  70. package/skills/orfeu/references/node-api.md +354 -0
  71. package/skills/orfeu/references/node-armadilhas.md +158 -0
  72. package/skills/orfeu/references/node-recipes.md +541 -0
  73. package/skills/orfeu/references/node.md +204 -0
  74. package/skills/orfeu/references/python-api.md +346 -0
  75. package/skills/orfeu/references/python-recipes.md +479 -0
  76. package/skills/orfeu/references/python.md +240 -0
  77. package/skills/orfeu/scripts/checar.mjs +126 -0
  78. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  79. package/skills/trismegisto/SKILL.md +194 -0
  80. package/skills/trismegisto/references/angular-api.md +2788 -0
  81. package/skills/trismegisto/references/angular-exports.md +4020 -0
  82. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  83. package/skills/trismegisto/references/angular-types.md +492 -0
  84. package/skills/trismegisto/references/angular.md +390 -0
  85. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  86. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  87. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  88. package/skills/trismegisto/references/spine-api.md +1530 -0
  89. package/skills/trismegisto/references/spine-recipes.md +581 -0
  90. package/skills/trismegisto/references/spine.md +343 -0
  91. package/skills/trismegisto/scripts/checar.mjs +216 -0
  92. package/skills/trismegisto/scripts/nucleo.mjs +227 -0
@@ -0,0 +1,197 @@
1
+ # Banco de dados
2
+
3
+ ## Stack real
4
+
5
+ - **Postgres apenas.** O ramo MSSQL (`mssql+pyodbc`, ODBC driver na imagem) foi removido de todos os
6
+ serviços; não reintroduza sem consumidor real.
7
+ - **SQLAlchemy 2.x síncrono** + **`psycopg2-binary`** (`postgresql+psycopg2`). Sem asyncpg, sem ORM async.
8
+ - **Sem Alembic e sem `create_all` em produção**: o schema vive em scripts SQL numa pasta `database/`
9
+ irmã do serviço (abaixo). `create_all` só nos testes (SQLite).
10
+ - Um *schema* Postgres por área do projeto (`deploy`, `requests`, `catalogo`...), não `public`.
11
+
12
+ ## Engine e sessão (`core/connections/database/events.py`)
13
+
14
+ ```python
15
+ from sqlalchemy import URL, create_engine, text
16
+ from sqlalchemy.orm import sessionmaker
17
+
18
+
19
+ def connect_to_db(app, settings) -> None:
20
+ url = URL.create(
21
+ drivername="postgresql+psycopg2",
22
+ username=settings.db_user, password=settings.db_password,
23
+ host=settings.db_host, port=int(settings.db_port), database=settings.db_name,
24
+ )
25
+ engine = create_engine(
26
+ url,
27
+ pool_size=settings.min_connection_count,
28
+ max_overflow=settings.max_connection_count,
29
+ pool_timeout=30, pool_recycle=1800, pool_pre_ping=True,
30
+ )
31
+ with engine.connect() as conn: # falha cedo: o app não sobe sem banco
32
+ conn.execute(text("SELECT 1"))
33
+ app.state.db_engine = engine
34
+ app.state.SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
35
+
36
+
37
+ def close_db_connections(app) -> None:
38
+ engine = getattr(app.state, "db_engine", None)
39
+ if engine:
40
+ engine.dispose()
41
+ ```
42
+
43
+ - Use `URL.create(...)` — nunca monte a URL por f-string (senha com `@`/`:` quebra).
44
+ - Atenção ao nome: `max_overflow` é o **excedente** sobre `pool_size`, não o máximo total.
45
+
46
+ Dependência por requisição (`app/shared/dependencies.py`):
47
+
48
+ ```python
49
+ def get_db(request: Request) -> Generator[Session, None, None]:
50
+ SessionLocal = getattr(request.app.state, "SessionLocal", None)
51
+ if SessionLocal is None:
52
+ raise RuntimeError("Database session not initialised.")
53
+ db = SessionLocal()
54
+ try:
55
+ yield db
56
+ finally:
57
+ db.close()
58
+ ```
59
+
60
+ Vários bancos: `app.state.SessionLocal_<nome>` + fábrica `get_db_connection("<nome>")` (ver
61
+ estrutura.md). Com um banco só, mantenha `get_db`.
62
+
63
+ ## Models
64
+
65
+ ```python
66
+ # app/shared/metadata.py — uma base por schema
67
+ CATALOGO_SCHEMA = "catalogo"
68
+ catalogo_metadata = MetaData(schema=CATALOGO_SCHEMA)
69
+
70
+ class CatalogoBase(DeclarativeBase):
71
+ metadata = catalogo_metadata
72
+ ```
73
+
74
+ ```python
75
+ class Tag(CatalogoBase):
76
+ __tablename__ = "tags"
77
+ tag_id = Column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4)
78
+ name = Column(Text, nullable=False, unique=True)
79
+ created_at = Column(DateTime(timezone=True), nullable=False, server_default=func.now())
80
+ ```
81
+
82
+ - PK `UUID` chamada `<entidade>_id`; `TIMESTAMPTZ` (`DateTime(timezone=True)`); `TEXT` em vez de
83
+ `VARCHAR(n)` salvo regra real.
84
+ - O model espelha o SQL de `database/scripts/create/` — o SQL é a fonte da verdade; ao mudar um, mude o
85
+ outro.
86
+ - Desativação lógica (`active=false`) quando há FK apontando, em vez de apagar.
87
+ - Constante do schema exportada (`CATALOGO_SCHEMA`) para os testes usarem `schema_translate_map`.
88
+
89
+ ## Repositories e transações
90
+
91
+ ```python
92
+ class BaseRepository:
93
+ def __init__(self, db_session: Session):
94
+ self.db_session = db_session
95
+ ```
96
+
97
+ Hoje os repositories fazem `commit()` a cada escrita. Funciona para CRUD de uma entidade, mas:
98
+
99
+ - **operação que escreve em várias tabelas deve ser uma transação só**: no repository use `flush()`
100
+ (gera ids/valida FK sem fechar a transação) e faça o `commit()` uma vez no service, no fim da
101
+ operação; em erro, `rollback()`.
102
+ - Depois de `IntegrityError`, chame `db.rollback()` antes de qualquer outra query na mesma sessão.
103
+ - `db.refresh(obj)` após `commit()` quando a resposta precisa de `server_default` (ex.: `created_at`).
104
+ - Estilo de query: ambos `session.query(...)` (legado) e `select(...)` funcionam em 2.x; em código novo
105
+ prefira `session.execute(select(...)).scalars()`.
106
+
107
+ ## SQL cru
108
+
109
+ Para relatórios/joins pesados, `text()` com parâmetros nomeados e `.mappings()`:
110
+
111
+ ```python
112
+ rows = self.db_session.execute(
113
+ text("SELECT id, nome FROM catalogo.itens WHERE grupo = :grupo ORDER BY nome"),
114
+ {"grupo": grupo},
115
+ ).mappings().all()
116
+ return [dict(r) for r in rows]
117
+ ```
118
+
119
+ Nunca interpole valor com f-string; só identificadores fixos do código podem ser concatenados.
120
+
121
+ ### Armadilha: `:` em `text()`
122
+
123
+ `text()` interpreta **qualquer** `:palavra` como bind param — inclusive dentro de comentários `--` e de
124
+ literais de string (`'/realms/:realm'`, `'10:30'`). Sintoma: erro de "parâmetro obrigatório" ou a
125
+ execução aborta num script que nem tem parâmetros. Soluções:
126
+
127
+ - script inteiro sem parâmetros (build do banco): `conn.execute(text(sql.replace(":", r"\:")))` — os
128
+ casts `::tipo` continuam funcionando (`\:\:` vira `::`);
129
+ - alternativa: `conn.exec_driver_sql(sql)` (não passa pelo parser do `text()`; aí `%` vira o caractere
130
+ especial do psycopg2 e precisa de `%%`);
131
+ - query com parâmetros e um `:` literal: escape só esse (`'10\:30'`) ou passe o literal como parâmetro.
132
+
133
+ ## Pasta `database/` (build do schema)
134
+
135
+ Mesma estrutura em todo app, ao lado de `angular/`, `graphql/` e `server/`. `build.py`, `tools/`, `tests/` (menos
136
+ `test_app.py`), `.gitignore`, `pytest.ini` e `requirements*.txt` são **idênticos byte a byte** entre os apps:
137
+ mudança neles vale para todos (copie para os outros e rode a suíte de cada um). O que é do app fica só em
138
+ `manifest.yml`, `env/`, `scripts/`, `tests/test_app.py` e nas seções "Schemas" e "Particularidades" do
139
+ `CLAUDE.md` da pasta. Um teste de estrutura falha se aparecer pasta ou arquivo fora do padrão.
140
+
141
+ ```
142
+ database/
143
+ manifest.yml ordem dos arquivos por fase: delete / create / insert (insert pode ser [] num app novo)
144
+ build.py scripts/ → output/build.sql; --exec aplica; --reset inclui delete; --seed só insert;
145
+ --bootstrap cria role+database (lê a senha do ambiente, nunca grava)
146
+ requirements.txt python-dotenv, PyYAML, SQLAlchemy, psycopg2-binary
147
+ env/.env(.example) POSTGRESQL_HOST/PORT/DATABASE/USER/PASSWORD (+ POSTGRESQL_SUPERUSER(_PASSWORD) do bootstrap)
148
+ scripts/
149
+ bootstrap/00-create-db.sql CREATE ROLE <app> + CREATE DATABASE <app> + REVOKE CONNECT FROM PUBLIC;
150
+ senha só por variável do psql (:'role_password'), nunca literal
151
+ delete/reset.sql DROP SCHEMA IF EXISTS <schemas> CASCADE — só com --reset (dev/homol/CI)
152
+ create/<schema>/NN-*.sql forma FINAL das tabelas (CREATE TABLE sem IF NOT EXISTS)
153
+ insert/<schema>/<tabela>.sql seed idempotente, um arquivo por tabela
154
+ migrations/NNN-descricao.sql histórico de ALTER aplicado manualmente (subpasta = DDL de outro banco)
155
+ output/build.sql gerado e versionado (um teste confere que está em dia); não editar
156
+ tools/ sync_from_db.py (regera insert/ de um banco) e compare_db.py (compara dois bancos)
157
+ tests/ pytest sem rede nem banco real; tests/pg = PGlite (Postgres em memória) para os testes de SQL
158
+ ```
159
+
160
+ App novo começa com o schema criado e sem tabela, seed nem migration: os testes compartilhados aceitam isso
161
+ (pulam as checagens que dependem de tabela/migration) e passam a valer a partir da primeira.
162
+
163
+ Uso:
164
+
165
+ ```bash
166
+ python build.py # gera output/build.sql (create + insert)
167
+ python build.py --exec # gera e aplica numa transação
168
+ python build.py --reset --exec # derruba o schema e recria do zero (nunca em banco com dado)
169
+ python build.py --seed --exec # só a fase insert, em banco existente
170
+ ```
171
+
172
+ Regras:
173
+
174
+ - `create/` sem `IF NOT EXISTS` (exceto `CREATE SCHEMA`): rodar duas vezes sem `--reset` falha de
175
+ propósito — impede aplicar create em banco vivo por engano.
176
+ - **Toda mudança de schema em produção = duas coisas**: editar `create/` para a forma final **e** escrever
177
+ `scripts/migrations/NNN-*.sql` com o `ALTER` real (cabeçalho com data, dependência e aviso se destrutivo; tudo
178
+ numa transação). `build.py` não aplica migrations.
179
+ - Seed: `ON CONFLICT ... DO NOTHING` para dado que a UI edita (não sobrescreve); `ON CONFLICT (pk) DO
180
+ UPDATE` com UUID literal para dado de referência controlado pelo código. Conflito sempre na PK ou numa
181
+ chave estável, nunca num nome que o usuário pode renomear.
182
+ - Nunca coloque segredo no seed (variáveis por app, tokens) nem histórico de execução.
183
+ - `build.py` recomendado (o mais completo entre os serviços): escreve com
184
+ `write_text(sql, encoding="utf-8", newline="")` (evita CRLF no Windows dentro de literais), captura
185
+ `DBAPIError` e mostra código, detalhe, dica e **o arquivo de origem** da linha que falhou (cada
186
+ arquivo é precedido por `-- scripts/<fase>/<arquivo>` no build.sql), e oferece `--seed`.
187
+ - Validar um seed: aplique o `build.sql` num Postgres descartável (container) e compare com o banco
188
+ real usando uma ferramenta só-leitura que imprime nomes/contagens, nunca valores.
189
+
190
+ Divergências observadas:
191
+
192
+ | Tema | Visto | Recomendado |
193
+ |---|---|---|
194
+ | Migrations | fora de `database/` ou misturando SQL e script Python | `database/scripts/migrations/NNN-*.sql`; scripts de dados pontuais em `database/tools/` |
195
+ | `build.py` | versões com e sem `--seed`, relatório de erro e `newline=""` | a versão completa acima |
196
+ | Seed | `DO NOTHING` por nome vs `DO UPDATE` por PK literal | regra da lista acima |
197
+ | Commit | no repository (todos) | `flush` no repository, `commit` no service quando a operação tem várias escritas |
@@ -0,0 +1,325 @@
1
+ # Estrutura do serviço FastAPI
2
+
3
+ ## Árvore recomendada
4
+
5
+ ```
6
+ <projeto>/
7
+ server/ serviço FastAPI (o nome da pasta varia; prefira `server/`)
8
+ Dockerfile
9
+ .dockerignore
10
+ .env.example só NOMES das variáveis
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
14
+ pytest.ini testpaths = tests · pythonpath = src
15
+ src/
16
+ main.py get_application() + `app = get_application()`
17
+ .env NÃO versionado: só APP_ENV=<local|dev|homol|prod>
18
+ settings/
19
+ __init__.py reexporta AppSettings
20
+ settings.py AppSettings (pydantic-settings) + carga dos .env
21
+ environment/.env.<APP_ENV> NÃO versionados; environment/.env.example (só nomes) versionado
22
+ core/
23
+ config.py get_app_settings() com @lru_cache
24
+ connections/
25
+ database/events.py connect_to_db / close_db_connections
26
+ redis/events.py connect_to_redis / close_redis_connection (se houver Redis)
27
+ app/
28
+ __init__.py APIRouter raiz: um include_router por domínio + /health
29
+ domains/
30
+ __init__.py docstring com a convenção das camadas
31
+ <domínio>/
32
+ router.py HTTP: rotas, @operation, DTO → service → ok(...)
33
+ schemas.py Pydantic: *Create / *Update (ou *In / *Patch) e *Out
34
+ service.py regra de negócio; levanta erros do orfeu; não conhece HTTP
35
+ repository.py acesso a dados (SQLAlchemy), sem regra
36
+ models.py tabelas ORM
37
+ access.py (opcional) quem pode ver/operar o quê, a partir das claims
38
+ shared/
39
+ dependencies.py get_db, get_redis
40
+ metadata.py DeclarativeBase por schema do Postgres
41
+ repository.py BaseRepository(db_session)
42
+ schemas.py (opcional) CamelModel
43
+ clients/ clientes HTTP de outros serviços (um arquivo por serviço)
44
+ tests/
45
+ conftest.py
46
+ test_<domínio>.py
47
+ database/ build do schema (ver banco.md)
48
+ ```
49
+
50
+ Módulos extras de um domínio (validadores, agregações, handlers) ficam dentro da pasta do domínio, não
51
+ em `shared/`. `shared/` é só o que mais de um domínio usa.
52
+
53
+ ## Responsabilidade das camadas
54
+
55
+ | Camada | Pode | Não pode |
56
+ |---|---|---|
57
+ | `router.py` | declarar rota/`@operation`, receber DTO, montar o service (via `Depends`), devolver `ok(...)` | regra de negócio, query |
58
+ | `service.py` | regra, orquestração, chamar outros services e clientes HTTP, `raise NotFound/Conflict/...` | importar `fastapi`/`HTTPException`, montar resposta |
59
+ | `repository.py` | query/insert/update/delete numa entidade, `commit` | decidir regra, levantar erro HTTP |
60
+ | `models.py` | colunas, PK, defaults | lógica |
61
+
62
+ Um domínio que precisa de outro chama o **service** do outro (`TagService(db).get(...)`), nunca o
63
+ repository dele.
64
+
65
+ Quando o service precisa do usuário (claims) ou de algo do `app.state`, crie uma fábrica no router:
66
+
67
+ ```python
68
+ def catalog_service(request: Request, db: Session = Depends(get_db)) -> CatalogService:
69
+ return CatalogService(db, getattr(request.state, "user", None))
70
+ ```
71
+
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)`.
77
+
78
+ ## `main.py`
79
+
80
+ ```python
81
+ from contextlib import asynccontextmanager
82
+
83
+ from fastapi import Depends, FastAPI
84
+ from fastapi.security import APIKeyHeader
85
+ from orfeu.adapters.fastapi import Orfeu, install_envelope
86
+ from starlette.middleware.cors import CORSMiddleware
87
+
88
+ from app import router as api_router
89
+ from core.config import get_app_settings
90
+ from core.connections.database.events import close_db_connections, connect_to_db
91
+
92
+ settings = get_app_settings()
93
+
94
+ # Só documentação: o botão "Authorize" do /docs mostra os headers aceitos pelo Orfeu.
95
+ # auto_error=False — quem valida é o middleware do Orfeu; isto nunca bloqueia.
96
+ _access = APIKeyHeader(name="x-access-token", scheme_name="x-access-token", auto_error=False)
97
+ _api = APIKeyHeader(name="x-api-token", scheme_name="x-api-token", auto_error=False)
98
+ _app = APIKeyHeader(name="x-app-token", scheme_name="x-app-token", auto_error=False)
99
+
100
+
101
+ def get_application() -> FastAPI:
102
+ settings.configure_logging()
103
+
104
+ @asynccontextmanager
105
+ async def lifespan(application: FastAPI):
106
+ connect_to_db(application, settings)
107
+ try:
108
+ yield
109
+ finally: # shutdown roda também se o lifespan for cancelado
110
+ close_db_connections(application)
111
+
112
+ application = FastAPI(
113
+ **settings.fastapi_kwargs,
114
+ lifespan=lifespan,
115
+ dependencies=[Depends(_access), Depends(_api), Depends(_app)],
116
+ )
117
+
118
+ # Embrulha o lifespan: bootstrap/sync das operações antes, flush da auditoria depois.
119
+ orfeu = Orfeu(
120
+ app=application,
121
+ authorizer_url=settings.authorizer_url,
122
+ realm_id=settings.realm_id,
123
+ app_id=settings.app_id,
124
+ secret=settings.app_secret,
125
+ tls_verify=settings.authorizer_tls_verify,
126
+ )
127
+ application.state.orfeu_client = orfeu.client # só se algum service checar permissão fora do @operation
128
+
129
+ application.add_middleware(
130
+ CORSMiddleware,
131
+ allow_origins=settings.allowed_hosts,
132
+ allow_credentials=True,
133
+ allow_methods=["*"],
134
+ allow_headers=["*"],
135
+ )
136
+ install_envelope(application)
137
+ application.include_router(api_router, prefix=settings.api_prefix)
138
+ return application
139
+
140
+
141
+ app = get_application()
142
+
143
+ if __name__ == "__main__":
144
+ import uvicorn
145
+ uvicorn.run("main:app", host="0.0.0.0", port=settings.port, reload=True)
146
+ ```
147
+
148
+ Pontos de atenção:
149
+
150
+ - **Use `try/finally` no lifespan** (nem todo serviço fazia): sem ele, um cancelamento pula o shutdown e
151
+ deixa pool/tarefas abertos.
152
+ - Tarefas longas iniciadas no lifespan (`asyncio.create_task(...)`) devem ser canceladas no shutdown e
153
+ aguardadas com `suppress(asyncio.CancelledError)`.
154
+ - Middlewares adicionados por último ficam mais externos. Middleware de trace/tempo que deve envolver
155
+ tudo é adicionado depois do CORS.
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):
160
+
161
+ ```python
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()
175
+ if not settings.authorizer_tls_verify:
176
+ logger.warning("AUTHORIZER_TLS_VERIFY=false: o certificado do Argos NÃO é verificado (inclusive o JWKS).")
177
+ ```
178
+
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.
182
+
183
+ ## Roteador raiz (`app/__init__.py`)
184
+
185
+ ```python
186
+ from fastapi import APIRouter
187
+ from orfeu import ok
188
+
189
+ from app.domains.tags.router import router as tags_router
190
+
191
+ router = APIRouter()
192
+ router.include_router(tags_router) # cada router de domínio tem o próprio prefix
193
+
194
+
195
+ @router.get("/health")
196
+ def health():
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")
200
+ ```
201
+
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.
204
+
205
+ ## Settings e variáveis de ambiente
206
+
207
+ Padrão (o mais consistente entre os serviços):
208
+
209
+ ```python
210
+ def _load_env_file() -> None:
211
+ root_env = Path(__file__).resolve().parent.parent / ".env" # src/.env → só APP_ENV
212
+ if root_env.exists():
213
+ load_dotenv(root_env, override=False)
214
+ app_env = os.getenv("APP_ENV", "local")
215
+ path = Path(__file__).resolve().parent / "environment" / f".env.{AppEnvTypes(app_env).value}"
216
+ if path.exists():
217
+ load_dotenv(path, override=False) # variáveis do processo (shell, compose) vencem o arquivo
218
+
219
+ _load_env_file()
220
+
221
+
222
+ class AppSettings(BaseSettings):
223
+ app_env: AppEnvTypes = AppEnvTypes.local
224
+ debug: bool = False
225
+ ...
226
+ @property
227
+ def fastapi_kwargs(self) -> dict: ...
228
+ def configure_logging(self) -> None: ...
229
+ ```
230
+
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.
233
+ - `get_app_settings()` com `@lru_cache` em `core/config.py`; nunca instancie `AppSettings()` solto.
234
+ - **Declare todo campo usado.** Depender de `extra="allow"` para ler, por exemplo, a porta faz o código
235
+ funcionar só enquanto a variável existir no ambiente, sem default nem validação.
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:
240
+
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
+
248
+ @property
249
+ def fastapi_kwargs(self) -> dict:
250
+ docs = self.docs_enabled
251
+ return {
252
+ "debug": self.debug,
253
+ "title": "meu-servico",
254
+ "docs_url": f"{self.api_prefix}/docs" if docs else None,
255
+ "openapi_url": f"{self.api_prefix}/openapi.json" if docs else None,
256
+ "redoc_url": f"{self.api_prefix}/redoc" if docs else None,
257
+ }
258
+ ```
259
+
260
+ Teste parametrizado (`tests/test_api_docs.py`): `local` ligado; `dev`/`homol`/`prod` desligados (`None`);
261
+ `API_DOCS` força nos dois sentidos.
262
+
263
+ Nomes de variáveis usados (sem valores):
264
+
265
+ | Grupo | Variáveis |
266
+ |---|---|
267
+ | Ambiente | `APP_ENV`, `DEBUG`, `PORT`, `API_PREFIX`, `ALLOWED_HOSTS`, `API_DOCS` |
268
+ | Orfeu/Argos | `AUTHORIZER_URL`, `REALM_ID`, `APP_ID`, `APP_SECRET`, `AUTHORIZER_TLS_VERIFY`, `ARGOS_ADMIN_SERVER_URL` (se chamar o admin do Argos) |
269
+ | Postgres | `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `MIN_CONNECTION_COUNT`, `MAX_CONNECTION_COUNT` |
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 |
271
+ | Processo | `APP_ROLE` (`all`/`api`/`collector`) quando há collectors — ver integracoes.md |
272
+
273
+ Serviço com **vários bancos** usa o padrão de prefixo: `DB_ENTRIES=<nome1>,<nome2>` e, para cada nome,
274
+ `<NOME>_TYPE/_HOST/_PORT/_USER/_PASSWORD/_DATABASE`; a sessão fica em `app.state.SessionLocal_<nome>` e a
275
+ dependência é a fábrica `get_db_connection("<nome>")`. Use só quando houver mais de um banco de fato;
276
+ com um banco, `DB_*` + `get_db`.
277
+
278
+ ## Dependências
279
+
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.
283
+
284
+ ```
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)
297
+ ```
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
+
318
+ Divergências observadas e recomendação:
319
+
320
+ | Tema | Visto | Recomendado |
321
+ |---|---|---|
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` |
323
+ | Python | 3.11 na imagem; local rodando 3.14 | piso 3.11; teste local na mesma menor da imagem quando possível |
324
+ | Pasta | `server/` (2) vs `fastapi/` (1) | `server/` |
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 |
@@ -0,0 +1,145 @@
1
+ # Outros serviços, Redis, segundo plano e logs
2
+
3
+ ## Chamar outro serviço
4
+
5
+ Duas situações, dois jeitos (API detalhada de `orfeu_headers` na **orfeu**):
6
+
7
+ 1. **Em nome do usuário da requisição** (o outro serviço também é guardado pelo Orfeu): repasse o
8
+ contexto com `orfeu_headers(request)` — leva `traceparent`, ids de rota/cliente e a credencial de
9
+ usuário; nunca o `x-api-token` recebido.
10
+
11
+ ```python
12
+ from orfeu.adapters.fastapi import orfeu_headers
13
+
14
+ async def get_form(self, request: Request, form_id: str) -> dict:
15
+ r = await self._http.get(f"/forms/{form_id}", headers=orfeu_headers(request))
16
+ ...
17
+ ```
18
+
19
+ Como o service não deve conhecer `Request`, o router pode passar `orfeu_headers(request)` pronto
20
+ para o service (um `dict`).
21
+
22
+ 2. **Como o próprio serviço** (machine-to-machine, ex.: admin do Argos para resolver usuários): token de
23
+ app obtido com `app_id` + `secret` do serviço (as mesmas credenciais do `Orfeu(...)`), cacheado até
24
+ perto de expirar, enviado em `x-access-token`. Ou, para outro backend Orfeu,
25
+ `{**orfeu_headers(request, credential=False), "x-api-token": <token do serviço>}`.
26
+
27
+ ### Padrão do cliente (`app/shared/clients/<servico>.py`)
28
+
29
+ ```python
30
+ class OutroServicoError(Exception):
31
+ def __init__(self, status_code: int, detail: str):
32
+ self.status_code, self.detail = status_code, detail
33
+ super().__init__(detail)
34
+
35
+
36
+ class OutroServicoClient:
37
+ def __init__(self, base_url: str, timeout: float = 10.0, tls_verify: bool = True):
38
+ self._base_url = base_url.rstrip("/")
39
+ self._timeout = timeout
40
+ self._tls_verify = tls_verify
41
+ self._client: httpx.AsyncClient | None = None
42
+
43
+ def _http(self) -> httpx.AsyncClient:
44
+ # Um cliente com keep-alive: abrir um AsyncClient por chamada paga TCP+TLS toda vez.
45
+ if self._client is None or self._client.is_closed:
46
+ self._client = httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout, verify=self._tls_verify)
47
+ return self._client
48
+
49
+ async def get(self, path: str, headers: dict, params: dict | None = None):
50
+ try:
51
+ resp = await self._http().get(path, headers=headers, params=params)
52
+ except httpx.RequestError as exc:
53
+ raise OutroServicoError(503, f"Falha ao conectar: {exc}")
54
+ if resp.status_code >= 400:
55
+ raise OutroServicoError(resp.status_code, "Falha ao consultar o serviço")
56
+ return resp.json()
57
+
58
+
59
+ @lru_cache
60
+ def get_outro_servico_client() -> OutroServicoClient:
61
+ s = get_app_settings()
62
+ return OutroServicoClient(s.outro_servico_url, tls_verify=s.outro_servico_tls_verify)
63
+ ```
64
+
65
+ - **Singleton** (`@lru_cache`) para reaproveitar conexão e cache de token. (Um serviço abria um
66
+ `AsyncClient` por chamada — evite.) Feche o cliente no shutdown do lifespan se ele for criado lá.
67
+ - Sempre `timeout`. Falha de rede → 503; o service traduz o erro do cliente para `Unavailable("...")`.
68
+ - Resposta de outro serviço Acrópole vem no envelope: leia `["data"]` e use `["message"]` no erro.
69
+ - Cliente síncrono (`requests`, SDK de terceiros) dentro de rota `async def` → `run_in_threadpool`.
70
+ - `*_TLS_VERIFY` por destino, default `True`; `False` só por configuração de ambiente com CA própria.
71
+ - Propagação de trace em bibliotecas de terceiros (ex.: `requests`): instrumente uma vez no `main.py`
72
+ (um hook que injeta `traceparent` em toda chamada de saída), em vez de reescrever cada chamada.
73
+
74
+ ## `async def` × `def`
75
+
76
+ | A rota… | Use |
77
+ |---|---|
78
+ | só usa a sessão SQLAlchemy/Redis síncronos | `def` (FastAPI roda no threadpool) |
79
+ | faz `await` (httpx, cliente async) | `async def`; trabalho bloqueante no meio vai para `await run_in_threadpool(f, ...)` |
80
+ | mistura muito I/O bloqueante e um `await` | `async def` + `run_in_threadpool` para cada bloco bloqueante |
81
+
82
+ `async def` chamando `session.query(...)` direto bloqueia o event loop para **todas** as requisições
83
+ (padrão encontrado num serviço inteiro; o outro usa `def` — siga o segundo).
84
+
85
+ ## Redis
86
+
87
+ ```python
88
+ pool = redis.ConnectionPool(
89
+ host=s.redis_host, port=int(s.redis_port), password=s.redis_password, db=int(s.redis_db),
90
+ decode_responses=True,
91
+ socket_connect_timeout=..., socket_timeout=...,
92
+ health_check_interval=30, # testa conexão ociosa antes de reusar
93
+ retry_on_timeout=True,
94
+ )
95
+ app.state.redis = redis.Redis(connection_pool=pool)
96
+ ```
97
+
98
+ - Dependência `get_redis(request)` em `shared/dependencies.py` (um serviço usa `app.state.redis`, outro
99
+ `app.state.redis_client` — escolha `redis`).
100
+ - Instância compartilhada entre projetos → **prefixo de chave/canal** por projeto, configurável.
101
+ - Pub/sub para avisar o gateway (subscriptions GraphQL, ver apollo) é *melhor esforço*: falha do
102
+ Redis não deve quebrar a escrita no banco.
103
+
104
+ ## Tarefas em segundo plano
105
+
106
+ | Necessidade | Ferramenta |
107
+ |---|---|
108
+ | Algo curto depois de responder (refresh de cache, notificação) | `BackgroundTasks.add_task(f, ...)` na rota |
109
+ | Ciclo contínuo enquanto o app vive (coletor, monitor) | `asyncio.create_task(...)` no lifespan, cancelado no shutdown |
110
+ | Trabalho pesado de CPU ou que deve rodar em 1 instância só | processo separado (`APP_ROLE`) |
111
+
112
+ Regras:
113
+
114
+ - **Abra uma sessão própria**: a da requisição já foi fechada quando a tarefa roda.
115
+ Passe `request.app.state.SessionLocal` e faça `db = factory(); try: ... finally: db.close()`.
116
+ - Envolva tudo em `try/except Exception: logger.exception(...)` — a tarefa não pode estourar sem log.
117
+ - Evite rajadas: flag “rodando” + TTL mínimo entre execuções (e conte a tentativa mesmo se falhar).
118
+ - Auditoria (`annotate_operation`) só no fluxo do handler, nunca na tarefa (orfeu).
119
+ - Ciclo que só interessa quando há alguém olhando: rode sob demanda (contador de espectadores) em vez
120
+ de coletar o tempo todo.
121
+
122
+ ### Collectors e `APP_ROLE`
123
+
124
+ Quando há coleta pesada de CPU, ela disputa o GIL com a API. Padrão:
125
+
126
+ - `APP_ROLE=all` (default: API + coletores no mesmo processo), `api` (só HTTP, pode ter várias
127
+ réplicas/workers) e `collector` (sem HTTP, entrada própria `python src/collector_main.py`, **exatamente
128
+ uma** instância).
129
+ - `main.py` recusa subir com `APP_ROLE=collector` (lançaria um HTTP à toa).
130
+ - `--workers > 1` só com `APP_ROLE=api`; com `all`, cada worker sobe seus coletores (coleta duplicada).
131
+ - Trava distribuída no Redis por ciclo (`SET NX EX` com token, liberação/renovação via Lua só pelo dono,
132
+ TTL curto) para que dois processos nunca rodem o mesmo ciclo.
133
+
134
+ ## Logs
135
+
136
+ - O Orfeu loga pela `logging` padrão (`orfeu.operation`, uma linha por chamada guardada, com
137
+ `trace_id`, operação, usuário, duração). Formato JSON: orfeu.
138
+ - Os serviços usam `loguru` para os próprios logs e divergem na integração: dois só chamam
139
+ `logging.basicConfig(...)` (dois formatos no mesmo stdout); um redireciona a `logging` padrão para o
140
+ loguru com um `InterceptHandler`. **Recomendado: uma saída só** — ou `logging` padrão em todo o
141
+ código, ou o `InterceptHandler` para o loguru, configurado em `settings.configure_logging()` antes de
142
+ criar o app.
143
+ - `DEBUG` controla o nível. Nunca logue segredo, token, senha nem corpo de requisição com dado pessoal;
144
+ ao logar URL de conexão, use só host/banco.
145
+ - `logger.exception(...)` em `except` (leva a stack); `install_envelope` já loga o 500 inesperado.