Merge pull request #23 from fga-eps-mds/docs/densidade-comentarios

docs: comenta a base de codigo da BFF (densidade de comentarios)

Author: GenilsonJrs

src/config/app.ts

@@ -1,3 +1,5 @@
+// Montagem da aplicacao Express: registra middlewares globais, o health check, o
+// roteador da API e, por ultimo, o 404 e o tratador central de erros.
 import cors from "cors";
 import express from "express";
 import helmet from "helmet";
@@ -13,11 +15,14 @@ import { middlewareTratamentoErros } from "@/shared/middlewares/tratamento-erros
 
 const aplicacao = express();
 
+// Cadeia de middlewares globais, na ordem em que rodam a cada requisicao:
+// log HTTP -> headers de seguranca (helmet) -> CORS -> parsing de JSON (limite 1mb).
 aplicacao.use(loggerHttp);
 aplicacao.use(helmet());
 aplicacao.use(cors(criarOpcoesCors(env.CORS_ORIGINS)));
 aplicacao.use(express.json({ limit: "1mb" }));
 
+// Endpoint de health check usado por monitoramento/infra para saber se o BFF esta no ar.
 aplicacao.get("/health", (_request, response) => {
   return response.status(200).json({
     mensagem: MENSAGENS.bffEmExecucao,
@@ -28,8 +33,10 @@ aplicacao.get("/health", (_request, response) => {
   });
 });
 
+// Todas as rotas da API ficam sob o prefixo /api/v1.
 aplicacao.use("/api/v1", apiRouter);
 
+// Qualquer rota nao reconhecida ate aqui vira um 404 padronizado.
 aplicacao.use((_request, _response, next) => {
   next(
     new ErroAplicacao({
@@ -40,6 +47,7 @@ aplicacao.use((_request, _response, next) => {
   );
 });
 
+// Tratador de erros sempre por ultimo, para capturar tudo o que veio antes.
 aplicacao.use(middlewareTratamentoErros);
 
 export { aplicacao };

src/config/cors.ts

@@ -4,21 +4,40 @@ import { MENSAGENS } from "@/shared/constants/mensagens";
 import { CodigoDeErro } from "@/shared/errors/codigos-de-erro";
 import { ErroAplicacao } from "@/shared/errors/erro-aplicacao";
 
+/**
+ * Converte a string de origens do .env em uma lista normalizada.
+ *
+ * Separa por virgula, remove espacos em volta e descarta entradas vazias.
+ *
+ * @param value String de origens separadas por virgula (ex.: "a,b,c").
+ * @returns Lista de origens limpas.
+ */
 export function parseCorsOrigins(value: string): string[] {
   return value
     .split(",")
     .map((origin) => origin.trim())
     .filter(Boolean);
 }
 
+/**
+ * Monta as opcoes do CORS a partir da lista de origens permitidas.
+ *
+ * Libera requisicoes sem origin (ex.: chamadas server-to-server e health checks)
+ * e as de origens presentes na lista; as demais sao rejeitadas com 403.
+ *
+ * @param origensPermitidas Lista de origens autorizadas.
+ * @returns Objeto de configuracao aceito pelo middleware cors.
+ */
 export function criarOpcoesCors(origensPermitidas: string[]): CorsOptions {
   return {
     origin(origin, callback) {
+      // Sem origin (ex.: chamadas server-to-server/health) ou origin na lista: libera.
       if (!origin || origensPermitidas.includes(origin)) {
         callback(null, true);
         return;
       }
 
+      // Origin nao autorizada vira erro 403 tratado pelo middleware central.
       callback(
         new ErroAplicacao({
           codigoStatus: 403,

src/config/env.ts

@@ -1,31 +1,59 @@
+// Fonte unica de configuracao do BFF: le o ambiente, valida com Zod e exporta um
+// objeto "env" tipado e seguro para o resto da aplicacao consumir.
 import dotenv from "dotenv";
 import { z } from "zod";
 
+// Carrega o .env e valida todas as variaveis de ambiente com Zod na subida do app:
+// se algo obrigatorio faltar, o processo nao inicia (falha cedo, com erro claro).
 dotenv.config();
 
 const ambienteAtual = process.env.NODE_ENV ?? "development";
 const ambienteTeste = ambienteAtual === "test";
 
+/**
+ * Cria um validador de variavel obrigatoria (presente e nao vazia).
+ *
+ * @param nome Nome da variavel, usado na mensagem de erro.
+ * @returns Schema Zod que exige uma string nao vazia.
+ */
 const obrigatoria = (nome: string) => z.string().min(1, `${nome} is required.`);
 
+/**
+ * Cria um validador obrigatorio com fallback apenas em ambiente de teste.
+ *
+ * Em testes, aplica um valor padrao para nao exigir um .env completo; fora de
+ * teste, mantem a variavel como obrigatoria.
+ *
+ * @param nome Nome da variavel, usado na mensagem de erro.
+ * @param padrao Valor padrao aplicado somente em ambiente de teste.
+ * @returns Schema Zod adequado ao ambiente atual.
+ */
 const obrigatoriaComDefaultDeTeste = (nome: string, padrao: string) =>
   ambienteTeste ? z.string().min(1).default(padrao) : obrigatoria(nome);
 
+// Schema de todas as variaveis de ambiente do BFF, com defaults e validacao de tipo.
 const envSchema = z.object({
+  // Ambiente de execucao; controla defaults de teste e nivel de log.
   NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+  // Porta HTTP do BFF (coercao de string para numero positivo).
   PORT: z.coerce.number().int().positive().default(4000),
+  // Verbosidade do logger, do mais critico (fatal) ao desligado (silent).
   LOG_LEVEL: z
     .enum(["fatal", "error", "warn", "info", "debug", "trace", "silent"])
     .default("info"),
+  // Enderecos dos servicos internos para onde o BFF faz proxy.
   BACKEND_URL: obrigatoriaComDefaultDeTeste("BACKEND_URL", "http://localhost:3333"),
   QUIZ_SERVICE_URL: obrigatoriaComDefaultDeTeste("QUIZ_SERVICE_URL", "http://localhost:3334"),
+  // IA ainda nao habilitada: aceita URL valida ou string vazia (desligada nesta release).
   AI_URL: z
     .string()
     .url()
     .or(z.literal(""))
     .default(""),
+  // Segredos compartilhados: precisam bater com os dos servicos, senao da 401/403.
   INTERNAL_TOKEN: obrigatoriaComDefaultDeTeste("INTERNAL_TOKEN", "test-internal-token"),
   JWT_SECRET_KEY: obrigatoriaComDefaultDeTeste("JWT_SECRET_KEY", "test-secret"),
+  // Lista de origens liberadas no CORS, informada separada por virgula no .env.
   CORS_ORIGINS: z
     .string()
     .default("")
@@ -35,11 +63,13 @@ const envSchema = z.object({
         .map((origem) => origem.trim())
         .filter(Boolean),
     ),
+  // Timeout das chamadas aos servicos internos (ms).
   REQUEST_TIMEOUT_MS: z.coerce.number().int().positive().default(15000),
 });
 
 const parsedEnv = envSchema.safeParse(process.env);
 
+// Configuracao invalida derruba o boot na hora, com a lista de campos problematicos.
 if (!parsedEnv.success) {
   throw new Error(
     `Invalid environment variables: ${JSON.stringify(z.flattenError(parsedEnv.error).fieldErrors)}`,

src/config/logger.ts

@@ -1,8 +1,12 @@
+// Configuracao de logging do BFF com pino: um logger base para a aplicacao e um
+// logger HTTP que registra cada requisicao com nivel proporcional ao status.
 import pino from "pino";
 import pinoHttp from "pino-http";
 
 import { env } from "@/config/env";
 
+// Logger base da aplicacao. Cada log sai com servico/ambiente fixos (base) e
+// timestamp em ISO, facilitando filtrar por servico na agregacao de logs.
 export const logger = pino({
   level: env.LOG_LEVEL,
   timestamp: pino.stdTimeFunctions.isoTime,
@@ -12,8 +16,10 @@ export const logger = pino({
   },
 });
 
+// Logger de requisicoes HTTP, derivado do logger base.
 export const loggerHttp = pinoHttp({
   logger,
+  // Define a severidade do log pelo desfecho: 5xx/erro = error, 4xx = warn, resto = info.
   customLogLevel(_request, response, error) {
     if (error || response.statusCode >= 500) {
       return "error";
@@ -25,6 +31,7 @@ export const loggerHttp = pinoHttp({
 
     return "info";
   },
+  // Loga so o essencial de cada req/res para nao poluir nem vazar dados sensiveis.
   serializers: {
     req(request) {
       return {

src/modules/perfil-social/perfil-social.controller.ts

@@ -5,10 +5,12 @@ import { ErroAplicacao } from "@/shared/errors/erro-aplicacao";
 
 import type { PerfilSocialService } from "./perfil-social.service";
 
+// Parametro de rota: id do usuario cujo perfil social sera consultado.
 type PerfilSocialParams = {
   usuarioId: string;
 };
 
+// Filtros e paginacao aceitos na listagem de amigos.
 type ListarAmigosQuery = {
   page?: number;
   limit?: number;
@@ -18,15 +20,31 @@ type ListarAmigosQuery = {
 
 type RequisicaoAutenticada = Pick<Request, "usuario" | "headers">;
 
+/**
+ * Controller HTTP do perfil social.
+ *
+ * Valida os dados da requisicao, delega ao PerfilSocialService e devolve a resposta
+ * em JSON, encaminhando erros ao middleware central via next.
+ */
 export class PerfilSocialController {
   constructor(private readonly perfilSocialService: PerfilSocialService) {}
 
+  /**
+   * GET da lista de amigos do usuario logado.
+   *
+   * Aceita paginacao e filtros por nome/nickname na query string.
+   *
+   * @param request Requisicao Express com os filtros de listagem.
+   * @param response Resposta Express.
+   * @param next Encaminha erros ao middleware central.
+   */
   listarAmigos = async (
     request: Request<unknown, unknown, unknown, ListarAmigosQuery>,
     response: Response,
     next: NextFunction,
   ) => {
     try {
+      // Resolve usuario e token e repassa os filtros (request.query) ao service.
       const usuario = this.obterUsuario(request);
       const authorization = this.obterAuthorization(request);
       const resultado = await this.perfilSocialService.listarAmigosSociais(
@@ -37,16 +55,25 @@ export class PerfilSocialController {
 
       return response.status(200).json(resultado);
     } catch (error) {
+      // Erros (inclusive 401 de validacao) vao para o middleware central.
       return next(error);
     }
   };
 
+  /**
+   * GET do perfil social de um amigo especifico. O usuarioId vem na rota.
+   *
+   * @param request Requisicao Express tipada com o parametro usuarioId.
+   * @param response Resposta Express.
+   * @param next Encaminha erros ao middleware central.
+   */
   buscarPerfil = async (
     request: Request<PerfilSocialParams>,
     response: Response,
     next: NextFunction,
   ) => {
     try {
+      // O usuarioId da rota ja foi validado pela camada de rota antes de chegar aqui.
       const usuario = this.obterUsuario(request);
       const authorization = this.obterAuthorization(request);
       const perfil = await this.perfilSocialService.buscarPerfilSocial(
@@ -55,15 +82,24 @@ export class PerfilSocialController {
         request.params.usuarioId,
       );
 
+      // Envolve o perfil no envelope padrao (mensagem + dados) da API.
       return response.status(200).json({
         mensagem: "Perfil social encontrado.",
         dados: perfil,
       });
     } catch (error) {
+      // O 404 de "nao e amigo" tambem cai aqui e e formatado pelo middleware central.
       return next(error);
     }
   };
 
+  /**
+   * Exige que o usuario ja tenha sido autenticado pelo middleware.
+   *
+   * @param request Requisicao que deveria conter o usuario autenticado.
+   * @returns O usuario autenticado.
+   * @throws ErroAplicacao 401 quando nao ha usuario na requisicao.
+   */
   private obterUsuario(request: RequisicaoAutenticada) {
     if (!request.usuario?.id) {
       throw new ErroAplicacao({
@@ -76,6 +112,13 @@ export class PerfilSocialController {
     return request.usuario;
   }
 
+  /**
+   * Recupera o header Authorization a ser repassado aos servicos internos.
+   *
+   * @param request Requisicao de onde o header e lido.
+   * @returns O valor do header Authorization.
+   * @throws ErroAplicacao 401 quando o header esta ausente.
+   */
   private obterAuthorization(request: RequisicaoAutenticada): string {
     const authorization = request.headers.authorization;
 

src/modules/perfil-social/perfil-social.routes.ts

@@ -6,16 +6,23 @@ import { middlewareAutenticacao } from "@/shared/middlewares/autenticacao.middle
 import { PerfilSocialController } from "./perfil-social.controller";
 import { PerfilSocialService } from "./perfil-social.service";
 
+// Liga o modulo de perfil social: instancia service e controller (compartilhados
+// tambem por amizade.routes) e registra a rota autenticada de perfil.
 const perfilSocialService = new PerfilSocialService();
 const perfilSocialController = new PerfilSocialController(perfilSocialService);
 
 const perfilSocialRouter = Router();
 
+// Exige usuario autenticado para acessar qualquer perfil social.
 perfilSocialRouter.use(middlewareAutenticacao);
 
+// Valida o usuarioId da rota antes de chamar o controller: se vier vazio/invalido,
+// corta com 400 e nem aciona o servico.
 perfilSocialRouter.get("/:usuarioId/social", (request, response, next) => {
+  // Valida o id da rota com Zod: precisa ser string nao vazia (apos trim).
   const resultado = z.string().trim().min(1).safeParse(request.params.usuarioId);
 
+  // Id invalido para o fluxo aqui mesmo, sem chamar o controller/servicos.
   if (!resultado.success) {
     return response.status(400).json({
       erro: {
@@ -25,6 +32,7 @@ perfilSocialRouter.get("/:usuarioId/social", (request, response, next) => {
     });
   }
 
+  // Id valido: segue para o controller buscar o perfil social.
   return perfilSocialController.buscarPerfil(request, response, next);
 });