Skip to content

ddd-model.es.md

Latest commit

 

History

History
306 lines (259 loc) · 15 KB

ddd-model.es.md

File metadata and controls

306 lines (259 loc) · 15 KB

Evolith Tracker: Modelo DDD - Módulo Artifacts

Navegación bilingüe: English · Español (este documento)

Este documento define el diseño táctico y estratégico del Bounded Context de Artifacts. Es un subdominio de soporte que gobierna el ciclo de vida de cada artefacto y registro de evidencia producido a través de las 5 Phase Gates — la prueba durable y auditable de que cada gate fue superada legítimamente. Las definiciones de artefactos se heredan de Evolith Core (Conformist); las instancias y evidencias se producen localmente. Fuente de los agregados: TAD §3. Relaciones estratégicas: Bounded Context Map.

1. Lenguaje Ubicuo (Ubiquitous Language)

  • Artifact Definition: El esquema/plantilla canónico de un tipo de artefacto (ej. Discovery Canvas, ADR, Technical Blueprint, Test Summary), heredado de Evolith Core. Inmutable en el upstream.
  • Artifact Instance: Un artefacto concreto producido por una gate contra una definición, vinculado a un tenant y a una ejecución del SDLC.
  • Evidence Record: Prueba inmutable que vincula una instancia de artefacto (o resultado externo) a la decisión de gate que justificó. La columna vertebral de la auditabilidad (BR-009).
  • Evidence Chain: El conjunto ordenado de registros de evidencia que traza una iniciativa desde la idea hasta el despliegue.
  • Validation Result: El resultado de verificar una instancia de artefacto contra su definición y los rulesets de Evolith Core.

2. Mapas Conceptuales y Agregados (Mermaid)

2.0. Leyendas Visuales y Glosario

Símbolo/Estereotipo Significado
<<Aggregate Root>> Entidad raíz transaccional.
<<Entity>> Objeto con identidad, dependiente de su raíz.
<<Value Object>> Objeto inmutable sin identidad intrínseca.
<<Shared Kernel Shell>> Módulo transversal inyectado por aplicación/infraestructura.
*-- (Línea sólida) Composición.
..> (Línea punteada) Dependencia.

2.1. Vista 1: Núcleo de Artifacts (Agregados y Entidades)

classDiagram
    class ArtifactDefinition {
        <<Aggregate Root>>
        +UUID id
        +String code
        +String name
        +String coreSchemaUrl
        +SDLCPhase phase
        +String version
        +Boolean isMandatory
        +syncFromCore(CoreArtifactSchema)
        +deprecate()
    }

    class ArtifactInstance {
        <<Aggregate Root>>
        +UUID id
        +String tenantId
        +UUID artifactDefinitionId
        +UUID sdlcExecutionId
        +SDLCPhase phase
        +ArtifactFormat format
        +String contentRef
        +ArtifactStatus status
        +submit(UUID umsUserId)
        +validate(ValidationResult)
        +supersede(UUID newInstanceId)
    }

    class EvidenceRecord {
        <<Aggregate Root>>
        +UUID id
        +String tenantId
        +UUID sdlcExecutionId
        +SDLCPhase phase
        +EvidenceType type
        +UUID artifactInstanceId
        +String sourceSystem
        +Date capturedAt
        +capture(UUID umsUserId)
    }

    class ValidationResult {
        <<Entity>>
        +Boolean isCompliant
        +List~String~ violations
        +String validatedAgainstRuleset
        +Date validatedAt
    }

    ArtifactDefinition "1" --> "0..*" ArtifactInstance : plantilla de
    ArtifactInstance "1" *-- "0..1" ValidationResult : validado por
    ArtifactInstance "1" --> "0..*" EvidenceRecord : evidenciado por
Loading

2.2. Vista 2: Cadena de Evidencia y Auditoría (Value Objects)

