# ============================================================================
# MATRIZ DE TRAZABILIDAD - MÓDULO MAE-009: FACTURACIÓN
# ============================================================================
# Proyecto: ERP Suite - Vertical Construcción
# Módulo: MAE-009 - Facturación Electrónica
# Versión: 1.0.0
# Fecha: 2025-12-06
# ============================================================================

metadata:
  module_id: MAE-009
  module_name: Facturación
  vertical: construccion
  version: 1.0.0
  status: planned
  owner: Equipo Construcción
  created_date: 2025-12-06
  last_updated: 2025-12-06
  description: |
    Módulo de facturación electrónica para el sector construcción.
    Gestiona la emisión, cancelación y recepción de CFDI, así como
    complementos de pago según la normativa del SAT mexicano.

# ============================================================================
# REQUERIMIENTOS FUNCIONALES
# ============================================================================

functional_requirements:

  # --------------------------------------------------------------------------
  # RF-001: EMISIÓN DE CFDI
  # --------------------------------------------------------------------------
  - id: RF-MAE-009-001
    name: Emisión de CFDI
    description: |
      Emisión de Comprobantes Fiscales Digitales por Internet (CFDI) según
      la normativa del SAT mexicano. Incluye validación de datos fiscales,
      timbrado mediante PAC y almacenamiento de XML y PDF.
    priority: critical
    status: pending
    business_rules:
      - id: BR-MAE-009-001-01
        description: El RFC del emisor debe estar registrado y activo en el SAT
      - id: BR-MAE-009-001-02
        description: Todos los CFDI deben timbarse con un PAC autorizado antes de ser válidos
      - id: BR-MAE-009-001-03
        description: Los datos fiscales del receptor deben validarse contra el SAT
      - id: BR-MAE-009-001-04
        description: El CFDI debe cumplir con el esquema XML vigente del SAT (versión 4.0)
      - id: BR-MAE-009-001-05
        description: Cada CFDI debe incluir UUID único proporcionado por el PAC
      - id: BR-MAE-009-001-06
        description: Se debe generar representación impresa (PDF) del CFDI
      - id: BR-MAE-009-001-07
        description: Los CFDI de obra deben incluir información de la obra/proyecto
      - id: BR-MAE-009-001-08
        description: Validar que la forma de pago coincida con el método de pago

    user_stories:
      - id: US-MAE-009-001-01
        title: Crear CFDI de ingreso desde contrato
        description: Como contador, quiero generar un CFDI de ingreso a partir de un contrato de obra para facturar estimaciones
        acceptance_criteria:
          - El sistema carga automáticamente los datos del contrato
          - Se pre-llena la información fiscal del cliente
          - Se permite seleccionar conceptos de la estimación
          - Se calcula automáticamente IVA y retenciones
          - Se valida el RFC del receptor contra el SAT
        priority: high
        story_points: 8

      - id: US-MAE-009-001-02
        title: Timbrar CFDI con PAC
        description: Como contador, quiero timbrar el CFDI generado mediante el PAC autorizado para obtener el sello digital
        acceptance_criteria:
          - El sistema envía el XML pre-validado al PAC
          - Se recibe y almacena el UUID del comprobante
          - Se guarda el XML timbrado con cadena original
          - Se genera PDF con código QR y sello digital
          - Se notifica al usuario del éxito o error del timbrado
        priority: critical
        story_points: 13

      - id: US-MAE-009-001-03
        title: Enviar CFDI por correo electrónico
        description: Como contador, quiero enviar el CFDI timbrado al cliente por correo electrónico con XML y PDF adjuntos
        acceptance_criteria:
          - Se adjuntan XML y PDF del CFDI
          - El correo incluye resumen de la factura
          - Se registra el envío en el historial
          - Se permite reenvío de CFDI
          - Se valida el formato del correo electrónico
        priority: medium
        story_points: 5

      - id: US-MAE-009-001-04
        title: Gestionar addendas de clientes
        description: Como contador, quiero agregar addendas específicas de clientes corporativos al CFDI para cumplir sus requerimientos
        acceptance_criteria:
          - Se pueden configurar addendas por cliente
          - Las addendas se incluyen en el XML del CFDI
          - Se valida la estructura XML de la addenda
          - Se mantiene compatibilidad con esquema SAT
        priority: low
        story_points: 8

    technical_requirements:
      - id: TR-MAE-009-001-01
        description: Implementar servicio de validación de RFC contra API del SAT
        component: backend/services/sat-validation
        technology: Node.js, Axios

      - id: TR-MAE-009-001-02
        description: Integrar con PAC autorizado (ej. Finkok, PAC SAT)
        component: backend/integrations/pac
        technology: SOAP/REST, XML

      - id: TR-MAE-009-001-03
        description: Generar XML según esquema CFDI 4.0
        component: backend/services/cfdi-generator
        technology: Node.js, xml2js

      - id: TR-MAE-009-001-04
        description: Generar PDF con representación impresa del CFDI
        component: backend/services/pdf-generator
        technology: PDFKit, QRCode

      - id: TR-MAE-009-001-05
        description: Implementar interfaz de captura de CFDI
        component: frontend/modules/facturacion
        technology: React, TypeScript

    dependencies:
      internal:
        - module: MGN-001
          requirement: Gestión de usuarios y autenticación
        - module: MGN-002
          requirement: Control de permisos para emisión de CFDI
        - module: MGN-003
          requirement: Aislamiento de datos por tenant/empresa
        - module: MAE-001
          requirement: Datos de contratos y clientes

      external:
        - service: PAC
          description: Proveedor Autorizado de Certificación para timbrado
          type: SOAP/REST API
        - service: SAT
          description: Servicio de Administración Tributaria - Validación de RFC
          type: Web Service

    test_cases:
      - id: TC-MAE-009-001-01
        description: Validar generación correcta de XML CFDI 4.0
        type: unit
        status: pending

      - id: TC-MAE-009-001-02
        description: Probar timbrado exitoso con PAC en ambiente de pruebas
        type: integration
        status: pending

      - id: TC-MAE-009-001-03
        description: Verificar generación de PDF con todos los elementos legales
        type: functional
        status: pending

      - id: TC-MAE-009-001-04
        description: Validar flujo completo de emisión de CFDI
        type: e2e
        status: pending

    implementation:
      files:
        - path: backend/src/modules/facturacion/services/cfdi-emision.service.ts
          status: pending
        - path: backend/src/modules/facturacion/controllers/cfdi.controller.ts
          status: pending
        - path: backend/src/integrations/pac/pac-client.ts
          status: pending
        - path: frontend/src/modules/facturacion/components/CFDIForm.tsx
          status: pending

      database_changes:
        - table: cfdi
          type: create
          description: Almacena los CFDI emitidos
        - table: cfdi_conceptos
          type: create
          description: Detalle de conceptos del CFDI
        - table: cfdi_impuestos
          type: create
          description: Desglose de impuestos

      api_endpoints:
        - method: POST
          path: /api/v1/facturacion/cfdi
          description: Crear y timbrar nuevo CFDI
        - method: GET
          path: /api/v1/facturacion/cfdi/:id
          description: Obtener detalles de un CFDI
        - method: GET
          path: /api/v1/facturacion/cfdi/:id/xml
          description: Descargar XML del CFDI
        - method: GET
          path: /api/v1/facturacion/cfdi/:id/pdf
          description: Descargar PDF del CFDI

  # --------------------------------------------------------------------------
  # RF-002: CANCELACIÓN DE CFDI
  # --------------------------------------------------------------------------
  - id: RF-MAE-009-002
    name: Cancelación de CFDI
    description: |
      Proceso de cancelación de CFDI previamente timbrados mediante el PAC,
      incluyendo solicitud de cancelación, gestión de aceptación por parte
      del receptor y actualización de estatus en el SAT.
    priority: critical
    status: pending
    business_rules:
      - id: BR-MAE-009-002-01
        description: Solo se pueden cancelar CFDI previamente timbrados
      - id: BR-MAE-009-002-02
        description: La cancelación debe registrarse ante el SAT a través del PAC
      - id: BR-MAE-009-002-03
        description: Para CFDI mayores a $5,000 se requiere aceptación del receptor
      - id: BR-MAE-009-002-04
        description: Se debe especificar el motivo de cancelación según catálogo SAT
      - id: BR-MAE-009-002-05
        description: Si se especifica UUID de sustitución, este debe ser válido
      - id: BR-MAE-009-002-06
        description: No se pueden cancelar CFDI ya cancelados
      - id: BR-MAE-009-002-07
        description: Validar período permitido para cancelación según reglas SAT

    user_stories:
      - id: US-MAE-009-002-01
        title: Solicitar cancelación de CFDI
        description: Como contador, quiero solicitar la cancelación de un CFDI emitido especificando el motivo para corregir errores
        acceptance_criteria:
          - Se muestra lista de motivos de cancelación del catálogo SAT
          - Se permite indicar UUID de sustitución si aplica
          - El sistema valida que el CFDI no esté ya cancelado
          - Se envía solicitud al PAC
          - Se registra el intento de cancelación
        priority: high
        story_points: 8

      - id: US-MAE-009-002-02
        title: Gestionar aceptación de cancelación
        description: Como receptor, quiero recibir notificación de solicitud de cancelación y poder aceptarla o rechazarla
        acceptance_criteria:
          - Se notifica por correo la solicitud de cancelación
          - Se proporciona enlace para aceptar/rechazar
          - Se registra la respuesta del receptor
          - Se actualiza el estatus del CFDI
          - Se notifica al emisor de la decisión
        priority: high
        story_points: 8

      - id: US-MAE-009-002-03
        title: Consultar estatus de cancelación
        description: Como contador, quiero consultar el estatus de una solicitud de cancelación para dar seguimiento
        acceptance_criteria:
          - Se muestra el estatus actual (pendiente, aceptada, rechazada)
          - Se muestra la fecha de solicitud
          - Se indica si requiere aceptación del receptor
          - Se muestra historial de la solicitud
        priority: medium
        story_points: 5

    technical_requirements:
      - id: TR-MAE-009-002-01
        description: Implementar servicio de cancelación vía PAC
        component: backend/services/cfdi-cancelacion
        technology: Node.js, SOAP/REST

      - id: TR-MAE-009-002-02
        description: Crear flujo de aceptación/rechazo de cancelación
        component: backend/services/cancelacion-workflow
        technology: Node.js, Estado de máquina

      - id: TR-MAE-009-002-03
        description: Implementar notificaciones de cancelación
        component: backend/services/notifications
        technology: Email, Push notifications

      - id: TR-MAE-009-002-04
        description: Interfaz de gestión de cancelaciones
        component: frontend/modules/facturacion/cancelacion
        technology: React, TypeScript

    dependencies:
      internal:
        - module: RF-MAE-009-001
          requirement: CFDI debe estar previamente emitido
        - module: MGN-008
          requirement: Sistema de notificaciones

      external:
        - service: PAC
          description: Cancelación de CFDI ante el SAT
          type: SOAP/REST API
        - service: SAT
          description: Consulta de estatus de cancelación
          type: Web Service

    test_cases:
      - id: TC-MAE-009-002-01
        description: Validar cancelación exitosa de CFDI menor a $5,000
        type: integration
        status: pending

      - id: TC-MAE-009-002-02
        description: Probar flujo de aceptación de cancelación por receptor
        type: functional
        status: pending

      - id: TC-MAE-009-002-03
        description: Verificar rechazo de cancelación de CFDI ya cancelado
        type: unit
        status: pending

    implementation:
      files:
        - path: backend/src/modules/facturacion/services/cfdi-cancelacion.service.ts
          status: pending
        - path: backend/src/modules/facturacion/controllers/cancelacion.controller.ts
          status: pending
        - path: frontend/src/modules/facturacion/components/CancelacionForm.tsx
          status: pending

      database_changes:
        - table: cfdi_cancelaciones
          type: create
          description: Registro de solicitudes de cancelación
        - table: cfdi
          type: alter
          description: Agregar campos de estatus de cancelación

      api_endpoints:
        - method: POST
          path: /api/v1/facturacion/cfdi/:id/cancelar
          description: Solicitar cancelación de CFDI
        - method: GET
          path: /api/v1/facturacion/cfdi/:id/cancelacion/status
          description: Consultar estatus de cancelación
        - method: POST
          path: /api/v1/facturacion/cancelacion/:id/aceptar
          description: Aceptar cancelación como receptor
        - method: POST
          path: /api/v1/facturacion/cancelacion/:id/rechazar
          description: Rechazar cancelación como receptor

  # --------------------------------------------------------------------------
  # RF-003: RECEPCIÓN DE CFDI
  # --------------------------------------------------------------------------
  - id: RF-MAE-009-003
    name: Recepción de CFDI
    description: |
      Gestión de CFDI recibidos de proveedores, incluyendo carga de XML,
      validación de timbrado, verificación ante el SAT y registro contable
      de documentos por pagar.
    priority: high
    status: pending
    business_rules:
      - id: BR-MAE-009-003-01
        description: El XML debe contener un UUID válido y verificable ante el SAT
      - id: BR-MAE-009-003-02
        description: El RFC receptor debe corresponder a la empresa activa
      - id: BR-MAE-009-003-03
        description: Se debe validar el sello digital del PAC
      - id: BR-MAE-009-003-04
        description: Verificar que el CFDI no esté cancelado en el SAT
      - id: BR-MAE-009-003-05
        description: Los CFDI recibidos deben asociarse a órdenes de compra o contratos
      - id: BR-MAE-009-003-06
        description: Detectar y alertar sobre CFDI duplicados (mismo UUID)
      - id: BR-MAE-009-003-07
        description: Validar que los montos coincidan con la orden de compra asociada

    user_stories:
      - id: US-MAE-009-003-01
        title: Cargar CFDI recibido
        description: Como auxiliar contable, quiero cargar el XML de un CFDI recibido para registrarlo en el sistema
        acceptance_criteria:
          - Se permite carga individual o masiva de archivos XML
          - El sistema extrae automáticamente datos del XML
          - Se valida la estructura y sello del XML
          - Se detectan XML duplicados
          - Se almacena el XML original
        priority: high
        story_points: 8

      - id: US-MAE-009-003-02
        title: Validar CFDI ante el SAT
        description: Como contador, quiero validar automáticamente el CFDI ante el SAT para verificar su autenticidad y vigencia
        acceptance_criteria:
          - Se consulta el estatus del UUID ante el SAT
          - Se verifica que el CFDI no esté cancelado
          - Se valida la cadena original y sello digital
          - Se muestra resultado de la validación
          - Se registra fecha de validación
        priority: high
        story_points: 8

      - id: US-MAE-009-003-03
        title: Asociar CFDI a orden de compra
        description: Como auxiliar contable, quiero asociar un CFDI recibido a su orden de compra correspondiente para conciliar
        acceptance_criteria:
          - Se sugieren órdenes de compra pendientes del proveedor
          - Se comparan montos entre CFDI y orden de compra
          - Se permite asociación manual o automática
          - Se actualiza estatus de la orden de compra
          - Se alerta si hay discrepancias en montos
        priority: medium
        story_points: 5

      - id: US-MAE-009-003-04
        title: Consultar CFDI recibidos
        description: Como contador, quiero consultar y filtrar los CFDI recibidos para revisión y auditoría
        acceptance_criteria:
          - Filtros por proveedor, fecha, monto, estatus
          - Visualización de datos fiscales principales
          - Descarga de XML y PDF
          - Exportación a Excel
          - Indicadores visuales de estatus
        priority: medium
        story_points: 5

    technical_requirements:
      - id: TR-MAE-009-003-01
        description: Implementar parser de XML CFDI 4.0 y versiones anteriores
        component: backend/services/cfdi-parser
        technology: Node.js, xml2js

      - id: TR-MAE-009-003-02
        description: Servicio de validación de CFDI ante SAT
        component: backend/services/sat-validator
        technology: Node.js, SOAP

      - id: TR-MAE-009-003-03
        description: Almacenamiento y gestión de archivos XML
        component: backend/services/file-storage
        technology: S3, MinIO

      - id: TR-MAE-009-003-04
        description: Interfaz de carga y gestión de CFDI recibidos
        component: frontend/modules/facturacion/recepcion
        technology: React, TypeScript

    dependencies:
      internal:
        - module: MGN-003
          requirement: Validación de RFC de empresa
        - module: MAE-002
          requirement: Órdenes de compra para asociación

      external:
        - service: SAT
          description: Validación de vigencia de CFDI
          type: Web Service

    test_cases:
      - id: TC-MAE-009-003-01
        description: Validar parsing correcto de XML CFDI 4.0
        type: unit
        status: pending

      - id: TC-MAE-009-003-02
        description: Probar validación de CFDI vigente ante SAT
        type: integration
        status: pending

      - id: TC-MAE-009-003-03
        description: Verificar detección de CFDI duplicados
        type: functional
        status: pending

      - id: TC-MAE-009-003-04
        description: Validar asociación correcta con orden de compra
        type: functional
        status: pending

    implementation:
      files:
        - path: backend/src/modules/facturacion/services/cfdi-recepcion.service.ts
          status: pending
        - path: backend/src/modules/facturacion/parsers/cfdi-parser.ts
          status: pending
        - path: frontend/src/modules/facturacion/components/RecepcionCFDI.tsx
          status: pending

      database_changes:
        - table: cfdi_recibidos
          type: create
          description: Almacena CFDI recibidos de proveedores
        - table: cfdi_recibidos_conceptos
          type: create
          description: Detalle de conceptos de CFDI recibidos
        - table: cfdi_validaciones
          type: create
          description: Historial de validaciones ante SAT

      api_endpoints:
        - method: POST
          path: /api/v1/facturacion/cfdi/recibidos
          description: Cargar CFDI recibido
        - method: POST
          path: /api/v1/facturacion/cfdi/recibidos/validar
          description: Validar CFDI ante SAT
        - method: GET
          path: /api/v1/facturacion/cfdi/recibidos
          description: Listar CFDI recibidos
        - method: POST
          path: /api/v1/facturacion/cfdi/recibidos/:id/asociar
          description: Asociar CFDI a orden de compra

  # --------------------------------------------------------------------------
  # RF-004: COMPLEMENTOS DE PAGO
  # --------------------------------------------------------------------------
  - id: RF-MAE-009-004
    name: Complementos de Pago
    description: |
      Emisión de CFDI con complemento de pago para relacionar pagos
      recibidos con facturas previamente emitidas, cumpliendo con
      la normativa del SAT para documentar la forma de pago.
    priority: high
    status: pending
    business_rules:
      - id: BR-MAE-009-004-01
        description: El complemento de pago debe relacionarse con uno o más CFDI de ingreso previos
      - id: BR-MAE-009-004-02
        description: La suma de pagos no debe exceder el total del CFDI relacionado
      - id: BR-MAE-009-004-03
        description: Se debe especificar la forma de pago (transferencia, cheque, etc.)
      - id: BR-MAE-009-004-04
        description: Incluir datos bancarios si el pago es por transferencia
      - id: BR-MAE-009-004-05
        description: El tipo de cambio es obligatorio para pagos en moneda extranjera
      - id: BR-MAE-009-004-06
        description: Validar que los CFDI relacionados no estén cancelados
      - id: BR-MAE-009-004-07
        description: El monto del pago debe ser mayor a cero

    user_stories:
      - id: US-MAE-009-004-01
        title: Generar complemento de pago
        description: Como contador, quiero generar un complemento de pago para documentar un pago recibido de un cliente
        acceptance_criteria:
          - Se seleccionan los CFDI pendientes de pago del cliente
          - Se captura monto, fecha y forma de pago
          - Se calculan parcialidades automáticamente
          - Se valida que no se exceda el saldo pendiente
          - Se genera y timbra el complemento
        priority: high
        story_points: 13

      - id: US-MAE-009-004-02
        title: Aplicar pago parcial a múltiples facturas
        description: Como contador, quiero aplicar un pago que cubre parcialmente varias facturas para documentar correctamente
        acceptance_criteria:
          - Se distribuye automáticamente el pago entre facturas
          - Se permite ajuste manual de distribución
          - Se muestra saldo pendiente de cada factura
          - Se valida que la suma sea correcta
          - Se generan parcialidades correctas en el XML
        priority: high
        story_points: 8

      - id: US-MAE-009-004-03
        title: Consultar complementos de pago emitidos
        description: Como contador, quiero consultar los complementos de pago emitidos para verificar aplicación de pagos
        acceptance_criteria:
          - Lista de complementos con filtros
          - Visualización de facturas relacionadas
          - Descarga de XML y PDF
          - Indicador de estatus (vigente/cancelado)
          - Integración con estado de cuenta del cliente
        priority: medium
        story_points: 5

      - id: US-MAE-009-004-04
        title: Cancelar complemento de pago
        description: Como contador, quiero cancelar un complemento de pago en caso de error para corregir la aplicación
        acceptance_criteria:
          - Se restaura el saldo de las facturas relacionadas
          - Se solicita cancelación al PAC
          - Se actualiza estado de cuenta del cliente
          - Se registra motivo de cancelación
          - Se notifica al cliente
        priority: medium
        story_points: 5

    technical_requirements:
      - id: TR-MAE-009-004-01
        description: Implementar generación de complemento de pago según anexo 20
        component: backend/services/complemento-pago
        technology: Node.js, xml2js

      - id: TR-MAE-009-004-02
        description: Servicio de cálculo de parcialidades
        component: backend/services/parcialidades-calculator
        technology: Node.js

      - id: TR-MAE-009-004-03
        description: Interfaz de aplicación de pagos
        component: frontend/modules/facturacion/pagos
        technology: React, TypeScript

      - id: TR-MAE-009-004-04
        description: Actualización de saldos de clientes
        component: backend/services/cuentas-corrientes
        technology: Node.js, PostgreSQL

    dependencies:
      internal:
        - module: RF-MAE-009-001
          requirement: CFDI de ingreso previamente emitidos
        - module: MAE-003
          requirement: Gestión de cuentas por cobrar

      external:
        - service: PAC
          description: Timbrado de complementos de pago
          type: SOAP/REST API
        - service: Banxico
          description: Tipo de cambio para pagos en moneda extranjera
          type: REST API

    test_cases:
      - id: TC-MAE-009-004-01
        description: Validar generación correcta de XML complemento de pago
        type: unit
        status: pending

      - id: TC-MAE-009-004-02
        description: Probar cálculo de parcialidades para pago múltiple
        type: unit
        status: pending

      - id: TC-MAE-009-004-03
        description: Verificar actualización de saldos tras aplicar pago
        type: integration
        status: pending

      - id: TC-MAE-009-004-04
        description: Validar flujo completo de complemento de pago
        type: e2e
        status: pending

    implementation:
      files:
        - path: backend/src/modules/facturacion/services/complemento-pago.service.ts
          status: pending
        - path: backend/src/modules/facturacion/controllers/pagos.controller.ts
          status: pending
        - path: frontend/src/modules/facturacion/components/ComplementoPagoForm.tsx
          status: pending

      database_changes:
        - table: complementos_pago
          type: create
          description: Registro de complementos de pago emitidos
        - table: complementos_pago_documentos
          type: create
          description: Relación con documentos relacionados
        - table: cfdi
          type: alter
          description: Agregar campos de control de saldo y parcialidades

      api_endpoints:
        - method: POST
          path: /api/v1/facturacion/complementos-pago
          description: Generar complemento de pago
        - method: GET
          path: /api/v1/facturacion/complementos-pago
          description: Listar complementos de pago
        - method: GET
          path: /api/v1/facturacion/cfdi/:id/saldo
          description: Consultar saldo pendiente de un CFDI
        - method: POST
          path: /api/v1/facturacion/complementos-pago/:id/cancelar
          description: Cancelar complemento de pago

