Renglones Presupuestarios

Cambio importante (mayo 2026): Lo que hasta el Sub-proyecto 1 se llamaba "Centros de Costo" en este módulo eran en realidad renglones presupuestarios — una matriz de clasificación que descompone empresa-categoría-subcategoría-actividad PDVSA. Se renombró a budget_positions para reflejar su semántica real. Los centros de costo verdaderos (unidades organizacionales con responsable y departamento) viven ahora en /accounting/cost-centers.

Acceso al Módulo

Menú principal: Presupuesto > Renglones Presupuestarios

Permisos requeridos: budget:positions:read (lectura), budget:positions:write (escritura)

Ruta API: /api/budget/positions (legacy /api/cost-centers → 308 redirect con header Deprecation).

---

¿Qué es un Renglón Presupuestario?

Un renglón presupuestario es la partida a la que se imputa un gasto o inversión. Responde la pregunta:

"¿Qué partida del presupuesto consume este flujo?"

En ACE el código sigue el patrón histórico PDVSA:

ACE - {Categoría} - {Subcategoría} - {Área Funcional}

Ejemplos: ACE-1-1AL-LEV, ACE-2-2MC-EQPS, ACE-CAPEX-INPR.

Cada renglón está asociado a:

• Un tipo de costo: OPEX o CAPEX.
• Un área funcional (ver Áreas Funcionales) — clasificador PDVSA.
• Una o varias cuentas contables vinculadas vía account_budget_position_links con rol (DEBIT_DEFAULT / CREDIT_DEFAULT / ALLOWED).

---

Estructura del Modelo

Campo	Tipo	Descripción
id	UUID	PK (preservado del rename desde cost_centers)
code	STRING	Código del renglón (ACE-1-1AL-LEV)
name	STRING	Nombre descriptivo
description	TEXT	Descripción detallada
cost_type	ENUM	OPEX o CAPEX
category	STRING	Categoría (Logística, Mantenimiento, …)
sub_category	STRING	Subcategoría libre
functional_area_id	UUID FK	Área funcional PDVSA (NOT NULL después del Sub-proyecto 1)
parent_id	UUID FK	Padre en la jerarquía (opcional)
status	ENUM	ACTIVE / INACTIVE

Columnas eliminadas en M9 (Sub-proyecto 1)

Las siguientes columnas legacy fueron archivadas en budget_positions_legacy_excel y eliminadas de la tabla productiva:

• pdvsa_code, pdvsa_description → reemplazadas por FK functional_area_id.
• budget_jan, budget_feb, budget_mar, budget_q2, budget_q3, budget_q4, total_annual_budget → el presupuesto vive ahora en budget_lines con período fiscal abierto y monedas duales.
• detalle → fundido en description.
• accounting_accounts (JSONB) → reemplazado por la tabla account_budget_position_links.
• allocated_budget, currency, fiscal_year → presupuesto vive en budget_lines.
• department_id, manager_id → no aplican a un renglón (son del CC real).

---

Tipos de Costo

Tipo	Significado	Ejemplos
OPEX	Gasto operacional recurrente	Levantamiento, mantenimiento, nómina, servicios
CAPEX	Inversión de capital	Equipos, perforación nueva, infraestructura

Reglas:

• Un renglón pertenece a un único tipo (no se permite mezclar OPEX/CAPEX en una misma partida).
• El cost_type del renglón debe coincidir con el budgetType del BudgetPlan al crear líneas presupuestarias contra él (BudgetLine.create() valida).
• Un proyecto puede tener renglones OPEX y CAPEX simultáneamente.

---

Patrón de Codificación ACE

ACE - {Área} - {Subcategoría}{Código} - {Tipo / Área Funcional}

Segmento	Descripción	Valores
ACE	Empresa	Siempre ACE
Área	Número de área funcional	1-6
Subcategoría	Identificador alfanumérico	1AL, 2MC, 3BM, …
Tipo / Área	Código de área funcional PDVSA	LEV, EQPS, INPR, ATIN, …

Áreas (legacy del Excel original)

#	Área	Categorías
1	Logística	Alimentación, transporte, combustibles, consumibles
2	Mantenimiento	Compresores, motores, PIAS, líneas, lubricantes
3	Producción	Bombas, análisis crudo, químicos, well testing
4	SG&A	Nómina, seguros, gastos admin, viajes
5	Infraestructura	Líneas crudo/agua/gas, transformadores, protección
6	Yacimientos	Taladros, procura eléctrica/mecánica, flush-by