classDiagram
    class EvidenceChain {
        <<Value Object>>
        +List~UUID~ orderedEvidenceIds
        +append(UUID evidenceRecordId)
        +isComplete(SDLCPhase) Boolean
    }

    class ContentReference {
        <<Value Object>>
        +String storageProvider
        +String uri
        +String checksum
    }

    class AuditControl {
        <<Value Object>>
        +String createdBy
        +Date createdAt
        +String modifiedBy
        +Date modifiedAt
    }

    class ArtifactInstance {
        <<Aggregate Root>>
    }
    class EvidenceRecord {
        <<Aggregate Root>>
    }

    ArtifactInstance "1" *-- "1" ContentReference : almacenado como
    ArtifactInstance "1" *-- "1" AuditControl : rastreado por
    EvidenceRecord "1" *-- "1" AuditControl : rastreado por
    EvidenceRecord "1" --> "1" EvidenceChain : participa en
Loading

2.3. Vista 3: Infraestructura Transversal (Shells)

classDiagram
    class CoreIntegrationShell {
        <<Shared Kernel Shell>>
        +getArtifactDefinitions(phase)
        +validateAgainstRuleset()
    }
    class TenantConfigShell {
        <<Shared Kernel Shell>>
        +getMandatoryArtifacts(phase)
    }

    class ArtifactDefinition {
        <<Aggregate Root>>
    }
    class ArtifactInstance {
        <<Aggregate Root>>
    }

    ArtifactDefinition ..> CoreIntegrationShell : sincronizado desde Core
    ArtifactInstance ..> CoreIntegrationShell : validado vía ruleset
    ArtifactInstance ..> TenantConfigShell : verificación de obligatoriedad
Loading

3. Diseño Táctico

3.1. Aggregate Roots (Small Aggregates)

  1. ArtifactDefinition: Espejo de un esquema de artefacto de Core. Sincronizado desde Evolith Core (Conformist); nunca inventado localmente (BR-005). Según la regla de Catálogo R-16, lleva code, value y description.
  2. ArtifactInstance: Un artefacto producido vinculado a un tenant + ejecución. Contiene una ContentReference (el payload vive en object storage, no en la fila).
  3. EvidenceRecord: Prueba inmutable, append-only. Una vez capturada, nunca se muta (soporta la disciplina append-only de tracker_audit y BR-009).

3.2. Value Objects

  • EvidenceChain: Rastro de evidencia ordenado por ejecución; la columna vertebral de la trazabilidad de extremo a extremo.
  • ContentReference: Puntero + checksum al contenido del artefacto almacenado externamente.
  • ValidationResult: Resultado de la verificación de cumplimiento contra un ruleset de Core.

3.3. Integración con Core (Conformist)

  • Las definiciones de artefactos se obtienen en tiempo de ejecución desde Evolith Core (sin segunda fuente de verdad, según TAD §17). Cuando se publiquen las URLs de esquemas de artefactos de Core (actualmente "Under Construction"), este contexto las consume directamente. Hasta entonces, ver UPSTREAM_PROPOSALS.

3.4. Inmutabilidad y Auditoría

  • EvidenceRecord es de escritura única. Con alcance por tenant y RLS aplicado (Security Spec §5, §7 DP-5).

4. Context Mapping (Integración de Fronteras)

  • Conformist hacia Evolith Core: hereda los esquemas de ArtifactDefinition.
  • Customer de las 5 gates (Customer-Supplier): recibe los payloads de ArtifactInstance / EvidenceRecord emitidos a medida que el trabajo de gate se completa.
  • Supplier hacia Governance: PhaseGateState referencia IDs de EvidenceRecord para autorizar las transiciones de gate.
  • Supplier hacia Metrics: las marcas de tiempo de evidencia alimentan los cálculos de lead-time / DORA.

Registro de Artefactos

Los siguientes ArtifactDefinitions se sincronizan desde Evolith Core. Cada entrada representa un esquema de artefacto definido por Core que el Tracker instancia, valida y muestra mediante vistas configurables por inquilino.

