66161b1566
Sistema NEXUS v3.4 migrado con: Estructura principal: - core/orchestration: Sistema SIMCO + CAPVED (27 directivas, 28 perfiles) - core/catalog: Catalogo de funcionalidades reutilizables - shared/knowledge-base: Base de conocimiento compartida - devtools/scripts: Herramientas de desarrollo - control-plane/registries: Control de servicios y CI/CD - orchestration/: Configuracion de orquestacion de agentes Proyectos incluidos (11): - gamilit (submodule -> GitHub) - trading-platform (OrbiquanTIA) - erp-suite con 5 verticales: - erp-core, construccion, vidrio-templado - mecanicas-diesel, retail, clinicas - betting-analytics - inmobiliaria-analytics - platform_marketing_content - pos-micro, erp-basico Configuracion: - .gitignore completo para Node.js/Python/Docker - gamilit como submodule (git@github.com:rckrdmrd/gamilit-workspace.git) - Sistema de puertos estandarizado (3005-3199) Generated with NEXUS v3.4 Migration System EPIC-010: Configuracion Git y Repositorios
13 KiB
13 KiB
ADR-012: Política de Trazabilidad Completa
Estado: Aceptado Fecha: 2025-11-24 Decisores: Architecture-Analyst, Tech Lead Contexto: ERP Generic - Gestión de documentación y trazabilidad
Contexto
El proyecto ERP Generic es un sistema empresarial complejo con múltiples capas (Base de Datos, Backend, Frontend) y cientos de objetos interrelacionados. Para mantener la coherencia, facilitar el mantenimiento y permitir análisis de impacto, necesitamos una política estricta de trazabilidad que conecte todos los artefactos del sistema.
Decisión
Adoptamos la política de "Trazabilidad Completa End-to-End" para todos los objetos del sistema.
Principio Fundamental
┌─────────────────────────────────────────────────────────────────────────┐
│ TRAZABILIDAD COMPLETA │
│ │
│ RF (Requerimiento) ──→ ET-Backend ──→ ET-Frontend ──→ US (Stories) │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Tablas │◄────────►│ APIs │◄───►│ Comps │◄──►│ Tests │ │
│ │ BD │ │ Backend │ │ Frontend│ │ E2E │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ │
│ TODO OBJETO DEBE CONOCER: │
│ • Su ORIGEN (RF/ET que lo define) │
│ • Sus DEPENDENCIAS (de qué depende) │
│ • Sus DEPENDIENTES (qué depende de él) │
│ • Sus RELACIONES con otras capas │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Inventarios Requeridos
| Inventario | Ubicación | Contenido |
|---|---|---|
| Objetos BD | trazabilidad/INVENTARIO-OBJETOS-BD.yml |
Tablas, funciones, triggers, enums, policies |
| Objetos Backend | trazabilidad/INVENTARIO-OBJETOS-BACKEND.yml |
Controllers, services, DTOs, repositories |
| Objetos Frontend | trazabilidad/INVENTARIO-OBJETOS-FRONTEND.yml |
Components, pages, hooks, stores |
| Matriz Completa | trazabilidad/MATRIZ-TRAZABILIDAD-COMPLETA.md |
RF → ET → BD → Backend → Frontend → Tests |
Estructura de Trazabilidad por Capa
Base de Datos
tabla:
nombre: financial.invoices
schema: financial
origen:
rf: RF-MGN-004-005
et_backend: ET-BACKEND-MGN-004-005
dependencias:
tablas:
- auth.tenants
- auth.companies
- core.partners
- core.currencies
funciones:
- calculate_invoice_totals()
dependientes:
tablas:
- financial.invoice_lines
- financial.payment_invoice
triggers:
- trg_invoices_updated_at
- track_invoice_changes
relacionados:
backend:
- InvoiceController
- InvoiceService
- InvoiceRepository
frontend:
- InvoiceForm.tsx
- InvoiceList.tsx
Backend
servicio:
nombre: InvoiceService
modulo: financial
origen:
rf: RF-MGN-004-005
et_backend: ET-BACKEND-MGN-004-005
dependencias:
tablas:
- financial.invoices
- financial.invoice_lines
servicios:
- PartnerService
- ProductService
- TaxService
dependientes:
controllers:
- InvoiceController
otros_servicios:
- PaymentService
- ReportService
relacionados:
frontend:
- useInvoice.hook.ts
- invoice.api.ts
Frontend
componente:
nombre: InvoiceForm.tsx
modulo: financial
tipo: form
origen:
rf: RF-MGN-004-005
et_frontend: ET-FRONTEND-MGN-004-005
us: US-MGN-004-010
dependencias:
apis:
- POST /api/v1/invoices
- GET /api/v1/partners
- GET /api/v1/products
hooks:
- useInvoice
- usePartners
stores:
- invoiceStore
dependientes:
pages:
- InvoicePage.tsx
tests:
- InvoiceForm.spec.tsx
Reglas de Mantenimiento de Documentación
┌─────────────────────────────────────────────────────────────────────────┐
│ REGLA 1: CREAR → DOCUMENTAR │
│ ───────────────────────────── │
│ Al crear cualquier objeto nuevo: │
│ ✅ Agregar al inventario correspondiente │
│ ✅ Documentar RF/ET/US de origen │
│ ✅ Mapear dependencias y dependientes │
│ ✅ Vincular con objetos de otras capas │
├─────────────────────────────────────────────────────────────────────────┤
│ REGLA 2: MODIFICAR → ACTUALIZAR │
│ ───────────────────────────────── │
│ Al modificar cualquier objeto: │
│ ✅ Actualizar inventario si cambió estructura │
│ ✅ Verificar impacto en dependientes │
│ ✅ Actualizar documentación relacionada │
│ ✅ Notificar cambios en capas afectadas │
├─────────────────────────────────────────────────────────────────────────┤
│ REGLA 3: ELIMINAR → LIMPIAR │
│ ────────────────────────────── │
│ Al eliminar o deprecar objeto: │
│ ✅ Eliminar del inventario │
│ ✅ Actualizar dependientes que lo usaban │
│ ✅ Eliminar referencias huérfanas │
│ ✅ Documentar razón de eliminación │
├─────────────────────────────────────────────────────────────────────────┤
│ REGLA 4: PR → VALIDAR TRAZABILIDAD │
│ ──────────────────────────────────── │
│ Todo PR debe incluir: │
│ ✅ Actualización de inventarios si aplica │
│ ✅ Actualización de matriz de trazabilidad │
│ ✅ Verificación de dependencias actualizadas │
├─────────────────────────────────────────────────────────────────────────┤
│ REGLA 5: REVISIÓN SEMANAL │
│ ──────────────────────────── │
│ Semanalmente verificar: │
│ ✅ Consistencia documentación vs código │
│ ✅ Objetos huérfanos (sin traza) │
│ ✅ Referencias rotas │
│ ✅ Inventarios completos │
└─────────────────────────────────────────────────────────────────────────┘
Formato de Trazabilidad en Documentos
Todo documento de especificación (RF, ET, US) debe incluir esta sección:
## Trazabilidad
### Origen
- **RF:** RF-MGN-004-005 (Gestión de facturas de cliente)
### Dependencias (De qué depende)
| Capa | Objetos |
|------|---------|
| BD | financial.invoices, invoice_lines, core.partners |
| Backend | PartnerService, ProductService, TaxService |
| Frontend | PartnerSelect, ProductSearch |
### Dependientes (Qué depende de esto)
| Capa | Objetos |
|------|---------|
| BD | financial.payment_invoice |
| Backend | PaymentService, ReportService |
| Frontend | PaymentForm, InvoiceReport |
### Objetos Implementados
| Capa | Objeto | Archivo |
|------|--------|---------|
| BD | financial.invoices | ddl/04-financial.sql:L100 |
| Backend | InvoiceController | src/modules/financial/invoice.controller.ts |
| Backend | InvoiceService | src/modules/financial/invoice.service.ts |
| Frontend | InvoiceForm | src/components/financial/InvoiceForm.tsx |
| Test | invoice.e2e | tests/e2e/invoice.spec.ts |
Herramientas de Validación
# Validar consistencia de inventarios (futuro script)
./scripts/validate-traceability.sh
# Generar reporte de objetos huérfanos
./scripts/find-orphan-objects.sh
# Verificar referencias cruzadas
./scripts/check-cross-references.sh
Consecuencias
Positivas
- Análisis de impacto: Saber qué afecta un cambio antes de hacerlo
- Debugging eficiente: Trazar errores desde UI hasta BD
- Onboarding rápido: Nuevos devs entienden relaciones rápidamente
- Refactoring seguro: Conocer todos los dependientes antes de cambiar
- Documentación viva: Siempre actualizada y útil
- Auditoría: Saber origen y justificación de cada objeto
Negativas (Manejables)
- Overhead inicial: Requiere disciplina para documentar
- Mitigación: Templates y automatización
- Tiempo adicional: Cada cambio requiere actualizar docs
- Mitigación: Incluir en Definition of Done
- Curva de aprendizaje: Entender estructura de trazabilidad
- Mitigación: Guías y ejemplos claros
Directiva para Agentes
Esta decisión es OBLIGATORIA para todos los agentes:
🔴 DIRECTIVA ADR-012 - TRAZABILIDAD COMPLETA
Los agentes DEBEN:
✅ Verificar trazabilidad antes de crear objetos nuevos
✅ Actualizar inventarios al crear/modificar/eliminar objetos
✅ Documentar dependencias y dependientes
✅ Mantener referencias cruzadas entre capas
✅ Incluir sección de trazabilidad en documentos
Los agentes NO DEBEN:
❌ Crear objetos sin documentar origen (RF/ET/US)
❌ Modificar objetos sin actualizar dependientes
❌ Eliminar objetos sin limpiar referencias
❌ Ignorar impacto en otras capas
❌ Dejar documentación desactualizada
ANTES DE IMPLEMENTAR, VERIFICAR:
1. ¿El objeto tiene RF/ET que lo define?
2. ¿Están mapeadas sus dependencias?
3. ¿Están identificados sus dependientes?
4. ¿Está en el inventario correspondiente?
5. ¿La documentación está actualizada?
Referencias
- ADR-011: Database Clean Load Strategy
- PROMPT-ARCHITECTURE-ANALYST.md
- INVENTARIO-OBJETOS-BD.yml
- MATRIZ-TRAZABILIDAD-RF-ET-BD.md
Aprobado por: Architecture-Analyst Fecha de aprobación: 2025-11-24