workspace-v1/projects/erp-construccion/docs/02-definicion-modulos/MAI-013-administracion-seguridad/historias-usuario/US-ADM-004-centros-costo.md

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

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

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

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

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

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

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

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

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

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

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