Fase 1: Discovery

ID de ArtifactDefinition Nombre Requerido Tiene Plantilla Tiene Schema
prd PRD — Documento de Requisitos de Producto Y Y Y
discovery-canvas Discovery Canvas Y Y Y
business-case-roi Caso de Negocio (ROI) Y Y Y
ballpark-estimation Estimación Ballpark Y Y Y
evolith-user-story Historia de Usuario Evolith Y Y Y
agile-backlog Backlog Ágil Y Y Y
cli-impact-analysis Análisis de Impacto CLI Y Y Y
architectural-directives Directivas Arquitectónicas Y Y —
repository-taxonomy Taxonomía de Repositorio Y Y —
agnostic-baseline Línea Base Agnóstica (Stack Tecnológico) Y Y —
adr-0047-monolith ADR-0047 — Selección de Monolito Modular Y Y —
engineering-manifesto Manifiesto de Ingeniería Y Y —
moscow-prioritization Matriz de Priorización MoSCoW Y — —

Opcionales: | evolutionary-roadmap | Hoja de Ruta Estratégica Evolutiva | — | Y | — | | maturity-assessment | Evaluación de Madurez | — | Y | — | | architecture-communication-strategy | Estrategia de Comunicación Arquitectónica | — | Y | — | | ums-reference-model | Modelo de Referencia UMS | — | Y | — |

Fase 2: Design

ID de ArtifactDefinition Nombre Requerido Tiene Plantilla Tiene Schema
api-contracts Contratos API/Eventos Y — Y
adr ADR (Registro de Decisión) Y Y Y
data-schema Definición de Esquema de Datos Y — —
technical-blueprint Blueprint Técnico Y — —
reference-blueprint Blueprint de Referencia Y Y —
authoritative-tech-stack Stack Tecnológico Autoritativo Y Y —
adr-decision-matrix Matriz de Decisiones ADR Y Y —
adr-0002-hexagonal ADR-0002 — Arquitectura Hexagonal Y Y —
adr-0018-testing-pyramid ADR-0018 — Pirámide de Pruebas Y Y —
adr-0031-schema-context ADR-0031 — Schema por Contexto Y Y —
adr-0032-protocol-matrix ADR-0032 — Matriz de Selección de Protocolo Y Y —
adr-0056-naming-conventions ADR-0056 — Convenciones de Nomenclatura y Diseño Y Y —
functional-story Historia Funcional Y Y Y
functional-story-standard Estándar de Redacción de Historias Funcionales Y Y —
sdlc-doc-best-practices Mejores Prácticas de Documentación SDLC Y Y —
simplicity-checklist-p1 Lista de Verificación de Simplicidad (Fase 1) Y Y —
bounded-context-map Mapa de Contextos Acotados (C4) Y — —

Opcionales: | adr-0010-multitenancy | ADR-0010 — Multi-Tenencia | — | Y | — | | adr-0045-extraction-readiness | ADR-0045 — Criterios de Extracción | — | Y | — | | c4-topology-spec | Especificación de Topología C4 | — | — | — | | cap-strategic-analysis | Análisis Estratégico CAP | — | Y | — | | observability-architecture-flow | Flujo de Arquitectura de Observabilidad | — | Y | — | | canonical-patterns | Patrones Canónicos | — | Y | — |

Fase 3: Construction