# ============================================================================
# INTEGRACIONES EXTERNAS
# ============================================================================

external_integrations:

  - id: INT-MAE-009-001
    name: Integración con PAC
    description: |
      Integración con Proveedor Autorizado de Certificación para timbrado
      y cancelación de CFDI ante el SAT.
    provider: PAC Autorizado (Finkok, PAC SAT, etc.)
    type: SOAP/REST API
    authentication: API Key + Certificado Digital
    endpoints:
      - name: Timbrado de CFDI
        method: POST
        description: Envío de XML para timbrado
      - name: Cancelación de CFDI
        method: POST
        description: Solicitud de cancelación
      - name: Consulta de estatus
        method: GET
        description: Verificación de estatus de CFDI
    requirements:
      - Certificado de sello digital vigente (CSD)
      - Cuenta activa con el PAC
      - Configuración de credenciales de API
    error_handling:
      - Timeout: Reintentar hasta 3 veces
      - Error de validación: Mostrar mensaje específico
      - Servicio no disponible: Encolar para reintento

  - id: INT-MAE-009-002
    name: Validación ante SAT
    description: |
      Servicios web del SAT para validación de RFC, estatus de CFDI
      y consulta de datos fiscales.
    provider: Servicio de Administración Tributaria
    type: Web Service (SOAP)
    authentication: Pública (sin autenticación para consultas)
    endpoints:
      - name: Validación de RFC
        method: GET
        description: Verificar existencia y estatus de RFC
      - name: Validación de CFDI
        method: GET
        description: Consultar vigencia de UUID
      - name: Consulta de estatus tributario
        method: GET
        description: Verificar situación fiscal del contribuyente
    requirements:
      - Conexión a internet estable
      - Manejo de certificados SSL
    error_handling:
      - Cache de RFC validados (24 horas)
      - Modo offline para consultas no críticas

  - id: INT-MAE-009-003
    name: Consulta de tipo de cambio
    description: |
      Obtención de tipo de cambio oficial para CFDI en moneda extranjera
      y complementos de pago.
    provider: Banco de México (Banxico)
    type: REST API
    authentication: API Token
    endpoints:
      - name: Tipo de cambio USD
        method: GET
        description: Obtener tipo de cambio USD/MXN
    requirements:
      - Token de API de Banxico
      - Actualización diaria de tipos de cambio
    error_handling:
      - Cache del último tipo de cambio conocido
      - Alerta si no se puede actualizar por 3 días

