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

O Person deve oferecer um componente para tratar o PersonVO e suas subclasses para as UIs suportadas pelo BISERP. Verifique a documentação de de cada UI para saber como utilizar este componente.