# ============================================================================
# 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
# ============================================================================
