Person

O serviço de pessoas oferecido pelo BISCore tem a finalidade de centralizar o cadastro de pessoas físicas e jurídicas por todo o sistema. A entidade Person conterá todos os dados relacionados à pessoa, e deve usada de forma compartilhada pelos plugins e módulos.

Em sua primeira versão, Person começa oferecendo um conjunto de campos para cada tipo de pessoa. Em versões futuras novos campos deverão ser oferecidos para centralizar o máximo de informações possíveis.

Estrutura

O serviço oferece o objecto PersonVO para representar cada pessoa. Dentro de PersonVO há dois outros objetos:

• PersonFieldVO - Usado para armazenar informações adicionais ou campos do tipo "lista" como telefones, e-mails, etc..
• PersonAddressVO - Usado para armazenar os endereços da pessoa, como "residencial", "comercial", "fábrica", "Loja 1", "Loja 2", etc..

PersonVO deve ser referenciado pelo objeto que usa determinada pessoa, de forma associativa. Porém jamais deverá ser persistido em cascata. PersonVO deve sempre ser persistido utilizando os métodos publicados no na fachada do BISCore.

Persistência Automática Como o BISCore utiliza as definições da JPA para persistir seus objetos, a maneira de evitar que o objeto seja persistido ou alterado automaticamente ao persistir um objeto que utilize o PersonVO, é garantir que no mapeamento seja definida a expressão "cascade = CascadeType.REFRESH" nos mapeamentos OneToOne, ManyToOne ou OneToMany.

Funcionamento e Usabilidade

O sistema não permitirá duas pessoas cadastradas com o Mesmo CPF/CNPJ, no entanto, permitirá que se cadastre uma pessoa sem o CPF ou CNPJ. Por isso, é recomendável que antes de associar um PersonVO novo em um determinado objeto, é aconselhável verificar se não existe ainda um Person com aquele CPF/CNPJ. Neste caso é aconselhável associar o objeto já existente. Como implementar essa usabilidade na UI do usuário deve ser definida na documentação de cada tipo de UI.

Funcionamento do Endereço

O Person utiliza o serviço de Location para cadastrar um endereço. Caso o CEP seja preenchido, o sistema verificará se o CEP é conhecido pelo Location, e em caso positivo, copiará as informações do Location por cima de qualquer informação definida no PersonAddressVO. Mantendo inalterado apenas campos adicionais como Número e Complemento. Caso o CEP não seja conhecido, ele não será cadastrado no serviço de Location, mas será permitido que o usuário utilize o endereço digitado manualmente (Sem associação com o LocationAddress).

Campos

Aqui estão relacionados os campos atuais dos objetos, sua finalidades e requisitos:

PersonVO

• type - Tipo de pessoa, Física ou Jurídica
• displayname - Nome de exibição. Um nome amigável que o usuário possa definir como quiser para identificar a pessoa. Ficando livre para criar seu próprio padrão como "Rodrigo Leitão (Barinella)" ou "Rodrigo - Barinella" ou ainda "Técnico: Máquina de Lavar (Mário)". Na UI, o BIS poderia oferecer para gerar esse campo automaticamente sugerindo alguns padrões de acordo similar ao que o outlook express funciona.
• contactname - Nome do Contato. Para PJ deve ser considerado como razão social, enquanto que para PF deve ser considerado como nome completo. Na UI é aconselhável exibir os títulos do campo com esses nomes para não confundir o usuário.
• cpfcnpj - Campo usado para armazenar o CPF ou CNPJ da pessoa.
• companyname - Nome da Empresa. Para PJ utilizar como nome fantasia da empresa. Para PF utilizar como Empresa para colocar onde trabalha.
• worktitle - Apenas PF Colocar o cargo da pessoa na empresa, como "vendedor", "supervisor", "gerente comercial", "técnico" Etc.
• ie - Apenas PJ Inscrição Estadual da empresa.
• im - Apenas PJ Inscrição Municipal.
• birthday - Na PF usado para armazenar a data de nascimento. Na PJ utilizar para armazenar a data de início da empresa: data da fundação.
• note - Campo livre para escrita de observações do contato. Por exemplo dados que não tem um campo próprio.

TODO Task Definir como representar a empresa isenta de IE ou de IM, já que deixar null simplesmente significa que a informação não foi definida.

PersonFieldVO

