Configuración y Despliegue

GM Fiscal Backend se configura mediante variables de entorno cargadas desde un archivo .env.{ENVIRONMENT} al iniciar. La carga ocurre exclusivamente en src/main.go mediante config.LoadConfig(). El servidor se ejecuta siempre a través de Docker Compose; el uso de go run está prohibido en todos los entornos.

Requisitos del entorno de desarrollo

Docker y Docker Compose.
Go 1.24.5 (solo para ejecutar tests y herramientas; el servidor se ejecuta dentro del contenedor).

Perfiles de Docker Compose

El sistema soporta cuatro perfiles, cada uno asociado a un archivo .env:

Perfil	Archivo de entorno	Uso
`dev`	`.env.dev`	Desarrollo local con BD local
`qa`	`.env.qa`	Testing y QA
`staging`	`.env.staging`	Pre-producción
`prod`	`.env`	Producción

Comandos de gestión del entorno

# Levantar API + PostgreSQL principal (5433) + PostgreSQL caché (5434)
docker-compose --profile dev up -d

# Ver logs en tiempo real
docker-compose --profile dev logs -f api

# Detener todos los servicios
docker-compose --profile dev down

# Reconstruir la imagen tras cambios en el código
docker-compose --profile dev build --no-cache && docker-compose --profile dev up -d

Variables de entorno

Servidor

PORT=8046
ENVIRONMENT=dev
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:4200

Base de datos principal

DB_HOST=localhost
DB_PORT=5433
DB_USER=postgres
DB_PASS=postgres
DB_NAME=gm_fiscal
DB_SSLMODE=disable

Base de datos caché CFDI

Solo activa cuando INVOICE_PROVIDER=hades. Almacena los metadatos de los CFDIs descargados para evitar reconsultas al SAT.

CACHE_DB_HOST=localhost
CACHE_DB_PORT=5434
CACHE_DB_USER=postgres
CACHE_DB_PASS=postgres
CACHE_DB_NAME=gm_fiscal_cache

Proveedor de facturas

La variable INVOICE_PROVIDER determina qué sistema se usa para obtener los CFDIs del SAT. El switch no requiere cambios de código:

INVOICE_PROVIDER=prodigia   # HTTP REST (legado)
INVOICE_PROVIDER=hades      # gRPC + caché dual (alta escala)

Configuración Prodigia:

PRODIGIA_BASEURL=https://api.prodigia.mx
PRODIGIA_PADE_USER=usuario@empresa.com
PRODIGIA_PADE_PASS=contraseña
PRODIGIA_CONTRATO=contrato

Configuración Hades gRPC:

# Desarrollo y QA
HADES_GRPC_ADDRESS=localhost:9456
HADES_GRPC_TLS=false

# Producción
HADES_GRPC_ADDRESS=hades.gmtransport.co:443
HADES_GRPC_TLS=true

ERP interno

APIERP=http://192.168.2.x:8080/api

Autenticación JWT

JWT_SECRET=clave-secreta-segura-minimo-32-caracteres
JWT_EXPIRY_HOURS=24
JWT_REFRESH_EXPIRY_DAYS=30
SERVICIOS_GM_URL=http://192.168.2.248:9300/api

Azure Blob Storage

AZURE_ACCOUNT_NAME=cuenta
AZURE_ACCOUNT_KEY=clave
AZURE_CONTAINER_NAME=contenedor
AZURE_ENDPOINT=https://cuenta.blob.core.windows.net
AZURE_SAS_EXPIRY_MINUTES=1440

Si Azure no está disponible al iniciar o durante la operación, el sistema cae de forma automática hacia almacenamiento local sin interrumpir el flujo.

Caché CFDI (solo con Hades)

CACHE_MAX_ENTRIES_PER_RFC=1000000      # Cuota máxima por empresa
CACHE_EVICTION_TARGET_PERCENT=50       # Objetivo de evicción al superar la cuota

Cuando una empresa supera 1,000,000 entradas en caché, el sistema aplica evicción FIFO automática hasta reducir al 50% del límite. No requiere intervención manual.

Logging centralizado

GMLOGS_ENABLED=true
GMLOGS_APIENDPOINT=192.168.2.248:9432
GMLOGS_APIKEY=api-key
GMLOGS_DEBUG=false

