Cuidando do Meu Bairro ====================== Versão |version| - dezembro de 2015. Projeto *Cuidando do Meu Bairro*: abertura e geolocalização do orçamento municipal. **Acesso**: - Portal e implantação para o município de São Paulo em `Cuidando.vc `__. - Fontes de dados orçamentários nos `webservices do projeto GastosAbertos.org `__. **Códigos-fonte** (repositórios `git `__): - Site: `okfn-brasil/cuidando2 `__ - Módulos de dados orçamentários: - Fontes dos engines e extratores: `okfn-brasil/gastos\_abertos `__, `teaser.gastosabertos.org `__. - Dados e documentação: `okfn-brasil/gastos\_abertos\_dados `__, `okfn-brasil/documents/gastos\_abertos `__. - Autenticação de usuários: `okfn-brasil/viralata `__ - Comunicação dos usuários: `okfn-brasil/tagarela `__ - Intermediação do eSIC: `okfn-brasil/esiclivre `__ **Documentação**: - Tutoriais na `Wikiversity-Português, Projeto Cuidando do Meu Bairro `__. - Instruções para o desenvolvedor: `okfn-brasil/cuidando2-doc `__. - Administração do projeto: `wiki.okfn.org `__. Histórico e versões ------------------- Este projeto teve origem no `Cuidando do Meu Bairro de 2013 `__, que buscava mapear a execução do orçamento municipal de São Paulo, não só em regiões, mas também colocando um ponto no mapa para cada despesa. Por isso o presente projeto foi apelidado de **Cuidando2**: uma nova interface, novos recursos e melhoras nos dados gerados pelo software. Como os `dados obtidos da prefeitura `__ não têm as coordenadas geográficas de cada despesa (no máximo algumas tem a região a que se destinam), o ponto de partida são os endereços nos textos das descrições das despesas, que por sua vez podem ser submetidos à `geocodificação `__ em ferramentas adequadas. A extração dos endereços a partir do texto é obtida através de `expressões regulares `__. A geocodificação desses endereços é realizada pelas `API `__\ s `OpenStreetMap-Nomination `__ e `Google-geocoding `__. Esse processo não é perfeito, acumula erros tanto da fase de extração como da fase de geocodificação, de modo que muitas despesas não são mapeadas, ou acabam exibidas no local errado. No Cuidando2 o processo foi aperfeiçoado para reduzir a taxa de erros. Arquitetura ----------- Buscando ampliar a chance de reuso do código desenvolvido e permitir um nível maior de interação com outros aplicativos, o projeto seguiu uma arquitetura de micro serviços. Ou seja, ao invés de ter um único código monolítico que implementasse todas as funcionalidades desejadas, elas foram distribuídas em pequenos módulos, cada um com uma funcionalidade específica: |Alt text| As setas avermelhadas indicam conexões em que as escritas provavelmente necessitarão de um `token `__. A navegação HTML é de responsabilidade do `Cuidando2 `__, implementado atualmente em `cuidando.vc `__, que através de `Ajax `__ faz a comunicação com cada módulo, nos respectivos `endpoints `__: +----------------------------------+--------------------------------------------------------------+-----------------------------------------------------------------------------------------------+--------------------------------------------------------+ | Função | Responsabilidade | **Endpoint** em uso | Notas | +==================================+==============================================================+===============================================================================================+========================================================+ | Geolocalização | *Gastos Abertos* | `site-cuidando.rhcloud.com/dados/api/v1 `__ | leitura das coordenadas | +----------------------------------+--------------------------------------------------------------+-----------------------------------------------------------------------------------------------+--------------------------------------------------------+ | Dados de execução orçamentária | *Gastos Abertos* | `demo.gastosabertos.org `__ | consulta à base de dados | +----------------------------------+--------------------------------------------------------------+-----------------------------------------------------------------------------------------------+--------------------------------------------------------+ | Autenticação dos usuários | `Vira-Lata `__ | `viralata-cuidando.rhcloud.com `__ | token de acesso, leitura/escrita | +----------------------------------+--------------------------------------------------------------+-----------------------------------------------------------------------------------------------+--------------------------------------------------------+ | Comentários dos usuários | `Tagarela `__ | `tagarela-cuidando.rhcloud.com `__ | leitura/escrita dos textos | +----------------------------------+--------------------------------------------------------------+-----------------------------------------------------------------------------------------------+--------------------------------------------------------+ | Interface com eSIC | `EsicLivre `__ | `cuidando.vc/esiclivre `__ | realização de pedidos de informação, leitura/escrita | +----------------------------------+--------------------------------------------------------------+-----------------------------------------------------------------------------------------------+--------------------------------------------------------+ Cada um desses *endpoints* apresenta também uma documentação mais detalhada da API quando acessado diretamente do navegador, exemplificando o uso de cada uma das operações `REST `__ disponíveis no microserviço. Modos de operação e replicação ------------------------------ Conforme a finalidade, o projeto pode ser copiado e adaptado, parcial ou integralmente. O caso típico é a replicação para atuar com outros municípios, mudando apenas o escopo de dados no Gastos Abertos e adaptando-se o *EsicLivre* para as peculiaridades do eSIC do município. Uma outra forma comum de replicação é a integral, quando se deseja instalar e testar localmente (o programador no seu computador) para entender melhor o funcionamento do software como um todo, ou para realizar (através de *fork*) adaptações maiores. Replicando apenas o site ~~~~~~~~~~~~~~~~~~~~~~~~ Na ausência de dados da cidade, operaria em modo "somente leitura". Util para designers e trabalhos restritos ao site. .. toctree:: :maxdepth: 1 install-site (disponível também em `install-site.md `__). Replicando serviços e preparo dos dados ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Para reproduzir os microserviços, deve-se reproduzir também as bases de dados. As instruções para replicação do *software* estão em `install-services.md `__. A preparação dos dados pode ser realizada de três modos: - *sandbox*: base de dados mínima com dados de teste. - *referência*: dados da base em operação, em um site Cuidando já implantado. - *novo*: construir uma base de dados nova (por exemplo para um novo município). A metodologia e dicas encontram-se descritas `nesta Wiki `__. Replicação completa ~~~~~~~~~~~~~~~~~~~ Para replicar ambos, o site e os serviços, um script mais consido também é oferecido: `src/full.sh `__. CRÉDITOS E LICENÇAS ------------------- A presente documentação e todos os scripts `deste módulo de documentação `__ estão licenceados sob `CC-BY 4.0 `__. O Cuidando2 é um projeto realizado por várias mãos, - Alexandre Evangelista de Souza Júnior (`@alexandre `__) - Andrés M. R. Martano (`@andresmrm `__) - Gisele S. Craveiro (coordenação), - Jutta Machado Schimdt - Solaine Lima - ... e todos os parceiros e beta-testers, que auxiliaram com sugestoes criativas e construtivas com apoio de, - `COLAB-USP `__ - `OKBR `__ - ? (financeamento) e disperso por alguns módulos, listados a seguir com indicação das respectivas licenças e equipes: - `Site Cuidando do Município `__: licença `AGPLv3 `__. - *equipe*: Gisele (coordenação), Andrés (software), Solaine (design). - `Software `__: @andresmrm e @LuizArmesto - `Gastos Abertos `__: licença `AGPLv3 `__ em nome de `OKBR `__/`Projeto Gastos Abertos `__. - `*Dados* `__: @aivuk, @andresmrm. - `*Software* `__: @andresmrm , @aivuk, @LuizArmesto, @waffle-iron, @carlosandrade, @lpirola. - Demais `microserviços `__ e módulos de apoio: - `eSIC Livre `__: licença `AGPLv3 `__. - *equipe*: @alexandre e @andresmrm - `Tagarela `__: licença `AGPLv3 `__, software @andresmrm. - `Viralata `__: licença `AGPLv3 `__, software @andresmrm. - `Viratoken `__: licença `AGPLv3 `__, software @andresmrm. .. |Alt text| image:: cuidando2_arq2-827px.png Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`