# Instrução Orientativa para Desenvolvimento de Sistemas no IFPE Instrução Orientativa para Desenvolvimento de Sistemas no IFPE # Introdução Este documento tem por finalidade descrever procedimentos, documentos necessários e boas práticas a serem adotadas em um projeto de software para que o produto seja adotado como solução **institucional**. É recomendável que a equipe engajada em desenvolver um software institucional envolva a DADT desde o começo do processo a fim de garantir conformidade às instruções normativas e, por conseguinte, facilitar a implantação sistemática da solução. ### Análise e Projeto - [DOD](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/documento-de-oficializa%C3%A7%C3%A3o-da-demanda-366 "Documento de Oficialização da Demanda") (opcional) - [Visão](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/documento-de-vis%C3%A3o-72b "Documento de Visão") - [Arquitetura](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/documento-de-arquitetura-839 "Documento de Arquitetura") ### Desenvolvimento Define linguagens e tecnologias suportadas e seus respectivos guias de estilo a fim de garantir legibilidade e qualidade do código gerado. Além disso, também são apresentadas boas práticas para documentação do código com o objetivo de facilitar futuras manutenções. Por fim, é apresentada uma proposta de interface gráfica construção dos sistemas. Essa proposta deve ser ajustada em parceria com a ASCOM para cada sistema desenvolvido. - [Linguagens e Guias de Estilo](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/linguagens-e-guias-de-estilo-6ec) - [Documentação](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/documenta%C3%A7%C3%A3o-67c) - [Interface de Usuário](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/interface-do-usu%C3%A1rio-6da) - [Release Notes](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/release-notes-8f1) ### Testes Para assegurar a qualidade do software, torna-se necessário envolver o processo de testes desde o começo do desenvolvimento em diversos níveis: desde testes unitários até testes de aceitação. Recomenda-se o uso de ferramentas de integração contínua a fim de descobrir problemas o mais cedo possível e facilitar a geração de relatórios. - Caixa-Branca - Caixa-Preta - [Relatórios](https://wiki.ifpe.edu.br/testes-relatorio) ### Implantação - [Web](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/implanta%C3%A7%C3%A3o-%28web%29-b2e) # Documento de Visão ##### Checklist - \[ \] Validado pelo requerente (escopo e protótipo de telas) ### Introdução ##### Finalidade do documento A finalidade deste documento é especificar os requisitos relevantes dos usuários, assim como os limites e restrições evidentes que dão uma visão geral. Essa visão viabiliza a identificação e a produção de documentos e requisitos mais técnicos, assim como do próprio sistema. A visão serve como forma de permitir a compreensão, pelos participantes do projeto, do "o quê e por quê" o projeto existe e provê uma estratégia a partir da qual todas as futuras decisões podem ser validadas. ##### Finalidade do sistema > > Descrever a finalidade do sistema > ### Escopo do produto ##### Declaração do escopo do produto > > Seção utilizada para documentar novos produtos. Forneça a declaração do escopo do produto, descrevendo as características do produto, serviço ou resultado que se deseja obter com a execução do projeto. Caso esteja documentando um produto já existente incluir o texto **"Não se aplica"** > > > > ##### Não faz parte do escopo > > > Descreva de forma explícita as características que não fazem parte do produto. Em muitos casos, é mais fácil declarar que certos comportamentos nunca poderão ocorrer. Exemplo: O sistema não fará controle financeiro; O sistema não fará estatísticas mensais. Caso esteja documentando um produto já existente incluir o texto **"Não se aplica"** ### Visão geral do produto ##### Modelagem de processos do negócio > > Cole aqui um diagrama de atividade para representar os processos de negócio (conjunto de atividades que ocorrem em algum negócio com o objetivo de gerar um produto ou serviço, alcançando determinado objetivo). Esse diagrama fornece o entendimento de como são realizadas as diversas atividades contidas em cada processo. > #### Descrição Para descrever funcionalidades/requisitos/features há duas opções: 1. Tradicionais requisitos e casos de uso 2. Utilizar Cucumber/Linguagem Gherkin para definir as features ##### Requisitos > > Descreva os requisitos funcionais e não funcionais do produto. >
CódigoDescrição
##### Casos de Uso > > Listar e descrever resumidamente as funcionalidades que se espera encontrar no produto. Funcionalidades são capacidades que o produto deve ter para atender a uma necessidade de usuário (ator). Cada funcionalidades descreve um serviço percebido pelo usuário e que tipicamente requer entradas para alcançar o resultado desejado. À medida que o modelo de casos de uso for desenvolvido, atualize a descrição para fazer referência aos casos de uso. Cada funcionalidade será descrita mais detalhadamente no modelo de casos de uso. É recomendado ordernar os casos de uso por ordem de decrescente de prioridade. >
NomeDescriçãoPrioridadeRequisitos Relacionados
##### Diagrama de Casos de Uso > > Defina aqui o diagrama de casos de uso > ##### Features Exemplo de uma feature que obedece à sintaxe do Gherkin/Cucumber: ``` #language: pt Funcionalidade: Gerenciar Workflows Para criar fluxos de tramitação de uma requisição Como um usuário com permissão para definição de fluxos Eu quero selecionar a sequência de papéis para tramitação de acordo com o curso e tipo de requisição Cenario de Fundo: Dado que o usuário está logado Cenario: Criar workflow Dado que possui permissão para criar workflows Quando usuário selecionar opção para criar workflow E selecionar o grupo-alvo E selecionar o tipo de requisição E selecionar ordem dos grupos Então solicitar salvamento do workflow na base de dados Mas recusar caso haja algum workflow conflitante ``` ##### Protótipo de Telas > > Defina aqui os protótipos de Telas > # Documento de Oficialização da Demanda Documento, assinado pelo beneficiário, que explicita a necessidade da contratação em termos do negócio da organização ([ref](http://portal3.tcu.gov.br/portal/page/portal/TCU/comunidades/logistica/repositorio_qrn/wikic/001.002.htm#Fund776-1)). --- (Novo Software) [Download](https://docs.google.com/a/reitoria.ifpe.edu.br/document/d/1IPTJvT_S6eX6333TNw3EkakNpxIJC-blRQJcOOBgOAc/edit?usp=sharing) (Alteração de Software) [Download](https://docs.google.com/document/d/1YL4HQ4zqkQPTz6SHad8SUgPz32fe0pjNLTTf7POTMd4/edit) --- A fim de aprovar a demanda, deve-se considerar os requisitos do Art. 12. da Lei 8.666 ([ref](http://www.planalto.gov.br/ccivil_03/leis/l8666cons.htm)): 1. segurança; 2. funcionalidade e adequação ao interesse público; 3. economia na execução, conservação e operação; 4. possibilidade de emprego de mão-de-obra, materiais, tecnologia e matérias-primas existentes no local para execução, conservação e operação; 5. facilidade na execução, conservação e operação, sem prejuízo da durabilidade da obra ou do serviço; 6. adoção das normas técnicas, de saúde e de segurança do trabalho adequadas; (Redação dada pela Lei nº 8.883, de 1994) 7. impacto ambiental. # Documento de Arquitetura Neste documento devem ser anexados todos os diagramas existentes. ##### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/documento-arquitetura#diagramas-exigidos)Diagramas exigidos - Modelo do domínio ([ver](http://www.documentador.pr.gov.br/documentador/pub.do?action=d&uuid=@gtf-escriba@b6494eb6-e917-4de1-ae5d-f7ff25612f01)) ##### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/documento-arquitetura#diagramas-recomendados)Diagramas recomendados - Sequência / Atividade # Linguagens e Guias de Estilo Este documento enumera as linguagens/frameworks que serão aceitas para o desenvolvimento de sistemas institucionais. - O motivo de limitar a escolha é usar os conhecimentos mais comuns entre os membros da equipe de desenvolvimento a fim de garantir a manutenção dos sistemas a longo prazo. - Os guias de estilo devem ser estritamente seguidos e passíveis de checagem automática através de qualquer *linter* disponível que esteja em conformidade com o guia. ##### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-linguages-estilo#sum%C3%A1rio)Sumário 1. [Python](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/linguagens-e-guias-de-estilo-6ec#bkmrk-python "Python") 2. [PHP](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/linguagens-e-guias-de-estilo-6ec#bkmrk-php "PHP") 3. [Javascript](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/linguagens-e-guias-de-estilo-6ec#bkmrk-javascript "Javascript") 4. [Java](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/linguagens-e-guias-de-estilo-6ec#bkmrk-java "Java") ### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-linguages-estilo#python)Python - Guia de Estilo - [PEP 8](https://www.python.org/dev/peps/pep-0008/) - Web - [Django](https://www.djangoproject.com/) ([Padrões](http://django-best-practices.readthedocs.io/en/latest/code.html)) - [Flask](http://flask.pocoo.org/) - Arquivos Ignorados no repositório - [.gitignore](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-linguages-estilo) ### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-linguages-estilo#php)PHP - Guia de Estilo - [PSR-2](http://www.php-fig.org/psr/psr-2/) - Web - [Laravel](https://laravel.com/) ### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-linguages-estilo#javascript)Javascript - Guia de Estilo - (ES6) [Airbnb](http://airbnb.io/javascript/) - Front-End - [AngularJS](https://angularjs.org/) - [JQuery](https://www.jquery.org/) - [VueJS](https://vuejs.org/) - Back-End - [ExpressJS](http://expressjs.com/pt-br/) - [Sails](http://sailsjs.org/) ### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-linguages-estilo#java)Java - Guia de Estilo - [Google Style Guide](https://google.github.io/styleguide/javaguide.html) - Web - [Play Framework](https://www.playframework.com/) - Mobile - [Android](https://developer.android.com/develop/index.html) # Documentação > Sempre programe considerando que a pessoa que vai manter seu código é um psicopata violento que sabe onde você mora. ##### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-documentacao#sum%C3%A1rio)Sumário 1. [Código](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/documenta%C3%A7%C3%A3o-67c#bkmrk-c%C3%B3digo) 2. [API](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/documenta%C3%A7%C3%A3o-67c#bkmrk-api) ### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-documentacao#c%C3%B3digo)Código Cada método deve possuir um comentário associado explicando sua finalidade, cada parâmetro e o seu retorno. Além disso, deve ser possível acessar a documentação fora do código através de uma página passível de navegação. Para isso, podem ser usados geradores automáticos de documentação como, por exemplo, o [Sphinx](http://www.sphinx-doc.org/en/stable/) para Python ou o nativo [Javadoc](http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html) para Java. Exemplos: - Javadoc ```code /** * Usado para buscar as inscrições válidas em um determinado edital. * Ver {@link remocao.ifpe.edu.br}. * @param edital Identificador do edital * @return Lista de inscrições válidas. * @see Inscricao, Edital */ ``` - Docstring / Epydoc ``` """ Essa função é usada para gerar um número aleatório. @type max: number @param max: Número máximo que o número aleatório pode atingir @rtype: number @return: número aleatório 0 < x < max """ ``` ### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-documentacao#api)API No desenvolvimento de uma API, esta também deve possuir uma documentação *live*. Ver documentação [Swagger](http://swagger.io/). # Interface do Usuário # Modelo de página para desenvolvimento de Sistemas IFPE ##### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-interface-usuario#sum%C3%A1rio)Sumário 1. [Logotipo](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/interface-do-usu%C3%A1rio-6da#bkmrk-logotipo) 2. [Manual](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/interface-do-usu%C3%A1rio-6da#bkmrk-manual) 3. [Navbar](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/interface-do-usu%C3%A1rio-6da#bkmrk-navbar) 4. [Footer](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/interface-do-usu%C3%A1rio-6da#bkmrk-footer) 5. [Exemplo](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/interface-do-usu%C3%A1rio-6da#bkmrk-exemplo) --- ### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-interface-usuario#logotipo)Logotipo
[![ifpelogo.png](https://wiki.ifpe.edu.br/uploads/images/gallery/2017-09-Sep/scaled-840-0/ifpelogo.png)](https://wiki.ifpe.edu.br/uploads/images/gallery/2017-09-Sep/ifpelogo.png)
### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-interface-usuario#manual)Manual Manual de Identidade Visual do IFPE [Download](http://gitlab.ifpe.edu.br/cadt/guia-software-institucional/uploads/1ec0caf75ad510b27d9634de5f0604da/Manual_todos_os_Campi.pdf) ### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-interface-usuario#p%C3%A1gina-estrutura)Página (Estrutura) Recomenda-se usar [bootstrap](http://getbootstrap.com/) como *framework* para desenvolvimento *front-end*. ##### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-interface-usuario#navbar)Navbar ```code ``` ##### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-interface-usuario#footer)Footer ```code ``` ##### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-interface-usuario#exemplo)Exemplo [index.html](http://gitlab.ifpe.edu.br/cadt/guia-software-institucional/uploads/ea1f528a623de395928295742465efa6/index.html) ### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-interface-usuario#emag-modelo-de-acessibilidade-em-governo-eletr%C3%B4nico)eMAG - Modelo de Acessibilidade em Governo Eletrônico Todos os sistema desenvolvidos para o IFPE devem ser adaptados ao Modelo de Acessibilidade em Governo Eletrônico para garantir a acessibilidade de todos. O Modelo de Acessibilidade em Governo Eletrônico (eMAG) tem o compromisso de ser o norteador no desenvolvimento e a adaptação de conteúdos digitais do governo federal, garantindo o acesso a todos. As recomendações do eMAG permitem que a implementação da acessibilidade digital seja conduzida de forma padronizada, de fácil implementação, coerente com as necessidades brasileiras e em conformidade com os padrões internacionais. Recomendamos o uso da ferramenta [*Tota11y*](http://khan.github.io/tota11y/) para verificar automaticamente a acessibilidade do sistema desenvolvido. O manual completo do eMAG pode ser encontrado no [site](http://emag.governoeletronico.gov.br/) do Departamento de Governo Eletrônico. # Release Notes Para cada nova versão do sistema, deve-se criar um tag específica no repositório anexando um documento estruturado como o exemplo a seguir: ## [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-release-notes#exemplo)Exemplo O sistema online **BPMN.ifpe** está com sua primeira versão disponível para acesso interno. #### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-release-notes#informa%C3%A7%C3%B5es)Informações
ProdutoBPMN.ifpe
Versãov0.1
Data01/12/2016
Acesso[Link](https://processos.ifpe.edu.br)
EscopoInterno
MilestoneFuncionalidades Básicas
Instruções[Manual](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/release-notes-8f1)
#### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-release-notes#adi%C3%A7%C3%B5es)Adições - \[UC05\] Compartilhar Diagrama - \[UC08\] Recuperar versão do diagrama #### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-release-notes#removidos)Removidos - Log do sistema usando [redis](https://redis.io/) ### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-release-notes#mudan%C3%A7as)Mudanças - Entrar no sistema usando credenciais do novo LDAP ### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-release-notes#corrigidos)Corrigidos - Permissões inválidas # Relatórios #### **Relatório** ##### Modelo Para cada *Release Candidate* de um sistema, é necessário anexar um relatório de testes executados na requisição de implantação. ---
**Produto**Nome do produto
**Milestone**Protótipo v1.0
**Categoria dos Testes**(Unitários / Interface / etc.)
**Data de execução**dd/MM/yyyy hh:mm
**\# Casos de Teste**250
**\# Sucessos**239
**\# Falhas**11
**\# Bugs corrigidos**2
**\# Bugs encontrados**0
**Detalhes (link)**[www.example.com](https://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/www.example.com)
**Comentários**
##### Ferramentas Para a automação da criação de relatórios - Jenkins - [xUnit](https://wiki.jenkins-ci.org/display/JENKINS/xUnit+Plugin) [![Screenshot_from_2016-09-27_15_31_12.png](https://wiki.ifpe.edu.br/uploads/images/gallery/2017-06-Jun/scaled-840-0/Screenshot_from_2016-09-27_15_31_12.png)](https://wiki.ifpe.edu.br/uploads/images/gallery/2017-06-Jun/Screenshot_from_2016-09-27_15_31_12.png) # Implantação (Web) A fim de facilitar a implantação do sistema em modo produção, o repositório deve conter os arquivos de configuração necessários para permitir o *deploy* de forma distribuída na infra-estrutura usando [Docker ](https://www.docker.com/). ### [](https://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/implantacao-web#build)Build A recomendação é que seja criado um `Dockerfile` ([ref](https://www.digitalocean.com/community/tutorials/como-instalar-e-utilizar-o-docker-primeiros-passos-pt)) com todas as instruções necessárias para criar uma imagem. Exemplo: ``` # https://www.digitalocean.com/community/tutorials/docker-explained-how-to-containerize-python-web-applications FROM ubuntu MAINTAINER Filipe Arruda (filipe.arruda@reitoria.ifpe.edu.br) RUN apt-get update RUN apt-get install -y tar git curl nano wget dialog net-tools build-essential RUN apt-get install -y python python-dev python-distribute python-pip COPY /minha_aplicacao /minha_aplicacao RUN pip install -r /minha_aplicacao/requirements.txt EXPOSE 80 WORKDIR /minha_aplicacao CMD python server.py ``` Para se conectar com outros serviços, como por exemplo um banco de dados, é recomendado criar um arquivo docker-compose.yml: ``` version: '2' services: db: image: postgres volumes: - app_data:/var/lib/postgresql/data web: build: . volumes: - .:/minha_aplicacao ports: - "7000:80" depends_on: - db ``` Vale salientar que é necessário definir os volumes/diretórios que devem ser salvos fora do *containter* para permitir backups/restaurações/escalabilidade.