Histórias do usuário · Pessoas

US-PESSOAS-001 · Cadastrar pessoa completa

Ator: membro de núcleo com Acesso de Núcleo ou superior.

Necessidade: cadastrar uma pessoa com contatos, endereços e documentos de identificação em uma única operação, sem cadastro parcial.

Critérios de aceitação

A API responde 201 com a pessoa e seus filhos.
name ou companyName está presente.
CPF/CNPJ é normalizado para dígitos e é único.
Os núcleos informados existem.
A API registra o evento person.created.

US-PESSOAS-002 · Cadastrar já como cliente

Ator: membro de núcleo com gestão institucional EXPINS.

Necessidade: cadastrar a pessoa já como cliente, informando origem e carteira, para que o cliente nasça vinculado à sua Carteira.

Critérios de aceitação

O cadastro com CLIENT exige originUoSigla, portfolioId e portfolioEffectiveFrom.
Sem gestão EXPINS, a API responde 403.
O vínculo de Cliente da Carteira é criado na mesma transação.

US-PESSOAS-003 · Abrir a conta de acesso junto com o cadastro

Ator: operador com Acesso Global.

Necessidade: cadastrar a pessoa e sua conta de acesso em um único passo.

Critérios de aceitação

account exige papel USER ou ASSOCIATE e pessoa física.
A API cria a identidade Appwrite na mesma transação.
E-mail já cadastrado responde 409.
Se o commit local falhar após o provisionamento, a API compensa a identidade criada.

US-PESSOAS-004 · Buscar e filtrar pessoas

Ator: qualquer usuário autenticado.

Necessidade: buscar pessoas por nome, CPF/CNPJ ou e-mail e filtrar por papel, núcleo, origem, indicação, canal de chegada e período de cadastro, encontrando rapidamente apenas o que está no seu alcance.

Critérios de aceitação

A listagem é alfabética e paginada por cursor.
Os filtros apenas estreitam o resultado; um valor desconhecido devolve página vazia.
A busca livre e o filtro oabNumber encontram pela inscrição na OAB.
Os itens da listagem vêm sem emails, documents e bankAccounts.

US-PESSOAS-005 · Ver a ficha completa

Ator: qualquer usuário autenticado.

Necessidade: ver a ficha completa da pessoa antes de atendê-la.

Critérios de aceitação

A API responde 200 com os filhos e o portfolioId vigente.
Pessoa fora do alcance responde 404.

US-PESSOAS-006 · Corrigir dados e contatos

Ator: autor do cadastro ou membro de um núcleo responsável.

Necessidade: corrigir dados da pessoa e substituir as listas de contatos, endereços e documentos, mantendo o cadastro atualizado.

Critérios de aceitação

O PATCH é parcial: apenas os campos enviados mudam.
As listas de filhos enviadas substituem a lista inteira.
A trilha registra os campos alterados.
As listas de contas bancárias e o conjunto de Representados também são substituídos por inteiro.

US-PESSOAS-007 · Corrigir origem e indicação depois do cadastro

Ator: presidência (núcleo PRES).

Necessidade: corrigir a origem e a indicação da pessoa depois do cadastro, mantendo a governança da originação.

Critérios de aceitação

Qualquer outro perfil recebe 403 ao enviar um campo de originação, mesmo com valor igual ao gravado.

US-PESSOAS-008 · Promover a cliente ou encerrar o papel de cliente

Ator: gestão institucional EXPINS.

Necessidade: conceder ou retirar o papel CLIENT, mantendo a Carteira coerente com o papel.

Critérios de aceitação

As datas de vigência seguem o dia civil.
A troca de carteira ocorre apenas pela transferência, nunca pelo PATCH.

US-PESSOAS-009 · Ver aniversariantes

Ator: qualquer usuário autenticado.

Necessidade: ver os aniversariantes do dia, ou de uma data escolhida, para o relacionamento com clientes.

Critérios de aceitação

O dia considerado é o dia civil de America/Recife.
O escopo é o mesmo da listagem.

US-PESSOAS-010 · Ver a trilha e o histórico da pessoa

Ator: qualquer usuário autenticado.

Necessidade: ver a trilha de alterações e o histórico da pessoa, para auditoria e contexto.

Critérios de aceitação

Os registros aparecem do mais recente ao mais antigo.
O histórico agrega entrevistas, processos e demais vínculos.

