Histórias do usuário · Atendimento

O operador autorizado cadastra, consulta e edita o atendimento e define os assuntos. O atendente realiza o atendimento, registra as conclusões e encerra. São atores do fluxo, sem vinculação a cargos ou novas permissões na API.

US-ATENDIMENTO-001 · Registrar atendimento

Ator: operador autorizado.

Necessidade: Como operador autorizado, quero registrar um atendimento para uma Pessoa, informando unidade, núcleo, modalidade, direção, origem, assuntos e participantes, para que o contato tenha um registro consultável e controlado.

Critérios de aceitação:

personId é obrigatório
modalidade exige exatamente um detalhe remoto ou presencial
cada registro tem ao menos um assunto
participantes são usuários ativos lotados no núcleo
registro agendado nasce em AGENDADO
a criação aceita idempotencyKey.

US-ATENDIMENTO-002 · Acompanhar o ciclo

Ator: usuário autorizado, conforme a etapa do fluxo.

Necessidade: Como usuário autorizado, conforme a etapa do fluxo, quero avançar o atendimento por comandos versionados, para registrar chegada, início, revisão, encerramento ou cancelamento sem sobrescrever alterações concorrentes.

Critérios de aceitação:

cada comando informa expectedVersion
versão divergente retorna conflito
startedAt é gravado no primeiro início
encerramento exige conclusão de todos os assuntos e pode partir de qualquer estado não terminal
estados terminais não aceitam novos comandos.

US-ATENDIMENTO-003 · Definir os assuntos

Ator: operador autorizado.

Necessidade: Como operador autorizado, quero definir os assuntos que serão tratados, para que o atendente registre posteriormente o resultado de cada um.

Critérios de aceitação:

assuntos aceitam as finalidades previstas
referências respeitam a Pessoa do atendimento
definir os assuntos na criação não exige preencher suas conclusões.

US-ATENDIMENTO-004 · Consultar e editar no alcance permitido

Ator: operador autorizado, o mesmo ator do cadastro.

Necessidade: Como operador autorizado, inclusive quando sou quem cadastra o atendimento, quero listar, consultar e editar os registros dentro do meu alcance efetivo, para acompanhar e corrigir os dados permitidos sem precisar assumir outro ator.

Critérios de aceitação:

registro inexistente e registro fora do alcance têm resposta uniforme
perda de legibilidade impede leitura
filtros da listagem são combináveis e paginados por cursor
quem pode criar também pode ler e editar no alcance permitido
edição respeita a versão e os estados terminais.

US-ATENDIMENTO-005 · Distribuir o atendimento

Ator: liderança do núcleo.

Necessidade: Como liderança do núcleo, quero adicionar, encerrar ou transferir participantes, para manter o atendente responsável atualizado.

Critérios de aceitação:

participante deve estar ativo e lotado no núcleo
transferência remove a participação anterior e insere a nova na mesma operação
a join table não duplica o par registro/usuário.

US-ATENDIMENTO-006 · Reutilizar conclusões

Ator: liderança do núcleo.

Necessidade: Como liderança do núcleo, quero criar, consultar, editar e desativar Modelos de Conclusão, para acelerar o preenchimento de notas sem alterar o histórico já gravado.

Critérios de aceitação:

título tem até 255 caracteres, conteúdo até 20.000 e active controla disponibilidade
a nota da conclusão é sempre uma cópia do texto usado.

US-ATENDIMENTO-007 · Registrar conclusões dos assuntos

Ator: atendente.

Necessidade: Como atendente, quero registrar a conclusão de cada assunto definido no cadastro, para documentar o resultado do atendimento que realizei, mesmo quando outra pessoa abriu o registro.

Critérios de aceitação:

cada assunto tem uma conclusão com tipo e nota de 1 a 20.000 caracteres
o atendente preenche as conclusões
a autoria da conclusão identifica quem a registra
pode-se usar o texto de um Modelo de Conclusão sem criar vínculo com ele
a operação respeita a versão do atendimento.

US-ATENDIMENTO-008 · Concluir o atendimento

Ator: atendente.

Necessidade: Como atendente, quero conferir as conclusões e encerrar o atendimento, com revisão quando necessária, para finalizar o contato com todos os assuntos documentados.

Critérios de aceitação:

encerramento aceita qualquer estado não terminal, com conclusões pendentes no mesmo comando e preservação das já existentes
assunto sem conclusão impede o encerramento
versão divergente gera conflito
após o encerramento o registro fica em ENCERRADO, com data de encerramento, e não aceita novos comandos.

Fluxos críticos

Do cadastro ao encerramento