Con GMLOGS_ENABLED=true, todos los logs se envían a GM Logs vía TCP en batch de forma asíncrona. El uso de log.Printf o fmt.Println está prohibido en producción.

Contrato de rutas HTTP

El contrato de rutas es permanente. Las rutas, métodos HTTP y estructura de request/response no se modifican sin un proceso de deprecación explícito. Todas las rutas bajo /api/* requieren Authorization: Bearer <token> excepto las de autenticación.

# Autenticación
POST   /api/auth/login
POST   /api/auth/refresh
POST   /api/auth/logout

# Empresa
GET    /api/empresas
POST   /api/empresas
GET    /api/empresas/rfc/{rfc}
GET    /api/empresas/{id}
PUT    /api/empresas/{id}
DELETE /api/empresas/{id}

# Solicitud
POST   /api/solicitudes
GET    /api/solicitudes/{id}
PUT    /api/solicitudes/{id}
DELETE /api/solicitudes/{id}
GET    /api/solicitudes/uuid/{uuid}
GET    /api/solicitudes/estatus/{estatus}
GET    /api/solicitudes/rfc/{rfc}
GET    /api/solicitudes/rfc/{rfc}/sincronizar

# Conciliación
POST   /api/conciliacion
GET    /api/conciliacion/{uuid}
GET    /api/conciliacion/{uuid}/export
GET    /api/conciliacion/{id}/columnas_impuestos
GET    /api/conciliaciones/por-rfc/{rfc}
POST   /api/conciliacion/manual
GET    /api/conciliacion/manual/xml/{uuid}
GET    /api/conciliacion/manual/solicitud/{uuid}/xmls
GET    /api/conciliacion/manual/solicitud/{uuid}/download-zip

# Reporte
POST   /api/reporte
GET    /api/reporte/{uuid}
GET    /api/reporte/rfc/{rfc}
GET    /api/reporte/solicitud/{solicitud_uuid}
DELETE /api/reporte/{uuid}
GET    /api/reporte/validation

# Facturas
GET    /api/facturas/erp/{rfc}
GET    /api/facturas/prodigia/{rfc}
GET    /api/facturas/para-conciliacion/{rfc}

# Comprobante
POST   /api/comprobantes/request
GET    /api/descargas/
DELETE /api/descargas/{uuid}

# Notificaciones
GET    /api/notificaciones/{rfc}
POST   /api/notificaciones/{id}/marcar-leido
WS     /api/ws/notificaciones/{rfc}

# Certificado
POST   /api/certificados/validar
POST   /api/certificados/generar-token
POST   /api/certificados/renovar

# Health
GET    /api/health
GET    /api/health/live
GET    /api/health/ready

Los endpoints de health se usan como probes de Kubernetes/Container Apps:

Endpoint	Probe	Descripción
`/api/health`	Startup	Responde inmediatamente al arranque
`/api/health/live`	Liveness	Verifica que el proceso no está bloqueado
`/api/health/ready`	Readiness	Verifica BD, storage y configuración

Proceso de verificación local

Antes de cualquier pull request, ejecutar la suite de verificación completa:

go vet ./src/...
go build ./src
go test ./src/domain/...          # funciones puras, siempre verde
go test ./src/application/...     # mocks testify, siempre verde
go test ./tests/...               # BDD godog
go test ./src/infrastructure/...  # requiere PostgreSQL en 5433
go test ./... -race -count=1      # detección de data races

Si un test falla dos veces con el mismo error, o si go build falla, se detiene el trabajo y se reporta el error exacto. No se continúa con el siguiente paso.

Resumen

La configuración se carga desde .env.{ENVIRONMENT} exclusivamente en src/main.go. Ningún otro módulo llama a config.LoadConfig().
El servidor se ejecuta siempre mediante docker-compose --profile {env} up -d. El uso de go run está prohibido.
INVOICE_PROVIDER controla el proveedor de facturas: prodigia (HTTP REST) o hades (gRPC + caché dual).
El caché CFDI (PostgreSQL 5434) solo se activa con INVOICE_PROVIDER=hades; la base de datos de caché no es necesaria con Prodigia.
Azure Blob Storage tiene fallback automático a almacenamiento local si no está disponible.
El contrato de rutas HTTP es permanente y no se modifica sin proceso de deprecación explícito.