Lexml: instruções de implantação

8 months ago · 52d78dfd09
3 changed files with 147 additions and 0 deletions
--- a/docs/implantacao-lexml.md
+++ 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://<seu-dominio>/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.
--- a/docs/poc-lexml.md
+++ 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
 <ConfiguracaoProvedor dataGeracao="2024-01-01T00:00:00">
  <Provedor idProvedor="123" nome="Camara Exemplo" tipo="Provedor" baseURL="https://seu.dominio/sistema/lexml/oai">
    <Administrador idResponsavel="1" email="contato@dominio.gov.br"/>
    <Publicador idPublicador="456" nome="Camara Exemplo" sigla="CE">
      <Responsavel idResponsavel="1" email="contato@dominio.gov.br"/>
      <Perfil localidade="BR;DF;Brasilia"/>
    </Publicador>
  </Provedor>
  <RepositorioOAILexML baseURL="https://www.lexml.gov.br/oai"/>
  <RepositorioOAILexML baseURL="https://seu.dominio/sistema/lexml/oai"/>
  <RepositorioOAILexML baseURL="https://seu.dominio/sistema/oai"/>
  <RepositorioOAILexML baseURL="https://seu.dominio/oai"/>
  <RepositorioOAILexML baseURL="http://seu.dominio/sistema/lexml/oai"/>
 </ConfiguracaoProvedor>
 ```
 ## 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).  
--- a/test_sessoes.py
+++ b/test_sessoes.py