ADR-40: Configuração por Preset e invariantes do Produto
Status: Aceito Data: 2026-04-23
Contexto
A HÉLICO oferece 13 modalidades de Produto com comportamentos pedagógicos distintos (CRE, Reta Final, Simulados Avulsos). A primeira abordagem considerada foi uma coluna modalidade no banco que determinasse o comportamento diretamente. Isso criaria rigidez: cada nova combinação pedagógica exigiria migração de dados e código condicional por modalidade.
O Gestor Pedagógico precisa configurar Trilhas Pedagógicas com liberdade (modo Personalizado) mas com garantia de coerência metodológica quando usar modalidades conhecidas.
Decisão
1. Preset como atalho de configuração, não como determinante de comportamento
O comportamento do Produto é definido exclusivamente pelos valores do config_json (Parâmetros da Trilha). A Modalidade Comercial é um rótulo de catálogo — ela organiza a comunicação, mas não determina o comportamento pedagógico.
Cada Modalidade possui um Template de Configuração que opera em dois modos:
- Preset — campos preenchidos automaticamente e bloqueados (
locked_fields), garantindo coerência metodológica. O Gestor não pode alterar campos críticos. - Personalizado — campos editáveis, validados por regras condicionais de dependência entre parâmetros.
2. Regras condicionais como contrato de consistência
As dependências entre parâmetros são formalizadas como regras condicionais (REF-40-A). Essas regras são aplicadas tanto no modo Preset (validação build-time via schema) quanto no modo Personalizado (validação runtime via validation_rules.json).
3. Invariantes operacionais por modalidade
Cada modalidade-padrão possui invariantes que não são apenas “defaults” — são contratos testáveis de comportamento (REF-40-B). Exemplo: no CRE, a Revisão Geral é obrigatória e o fluxo CDA → RG → SO é fixo.
4. Seções editáveis em todos os presets
Mesmo em modo Preset, as seções parametros_comerciais, disciplinas_unidades, montagem_fluxo, configuracao_unidades e validacao permanecem editáveis — elas são específicas do Produto, não da Modalidade.
Consequências
- Liberdade total para Personalizado sem campo
modalidaderígido - Consistência garantida nos presets via
locked_fields - Novas modalidades criadas por combinação de parâmetros, sem migração de dados
- Regras condicionais testáveis e auditáveis (REF-40-A)
- Invariantes do CRE documentados formalmente (REF-40-B)
- Complexidade das regras condicionais exige engine de validação robusta
locked_fieldsprecisa ser mantido em sincronia com os presets
ADRs relacionados
- ADR-02 — Ciclo de vida pedagógico em 4 fases (configuração → compilação → instanciação → execução)
- ADR-21 — Contratos JSON para validação de entities (convenções de schema)
REFs
- REF-40-A — Regras condicionais do config_json
- REF-40-B — Invariantes operacionais do CRE
Histórico
| Data | Evento |
|---|---|
| 2026-02-28 | Spec modalidades-como-presets.md — proposta original do padrão |
| 2026-02-28 | Spec config-json-trilha-v1.md — primeira versão dos parâmetros |
| 2026-02-28 | Spec config-json-trilha-v2.md — versão canônica com 8 regras condicionais |
| 2026-03-05 | Spec decisoes-confirmadas-cre.md — 20 invariantes do CRE confirmados pelo Gestor |
| 2026-04-23 | Absorção dos specs em 03-product.md + 06-engine-execucao.md (BL-007 Fases 2-5) |
| 2026-04-23 | ADR-40 criado, consolidando decisões dispersas em 6 specs (BL-007 sessão 12) |