Estas "áreas" del Excel original no son las functional_areas de la base de datos. La tabla functional_areas (26 códigos normalizados) reemplazó la columna pdvsa_code y se referencia vía FK. Ver Áreas Funcionales.

---

Catálogo de producción

Producción tiene 149 renglones presupuestarios activos al cierre del Sub-proyecto 1. La distribución típica es:

• ~80 renglones OPEX por área operativa (LEV, MEP, OLT, …)
• ~30 renglones CAPEX por proyecto/inversión (INPR, EQPS, ATIN, …)
• ~40 renglones administrativos y de soporte (ADM, PER, SHA, …)

Para listar todos:

GET /api/budget/positions
GET /api/budget/positions/by-cost-type/OPEX
GET /api/budget/positions/by-cost-type/CAPEX
GET /api/budget/positions/by-functional-area/:faId

---

Crear un Renglón Presupuestario

Paso 1

Navegar a Presupuesto > Renglones Presupuestarios, clic en + Nuevo.

Paso 2: Datos básicos

Campo	Requerido	Descripción
Código	✅	UNIQUE; seguir patrón ACE-{Cat}-{Sub}-{Área}
Nombre	✅	Nombre descriptivo
Descripción		Detalle libre
Tipo de Costo	✅	OPEX o CAPEX
Área Funcional	✅	Selector de las 26 áreas (FunctionalAreaSelector)
Categoría		Texto libre
Subcategoría		Texto libre
Padre		Otro renglón si forma parte de jerarquía

Paso 3: Cuentas vinculadas (opcional)

Tras guardar el renglón, en la pestaña Cuentas Contables se pueden crear account_budget_position_links:

1. Seleccionar la cuenta del plan.
2. Asignar rol: DEBIT_DEFAULT, CREDIT_DEFAULT o ALLOWED.
3. Sólo puede haber un DEBIT_DEFAULT y un CREDIT_DEFAULT por cuenta.

Estos links se usan en journalEntryService.create() para validar que un budget_position_id solo se acepta si existe un link configurado para esa cuenta.

---

Vinculación con otras Tablas

Con budget_lines

Cada línea presupuestaria referencia un renglón. Al crear una línea:

• budget_position.cost_type debe coincidir con BudgetPlan.budgetType.
• functional_area_id se infiere desde bp.functional_area_id si no se provee.

Con journal_entry_lines

El renglón aparece como una de las 5 dimensiones por línea de asiento. Ver Dimensiones Contables.

Con budget_commitments / afe_expenses

Propagan budget_position_id desde la línea origen para conservar la trazabilidad hasta el asiento.

---

Endpoints API

Operación	Endpoint	Permiso
Listar	GET /api/budget/positions	budget:positions:read
Detalle	GET /api/budget/positions/:id	:read
Crear	POST /api/budget/positions	:write
Editar	PUT /api/budget/positions/:id	:write
Eliminar / desactivar	DELETE /api/budget/positions/:id	:write
Filtrar por área funcional	GET /api/budget/positions/by-functional-area/:faId	:read
Filtrar por tipo	GET /api/budget/positions/by-cost-type/:type	:read
Listar links de cuentas	GET /api/accounting/positions/:id/accounts	accounting:mappings:read

Endpoint legacy /api/cost-centers/* mantiene 308 redirect a /api/budget/positions/* durante 1 release con header Deprecation: true.

---

Migración desde el modelo viejo

Concepto viejo	Concepto nuevo
cost_centers (149 registros)	budget_positions (mismas filas, mismo UUID, renombrada)
cost_centers.pdvsa_code	FK functional_area_id
cost_centers.budget_jan…q4	budget_positions_legacy_excel (archivo histórico) + budget_lines (presupuesto productivo)
cost_centers.accounting_accounts JSONB	Tabla account_budget_position_links
cost_centers como CC real	Nueva tabla cost_centers (22 unidades organizacionales)

Las 9 migraciones que hicieron este cambio están en backend_erp/src/database/migrations/ con nombres 20260501000001-* a 20260501000009-*.

---

Documentación relacionada

• Áreas Funcionales — clasificador PDVSA usado en cada renglón.
• Centros de Costo — unidades organizacionales (modelo nuevo, distinto a renglones).
• Dimensiones Contables — cómo se cruzan las 5 dimensiones por línea de asiento.
• Planes Presupuestarios — agrupan renglones por proyecto/período.
• Compromisos Presupuestarios
• Ejecución Presupuestaria

Referencia técnica completa: backend_erp/docs/superpowers/specs/2026-05-01-sub1-fundamento-dimensional-design.md.