@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.
Files changed (90) hide show
  1. package/README.md +180 -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 +75 -0
  9. package/skills/acropole/references/fluxos/doctor.md +55 -0
  10. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  11. package/skills/acropole/references/fluxos/revisar.md +56 -0
  12. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  13. package/skills/acropole/scripts/doctor.mjs +439 -0
  14. package/skills/angular/SKILL.md +152 -0
  15. package/skills/angular/references/armadilhas.md +95 -0
  16. package/skills/angular/references/dados.md +251 -0
  17. package/skills/angular/references/estrutura.md +260 -0
  18. package/skills/angular/references/features.md +219 -0
  19. package/skills/angular/references/testes-build.md +230 -0
  20. package/skills/angular/scripts/checar.mjs +182 -0
  21. package/skills/angular/scripts/nucleo.mjs +227 -0
  22. package/skills/apollo/SKILL.md +222 -0
  23. package/skills/apollo/references/armadilhas.md +95 -0
  24. package/skills/apollo/references/envelope-erros.md +120 -0
  25. package/skills/apollo/references/estrutura-bootstrap.md +299 -0
  26. package/skills/apollo/references/schema-resolvers.md +183 -0
  27. package/skills/apollo/references/subscriptions.md +224 -0
  28. package/skills/apollo/references/testes-build.md +180 -0
  29. package/skills/apollo/scripts/checar.mjs +160 -0
  30. package/skills/apollo/scripts/nucleo.mjs +227 -0
  31. package/skills/docker/SKILL.md +102 -0
  32. package/skills/docker/references/modelos.md +251 -0
  33. package/skills/docker/references/porques.md +282 -0
  34. package/skills/documentacao/SKILL.md +146 -0
  35. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  36. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  37. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  38. package/skills/documentacao/references/modelo-readme.md +75 -0
  39. package/skills/documentacao/scripts/checar.mjs +454 -0
  40. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  41. package/skills/express/SKILL.md +154 -0
  42. package/skills/express/references/dados.md +180 -0
  43. package/skills/express/references/estrutura.md +154 -0
  44. package/skills/express/references/middlewares.md +227 -0
  45. package/skills/express/references/rotas-erros.md +274 -0
  46. package/skills/express/references/testes-deploy.md +150 -0
  47. package/skills/express/scripts/checar.mjs +115 -0
  48. package/skills/express/scripts/nucleo.mjs +227 -0
  49. package/skills/fastapi/SKILL.md +129 -0
  50. package/skills/fastapi/references/banco.md +185 -0
  51. package/skills/fastapi/references/estrutura.md +281 -0
  52. package/skills/fastapi/references/integracoes.md +145 -0
  53. package/skills/fastapi/references/rotas-erros.md +140 -0
  54. package/skills/fastapi/references/testes-deploy.md +190 -0
  55. package/skills/fastapi/scripts/checar.mjs +108 -0
  56. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  57. package/skills/hefesto/SKILL.md +119 -0
  58. package/skills/hefesto/references/conceitos.md +131 -0
  59. package/skills/hefesto/references/diagnostico.md +70 -0
  60. package/skills/hefesto/references/fluxo.md +122 -0
  61. package/skills/hefesto/references/preparar-app.md +105 -0
  62. package/skills/orfeu/SKILL.md +162 -0
  63. package/skills/orfeu/references/angular-api.md +201 -0
  64. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  65. package/skills/orfeu/references/angular-recipes.md +474 -0
  66. package/skills/orfeu/references/angular.md +212 -0
  67. package/skills/orfeu/references/diferencas.md +56 -0
  68. package/skills/orfeu/references/node-api.md +348 -0
  69. package/skills/orfeu/references/node-armadilhas.md +158 -0
  70. package/skills/orfeu/references/node-recipes.md +534 -0
  71. package/skills/orfeu/references/node.md +204 -0
  72. package/skills/orfeu/references/python-api.md +346 -0
  73. package/skills/orfeu/references/python-recipes.md +479 -0
  74. package/skills/orfeu/references/python.md +234 -0
  75. package/skills/orfeu/scripts/checar.mjs +126 -0
  76. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  77. package/skills/trismegisto/SKILL.md +194 -0
  78. package/skills/trismegisto/references/angular-api.md +2788 -0
  79. package/skills/trismegisto/references/angular-exports.md +4020 -0
  80. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  81. package/skills/trismegisto/references/angular-types.md +492 -0
  82. package/skills/trismegisto/references/angular.md +390 -0
  83. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  84. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  85. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  86. package/skills/trismegisto/references/spine-api.md +1530 -0
  87. package/skills/trismegisto/references/spine-recipes.md +581 -0
  88. package/skills/trismegisto/references/spine.md +343 -0
  89. package/skills/trismegisto/scripts/checar.mjs +216 -0
  90. 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.