diff --git a/docs/implantacao-lexml.md b/docs/implantacao-lexml.md new file mode 100644 index 000000000..524296520 --- /dev/null +++ b/docs/implantacao-lexml.md @@ -0,0 +1,60 @@ +# Guia de Implantação do provedor LexML no SGVP + +Este guia resume o que é necessário para expor o provedor OAI-PMH do LexML que já vem embutido no SGVP (código em `sapl/lexml`). Ele parte do pressuposto de que você já instalou o SGVP 3.1+ (via `docs/instalacao31.rst`) e vai publicá-lo em produção (veja `docs/deploy.rst` para Nginx+Gunicorn). + +## Pré-requisitos +- Python 3 com as dependências instaladas: `pip install -r requirements/requirements.txt` (usa `pyoai`, `lxml` e demais libs já listadas). +- Banco PostgreSQL com o SGVP configurado e migrado. +- Acesso administrativo ao sistema para cadastrar dados do LexML. +- Identificadores enviados pelo LexML (id do provedor, id do publicador e o XML de configuração validado). + +## 1. Preparar o serviço do SGVP +- Gere o arquivo `.env` e configure `DEBUG=False`, banco, e demais variáveis usadas pelo Django. +- Colete estáticos para uso pelo Nginx: `./manage.py collectstatic --no-input --clear`. +- Suba a aplicação via Gunicorn/Nginx (modelos em `docker/.gunicorn_start.sh` e `docs/deploy.rst`). Certifique-se de que o domínio público configurado no Nginx corresponde ao valor que a Casa Legislativa usará em `endereco_web`; ele é usado para montar os identificadores OAI. + +## 2. Configurações institucionais obrigatórias +O provedor LexML consome dados das seguintes telas: +- **Casa Legislativa** (`Sistema -> Casa Legislativa`): preencher `nome`, `sigla`, `municipio`, `uf`, `endereco_web` e `email`. Essas informações alimentam o `Identify`, a montagem do prefixo OAI e da URN. +- **Parâmetros da Aplicação** (`Sistema -> Parâmetros -> Configurações da Aplicação`): defina `Esfera Federação` (`M` ou `E`). O filtro de normas e a URN dependem disso. +- **Tipos de Norma Jurídica** (`Tabelas Auxiliares -> Norma Jurídica -> Tipo Norma Jurídica`): configure o campo `Equivalente LexML` com um dos valores aceitos (`lei`, `lei.organica`, `resolucao`, `regimento.interno`, etc.). +- **Normas Jurídicas**: cada norma deve ter `esfera_federacao`, `numero`, `ano`, `data`, `tipo` com equivalente LexML e `timestamp` preenchido (o formulário já grava o timestamp; para dados antigos, reabra e salve). Se houver `texto_integral`, ele será publicado como conteúdo; caso contrário, será apontado o link HTML da norma. + +## 3. Cadastrar dados fornecidos pelo LexML +As telas ficam em `Sistema -> LexML`: +- **Provedor** (`/sistema/lexml/provedor/`): cadastre `id_provedor`, `nome`, dados do responsável e **cole o XML** enviado pelo LexML. O formulário valida o XML contra `sapl/templates/lexml/schema.xsd`; qualquer erro de schema ou formatação bloqueia o salvamento. +- **Publicador** (`/sistema/lexml/publicador/`): cadastre `id_publicador`, `nome`, `sigla`, `tipo` e dados do responsável. + +O provedor OAI usa sempre o primeiro registro de cada tabela (`LexmlProvedor` e `LexmlPublicador`), portanto mantenha apenas um registro ativo e atualizado. + +## 4. Endpoint OAI-PMH exposto +- URL: `https:///sistema/lexml/oai` +- `metadataPrefix` suportado: `oai_lexml`. +- Verbos principais: + - `Identify` – retorna os dados da Casa Legislativa e o XML do provedor. + - `ListRecords` – retorna os registros das normas como LexML, respeitando `from`, `until` (datas ISO 8601) e `batch_size` (padrão 10) para paginação. +- A URN e o identificador OAI são gerados a partir de `casa.sigla`, domínio de `casa.endereco_web`, tipo equivalente LexML, ano/número da norma e datas de publicação/vigência quando informadas. + +## 5. Testes rápidos +Com o servidor rodando: +```bash +curl "http://localhost:8000/sistema/lexml/oai?verb=Identify" +curl "http://localhost:8000/sistema/lexml/oai?verb=ListRecords&metadataPrefix=oai_lexml&batch_size=50" +``` + +Para inspecionar pelo shell (usa o mesmo servidor interno em `sapl/lexml/OAIServer.py`): +```bash +./manage.py shell_plus <<'PY' +from sapl.lexml.OAIServer import OAIServerFactory, get_config +server = OAIServerFactory(get_config('http://127.0.0.1:8000/', 10)) +print(server.handleRequest({'verb': 'ListRecords', 'metadataPrefix': 'oai_lexml'}).decode('utf-8')) +PY +``` + +## 6. Checklist de prontidão +- [ ] Casa Legislativa completa com `endereco_web` e `email`. +- [ ] `Esfera Federação` definida em Parâmetros da Aplicação. +- [ ] Tipos de Norma com `Equivalente LexML` configurado. +- [ ] Normas com `timestamp`, `esfera_federacao`, `data`, `numero` e `ano` corretos. +- [ ] Provedor e Publicador cadastrados; XML validado. +- [ ] `Identify` e `ListRecords` respondendo 200 e entregando XML válido. diff --git a/docs/poc-lexml.md b/docs/poc-lexml.md new file mode 100644 index 000000000..42115ba12 --- /dev/null +++ b/docs/poc-lexml.md @@ -0,0 +1,87 @@ +# POC do provedor LexML no SGVP (explicado de forma simples) + +Pense no LexML como uma grande biblioteca que quer receber copias digitais das leis que voce publica no SGVP. O SGVP ja fala esse idioma (OAI-PMH); basta preencher alguns formularios e mostrar o endereco certo para o coletor do LexML. + +## Escopo rapido da POC +- SGVP entrega dados em formato LexML sem programacao extra. +- Basta preencher dados da Casa, cadastrar provedor/publicador e ter ao menos uma norma. +- Endpoint `.../sistema/lexml/oai` responde aos verbos `Identify` e `ListRecords`. + +## Quem e quem (em termos bem simples) +- **SGVP**: o site da Casa que guarda as normas. +- **LexML**: a biblioteca nacional que vai buscar os dados. +- **Casa Legislativa**: dados institucionais (nome, cidade, UF, site, email). +- **Tipo de Norma**: o "tipo de livro" (lei, resolucao, regimento etc.). +- **Norma Juridica**: o "livro" com numero, ano, data, texto e resumo. +- **Provedor / Publicador**: cartoes de visita fornecidos pelo time do LexML (ids e XML). + +## Preparacao do ambiente +- SGVP 3.1+ rodando (dev ou staging). Exemplos: `./manage.py runserver 0.0.0.0:8000` ou `docker-compose -f dist/docker-compose.yml up -d`. +- Dependencias instaladas: `pip install -r requirements/requirements.txt`. +- Banco migrado e usuario administrador ativo. +- `Casa Legislativa.endereco_web` e o host usado nos identificadores; configure o mesmo host em `ALLOWED_HOSTS` e nos testes do navegador. + +## Implantacao passo a passo (modo receita) +1) **Suba o SGVP**: escolha execucao local ou container e confirme acesso ao admin. +2) **Casa Legislativa**: em `Sistema -> Casa Legislativa`, preencha nome, sigla, municipio, UF, endereco_web e email. +3) **Esfera Federacao**: em `Sistema -> Parametros -> Configuracoes da Aplicacao`, escolha `M` (Municipal) ou `E` (Estadual). +4) **Tipos de Norma Juridica**: em `Tabelas Auxiliares -> Norma Juridica -> Tipo de Norma Juridica`, ajuste o campo `Equivalente LexML` (ex.: `lei`, `lei.organica`, `resolucao`, `regimento.interno`). +5) **Norma Juridica de exemplo**: cadastre ao menos uma norma com `numero`, `ano`, `data`, `esfera_federacao`, tipo com equivalente LexML, `ementa` e, se possivel, `texto_integral` (PDF ou DOC). O formulario grava `timestamp` automaticamente; para dados antigos, abra e salve de novo. +6) **Provedor**: em `Sistema -> LexML -> Provedor`, preencha `id_provedor`, `nome`, responsavel, email e cole o XML que o LexML enviou. O SGVP valida contra `sapl/templates/lexml/schema.xsd` e aponta erros de schema. +7) **Publicador**: em `Sistema -> LexML -> Publicador`, preencha `id_publicador`, `nome`, `sigla`, `tipo` e responsavel. +8) **Teste interno**: acesse `http://localhost:8000/sistema/lexml/oai?verb=Identify` e `ListRecords` (com `metadataPrefix=oai_lexml`) para ver se a resposta chega em XML. +9) **Compartilhe a baseURL**: envie ao time LexML o `baseURL` gerado (o mesmo usado no XML de provedor) para que eles habilitem o coletor externo. + +## XML de exemplo (ajuste IDs e dominio) +```xml + + + + + + + + + + + + + + +``` + +## Comandos para testar e demonstrar +- Identify: `curl "http://localhost:8000/sistema/lexml/oai?verb=Identify"` +- ListRecords (padrao): `curl "http://localhost:8000/sistema/lexml/oai?verb=ListRecords&metadataPrefix=oai_lexml&batch_size=10"` +- ListRecords filtrando por data: `curl "http://localhost:8000/sistema/lexml/oai?verb=ListRecords&metadataPrefix=oai_lexml&from=2023-01-01T00:00:00Z&batch_size=50"` + +O que aparece no `ListRecords`: +- `Item` com link do conteudo (PDF/HTML) e outro `Item` para o metadado. +- `DocumentoIndividual` com URN montada a partir da Casa, tipo, data e numero/ano. +- `Epigrafe`, `Ementa` e opcionalmente `Indexacao`. + +## Uso diario na rotina LexML +- Cadastre novas normas sempre com `numero`, `ano`, `data`, esfera e tipo com `Equivalente LexML`; anexe o `texto_integral` quando existir. +- Se atualizar metadados de normas antigas, salve novamente para atualizar o `timestamp` que o coletor usa no filtro por data. +- Mantenha apenas um provedor e um publicador ativos e corretos; revise o XML sempre que o LexML mandar atualizacao. +- Valide periodicamente chamando `Identify` e `ListRecords` para checar disponibilidade externa (use o host oficial, nao apenas localhost). +- Se o coletor do LexML reportar falhas, verifique `sapl.log` e se o `endereco_web` esta batendo com o dominio publicado. +- Quando trocar certificados/HTTPS, confira se a `baseURL` no XML do provedor esta coerente e acessivel. + +## Roteiro de falas simples (colinha) +1) "O SGVP e nosso site. O LexML e a biblioteca. Vamos fazer eles conversarem." +2) "Preenchi os dados da Casa e disse se ela e Municipal ou Estadual." +3) "Escolhi o tipo de lei e marquei o equivalente LexML, que define como a URN e montada." +4) "Cadastrei o Provedor e o Publicador com o XML que o time do LexML enviou; o sistema checa se esta correto." +5) "Aqui esta uma norma de exemplo com PDF e resumo." +6) "Chamando Identify, o SGVP mostra quem ele e e qual e a baseURL." +7) "Chamando ListRecords, vemos o XML LexML com a URN e os links para o conteudo." +8) "Esse mesmo endereco pode ser usado pelo coletor do LexML para sincronizar as normas." + +## Checklist final (confira antes da demo ou producao) +- [ ] Casa Legislativa preenchida (nome, sigla, municipio, UF, endereco_web, email). +- [ ] Esfera Federacao escolhida em Parametros. +- [ ] Tipos de Norma com `Equivalente LexML` definido. +- [ ] Pelo menos 1 Norma com data, numero, ano, esfera e `timestamp` salvo. +- [ ] Provedor e Publicador cadastrados com XML validado. +- [ ] `Identify` e `ListRecords` retornando 200 e XML legivel (usando host publico). diff --git a/test_sessoes.py b/test_sessoes.py new file mode 100644 index 000000000..e69de29bb