# ============================================================================
# MODELO DE DATOS
# ============================================================================

data_model:

  tables:
    - name: cfdi
      description: Catálogo principal de CFDI emitidos
      columns:
        - name: id
          type: UUID
          primary_key: true
        - name: tenant_id
          type: UUID
          nullable: false
          foreign_key: tenants.id
        - name: uuid
          type: VARCHAR(36)
          nullable: false
          unique: true
          description: UUID del CFDI asignado por el PAC
        - name: folio
          type: VARCHAR(20)
          nullable: false
        - name: serie
          type: VARCHAR(10)
          nullable: true
        - name: tipo_comprobante
          type: VARCHAR(1)
          nullable: false
          description: I=Ingreso, E=Egreso, T=Traslado, N=Nómina, P=Pago
        - name: fecha_emision
          type: TIMESTAMP
          nullable: false
        - name: fecha_timbrado
          type: TIMESTAMP
          nullable: true
        - name: emisor_rfc
          type: VARCHAR(13)
          nullable: false
        - name: emisor_nombre
          type: VARCHAR(300)
          nullable: false
        - name: receptor_rfc
          type: VARCHAR(13)
          nullable: false
        - name: receptor_nombre
          type: VARCHAR(300)
          nullable: false
        - name: receptor_email
          type: VARCHAR(100)
          nullable: true
        - name: subtotal
          type: DECIMAL(18,2)
          nullable: false
        - name: total
          type: DECIMAL(18,2)
          nullable: false
        - name: moneda
          type: VARCHAR(3)
          nullable: false
          default: MXN
        - name: tipo_cambio
          type: DECIMAL(10,6)
          nullable: true
        - name: forma_pago
          type: VARCHAR(2)
          nullable: true
        - name: metodo_pago
          type: VARCHAR(3)
          nullable: false
        - name: uso_cfdi
          type: VARCHAR(3)
          nullable: false
        - name: estatus
          type: VARCHAR(20)
          nullable: false
          description: borrador, timbrado, cancelado, cancelacion_pendiente
        - name: xml_path
          type: VARCHAR(500)
          nullable: true
        - name: pdf_path
          type: VARCHAR(500)
          nullable: true
        - name: saldo_pendiente
          type: DECIMAL(18,2)
          nullable: true
          description: Para control de complementos de pago
        - name: contrato_id
          type: UUID
          nullable: true
          foreign_key: contratos.id
        - name: created_at
          type: TIMESTAMP
          default: NOW()
        - name: updated_at
          type: TIMESTAMP
          default: NOW()
      indexes:
        - columns: [uuid]
          unique: true
        - columns: [tenant_id, folio, serie]
        - columns: [receptor_rfc]
        - columns: [estatus]
        - columns: [fecha_emision]

    - name: cfdi_conceptos
      description: Conceptos/partidas de los CFDI
      columns:
        - name: id
          type: UUID
          primary_key: true
        - name: cfdi_id
          type: UUID
          nullable: false
          foreign_key: cfdi.id
        - name: numero
          type: INTEGER
          nullable: false
        - name: clave_prod_serv
          type: VARCHAR(8)
          nullable: false
        - name: clave_unidad
          type: VARCHAR(3)
          nullable: false
        - name: unidad
          type: VARCHAR(20)
          nullable: true
        - name: descripcion
          type: TEXT
          nullable: false
        - name: cantidad
          type: DECIMAL(18,6)
          nullable: false
        - name: valor_unitario
          type: DECIMAL(18,6)
          nullable: false
        - name: importe
          type: DECIMAL(18,2)
          nullable: false
        - name: descuento
          type: DECIMAL(18,2)
          nullable: true
        - name: objeto_imp
          type: VARCHAR(2)
          nullable: false
      indexes:
        - columns: [cfdi_id]

    - name: cfdi_impuestos
      description: Desglose de impuestos por concepto
      columns:
        - name: id
          type: UUID
          primary_key: true
        - name: concepto_id
          type: UUID
          nullable: false
          foreign_key: cfdi_conceptos.id
        - name: tipo
          type: VARCHAR(10)
          nullable: false
          description: traslado o retencion
        - name: impuesto
          type: VARCHAR(3)
          nullable: false
          description: 001=ISR, 002=IVA, 003=IEPS
        - name: tipo_factor
          type: VARCHAR(10)
          nullable: false
        - name: tasa_o_cuota
          type: DECIMAL(6,6)
          nullable: true
        - name: base
          type: DECIMAL(18,2)
          nullable: false
        - name: importe
          type: DECIMAL(18,2)
          nullable: false
      indexes:
        - columns: [concepto_id]

    - name: cfdi_cancelaciones
      description: Registro de solicitudes de cancelación
      columns:
        - name: id
          type: UUID
          primary_key: true
        - name: cfdi_id
          type: UUID
          nullable: false
          foreign_key: cfdi.id
        - name: fecha_solicitud
          type: TIMESTAMP
          nullable: false
          default: NOW()
        - name: motivo
          type: VARCHAR(2)
          nullable: false
          description: Catálogo de motivos SAT
        - name: uuid_sustitucion
          type: VARCHAR(36)
          nullable: true
        - name: estatus
          type: VARCHAR(20)
          nullable: false
          description: pendiente, aceptada, rechazada
        - name: fecha_respuesta
          type: TIMESTAMP
          nullable: true
        - name: respuesta_receptor
          type: VARCHAR(20)
          nullable: true
        - name: pac_acuse
          type: TEXT
          nullable: true
        - name: created_by
          type: UUID
          nullable: false
          foreign_key: users.id
      indexes:
        - columns: [cfdi_id]
        - columns: [estatus]

    - name: cfdi_recibidos
      description: CFDI recibidos de proveedores
      columns:
        - name: id
          type: UUID
          primary_key: true
        - name: tenant_id
          type: UUID
          nullable: false
          foreign_key: tenants.id
        - name: uuid
          type: VARCHAR(36)
          nullable: false
          unique: true
        - name: folio
          type: VARCHAR(20)
          nullable: true
        - name: serie
          type: VARCHAR(10)
          nullable: true
        - name: fecha_emision
          type: TIMESTAMP
          nullable: false
        - name: emisor_rfc
          type: VARCHAR(13)
          nullable: false
        - name: emisor_nombre
          type: VARCHAR(300)
          nullable: false
        - name: subtotal
          type: DECIMAL(18,2)
          nullable: false
        - name: total
          type: DECIMAL(18,2)
          nullable: false
        - name: moneda
          type: VARCHAR(3)
          nullable: false
        - name: estatus
          type: VARCHAR(20)
          nullable: false
          description: pendiente_validar, vigente, cancelado
        - name: xml_path
          type: VARCHAR(500)
          nullable: false
        - name: pdf_path
          type: VARCHAR(500)
          nullable: true
        - name: validado_sat
          type: BOOLEAN
          default: false
        - name: fecha_validacion
          type: TIMESTAMP
          nullable: true
        - name: orden_compra_id
          type: UUID
          nullable: true
          foreign_key: ordenes_compra.id
        - name: created_at
          type: TIMESTAMP
          default: NOW()
      indexes:
        - columns: [uuid]
          unique: true
        - columns: [tenant_id, emisor_rfc]
        - columns: [estatus]

    - name: complementos_pago
      description: Complementos de pago emitidos
      columns:
        - name: id
          type: UUID
          primary_key: true
        - name: cfdi_id
          type: UUID
          nullable: false
          foreign_key: cfdi.id
          description: CFDI tipo P que contiene el complemento
        - name: fecha_pago
          type: DATE
          nullable: false
        - name: forma_pago
          type: VARCHAR(2)
          nullable: false
        - name: moneda
          type: VARCHAR(3)
          nullable: false
        - name: tipo_cambio
          type: DECIMAL(10,6)
          nullable: true
        - name: monto
          type: DECIMAL(18,2)
          nullable: false
        - name: num_operacion
          type: VARCHAR(100)
          nullable: true
        - name: rfc_banco_ordenante
          type: VARCHAR(13)
          nullable: true
        - name: cuenta_ordenante
          type: VARCHAR(50)
          nullable: true
        - name: rfc_banco_beneficiario
          type: VARCHAR(13)
          nullable: true
        - name: cuenta_beneficiario
          type: VARCHAR(50)
          nullable: true
        - name: created_at
          type: TIMESTAMP
          default: NOW()
      indexes:
        - columns: [cfdi_id]

    - name: complementos_pago_documentos
      description: Documentos relacionados en complemento de pago
      columns:
        - name: id
          type: UUID
          primary_key: true
        - name: complemento_pago_id
          type: UUID
          nullable: false
          foreign_key: complementos_pago.id
        - name: cfdi_relacionado_id
          type: UUID
          nullable: false
          foreign_key: cfdi.id
        - name: uuid_documento
          type: VARCHAR(36)
          nullable: false
        - name: serie
          type: VARCHAR(10)
          nullable: true
        - name: folio
          type: VARCHAR(20)
          nullable: false
        - name: moneda
          type: VARCHAR(3)
          nullable: false
        - name: equivalencia_dr
          type: DECIMAL(10,6)
          nullable: true
        - name: num_parcialidad
          type: INTEGER
          nullable: false
        - name: imp_saldo_anterior
          type: DECIMAL(18,2)
          nullable: false
        - name: imp_pagado
          type: DECIMAL(18,2)
          nullable: false
        - name: imp_saldo_insoluto
          type: DECIMAL(18,2)
          nullable: false
        - name: objeto_imp_dr
          type: VARCHAR(2)
          nullable: false
      indexes:
        - columns: [complemento_pago_id]
        - columns: [cfdi_relacionado_id]

