2001 lines
66 KiB
YAML
2001 lines
66 KiB
YAML
# ============================================================================
|
|
# MATRIZ DE TRAZABILIDAD - MAE-015 ACTIVOS FIJOS
|
|
# ============================================================================
|
|
# Proyecto: ERP Suite - Vertical Construcción
|
|
# Módulo: MAE-015 - Gestión de Activos Fijos
|
|
# Propósito: Control y administración de maquinaria pesada de construcción
|
|
# Fecha: 2025-12-06
|
|
# ============================================================================
|
|
|
|
metadata:
|
|
module_id: MAE-015
|
|
module_name: Activos Fijos
|
|
vertical: construccion
|
|
version: 1.0.0
|
|
status: planificado
|
|
owner: Equipo Verticales Construcción
|
|
description: >
|
|
Sistema de gestión de activos fijos orientado a maquinaria pesada de
|
|
construcción (excavadoras, grúas, retroexcavadoras, etc.) que incluye
|
|
control de depreciación, mantenimiento preventivo y baja de activos.
|
|
|
|
# ============================================================================
|
|
# REQUERIMIENTOS FUNCIONALES
|
|
# ============================================================================
|
|
|
|
functional_requirements:
|
|
|
|
# --------------------------------------------------------------------------
|
|
# RF-001: ALTA DE ACTIVOS FIJOS
|
|
# --------------------------------------------------------------------------
|
|
- id: RF-MAE015-001
|
|
name: Alta de Activos Fijos
|
|
priority: alta
|
|
status: pendiente
|
|
description: >
|
|
Registro y catalogación de nuevos activos fijos de maquinaria pesada
|
|
de construcción en el sistema, incluyendo datos técnicos, financieros
|
|
y de ubicación.
|
|
|
|
acceptance_criteria:
|
|
- criterion: Registro completo de datos del activo
|
|
description: >
|
|
El sistema debe permitir capturar: tipo de maquinaria, marca, modelo,
|
|
número de serie, año de fabricación, capacidad, especificaciones técnicas,
|
|
fecha de adquisición, costo de adquisición, proveedor, ubicación, centro
|
|
de costos, método de depreciación, vida útil estimada, valor residual.
|
|
validation: >
|
|
Formulario de alta con todos los campos requeridos y validaciones.
|
|
|
|
- criterion: Generación automática de código de activo
|
|
description: >
|
|
El sistema debe asignar automáticamente un código único al activo
|
|
basado en nomenclatura: [TIPO]-[AÑO]-[SECUENCIAL].
|
|
validation: >
|
|
Código generado automáticamente y sin duplicados.
|
|
|
|
- criterion: Carga de documentación soporte
|
|
description: >
|
|
Permitir adjuntar documentos: factura de compra, póliza de seguro,
|
|
manual de operación, certificados, garantías.
|
|
validation: >
|
|
Repositorio de documentos asociados al activo.
|
|
|
|
- criterion: Registro fotográfico del activo
|
|
description: >
|
|
Captura y almacenamiento de fotografías del activo en diferentes
|
|
ángulos y detalle de componentes principales.
|
|
validation: >
|
|
Galería de imágenes asociada al activo.
|
|
|
|
- criterion: Asignación de responsable
|
|
description: >
|
|
Designar responsable del activo (operador, supervisor, gerente de obra).
|
|
validation: >
|
|
Campo de responsable con búsqueda de usuarios activos.
|
|
|
|
business_rules:
|
|
- rule: El costo de adquisición debe ser mayor a cero
|
|
validation: Validación en formulario
|
|
|
|
- rule: La vida útil debe estar entre 1 y 50 años
|
|
validation: Rango permitido según normativa contable
|
|
|
|
- rule: El valor residual no puede ser mayor al 30% del costo de adquisición
|
|
validation: Validación cruzada de campos
|
|
|
|
- rule: La fecha de adquisición no puede ser futura
|
|
validation: Validación de fecha
|
|
|
|
- rule: Maquinaria pesada debe tener póliza de seguro obligatoria
|
|
validation: Campo de póliza requerido para categoría específica
|
|
|
|
user_stories:
|
|
- US-MAE015-001: Como gerente de activos, quiero registrar nueva maquinaria para tener control del inventario
|
|
- US-MAE015-002: Como contador, quiero capturar datos de adquisición para calcular depreciación
|
|
- US-MAE015-003: Como administrador de obra, quiero asignar responsables para el control de uso
|
|
|
|
technical_requirements:
|
|
- type: database
|
|
description: Tabla assets con campos completos
|
|
implementation: Schema con índices en código y tipo
|
|
|
|
- type: storage
|
|
description: Almacenamiento de documentos y fotografías
|
|
implementation: Integración con servicio de storage (S3/Azure Blob)
|
|
|
|
- type: validation
|
|
description: Validaciones de negocio en frontend y backend
|
|
implementation: Schemas de validación con Zod/Joi
|
|
|
|
- type: audit
|
|
description: Registro de creación y modificaciones
|
|
implementation: Triggers de auditoría automática
|
|
|
|
dependencies:
|
|
- module: MGN-001
|
|
requirement: Gestión de usuarios para asignar responsables
|
|
|
|
- module: MGN-005
|
|
requirement: Catálogos de tipos de maquinaria y marcas
|
|
|
|
- module: MGN-007
|
|
requirement: Auditoría de operaciones
|
|
|
|
test_scenarios:
|
|
- scenario: Alta exitosa de excavadora
|
|
steps:
|
|
- Ingresar datos completos de excavadora CAT 320D
|
|
- Adjuntar factura y póliza de seguro
|
|
- Cargar 4 fotografías
|
|
- Asignar responsable
|
|
- Guardar registro
|
|
expected: Activo creado con código generado y confirmación
|
|
|
|
- scenario: Validación de valor residual excesivo
|
|
steps:
|
|
- Ingresar costo de adquisición $500,000
|
|
- Ingresar valor residual $200,000 (40%)
|
|
expected: Error de validación, valor residual máximo 30%
|
|
|
|
- scenario: Alta sin póliza de seguro en maquinaria pesada
|
|
steps:
|
|
- Seleccionar tipo "Grúa Torre"
|
|
- No ingresar datos de póliza
|
|
- Intentar guardar
|
|
expected: Error, póliza de seguro obligatoria
|
|
|
|
implementation:
|
|
estimated_effort: 40 horas
|
|
complexity: media
|
|
components:
|
|
- AssetRegistrationForm
|
|
- AssetDocumentManager
|
|
- AssetPhotoGallery
|
|
- AssetCodeGenerator
|
|
endpoints:
|
|
- POST /api/v1/construction/assets
|
|
- POST /api/v1/construction/assets/{id}/documents
|
|
- POST /api/v1/construction/assets/{id}/photos
|
|
|
|
# --------------------------------------------------------------------------
|
|
# RF-002: DEPRECIACIÓN DE ACTIVOS
|
|
# --------------------------------------------------------------------------
|
|
- id: RF-MAE015-002
|
|
name: Depreciación de Activos
|
|
priority: alta
|
|
status: pendiente
|
|
description: >
|
|
Cálculo automático y registro de la depreciación de activos fijos
|
|
utilizando diferentes métodos contables, generación de reportes
|
|
y asientos contables correspondientes.
|
|
|
|
acceptance_criteria:
|
|
- criterion: Métodos de depreciación soportados
|
|
description: >
|
|
El sistema debe calcular depreciación por: línea recta, saldos
|
|
decrecientes, suma de dígitos, y unidades de producción (horas máquina).
|
|
validation: >
|
|
Configuración de método por activo y cálculo correcto.
|
|
|
|
- criterion: Cálculo automático mensual
|
|
description: >
|
|
Proceso batch que calcula depreciación mensual de todos los activos
|
|
activos al cierre de mes.
|
|
validation: >
|
|
Job programado que ejecuta cálculo y genera registros.
|
|
|
|
- criterion: Generación de asientos contables
|
|
description: >
|
|
Crear automáticamente asientos de depreciación con cuentas de
|
|
gasto depreciación y depreciación acumulada.
|
|
validation: >
|
|
Asientos generados según plan de cuentas configurado.
|
|
|
|
- criterion: Historial de depreciación
|
|
description: >
|
|
Mantener registro mensual de depreciación acumulada y valor en libros.
|
|
validation: >
|
|
Tabla de movimientos con histórico completo.
|
|
|
|
- criterion: Reportes de depreciación
|
|
description: >
|
|
Generar reporte de depreciación mensual, anual, y proyección de
|
|
vida útil restante.
|
|
validation: >
|
|
Reportes con totales por tipo, centro de costos, y estado.
|
|
|
|
business_rules:
|
|
- rule: La depreciación inicia el mes siguiente a la fecha de adquisición
|
|
validation: Lógica de cálculo de períodos
|
|
|
|
- rule: No se deprecia el valor residual del activo
|
|
validation: Cálculo considera valor residual
|
|
|
|
- rule: Activos dados de baja no se deprecian
|
|
validation: Filtro de activos activos
|
|
|
|
- rule: Método de unidades de producción requiere registro de horas trabajadas
|
|
validation: Validación de datos requeridos
|
|
|
|
- rule: Cambio de método de depreciación requiere autorización
|
|
validation: Workflow de aprobación
|
|
|
|
user_stories:
|
|
- US-MAE015-004: Como contador, quiero calcular depreciación automática para cierre mensual
|
|
- US-MAE015-005: Como auditor, quiero consultar historial de depreciación para verificar cálculos
|
|
- US-MAE015-006: Como CFO, quiero reportes de depreciación para análisis financiero
|
|
|
|
technical_requirements:
|
|
- type: batch
|
|
description: Proceso programado de cálculo mensual
|
|
implementation: Job scheduler (cron/agenda) para cierre de mes
|
|
|
|
- type: calculation
|
|
description: Algoritmos de depreciación
|
|
implementation: Service layer con métodos de cálculo
|
|
|
|
- type: integration
|
|
description: Integración con módulo contable
|
|
implementation: API calls para generación de asientos
|
|
|
|
- type: reporting
|
|
description: Generación de reportes
|
|
implementation: Query builders y exportación a Excel/PDF
|
|
|
|
dependencies:
|
|
- module: FIN-001
|
|
requirement: Integración con contabilidad para asientos
|
|
|
|
- module: MGN-009
|
|
requirement: Motor de reportes
|
|
|
|
- module: MGN-006
|
|
requirement: Configuración de plan de cuentas
|
|
|
|
test_scenarios:
|
|
- scenario: Depreciación línea recta
|
|
steps:
|
|
- Crear activo con costo $120,000, vida útil 10 años, valor residual $12,000
|
|
- Ejecutar cálculo mensual
|
|
expected: Depreciación mensual de $900 (($120,000-$12,000)/120 meses)
|
|
|
|
- scenario: Depreciación por unidades de producción
|
|
steps:
|
|
- Activo con 10,000 horas de vida útil estimada
|
|
- Registrar 150 horas trabajadas en el mes
|
|
- Ejecutar cálculo
|
|
expected: Depreciación proporcional a horas trabajadas
|
|
|
|
- scenario: No depreciar activo dado de baja
|
|
steps:
|
|
- Dar de baja activo el día 15
|
|
- Ejecutar cálculo mensual
|
|
expected: No generar depreciación para ese mes
|
|
|
|
implementation:
|
|
estimated_effort: 60 horas
|
|
complexity: alta
|
|
components:
|
|
- DepreciationCalculator
|
|
- DepreciationBatchJob
|
|
- DepreciationReportGenerator
|
|
- AccountingIntegrationService
|
|
endpoints:
|
|
- POST /api/v1/construction/assets/depreciation/calculate
|
|
- GET /api/v1/construction/assets/{id}/depreciation/history
|
|
- GET /api/v1/construction/assets/depreciation/report
|
|
|
|
# --------------------------------------------------------------------------
|
|
# RF-003: MANTENIMIENTO PREVENTIVO
|
|
# --------------------------------------------------------------------------
|
|
- id: RF-MAE015-003
|
|
name: Mantenimiento Preventivo
|
|
priority: alta
|
|
status: pendiente
|
|
description: >
|
|
Sistema de programación, seguimiento y control de mantenimientos
|
|
preventivos para maquinaria pesada basado en calendario, horas de
|
|
operación o kilómetros recorridos, con alertas y registro de actividades.
|
|
|
|
acceptance_criteria:
|
|
- criterion: Planes de mantenimiento configurables
|
|
description: >
|
|
Definir planes de mantenimiento preventivo por tipo de maquinaria
|
|
con periodicidad (días, horas máquina, km) y actividades a realizar.
|
|
validation: >
|
|
Catálogo de planes con actividades y frecuencias configurables.
|
|
|
|
- criterion: Programación automática de mantenimientos
|
|
description: >
|
|
Generar automáticamente órdenes de mantenimiento según plan
|
|
y fecha/horas programadas.
|
|
validation: >
|
|
Órdenes creadas automáticamente según calendario.
|
|
|
|
- criterion: Alertas y notificaciones
|
|
description: >
|
|
Enviar alertas cuando se aproxima mantenimiento programado (7 días,
|
|
50 horas antes) y alertas de mantenimientos vencidos.
|
|
validation: >
|
|
Notificaciones por email y en sistema a responsables.
|
|
|
|
- criterion: Registro de ejecución de mantenimiento
|
|
description: >
|
|
Capturar datos de mantenimiento realizado: fecha, técnico, actividades
|
|
ejecutadas, repuestos utilizados, horas trabajadas, observaciones,
|
|
evidencias fotográficas.
|
|
validation: >
|
|
Formulario de cierre de orden con todos los datos.
|
|
|
|
- criterion: Control de costos de mantenimiento
|
|
description: >
|
|
Registrar costos de mano de obra, repuestos y servicios externos
|
|
asociados a cada mantenimiento.
|
|
validation: >
|
|
Detalle de costos por orden y totales por activo.
|
|
|
|
- criterion: Historial de mantenimientos
|
|
description: >
|
|
Consultar historial completo de mantenimientos preventivos y correctivos
|
|
realizados a cada activo.
|
|
validation: >
|
|
Vista de timeline con todos los mantenimientos.
|
|
|
|
business_rules:
|
|
- rule: Maquinaria con mantenimiento vencido no puede ser asignada a obras
|
|
validation: Validación en asignación de recursos
|
|
|
|
- rule: Mantenimientos críticos (>100 hrs vencidos) requieren justificación
|
|
validation: Campo obligatorio de justificación
|
|
|
|
- rule: Técnico debe estar certificado para el tipo de maquinaria
|
|
validation: Verificación de certificaciones
|
|
|
|
- rule: Repuestos utilizados deben descontarse de inventario
|
|
validation: Integración con módulo de inventarios
|
|
|
|
- rule: Mantenimiento mayor (>500 hrs) requiere aprobación gerencial
|
|
validation: Workflow de aprobación
|
|
|
|
user_stories:
|
|
- US-MAE015-007: Como jefe de mantenimiento, quiero programar mantenimientos para evitar fallas
|
|
- US-MAE015-008: Como operador, quiero recibir alertas de mantenimiento para no usar equipo vencido
|
|
- US-MAE015-009: Como gerente, quiero consultar costos de mantenimiento para optimizar presupuesto
|
|
|
|
technical_requirements:
|
|
- type: scheduling
|
|
description: Motor de programación de mantenimientos
|
|
implementation: Scheduler con reglas de periodicidad
|
|
|
|
- type: notifications
|
|
description: Sistema de alertas y notificaciones
|
|
implementation: Integración con módulo de notificaciones
|
|
|
|
- type: workflow
|
|
description: Flujo de trabajo de órdenes
|
|
implementation: State machine para estados de orden
|
|
|
|
- type: integration
|
|
description: Integración con inventarios y contabilidad
|
|
implementation: APIs para movimientos de stock y costos
|
|
|
|
dependencies:
|
|
- module: MGN-008
|
|
requirement: Sistema de notificaciones para alertas
|
|
|
|
- module: INV-001
|
|
requirement: Control de inventario de repuestos
|
|
|
|
- module: MGN-007
|
|
requirement: Auditoría de operaciones
|
|
|
|
- module: MGN-001
|
|
requirement: Gestión de usuarios y certificaciones
|
|
|
|
test_scenarios:
|
|
- scenario: Generación automática de orden por horas
|
|
steps:
|
|
- Configurar plan: mantenimiento cada 250 horas
|
|
- Registrar 240 horas en activo
|
|
- Registrar 15 horas más (total 255)
|
|
expected: Orden de mantenimiento generada automáticamente
|
|
|
|
- scenario: Alerta de mantenimiento próximo
|
|
steps:
|
|
- Mantenimiento programado para dentro de 5 días
|
|
- Ejecutar job de alertas
|
|
expected: Notificación enviada a responsable y jefe de mantenimiento
|
|
|
|
- scenario: Cierre de orden con consumo de repuestos
|
|
steps:
|
|
- Ejecutar mantenimiento
|
|
- Registrar 2 filtros y 20 litros de aceite
|
|
- Cerrar orden
|
|
expected: Repuestos descontados de inventario y costo registrado
|
|
|
|
- scenario: Bloqueo de asignación por mantenimiento vencido
|
|
steps:
|
|
- Activo con mantenimiento vencido hace 15 días
|
|
- Intentar asignar a obra
|
|
expected: Error, mantenimiento vencido debe completarse primero
|
|
|
|
implementation:
|
|
estimated_effort: 80 horas
|
|
complexity: alta
|
|
components:
|
|
- MaintenancePlanManager
|
|
- MaintenanceScheduler
|
|
- MaintenanceOrderWorkflow
|
|
- MaintenanceAlertService
|
|
- MaintenanceCostTracker
|
|
endpoints:
|
|
- POST /api/v1/construction/assets/maintenance/plans
|
|
- POST /api/v1/construction/assets/maintenance/orders
|
|
- PATCH /api/v1/construction/assets/maintenance/orders/{id}/complete
|
|
- GET /api/v1/construction/assets/{id}/maintenance/history
|
|
- GET /api/v1/construction/assets/maintenance/alerts
|
|
|
|
# --------------------------------------------------------------------------
|
|
# RF-004: BAJA DE ACTIVOS
|
|
# --------------------------------------------------------------------------
|
|
- id: RF-MAE015-004
|
|
name: Baja de Activos Fijos
|
|
priority: media
|
|
status: pendiente
|
|
description: >
|
|
Proceso de baja de activos fijos por venta, donación, robo, obsolescencia
|
|
o deterioro total, incluyendo cálculo de utilidad/pérdida, generación
|
|
de asientos contables y actualización de inventario.
|
|
|
|
acceptance_criteria:
|
|
- criterion: Tipos de baja soportados
|
|
description: >
|
|
El sistema debe permitir dar de baja por: venta, donación, robo,
|
|
siniestro, obsolescencia, chatarra, permuta.
|
|
validation: >
|
|
Catálogo de motivos de baja con flujos específicos.
|
|
|
|
- criterion: Cálculo de utilidad o pérdida
|
|
description: >
|
|
Calcular automáticamente utilidad o pérdida en la disposición
|
|
considerando: valor en libros, precio de venta, gastos de venta,
|
|
valor recuperado de seguros.
|
|
validation: >
|
|
Cálculo correcto y presentación de detalle.
|
|
|
|
- criterion: Generación de asientos contables
|
|
description: >
|
|
Crear asientos de baja que afecten: depreciación acumulada,
|
|
costo del activo, utilidad/pérdida en venta, efectivo/cuentas por cobrar.
|
|
validation: >
|
|
Asientos según tipo de baja y normativa contable.
|
|
|
|
- criterion: Documentación de baja
|
|
description: >
|
|
Adjuntar documentos soporte: contrato de venta, acta de donación,
|
|
denuncia de robo, dictamen de perito, autorización gerencial.
|
|
validation: >
|
|
Repositorio de documentos según tipo de baja.
|
|
|
|
- criterion: Workflow de aprobación
|
|
description: >
|
|
Solicitud de baja requiere aprobación de jefe de activos y gerencia
|
|
financiera antes de ejecutarse.
|
|
validation: >
|
|
Flujo de aprobación multinivel implementado.
|
|
|
|
- criterion: Actualización de inventario
|
|
description: >
|
|
Marcar activo como "Dado de baja" en inventario y excluir de reportes
|
|
de activos activos, pero mantener en histórico.
|
|
validation: >
|
|
Estado actualizado y filtros en consultas.
|
|
|
|
business_rules:
|
|
- rule: No se puede dar de baja activo con mantenimientos pendientes sin autorización
|
|
validation: Verificación de órdenes abiertas
|
|
|
|
- rule: Baja por venta requiere precio mínimo del 50% del valor en libros
|
|
validation: Validación de precio vs valor contable
|
|
|
|
- rule: Activo con garantía vigente requiere notificación a proveedor
|
|
validation: Alerta en proceso de baja
|
|
|
|
- rule: Baja por robo requiere denuncia policial adjunta
|
|
validation: Validación de documento obligatorio
|
|
|
|
- rule: Activos mayores a $100,000 requieren aprobación de dirección general
|
|
validation: Nivel de aprobación según monto
|
|
|
|
user_stories:
|
|
- US-MAE015-010: Como gerente de activos, quiero dar de baja maquinaria obsoleta para actualizar inventario
|
|
- US-MAE015-011: Como contador, quiero calcular utilidad/pérdida en venta para estados financieros
|
|
- US-MAE015-012: Como auditor, quiero verificar documentación de bajas para cumplimiento normativo
|
|
|
|
technical_requirements:
|
|
- type: workflow
|
|
description: Sistema de aprobaciones multinivel
|
|
implementation: Workflow engine con roles y permisos
|
|
|
|
- type: calculation
|
|
description: Cálculo de utilidad/pérdida
|
|
implementation: Service con fórmulas contables
|
|
|
|
- type: integration
|
|
description: Integración con contabilidad
|
|
implementation: Generación de asientos contables
|
|
|
|
- type: audit
|
|
description: Auditoría completa de bajas
|
|
implementation: Log detallado de todas las operaciones
|
|
|
|
dependencies:
|
|
- module: FIN-001
|
|
requirement: Módulo contable para asientos
|
|
|
|
- module: MGN-001
|
|
requirement: Usuarios y roles para aprobaciones
|
|
|
|
- module: MGN-007
|
|
requirement: Auditoría de operaciones críticas
|
|
|
|
- module: MGN-008
|
|
requirement: Notificaciones de aprobaciones
|
|
|
|
test_scenarios:
|
|
- scenario: Baja por venta con utilidad
|
|
steps:
|
|
- Activo con costo $100,000, depreciación acumulada $60,000, valor en libros $40,000
|
|
- Solicitar baja por venta en $50,000
|
|
- Aprobar solicitud
|
|
- Confirmar baja
|
|
expected: Utilidad en venta $10,000, asientos generados, activo marcado como dado de baja
|
|
|
|
- scenario: Baja por robo sin denuncia
|
|
steps:
|
|
- Seleccionar motivo "Robo"
|
|
- No adjuntar denuncia policial
|
|
- Intentar enviar solicitud
|
|
expected: Error, denuncia policial obligatoria
|
|
|
|
- scenario: Baja rechazada por precio bajo
|
|
steps:
|
|
- Activo con valor en libros $80,000
|
|
- Solicitar baja por venta en $30,000 (37.5%)
|
|
expected: Alerta, precio menor al 50% del valor en libros
|
|
|
|
- scenario: Workflow de aprobación exitoso
|
|
steps:
|
|
- Solicitar baja de excavadora ($150,000)
|
|
- Jefe de activos aprueba
|
|
- Gerente financiero aprueba
|
|
- Director general aprueba (>$100,000)
|
|
- Sistema ejecuta baja
|
|
expected: Baja procesada, asientos contables generados, notificaciones enviadas
|
|
|
|
implementation:
|
|
estimated_effort: 50 horas
|
|
complexity: media-alta
|
|
components:
|
|
- AssetDisposalWorkflow
|
|
- DisposalCalculator
|
|
- DisposalApprovalManager
|
|
- DisposalAccountingService
|
|
endpoints:
|
|
- POST /api/v1/construction/assets/{id}/disposal/request
|
|
- PATCH /api/v1/construction/assets/disposal/{id}/approve
|
|
- PATCH /api/v1/construction/assets/disposal/{id}/reject
|
|
- POST /api/v1/construction/assets/disposal/{id}/execute
|
|
- GET /api/v1/construction/assets/disposal/pending-approval
|
|
|
|
# ============================================================================
|
|
# REQUERIMIENTOS NO FUNCIONALES
|
|
# ============================================================================
|
|
|
|
non_functional_requirements:
|
|
|
|
- id: NFR-MAE015-001
|
|
category: performance
|
|
description: Cálculo de depreciación de 10,000 activos en menos de 5 minutos
|
|
measurement: Tiempo de ejecución del batch job
|
|
priority: alta
|
|
|
|
- id: NFR-MAE015-002
|
|
category: performance
|
|
description: Consulta de historial de mantenimiento en menos de 2 segundos
|
|
measurement: Response time de endpoint
|
|
priority: media
|
|
|
|
- id: NFR-MAE015-003
|
|
category: security
|
|
description: Encriptación de documentos sensibles (facturas, contratos)
|
|
measurement: Documentos almacenados con encriptación AES-256
|
|
priority: alta
|
|
|
|
- id: NFR-MAE015-004
|
|
category: availability
|
|
description: Disponibilidad del sistema 99.5% (excluyendo mantenimientos programados)
|
|
measurement: Uptime monitoring
|
|
priority: media
|
|
|
|
- id: NFR-MAE015-005
|
|
category: auditability
|
|
description: Registro completo de todas las operaciones críticas (alta, baja, cambios)
|
|
measurement: 100% de operaciones auditadas
|
|
priority: alta
|
|
|
|
- id: NFR-MAE015-006
|
|
category: usability
|
|
description: Interfaz mobile-responsive para registro de mantenimientos en campo
|
|
measurement: UI funcional en tablets y smartphones
|
|
priority: media
|
|
|
|
- id: NFR-MAE015-007
|
|
category: scalability
|
|
description: Soportar hasta 50,000 activos sin degradación de performance
|
|
measurement: Load testing con 50K registros
|
|
priority: media
|
|
|
|
- id: NFR-MAE015-008
|
|
category: integration
|
|
description: APIs REST documentadas con OpenAPI/Swagger para integraciones
|
|
measurement: Documentación completa y actualizada
|
|
priority: alta
|
|
|
|
# ============================================================================
|
|
# REGLAS DE NEGOCIO TRANSVERSALES
|
|
# ============================================================================
|
|
|
|
business_rules:
|
|
|
|
- id: BR-MAE015-001
|
|
name: Segregación de funciones
|
|
description: >
|
|
Usuario que da de alta un activo no puede aprobarlo para uso.
|
|
Usuario que solicita baja no puede aprobarla.
|
|
impact: Todos los módulos
|
|
validation: Permisos y workflow
|
|
|
|
- id: BR-MAE015-002
|
|
name: Inmutabilidad de registros contables
|
|
description: >
|
|
Una vez generados los asientos contables de depreciación o baja,
|
|
no pueden modificarse, solo revertirse con asientos de ajuste.
|
|
impact: Depreciación y Baja
|
|
validation: Permisos y lógica de negocio
|
|
|
|
- id: BR-MAE015-003
|
|
name: Unicidad de códigos de activo
|
|
description: >
|
|
Cada activo debe tener un código único que no se reutiliza aun
|
|
después de darlo de baja.
|
|
impact: Alta de activos
|
|
validation: Constraint en base de datos
|
|
|
|
- id: BR-MAE015-004
|
|
name: Trazabilidad de costos
|
|
description: >
|
|
Todo costo asociado a un activo (adquisición, mantenimiento, mejoras)
|
|
debe ser trazable y auditable.
|
|
impact: Todos los módulos
|
|
validation: Registro de movimientos
|
|
|
|
- id: BR-MAE015-005
|
|
name: Alertas tempranas
|
|
description: >
|
|
Sistema debe alertar proactivamente sobre: mantenimientos próximos,
|
|
fin de garantía, fin de vida útil, seguros por vencer.
|
|
impact: Todo el módulo
|
|
validation: Jobs programados de alertas
|
|
|
|
# ============================================================================
|
|
# HISTORIAS DE USUARIO
|
|
# ============================================================================
|
|
|
|
user_stories:
|
|
|
|
- id: US-MAE015-001
|
|
title: Registro de nueva excavadora
|
|
as_a: Gerente de activos
|
|
i_want: Registrar nueva maquinaria pesada en el sistema
|
|
so_that: Pueda tener control del inventario y comenzar su depreciación
|
|
acceptance_criteria:
|
|
- Formulario con todos los datos técnicos y financieros
|
|
- Generación automática de código de activo
|
|
- Carga de documentación soporte
|
|
- Asignación de responsable
|
|
priority: alta
|
|
story_points: 8
|
|
sprint: 1
|
|
|
|
- id: US-MAE015-002
|
|
title: Captura de datos de adquisición
|
|
as_a: Contador
|
|
i_want: Capturar todos los datos financieros de la adquisición
|
|
so_that: Pueda calcular correctamente la depreciación
|
|
acceptance_criteria:
|
|
- Campos de costo, fecha, método de depreciación, vida útil
|
|
- Validaciones de rangos y valores
|
|
- Selección de centro de costos
|
|
priority: alta
|
|
story_points: 5
|
|
sprint: 1
|
|
|
|
- id: US-MAE015-003
|
|
title: Asignación de responsables
|
|
as_a: Administrador de obra
|
|
i_want: Asignar responsables a cada activo
|
|
so_that: Pueda tener control de quién usa cada maquinaria
|
|
acceptance_criteria:
|
|
- Búsqueda de usuarios
|
|
- Historial de asignaciones
|
|
- Notificación al responsable
|
|
priority: media
|
|
story_points: 3
|
|
sprint: 1
|
|
|
|
- id: US-MAE015-004
|
|
title: Cálculo automático de depreciación
|
|
as_a: Contador
|
|
i_want: Que el sistema calcule automáticamente la depreciación mensual
|
|
so_that: No tenga que hacerlo manualmente cada mes
|
|
acceptance_criteria:
|
|
- Job programado de cálculo mensual
|
|
- Soporte de múltiples métodos de depreciación
|
|
- Generación de asientos contables
|
|
priority: alta
|
|
story_points: 13
|
|
sprint: 2
|
|
|
|
- id: US-MAE015-005
|
|
title: Consulta de historial de depreciación
|
|
as_a: Auditor
|
|
i_want: Consultar el historial completo de depreciación de un activo
|
|
so_that: Pueda verificar la correctitud de los cálculos
|
|
acceptance_criteria:
|
|
- Vista de timeline con todos los períodos
|
|
- Detalle de cálculo por período
|
|
- Exportación a Excel
|
|
priority: media
|
|
story_points: 5
|
|
sprint: 2
|
|
|
|
- id: US-MAE015-006
|
|
title: Reportes de depreciación
|
|
as_a: CFO
|
|
i_want: Generar reportes de depreciación por diferentes criterios
|
|
so_that: Pueda analizar el impacto financiero
|
|
acceptance_criteria:
|
|
- Reporte mensual y anual
|
|
- Filtros por tipo, centro de costos, estado
|
|
- Exportación a PDF y Excel
|
|
priority: media
|
|
story_points: 8
|
|
sprint: 2
|
|
|
|
- id: US-MAE015-007
|
|
title: Programación de mantenimientos preventivos
|
|
as_a: Jefe de mantenimiento
|
|
i_want: Programar mantenimientos preventivos para cada maquinaria
|
|
so_that: Pueda evitar fallas y prolongar vida útil
|
|
acceptance_criteria:
|
|
- Planes de mantenimiento por tipo de maquinaria
|
|
- Generación automática de órdenes
|
|
- Alertas de mantenimientos próximos
|
|
priority: alta
|
|
story_points: 13
|
|
sprint: 3
|
|
|
|
- id: US-MAE015-008
|
|
title: Alertas de mantenimiento
|
|
as_a: Operador de maquinaria
|
|
i_want: Recibir alertas cuando se aproxima un mantenimiento
|
|
so_that: No use equipo con mantenimiento vencido
|
|
acceptance_criteria:
|
|
- Notificaciones por email y en sistema
|
|
- Alertas con 7 días y 50 horas de anticipación
|
|
- Bloqueo de uso si está vencido
|
|
priority: alta
|
|
story_points: 8
|
|
sprint: 3
|
|
|
|
- id: US-MAE015-009
|
|
title: Consulta de costos de mantenimiento
|
|
as_a: Gerente de operaciones
|
|
i_want: Consultar los costos acumulados de mantenimiento por activo
|
|
so_that: Pueda optimizar presupuesto y tomar decisiones
|
|
acceptance_criteria:
|
|
- Vista de costos por activo y período
|
|
- Desglose por tipo de costo
|
|
- Gráficas de tendencia
|
|
priority: media
|
|
story_points: 5
|
|
sprint: 3
|
|
|
|
- id: US-MAE015-010
|
|
title: Baja de maquinaria obsoleta
|
|
as_a: Gerente de activos
|
|
i_want: Dar de baja maquinaria que ya no se usa
|
|
so_that: Pueda mantener actualizado el inventario
|
|
acceptance_criteria:
|
|
- Selección de motivo de baja
|
|
- Workflow de aprobación
|
|
- Documentación soporte
|
|
priority: media
|
|
story_points: 8
|
|
sprint: 4
|
|
|
|
- id: US-MAE015-011
|
|
title: Cálculo de utilidad/pérdida en venta
|
|
as_a: Contador
|
|
i_want: Que el sistema calcule automáticamente utilidad o pérdida en venta
|
|
so_that: Pueda registrarlo correctamente en estados financieros
|
|
acceptance_criteria:
|
|
- Cálculo automático considerando valor en libros
|
|
- Generación de asientos contables
|
|
- Detalle de cálculo
|
|
priority: alta
|
|
story_points: 8
|
|
sprint: 4
|
|
|
|
- id: US-MAE015-012
|
|
title: Verificación de documentación de bajas
|
|
as_a: Auditor
|
|
i_want: Verificar que todas las bajas tengan documentación completa
|
|
so_that: Cumpla con requisitos normativos
|
|
acceptance_criteria:
|
|
- Repositorio de documentos por baja
|
|
- Checklist de documentos obligatorios
|
|
- Reporte de bajas sin documentación completa
|
|
priority: media
|
|
story_points: 5
|
|
sprint: 4
|
|
|
|
# ============================================================================
|
|
# CASOS DE USO
|
|
# ============================================================================
|
|
|
|
use_cases:
|
|
|
|
- id: UC-MAE015-001
|
|
name: Registrar nuevo activo de maquinaria pesada
|
|
actor: Gerente de activos
|
|
preconditions:
|
|
- Usuario autenticado con permiso de alta de activos
|
|
- Catálogos de tipos y marcas configurados
|
|
postconditions:
|
|
- Activo registrado en sistema
|
|
- Código único asignado
|
|
- Auditoría registrada
|
|
main_flow:
|
|
- Actor selecciona opción "Nuevo Activo"
|
|
- Sistema presenta formulario de registro
|
|
- Actor ingresa datos técnicos y financieros
|
|
- Actor adjunta documentos soporte
|
|
- Actor carga fotografías
|
|
- Actor asigna responsable
|
|
- Sistema valida datos
|
|
- Sistema genera código único
|
|
- Sistema guarda registro
|
|
- Sistema envía notificación a responsable
|
|
- Sistema muestra confirmación
|
|
alternative_flows:
|
|
- "3a. Datos inválidos: Sistema muestra errores, actor corrige"
|
|
- "7a. Código duplicado: Sistema regenera código"
|
|
related_requirements:
|
|
- RF-MAE015-001
|
|
|
|
- id: UC-MAE015-002
|
|
name: Ejecutar cálculo mensual de depreciación
|
|
actor: Sistema (Job programado)
|
|
preconditions:
|
|
- Es cierre de mes
|
|
- Existen activos activos
|
|
postconditions:
|
|
- Depreciación calculada para todos los activos
|
|
- Asientos contables generados
|
|
- Notificaciones enviadas
|
|
main_flow:
|
|
- Job se activa al cierre de mes
|
|
- Sistema obtiene lista de activos activos
|
|
- Para cada activo, sistema calcula depreciación según método
|
|
- Sistema registra movimiento de depreciación
|
|
- Sistema genera asiento contable
|
|
- Sistema actualiza valor en libros
|
|
- Sistema envía reporte a contabilidad
|
|
- Sistema registra log de ejecución
|
|
alternative_flows:
|
|
- "3a. Error en cálculo: Sistema registra error y continúa con siguiente"
|
|
- "5a. Error en asiento: Sistema marca para revisión manual"
|
|
related_requirements:
|
|
- RF-MAE015-002
|
|
|
|
- id: UC-MAE015-003
|
|
name: Registrar ejecución de mantenimiento preventivo
|
|
actor: Técnico de mantenimiento
|
|
preconditions:
|
|
- Orden de mantenimiento generada
|
|
- Técnico con certificación para el tipo de maquinaria
|
|
postconditions:
|
|
- Mantenimiento registrado
|
|
- Repuestos descontados de inventario
|
|
- Costos registrados
|
|
- Próximo mantenimiento programado
|
|
main_flow:
|
|
- Actor abre orden de mantenimiento
|
|
- Actor ejecuta actividades programadas
|
|
- Actor ingresa a sistema
|
|
- Actor marca actividades completadas
|
|
- Actor registra repuestos utilizados
|
|
- Actor registra horas de mano de obra
|
|
- Actor adjunta evidencias fotográficas
|
|
- Actor ingresa observaciones
|
|
- Sistema valida disponibilidad de repuestos
|
|
- Sistema descuenta repuestos de inventario
|
|
- Sistema calcula costo total
|
|
- Sistema cierra orden
|
|
- Sistema programa próximo mantenimiento
|
|
- Sistema envía notificación a jefe de mantenimiento
|
|
alternative_flows:
|
|
- "9a. Repuestos no disponibles: Sistema alerta, actor gestiona pedido"
|
|
- "12a. Problemas detectados: Sistema genera orden correctiva"
|
|
related_requirements:
|
|
- RF-MAE015-003
|
|
|
|
- id: UC-MAE015-004
|
|
name: Procesar baja de activo por venta
|
|
actor: Gerente de activos
|
|
preconditions:
|
|
- Activo existe y está activo
|
|
- Usuario con permiso de solicitar bajas
|
|
postconditions:
|
|
- Baja aprobada y ejecutada
|
|
- Utilidad/pérdida calculada
|
|
- Asientos contables generados
|
|
- Activo marcado como dado de baja
|
|
main_flow:
|
|
- Actor selecciona activo
|
|
- Actor selecciona "Solicitar baja"
|
|
- Actor selecciona motivo "Venta"
|
|
- Sistema muestra valor en libros actual
|
|
- Actor ingresa precio de venta y comprador
|
|
- Sistema calcula utilidad o pérdida
|
|
- Actor adjunta contrato de venta
|
|
- Actor envía solicitud
|
|
- Sistema notifica a jefe de activos
|
|
- Jefe de activos aprueba
|
|
- Sistema notifica a gerente financiero
|
|
- Gerente financiero aprueba
|
|
- Sistema ejecuta baja
|
|
- Sistema genera asientos contables
|
|
- Sistema actualiza estado del activo
|
|
- Sistema envía confirmación
|
|
alternative_flows:
|
|
- "6a. Precio < 50% valor en libros: Sistema alerta, requiere justificación"
|
|
- "10a. Jefe rechaza: Sistema notifica actor, fin del caso de uso"
|
|
- "12a. Gerente rechaza: Sistema notifica actor, fin del caso de uso"
|
|
related_requirements:
|
|
- RF-MAE015-004
|
|
|
|
# ============================================================================
|
|
# MODELO DE DATOS
|
|
# ============================================================================
|
|
|
|
data_model:
|
|
|
|
entities:
|
|
|
|
- name: Asset
|
|
description: Activo fijo de maquinaria pesada
|
|
attributes:
|
|
- name: id
|
|
type: uuid
|
|
description: Identificador único
|
|
constraints: [primary_key]
|
|
|
|
- name: code
|
|
type: string(20)
|
|
description: Código del activo (EXC-2025-001)
|
|
constraints: [unique, not_null]
|
|
|
|
- name: asset_type_id
|
|
type: uuid
|
|
description: Tipo de maquinaria
|
|
constraints: [foreign_key, not_null]
|
|
|
|
- name: brand
|
|
type: string(100)
|
|
description: Marca
|
|
constraints: [not_null]
|
|
|
|
- name: model
|
|
type: string(100)
|
|
description: Modelo
|
|
constraints: [not_null]
|
|
|
|
- name: serial_number
|
|
type: string(100)
|
|
description: Número de serie
|
|
constraints: [unique]
|
|
|
|
- name: manufacturing_year
|
|
type: integer
|
|
description: Año de fabricación
|
|
|
|
- name: acquisition_date
|
|
type: date
|
|
description: Fecha de adquisición
|
|
constraints: [not_null]
|
|
|
|
- name: acquisition_cost
|
|
type: decimal(15,2)
|
|
description: Costo de adquisición
|
|
constraints: [not_null, positive]
|
|
|
|
- name: supplier_id
|
|
type: uuid
|
|
description: Proveedor
|
|
constraints: [foreign_key]
|
|
|
|
- name: depreciation_method
|
|
type: enum
|
|
description: Método de depreciación
|
|
values: [straight_line, declining_balance, sum_of_digits, units_of_production]
|
|
constraints: [not_null]
|
|
|
|
- name: useful_life_years
|
|
type: integer
|
|
description: Vida útil en años
|
|
constraints: [not_null, between_1_and_50]
|
|
|
|
- name: residual_value
|
|
type: decimal(15,2)
|
|
description: Valor residual
|
|
constraints: [not_null, max_30_percent_of_cost]
|
|
|
|
- name: current_book_value
|
|
type: decimal(15,2)
|
|
description: Valor en libros actual
|
|
constraints: [not_null]
|
|
|
|
- name: accumulated_depreciation
|
|
type: decimal(15,2)
|
|
description: Depreciación acumulada
|
|
constraints: [not_null, default_0]
|
|
|
|
- name: location
|
|
type: string(200)
|
|
description: Ubicación física
|
|
|
|
- name: cost_center_id
|
|
type: uuid
|
|
description: Centro de costos
|
|
constraints: [foreign_key]
|
|
|
|
- name: responsible_user_id
|
|
type: uuid
|
|
description: Usuario responsable
|
|
constraints: [foreign_key]
|
|
|
|
- name: status
|
|
type: enum
|
|
description: Estado del activo
|
|
values: [active, in_maintenance, inactive, disposed]
|
|
constraints: [not_null, default_active]
|
|
|
|
- name: insurance_policy_number
|
|
type: string(100)
|
|
description: Número de póliza de seguro
|
|
|
|
- name: insurance_expiry_date
|
|
type: date
|
|
description: Fecha de vencimiento del seguro
|
|
|
|
- name: warranty_expiry_date
|
|
type: date
|
|
description: Fecha de vencimiento de garantía
|
|
|
|
- name: technical_specs
|
|
type: jsonb
|
|
description: Especificaciones técnicas en JSON
|
|
|
|
- name: notes
|
|
type: text
|
|
description: Observaciones
|
|
|
|
- name: tenant_id
|
|
type: uuid
|
|
description: Tenant (multitenancy)
|
|
constraints: [foreign_key, not_null]
|
|
|
|
- name: created_at
|
|
type: timestamp
|
|
constraints: [not_null, default_now]
|
|
|
|
- name: updated_at
|
|
type: timestamp
|
|
constraints: [not_null, default_now]
|
|
|
|
- name: created_by
|
|
type: uuid
|
|
constraints: [foreign_key, not_null]
|
|
|
|
- name: updated_by
|
|
type: uuid
|
|
constraints: [foreign_key]
|
|
|
|
indexes:
|
|
- fields: [code]
|
|
unique: true
|
|
- fields: [asset_type_id]
|
|
- fields: [status]
|
|
- fields: [tenant_id, status]
|
|
- fields: [responsible_user_id]
|
|
|
|
- name: AssetDocument
|
|
description: Documentos asociados a activos
|
|
attributes:
|
|
- name: id
|
|
type: uuid
|
|
constraints: [primary_key]
|
|
- name: asset_id
|
|
type: uuid
|
|
constraints: [foreign_key, not_null]
|
|
- name: document_type
|
|
type: enum
|
|
values: [invoice, insurance_policy, manual, certificate, warranty, contract, other]
|
|
constraints: [not_null]
|
|
- name: file_name
|
|
type: string(255)
|
|
constraints: [not_null]
|
|
- name: file_path
|
|
type: string(500)
|
|
constraints: [not_null]
|
|
- name: file_size
|
|
type: bigint
|
|
- name: mime_type
|
|
type: string(100)
|
|
- name: uploaded_at
|
|
type: timestamp
|
|
constraints: [not_null, default_now]
|
|
- name: uploaded_by
|
|
type: uuid
|
|
constraints: [foreign_key, not_null]
|
|
|
|
- name: AssetPhoto
|
|
description: Fotografías de activos
|
|
attributes:
|
|
- name: id
|
|
type: uuid
|
|
constraints: [primary_key]
|
|
- name: asset_id
|
|
type: uuid
|
|
constraints: [foreign_key, not_null]
|
|
- name: photo_url
|
|
type: string(500)
|
|
constraints: [not_null]
|
|
- name: description
|
|
type: string(200)
|
|
- name: is_primary
|
|
type: boolean
|
|
constraints: [default_false]
|
|
- name: uploaded_at
|
|
type: timestamp
|
|
constraints: [not_null, default_now]
|
|
|
|
- name: DepreciationMovement
|
|
description: Movimientos de depreciación mensuales
|
|
attributes:
|
|
- name: id
|
|
type: uuid
|
|
constraints: [primary_key]
|
|
- name: asset_id
|
|
type: uuid
|
|
constraints: [foreign_key, not_null]
|
|
- name: period
|
|
type: date
|
|
description: Período (primer día del mes)
|
|
constraints: [not_null]
|
|
- name: depreciation_amount
|
|
type: decimal(15,2)
|
|
description: Monto depreciado en el período
|
|
constraints: [not_null]
|
|
- name: accumulated_depreciation
|
|
type: decimal(15,2)
|
|
description: Depreciación acumulada hasta el período
|
|
constraints: [not_null]
|
|
- name: book_value
|
|
type: decimal(15,2)
|
|
description: Valor en libros al final del período
|
|
constraints: [not_null]
|
|
- name: accounting_entry_id
|
|
type: uuid
|
|
description: Referencia al asiento contable
|
|
constraints: [foreign_key]
|
|
- name: calculation_method
|
|
type: string(50)
|
|
description: Método usado para el cálculo
|
|
- name: calculation_details
|
|
type: jsonb
|
|
description: Detalles del cálculo en JSON
|
|
- name: created_at
|
|
type: timestamp
|
|
constraints: [not_null, default_now]
|
|
|
|
indexes:
|
|
- fields: [asset_id, period]
|
|
unique: true
|
|
- fields: [period]
|
|
|
|
- name: MaintenancePlan
|
|
description: Planes de mantenimiento preventivo
|
|
attributes:
|
|
- name: id
|
|
type: uuid
|
|
constraints: [primary_key]
|
|
- name: name
|
|
type: string(200)
|
|
constraints: [not_null]
|
|
- name: asset_type_id
|
|
type: uuid
|
|
description: Tipo de maquinaria al que aplica
|
|
constraints: [foreign_key]
|
|
- name: frequency_type
|
|
type: enum
|
|
values: [days, hours, kilometers]
|
|
constraints: [not_null]
|
|
- name: frequency_value
|
|
type: integer
|
|
description: Cada cuántos días/horas/km
|
|
constraints: [not_null, positive]
|
|
- name: activities
|
|
type: jsonb
|
|
description: Lista de actividades a realizar
|
|
constraints: [not_null]
|
|
- name: estimated_duration_hours
|
|
type: decimal(5,2)
|
|
- name: is_active
|
|
type: boolean
|
|
constraints: [default_true]
|
|
- name: tenant_id
|
|
type: uuid
|
|
constraints: [foreign_key, not_null]
|
|
- name: created_at
|
|
type: timestamp
|
|
constraints: [not_null, default_now]
|
|
|
|
- name: MaintenanceOrder
|
|
description: Órdenes de mantenimiento
|
|
attributes:
|
|
- name: id
|
|
type: uuid
|
|
constraints: [primary_key]
|
|
- name: order_number
|
|
type: string(20)
|
|
constraints: [unique, not_null]
|
|
- name: asset_id
|
|
type: uuid
|
|
constraints: [foreign_key, not_null]
|
|
- name: maintenance_plan_id
|
|
type: uuid
|
|
constraints: [foreign_key]
|
|
- name: order_type
|
|
type: enum
|
|
values: [preventive, corrective]
|
|
constraints: [not_null]
|
|
- name: scheduled_date
|
|
type: date
|
|
constraints: [not_null]
|
|
- name: scheduled_hours
|
|
type: integer
|
|
description: Horas de máquina al momento de programar
|
|
- name: status
|
|
type: enum
|
|
values: [scheduled, in_progress, completed, cancelled]
|
|
constraints: [not_null, default_scheduled]
|
|
- name: assigned_technician_id
|
|
type: uuid
|
|
constraints: [foreign_key]
|
|
- name: activities_planned
|
|
type: jsonb
|
|
description: Actividades programadas
|
|
- name: activities_completed
|
|
type: jsonb
|
|
description: Actividades completadas
|
|
- name: completion_date
|
|
type: timestamp
|
|
- name: labor_hours
|
|
type: decimal(5,2)
|
|
description: Horas de mano de obra
|
|
- name: labor_cost
|
|
type: decimal(10,2)
|
|
- name: parts_cost
|
|
type: decimal(10,2)
|
|
- name: external_services_cost
|
|
type: decimal(10,2)
|
|
- name: total_cost
|
|
type: decimal(10,2)
|
|
- name: observations
|
|
type: text
|
|
- name: tenant_id
|
|
type: uuid
|
|
constraints: [foreign_key, not_null]
|
|
- name: created_at
|
|
type: timestamp
|
|
constraints: [not_null, default_now]
|
|
- name: completed_by
|
|
type: uuid
|
|
constraints: [foreign_key]
|
|
|
|
indexes:
|
|
- fields: [asset_id, status]
|
|
- fields: [scheduled_date]
|
|
- fields: [status]
|
|
|
|
- name: MaintenanceOrderPart
|
|
description: Repuestos utilizados en mantenimientos
|
|
attributes:
|
|
- name: id
|
|
type: uuid
|
|
constraints: [primary_key]
|
|
- name: maintenance_order_id
|
|
type: uuid
|
|
constraints: [foreign_key, not_null]
|
|
- name: part_id
|
|
type: uuid
|
|
description: Referencia a catálogo de repuestos
|
|
constraints: [foreign_key, not_null]
|
|
- name: quantity
|
|
type: decimal(10,2)
|
|
constraints: [not_null, positive]
|
|
- name: unit_cost
|
|
type: decimal(10,2)
|
|
constraints: [not_null]
|
|
- name: total_cost
|
|
type: decimal(10,2)
|
|
constraints: [not_null]
|
|
|
|
- name: MaintenancePhoto
|
|
description: Evidencias fotográficas de mantenimientos
|
|
attributes:
|
|
- name: id
|
|
type: uuid
|
|
constraints: [primary_key]
|
|
- name: maintenance_order_id
|
|
type: uuid
|
|
constraints: [foreign_key, not_null]
|
|
- name: photo_url
|
|
type: string(500)
|
|
constraints: [not_null]
|
|
- name: description
|
|
type: string(200)
|
|
- name: uploaded_at
|
|
type: timestamp
|
|
constraints: [not_null, default_now]
|
|
|
|
- name: AssetDisposal
|
|
description: Bajas de activos
|
|
attributes:
|
|
- name: id
|
|
type: uuid
|
|
constraints: [primary_key]
|
|
- name: disposal_number
|
|
type: string(20)
|
|
constraints: [unique, not_null]
|
|
- name: asset_id
|
|
type: uuid
|
|
constraints: [foreign_key, not_null]
|
|
- name: disposal_type
|
|
type: enum
|
|
values: [sale, donation, theft, accident, obsolescence, scrap, exchange]
|
|
constraints: [not_null]
|
|
- name: disposal_date
|
|
type: date
|
|
constraints: [not_null]
|
|
- name: book_value_at_disposal
|
|
type: decimal(15,2)
|
|
constraints: [not_null]
|
|
- name: sale_price
|
|
type: decimal(15,2)
|
|
description: Precio de venta (si aplica)
|
|
- name: sale_expenses
|
|
type: decimal(15,2)
|
|
description: Gastos de venta
|
|
- name: insurance_recovery
|
|
type: decimal(15,2)
|
|
description: Recuperación de seguro
|
|
- name: gain_loss_amount
|
|
type: decimal(15,2)
|
|
description: Utilidad o pérdida (negativo = pérdida)
|
|
- name: buyer_supplier
|
|
type: string(200)
|
|
description: Comprador o receptor
|
|
- name: status
|
|
type: enum
|
|
values: [requested, pending_approval, approved, rejected, executed]
|
|
constraints: [not_null, default_requested]
|
|
- name: requested_by
|
|
type: uuid
|
|
constraints: [foreign_key, not_null]
|
|
- name: requested_at
|
|
type: timestamp
|
|
constraints: [not_null, default_now]
|
|
- name: approved_by
|
|
type: uuid
|
|
constraints: [foreign_key]
|
|
- name: approved_at
|
|
type: timestamp
|
|
- name: rejection_reason
|
|
type: text
|
|
- name: accounting_entry_id
|
|
type: uuid
|
|
constraints: [foreign_key]
|
|
- name: justification
|
|
type: text
|
|
- name: notes
|
|
type: text
|
|
- name: tenant_id
|
|
type: uuid
|
|
constraints: [foreign_key, not_null]
|
|
|
|
indexes:
|
|
- fields: [asset_id]
|
|
- fields: [status]
|
|
- fields: [disposal_date]
|
|
|
|
- name: DisposalDocument
|
|
description: Documentos de baja
|
|
attributes:
|
|
- name: id
|
|
type: uuid
|
|
constraints: [primary_key]
|
|
- name: disposal_id
|
|
type: uuid
|
|
constraints: [foreign_key, not_null]
|
|
- name: document_type
|
|
type: enum
|
|
values: [sale_contract, donation_deed, police_report, appraisal, authorization, other]
|
|
constraints: [not_null]
|
|
- name: file_name
|
|
type: string(255)
|
|
constraints: [not_null]
|
|
- name: file_path
|
|
type: string(500)
|
|
constraints: [not_null]
|
|
- name: uploaded_at
|
|
type: timestamp
|
|
constraints: [not_null, default_now]
|
|
- name: uploaded_by
|
|
type: uuid
|
|
constraints: [foreign_key, not_null]
|
|
|
|
- name: DisposalApproval
|
|
description: Aprobaciones de bajas
|
|
attributes:
|
|
- name: id
|
|
type: uuid
|
|
constraints: [primary_key]
|
|
- name: disposal_id
|
|
type: uuid
|
|
constraints: [foreign_key, not_null]
|
|
- name: approval_level
|
|
type: integer
|
|
description: Nivel de aprobación (1, 2, 3)
|
|
constraints: [not_null]
|
|
- name: approver_role
|
|
type: string(100)
|
|
description: Rol del aprobador
|
|
constraints: [not_null]
|
|
- name: approver_user_id
|
|
type: uuid
|
|
constraints: [foreign_key]
|
|
- name: status
|
|
type: enum
|
|
values: [pending, approved, rejected]
|
|
constraints: [not_null, default_pending]
|
|
- name: decision_date
|
|
type: timestamp
|
|
- name: comments
|
|
type: text
|
|
|
|
# ============================================================================
|
|
# INTEGRACIONES
|
|
# ============================================================================
|
|
|
|
integrations:
|
|
|
|
- module: MGN-001
|
|
name: Gestión de Usuarios
|
|
type: interna
|
|
purpose: Autenticación, roles, permisos, asignación de responsables
|
|
endpoints:
|
|
- GET /api/v1/users
|
|
- GET /api/v1/users/{id}
|
|
- GET /api/v1/users/by-role/{role}
|
|
data_exchanged:
|
|
- Usuario (id, nombre, email, rol)
|
|
- Certificaciones de técnicos
|
|
|
|
- module: MGN-005
|
|
name: Catálogos
|
|
type: interna
|
|
purpose: Tipos de maquinaria, marcas, modelos, tipos de repuestos
|
|
endpoints:
|
|
- GET /api/v1/catalogs/asset-types
|
|
- GET /api/v1/catalogs/brands
|
|
- GET /api/v1/catalogs/parts
|
|
data_exchanged:
|
|
- Tipos de activos
|
|
- Marcas y modelos
|
|
- Repuestos
|
|
|
|
- module: MGN-006
|
|
name: Configuración
|
|
type: interna
|
|
purpose: Plan de cuentas, centros de costos, parámetros del sistema
|
|
endpoints:
|
|
- GET /api/v1/settings/chart-of-accounts
|
|
- GET /api/v1/settings/cost-centers
|
|
- GET /api/v1/settings/parameters
|
|
data_exchanged:
|
|
- Cuentas contables
|
|
- Centros de costos
|
|
- Parámetros de depreciación
|
|
|
|
- module: MGN-007
|
|
name: Auditoría
|
|
type: interna
|
|
purpose: Registro de todas las operaciones críticas
|
|
endpoints:
|
|
- POST /api/v1/audit/log
|
|
data_exchanged:
|
|
- Eventos de auditoría (alta, modificación, baja)
|
|
|
|
- module: MGN-008
|
|
name: Notificaciones
|
|
type: interna
|
|
purpose: Envío de alertas y notificaciones
|
|
endpoints:
|
|
- POST /api/v1/notifications/send
|
|
- POST /api/v1/notifications/send-bulk
|
|
data_exchanged:
|
|
- Notificaciones de mantenimiento
|
|
- Alertas de vencimientos
|
|
- Notificaciones de aprobaciones
|
|
|
|
- module: MGN-009
|
|
name: Reportes
|
|
type: interna
|
|
purpose: Generación de reportes del módulo
|
|
endpoints:
|
|
- POST /api/v1/reports/generate
|
|
- GET /api/v1/reports/{id}/download
|
|
data_exchanged:
|
|
- Parámetros de reporte
|
|
- Archivos PDF/Excel generados
|
|
|
|
- module: FIN-001
|
|
name: Contabilidad
|
|
type: interna
|
|
purpose: Generación de asientos contables de depreciación y baja
|
|
endpoints:
|
|
- POST /api/v1/accounting/entries
|
|
- GET /api/v1/accounting/entries/{id}
|
|
data_exchanged:
|
|
- Asientos contables
|
|
- Estado de asientos
|
|
|
|
- module: INV-001
|
|
name: Inventarios
|
|
type: interna
|
|
purpose: Control de repuestos utilizados en mantenimientos
|
|
endpoints:
|
|
- GET /api/v1/inventory/parts/{id}
|
|
- POST /api/v1/inventory/movements
|
|
data_exchanged:
|
|
- Disponibilidad de repuestos
|
|
- Movimientos de salida
|
|
- Costos de repuestos
|
|
|
|
# ============================================================================
|
|
# APIS EXTERNAS
|
|
# ============================================================================
|
|
|
|
external_apis:
|
|
|
|
- name: Servicio de Storage
|
|
provider: AWS S3 / Azure Blob Storage
|
|
purpose: Almacenamiento de documentos y fotografías
|
|
authentication: API Key / OAuth
|
|
endpoints:
|
|
- PUT /storage/upload
|
|
- GET /storage/download/{key}
|
|
- DELETE /storage/{key}
|
|
|
|
- name: Servicio de Email
|
|
provider: SendGrid / AWS SES
|
|
purpose: Envío de notificaciones por correo
|
|
authentication: API Key
|
|
endpoints:
|
|
- POST /email/send
|
|
|
|
- name: Servicio de geolocalización (opcional)
|
|
provider: Google Maps API
|
|
purpose: Geolocalización de activos en obras
|
|
authentication: API Key
|
|
endpoints:
|
|
- GET /geocoding/address
|
|
|
|
# ============================================================================
|
|
# COMPONENTES TÉCNICOS
|
|
# ============================================================================
|
|
|
|
technical_components:
|
|
|
|
backend:
|
|
- component: AssetService
|
|
responsibility: Lógica de negocio de activos
|
|
dependencies: [AssetRepository, UserService, CatalogService]
|
|
|
|
- component: DepreciationService
|
|
responsibility: Cálculo de depreciación
|
|
dependencies: [AssetRepository, DepreciationRepository, AccountingService]
|
|
|
|
- component: DepreciationBatchJob
|
|
responsibility: Job programado de depreciación mensual
|
|
dependencies: [DepreciationService, NotificationService]
|
|
|
|
- component: MaintenanceService
|
|
responsibility: Gestión de mantenimientos
|
|
dependencies: [MaintenanceRepository, AssetRepository, InventoryService]
|
|
|
|
- component: MaintenanceScheduler
|
|
responsibility: Programación automática de mantenimientos
|
|
dependencies: [MaintenanceService, MaintenancePlanRepository]
|
|
|
|
- component: MaintenanceAlertService
|
|
responsibility: Generación de alertas de mantenimiento
|
|
dependencies: [MaintenanceRepository, NotificationService]
|
|
|
|
- component: DisposalService
|
|
responsibility: Gestión de bajas
|
|
dependencies: [DisposalRepository, AssetRepository, AccountingService]
|
|
|
|
- component: DisposalWorkflow
|
|
responsibility: Workflow de aprobaciones
|
|
dependencies: [DisposalRepository, UserService, NotificationService]
|
|
|
|
- component: AssetReportService
|
|
responsibility: Generación de reportes
|
|
dependencies: [AssetRepository, DepreciationRepository, ReportService]
|
|
|
|
frontend:
|
|
- component: AssetRegistrationForm
|
|
responsibility: Formulario de alta de activos
|
|
technology: React/Vue component
|
|
|
|
- component: AssetDetailView
|
|
responsibility: Vista de detalle de activo
|
|
technology: React/Vue component
|
|
|
|
- component: AssetDocumentManager
|
|
responsibility: Gestión de documentos
|
|
technology: React/Vue component
|
|
|
|
- component: DepreciationDashboard
|
|
responsibility: Dashboard de depreciación
|
|
technology: React/Vue component
|
|
|
|
- component: MaintenanceCalendar
|
|
responsibility: Calendario de mantenimientos
|
|
technology: React/Vue component with FullCalendar
|
|
|
|
- component: MaintenanceOrderForm
|
|
responsibility: Formulario de orden de mantenimiento
|
|
technology: React/Vue component
|
|
|
|
- component: DisposalRequestForm
|
|
responsibility: Formulario de solicitud de baja
|
|
technology: React/Vue component
|
|
|
|
- component: DisposalApprovalPanel
|
|
responsibility: Panel de aprobaciones
|
|
technology: React/Vue component
|
|
|
|
database:
|
|
- component: AssetRepository
|
|
responsibility: Acceso a datos de activos
|
|
technology: TypeORM/Prisma repository
|
|
|
|
- component: DepreciationRepository
|
|
responsibility: Acceso a datos de depreciación
|
|
technology: TypeORM/Prisma repository
|
|
|
|
- component: MaintenanceRepository
|
|
responsibility: Acceso a datos de mantenimientos
|
|
technology: TypeORM/Prisma repository
|
|
|
|
- component: DisposalRepository
|
|
responsibility: Acceso a datos de bajas
|
|
technology: TypeORM/Prisma repository
|
|
|
|
# ============================================================================
|
|
# PLAN DE IMPLEMENTACIÓN
|
|
# ============================================================================
|
|
|
|
implementation_plan:
|
|
|
|
sprints:
|
|
|
|
- sprint: 1
|
|
name: Alta de Activos
|
|
duration: 2 semanas
|
|
objectives:
|
|
- Implementar registro de activos
|
|
- Gestión de documentos y fotografías
|
|
- Asignación de responsables
|
|
deliverables:
|
|
- RF-MAE015-001 completo
|
|
- US-MAE015-001, US-MAE015-002, US-MAE015-003
|
|
stories:
|
|
- US-MAE015-001
|
|
- US-MAE015-002
|
|
- US-MAE015-003
|
|
estimated_effort: 80 horas
|
|
|
|
- sprint: 2
|
|
name: Depreciación
|
|
duration: 2 semanas
|
|
objectives:
|
|
- Implementar cálculo de depreciación
|
|
- Job batch mensual
|
|
- Integración con contabilidad
|
|
- Reportes de depreciación
|
|
deliverables:
|
|
- RF-MAE015-002 completo
|
|
- US-MAE015-004, US-MAE015-005, US-MAE015-006
|
|
stories:
|
|
- US-MAE015-004
|
|
- US-MAE015-005
|
|
- US-MAE015-006
|
|
estimated_effort: 100 horas
|
|
|
|
- sprint: 3
|
|
name: Mantenimiento Preventivo
|
|
duration: 3 semanas
|
|
objectives:
|
|
- Implementar planes de mantenimiento
|
|
- Programación automática
|
|
- Sistema de alertas
|
|
- Registro de ejecución
|
|
- Control de costos
|
|
deliverables:
|
|
- RF-MAE015-003 completo
|
|
- US-MAE015-007, US-MAE015-008, US-MAE015-009
|
|
stories:
|
|
- US-MAE015-007
|
|
- US-MAE015-008
|
|
- US-MAE015-009
|
|
estimated_effort: 120 horas
|
|
|
|
- sprint: 4
|
|
name: Baja de Activos
|
|
duration: 2 semanas
|
|
objectives:
|
|
- Implementar proceso de baja
|
|
- Workflow de aprobaciones
|
|
- Cálculo de utilidad/pérdida
|
|
- Integración contable
|
|
deliverables:
|
|
- RF-MAE015-004 completo
|
|
- US-MAE015-010, US-MAE015-011, US-MAE015-012
|
|
stories:
|
|
- US-MAE015-010
|
|
- US-MAE015-011
|
|
- US-MAE015-012
|
|
estimated_effort: 90 horas
|
|
|
|
- sprint: 5
|
|
name: Testing y Refinamiento
|
|
duration: 2 semanas
|
|
objectives:
|
|
- Testing integral
|
|
- Corrección de bugs
|
|
- Optimización de performance
|
|
- Documentación
|
|
deliverables:
|
|
- Módulo completo y testeado
|
|
- Documentación técnica
|
|
- Manual de usuario
|
|
estimated_effort: 80 horas
|
|
|
|
total_estimated_effort: 470 horas
|
|
total_duration: 11 semanas
|
|
|
|
milestones:
|
|
- milestone: M1 - Alta de Activos
|
|
date: Fin Sprint 1
|
|
deliverable: Registro de activos funcional
|
|
|
|
- milestone: M2 - Depreciación
|
|
date: Fin Sprint 2
|
|
deliverable: Cálculo automático de depreciación
|
|
|
|
- milestone: M3 - Mantenimiento
|
|
date: Fin Sprint 3
|
|
deliverable: Sistema de mantenimiento preventivo
|
|
|
|
- milestone: M4 - Baja de Activos
|
|
date: Fin Sprint 4
|
|
deliverable: Proceso de baja completo
|
|
|
|
- milestone: M5 - Go Live
|
|
date: Fin Sprint 5
|
|
deliverable: Módulo en producción
|
|
|
|
# ============================================================================
|
|
# CRITERIOS DE ACEPTACIÓN DEL MÓDULO
|
|
# ============================================================================
|
|
|
|
acceptance_criteria:
|
|
|
|
functional:
|
|
- criterion: Registro completo de activos
|
|
validation: Crear 10 activos de diferentes tipos con documentación completa
|
|
status: pendiente
|
|
|
|
- criterion: Depreciación mensual automática
|
|
validation: Ejecutar cálculo de 100 activos con diferentes métodos
|
|
status: pendiente
|
|
|
|
- criterion: Mantenimientos programados
|
|
validation: Configurar 5 planes y verificar generación automática de órdenes
|
|
status: pendiente
|
|
|
|
- criterion: Alertas de mantenimiento
|
|
validation: Verificar envío de notificaciones 7 días antes
|
|
status: pendiente
|
|
|
|
- criterion: Proceso de baja completo
|
|
validation: Ejecutar baja por venta con workflow de aprobación
|
|
status: pendiente
|
|
|
|
non_functional:
|
|
- criterion: Performance de cálculo
|
|
validation: Depreciar 10,000 activos en menos de 5 minutos
|
|
status: pendiente
|
|
|
|
- criterion: Seguridad de documentos
|
|
validation: Verificar encriptación de archivos sensibles
|
|
status: pendiente
|
|
|
|
- criterion: Auditoría completa
|
|
validation: Verificar registro de todas las operaciones críticas
|
|
status: pendiente
|
|
|
|
- criterion: Responsive design
|
|
validation: Verificar funcionalidad en tablets y smartphones
|
|
status: pendiente
|
|
|
|
# ============================================================================
|
|
# RIESGOS Y MITIGACIONES
|
|
# ============================================================================
|
|
|
|
risks:
|
|
|
|
- risk: Complejidad de cálculos de depreciación
|
|
probability: media
|
|
impact: alto
|
|
mitigation: >
|
|
Validar fórmulas con equipo contable, crear suite completa de tests
|
|
unitarios, verificar con casos reales.
|
|
owner: Tech Lead
|
|
|
|
- risk: Integración con módulo contable
|
|
probability: media
|
|
impact: alto
|
|
mitigation: >
|
|
Definir contrato de integración tempranamente, desarrollar en paralelo,
|
|
crear mocks para testing independiente.
|
|
owner: Arquitecto de Software
|
|
|
|
- risk: Performance en cálculo masivo
|
|
probability: baja
|
|
impact: medio
|
|
mitigation: >
|
|
Implementar procesamiento en lotes, optimizar queries, considerar
|
|
procesamiento asíncrono si es necesario.
|
|
owner: Tech Lead
|
|
|
|
- risk: Complejidad de workflow de aprobaciones
|
|
probability: media
|
|
impact: medio
|
|
mitigation: >
|
|
Usar librería probada de workflow (state machine), diseñar flujos
|
|
simples y extensibles.
|
|
owner: Desarrollador Backend
|
|
|
|
- risk: Disponibilidad de datos de catálogos
|
|
probability: alta
|
|
impact: bajo
|
|
mitigation: >
|
|
Coordinar con equipo de MGN-005, tener catálogos base precargados,
|
|
permitir creación on-the-fly con permisos.
|
|
owner: Product Owner
|
|
|
|
# ============================================================================
|
|
# MÉTRICAS DE ÉXITO
|
|
# ============================================================================
|
|
|
|
success_metrics:
|
|
|
|
- metric: Adopción del módulo
|
|
target: 90% de activos registrados en sistema en 3 meses
|
|
measurement: Comparar inventario físico vs sistema
|
|
|
|
- metric: Precisión de depreciación
|
|
target: 100% de coincidencia con cálculos contables
|
|
measurement: Auditoría mensual de cálculos
|
|
|
|
- metric: Cumplimiento de mantenimientos
|
|
target: 95% de mantenimientos ejecutados en fecha programada
|
|
measurement: Reporte de cumplimiento mensual
|
|
|
|
- metric: Reducción de tiempo de cierre
|
|
target: Reducir 80% tiempo de cálculo de depreciación mensual
|
|
measurement: Comparar tiempo antes vs después de automatización
|
|
|
|
- metric: Trazabilidad de costos
|
|
target: 100% de costos de mantenimiento registrados y trazables
|
|
measurement: Auditoría de registros de costos
|
|
|
|
- metric: Satisfacción de usuarios
|
|
target: Calificación promedio de 4.5/5 en encuesta de usuarios
|
|
measurement: Encuesta trimestral a usuarios del módulo
|
|
|
|
# ============================================================================
|
|
# DOCUMENTACIÓN REQUERIDA
|
|
# ============================================================================
|
|
|
|
documentation:
|
|
|
|
technical:
|
|
- Manual de instalación y configuración
|
|
- Documentación de APIs (OpenAPI/Swagger)
|
|
- Diagrama de arquitectura
|
|
- Modelo de datos (ERD)
|
|
- Guía de desarrollo y estándares de código
|
|
- Manual de pruebas y casos de test
|
|
|
|
user:
|
|
- Manual de usuario general
|
|
- Guías rápidas por rol (gerente, contador, técnico)
|
|
- Videos tutoriales
|
|
- FAQ
|
|
|
|
business:
|
|
- Especificación de requerimientos
|
|
- Reglas de negocio
|
|
- Procesos de negocio (BPMN)
|
|
- Matriz de trazabilidad (este documento)
|
|
|
|
# ============================================================================
|
|
# HISTORIAL DE CAMBIOS
|
|
# ============================================================================
|
|
|
|
change_history:
|
|
- version: 1.0.0
|
|
date: 2025-12-06
|
|
author: Equipo Verticales Construcción
|
|
changes:
|
|
- Creación inicial del documento
|
|
- Definición de 4 RF principales
|
|
- Modelo de datos completo
|
|
- Plan de implementación en 5 sprints
|
|
approved_by: Product Owner
|
|
|
|
# ============================================================================
|
|
# FIN DEL DOCUMENTO
|
|
# ============================================================================
|