Histórias relacionadas: US-ATENDIMENTO-001, US-ATENDIMENTO-002, US-ATENDIMENTO-003, US-ATENDIMENTO-007 e US-ATENDIMENTO-008.

O operador autorizado cadastra o atendimento, seus assuntos e participantes. O registro agendado entra em AGENDADO; o não agendado, em EM_ESPERA. A repetição da mesma idempotencyKey devolve o registro criado.
O comando de chegada move AGENDADO para EM_ESPERA. O início move AGENDADO ou EM_ESPERA para EM_ATENDIMENTO.
O atendente registra a conclusão de cada assunto, com tipo, nota e autoria. Salvar uma conclusão não encerra o atendimento. Uma conclusão existente é atualizada no mesmo assunto.
O comando de revisão move EM_ATENDIMENTO para EM_REVISAO. O encerramento exige uma conclusão para cada assunto e move qualquer estado não terminal para ENCERRADO, registrando a data de encerramento. As etapas intermediárias podem ser puladas, sem gerar eventos de início ou revisão.

Cada alteração usa a versão esperada. Um conflito de versão exige recarregar o atendimento; estado ou conclusão inválidos impedem a transição, e o registro permanece sem encerramento. O operador e o atendente representam responsabilidades distintas no fluxo, sem implicar cargos ou permissões adicionais da API.

Transferência de participante

História relacionada: US-ATENDIMENTO-005.

A liderança do núcleo informa o participante de destino e, opcionalmente, o participante de origem. A operação valida atividade e lotação e encerra a participação anterior ao registrar a nova na mesma alteração versionada.

Relações

As histórias de cadastro, consulta e edição se relacionam à RN-ATENDIMENTO-010. As histórias de conclusão US-ATENDIMENTO-007 e US-ATENDIMENTO-008 se relacionam às regras RN-ATENDIMENTO-005, RN-ATENDIMENTO-007 e RN-ATENDIMENTO-010.

US-ATENDIMENTO-009 · Criar e acompanhar Solicitações

Ator: operador autorizado.

Necessidade: Organizar os itens pedidos à Pessoa durante o atendimento e acompanhar seu cumprimento.

Critérios de aceitação:

A criação exige Registro gravável e ao menos um item com título e tipo DOCUMENT, INFORMATION ou ATTENDANCE.
A Pessoa é herdada do Registro; um assunto opcional pertence a esse Registro e deve ser legível.
Exatamente um usuário ou grupo responde pela Solicitação. O usuário precisa estar ativo e ter alcance sobre o núcleo; o grupo precisa estar habilitado.
Repetir a chave de criação com o mesmo conteúdo retorna a Solicitação existente; conteúdo divergente gera conflito.
Lista, detalhe e itens respeitam a leitura do Registro de origem; paginação usa cursor.

US-ATENDIMENTO-010 · Receber e avaliar itens

Ator: usuário autorizado a ler o Registro de origem.

Necessidade: Registrar apresentações, avaliar o conteúdo recebido e resolver cada item sem apagar as entregas anteriores.

Critérios de aceitação:

O recebimento exige atendimento de cumprimento gravável da mesma Pessoa; item documental exige documento válido no dossiê dessa Pessoa.
Item pendente ou recusado pode ser recebido. Cada recebimento cria uma apresentação com sequência crescente.
Item recebido pode ir para validação, ser aceito ou recusado; item em validação pode ser aceito ou recusado.
A dispensa resolve um item ainda não aceito ou dispensado.
Comandos de item usam a versão do item e chave de idempotência. Versão antiga, transição incompatível ou replay divergente geram conflito.
O Registro de origem pode estar encerrado; o atendimento de cumprimento continua sujeito à sua própria gravabilidade.
A situação agregada muda para COMPLETED quando todos os itens estão aceitos ou dispensados.

US-ATENDIMENTO-011 · Cancelar Solicitação e vincular atividade

Ator: usuário autorizado a ler o Registro de origem.

Necessidade: Cancelar uma Solicitação com justificativa ou associar uma atividade da mesma Pessoa.

Critérios de aceitação:

Cancelamento e vínculo usam a versão da Solicitação e uma chave de idempotência.
Cancelar registra instante e motivo, torna a situação CANCELED e impede novos comandos de item ou vínculo.
A atividade deve ser legível e pertencer à mesma Pessoa; o par Solicitação/atividade não se duplica.
Apresentações ou atividades fora do alcance do leitor são omitidas da projeção.

US-ATENDIMENTO-012 · Configurar Rotas

Ator: liderança autorizada do núcleo.

Necessidade: Definir responsáveis, recorrência e condições de execução de uma Rota.

Critérios de aceitação:

