420 lines
16 KiB
Markdown
420 lines
16 KiB
Markdown
# US-ADM-004: Gestionar Centros de Costo Jerárquicos
|
||
|
||
**ID:** US-ADM-004
|
||
**Módulo:** MAI-013
|
||
**Relacionado con:** RF-ADM-003, ET-ADM-002
|
||
**Prioridad:** Alta
|
||
**Story Points:** 8
|
||
|
||
---
|
||
|
||
## 📖 Historia de Usuario
|
||
|
||
**Como** Director General o Finanzas
|
||
**Quiero** crear y organizar centros de costo en estructura jerárquica ilimitada
|
||
**Para** rastrear costos a nivel granular y obtener reportes consolidados por nivel
|
||
|
||
---
|
||
|
||
## ✅ Criterios de Aceptación
|
||
|
||
### 1. Visualizar Árbol de Centros de Costo
|
||
|
||
```gherkin
|
||
Given que soy Director o Finanzas
|
||
When accedo a "Administración > Centros de Costo"
|
||
Then debo ver un árbol expandible con:
|
||
- Todos los centros de costo organizados jerárquicamente
|
||
- Iconos según tipo (Directo, Indirecto, Servicio Compartido)
|
||
- Código y nombre de cada centro
|
||
- Costos acumulados del mes actual
|
||
- Estados: Activo / Inactivo
|
||
- Acciones: Crear hijo, Editar, Desactivar
|
||
```
|
||
|
||
### 2. Crear Centro de Costo Raíz
|
||
|
||
```gherkin
|
||
Given que no existen centros de costo o quiero crear uno nuevo en raíz
|
||
When hago clic en "+ Nuevo Centro de Costo"
|
||
And completo el formulario:
|
||
- Código: "100" (único)
|
||
- Nombre: "Operaciones"
|
||
- Tipo: "Indirecto"
|
||
- Descripción: (opcional)
|
||
And hago clic en "Guardar"
|
||
Then el sistema debe:
|
||
- Crear el centro con level = 0
|
||
- path = "100"
|
||
- parentId = null
|
||
- Mostrar en árbol como raíz
|
||
- Registrar en audit log
|
||
```
|
||
|
||
### 3. Crear Centro de Costo Hijo
|
||
|
||
```gherkin
|
||
Given que existe un centro "100 - Operaciones"
|
||
When hago clic derecho en "100" y selecciono "Crear Centro Hijo"
|
||
And completo el formulario:
|
||
- Código: "101"
|
||
- Nombre: "Proyecto Residencial"
|
||
- Tipo: "Directo"
|
||
And guardo
|
||
Then el sistema debe:
|
||
- Crear centro con parentId = "100"
|
||
- path = "100/101"
|
||
- level = 1
|
||
- Mostrarlo indentado bajo "100" en el árbol
|
||
- Permitir expandir/colapsar
|
||
```
|
||
|
||
### 4. Jerarquía Ilimitada
|
||
|
||
```gherkin
|
||
Given esta estructura:
|
||
100 Operaciones (raíz, level 0)
|
||
└─ 101 Proyecto Res (level 1)
|
||
└─ 101.1 Torre A (level 2)
|
||
└─ 101.1.1 Pisos 1-5 (level 3)
|
||
└─ 101.1.1.1 Acabados (level 4)
|
||
|
||
When consulto el árbol
|
||
Then debo poder navegar todos los niveles sin límite
|
||
And cada nivel debe mostrar su path completo
|
||
```
|
||
|
||
### 5. Tipos de Centro de Costo
|
||
|
||
```gherkin
|
||
Given que estoy creando un centro de costo
|
||
When selecciono el tipo:
|
||
- "Directo": Costos imputables directamente a proyectos
|
||
- "Indirecto": Gastos generales (admin, marketing)
|
||
- "Servicio Compartido": Servicios internos (IT, RH)
|
||
Then el sistema debe:
|
||
- Aplicar reglas de imputación según el tipo
|
||
- Mostrar ícono diferenciado en el árbol
|
||
- Permitir configurar método de asignación (solo Indirecto y Compartido)
|
||
```
|
||
|
||
### 6. Imputación de Costos
|
||
|
||
```gherkin
|
||
Given que tengo esta estructura:
|
||
100 Operaciones
|
||
└─ 101 Proyecto A
|
||
└─ 101.1 Materiales
|
||
|
||
When imputo un costo de $10,000 a "101.1 Materiales"
|
||
Then el sistema debe:
|
||
- Crear registro en cost_imputations
|
||
- Incrementar costo acumulado de:
|
||
- 101.1 Materiales: +$10,000
|
||
- 101 Proyecto A: +$10,000 (consolidado)
|
||
- 100 Operaciones: +$10,000 (consolidado)
|
||
- Actualizar en tiempo real el árbol
|
||
```
|
||
|
||
### 7. Distribución de Overhead
|
||
|
||
```gherkin
|
||
Given que tengo:
|
||
- Centro "200 - Administración" (Indirecto) con $50,000 en gastos
|
||
- 3 proyectos directos activos
|
||
When ejecuto "Distribuir Overhead" para el periodo "Nov 2025"
|
||
And selecciono método: "Proporcional por Ingresos"
|
||
Then el sistema debe:
|
||
- Calcular proporción de cada proyecto
|
||
- Crear imputaciones de overhead en cada proyecto
|
||
- Mostrar desglose en reporte
|
||
- Registrar en audit log
|
||
```
|
||
|
||
### 8. Reporte Consolidado
|
||
|
||
```gherkin
|
||
Given que tengo múltiples niveles de centros de costo
|
||
When genero "Reporte Consolidado" para "Q4 2025"
|
||
Then debo ver:
|
||
- Árbol completo con costos por nivel
|
||
- Costos propios vs. consolidados (incluye hijos)
|
||
- Gráfico de distribución por tipo
|
||
- Opciones de exportar: PDF, Excel, CSV
|
||
```
|
||
|
||
### 9. Buscar en Árbol
|
||
|
||
```gherkin
|
||
Given que tengo 50+ centros de costo
|
||
When escribo "Torre" en el buscador
|
||
Then el sistema debe:
|
||
- Filtrar árbol mostrando solo coincidencias
|
||
- Expandir automáticamente la ruta de cada coincidencia
|
||
- Resaltar el texto coincidente
|
||
```
|
||
|
||
### 10. Desactivar Centro de Costo
|
||
|
||
```gherkin
|
||
Given que un centro ya no se usa
|
||
When hago clic en "Desactivar"
|
||
Then el sistema debe:
|
||
- Marcar isActive = false
|
||
- Mantener histórico de costos
|
||
- Ocultarlo del árbol (con opción "Mostrar Inactivos")
|
||
- NO permitir nuevas imputaciones
|
||
- NO permitir desactivar si tiene hijos activos
|
||
```
|
||
|
||
---
|
||
|
||
## 🎨 Mockup / Wireframe
|
||
|
||
### Árbol de Centros de Costo
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Centros de Costo [+ Nuevo] [📊 Reportes] [⚙️]│
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ 🔍 Buscar... ☐ Mostrar inactivos │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ▼ 📦 100 - Operaciones $250,000.00 │
|
||
│ │ [+][✏️][❌] │
|
||
│ │ │
|
||
│ ├─▼ 🎯 101 - Proyecto Residencial A $180,000.00 │
|
||
│ │ │ [+][✏️][❌] │
|
||
│ │ │ │
|
||
│ │ ├─▶ 🏗️ 101.1 - Torre A $120,000.00 │
|
||
│ │ │ [+][✏️][❌] │
|
||
│ │ │ │
|
||
│ │ ├─▶ 🏗️ 101.2 - Torre B $60,000.00 │
|
||
│ │ │ [+][✏️][❌] │
|
||
│ │ │ │
|
||
│ │ └─▶ 📋 101.3 - Administración Obra $0.00 │
|
||
│ │ [+][✏️][❌] │
|
||
│ │ │
|
||
│ ├─▶ 🎯 102 - Proyecto Comercial B $70,000.00 │
|
||
│ │ [+][✏️][❌] │
|
||
│ │ │
|
||
│ └─▶ 💼 103 - Servicios Compartidos $0.00 │
|
||
│ [+][✏️][❌] │
|
||
│ │
|
||
│ ▼ 📦 200 - Administración $50,000.00 │
|
||
│ │ [+][✏️][❌] │
|
||
│ │ │
|
||
│ ├─▶ 💼 201 - Dirección General $20,000.00 │
|
||
│ ├─▶ 💼 202 - Finanzas $15,000.00 │
|
||
│ └─▶ 💼 203 - RH $15,000.00 │
|
||
│ │
|
||
│ ▶ 📦 300 - Marketing $30,000.00 │
|
||
│ [+][✏️][❌] │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
|
||
Leyenda:
|
||
🎯 Directo 💼 Indirecto 🏗️ Servicio Compartido
|
||
▶ Colapsado ▼ Expandido
|
||
```
|
||
|
||
### Modal Crear Centro de Costo
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ Nuevo Centro de Costo [X]│
|
||
├─────────────────────────────────────────────┤
|
||
│ │
|
||
│ Centro Padre (opcional) │
|
||
│ [v] 101 - Proyecto Residencial A │
|
||
│ │
|
||
│ Código * │
|
||
│ ┌─────────────────────────────────────────┐ │
|
||
│ │ 101.1 │ │
|
||
│ └─────────────────────────────────────────┘ │
|
||
│ ℹ️ Path completo: 100/101/101.1 │
|
||
│ │
|
||
│ Nombre * │
|
||
│ ┌─────────────────────────────────────────┐ │
|
||
│ │ Torre A │ │
|
||
│ └─────────────────────────────────────────┘ │
|
||
│ │
|
||
│ Tipo * │
|
||
│ ◉ Directo │
|
||
│ ○ Indirecto │
|
||
│ ○ Servicio Compartido │
|
||
│ │
|
||
│ Descripción │
|
||
│ ┌─────────────────────────────────────────┐ │
|
||
│ │ Primera torre del proyecto, pisos 1-15 │ │
|
||
│ └─────────────────────────────────────────┘ │
|
||
│ │
|
||
│ Responsable │
|
||
│ [v] Juan Pérez (Ingeniero) │
|
||
│ │
|
||
│ [Cancelar] [Crear Centro] │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Modal Distribuir Overhead
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ Distribuir Overhead [X]│
|
||
├─────────────────────────────────────────────┤
|
||
│ │
|
||
│ Centro de Costo Indirecto │
|
||
│ [v] 200 - Administración │
|
||
│ Costo acumulado: $50,000.00 │
|
||
│ │
|
||
│ Periodo │
|
||
│ [Noviembre 2025] 📅 │
|
||
│ │
|
||
│ Método de Distribución * │
|
||
│ ◉ Proporcional por Ingresos │
|
||
│ ○ Proporcional por Costos Directos │
|
||
│ ○ Partes Iguales │
|
||
│ ○ Porcentaje Manual │
|
||
│ │
|
||
│ Centros de Costo Receptores: │
|
||
│ ┌─────────────────────────────────────────┐ │
|
||
│ │ ☑️ 101 - Proyecto Res A (60%) $30K │ │
|
||
│ │ ☑️ 102 - Proyecto Com B (40%) $20K │ │
|
||
│ │ ☐ 103 - Servicios (inactivo) │ │
|
||
│ └─────────────────────────────────────────┘ │
|
||
│ │
|
||
│ [Cancelar] [Distribuir] │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 Casos de Prueba
|
||
|
||
### CP-001: Crear Centro Raíz
|
||
|
||
**Precondiciones:**
|
||
- Usuario con rol "director" o "finance"
|
||
|
||
**Pasos:**
|
||
1. Ir a "Centros de Costo"
|
||
2. Clic "+ Nuevo"
|
||
3. Dejar "Centro Padre" vacío
|
||
4. Código: "100", Nombre: "Operaciones", Tipo: "Indirecto"
|
||
5. Guardar
|
||
|
||
**Resultado Esperado:**
|
||
- ✅ Centro creado con level=0, path="100", parentId=null
|
||
- ✅ Aparece en árbol como raíz
|
||
- ✅ Audit log: "cost_center_created"
|
||
|
||
### CP-002: Crear Jerarquía de 5 Niveles
|
||
|
||
**Pasos:**
|
||
1. Crear 100 (raíz)
|
||
2. Crear 101 hijo de 100
|
||
3. Crear 101.1 hijo de 101
|
||
4. Crear 101.1.1 hijo de 101.1
|
||
5. Crear 101.1.1.1 hijo de 101.1.1
|
||
|
||
**Resultado Esperado:**
|
||
- ✅ Todos los centros creados correctamente
|
||
- ✅ Paths: "100", "100/101", "100/101/101.1", etc.
|
||
- ✅ Levels: 0, 1, 2, 3, 4
|
||
- ✅ Árbol muestra correctamente la indentación
|
||
|
||
### CP-003: Imputar Costo y Consolidación
|
||
|
||
**Precondiciones:**
|
||
- Estructura: 100 > 101 > 101.1
|
||
|
||
**Pasos:**
|
||
1. Imputar $10,000 a "101.1"
|
||
2. Verificar montos
|
||
|
||
**Resultado Esperado:**
|
||
- ✅ 101.1: $10,000 (propio)
|
||
- ✅ 101: $10,000 (consolidado de hijos)
|
||
- ✅ 100: $10,000 (consolidado de hijos)
|
||
- ✅ Query recursiva funciona correctamente
|
||
|
||
### CP-004: Distribuir Overhead
|
||
|
||
**Precondiciones:**
|
||
- Centro "200 Administración" (Indirecto) con $50,000
|
||
- 2 proyectos directos: A ($100K ingresos), B ($50K ingresos)
|
||
|
||
**Pasos:**
|
||
1. Seleccionar "200 - Administración"
|
||
2. Método: "Proporcional por Ingresos"
|
||
3. Distribuir
|
||
|
||
**Resultado Esperado:**
|
||
- ✅ Proyecto A recibe: $33,333 (66.6%)
|
||
- ✅ Proyecto B recibe: $16,667 (33.3%)
|
||
- ✅ Imputaciones creadas con source_type="overhead"
|
||
- ✅ Audit log registra distribución
|
||
|
||
### CP-005: Buscar en Árbol
|
||
|
||
**Precondiciones:**
|
||
- 50 centros de costo
|
||
|
||
**Pasos:**
|
||
1. Escribir "Torre" en buscador
|
||
|
||
**Resultado Esperado:**
|
||
- ✅ Solo muestra centros con "Torre" en nombre/código
|
||
- ✅ Expande automáticamente la ruta completa
|
||
- ✅ Resalta texto coincidente
|
||
|
||
### CP-006: No Desactivar con Hijos Activos
|
||
|
||
**Precondiciones:**
|
||
- Centro "100" tiene hijo "101" activo
|
||
|
||
**Pasos:**
|
||
1. Intentar desactivar "100"
|
||
|
||
**Resultado Esperado:**
|
||
- ✅ Error: "No se puede desactivar. Tiene centros hijo activos."
|
||
- ✅ Sugerencia: "Desactiva primero: 101"
|
||
- ✅ Centro permanece activo
|
||
|
||
---
|
||
|
||
## 🔗 Dependencias
|
||
|
||
**Requisitos Previos:**
|
||
- ET-ADM-002: Tabla `cost_centers` con triggers de path
|
||
- ET-ADM-002: Función SQL `get_consolidated_costs()`
|
||
- Backend: Servicio de distribución de overhead
|
||
|
||
**APIs Necesarias:**
|
||
- `GET /api/cost-centers/tree` - Árbol completo
|
||
- `POST /api/cost-centers` - Crear
|
||
- `PUT /api/cost-centers/:id` - Actualizar
|
||
- `DELETE /api/cost-centers/:id` - Desactivar
|
||
- `POST /api/cost-centers/:id/impute` - Imputar costo
|
||
- `POST /api/cost-centers/:id/distribute-overhead` - Distribuir
|
||
- `GET /api/cost-centers/:id/report` - Reporte consolidado
|
||
|
||
**Componentes Frontend:**
|
||
- CostCenterTree (árbol recursivo)
|
||
- CostCenterForm (crear/editar)
|
||
- OverheadDistributionModal
|
||
- CostCenterReports
|
||
|
||
---
|
||
|
||
## 📊 Métricas de Éxito
|
||
|
||
- **Profundidad máxima soportada:** ≥10 niveles sin degradación
|
||
- **Tiempo de carga árbol:** <1s para 1000 centros
|
||
- **Precisión consolidación:** 100% (sin discrepancias)
|
||
- **Tiempo distribución overhead:** <5s para 100 proyectos
|
||
|
||
---
|
||
|
||
**Generado:** 2025-11-20
|
||
**Estado:** ✅ Listo para desarrollo
|