rckrdmrd/erp-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
23786ad49f
erp-core/docs/97-adr/ADR-012-complete-traceability-policy.md

292 lines
13 KiB
Markdown
Raw Blame History

# 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
```yaml
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
```yaml
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
```yaml
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:
```markdown
## 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
```bash
# 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
1. **Análisis de impacto**: Saber qué afecta un cambio antes de hacerlo
2. **Debugging eficiente**: Trazar errores desde UI hasta BD
3. **Onboarding rápido**: Nuevos devs entienden relaciones rápidamente
4. **Refactoring seguro**: Conocer todos los dependientes antes de cambiar
5. **Documentación viva**: Siempre actualizada y útil
6. **Auditoría**: Saber origen y justificación de cada objeto
### Negativas (Manejables)
1. **Overhead inicial**: Requiere disciplina para documentar
- *Mitigación*: Templates y automatización
2. **Tiempo adicional**: Cada cambio requiere actualizar docs
- *Mitigación*: Incluir en Definition of Done
3. **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](./ADR-011-database-clean-load-strategy.md)
- [PROMPT-ARCHITECTURE-ANALYST.md](../../../shared/orchestration/prompts/PROMPT-ARCHITECTURE-ANALYST.md)
- [INVENTARIO-OBJETOS-BD.yml](../02-modelado/trazabilidad/INVENTARIO-OBJETOS-BD.yml)
- [MATRIZ-TRAZABILIDAD-RF-ET-BD.md](../02-modelado/trazabilidad/MATRIZ-TRAZABILIDAD-RF-ET-BD.md)
---
**Aprobado por:** Architecture-Analyst
**Fecha de aprobación:** 2025-11-24
Reference in New Issue View Git Blame Copy Permalink