ID de ArtifactDefinition Nombre Requerido Tiene Plantilla Tiene Schema
technical-story Historia Técnica Y Y Y
drift-report Informe de Deriva Y — —
code-coverage-report Informe de Cobertura de Código Y — —
peer-review-summary Resumen de Revisión de Pares Y — —
definition-of-done Lista de Verificación de Definición de Hecho Y Y —
documentation-delta Delta de Documentación Y — —
engineering-manifesto Manifiesto de Ingeniería Y Y —
sdlc-framework-construction Framework SDLC (Construcción SS3-4) Y Y —
sdlc-quality-gates Compuertas de Calidad SDLC Y Y —
adr-0005-cicd ADR-0005 — Pipeline CI/CD Y Y —
adr-0018-testing-pyramid ADR-0018 — Pirámide de Pruebas Y Y —
adr-0049-naming-semantics ADR-0049 — Semántica de Nomenclatura y Código Limpio Y Y —
adr-0050-gitflow ADR-0050 — Estrategia de Branching GitFlow Y Y —
sdlc-doc-best-practices Mejores Prácticas de Documentación SDLC Y Y —
canonical-patterns Patrones Canónicos Y Y —
ci-pipeline-evidence Evidencia de Pipeline CI Y — —
coverage-report-external Informe de Cobertura Y — —

Fase 4: QA

ID de ArtifactDefinition Nombre Requerido Tiene Plantilla Tiene Schema
test-summary-report Informe Resumen de Pruebas Y Y Y
sdlc-quality-gates Compuertas de Calidad SDLC Y Y —
adr-0018-testing-pyramid ADR-0018 — Pirámide de Pruebas Y Y —
adr-0052-unit-testing-isolation ADR-0052 — Estrategia de Aislamiento de Pruebas Unitarias Y Y —
adr-0053-integration-e2e-testing ADR-0053 — Estrategia de Pruebas de Integración/E2E Y Y —
acceptance-validation Validación de Aceptación Y — —
security-scan-report Informe de Escaneo de Seguridad Y — —
pyramid-distribution-evidence Evidencia de Distribución de Pirámide Y — —

Opcionales: | contract-testing-guideline | Guía de Pruebas de Contrato | — | Y | — | | adr-0037-performance-chaos | ADR-0037 — Verificación de Rendimiento/Caos | — | Y | — | | vendor-risk-assessment | Evaluación de Riesgo de Proveedor | — | Y | — | | observability-architecture-flow | Flujo de Arquitectura de Observabilidad | — | Y | — |

Fase 5: Release

ID de ArtifactDefinition Nombre Requerido Tiene Plantilla Tiene Schema
release-notes Notas de Release Y Y Y
rollback-procedure Procedimiento de Rollback Y Y —
deployment-evidence Evidencia de Despliegue Y — —
adr-0007-otel-loki ADR-0007 — Observabilidad OTel y Loki Y Y —
adr-0013-cloud-topology-dr ADR-0013 — Topología Cloud y DR Y Y —
adr-0005-cicd ADR-0005 — Pipeline CI/CD Y Y —
operations-hub Hub de Operaciones Y Y —
infrastructure-hub Hub de Infraestructura Y Y —
sdlc-doc-best-practices Mejores Prácticas de Documentación SDLC Y Y —
observability-validation Validación de Observabilidad Y — —

Transversal

ID de ArtifactDefinition Nombre Requerido Tiene Plantilla Tiene Schema
agnostic-baseline Línea Base Agnóstica Y Y —
reference-blueprint Blueprint de Referencia Arquitectónica Y Y —
engineering-manifesto Manifiesto de Ingeniería Y Y —
definition-of-done Definición de Hecho Y Y —
repository-taxonomy Taxonomía de Repositorio Y Y —
gate-evidence Evidencia de Compuerta Y — Y

Nota: Los ArtifactDefinitions marcados con "Tiene Schema" tienen esquemas JSON publicados en el directorio rulesets/schema/ de Evolith Core. Aquellos sin esquema están documentados como plantillas en 04-artifact-templates/. El CoreIntegrationService del Tracker obtiene ambos en tiempo de ejecución — ver US-ART-001.

5. Domain Events

  • ArtifactDefinitionSyncedEvent
  • ArtifactInstanceSubmittedEvent
  • ArtifactValidatedEvent / ArtifactValidationFailedEvent
  • EvidenceCapturedEvent
  • ArtifactSupersededEvent