Ir para o conteúdo

Backend - Estado Atual (2026-03-10)

Este documento consolida o estado real do backend em billings-ease-backend na data 2026-03-10.

Fonte de verdade

  1. Registro de rotas: internal/http/bootstrap/routes.go
  2. Contratos OpenAPI: openapi.v1.yaml e openapi.v2.yaml
  3. Módulos por domínio: internal/modules/*
  4. Catálogo de módulos: internal/modules/module_access/catalog.go

Arquitetura em operação

  • Go 1.25 + Echo + GORM + PostgreSQL
  • organização modular por contexto (auth, general, client, professional, admin, marketplace, module_access, plans)
  • API versionada em paralelo: /api, /api/v1, /api/v2
  • /api/v2 com middleware de resolução de public_id

Registro de rotas (estado real)

Rotas públicas

  • /health
  • /docs* e /metrics (protegidos por middleware admin)
  • auth público com prefixos /api, /api/v1, /api/v2
  • planos públicos nos três prefixos
  • webhook público de cursos/marketplace nos três prefixos

Rotas protegidas

Todos os grupos protegidos recebem:

  • AuthMiddleware
  • ObservationContextMiddleware
  • ObservationReadOnlyMiddleware

Apenas /api/v2 recebe adicionalmente:

  • publicid.ResolveMiddleware

Controle de módulos

Endpoints principais (v2):

  • GET /api/v2/admin/modules/catalog
  • GET /api/v2/admin/modules/settings
  • PUT /api/v2/admin/modules/settings
  • GET /api/v2/admin/users/:id/module-overrides
  • PUT /api/v2/admin/users/:id/module-overrides
  • GET /api/v2/users/me/modules

Catálogo canônico atual inclui:

  • comunicacao.chat
  • pacientes.cadastro, pacientes.crm, pacientes.ciclos, pacientes.registro_diario, pacientes.analise_ciclo, pacientes.saude
  • consultas.gerenciar
  • financeiro.informacoes_pagamento, financeiro.extrato, financeiro.saques
  • educacional.cursos
  • educacional.cursos.catalogo, educacional.cursos.player, educacional.cursos.bundles, educacional.cursos.reviews
  • educacional.cursos.profissional.gestao, educacional.cursos.profissional.recomendacoes, educacional.cursos.profissional.bundles, educacional.cursos.profissional.materiais, educacional.cursos.profissional.revenue

Marketplace e cursos (status operacional)

  • rotas cliente/profissional/admin ativas no backend
  • implementação unificada em internal/modules/marketplace/courses com subpastas por ator (client, professional, admin, webhooks)
  • webhook Mercado Pago ativo
  • operação financeira e reconciliação presentes
  • deleção lógica de curso com fila assíncrona de remoção de vídeos publicada em produção
  • hardening por kill switches:
  • MARKETPLACE_CHECKOUT_ENABLED
  • MARKETPLACE_WEBHOOK_ENABLED
  • MARKETPLACE_SETTLEMENT_ENABLED

Observabilidade e segurança

  • middleware Prometheus global
  • /metrics protegido por docsauth.AdminOnlyMiddleware
  • CORS com configuração explícita por ambiente (cmd/api/main.go)
  • feature flags via internal/config/feature_flags.go

Atualização incremental (2026-03-10)

Mudanças recentes relevantes:

  • manutenção da refatoração de fertilidade/MOB com núcleo compartilhado em internal/modules/general/services/fertility/;
  • marketplace com exclusão lógica de cursos e remoção assíncrona de vídeos (POST /marketplace/professional/courses/:id/delete);
  • adição da migração 046_marketplace_course_logical_delete.sql;
  • estabilidade do contrato HTTP preservada para clientes web/mobile (mudanças com foco de domínio e operação).

Riscos e pontos de atenção

  1. Manter três prefixos de API eleva custo de compatibilidade.
  2. Alterações no catálogo canônico de módulos precisam preservar aliases legados.
  3. Mudanças em middleware de v2 afetam parsing de IDs públicos em várias rotas.