djangoapp-integrador_ava

Documentação — Integrador AVA

O Integrador AVA é um middleware que conecta Sistemas de Gestão Acadêmica (SGA) ao Moodle. Suporta o SUAP como padrão principal — pronto de fábrica para o IFRN — e o padrão SGA genérico para instituições que usam SIGAA, qAcadêmico ou outro sistema acadêmico.

Como funciona

O Integrador recebe dados de um SGA e os sincroniza com o Moodle. Ele suporta atualmente duas convenções de payload e três estratégias de integração, cada uma viabilizada por um broker próprio.

Padrões de payload

Suap — padrão específico do IFRN, com estrutura de campos bem definida e políticas institucionais pré-configuradas. Funciona “pronto de fábrica” para quem usa o SUAP.

SGA — padrão genérico para qualquer Sistema de Gestão Acadêmica. Mais flexível, porém requer personalização do middleware por parte da instituição.

Brokers (estratégias de integração)

Broker	Payload recebido	Plugin Moodle	Payload retornado	Customização necessária	Status
`suap2local_suap`	Suap	`local_suap`	Suap	Nenhuma	Implementado
`suap2tool_sga`	Suap	`tool_sga`	Suap	Mínima (config.)	Em elaboração
`sga2tool_sga`	SGA (genérico)	`tool_sga`	Suap	Requer personalização	Em elaboração

`suap2local_suap` — Suap → plugin `local_suap`

Recebe payload no padrão Suap, integra com o plugin Moodle local_suap e retorna no padrão Suap. Estratégia mais direta, sem necessidade de customização de payload.

Operação	Método	URL	Descrição
Enviar diário	POST	`/api/enviar_diarios/`	Sincroniza matrículas, papéis e coortes
Baixar notas	GET	`/api/baixar_notas/`	Retorna notas dos alunos do Moodle

Plugin necessário: local_suap
Referência completa: docs/suap2local_suap/

`suap2tool_sga` — Suap → plugin `tool_sga`

Recebe payload no padrão Suap, traduz para o padrão SGA e integra com o plugin Moodle tool_sga. Em elaboração.

Plugin necessário: tool_sga
Referência: docs/suap2tool_sga/

`sga2tool_sga` — SGA → plugin `tool_sga`

Recebe payload no padrão SGA genérico e integra com o plugin Moodle tool_sga. Estratégia mais flexível: qualquer SGA pode ser integrado com a personalização adequada. Em elaboração.

Plugin necessário: tool_sga
Referência: docs/sga2tool_sga/

Configuração completa de uma integração

Passo 1 — Instalar e configurar o plugin no Moodle

Plugin Moodle	Brokers que o usam
`local_suap`	`suap2local_suap`
`tool_sga`	`suap2tool_sga`, `sga2tool_sga`

Após instalar o plugin no Moodle, configure:

Token de autenticação: valor livre, mas deve ser idêntico ao campo token do Ambiente no Integrador (Passo 3).
Demais parâmetros conforme a documentação do respectivo plugin.

Passo 2 — Configurar as variáveis de ambiente do Integrador

Variável	Obrigatória	Descrição	Padrão
`SUAP_INTEGRADOR_KEY`	Sim	Token que o SGA deve enviar no header `Authentication`	`changeme`
`DJANGO_SECRET_KEY`	Sim	Chave secreta Django (use valor aleatório em produção)	`changeme`
`SUAP_BASE_URL`	Não	URL base do SUAP (usada para redirect de logout)	`https://suap.ifrn.edu.br`
`DJANGO_LANGUAGE_CODE`	Não	Código do idioma padrão do sistema	`pt-br`

Atenção: troque changeme por valores secretos reais antes de ir para produção.

Suporte a Internacionalização (i18n)

O Integrador AVA possui suporte nativo a múltiplos idiomas com catálogos gettext completos para:

Português (pt-br) — idioma padrão
Inglês (en)
Espanhol (es)
Francês (fr)
Chinês Simplificado (zh-hans)

A seleção do idioma ocorre automaticamente via cabeçalho HTTP Accept-Language ou sessão/cookie de usuário.

Passo 3 — Cadastrar o Ambiente no admin

Acesse /admin/integrador/ambiente/add/ e cadastre:

Campo	Descrição	Exemplo
`nome`	Nome descritivo	`Moodle Produção ZL`
`url`	URL base do Moodle (sem barra final)	`https://ava.zl.ifrn.edu.br`
`token`	Token configurado no plugin (idêntico ao definido lá)	`token_secreto_do_plugin`
`expressao_seletora`	Expressão `rule_engine` para seleção automática do ambiente	`campus.sigla == "ZL"`
`ordem`	Prioridade (menor = maior prioridade)	`1`
`active`	Se o ambiente está ativo	`true`

A seleção acontece avaliando expressao_seletora de cada ambiente ativo em ordem crescente de ordem. O primeiro que corresponder ao payload é usado.

Guia completo do admin: docs/admin/

Passo 4 — Configurar o cliente REST (SGA)

O SGA deve chamar os endpoints com:

Header: Authentication: Token <SUAP_INTEGRADOR_KEY>
Content-Type (POST): application/json

Exemplo completo para suap2local_suap:

POST https://<integrador>/api/enviar_diarios/
Authentication: Token <SUAP_INTEGRADOR_KEY>
Content-Type: application/json

{
    "campus":     {"id": 1,  "sigla": "ZL",      "descricao": "Campus Zona Leste"},
    "curso":      {"id": 1,  "codigo": "15806",  "nome": "Sistemas Operacionais Abertos"},
    "turma":      {"id": 2,  "codigo": "20261.6.15806.1E"},
    "componente": {"id": 1,  "sigla": "TEC.1023","descricao": "Bancos de Dados"},
    "diario":     {"id": 2,  "sigla": "TEC.1023","situacao": "Aberto"}
}

GET https://<integrador>/api/baixar_notas/?campus_sigla=ZL&diario_id=2
Authentication: Token <SUAP_INTEGRADOR_KEY>

Para exemplos completos de payload, consulte requests.http na raiz do projeto.

Índice da documentação

Seção	Conteúdo
Modelos de dados	`Ambiente`, `Solicitacao` — campos, comportamentos, manager
Guia do administrador	Django admin: Ambientes, Solicitações, Cohorts
Broker suap2local_suap	API completa: endpoints, payload, stack de decorators
Broker suap2tool_sga	Em elaboração
Broker sga2tool_sga	Em elaboração
Guia de testes	TestCases, receitas QA, cobertura, mock HTTP
Mock HTTP de Moodle	`LocalSuapHTTPMock`, `ToolSgaHTTPMock` por broker

Links rápidos

Repositório

This site is open source. Improve this page.