# ============================================================================
# PLAN DE IMPLEMENTACIÓN
# ============================================================================

implementation_plan:

  phases:
    - phase: 1
      name: Configuración y infraestructura
      duration: 2 semanas
      tasks:
        - Configurar integración con PAC de pruebas
        - Implementar servicio de validación SAT
        - Configurar almacenamiento de archivos XML/PDF
        - Crear estructura de base de datos
        - Configurar certificados de sello digital
      deliverables:
        - Integración con PAC funcional en ambiente de pruebas
        - Base de datos creada y migrada
        - Servicio de almacenamiento configurado

    - phase: 2
      name: Emisión de CFDI (RF-001)
      duration: 3 semanas
      tasks:
        - Implementar generador de XML CFDI 4.0
        - Desarrollar servicio de timbrado con PAC
        - Crear generador de PDF con representación impresa
        - Desarrollar interfaz de captura de CFDI
        - Implementar envío por correo electrónico
        - Pruebas de timbrado en ambiente de pruebas
      deliverables:
        - Módulo de emisión de CFDI completo
        - Casos de prueba ejecutados
        - Documentación de usuario

    - phase: 3
      name: Cancelación de CFDI (RF-002)
      duration: 2 semanas
      tasks:
        - Implementar servicio de cancelación vía PAC
        - Desarrollar flujo de aceptación/rechazo
        - Crear interfaz de gestión de cancelaciones
        - Implementar notificaciones de cancelación
        - Pruebas de cancelación
      deliverables:
        - Módulo de cancelación funcional
        - Sistema de notificaciones integrado
        - Casos de prueba ejecutados

    - phase: 4
      name: Recepción de CFDI (RF-003)
      duration: 2 semanas
      tasks:
        - Implementar parser de XML CFDI
        - Desarrollar validador ante SAT
        - Crear interfaz de carga de XML
        - Implementar asociación con órdenes de compra
        - Desarrollar consultas y reportes
      deliverables:
        - Módulo de recepción completo
        - Validación automática ante SAT
        - Reportes de CFDI recibidos

    - phase: 5
      name: Complementos de Pago (RF-004)
      duration: 2 semanas
      tasks:
        - Implementar generador de complemento de pago
        - Desarrollar calculadora de parcialidades
        - Crear interfaz de aplicación de pagos
        - Implementar actualización de saldos
        - Integrar con cuentas por cobrar
        - Pruebas de complementos
      deliverables:
        - Módulo de complementos de pago funcional
        - Integración con cuentas por cobrar
        - Actualización automática de saldos

    - phase: 6
      name: Pruebas integrales y despliegue
      duration: 1 semana
      tasks:
        - Pruebas de integración end-to-end
        - Pruebas de rendimiento
        - Migración a ambiente de producción
        - Configuración de PAC en producción
        - Capacitación a usuarios
        - Documentación final
      deliverables:
        - Sistema probado y validado
        - Ambiente de producción configurado
        - Usuarios capacitados
        - Documentación completa

  total_duration: 12 semanas

  resources:
    - role: Tech Lead
      allocation: 100%
    - role: Backend Developer
      allocation: 100%
      count: 2
    - role: Frontend Developer
      allocation: 100%
    - role: QA Engineer
      allocation: 50%
    - role: DevOps Engineer
      allocation: 25%

