Documentação comum

← Documentação Geral

REGRAS DE NEGÓCIO COMUNS:

RNC003 - Controle de alterações em uma entidade

O cadastro de uma <ENTIDADE> possui: (i) data/hora da sua criação; (ii) data/hora das alterações realizadas; (iii) usuário que realizou a respectiva alteração; e (iv) usuário que aprovou a alteração, caso a alteração tenha sido solicitado por usuário externo ao IMA.

RNC005 - Comportamento para situações em que o CEP não foi validado

Caso os dados do CEP não possam ser buscados devido a erros de comunicação com API externa, deve-se tentar localizar outro cadastro no sistema com mesmo CEP e trazer as seguintes informações a partir dele: estado e município. Caso não haja, deve-se permitir o cadastro com dados informados manualmente.

RNC006 - Comportamento para situações em que um cadastro exige um CPF

Sempre que um processo de cadastro exigir a indicação de um CPF, o sistema deve verificar se já existe um usuário registrado com esse CPF; se existir, o novo cadastro deve ser vinculado ao usuário já existente, e, caso não exista, uma nova conta de usuário adormecida deve ser criada para o CPF informado.

RNC007 - Permissões de acesso

As permissões de acesso a telas, funcionalidades e tipos de informação são atribuídas de acordo com o cargo do usuário. Além disso, as informações exibidas podem variar conforme a unidade administrativa vinculada ao usuário. Essas regras são detalhadas e atualizadas de forma incremental à medida que são especificadas as histórias de usuário, sendo consolidadas no seguinte documento: Planilha de Módulos e Permissões do sistema

RNC008 - Estado do cadastro de uma entidade

O cadastro da <ENTIDADE> possui um dos seguintes estados, sendo possível alterar de um estado para outro, conforme as regras abaixo:

  • Ativo:
    • Estado em que o cadastro encontra-se válido no sistema.
    • Esse é o estado padrão, logo após a realização de um novo cadastro.
    • Um cadastro só pode ser ativado caso não haja erros de validação OU outros cadastros inativos vinculados a ele.
  • Inativo:
    • Situação em que o cadastro foi removido da base de dados do sistema (remoção lógica).
    • Um cadastro só pode ser inativado caso não haja outros cadastros ativos vinculados a ele e não exista violação de regras de negócio específicas do cadastro da <ENTIDADE>.

RNC010 - Coordenadas geográficas no componente de geolocalização

A localização informada por coordenadas geográficas deve possuir uma máscara de acordo com o formato informado, conforme especificado abaixo:

  • Formato DMS (Degrees, Minutes, Seconds):

    • Latitude deve variar de 0° a 90° e longitude de 0° a 180°, com minutos de 0 a 59 e segundos de 0 a 59,999999999999.

      • Deve indicar hemisfério utilizando N ou S para latitude e E ou W para longitude.

      • Deve aceitar até 12 casas decimais nos segundos, garantindo equivalência de precisão com o formato decimal.

      • Máscara:

        • DD°MM'SS.SSSSSSSSSSSS"N/S (Latitude)

        • DDD°MM'SS.SSSSSSSSSSSS"E/W (Longitude)

    • Formato DD (Decimal Degrees)

      • Latitude deve variar entre -90 e +90 e longitude entre -180 e +180.

      • Deve utilizar o sinal “+” ou “-” para indicar hemisfério (positivo = Norte/Leste, negativo = Sul/Oeste).

      • Deve aceitar até 15 casas decimais, conforme retorno da API do Google Maps.

      • Máscara:

        • [+|-]DD.DDDDDDDDDDDDDDD (Latitude)

        • [+|-]DDD.DDDDDDDDDDDDDDD (Longitude)

    • Exemplos equivalentes:

      • DMS: 19°09'56.979800000000"S 44°21'46.336500000000"W

      • DD: -19.165827719338893, -44.362871253967285

RNC011 - Geração de números de protocolo para documentos do sistema

O sistema deverá gerar automaticamente um número de protocolo único para todo documento oficial emitido em nome do IMA, tais como certificados, declarações, atestados e documentos correlatos. O número de protocolo deverá ser composto por 10 caracteres alfanuméricos e deverá permitir a identificação inequívoca do documento, possibilitando sua consulta e validação de autenticidade. Não será permitida a reutilização ou duplicidade de protocolos gerados pelo sistema, mesmo que para documentos de naturezas diferentes. Exemplo: A566T8UI9X.

CRITÉRIOS DE ACEITAÇÃO COMUNS:

CAC001 - Salvar cadastro de uma entidade

Dado que estou no formulário de cadastro e edição de <ENTIDADE>

// Caso de sucesso
E todos os campos obrigatórios estão corretamente preenchidos
E não há violação da regra de unicidade do cadastro
Quando salvo o cadastro
Então o sistema persiste os dados informados
E exibe uma mensagem informando que os dados da <ENTIDADE> foram salvos com sucesso