A Rota exige nome, núcleo válido, ao menos um responsável ativo com alcance, frequência, intervalo, período, transporte e política de calendário.
Recorrência semanal ou mensal exige dias da semana; mensal também exige a semana do mês.
Criação e edição exigem perfil mínimo acesso-de-nucleo, liderança e alcance; mudar o núcleo exige liderança e alcance no destino.
Leituras respeitam o alcance por núcleo e usam cursor nas coleções.

US-ATENDIMENTO-013 · Executar Ocorrências e Paradas

Ator: executor autorizado da Rota.

Necessidade: Executar a Rota em uma data, registrar visitas e relacionar os atendimentos presenciais realizados.

Critérios de aceitação:

A data solicitada respeita a recorrência. Repetir a mesma Rota/data devolve a Ocorrência existente.
A política de calendário define a data efetiva ou produz uma Ocorrência skipped.
A transição usa a versão da Ocorrência; início parte de planned, conclusão exige in_progress e estados terminais recusam novas transições, ressalvado o replay imediato do mesmo comando.
Uma Parada tem posição única na Ocorrência; repetir posição e conteúdo devolve a Parada, e conteúdo divergente gera conflito.
Chegada e saída exigem Ocorrência em andamento; saída exige chegada anterior. Repetir a marcação preserva o instante.
O vínculo exige atendimento presencial gravável e Ocorrência aberta; um atendimento já ligado a outra Parada gera conflito.
O operador operacional-restrito só executa Rota da qual é responsável, além de precisar de alcance.

US-ATENDIMENTO-014 · Registrar e consultar Interações

Ator: usuário autorizado do Registro.

Necessidade: Manter o histórico de contatos já ocorridos, sem produzir envio externo.

Critérios de aceitação:

Registro manual aceita PHONE, EMAIL, VIDEO, IN_PERSON ou NOTE, direção, resumo e instante.
A gravação exige Registro gravável e retorna entrega RECORDED com autoria; não altera sua versão de ciclo.
A mesma chave e conteúdo não criam duplicidade; conteúdo divergente gera conflito.
A leitura exige Registro legível e ordena as interações por instante e identificador, com cursor.

US-ATENDIMENTO-015 · Enviar e sincronizar Interações externas

Ator: usuário autorizado; na sincronização, também sistema cliente com escopo próprio e dono ativo.

Necessidade: Associar ao atendimento o resultado de operações externas e as mensagens selecionadas para importação.

Critérios de aceitação:

Envio distingue texto, modelo e transferência; exige os campos correspondentes ao tipo e Registro gravável.
Resultado simulado recebe SIMULATED; envio confirmado recebe SENT. Uma saída falha não deve aparecer como interação enviada.
Sincronização recebe até 100 identificadores e elimina duplicados; uma mensagem precisa ter instante externo válido.
Lista vazia produz synced-empty com lista vazia e recibo idempotente.
Token de sistema exige service-record-interactions:sync; a operação também verifica o dono ativo e seu alcance.
Cada comando preserva sua chave e impressão do conteúdo para recusar replay divergente.

Fluxos críticos complementares

Solicitação atendida em contato posterior

Histórias relacionadas: US-ATENDIMENTO-009, US-ATENDIMENTO-010 e US-ATENDIMENTO-008.

O operador cria a Solicitação no Registro de origem e define os itens e o responsável.
O atendente conclui os assuntos e encerra o Registro de origem. A Solicitação mantém seus itens pendentes.
Em outro Registro gravável da mesma Pessoa, o usuário registra a apresentação de um item, informando documento quando exigido.
O usuário aceita, recusa ou encaminha o item para validação. Uma recusa permite nova apresentação sem apagar a anterior.
Quando todos os itens estiverem aceitos ou dispensados, a Solicitação fica concluída.

Visita em Rota

Histórias relacionadas: US-ATENDIMENTO-012 e US-ATENDIMENTO-013.

A liderança configura a Rota e os responsáveis.
O executor cria a Ocorrência para uma data da recorrência; o calendário determina a execução ou o salto.
O executor cadastra Paradas, inicia a Ocorrência e registra chegada e saída.
Atendimentos presenciais graváveis podem ser vinculados às Paradas enquanto a Ocorrência estiver aberta.
O executor conclui ou cancela a Ocorrência. Um conflito exige leitura atual antes de decidir novo comando.

Registro e comunicação externa

Histórias relacionadas: US-ATENDIMENTO-014 e US-ATENDIMENTO-015.

O usuário escolhe entre registrar um contato ocorrido, enviar uma operação externa ou sincronizar mensagens selecionadas. Cada opção tem contrato próprio. O histórico conserva o resultado real da operação e não apresenta simulação ou falha como transmissão confirmada.