Versión: 1.0
Fecha: 27 de Diciembre, 2025
Estado: NORMATIVO - Gobernanza Operativa
Arquitecto: Carlos Alberto Torres Camargo
Este documento define la gobernanza operativa completa de la fábrica de software Nebula ERP. Es la biblia operativa que TODO el equipo debe seguir.
Alcance:
| Actividad | Arquitecto | Gatekeeper | Backend Sr | Backend Jr | Frontend Sr | QA | DevOps |
|---|---|---|---|---|---|---|---|
| Definir arquitectura de nuevo microservicio | R/A | C | C | I | I | I | C |
| Generar microservicio con arquetipo | A | I | R | I | I | I | C |
| Aprobar PR de CentricaModel | A | R | C | I | I | I | I |
| Aprobar PR de microservicio | I | A | R | C | I | I | I |
| Definir Entities core (Tercero, Cuenta) | R/A | C | C | I | I | I | I |
| Definir Entities features | A | C | R | C | I | I | I |
| Aprobar migraciones Flyway | A | C | R | I | I | I | C |
| Implementar lógica de negocio | I | C | R/A | C | I | I | I |
| Code review código negocio | I | A | R | C | C | I | I |
| Ejecutar tests unitarios | I | I | R/A | R | R | C | I |
| Ejecutar tests integración | I | I | C | C | I | R/A | C |
| Deploy a DEV | I | I | I | I | I | I | R/A |
| Aprobar deploy a QA | I | A | I | I | I | R | C |
| Aprobar deploy a PROD | A | C | I | I | I | R | C |
| Definir Definition of Done | R/A | C | C | I | C | C | I |
| Reportar métricas DORA | C | I | I | I | I | I | R/A |
Leyenda:
Autoridad Técnica Máxima
Responsabilidades:
NO es responsable de:
Guardián de Calidad de Código
Responsabilidades:
Autoridad:
Líder Técnico de Implementación
Responsabilidades:
Implementador Guiado
Responsabilidades:
Requiere aprobación de:
Similar a Backend Senior, para Angular
Guardián de Calidad Funcional
Responsabilidades:
Autoridad:
Guardián de Infraestructura y Pipelines
Responsabilidades:
Template JIRA:
**Título:** [NEB-XXX] Como [ROL] necesito [FUNCIONALIDAD] para [BENEFICIO]
**Descripción:**
Como contador, necesito registrar terceros (clientes, proveedores) con su
información fiscal (NIT, nombre, dirección) para poder crear asientos
contables y facturas.
**Criterios de Aceptación:**
- [ ] CRUD completo de terceros
- [ ] Validación de NIT con dígito de verificación
- [ ] Tipos de tercero: CLIENTE, PROVEEDOR, EMPLEADO
- [ ] Búsqueda por NIT y nombre
- [ ] Paginación y ordenamiento
- [ ] API documentada en Swagger UI
**Dependencias:**
- CentricaModel debe tener TerceroDto
**Estimación:** 8 Story Points
**Asignado a:** [Sin asignar - espera análisis arquitecto]
Checklist:
Comentario del Arquitecto en JIRA:
@backend-senior-1
**Análisis Arquitectónico:**
✅ **NO requiere nuevo microservicio** - Usar nebula-accounting existente
✅ **Requiere cambios en CentricaModel** - Crear TerceroDto
✅ **Tablas:** contabilidad.tercero (con índice en numero_identificacion)
✅ **Multi-Tenancy:** @ConnectionContext en TerceroComponent
✅ **Validaciones:** Dígito de verificación NIT (algoritmo colombiano)
**Directrices:**
1. DTO en CentricaModel primero (PR separado)
2. Migración Flyway V1\_\_create_table_tercero.sql (3 motores)
3. Validación de NIT duplicado en Component
4. Tests unitarios >80% cobertura
**Estimación confirmada:** 8 SP (2-3 días)
Adelante.
Solo si es microservicio NUEVO
Paso 1: Backend Senior solicita creación
# Email al Arquitecto
Asunto: Solicitud de nuevo microservicio: nebula-inventory
Arquitecto,
Requiero creación de microservicio nebula-inventory para gestión de inventarios.
Razón: Separación de responsabilidades. Accounting no debe manejar stock.
Features iniciales:
- Productos
- Bodegas
- Movimientos de inventario (entrada/salida)
- Valoración (PEPS, Promedio Ponderado)
Aprobación: [Adjuntar ticket JIRA NEB-XXX]
Gracias,
[Backend Senior]
Paso 2: Arquitecto genera con arquetipo
# Ejecutado por Arquitecto
mvn archetype:generate \
-DarchetypeGroupId=com.catcsoft.simappe \
-DarchetypeArtifactId=SimappeArchetype \
-DarchetypeVersion=1.0.26-SNAPSHOTS \
-DgroupId=com.centrica.nebula \
-DartifactId=nebula-inventory \
-Dversion=1.0.0-SNAPSHOT \
-DinteractiveMode=false
Paso 3: Arquitecto configura base
cd nebula-inventory
# Actualizar README.md
# Configurar application.yml (Eureka, Config Server, DB)
# Crear Jenkinsfile
git init
git add .
git commit -m "chore: generar microservicio nebula-inventory con SimappeArchetype
- Estructura base con patrón Component
- Configuración multi-tenancy
- Dependencias a SimappeCommons 1.0.26-SNAPSHOTS
- Dockerfile y docker-compose.yml
Refs: NEB-XXX"
git remote add origin git@github.com:centrica/nebula-inventory.git
git push -u origin main
git checkout -b develop
git push -u origin develop
Paso 4: DevOps configura CI/CD
# Jenkins: Crear pipeline para nebula-inventory
# Nexus: Crear repositorio maven-snapshots/nebula-inventory
# Kubernetes: Crear namespace y deployment
# Secrets: Configurar variables de entorno en Vault
Paso 5: Arquitecto notifica a Backend Senior
@backend-senior-1
Microservicio nebula-inventory creado y listo para desarrollo:
**Repositorio:** https://github.com/centrica/nebula-inventory
**Branch principal:** develop
**CI/CD:** http://jenkins.internal/job/nebula-inventory
**Swagger UI (DEV):** http://dev-inventory.internal/swagger-ui.html
**Estructura creada:**
- Entity: ProductoEntity (ejemplo)
- Repository: ProductoRepository
- Component: ProductoComponent
- Service: ProductoService
- Controller: ProductoController
**Pendiente:**
1. Actualizar DTOs en CentricaModel
2. Crear migraciones Flyway
3. Implementar lógica de negocio
Adelante con NEB-XXX.
Ver: FLUJO_DESARROLLO_NEBULA.md para detalles técnicos completos.
Resumen:
developChecklist de Code Review:
Obligatorio (bloquea merge si falta):
Recomendaciones (no bloquea, pero comentar):
Aprobación:
✅ **APROBADO**
**Revisión:**
- ✅ Tests pasan (92% cobertura)
- ✅ SonarQube OK (0 issues críticos)
- ✅ Validación de NIT correcta
- ✅ Multi-tenancy implementado
- ⚠️ Sugerencia: Agregar índice en `tercero.nombre` para búsquedas rápidas
**Próximo paso:** Merge a develop → CI/CD → Deploy DEV
Adelante.
Checklist de QA:
Reporte QA (si pasa):
✅ **QA APROBADO**
**Tests ejecutados:**
- ✅ Integración: 15/15 pasan
- ✅ E2E: 8/8 pasan
- ✅ Manual: CRUD completo funciona
- ✅ Multi-Tenancy: Datos aislados correctamente
- ✅ Performance: P95 = 320ms (OK)
**Aprobación para deploy a QA.**
Ticket: NEB-XXX
Reporte QA (si falla):
❌ **BUG CRÍTICO ENCONTRADO**
**Descripción:**
Validación de NIT no funciona para NITs con DV = 0
**Pasos para reproducir:**
1. POST /api/v1/accounting/terceros/create
2. Body: {"nit": "860502609", "dv": "0", ...}
3. Response: 400 Bad Request "DV inválido. Calculado: 0, Proporcionado: 0"
**Esperado:** Crear tercero con DV = 0
**Actual:** Rechaza con error
**Evidencia:** [Adjuntar screenshot Postman]
**Severidad:** CRÍTICA (bloquea feature)
**Asignado a:** @backend-senior-1
Ticket: NEB-XXX-BUG1
Aprobadores: Arquitecto + QA Lead
Pre-requisitos:
Aprobación del Arquitecto:
✅ **APROBADO PARA PRODUCCIÓN**
**Validación arquitectónica:**
- ✅ Multi-tenancy funciona correctamente
- ✅ Performance aceptable (<500ms P95)
- ✅ Sin vulnerabilidades de seguridad
- ✅ Migraciones Flyway testeadas
- ✅ Rollback plan documentado
**Autorización:** Deploy a PROD autorizado para Sprint 1.4 Release.
**Monitoreo post-deploy:** 24 horas intensivo.
Adelante DevOps.
Ejecución (DevOps):
# Deploy con kubectl
kubectl set image deployment/nebula-accounting \
nebula-accounting=registry.centrica.internal/nebula-accounting:v1.1.0 \
-n nebula-prod
kubectl rollout status deployment/nebula-accounting -n nebula-prod
# Smoke tests
./scripts/smoke-test-prod.sh
# Monitoreo
# Grafana: http://grafana.internal/d/nebula-prod
# Logs: kubectl logs -f deployment/nebula-accounting -n nebula-prod
Reporte Post-Deploy:
✅ **DEPLOY A PRODUCCIÓN EXITOSO**
**Versión:** v1.1.0
**Fecha:** 2025-01-20 22:00 UTC-5
**Downtime:** 0 segundos (rolling update)
**Smoke Tests:**
- ✅ Health check: OK
- ✅ Database connectivity: OK
- ✅ Kafka connectivity: OK
- ✅ First CRUD operation: OK (180ms)
**Monitoreo 24h:** En progreso
Ticket: NEB-XXX
| Tipo de Entity | Definido Por | Aprobado Por | Razón |
|---|---|---|---|
| Core Business (Tercero, Cuenta, Factura, Producto) | Arquitecto | Arquitecto | Impacto en toda la aplicación |
| Features Específicas (ReporteInventario, ConfiguracionCRM) | Backend Senior | Arquitecto (revisión) | Funcionalidad específica de módulo |
| Auxiliares/DTOs Internos | Cualquier Backend | Gatekeeper | No se exponen externamente |
Paso 1: Arquitecto crea ADR (Architecture Decision Record)
# ADR-005: Modelo de Datos Tercero
**Fecha:** 2025-01-10
**Estado:** APROBADO
**Decisión:** Definir estructura de entidad Tercero
**Contexto:**
Nebula requiere gestión de terceros (clientes, proveedores, empleados) con
información fiscal completa para cumplimiento normativo colombiano.
**Decisión:**
Tabla: contabilidad.tercero
Campos core:
- id (BIGINT, PK)
- tipo_identificacion (VARCHAR(20), FK a tipo_identificacion)
- numero_identificacion (VARCHAR(20), UNIQUE con tipo)
- digito_verificacion (CHAR(1))
- nombre (VARCHAR(200), NOT NULL)
- tipo_tercero (VARCHAR(20), CHECK: CLIENTE, PROVEEDOR, EMPLEADO)
- activo (BOOLEAN, DEFAULT true)
- campos de auditoría (BusinessBaseEntity)
Índices:
- idx_tercero_nit (numero_identificacion, tipo_identificacion)
- idx_tercero_nombre (nombre) para búsquedas
**Consecuencias:**
- Modelo normalizado
- Búsquedas rápidas por NIT
* Requiere migraciones en 3 motores SQL
**Implementación:** @backend-senior-1
**Refs:** NEB-XXX
Paso 2: Backend Senior implementa según ADR
// Entity DEBE seguir 100% el ADR del arquitecto
@Entity
@Table(name = "tercero", schema = "contabilidad",
indexes = {
@Index(name = "idx_tercero_nit",
columnList = "numero_identificacion, tipo_identificacion"),
@Index(name = "idx_tercero_nombre", columnList = "nombre")
}
)
public class Tercero extends BusinessBaseEntity<LongId> {
// EXACTAMENTE como define el ADR
}
TODAS las migraciones requieren aprobación del Arquitecto. SIN EXCEPCIONES.
Checklist de Migración:
Aprobación del Arquitecto:
✅ **MIGRACIÓN APROBADA**
**Archivo:** V5**add_column_saldo_to_cuenta_contable.sql
**Impacto:** LOW (solo ALTER TABLE ADD COLUMN)
**Downtime:** 0 segundos (columna nullable)
**Rollback:** Posible con V5**rollback.sql (DROP COLUMN)
**Validaciones:**
- ✅ Script para 3 motores SQL
- ✅ Probado en DEV
- ✅ No rompe datos existentes
- ✅ Índices no afectados
**Autorización:** Ejecutar en QA primero, luego PROD.
Adelante.
Formato:
**Daily Standup - 2025-01-20**
**@backend-senior-1:**
- Ayer: Implementé CRUD de Terceros (NEB-158), PR creado
- Hoy: Code review de PR de junior, iniciar NEB-159
- Bloqueadores: Ninguno
**@backend-junior-1:**
- Ayer: Tests unitarios para TerceroComponent (92% cobertura)
- Hoy: Corregir bug NEB-158-BUG1 (validación DV)
- Bloqueadores: Necesito acceso a base de datos QA
**@qa-automation:**
- Ayer: Tests E2E de Terceros (8/8 pasan)
- Hoy: Smoke tests en QA para release 1.4
- Bloqueadores: QA environment down desde ayer
**@devops:**
- Ayer: Deploy de nebula-accounting v1.1.0 a DEV
- Hoy: Configurar monitoreo Prometheus para nuevo microservicio
- Bloqueadores: Permisos de Vault pendientes
**Arquitecto:**
- Revisión de ADR-005 (Modelo Tercero)
- Code review de PR CentricaModel #45
Agenda:
Métricas Presentadas:
**Sprint 1.4 Review - 2025-01-20**
**Velocidad:**
- Story Points completados: 34 / 40 planeados (85%)
- Historias completadas: 5 / 6
**Calidad:**
- Bugs críticos: 1 (NEB-158-BUG1, corregido)
- Bugs menores: 3 (en backlog)
- Cobertura de tests: 87% (meta: 80%)
- Backend: 89%
- Frontend: 84%
**Performance:**
- Latencia P95: 280ms (meta: <500ms) ✅
- Throughput: 150 req/seg (meta: 100 req/seg) ✅
**CI/CD:**
- Build success rate: 94% (fallos por tests intermitentes)
- Deploy frequency: 12 deploys a DEV
- Lead time: 2.1 días (ticket → producción)
**Deuda Técnica:**
- Items nuevos: 2 (refactorizar validación NIT, optimizar query de búsqueda)
- Items cerrados: 1
**Features Completadas:**
1. NEB-156: Integración DIAN ✅
2. NEB-157: Reporte contable ✅
3. NEB-158: CRUD Terceros ✅
4. NEB-159: Validación terceros ✅
5. NEB-160: Dashboard flujo de caja ✅
**Bloqueadores Resueltos:**
- Acceso a QA environment (DevOps)
- Credenciales DIAN de prueba (Arquitecto)
**Próximo Sprint:**
- 6 historias (42 SP)
- Focus: Facturación electrónica
DevOps reporta semanalmente en dashboard Grafana:
| Métrica | Valor Actual | Meta | Estado |
|---|---|---|---|
| Deployment Frequency | 12 deploys/semana | >5 deploys/semana | ✅ ELITE |
| Lead Time for Changes | 2.1 días | <7 días | ✅ HIGH |
| Change Failure Rate | 8% (1 rollback / 12 deploys) | <15% | ✅ HIGH |
| Time to Restore Service | 45 minutos | <1 hora | ✅ ELITE |
Dashboard URL: http://grafana.internal/d/dora-metrics
Backend Senior envía cada viernes:
**Reporte Semanal Backend - Semana 2025-01-13 a 2025-01-19**
**Completadas:**
- NEB-158: CRUD Terceros (8 SP) ✅
- NEB-159: Validación terceros (3 SP) ✅
- Code review: 12 PRs revisados
- Mentoring: 3 sesiones con junior sobre multi-tenancy
**En Progreso:**
- NEB-160: Dashboard flujo de caja (13 SP, 60% completo)
**Bloqueadores:**
- Ninguno
**Métricas:**
- PRs mergeados: 5
- Tests escritos: 47 tests unitarios nuevos
- Cobertura: 89% (+2% vs semana anterior)
- Bugs reportados por QA: 1 crítico (corregido), 2 menores
**Deuda Técnica:**
- Identificada: Refactorizar TerceroComponent (muy largo, 250 líneas)
- Propuesta: Sprint 1.6
**Próxima Semana:**
- Completar NEB-160
- Iniciar NEB-161 (Integración pasarela pagos)
- Code review para release 1.5
Saludos,
[Backend Senior]
Una historia SOLO está DONE cuando:
Código:
Tests:
Documentación:
Calidad:
Base de Datos:
Deployment:
Aceptación:
Un microservicio SOLO está listo cuando:
Código Base:
Infraestructura:
Documentación:
Tests:
Validación:
Un release SOLO va a PROD cuando:
Funcionalidad:
Calidad:
Documentación:
Aprobaciones:
Operaciones:
| Acción | Aprobadores Requeridos | Tiempo SLA |
|---|---|---|
| PR a CentricaModel | Gatekeeper + Arquitecto | 24 horas |
| PR a microservicio (código normal) | Gatekeeper o Senior | 8 horas |
| Migración Flyway | Arquitecto | 48 horas |
| Creación de microservicio nuevo | Arquitecto | 72 horas |
| Deploy a DEV | Automático (CI/CD) | 0 horas |
| Deploy a QA | Gatekeeper | 4 horas |
| Deploy a PROD | Arquitecto + QA Lead | 24 horas |
| Cambio arquitectónico mayor | Arquitecto + Equipo completo | 1 semana |
Nivel 1: Backend (Autónomo)
Decisión: Backend decide solo, notifica en daily standup.
Nivel 2: Gatekeeper (Code Review)
Decisión: Gatekeeper aprueba, notifica a Arquitecto.
Nivel 3: Arquitecto (Arquitectura)
Decisión: Arquitecto aprueba, documenta en ADR.
Nivel 4: Arquitecto + Equipo (Estratégica)
Decisión: Arquitecto lidera, equipo vota, se documenta en ADR Mayor.
Deuda Técnica: Código o arquitectura que funciona AHORA pero requerirá refactorización DESPUÉS por:
| Tipo | Severidad | Plazo Máximo para Abordar |
|---|---|---|
| Crítica | Bloquea nuevas features | 1 sprint |
| Alta | Impacta performance o mantenibilidad | 3 sprints |
| Media | Dificulta desarrollo futuro | 6 meses |
| Baja | Mejora "nice to have" | 1 año o nunca |
Paso 1: Identificación
Cualquier miembro del equipo puede identificar deuda técnica en:
Paso 2: Registro
**Título:** [TECH-DEBT] Refactorizar TerceroComponent (muy largo)
**Descripción:**
TerceroComponent tiene 250 líneas, viola SRP (Single Responsibility Principle).
Mezcla validación de negocio, transformación de datos y logging.
**Impacto:**
- Dificulta tests unitarios (muchos mocks necesarios)
- Dificulta agregar nuevas validaciones sin romper existentes
- Código duplicado en validación de NIT (se repite en 3 lugares)
**Propuesta de Solución:**
1. Extraer validaciones a TerceroValidator
2. Extraer transformaciones a TerceroMapper
3. Simplificar TerceroComponent a <100 líneas
**Estimación:** 5 Story Points
**Prioridad:** MEDIA (no bloquea desarrollo actual)
**Asignado a:** [Backlog - para planificación]
Refs: NEB-DEBT-005
Paso 3: Priorización (Sprint Planning)
Arquitecto y equipo priorizan deuda técnica vs features nuevas:
Paso 4: Ejecución
Igual que feature normal:
Paso 5: Validación
Arquitecto valida que la deuda técnica fue realmente resuelva:
Este documento define la gobernanza operativa completa de la fábrica de software Nebula.
Es NORMATIVO: TODO el equipo DEBE seguirlo.
Responsabilidad del Arquitecto:
Responsabilidad del Equipo:
Actualización:
Documento Normativo - Proceso Operativo Fábrica de Software
© 2025 CatcSoft - Medellín, Colombia
| Version | Fecha | Autor | Descripcion |
|---|---|---|---|
| 1.1.0 | 2026-03-04 | Carlos Torres | Revision, sanitizacion y publicacion en Wiki Arquitectura Centrica. |
| 1.0.0 | 2025-12-27 | Carlos Torres | Creacion del documento. |