// Caso de erro - regra de duplicidade violada
E todos os campos obrigatórios estão corretamente preenchidos
E há violação da regra de unicidade do cadastro
Quando salvo o cadastro
Então o sistema não persiste os dados informados
E exibe uma mensagem informando que essa <ENTIDADE> já encontra-se cadastrada
E mantém os dados já informados pelo usuário

// Caso de erro - validação de dados falhou
E há campos obrigatórios não preenchidos ou preenchidos incorretamente
Quando salvo o cadastro
Então o sistema não persiste os dados informados
E exibe uma mensagem de erro “Por favor, verifique os campos obrigatórios”
E destaca os campos obrigatórios que estão faltando ou com erros de validação no formulário

CAC003 - Notificar erro ao usuário devido a falha técnica

Dado que estou em uma tela do sistema
Quando o sistema enfrenta problemas técnicos para realizar um ação (cadastrar, editar, recuperar, entre outros)
Então o sistema exibe uma mensagem informando que ocorreu um problema e que o usuário deve tentar novamente mais tarde. Se o problema persistir, ele deve entrar em contato com o suporte técnico.

CAC007 - Reenviar código de verificação

Dado que estou na tela de validação do código de verificação
E a ação de reenviar código está habilitada
Quando acesso a opção “Reenviar código”
Então o sistema reenvia um código de verificação para o email informado
E desabilita a ação de reenviar código por 30 segundos

CAC008 - Notificar erro ao usuário devido a falha de comunicação com API externa

Dado que estou em uma tela do sistema
Quando o sistema enfrenta problemas técnicos para realizar um ação (cadastrar, editar, recuperar, entre outros)
Então o sistema exibe a mensagem “Ocorreu um problema! Por favor, tente novamente mais tarde. Se o problema persistir, entre em contato com o suporte técnico.”.

CAC009 - Busca sem resultados

Dado que estou em uma tela de busca do sistema
E o campo de busca e/ou pelo menos um dos filtros disponíveis foi corretamente preenchido
Quando realizo a ação “Pesquisar”
E o sistema não encontrou registros compatíveis com os valores informados
Então o sistema exibe uma mensagem informando que nenhum resultado foi encontrado.

CAC010 - Uso incorreto de filtros de busca

Dado que estou em uma tela de busca do sistema
E o campo de busca e/ou pelo menos um dos filtros disponíveis não foi corretamente preenchido
Quando acesso a opção “Pesquisar”
Então o sistema não realiza a busca
E exibe uma mensagem de erro indicando os problemas encontrados

CAC011 - Indicação de filtros de busca aplicados

Dado que estou em uma tela de busca do sistema
Quando aplico um filtro
Então o sistema destaca quais filtros foram aplicados
E permite remover um filtro selecionado.

CAC012 - Relatório sem resultados

Dado que estou em uma tela de relatório do sistema
E pelo menos um dos filtros obrigatórios foi corretamente preenchido
Quando realizo a ação “Gerar relatório”
E o sistema não encontrou registros compatíveis com os valores informados
Então o sistema exibe uma mensagem informando que nenhum resultado foi encontrado.

CAC013 - Exibir mensagem de campos obrigatórios

Dado que acesso a tela de cadastro, visualização ou edição de um cadastro do sistema
Então o sistema exibe a seguinte mensagem indicativa ao topo do formulário do cadastro: “🛈 Campos indicados com * são obrigatórios e deverão ser preenchidos.”

CAC014 - Exibir alertas de um cadastro

Dado que acesso a tela de visualização de um cadastro do sistema
E o cadastro possui alertas associados
Então o sistema exibe os alertas ao topo do formulário de visualização do cadastro

REQUISITOS NÃO FUNCIONAIS:

RNF001 - Registro de eventos

O sistema deve realizar o registro de informações sempre que ocorrer um evento de cadastro ou alteração em qualquer entidade do sistema. O registro deve incluir as seguintes informações:

  1. Usuário que realizou a ação
  2. Data e hora do evento, no formato DD/MM/AAAA HH:MM:SS
  3. Dados cadastrados/alterados da entidade em questão

Os registros devem ser imutáveis, ou seja, não podem ser excluídos ou alterados após a sua criação.

RNF002 - Gerenciamento de chamadas externas (API)

Todas as chamadas externas realizadas pelo sistema, incluindo integrações com APIs (por exemplo, APIs de CEP), devem implementar um timeout de 10 (dez) segundos. Em caso de timeout excedido, o sistema deve realizar até 3 (três) tentativas adicionais antes de retornar uma falha.

Caso haja falha de comunicação, deve-se respeitar as regras de negócio definidas na própria história. Caso não haja, o comportamento padrão será notificar o usuário com a mensagem: “Ocorreu um problema! Por favor, tente novamente mais tarde!”.