# ============================================================================
# MÉTRICAS Y KPIs
# ============================================================================

metrics:

  business_metrics:
    - name: CFDI emitidos por mes
      description: Número total de CFDI timbrados exitosamente
      target: "> 1000"
      measurement: Conteo mensual

    - name: Tasa de éxito de timbrado
      description: Porcentaje de CFDI timbrados exitosamente vs. intentos
      target: "> 98%"
      measurement: (Timbrados exitosos / Total intentos) * 100

    - name: Tiempo promedio de emisión
      description: Tiempo desde captura hasta timbrado exitoso
      target: "< 30 segundos"
      measurement: Promedio de tiempo por CFDI

    - name: Tasa de cancelación
      description: Porcentaje de CFDI cancelados vs. emitidos
      target: "< 5%"
      measurement: (Cancelados / Emitidos) * 100

    - name: CFDI recibidos validados
      description: Porcentaje de CFDI recibidos validados ante SAT
      target: "100%"
      measurement: (Validados / Total recibidos) * 100

  technical_metrics:
    - name: Disponibilidad del servicio
      description: Uptime del módulo de facturación
      target: "> 99.5%"
      measurement: Monitoreo continuo

    - name: Tiempo de respuesta API
      description: Tiempo promedio de respuesta de endpoints
      target: "< 500ms"
      measurement: Promedio de p95

    - name: Tasa de errores
      description: Porcentaje de requests con error
      target: "< 1%"
      measurement: (Errores / Total requests) * 100

    - name: Cobertura de pruebas
      description: Porcentaje de código cubierto por pruebas
      target: "> 80%"
      measurement: Análisis de cobertura

