ADR-50: Domínio Product — Arquitetura e Aggregate Roots
Status: Aceito Data: 2026-04-23 Autor: Michael Meneses (Arquiteto)
Contexto
O domínio product é o segundo a receber especificação formal. Ele materializa a camada de configuração pedagógica e comercial da plataforma: o Produto Comercial (Curso-Produto no Moodle), a Trilha Pedagógica que define o percurso de estudo e o Plano de Estudo que resulta da compilação da Trilha.
O ADR-02 já define o ciclo de vida em 4 fases (Configuração → Publicação → Instanciação → Execução). O ADR-40 define presets e regras condicionais. Este ADR consolida a arquitetura do domínio — aggregate roots, boundaries, item types, events e interfaces cross-domain.
As decisões aqui formalizadas absorvem D-28 a D-34 do BL-009 (Product Discovery Review, 2026-03-31).
Subdomínios
O domínio product concentra três subdomínios:
| Subdomínio | Slug | Escopo funcional |
|---|---|---|
| Produto (raiz) | product |
Produto Comercial (Curso-Produto), Tutoria, Estrutura do Produto |
| Trilha Pedagógica | product.learning_path |
Trilha, 9 etapas de configuração, Parâmetros, Presets, Validação |
| Comercialização | product.commercial |
SKU, Cronograma, Modalidades, Ofertas, Campanhas, Pós-venda |
Nota: O subdomínio product.enrolment definido no ddd-config.yaml será migrado para engine.access em sessão futura. A Matrícula pertence ao domínio engine por decisão da sessão 14 — é o vínculo operacional que habilita o Motor a criar o Plano do Aluno.
Aggregate Roots
Item types
| item_type | Conceito | Natureza | Storage |
|---|---|---|---|
product |
Produto Comercial (Curso-Produto) | AR independente | EAV (helico_items) |
trail |
Trilha Pedagógica | AR com parent=product | EAV (helico_items) |
plan |
Plano de Estudo | AR derivado | EAV (helico_items) |
Relação entre aggregate roots
product (Curso-Produto Moodle)
└── trail (Trilha Pedagógica — parent=product, relação 1:1)
└── plan (Plano de Estudo — gerado pela publicação da trail)producté o registro independente equivalente ao Curso-Produto (course) no Moodle. Agrupa Parâmetros Comerciais, SKU e Cronograma.trailtem identidade própria e lifecycle independente (Rascunho → Publicada → Travada → Descontinuada), mas sempre pertence a umproductviaparent. Relação 1:1: um Produto, uma Trilha. Padrão idêntico aunitque é AR comparent = discipline.plané gerado pelo Motor de Compilação Pedagógica quando a Trilha é publicada. Cada publicação gera nova versão. Imutável após geração.
Entidades que NÃO são aggregate roots no product
| Entidade | Decisão | Motivo |
|---|---|---|
| Matrícula | Migrada para engine.access |
É vínculo operacional do Motor, não do Produto |
| Pedido | Herdado de local_middag |
Entidade transversal do framework |
| Campanhas | Seção do ADR, sem AR próprio | Funcionalidade secundária, registrada em termos |
Invariantes dos Aggregate Roots (absorve D-28)
product
- Produto deve ter SKU único no catálogo
- Produto deve ter Trilha Publicada antes de publicação comercial
- Cronograma Comercial deve ser temporalmente consistente (início < término)
- Relação 1:1:1: um Produto Comercial, um Curso-Produto (Moodle), uma Trilha Pedagógica
trail
- Status controla permissões de edição (ver Travamento Estrutural, ADR-40)
- Validação obrigatória antes de publicação
- Travamento Estrutural após 1ª Matrícula: Montagem dos Fluxos e Configuração das Disciplinas bloqueadas
- Consistência entre Disciplinas, Unidades, Fluxos e Atividades obrigatória em toda publicação
- Campos
config_jsondeterminam comportamento — Modalidade é rótulo (ADR-40)
plan
- Imutável após geração
- Cada publicação da Trilha gera nova versão
- Sequência do Plano deve ser consistente com a Trilha de origem
- Antes da 1ª Matrícula: publicações substituem livremente
- Após 1ª Matrícula: nova versão vale para novas Matrículas e Matrículas sem Primeiro Acesso
Domain Events (absorve D-29)
Events emitidos pelo product
| Evento | Trigger | Consumidores |
|---|---|---|
trail_published |
Publicação concluída | Motor (compilar Plano de Estudo) |
trail_republished |
Nova publicação em Trilha já publicada | Motor (Migração de Plano), Notificações |
trail_locked |
1ª Matrícula vinculada | Interface (bloquear campos estruturais) |
trail_discontinued |
Gestor descontinua Trilha | Produto Comercial (bloquear vendas), Motor (manter planos existentes) |
commercial_product_published |
Publicação Comercial concluída | Frontend (Vitrine) |
Events consumidos pelo product
| Evento | Produtor | Efeito |
|---|---|---|
plan_study_generated |
Motor (Compilação) | Vincular ao Produto |
order_received |
Webhook externo | Disparar Concessão de Acesso |
commercial_sync_event |
Webhook externo | Renovação, Revogação, Cancelamento |
Regras de Negócio (absorve D-30)
| # | Regra | Tipo | Escopo |
|---|---|---|---|
| 1 | Trilha deve estar validada antes de publicar | consistência | trail |
| 2 | Trilha Travada não permite edição estrutural | consistência | trail |
| 3 | Cada Publicação gera nova Versão do Plano de Estudo | funcional | trail→plan |
| 4 | Produto Comercial deve ter SKU único | consistência | product |
| 5 | Produto Comercial deve estar associado a Trilha Publicada | funcional | product |
| 6 | Modo de Acesso Comercial define elegibilidade de concessão | funcional | product |
| 7 | Critério de Conclusão Pedagógica define quando Plano é concluído | pedagógica | trail |
| 8 | Pré-requisito de Unidade condiciona sequência de estudo | pedagógica | trail |
Services (absorve D-32)
| Service | Responsabilidade |
|---|---|
| TrailConfigurationService | Orquestra 9 etapas de configuração |
| TrailValidationService | Validação completa: disciplinas, unidades, fluxos, atividades, pré-requisitos |
| TrailPreviewService | Gera pré-visualização da Trilha montada |
| TrailPublicationService | Valida → compila → gera Plano → transita status → emite trail_published |
| StudyPlanMigrationService | Identifica Matrículas afetadas por republicação, coordena migração |
| CommercialProductService | Ciclo de vida do Produto Comercial: SKU, cronograma, publicação |
| TutorManagementService | Designação de Tutores a Trilhas, avaliações e relatórios |
Nota: Services de Acesso (OrderProcessingService, AccessGrantService, EnrolmentProvisioningService, EnrolmentLifecycleService, AccessRenewalService) migram para engine.access.
Interfaces Cross-Domain (absorve D-33)
| Domínio externo | Direção | Contrato | Dados trocados |
|---|---|---|---|
| Content | consome | ContentCatalogContract | Disciplinas e Unidades para configuração da Trilha |
| Engine | publica | StudyPlanPublishedContract | Plano de Estudo para gerar Plano do Aluno |
| Activity | consome | ActivityCatalogContract | Tipos de atividades para Configuração das Atividades |
| Moodle core | consome/publica | MoodleEnrolmentAPI | Inscrição via Enrolment API nativa |
Decisões abertas registradas (absorve D-34)
| # | Item | Tipo | Status |
|---|---|---|---|
| 1 | Migração trilha.php de content/ para product/ |
decisão técnica | Adiada — migrar quando iniciar implementação |
| 2 | EAV vs tabela própria para Matrícula | decisão de storage | Provisoriamente EAV; decisão final no ADR de engine.access |
| 3 | Pedido como entidade local | decisão validada | Herdado de middag (confirmado sessão 14) |
| 4 | Fronteira Produto vs Motor (Compilação) | decisão validada | Produto gera Plano de Estudo; Motor gera Plano do Aluno (confirmado sessão 14) |
| 5 | Tutoria provisoriamente no Produto | hipótese | Mantida — se acompanhamento crescer, migrar para domínio próprio |
| 6 | Política de Entrada Tardia | decisão validada | Configurada no Produto, aplicada pelo Motor |
| 7 | Schema do webhook de Pedido | decisão futura | Formato do contrato com sistema de pagamento externo |
Campanhas (absorve D-11)
Campanhas de Comunicação estão definidas no escopo do domínio product e nos termos (terms-product-commercial.yaml), mas a implementação é por priorização. Não recebem ADR separado nem JSON contracts nesta fase.
Termos existentes: Campanha de Comunicação, Evento de Comunicação, Segmentação de Campanha, Calendário Comercial.
TRIAL / Degustação (absorve D-51 §9.8)
Não há distinção entre Degustação e TRIAL — são a mesma coisa operacionalmente. Ambos são tratados como variação comercial do Produto, controlada pelo campo trial_mode no config_json da Trilha (ver ADR-40). Não há escopo pedagógico diferenciado: a restrição de conteúdo, se existir, é configurada via os parâmetros normais da Trilha. Não criar terms separados para Degustação vs TRIAL.
Consequências
- Três aggregate roots com item types limpos (
product,trail,plan) — sem underscore, autoexplicativos - Matrícula fora do product (em engine.access) — separação clara entre configuração e execução
- Pedido herdado de middag — sem duplicação de entidade
- Campanhas registradas mas não bloqueiam implementação
- Events e interfaces cross-domain formalizados — base para contratos JSON
- Migração de
trilha.phppendente (content → product) quando implementação iniciar product.enrolmentno ddd-config.yaml precisa migrar para engine em sessão futura- Campanhas sem especificação detalhada — podem gerar retrabalho quando priorizadas
ADRs relacionados
- ADR-02 — Ciclo de vida pedagógico em 4 fases (fundação)
- ADR-04 — Eventos para desacoplamento (events deste ADR seguem o padrão)
- ADR-10 — Persistência EAV (storage dos 3 ARs)
- ADR-11 — Versionamento por snapshot (plan é imutável)
- ADR-21 — Contratos JSON para entities (contracts de product, trail, plan)
- ADR-22 — Convenções de domínio (subdomains product.*)
- ADR-40 — Configuração por preset e invariantes (complementa trail)
- REF-40-A — Regras condicionais do config_json
- REF-40-B — Invariantes operacionais do CRE
Histórico
| Data | Evento |
|---|---|
| 2026-04-23 | Criado — consolida decisões da sessão 14 + absorve BL-009 D-28..D-34 |
| 2026-04-24 | Adicionado § TRIAL / Degustação — absorve D-51 §9.8 (decisão C: sem distinção, trial_mode no config_json) |