O PersonFieldVO mistura diversos tipos de campos, que só serão diferenciados pelo campo type. Optamos por manter todas as informações em um único objeto ao invés de um monte separado para simplificar o desenvolvimento, a persistência, e mesmo a performance de manipulação no banco de dados já que tudo fica em uma única tabela.

• indexorder - Salva a ordem dos registros. A ordem é importante para definição de dados primários como telefones, e-mails, etc.
• type - Define o tipo de informação que este objeto armazena. Dependendo do tipo definido e seu tipo de dado, o valor deverá ser definido no campo value correspondente.
  • EMAIL - Define um endereço de e-mail. (salvo em valuetext).
  • WEBSITE - Define um endereço web. (salvo em valuetext).
  • CUSTOMDATE - Permite a definição de uma data qualquer pelo usuário. (salvo em valuedate)
  • CUSTOMTEXT - Permite a definição de um texto qualquer pelo usuário. (salvo em valuetext)
  • PHONE - Permite a definição de telefones.
• label - Define um rótulo para identificar o campo. Por exemplo, se o campo for do tipo telefone, o usuário pode aplicar labels para saber de onde são os telefones, como "casa", "cunhada", "trabalho", "celular", "nextel", "televendas", "central de relacionamento", etc. Este campo é livre para o usuário escrever o que achar pertinente.
• valuetext - Campo utilizado para salvar os campos do tipo texto.
• valuedate - Campo utilizado para salvar os campos do tipo data, hora e data-hora.

PersonAddressVO

Este objeto mantém o cadastro de cada endereço definido. Ele utiliza o serviço de Location do BISCore, e consequentemente tem referências para seus objetos.

• indexorder - Define a ordem dos endereços. A ordem é importante para definir endereços primários/principais, assim como para sempre exibir para o usuário na mesma ordem que ele salvou.
• label - Define um rótulo para identificar o endereço. Por exemplo, "residência", "fábrica", "loja 1", etc. É um campo livre para uso do usuário.
• street - Nome da rua do endereço. Incluindo o tipo do logradouro, como "Avenida", "Rua", etc.
• number - Número da casa/imóvel do endereço. Só permite valor numérico inteiro.
• complement - Complemento do endereço, como "Casa 2", "Casa dos Fundos", "Bloco 25, Apartamento 44", etc.
• neighborhood - Bairro do endereço.
• cep - CEP do endereço.
• LocationCityVO - Referência ao objeto que representa a cidade. Obrigatório. ao definir a cidade.
• LocationAddressVO - Referência ao definir a rua. Não é obrigatório, mas é recomendado para manter o endereço vinculado ao cadastro de ruas do serviço de Locaiton.

PreProcess & Validação

Validações

• Campos Obrigatórios
  • Verificar a obrigatoriedade já definida no modelo o Banco
• Verificar Unicidade dos Campos no Banco de Dados
  • PersonVO.displayline
  • PersonVO.cpfcnpj (Se não nulo)
• PersonVO
  • cpfcnpj - validar se numeração é válida de acordo com o type definido.
  • ie - validar se numeração é valida
  • birthdate - validar se data é passada.
• PersonFieldVO
  • type - Verificar se esta preenchido, e para cada tipo aceito verificar se os campos "value" que não são utilizados estão definidos como null e fazer as validações específicas abaixo:
    • EMAIL - Validar se o e-mail está em um formato válido.
    • WEBSITE - validar se o site tem um endereço válido.
    • CUSTOMDATE - Validar se a data está adequada e se o horário está zerado.
    • CUSTOMTEXT - Nada específico para validar.
    • PHONE - Valida se o telefone está preenchido corretamente. Obrigar a presença do DDD, validando assim o tamanho do número para fixo e celulares com o 9°dígito.
• PersonAddressVO - Nenhuma validação

PreProcessamentos

• • PersonFieldVO
    • indexorder - Criar o indexorder começando em 0 de acordo com a posição do item na lista.
    • valuetext - Definir como null se type igual a: CUSTOMDATE.
    • valuedate - Definir como null se type igual a: EMAIL, WEBSITE, CUSTOMTEXT, PHONE.
  • PersonAddressVO
    • indexorder - Criar o indexorder começando em 0 de acordo com a posição do item na lista.
    • cep - Se preenchido, procurar pelo LocationAddress e se encontrado copiar suas informações e associar ao PersonAddressVO incluindo a associação à LocationCityVO, se não encontrado garantir que nenhum LocationAddressVO ficará associado ao PersonAddressVO.

