Guía de Administrador — Centros de Costo

Guía técnica para administradores del módulo de Centros de Costo del ERP del Consorcio Alvorada & Cladoca.

---

Configuración Inicial

1. Crear Centros de Costo

Acceda a Administración → Centros de Costo o use la API:

POST /api/cost-centers
Content-Type: application/json

{
  "code": "CC-LEV-001",
  "name": "Levantamiento Topográfico - Proyecto Norte",
  "pdvsaCode": "LEV",
  "pdvsaDescription": "Levantamiento Topográfico",
  "costType": "OPEX",
  "departmentId": 3,
  "isActive": true
}

Campos requeridos:

• code — Código único en el sistema
• name — Nombre descriptivo
• costType — OPEX o CAPEX

Campos opcionales pero recomendados:

• pdvsaCode — Código de la nomenclatura PDVSA
• pdvsaDescription — Descripción según PDVSA
• departmentId — Departamento responsable

2. Importación Masiva desde Excel/CSV

Para cargar múltiples centros de costo use el endpoint de importación:

POST /api/cost-centers/import
Content-Type: multipart/form-data

file: centros-de-costo.xlsx

Formato del archivo Excel:

code	name	pdvsaCode	pdvsaDescription	costType	departmentId
CC-001	Levantamiento	LEV	Levantamiento Topográfico	OPEX	1
CC-002	Infraestructura	INPR	Infraestructura y Proyectos	CAPEX	2

---

Configuración de Permisos

Permisos del Módulo

Permiso	Descripción	Quién debe tenerlo
budget:read	Ver dashboards y reportes de presupuesto	Todos los usuarios con acceso a presupuestos
cost-centers:read	Ver lista de centros de costo	Todos los usuarios
cost-centers:write	Crear y editar centros de costo	Administradores y Jefes de Área
cost-centers:reports	Ver desgloses por CC en dashboards	Supervisores, Gerentes, Directivos
cost-centers:delete	Eliminar centros de costo (soft delete)	Solo Administradores

Asignar Permisos en el Sistema

# Asignar permiso a un rol
POST /api/roles/{roleId}/permissions
{
  "permissions": ["cost-centers:reports", "budget:read"]
}

# Verificar permisos de un usuario
GET /api/users/{userId}/permissions

---

Vinculación con Planes Presupuestarios

Crear un Plan con Centros de Costo

1. Crear el BudgetPlan con budgetType: "OPEX" o "CAPEX"
2. Crear BudgetLines vinculando costCenterId

# 1. Crear plan OPEX
POST /api/budget/plans
{
  "fiscalYear": 2026,
  "budgetType": "OPEX",
  "departmentId": 3,
  "description": "Presupuesto Operacional 2026"
}

# 2. Crear línea con CC
POST /api/budget/lines
{
  "budgetPlanId": 15,
  "costCenterId": 7,
  "categoryId": 3,
  "description": "Servicios de levantamiento Q1",
  "plannedAmount": 150000
}

Importante: BudgetLine no tiene columna budgetType. El tipo OPEX/CAPEX se determina siempre a través del BudgetPlan asociado. Nunca filtre directamente en BudgetLine.budgetType.

---

Migración de Datos Existentes

Si ya tiene centros de costo sin código PDVSA asignado, puede actualizar masivamente:

# Actualizar código PDVSA de un CC existente
PATCH /api/cost-centers/{id}
{
  "pdvsaCode": "LEV",
  "pdvsaDescription": "Levantamiento Topográfico"
}

Script SQL de migración (solo para DBA)

-- Actualizar centros de costo OPEX sin código PDVSA
UPDATE cost_centers
SET pdvsa_code = 'SSG',
    pdvsa_description = 'Suministros y Servicios Generales'
WHERE cost_type = 'OPEX'
  AND pdvsa_code IS NULL
  AND name ILIKE '%suministro%';

-- Verificar centros sin PDVSA
SELECT id, code, name, cost_type
FROM cost_centers
WHERE pdvsa_code IS NULL
  AND is_active = true
ORDER BY cost_type, name;

---

Configuración de Alertas Presupuestarias

Las alertas se generan automáticamente cuando la ejecución supera umbrales configurados. Para ajustar los umbrales, modifique las constantes en:

backend/src/modules/budget/services/budgetAlertService.js

const ALERT_THRESHOLDS = {
  WARNING: 0.80,  // Alerta amarilla al 80%
  CRITICAL: 0.95, // Alerta roja al 95%
};

---

Monitoreo y Resolución de Problemas

Verificar endpoint de ejecución por CC

curl -H "Authorization: Bearer {token}" \
  "http://localhost:3000/api/budget/dashboard/execution-by-cost-center?fiscalYear=2026&costType=opex"

Respuesta esperada:

{
  "fiscalYear": 2026,
  "costType": "opex",
  "costCenters": [
    {
      "costCenterId": 7,
      "costCenterCode": "CC-LEV-001",
      "costCenterName": "Levantamiento Topográfico",
      "pdvsaCode": "LEV",
      "pdvsaDescription": "Levantamiento Topográfico",
      "costType": "OPEX",
      "totalPlanned": 150000,
      "totalCommitted": 45000,
      "totalExecuted": 80000,
      "totalAvailable": 25000,
      "executionPercentage": "53.33"
    }
  ]
}

Problemas Comunes

Error: "column BudgetLine.budgetType does not exist"

Este error ocurre si el código intenta filtrar directamente en BudgetLine por budgetType. La columna no existe en esa tabla. El filtro debe aplicarse en el include de BudgetPlan:

// ❌ Incorrecto
where: { budgetType: 'OPEX' }  // en BudgetLine

// ✅ Correcto
include: [{
  model: BudgetPlan,
  where: { budgetType: 'OPEX' },
  attributes: []
}]

Error 500 en GET /commitments/summary/by-category

Este endpoint requiere el método getCommitmentsSummaryByCategory() en budgetCommitmentService.js. Si recibe un 500, verifique que el método esté implementado (fue agregado en ERP-30).

Dashboard no muestra datos de CC

1. Verificar que el usuario tiene el permiso cost-centers:reports
2. Verificar que las BudgetLines tienen costCenterId asignado
3. Revisar los logs del backend para errores de consulta

---

Respaldo y Mantenimiento

Tablas involucradas en el módulo

Tabla	Descripción
cost_centers	Definición de centros de costo
budget_plans	Planes presupuestarios (tiene budget_type)
budget_lines	Líneas con cost_center_id
budget_executions	Ejecuciones registradas por CC
budget_commitments	Compromisos vinculados a líneas (y CC via join)

Índices recomendados

-- Acelerar consultas de dashboard por CC
CREATE INDEX IF NOT EXISTS idx_budget_executions_cost_center
  ON budget_executions(cost_center_id, fiscal_year);

CREATE INDEX IF NOT EXISTS idx_budget_lines_cost_center
  ON budget_lines(cost_center_id);

CREATE INDEX IF NOT EXISTS idx_cost_centers_pdvsa
  ON cost_centers(pdvsa_code) WHERE is_active = true;

---

Referencias

• nomenclatura-pdvsa.md — Códigos PDVSA de referencia
• flujo-centros-de-costo.md — Flujos operativos
• api-reference-centros-de-costo.md — API Reference completa