feat(api): foundation canon JCS — Pino+CLS+RFC9457+health+ping (Frente A)

Estabelece a fundação operacional de apps/api conforme STACK.md v2.2 e
CODING-RULES.md v2.0, substituindo o hello-world scaffolded.

- tracing.ts primeiro import (PGD-OBS-001) — stub OTel ativável por env
- EnvSchema Zod 4 com fail-fast (superRefine guarda prod) + EnvModule global
- nestjs-pino com redact LGPD (*.cpf|*.cardNumber|*.password|auth|cookie)
- main.ts hardenizado: helmet, CORS por env, compression, versionamento URI
  /api/v1, graceful shutdown
- ProblemDetailsFilter global (RFC 9457 application/problem+json), Zod -> 422
- Health endpoints /api/v1/health/{live,ready} com memory.checkHeap(350MB)
  (ready skeleton documenta K=3 LRU pool conforme PGD-OBS-003)
- WorkspaceModule via ClsModule.forRootAsync — requestId+workspaceId no CLS,
  idGenerator alinhado com pino-http para mesmo UUID em header e body
- GET /api/v1/ping retornando workspaceId+requestId (alvo de smoke test e
  futuro healthcheck do docker compose)
- ZodValidationPipe (nestjs-zod) como APP_PIPE global
- tsconfig.app.json target ES2023 (alinhado ao base)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-27 17:50:42 +00:00
parent 3a42723c71
commit 055f9f98f0
21 changed files with 1148 additions and 80 deletions

22
apps/api/src/tracing.ts Normal file
View File

@@ -0,0 +1,22 @@
// CODING-RULES.md §09 (PGD-OBS-001):
// Este arquivo DEVE ser o primeiro import de main.ts — antes do NestJS.
// OTel NodeSDK precisa fazer monkey-patch dos módulos node:http, pg, etc.
// antes que qualquer outro código os carregue.
//
// Stub ativo:
// - Quando OTEL_EXPORTER_OTLP_ENDPOINT estiver definida, inicializa SDK real
// (a ser plugado quando @opentelemetry/sdk-node entrar no canon catalog).
// - Caso contrário, no-op silencioso (dev local).
//
// Sampling alvo (prod): parentbased_traceidratio com ARG=0.1 (10% head-based).
const otlpEndpoint = process.env['OTEL_EXPORTER_OTLP_ENDPOINT'];
if (otlpEndpoint) {
// TODO(otel): plugar @opentelemetry/sdk-node + auto-instrumentations
// quando dependência entrar no catálogo. Stub atual mantém posição correta
// do import sem instalar dependência pesada em solo-founder mode.
console.warn(
'[tracing] OTEL_EXPORTER_OTLP_ENDPOINT definido mas SDK não plugado ainda — placeholder ativo.',
);
}