Conectores multi-fontes — contrato v0.1

P2-008 · Gate S3 · Fonte: conectores-multi-fontes.md

APROVADO v0.1 para implementação. Desbloqueia P2-009 (job incremental + log + alerta). Este documento não implementa jobs — define o contrato.

Princípios: uma fonte = um conector; camada canônica; idempotência; dry-run antes do commit; falha visível; segredos mascarados.

1. Fontes oficiais

Código	Domínio	Estado atual
`crm_calendario`	Períodos/marcos	Parcial (REST + CSV)
`lms`	Engajamento AVA	Conector P2-009
`erp_academico`	Notas/presença	Conector P2-009
`erp_financeiro`	Mensalidade	Conector P2-009
`sis_estudantes`	Identidade	Conector P2-009

2. Envelope comum

{
  "versao_payload": "conectores_v0.1",
  "fonte": "lms",
  "gerado_em": "2026-08-05T12:00:00Z",
  "cursor": { "modo": "incremental", "since": "…", "page": 1, "page_size": 500 },
  "itens": [],
  "meta": { "total_declarado": null }
}

Config por fonte em app_config_instituicao (padrão de calendario_crm_api): URL, auth (none|bearer|api_key|basic), mapeamento, schedule, limiares, alerta e-mail.

3. Frequência

Modo	Uso
`full`	Carga inicial / recuperação
`incremental`	Rotina com `since` + lookback
`backfill`	Janela histórica `since`+`until`
`manual`	Botão na UI (já usado no calendário)

Sugestão: LMS 03:00, financeiro 04:00, acadêmico 05:00 (America/Sao_Paulo); calendário semanal + manual.

4. Reconciliação

Upsert por estudante_id (uc:/id:) ou (nivel, codigo) no calendário.
Merge parcial por namespace (ava.*, mensalidade.*…) — não apagar campos de outras fontes.
Soft-delete só em carga full e se opt-in.
Queda de volume ≥ 40% vs mediana das runs OK → bloquear commit (salvo forcar).

5. Alertas de falha

Código	Severidade
`config_invalida`, `http_erro`, `timeout`, `schema_invalido`, `volume_queda`	alta
`volume_zero`, `volume_inconsistente`	média
`partial_ok`	baixa
`sucesso`	info

Canais: log de run (obrigatório) → UI admin → e-mail SMTP. Retenção metadados ≥ 90 dias.

6. Run (contrato)

{
  "run_id": "uuid",
  "fonte": "lms",
  "modo": "incremental",
  "dry_run": false,
  "status": "sucesso|falha|parcial",
  "contagens": { "recebidos": 0, "validos": 0, "upserted": 0, "erros": 0 },
  "alerta_codigos": []
}

API entregue (P2-009): /api/conectores/{fonte}/config|test|sincronizar, /api/conectores/runs, job /api/conectores/jobs/tick. UI: admin-conectores.html. Calendário CRM permanece em /api/calendario-academico/crm-api/*.

7. DoD P2-008 / P2-009

Payload, frequência, reconciliação e alertas documentados.
P2-009: conectores LMS, ERP financeiro, ERP acadêmico e SIS (incremental/full + job + log + alerta) — entregue.

Plano P2 · API · Efetividade causal · Índice