Servicios Go/Gin

Servicio: users

Información General

Propósito: Sistema central de autenticación y gestión de usuarios. Mantiene el registro de usuarios, sus permisos por proyecto y controla el acceso al sistema.
Tecnología: Go 1.24.0 / Gin
Puerto: Variable por ambiente (DEV_PORT, QA_PORT, PROD_PORT)
Módulo: users
CI/CD: GitLab CI/CD

Propósito de Negocio

Centraliza: - Registro y login de usuarios (email/password y Google OAuth) - Asignación de usuarios a proyectos con roles y vistas específicas - Control granular de permisos (certify, whatsappAssistant, CCA) - Generación de tokens JWT para acceso a la plataforma

Endpoints Expuestos

Path	Descripción
`POST /users/login`	Login con email/password o Google
`POST /users/register`	Registro de nuevo usuario
`POST /users/by-email`	Buscar usuario por email
`POST /users/by-email-and-project`	Buscar usuario en proyecto específico
`POST /users/get-by-emails`	Buscar múltiples usuarios por emails (bulk)
`GET /users`	Listar todos los usuarios
`GET /users/by-project/:projectId`	Usuarios de un proyecto
`GET /users/by-project/v2/:projectId`	Usuarios de un proyecto (versión mejorada)
`GET /users/by-phone-number/:projectId/:phoneNumber`	Buscar por teléfono en proyecto
`GET /users/permissions/:projectId`	Usuarios con permisos detallados del proyecto
`GET /all-cca/:projectId`	Usuarios con rol CCA en el proyecto
`PUT /users`	Actualizar datos básicos de usuario
`PUT /users/add-views`	Agregar vistas a un usuario en un proyecto
`PUT /update-permissions`	Actualizar permisos binarios
`PUT /update-permissions/by-phone-number`	Permisos actualizados por teléfono
`PUT /phone-number`	Actualizar número de teléfono
`DELETE /users`	Desactivar usuario (status=false)
`DELETE /users/remove-project`	Desactivar proyecto del scope del usuario

Base de Datos

Motor: MongoDB v1.17.2
Conexión: Variables de entorno por ambiente

Colecciones Usadas

Colección	Base de Datos	Descripción
`users`	`master`	Registro global de usuarios (email único)

Estructura del Documento Usuario

{
  "_id": "ObjectId",
  "name": "string",
  "email": "string (ÚNICO — clave principal)",
  "charge": "string (cargo/puesto)",
  "profile": "string",
  "scope": [
    {
      "code": "projectId",
      "project": "nombre del proyecto",
      "labels": ["labelCode1", "labelCode2"],
      "views": ["dashboard", "gantt", "..."],
      "status": true
    }
  ],
  "status": true,
  "phone": ["string"],
  "userId": "string (Google ID)",
  "pass_user": "string (hash bcrypt)"
}

Variables de Entorno

Variable	Descripción
`ENVIRONMENT`	Ambiente: `dev`, `qa`, `prod`
`{ENV}_PORT`	Puerto HTTP
`{ENV}_API_URL`	URL de la API para generación de tokens
`{ENV}_DB_USER`	Usuario MongoDB
`{ENV}_DB_PASSWORD`	Contraseña MongoDB (sensible)
`{ENV}_DB_HOST`	Host MongoDB
`{ENV}_DB_PORT`	Puerto MongoDB

Sistema de Autenticación

Opción 1 — Email + Password:

hash_almacenado = bcrypt(email + password)
En login: bcrypt.Compare(email + password, hash_almacenado)

Opción 2 — Google Sign-In:

userId = Google ID del usuario
Validación directa contra userId almacenado en BD

Generación de JWT

Después de validar credenciales: 1. Llama a POST {API_URL}/gen-access-token/... con Bearer token interno 2. Recibe: token (JWT de acceso) + refreshToken 3. Retorna ambos tokens al cliente junto con la lista de proyectos

Nota de seguridad: El Bearer token usado para generar tokens JWT está hardcodeado en el código fuente. Debe migrarse a variable de entorno o vault.

Dependencias Externas

Servicio	Llamada	Propósito
API Gateway	`POST /gen-access-token/...`	Obtener JWT de acceso

Roles y Permisos

Campo	Tipo	Significado
`scope[].views[]`	array	Vistas de la plataforma accesibles (dashboard, gantt, digitaltwin, etc.)
`scope[].labels[]`	array	Etiquetas visibles para el usuario en el proyecto
`scope[].status`	bool	Acceso activo/inactivo al proyecto
`permissions.certify`	bool	Puede certificar bloques de construcción
`permissions.whatsappAssistant`	bool	Recibe notificaciones WhatsApp
`isCca`	bool	Es Coordinador de Control de Obra (CCA)

Middlewares

CORS: AllowAllOrigins=true
gin.Recovery(), gin.Logger()

Rol en Casos de Uso

Caso de Uso	Rol
CU-01: Login	Servicio principal
CU-03: Creación de Proyecto	`projects` valida creador vía este servicio
CU-05: Certificación	`registry` valida permisos del usuario aquí