US-PESSOAS-011 · Registrar ou remover laço de família ou amizade

Ator: autor do cadastro ou membro de um núcleo responsável.

Necessidade: registrar e remover laços de família ou amizade, como base para o atendimento e para a verificação de conflito de interesse.

Critérios de aceitação

O laço pode ser registrado a partir de qualquer ponta.
Duplicata ou contradição responde 409.
A remoção apaga o laço das duas pontas.

US-PESSOAS-012 · Marcar documentos entregues

Ator: membro de núcleo com Acesso de Núcleo ou superior.

Necessidade: marcar os quatro itens do checklist de documentos, para acompanhar pendências sem bloquear o cadastro.

Critérios de aceitação

A marcação é um upsert idempotente.
Qualquer perfil que lê a pessoa lê o checklist.

US-PESSOAS-013 · Importar pessoas do legado

Ator: Tecnologia.

Necessidade: importar pessoas e laços do legado sem perder dados, de forma idempotente.

Critérios de aceitação

A importação é um comando de linha de comando.
Conflitos são contados, não lançados.

US-PESSOAS-014 · Cadastrar advogado associado com a Associação

Ator: gestão de Associações (EXPINS).

Necessidade: cadastrar um advogado associado abrindo a Associação e a carteira dele em uma única operação.

Critérios de aceitação

A pessoa tem papel ASSOCIATE e é física.
association informa sigla e lamarckPercentage, e opcionalmente percentage, name, effectiveFrom e effectiveTo.
A sigla é única.
A resposta traz association com portfolioId da carteira criada.

US-PESSOAS-016 · Marcar uma pessoa como parceira

Ator: membro de núcleo.

Necessidade: marcar uma pessoa como parceira e ter a carteira dela pronta.

Critérios de aceitação

O papel PARTNER cria a carteira própria.
A ficha traz ownedPortfolioId.
GET /v1/portfolios?ownerPersonId= localiza a carteira.

US-PESSOAS-017 · Registrar quem um advogado externo representa

Ator: membro de núcleo.

Necessidade: registrar quem um advogado externo representa perante o escritório.

Critérios de aceitação

Os Representados existem no catálogo /v1/represented-parties.
A pessoa recebe representedPartyIds.
A ficha traz representedParties expandido.

US-PESSOAS-018 · Guardar dados bancários e OAB

Ator: membro de núcleo.

Necessidade: guardar os dados bancários e a inscrição na OAB da pessoa.

Critérios de aceitação

A lista bankAccounts é aceita no cadastro e na edição.
oabNumber e oabUf são aceitos em par, para pessoa física ou jurídica (sociedade de advogados), conforme RN-PESSOAS-046.
O cadastro de Advogado externo, pessoa física ou jurídica, exige a inscrição na OAB.
A busca encontra a pessoa pela OAB (search e oabNumber).
A conta bancária aceita operação, observações e o tipo Benefício (RN-PESSOAS-058).

US-PESSOAS-019 · Abrir conta de acesso para um associado no cadastro

Ator: operador com Acesso Global.

Necessidade: abrir a conta de acesso de um associado junto com o cadastro.

Critérios de aceitação

account é aceito com o papel ASSOCIATE, sem exigir USER.
As demais condições de US-PESSOAS-003 se aplicam.

US-PESSOAS-020 · Informar Juiz ou Perito e acessar o cadastro rápido

Ator: usuário que informa o Juiz ou o Perito na Ficha da Pessoa.

Necessidade: informar o nome sem exigir cadastro prévio e ter acesso ao cadastro rápido quando a pessoa não estiver cadastrada.

Estado: fluxo previsto.

Critérios de aceitação

Informar o nome não obriga a cadastrar uma Pessoa.
O cadastro rápido permite vincular a matrícula do servidor localizada em fontes públicas com auxílio de IA, por busca e leitura de páginas.
Para peritos médicos, a consulta utiliza o conselho de classe nacional ou local.
O fluxo se limita aos papéis de Juiz e Perito e não altera os demais papéis.

US-PESSOAS-021 · Registrar o relacionamento com a pessoa

Ator: usuário com permissão para editar a Pessoa.

Necessidade: registrar Expectativa, Preferência, Afinidade e Atenção da pessoa.

Critérios de aceitação

