@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,185 @@
|
|
|
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
|
+
```
|
|
136
|
+
database/
|
|
137
|
+
manifest.yml ordem dos arquivos por fase: delete / create / insert
|
|
138
|
+
build.py scripts/ → output/build.sql; --exec aplica; --reset inclui delete; --seed só insert
|
|
139
|
+
requirements.txt python-dotenv, PyYAML, SQLAlchemy, psycopg2-binary
|
|
140
|
+
env/.env(.example) POSTGRESQL_HOST, POSTGRESQL_PORT, POSTGRESQL_USER, POSTGRESQL_PASSWORD, POSTGRESQL_DATABASE
|
|
141
|
+
scripts/
|
|
142
|
+
bootstrap/ CREATE DATABASE/ROLE — manual, uma vez, fora do build (não roda em transação)
|
|
143
|
+
delete/ DROP SCHEMA ... CASCADE — só com --reset (dev/homol/CI)
|
|
144
|
+
create/<schema>/NN-*.sql forma FINAL das tabelas (CREATE TABLE sem IF NOT EXISTS)
|
|
145
|
+
insert/<schema>/*.sql seed idempotente
|
|
146
|
+
migrations/NNN-descricao.sql histórico de ALTER aplicado manualmente em banco existente
|
|
147
|
+
output/build.sql gerado; não editar
|
|
148
|
+
tools/ (opcional) comparação de bancos, só leitura
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Uso:
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
python build.py # gera output/build.sql (create + insert)
|
|
155
|
+
python build.py --exec # gera e aplica numa transação
|
|
156
|
+
python build.py --reset --exec # derruba o schema e recria do zero (nunca em banco com dado)
|
|
157
|
+
python build.py --seed --exec # só a fase insert, em banco existente
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Regras:
|
|
161
|
+
|
|
162
|
+
- `create/` sem `IF NOT EXISTS` (exceto `CREATE SCHEMA`): rodar duas vezes sem `--reset` falha de
|
|
163
|
+
propósito — impede aplicar create em banco vivo por engano.
|
|
164
|
+
- **Toda mudança de schema em produção = duas coisas**: editar `create/` para a forma final **e** escrever
|
|
165
|
+
`migrations/NNN-*.sql` com o `ALTER` real (cabeçalho com data, dependência e aviso se destrutivo; tudo
|
|
166
|
+
numa transação). `build.py` não aplica migrations.
|
|
167
|
+
- Seed: `ON CONFLICT ... DO NOTHING` para dado que a UI edita (não sobrescreve); `ON CONFLICT (pk) DO
|
|
168
|
+
UPDATE` com UUID literal para dado de referência controlado pelo código. Conflito sempre na PK ou numa
|
|
169
|
+
chave estável, nunca num nome que o usuário pode renomear.
|
|
170
|
+
- Nunca coloque segredo no seed (variáveis por app, tokens) nem histórico de execução.
|
|
171
|
+
- `build.py` recomendado (o mais completo entre os serviços): escreve com
|
|
172
|
+
`write_text(sql, encoding="utf-8", newline="")` (evita CRLF no Windows dentro de literais), captura
|
|
173
|
+
`DBAPIError` e mostra código, detalhe, dica e **o arquivo de origem** da linha que falhou (cada
|
|
174
|
+
arquivo é precedido por `-- scripts/<fase>/<arquivo>` no build.sql), e oferece `--seed`.
|
|
175
|
+
- Validar um seed: aplique o `build.sql` num Postgres descartável (container) e compare com o banco
|
|
176
|
+
real usando uma ferramenta só-leitura que imprime nomes/contagens, nunca valores.
|
|
177
|
+
|
|
178
|
+
Divergências observadas:
|
|
179
|
+
|
|
180
|
+
| Tema | Visto | Recomendado |
|
|
181
|
+
|---|---|---|
|
|
182
|
+
| Migrations | em `database/migrations/` (2 serviços) vs `server/migrations/` misturando SQL e script Python (1) | `database/migrations/NNN-*.sql`; scripts de dados pontuais em `database/tools/` |
|
|
183
|
+
| `build.py` | versões com e sem `--seed`, relatório de erro e `newline=""` | a versão completa acima |
|
|
184
|
+
| Seed | `DO NOTHING` por nome vs `DO UPDATE` por PK literal | regra da lista acima |
|
|
185
|
+
| Commit | no repository (todos) | `flush` no repository, `commit` no service quando a operação tem várias escritas |
|
|
@@ -0,0 +1,281 @@
|
|
|
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 de runtime (o que a imagem instala)
|
|
12
|
+
requirements-dev.txt -r requirements.txt + pytest (+ pytest-asyncio se houver teste async)
|
|
13
|
+
pytest.ini testpaths = tests · pythonpath = src
|
|
14
|
+
src/
|
|
15
|
+
main.py get_application() + `app = get_application()`
|
|
16
|
+
.env NÃO versionado: só APP_ENV=<local|dev|homol|prod>
|
|
17
|
+
settings/
|
|
18
|
+
__init__.py reexporta AppSettings
|
|
19
|
+
settings.py AppSettings (pydantic-settings) + carga dos .env
|
|
20
|
+
environment/.env.<APP_ENV>
|
|
21
|
+
core/
|
|
22
|
+
config.py get_app_settings() com @lru_cache
|
|
23
|
+
connections/
|
|
24
|
+
database/events.py connect_to_db / close_db_connections
|
|
25
|
+
redis/events.py connect_to_redis / close_redis_connection (se houver Redis)
|
|
26
|
+
app/
|
|
27
|
+
__init__.py APIRouter raiz: um include_router por domínio + /health
|
|
28
|
+
domains/
|
|
29
|
+
__init__.py docstring com a convenção das camadas
|
|
30
|
+
<domínio>/
|
|
31
|
+
router.py HTTP: rotas, @operation, DTO → service → ok(...)
|
|
32
|
+
schemas.py Pydantic: *Create / *Update (ou *In / *Patch) e *Out
|
|
33
|
+
service.py regra de negócio; levanta erros do orfeu; não conhece HTTP
|
|
34
|
+
repository.py acesso a dados (SQLAlchemy), sem regra
|
|
35
|
+
models.py tabelas ORM
|
|
36
|
+
access.py (opcional) quem pode ver/operar o quê, a partir das claims
|
|
37
|
+
shared/
|
|
38
|
+
dependencies.py get_db, get_redis
|
|
39
|
+
metadata.py DeclarativeBase por schema do Postgres
|
|
40
|
+
repository.py BaseRepository(db_session)
|
|
41
|
+
schemas.py (opcional) CamelModel
|
|
42
|
+
clients/ clientes HTTP de outros serviços (um arquivo por serviço)
|
|
43
|
+
tests/
|
|
44
|
+
conftest.py
|
|
45
|
+
test_<domínio>.py
|
|
46
|
+
database/ build do schema (ver banco.md)
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Módulos extras de um domínio (validadores, agregações, handlers) ficam dentro da pasta do domínio, não
|
|
50
|
+
em `shared/`. `shared/` é só o que mais de um domínio usa.
|
|
51
|
+
|
|
52
|
+
## Responsabilidade das camadas
|
|
53
|
+
|
|
54
|
+
| Camada | Pode | Não pode |
|
|
55
|
+
|---|---|---|
|
|
56
|
+
| `router.py` | declarar rota/`@operation`, receber DTO, montar o service (via `Depends`), devolver `ok(...)` | regra de negócio, query |
|
|
57
|
+
| `service.py` | regra, orquestração, chamar outros services e clientes HTTP, `raise NotFound/Conflict/...` | importar `fastapi`/`HTTPException`, montar resposta |
|
|
58
|
+
| `repository.py` | query/insert/update/delete numa entidade, `commit` | decidir regra, levantar erro HTTP |
|
|
59
|
+
| `models.py` | colunas, PK, defaults | lógica |
|
|
60
|
+
|
|
61
|
+
Um domínio que precisa de outro chama o **service** do outro (`TagService(db).get(...)`), nunca o
|
|
62
|
+
repository dele.
|
|
63
|
+
|
|
64
|
+
Quando o service precisa do usuário (claims) ou de algo do `app.state`, crie uma fábrica no router:
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
def catalog_service(request: Request, db: Session = Depends(get_db)) -> CatalogService:
|
|
68
|
+
return CatalogService(db, getattr(request.state, "user", None))
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
`request.state.user` é preenchido pelo middleware do Orfeu (detalhes na orfeu).
|
|
72
|
+
|
|
73
|
+
## `main.py`
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
from contextlib import asynccontextmanager
|
|
77
|
+
|
|
78
|
+
from fastapi import Depends, FastAPI
|
|
79
|
+
from fastapi.security import APIKeyHeader
|
|
80
|
+
from orfeu.adapters.fastapi import Orfeu, install_envelope
|
|
81
|
+
from starlette.middleware.cors import CORSMiddleware
|
|
82
|
+
|
|
83
|
+
from app import router as api_router
|
|
84
|
+
from core.config import get_app_settings
|
|
85
|
+
from core.connections.database.events import close_db_connections, connect_to_db
|
|
86
|
+
|
|
87
|
+
settings = get_app_settings()
|
|
88
|
+
|
|
89
|
+
# Só documentação: o botão "Authorize" do /docs mostra os headers aceitos pelo Orfeu.
|
|
90
|
+
# auto_error=False — quem valida é o middleware do Orfeu; isto nunca bloqueia.
|
|
91
|
+
_access = APIKeyHeader(name="x-access-token", scheme_name="x-access-token", auto_error=False)
|
|
92
|
+
_api = APIKeyHeader(name="x-api-token", scheme_name="x-api-token", auto_error=False)
|
|
93
|
+
_app = APIKeyHeader(name="x-app-token", scheme_name="x-app-token", auto_error=False)
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def get_application() -> FastAPI:
|
|
97
|
+
settings.configure_logging()
|
|
98
|
+
|
|
99
|
+
@asynccontextmanager
|
|
100
|
+
async def lifespan(application: FastAPI):
|
|
101
|
+
connect_to_db(application, settings)
|
|
102
|
+
try:
|
|
103
|
+
yield
|
|
104
|
+
finally: # shutdown roda também se o lifespan for cancelado
|
|
105
|
+
close_db_connections(application)
|
|
106
|
+
|
|
107
|
+
application = FastAPI(
|
|
108
|
+
**settings.fastapi_kwargs,
|
|
109
|
+
lifespan=lifespan,
|
|
110
|
+
dependencies=[Depends(_access), Depends(_api), Depends(_app)],
|
|
111
|
+
)
|
|
112
|
+
|
|
113
|
+
# Embrulha o lifespan: bootstrap/sync das operações antes, flush da auditoria depois.
|
|
114
|
+
orfeu = Orfeu(
|
|
115
|
+
app=application,
|
|
116
|
+
authorizer_url=settings.authorizer_url,
|
|
117
|
+
realm_id=settings.realm_id,
|
|
118
|
+
app_id=settings.app_id,
|
|
119
|
+
secret=settings.app_secret,
|
|
120
|
+
tls_verify=settings.authorizer_tls_verify,
|
|
121
|
+
)
|
|
122
|
+
application.state.orfeu_client = orfeu.client # só se algum service checar permissão fora do @operation
|
|
123
|
+
|
|
124
|
+
application.add_middleware(
|
|
125
|
+
CORSMiddleware,
|
|
126
|
+
allow_origins=settings.allowed_hosts,
|
|
127
|
+
allow_credentials=True,
|
|
128
|
+
allow_methods=["*"],
|
|
129
|
+
allow_headers=["*"],
|
|
130
|
+
)
|
|
131
|
+
install_envelope(application)
|
|
132
|
+
application.include_router(api_router, prefix=settings.api_prefix)
|
|
133
|
+
return application
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
app = get_application()
|
|
137
|
+
|
|
138
|
+
if __name__ == "__main__":
|
|
139
|
+
import uvicorn
|
|
140
|
+
uvicorn.run("main:app", host="0.0.0.0", port=settings.port, reload=True)
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Pontos de atenção:
|
|
144
|
+
|
|
145
|
+
- **Use `try/finally` no lifespan** (nem todo serviço fazia): sem ele, um cancelamento pula o shutdown e
|
|
146
|
+
deixa pool/tarefas abertos.
|
|
147
|
+
- Tarefas longas iniciadas no lifespan (`asyncio.create_task(...)`) devem ser canceladas no shutdown e
|
|
148
|
+
aguardadas com `suppress(asyncio.CancelledError)`.
|
|
149
|
+
- Middlewares adicionados por último ficam mais externos. Middleware de trace/tempo que deve envolver
|
|
150
|
+
tudo é adicionado depois do CORS.
|
|
151
|
+
- Não use `urllib3.disable_warnings(...)` como “solução” de TLS; prefira configurar a CA. Se o ambiente
|
|
152
|
+
realmente exige, deixe explícito por settings (`*_TLS_VERIFY`, default `True`).
|
|
153
|
+
- **TLS do autorizador desligado só fora de produção, e com aviso.** `AUTHORIZER_TLS_VERIFY=false` em
|
|
154
|
+
`prod` é erro de configuração: o serviço recusa subir. Fora de produção, sobe com um `warning` no log
|
|
155
|
+
(quem lê o log de homologação vê que a verificação está desligada):
|
|
156
|
+
|
|
157
|
+
```python
|
|
158
|
+
# core/config.py (validação das settings)
|
|
159
|
+
@model_validator(mode="after")
|
|
160
|
+
def _tls_do_autorizador(self) -> "AppSettings":
|
|
161
|
+
if not self.authorizer_tls_verify and self.app_env == AppEnvTypes.prod:
|
|
162
|
+
raise ValueError("AUTHORIZER_TLS_VERIFY=false não é permitido em produção")
|
|
163
|
+
return self
|
|
164
|
+
|
|
165
|
+
# main.py, em get_application(), depois do configure_logging()
|
|
166
|
+
if not settings.authorizer_tls_verify:
|
|
167
|
+
logger.warning("TLS do autorizador DESLIGADO (APP_ENV=%s): aceitável só fora de produção", settings.app_env.value)
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
Vale igual para todo `*_TLS_VERIFY` de outro destino.
|
|
171
|
+
|
|
172
|
+
## Roteador raiz (`app/__init__.py`)
|
|
173
|
+
|
|
174
|
+
```python
|
|
175
|
+
from fastapi import APIRouter
|
|
176
|
+
from orfeu import ok
|
|
177
|
+
|
|
178
|
+
from app.domains.tags.router import router as tags_router
|
|
179
|
+
|
|
180
|
+
router = APIRouter()
|
|
181
|
+
router.include_router(tags_router) # cada router de domínio tem o próprio prefix
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
@router.get("/health")
|
|
185
|
+
def health():
|
|
186
|
+
return ok(message="ok")
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
`/health` sem `@operation` é público de propósito (healthcheck do orquestrador). Nem todo serviço tinha;
|
|
190
|
+
inclua sempre.
|
|
191
|
+
|
|
192
|
+
## Settings e variáveis de ambiente
|
|
193
|
+
|
|
194
|
+
Padrão (o mais consistente entre os serviços):
|
|
195
|
+
|
|
196
|
+
```python
|
|
197
|
+
def _load_env_file() -> None:
|
|
198
|
+
root_env = Path(__file__).resolve().parent.parent / ".env" # src/.env → só APP_ENV
|
|
199
|
+
if root_env.exists():
|
|
200
|
+
load_dotenv(root_env, override=False)
|
|
201
|
+
app_env = os.getenv("APP_ENV", "local")
|
|
202
|
+
path = Path(__file__).resolve().parent / "environment" / f".env.{AppEnvTypes(app_env).value}"
|
|
203
|
+
if path.exists():
|
|
204
|
+
load_dotenv(path, override=False) # variáveis do processo (shell, compose) vencem o arquivo
|
|
205
|
+
|
|
206
|
+
_load_env_file()
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
class AppSettings(BaseSettings):
|
|
210
|
+
app_env: AppEnvTypes = AppEnvTypes.local
|
|
211
|
+
debug: bool = False
|
|
212
|
+
...
|
|
213
|
+
@property
|
|
214
|
+
def fastapi_kwargs(self) -> dict: ...
|
|
215
|
+
def configure_logging(self) -> None: ...
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
- Ambientes: `local`, `dev`, `homol`, `prod` (um serviço usava também `devel`/`ti` — padronize nos quatro).
|
|
219
|
+
- `get_app_settings()` com `@lru_cache` em `core/config.py`; nunca instancie `AppSettings()` solto.
|
|
220
|
+
- **Declare todo campo usado.** Depender de `extra="allow"` para ler, por exemplo, a porta faz o código
|
|
221
|
+
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 **desliga os três em
|
|
223
|
+
produção** (`None`). O `/openapi.json` entrega o mapa inteiro da API (rotas, parâmetros, modelos) a quem
|
|
224
|
+
chegar; em produção ninguém precisa dele, e o `/docs` ainda carrega script de CDN:
|
|
225
|
+
|
|
226
|
+
```python
|
|
227
|
+
@property
|
|
228
|
+
def fastapi_kwargs(self) -> dict:
|
|
229
|
+
docs = self.app_env != AppEnvTypes.prod # /docs, /openapi.json e /redoc só fora de produção
|
|
230
|
+
return {
|
|
231
|
+
"debug": self.debug,
|
|
232
|
+
"title": "meu-servico",
|
|
233
|
+
"docs_url": f"{self.api_prefix}/docs" if docs else None,
|
|
234
|
+
"openapi_url": f"{self.api_prefix}/openapi.json" if docs else None,
|
|
235
|
+
"redoc_url": f"{self.api_prefix}/redoc" if docs else None,
|
|
236
|
+
}
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
Teste: com `APP_ENV=prod`, `GET <prefixo>/docs`, `/openapi.json` e `/redoc` respondem 404.
|
|
240
|
+
|
|
241
|
+
Nomes de variáveis usados (sem valores):
|
|
242
|
+
|
|
243
|
+
| Grupo | Variáveis |
|
|
244
|
+
|---|---|
|
|
245
|
+
| Ambiente | `APP_ENV`, `DEBUG`, `PORT`, `API_PREFIX`, `ALLOWED_HOSTS` |
|
|
246
|
+
| Orfeu/Argos | `AUTHORIZER_URL`, `REALM_ID`, `APP_ID`, `APP_SECRET`, `AUTHORIZER_TLS_VERIFY`, `ARGOS_ADMIN_SERVER_URL` (se chamar o admin do Argos) |
|
|
247
|
+
| 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) |
|
|
249
|
+
| Processo | `APP_ROLE` (`all`/`api`/`collector`) quando há collectors — ver integracoes.md |
|
|
250
|
+
|
|
251
|
+
Serviço com **vários bancos** usa o padrão de prefixo: `DB_ENTRIES=<nome1>,<nome2>` e, para cada nome,
|
|
252
|
+
`<NOME>_TYPE/_HOST/_PORT/_USER/_PASSWORD/_DATABASE`; a sessão fica em `app.state.SessionLocal_<nome>` e a
|
|
253
|
+
dependência é a fábrica `get_db_connection("<nome>")`. Use só quando houver mais de um banco de fato;
|
|
254
|
+
com um banco, `DB_*` + `get_db`.
|
|
255
|
+
|
|
256
|
+
## Dependências
|
|
257
|
+
|
|
258
|
+
`requirements.txt` mínimo:
|
|
259
|
+
|
|
260
|
+
```
|
|
261
|
+
fastapi>=0.142
|
|
262
|
+
uvicorn[standard]
|
|
263
|
+
python-dotenv
|
|
264
|
+
pydantic-settings
|
|
265
|
+
orfeu[fastapi]>=1.0,<2
|
|
266
|
+
sqlalchemy>=2
|
|
267
|
+
psycopg2-binary
|
|
268
|
+
httpx
|
|
269
|
+
loguru # se usar loguru (ver logs em integracoes.md)
|
|
270
|
+
redis # se usar Redis
|
|
271
|
+
python-multipart # se houver upload (Form/File)
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
Divergências observadas e recomendação:
|
|
275
|
+
|
|
276
|
+
| Tema | Visto | Recomendado |
|
|
277
|
+
|---|---|---|
|
|
278
|
+
| Gerenciador | `requirements.txt` solto (2 serviços) vs `requirements.txt` congelado + `pyproject.toml` Poetry (1 serviço) | **pip + requirements.txt/requirements-dev.txt**; versões de topo, travando só o que tem motivo (`orfeu`, `fastapi`). Se quiser lock, gere com `pip freeze` num arquivo à parte, não com Poetry paralelo |
|
|
279
|
+
| Python | 3.11 na imagem; local rodando 3.14 | piso 3.11; teste local na mesma menor da imagem quando possível |
|
|
280
|
+
| Pasta | `server/` (2) vs `fastapi/` (1) | `server/` |
|
|
281
|
+
| 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.
|