# ============================================================================
# RIESGOS Y MITIGACIONES
# ============================================================================

risks:

  - id: RISK-MAE-009-001
    description: Indisponibilidad del servicio del PAC
    probability: medium
    impact: high
    mitigation: |
      - Implementar sistema de cola para reintentos automáticos
      - Configurar PAC de respaldo
      - Alertas automáticas al equipo técnico
      - SLA con proveedor PAC

  - id: RISK-MAE-009-002
    description: Cambios en normativa SAT
    probability: high
    impact: high
    mitigation: |
      - Monitoreo continuo de publicaciones del SAT
      - Arquitectura flexible para adaptación rápida
      - Mantener compatibilidad con versiones anteriores
      - Equipo de compliance fiscal

  - id: RISK-MAE-009-003
    description: Problemas con certificados de sello digital
    probability: low
    impact: critical
    mitigation: |
      - Alertas de vencimiento 60 días antes
      - Proceso documentado de renovación
      - Respaldo de certificados en vault seguro
      - Procedimiento de emergencia

  - id: RISK-MAE-009-004
    description: Volumen alto de facturación (cierre de mes)
    probability: high
    impact: medium
    mitigation: |
      - Arquitectura escalable horizontalmente
      - Auto-scaling en cloud
      - Cache de validaciones frecuentes
      - Pruebas de carga periódicas

  - id: RISK-MAE-009-005
    description: Pérdida de archivos XML/PDF
    probability: low
    impact: high
    mitigation: |
      - Almacenamiento redundante (S3 con replicación)
      - Backups diarios automáticos
      - Registro en blockchain (opcional)
      - Posibilidad de re-descarga desde PAC

