Skip to content

ddd-model.es.md

Latest commit

 

History

History
175 lines (147 loc) · 7.25 KB

ddd-model.es.md

File metadata and controls

175 lines (147 loc) · 7.25 KB

Evolith Tracker: Modelo DDD - Módulo Integration

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

Este documento define el diseño táctico y estratégico del Bounded Context de Integration. Es un subdominio de soporte que actúa como la Anti-Corruption Layer (ACL) de todo el sistema: ingiere datos de sistemas externos (GitHub, GitLab, Jira, Trello, .harness) y exporta artefactos del Tracker hacia afuera, traduciendo cada forma externa a domain events canónicos — de modo que ningún tipo externo penetre un contexto core. Fuente de los agregados: TAD §3. Relaciones estratégicas: Bounded Context Map.

1. Lenguaje Ubicuo (Ubiquitous Language)

  • Integration Endpoint: Una conexión configurada a un sistema externo para un tenant (proveedor, referencia de credenciales, dirección, alcance).
  • ACL Adapter: El traductor que mapea un payload externo a un domain event canónico del Tracker (y viceversa para la exportación).
  • Sync Record: Un rastro inmutable de una sincronización individual entrante/saliente, incluyendo el resultado canónico y la clave de idempotencia.
  • Canonical Event: El domain event interno del Tracker producido a partir de un payload externo (ej. CodeCommittedEvent desde un webhook de GitHub).
  • Egress / Ingress: La dirección del flujo de datos relativa al Tracker.

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 Integration (Agregados y Entidades)

classDiagram
    class IntegrationEndpoint {
        <<Aggregate Root>>
        +UUID id
        +String tenantId
        +ExternalProvider provider
        +SyncDirection direction
        +String credentialsRef
        +EndpointStatus status
        +configure(UUID umsUserId)
        +enable()
        +disable()
        +rotateCredentials(String newRef)
    }

    class SyncRecord {
        <<Aggregate Root>>
        +UUID id
        +String tenantId
        +UUID integrationEndpointId
        +SyncDirection direction
        +String idempotencyKey
        +SyncStatus status
        +String canonicalEventType
        +Date syncedAt
        +record(UUID umsUserId)
        +markFailed(String reason)
    }

    class ACLAdapter {
        <<Entity>>
        +ExternalProvider provider
        +String adapterVersion
        +ingest(ExternalPayload) CanonicalEvent
        +export(CanonicalArtifact) ExternalPayload
    }

    IntegrationEndpoint "1" *-- "1" ACLAdapter : usa
    IntegrationEndpoint "1" --> "0..*" SyncRecord : produce
Loading

2.2. Vista 2: Traducción y Auditoría (Value Objects)

classDiagram
    class ExternalReference {
        <<Value Object>>
        +ExternalSystem system
        +String externalId
        +String url
        +ReferenceType type
        +String label
        +Date linkedAt
        +Map metadata
    }

    class WebhookSignature {
        <<Value Object>>
        +String algorithm
        +String signature
        +Boolean verified
    }

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

    class IntegrationEndpoint {
        <<Aggregate Root>>
    }
    class SyncRecord {
        <<Aggregate Root>>
    }

    SyncRecord "1" *-- "0..1" WebhookSignature : verificado por
    SyncRecord "1" *-- "1" ExternalReference : enlaza a
    SyncRecord "1" *-- "1" AuditControl : rastreado por
    IntegrationEndpoint "1" *-- "1" AuditControl : rastreado por
Loading

2.3. Vista 3: Infraestructura Transversal (Shells)

classDiagram
    class IntegrationFabric {
        <<Shared Kernel Shell>>
        +ingestFromWebhook()
        +exportToExternalSystem()
    }
    class EventBusShell {
        <<Shared Kernel Shell>>
        +publish(CanonicalEvent)
    }
    class UMS_SDK {
        <<Cross-Cutting>>
        +RequiresDomainAccess()
    }

    class IntegrationEndpoint {
        <<Aggregate Root>>
    }
    class ACLAdapter {
        <<Entity>>
    }

    ACLAdapter ..> IntegrationFabric : delega transporte
    ACLAdapter ..> EventBusShell : publica eventos canónicos
    IntegrationEndpoint ..> UMS_SDK : asegurado vía
Loading

3. Diseño Táctico

3.1. Aggregate Roots (Small Aggregates)

  1. IntegrationEndpoint: Config de conexión externa por tenant. Las credenciales se mantienen solo por referencia (el secreto vive en el secret manager — Security Spec §8), nunca en línea.
  2. SyncRecord: Rastro inmutable e idempotente de una sincronización. La idempotencyKey garantiza que la entrega entrante at-least-once no se aplique dos veces (alineado con la regla de idempotencia de consumidor de TAD §13.1).

3.2. Entidades y Value Objects

  • ACLAdapter (Entity): El traductor específico del proveedor; versionado para que un cambio de formato del proveedor sea un bump de versión del adapter, no un cambio de dominio.
  • ExternalReference (VO): Compartido con Discovery, Construction, QA (Shared Kernel) — el enlace canónico a un objeto externo.
  • WebhookSignature (VO): Verificación HMAC de webhooks entrantes (Security Spec SEC-D4 ⊕ propuesta) — protege contra la falsificación de payloads (STRIDE Tampering).

3.3. Disciplina de Anti-Corruption Layer

  • Ningún tipo externo cruza la frontera. Cada payload entrante se convierte en un DomainEvent canónico; cada exportación parte de un artefacto canónico. Los contextos core nunca importan tipos de GitHub/Jira. Esta es la ACL primaria del sistema, complementando la ACL UmsSecurityAdapter para auth.

3.4. Dirección e Idempotencia

  • Ingreso: webhook/CSV → verificado → normalizado → evento canónico publicado en el bus.
  • Egreso: artefacto canónico → adapter → API externa (exportación en Modo Standalone).
  • Ambas direcciones persisten un SyncRecord con clave de idempotencia.

4. Context Mapping (Integración de Fronteras)

  • Anti-Corruption Layer (upstream de Discovery): ingiere iniciativas externas → InitiativeImport.
  • Anti-Corruption Layer (par de Construction): webhooks de PR y commit de GitHub/GitLab → CodeCommittedEvent, PeerReviewUpdatedEvent.
  • Puente .harness ↔ QA: retransmite payloads de CI/test (el contexto QA posee el contrato de resultados de .harness; Integration maneja el transporte).
  • Conformist hacia proveedores externos: se adapta a sus formatos; nunca les pide cambiar.

5. Domain Events

  • IntegrationEndpointConfiguredEvent
  • InboundSyncReceivedEvent
  • OutboundSyncCompletedEvent
  • SyncFailedEvent
  • WebhookRejectedEvent (fallo de verificación de firma)
  • ExternalCheckpointRegisteredEvent (avance por checkpoint externo en modo initiative-only)