RNF003 - Rotinas de backup

Devem ser realizadas cópias de segurança (backup) diárias da base de dados e dos documentos (arquivos) enviados pelos usuários do sistema. Essas cópias devem ser armazenadas por um período mínimo de 7 (sete) dias.

RNF004 - Validade de códigos de verificação

Os códigos enviados por e-mail para validação de cadastros têm prazo de duração de 30 (trinta) minutos. Após isso, o código expira, sendo necessário solicitar novo envio de código.

RNF005 - Responsividade

As telas do sistema devem se conformar a diferentes tamanhos de tela, a saber:

  • Móvel (Mobile): entre 320px e 767px, ideal para smartphones em retrato e paisagem.
  • Tablet: entre 768px e 1024px, para tablets menores e maiores.
  • Desktop: entre 1025px e 1400px, para telas de laptops e desktops maiores.
  • Desktop Grande (Large Desktop): acima de 1400px, para telas de alta resolução e monitores maiores.

RNF006 - Acessibilidade

As telas do sistema devem ser acessíveis seguindo os critérios de acessibilidade definidos conforme documento de orientações a seguir: Orientações para Desenvolvimento Acessível

REQUISITOS TÉCNICOS:

RT001 - Obtenção de dados de indivíduos, empresas e endereço

Os dados de indivíduos (pessoais), empresas e de endereço devem ser obtidos a partir de APIs oficiais do governo.

RT002 - Obtenção de dados de localização

Dados de localização (latitude/longitude) devem ser obtidos via GPS ou informada pelo usuário, manualmente ou por meio de plataformas de georeferenciamento.

RT003 - Pesquisa por nomes

A busca por nomes no sistema (produtores, estabelecimentos, entre outros) deve ser realizada utilizando o critério “contém”. Isso significa que, se o usuário informar o nome “Maria”, devem ser retornados todos os registros cujos nomes contenham a palavra “Maria”, independentemente do que vem antes ou depois dessa palavra.

A busca pelo nome também não deve ser sensível à acentuação nem à diferenciação entre maiúsculas e minúsculas. Por exemplo, um produtor/proprietário com o nome “João da Silva” deve ser retornado ao buscar por “JOÃO”, “João”, “joão” ou “Joao”.

RT004 - Paginação das telas de busca

Os resultados das buscas realizadas nos critérios de aceitação de busca devem ser paginados oferecendo 20 (vinte) registros por página.

RT005 - Verificação de unicidade campos de texto

Quando for necessário verificar a unicidade de um cadastro com base em um campo de texto, deve-se aplicar o seguinte procedimento: não ser sensível à acentuação nem à diferenciação entre maiúsculas e minúsculas. Por exemplo, os nomes “Suíno”, “suíno”, “suino” (sem acento) são todos referentes à mesma espécie.

RT006 - Paginação dos registros nas abas

Os registros em telas complementares as telas de cadastro devem ser paginados oferecendo 3 (três) registros por página.

RT007 - Ordenação das telas de busca do sistema

A ordenação dos registros das tabelas de busca deve ocorrer da seguinte forma:

  • Ao realizar a busca com um conjunto de filtros selecionados, o sistema deve ordenar os resultados, inicialmente, com base na data da última alteração do cadastro em ordem decrescente (mais recentes primeiro). Considera-se como “Data da última alteração”:

    • A data de cadastro, quando o registro ainda não possuir alterações posteriores;

    • A data da última edição, quando o registro já tiver sido alterado.

  • Após a apresentação dos resultados, o usuário poderá alterar a ordenação utilizando qualquer coluna disponível na tabela. A ordenação realizada pelo usuário deverá utilizar o critério alfanumérico.

RT007 - Ordenação dos resultados listados em abas

A ordenação dos registros listados nas abas deve ocorrer da seguinte forma:

  • O sistema deve ordenar os resultados com base na data da última alteração do cadastro em ordem decrescente (mais recentes primeiro), seguindo os mesmos critérios de definição da “Data da última alteração” na regra anterior.

RT009 - Ordenação das telas de vinculações

A ordenação dos registros de vinculação deve ocorrer da seguinte forma:

  • Os tipos de vinculação devem ser divididos em dois grupos: o primeiro composto pelos tipos de vinculação para os quais exista pelo menos um registro, e o segundo composto pelos tipos de vinculação para os quais não existam registros. Devem ser exibidos primeiro os tipos de vinculação que possuem registro e, em seguida, aqueles que não possuem.

  • Dentro de cada grupo, os tipos de vinculação devem ser organizados em ordem alfabética pelo nome (exemplo: Eventos, Exploração, Revendedora de Animais Vivos).

  • Dentro de cada tipo de vinculação, os registros devem ser listados em ordem de data de vinculação.