# ============================================================================
# NOTAS Y CONSIDERACIONES
# ============================================================================

notes: |
  1. CUMPLIMIENTO NORMATIVO:
     - Todas las funcionalidades deben cumplir con el Anexo 20 del SAT
     - Mantener actualización con versión vigente de CFDI (actualmente 4.0)
     - Consultar regularmente el Diario Oficial de la Federación

  2. SEGURIDAD:
     - Los certificados de sello digital (CSD) deben almacenarse encriptados
     - Implementar logs de auditoría para todas las operaciones
     - Control de acceso basado en roles para emisión de CFDI
     - Encriptación en tránsito y en reposo para archivos XML

  3. INTEGRACIONES:
     - Priorizar PAC con mejor uptime y soporte
     - Considerar integración con múltiples PAC para redundancia
     - Mantener ambiente de pruebas separado (sandbox PAC)

  4. EXPERIENCIA DE USUARIO:
     - Formularios con autocompletado de catálogos SAT
     - Validaciones en tiempo real antes de timbrar
     - Mensajes de error claros y accionables
     - Descarga masiva de XML y PDF

  5. RENDIMIENTO:
     - Optimizar para alta concurrencia en cierre de mes
     - Implementar procesamiento asíncrono para timbrado
     - Cache de catálogos SAT (actualización semanal)

  6. REPORTES Y ANALYTICS:
     - Dashboard de facturación con métricas clave
     - Reportes de CFDI para contabilidad
     - Integración con sistema contable
     - Exportación a formatos estándar (Excel, PDF, XML)

# ============================================================================
# HISTORIAL DE CAMBIOS
# ============================================================================

change_log:
  - version: 1.0.0
    date: 2025-12-06
    author: Sistema
    changes:
      - Creación inicial del archivo de trazabilidad
      - Definición de 4 requerimientos funcionales principales
      - Especificación de integraciones con PAC y SAT
      - Definición de modelo de datos
      - Plan de implementación en 6 fases
