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