O card Relacionamento lista os registros da Pessoa por tipo, com autor e data.
O registro é criado com um dos quatro tipos e um texto de até 2000 caracteres.
O registro pode ter tipo, texto e campos próprios do tipo alterados e pode ser excluído; criação, alteração e exclusão aparecem no histórico da Pessoa.
Sem permissão para editar a Pessoa, criar, alterar ou excluir é recusado (RN-PESSOAS-062).
Em implementação na API: a Preferência aceita categoria; a Atenção exige o tipo da etiqueta; a Expectativa pode apontar um processo em que a pessoa é cliente; Afinidade e Atenção aceitam detalhe (RN-PESSOAS-063 e RN-PESSOAS-064).
Em implementação na API: o histórico de cada registro mostra como ele ficou ou, na exclusão, como estava (RN-PESSOAS-065).

US-PESSOAS-022 · Registrar nota de atendimento na ficha

Ator: usuário com permissão para editar a Pessoa.

Necessidade: registrar um atendimento simplificado da pessoa, com o que foi tratado, a forma, quem iniciou, a finalidade e a satisfação dela.

Estado: em implementação na API.

Critérios de aceitação

A nota guarda texto, forma, quem iniciou, finalidade opcional, satisfação opcional, autor e data (RN-PESSOAS-066).
A forma é Presencial ou um canal remoto (WhatsApp, Telefone, Videoconferência, E-mail ou Rede social); quem iniciou é Recebido ou Realizado. Os dois são obrigatórios.
Notas registradas antes da forma e de quem iniciou continuam listadas, sem esses campos.
A ficha lista as notas da mais recente para a mais antiga a quem lê a Pessoa.
O que foi tratado é escrito no mesmo editor do relato da entrevista e aceita menções a pessoa, entrevista e processo; a menção vira link na linha do tempo.
A nota não cria um Registro de Atendimento.

Fluxos críticos

Cadastro com vínculos em uma operação

Histórias relacionadas: US-PESSOAS-001, US-PESSOAS-002, US-PESSOAS-003, US-PESSOAS-014, US-PESSOAS-016, US-PESSOAS-017, US-PESSOAS-018 e US-PESSOAS-019.

A operação valida a Pessoa e os vínculos solicitados antes de gravar o cadastro.
Na mesma transação, grava a Pessoa e seus dados associados, registra person.created e cria os vínculos aplicáveis: Cliente da Carteira, carteira própria da Pessoa Parceira, conta de acesso e Associação.
A Associação criada junto com a Pessoa recebe identidade, primeira versão, participação da própria Pessoa e Carteira vazia.
Uma falha impede a confirmação do cadastro e dos vínculos. Se ocorrer após o provisionamento da identidade Appwrite, a operação tenta remover essa identidade.

Os vínculos de conta e Associação podem ser criados posteriormente por suas operações próprias; os blocos account e association pertencem ao cadastro inicial e não à edição da Pessoa.

Alteração dos papéis de Cliente e Parceiro

Histórias relacionadas: US-PESSOAS-006, US-PESSOAS-008 e US-PESSOAS-016.

As transições de CLIENT e PARTNER são feitas em transação com bloqueio da Pessoa e detecção de alteração concorrente. A entrada no papel PARTNER cria ou reaproveita sua Carteira própria. A saída apaga essa Carteira somente quando está vazia e sem histórico; se ela já teve cliente, a saída é recusada. A transferência entre carteiras de Cliente é uma operação própria, fora da edição da Pessoa.

Relações entre pessoas com alcance distinto

História relacionada: US-PESSOAS-011.

O laço é gravado em uma forma canônica e gera evento nas duas Pessoas. Na consulta expandida, a contraparte fora do alcance de leitura do ator aparece sem nome, preservando a existência do laço sem expor sua ficha.

Importação do legado

História relacionada: US-PESSOAS-013.

A importação grava Pessoas e laços vindos do Appwrite e do Projuris sem ator humano. Os registros importados ficam com authorUserId nulo e recebem o evento person.imported; conflitos são contabilizados para continuidade da importação.

Refinamento previsto da busca no Projuris

A busca de Pessoas terá filtros avançados em Sheet, incluindo o switch Buscar no Projuris. Os resultados externos usarão o mesmo renderizador da listagem nativa, com indicador Projuris, sem uma listagem visual independente.

A seleção da origem de busca não incorpora uma Pessoa. A incorporação dependerá de comando explícito do módulo Projuris Legado. A definição de busca exclusiva no espelho ou combinada com a base nativa permanece pendente.