UI Vaadin

PersonComponent

O PersonComponent é um componente usado na UI do BIS que permite que telas dos módulos e plugins manipulem o objeto PersonVO sem a necessidade de incluir campo à campo em sua tela. Este componente recebe (ou não) um PersonVO, cria os campos e já o associa completamente. Desta forma, invés do desenvolvedor da tela ter que criar e obter o valor de cada campo, basta incluir este componente e obter o valor através do método:

getPersonVO();

Requisitos & Regras de Funcionamento

A principal ideia do serviço Person do BISCore é garantir um "cadastro único" das pessoas (Físicas e Jurídicas) em todo o sistema. Permitindo que as pessoas cadastradas em um módulo estejam disponíveis em outros módulo. Já a ideia do PersonComponent é simplificar a implementação dessa ideia nas telas dos módulos que utilizam o Person para manipular o cadastro dessas pessoas. Assim, temos as seguintes regras:

1. O componente deve identificar automaticamente o tipo de pessoa (física ou jurídica) de acordo com o valor digitado em "CPF/CNPJ:".
2. Para os casos em que o usuário não informe (ou não saiba) o CPF/CNPJ, o componente deve ter um campo (combobox) com as opções: "Pessoa Física Sem CPF" e "Pessoa Jurídica sem CNPJ" que permitam o componente identificar o tipo de pessoa sendo cadastrada sem a necessidade do documento.
3. O componente deve estender algum tipo de layout (Grid, VerticalLayout, etc.) sem incluir nenhum "Panel" (como o BISPanel). Deixando a prerrogativa de ser inserido em um Panel ou não para a tela que o for utilizar. Algumas telas, por exemplo, podem preferir inseri-lo diretamente em alguma "Aba" do PanelTab, BISPopupPanel, etc..
4. Devido a resolução definida no Padrão Visual o componente deve caber em uma dimensão mínima de 1000px (Largura) x 500px (Altura). E deve ser preparado para "esticar" para resoluções maiores.

Regras de Habilitação dos Campos

1. O campo "CPF/CNPJ:" é o único campo que ficará sempre habilitado.
2. O campo "Tipo de Cadastro:" só fica habilitando enquanto o campo "CPF/CNPJ:" estiver em branco.
3. Quando o "CPF/CNPJ:" for preenchido, o campo "Tipo de Cadastro:" deverá ter a opção "Cadastro Completo" selecionada e ser desabilitado.
4. Os demais serão desabilitados sempre que o campo "CPF/CNPJ:" estiver vazio E o campo "Tipo de Cadastro:" não estiver definido com uma das opções de "Cadastro Incompleto".

Quando uma das duas condições for falsa, os campos devem estar habilitados para edição, ou seguir suas próprias regras de habilitado/desabilitado.}}

Construtor

Lógica de construção:

1. O construtor do PersonComponent deve receber um PersonVO como atributo, sendo que se o objeto recebido for:
   1. nulo: o componente deve criar um novo PersonVO e associar todos os campos a este novo PersonVO.
      1. Assim que criado o componente deve ter todos os seus campos desabilitados. Permitir apenas o campo "CPF/CNPJ:" e o "Tipo de Cadastro:" habilitados para preenchimento.
   2. Não for Nulo, utiliza o objeto recebido para associar aos campos.

Habilitando/Desabilitando em Massa O melhor para habilitar e desabilitar todos os componentes é utilizar algum container e desabilita-lo ao invés de ir campo a campo. Assim, evita inclusive a interferência de acabar habilitando algum campo que tem sua própria lógica de habilitação. Habilitando algum componente que deveria continuar desabilitado, como o caso do campo "Nome da Rua" que deve continuar desabilitado de acordo com o preenchimento do campo "CEP:". No caso do esboço, a maneira mais fácil será desabilitar o próprio TabPanel, se possível.

Campo: CPF/CNPJ

Uma vez que o componente foi criado de acordo com a regra do construtor, o usuário poderá alterar o valor do campo "CPF/CNPJ:". Neste caso devemos seguir as seguintes regras:

• Caso o novo valor seja um CPF/CNPJ válido...
  • ...e o novo valor não esteja no banco: Simplesmente deixamos que o CPF/CNPJ seja alterado no PersonVO que já estamos editando. Fazendo com que o objeto seja inserido com o novo valor.
  • ...e o novo valor esteja no banco: Exibimos um dialog (BISConfirmCancelDialog) com a seguinte indagação:

    No caso de CPF: "O CPF já está em uso por outra pessoa. Gostaria de utilizar os dados existentes?"

    No caso de CNPJ: "O CNPJ já está em uso por outra empresa. Gostaria de utilizar os dados existentes?"

    Caso o dialog seja confirmado o objeto atual deve ser substituído pelo novo. Associar o novo objeto aos campos de tela os valores serão atualizados para os dados que vieram do banco de dados. Em caso de cancelamento o valor do campo "CPF/CNPJ:" deve ser limpo. Impedindo que o usuário tente inserir ou alterar o objeto atual para o CPF/CNPJ que já está em branco.

• Caso o novo valor esteja em branco: permite que o PersonVO receba o novo valor em branco.

Valores Inválidos Caso o valor seja definido como um valor inválido, não é considerado como se o valor tivesse sido alterado. O vaadin nem sequer passar o valor para o VO. Por isso não nos preocupamos se o usuário fizer a troca para um valor inválido.

Campo: Tipo de Cadastro

Como o componente deve permitir que o usuário cadastre uma nova pessoa sem o CPF ou CNPJ. Para isso deve incluir do lado do campo "CPF/CNPJ:" um combobox com o título "Tipo de Cadastro:". Este combo terá as seguintes opções:

• Cadastro Completo - Quando esta opção for escolhida o combo, os outros campos só serão habilitados de acordo com o preenchimento do campo "CPF/CNPJ:"
• Pessoa Física sem CPF - Quando esta opção for escolhida o campo CPF/CNPJ deve ser limpo e desabilitado. Os demais campos devem ser habilitados para edição. A aba de informações PJ deve ser ocultada.
• Pessoa Jurídica sem CNPJ - Quando esta opção for escolhida o campo CPF/CNPJ deve ser limpo e desabilitado. Os demais campos devem ser habilitados para edição. A aba de informações PF deve ser ocultada.

Esboço da UI

Abaixo estão alguns esboços sobre a composição do componente e algumas observações:

Para organizar todos os campos do objeto, os campos serão agrupados em abas de um TabPanel. Permitindo inclusive que os campos que o PersonVO venha a ganhar no futuro possam ser incluídos no componente sem desfigurar sua aparência atual.

Identificação Pessoa Física

Identificação Pessoa Jurídica

Na aba "Identificação" mantemos os campos referente a identificação de cada pessoa (Física ou Jurídica) Por isso uma aba diferente para cada pessoa. Dependendo do valor informado em "CPF/CNPJ" a aba correspondente deve aparecer. Caso não seja informado, a aba que aparecerá será de acordo com as opções do tipo de pessoa no combobox "Tipo de Cadastro". Lembrando que todo o tabpanel só ficará habilitado quando uma das informações já tiver sido definida.

Contato

Na aba contato teremos 3 listas. Para inclusão de números de telefones, e-mails e websites. A tela deve incluir uma nova coleção de campos para "telefone" a cada vez que o usuário clicar no campo "Adicionar Novo Telefone". O mesmo para o e-mail e websites. Similar ao funcionamento desses campos em cadastro de contatos atualmente no Android e iOS.

O campo "Label", que servirá para o usuário criar alguma identificação para o dado, deverá ter um PoupUp que exiba uma lista dos labels já utilizados, preferencialmente na ordem do mais usado para o menos usado. Ao clicar em um item na lista o mesmo label é definido na caixa de label. Não utilizamos um combo pois o usuário poderá inserir um valor que ainda não tenha sido utilizado.

Endereços

A aba de endereços tem a finalidade de permitir que o usuário gerencie endereços dos contatos. Podendo ser salvo mais de um endereço, como por exemplo, o endereço da fábrica, da loja, do estoque, etc. O funcionamento da tela segue o mesmo conceito da aba de contatos, a cada clique no botão "Adcionar ..." um novo bloco de endereço é adicionado.

Dados Bancários

A aba de Dados Bancários funciona como a aba de contatos ao gerenciar a lista de dados bancários. A cada clique no botão "Adicionar..." um novo bloco é criado para a entrada de novos dados.

Notas

Esta aba simplesmente exibe um campo de TextArea livre para que o usuário possa escrever o que preferir sobre a pessoa. Permitindo que informações sem campo próprio possam ser "salvas" até que um lugar apropriado seja criado.