Person

Este módulo começou no BIS2 e também no BIS10, esta página armazena a informação do módulo de ambas as versões.

BIS10

O módulo Person faz parte do Kernel e tem a finalidade de centralizar o cadastro de pessoas físicas e jurídicas para todos os módulos. Indepentende da utilização pelos outros módulos, o módulo Person deve ser capaz de armazenas as mais diversas informações das pessoas, e deve expandir a medida que outros módulos solicitem, sem criar dependências externas nem obrigatoriedade de preenchimento de campos além do básico. Em outras palavras, não se pode transferir a obrigatoriedade de dados dos campos para dentro do módulo Person.

Pessoa (PersonVO)

O objeto principal que representa uma pessoa é o PersonVO. Este objeto carrega os atributos diretos e únicos de PersonVO, por exemplo:

• type [Obrigatório] - Enumeration que define o Tipo de pessoa cadastrada:

  PERSONAL - Indica uma pessoa física cadastradas no sistema (utilizada apenas para pessoas/civís/humanos!!!);

  CORPORATION - Indica uma pessoa jurídica, instituição, organização, etc.. Qualquer tipo de instituição representativa que não seja uma pessoa física.

• displayName [Obrigatório/Unico] - Nome como a pessoa é exibida no sistema, útil para busca ou para conter nomes que o usuário identifique ou se lembre sobre a pessoa.
• cpfCnpj [Obrigatório] - Documento da pessoa, CPF para PF e CNPJ para PJ.
• fullName - Nome completo (PF) ou Razão Social (PJ).
• companyName - Nome fantasia (PJ) ou apelido (PF).
• Outros campos descritos no JavaDoc

Instituições sem CNPJ Em alguns casos se faz necessário identificar instituições que não tem um CNPJ direto. Por exemplo, identificação do beneficiário de uma guia de pagamento de tributos estaduais ou federais, pagas por chave pix ou código de barras. Neste casos se convencionou a cadastrar a Pessoa Jurídica com algum CNPJ válido que não tenha no sistema. que não dê conflito com outras empresas, uma estratégia pode ser utilizar o CNPJ do Banco do Brasil, com os códigos de filiais em 9999, 9998, etc.. Exemplos: CNPJ da Matriz do BB: 00.000.000/0001-91 (não utilizar para evitar conflito com o Banco do Brasil. CNPJ da Filial 9999: 00.000.000/9999-62 CNPJ da Filial 9998: 00.000.000/9998-81 CNPJ da Filial 9997: 00.000.000/9997-09 CNPJ da Filial 9996: 00.000.000/9996-10 CNPJ da Filial 9995: 00.000.000/9995-39

Conta Bancária (PersonBankAccountVO)

Objeto com relação N:1 com PersonVO, responsável por armazenar informações de contas bancárias da Pessoa. Útil para realizaçãod e pagamentos, validação de recebimentos, informações e consultas cadastrais, etc.

• label - Permite que o usuário defina um rótulo identificador sobre essa conta para facilitar sua organização.
• accountType [Obrigatório] - Enumeration indicando o tipo da conta:

  CHECKING - Conta Corrente

  SAVINGS - Poupança

  INVESTMENT - Conta de Investimentos

  SALARY - Conta Salário

• bankVO [Obrigatório] - Relaciona o banco de origem da conta representada por este objeto.
• agency [Obrigatório] - Número da agência da conta.
• agencyDV - Dígito verificador da agência. Normalmente não utilizado pelos bancos, mas alguns, com o BB, utiliza.
• account [Obrigatório] - Número da conta.
• accountDV [Obrigatório] - Dígito Verificacor da conta informada. Utilizado pela maioria dos bancos, e em geral é requierido ao se realizar transferências.
• flags - Lista de 'marcadores' que podem ser definidos na conta para ajudar os módulos a tratar a conta. Cada flag pode ser definida em nenhum ou múltiplas contas simultâneamente cabe a cada módulo pesquisar as contas com as flags e decidir como tratar as multiplas marcações. As marcações existentes são:

  SALARY - Índica que é a conta pode ser utilizada para pagamento de salário.

TODO Task Em alguns lugares é previsto que haja o DV para agência, para o número da conta e um terceiro para o número da agência e conta. Esse objeto não tem essa previsão, e em algum momento podemos precisar desse terceiro DV. Acredito que seja necessário em contas da CEF. Ao implementar o campo para guardar esse terceiro DV é preciso estudar se o DV que a maioria das contas utiliza (e que já é guardado neste objeto) é o DV da conta corrente isolado ou o do conjunto agência + conta, e realizar a implementação correta mantendo a compatibilidade com o código já existente.

BIS2

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

O Person não tem uma tela específica para manipular as pessoas. O que ele oferece é um componente (PersonComponent) que pode ser acoplado nas telas que precisam incluir o cadastro de uma pessoa física ou jurídica.