Entidades e relacionamentos · Atendimento

Diagrama

Relacionamentos do Atendimento

Carregando diagrama…

Ver código Mermaid

erDiagram
  PEOPLE ||--o{ SERVICE_RECORDS : atende
  ORG_UNITS ||--o{ SERVICE_RECORDS : responsavel
  SERVICE_RECORDS ||--o| REMOTE_DETAILS : modalidade
  SERVICE_RECORDS ||--o| ONSITE_DETAILS : modalidade
  SERVICE_RECORDS ||--o{ SUBJECTS : contem
  SUBJECTS ||--o| CONCLUSIONS : conclui
  SERVICE_RECORDS ||--o{ PARTICIPANTS : possui
  USERS ||--o{ PARTICIPANTS : atende
  SERVICE_RECORDS ||--o{ REQUESTS : origina
  PEOPLE ||--o{ REQUESTS : possui
  SUBJECTS o|--o{ REQUESTS : contextualiza
  USERS o|--o{ REQUESTS : responsavel
  WORK_GROUPS o|--o{ REQUESTS : responsavel
  REQUESTS ||--o{ REQUEST_ITEMS : contem
  USERS o|--o{ REQUEST_ITEMS : valida
  REQUEST_ITEMS ||--o{ PRESENTATIONS : recebe
  SERVICE_RECORDS ||--o{ PRESENTATIONS : cumpre
  DOCUMENTS o|--o{ PRESENTATIONS : comprova
  USERS ||--o{ PRESENTATIONS : recebe
  REQUESTS ||--o{ ACTIVITY_LINKS : vincula
  WORK_ITEMS ||--o{ ACTIVITY_LINKS : atividade
  USERS ||--o{ ACTIVITY_LINKS : vincula
  REQUESTS ||--o{ REQUEST_COMMANDS : deduplica
  REQUEST_ITEMS o|--o{ REQUEST_COMMANDS : comanda
  ROUTES ||--o{ OCCURRENCES : agenda
  OCCURRENCES ||--o{ STOPS : organiza
  STOPS o|--o{ ONSITE_DETAILS : localiza
  SERVICE_RECORDS ||--o{ INTERACTIONS : comunica
  USERS o|--o{ INTERACTIONS : registra
  OUTBOX o|--o{ INTERACTIONS : envia
  SERVICE_RECORDS ||--o{ INTERACTION_COMMANDS : deduplica

O Registro identifica a Pessoa atendida. Cada Registro usa o detalhe da sua modalidade; os dois detalhes não são simultaneamente obrigatórios. Solicitações preservam o cumprimento por itens e apresentações; Rotas organizam Ocorrências e Paradas; interações preservam comunicações. Os responsáveis da Rota são um array de UUIDs validado pelo serviço, não uma tabela de junção com FKs individuais.

Registro de Atendimento (`service_records`)

Coluna	Tipo	Significado
`id`	uuid	Identificador.
`person_id`	uuid, obrigatório	Pessoa atendida; FK `people`, `RESTRICT`, imutável.
`unit_id`	uuid	Unidade responsável; FK `org_units`, `RESTRICT`; não é o local físico.
`responsible_nucleus_sigla`	varchar(40)	Núcleo do alcance de leitura e escrita.
`mode`	`service_mode`	`REMOTO` ou `PRESENCIAL`; fixo.
`direction`	`service_record_direction`	`INBOUND` ou `OUTBOUND`.
`origin`	`service_record_origin`	`ESPONTANEO`, `ROTA`, `AUTOMACAO` ou `AGENDAMENTO`.
`is_appointment`	boolean	Verdadeiro implica `AGENDADO` e `AGENDAMENTO`.
`appointment_id`	uuid, nulo	Compromisso de origem, `SET NULL`, único quando presente.
`status`	`service_record_status`	Seis estados do ciclo.
`started_at` / `closed_at`	timestamptz(3), nulo	Primeiro início; encerramento/cancelamento.
`version`	integer	Controle otimista por `expectedVersion`.
`idempotency_key`	varchar(100), nulo	Idempotência da criação.

Detalhes e filhos

Entidade	Campos e função
`service_record_remote_details`	Possui `id`, `service_record_id` único com `CASCADE`, `channel` (`WHATSAPP`, `TELEFONE`, `VIDEOCONFERENCIA`, `EMAIL`, `REDE_SOCIAL`), `channel_account_id` e `external_conversation_id` opcionais sem FK.
`service_record_onsite_details`	Possui `id`, `service_record_id` único com `CASCADE`, `location`, `location_unit_id` (`SET NULL`), `route_stop_id` (`SET NULL`) e `arrived_at`.
`service_record_subjects`	Possui `id`, `service_record_id`, `purpose` (`AVULSO`, `ENTREVISTA_INAUGURAL`, `ACOMPANHAMENTO`, `SOLICITACAO`, `ORIENTACAO`, `FINANCEIRO`), referências opcionais a entrevista, processo e contrato de honorários, e timestamps.
`service_record_conclusions`	Possui `id`, `subject_id` único, `type` (`PROVIDENCIAS` ou `SEM_INTERCORRENCIA`), `note` de 1–20.000 caracteres, autor opcional e timestamps.
`service_record_participants`	É uma join table com chave composta (`service_record_id`, `user_id`); o usuário deve estar ativo e lotado no núcleo responsável.
`service_record_conclusion_templates`	Possui `id`, `title` até 255, `content` até 20.000, `active` e timestamps.

Solicitação (`service_requests`)

Preserva o pedido e seu responsável único.

Atributo	Tipo	Obrigatório	Regra
`id`	uuid	Gerado	Chave primária.
`idempotency_key`	varchar(100)	Sim	Único; repetição equivalente reapresenta a Solicitação.
`service_record_id`	uuid	Sim	Registro de origem; FK RESTRICT.
`person_id`	uuid	Derivado	Pessoa do Registro de origem; FK RESTRICT.
`subject_id`	uuid; null	Não	Assunto opcional do Registro; FK RESTRICT.
`responsible_user_id`	uuid; null	Condicional	FK users RESTRICT; exatamente um responsável entre usuário e grupo.
`responsible_group_id`	uuid; null	Condicional	FK work_groups RESTRICT; exatamente um responsável entre usuário e grupo.
`due_at`	timestamptz(3); null	Não	Prazo da Solicitação.
`canceled_at`	timestamptz(3); null	Derivado	Data do cancelamento.
`cancellation_reason`	varchar(500); null	Condicional	Motivo do cancelamento.
`version`	integer; padrão 1	Gerado	Versão da Solicitação, distinta da versão dos itens.
`created_at`	timestamptz(3)	Gerado	Data de criação.
`updated_at`	timestamptz(3)	Gerado	Data da última atualização.

Item da Solicitação (`service_request_items`)

Define um cumprimento esperado.

Atributo	Tipo	Obrigatório	Regra
`id`	uuid	Gerado	Chave primária.
`request_id`	uuid	Sim	Solicitação; FK RESTRICT.
`title`	varchar(255)	Sim	Descrição do item.
`kind`	enum	Sim	DOCUMENT, INFORMATION ou ATTENDANCE.
`status`	enum; padrão PENDING	Gerado	PENDING, RECEIVED, VALIDATING, ACCEPTED, REJECTED ou WAIVED.
`version`	integer; padrão 1	Gerado	Concorrência por item.
`resolved_at`	timestamptz(3); null	Derivado	Resolução por aceite ou dispensa.
`validated_by_user_id`	uuid; null	Derivado	Autor da avaliação; FK users RESTRICT.
`validation_note`	varchar(1000); null	Não	Observação da avaliação.
`created_at`	timestamptz(3)	Gerado	Data de criação.
`updated_at`	timestamptz(3)	Gerado	Data da última atualização.

Apresentação (`service_request_presentations`)

Preserva cada recebimento, inclusive reapresentações.

Atributo	Tipo	Obrigatório	Regra
`id`	uuid	Gerado	Chave primária.
`item_id`	uuid	Sim	Item; FK RESTRICT.
`sequence`	integer	Gerado	Sequência única por item.
`fulfillment_service_record_id`	uuid	Sim	Registro de cumprimento da mesma Pessoa; FK RESTRICT.
`document_id`	uuid; null	Condicional	Documento exigido para item DOCUMENT; FK RESTRICT.
`received_by_user_id`	uuid	Derivado	Autor do recebimento; FK users RESTRICT.
`idempotency_key`	varchar(100)	Sim	Único.
`received_at`	timestamptz(3)	Gerado	Data do recebimento.

Vínculo de atividade (`service_request_activity_links`)

Relaciona a Solicitação com uma atividade da mesma Pessoa.

Atributo	Tipo	Obrigatório	Regra
`id`	uuid	Gerado	Chave primária.
`request_id`	uuid	Sim	Solicitação; FK RESTRICT.
`activity_id`	uuid	Sim	Atividade; FK work_items RESTRICT; par com request_id único.
`linked_by_user_id`	uuid	Derivado	Autor do vínculo; FK users RESTRICT.
`created_at`	timestamptz(3)	Gerado	Data de criação.

Comando da Solicitação (`service_request_commands`)

Recibo interno de idempotência; não é um segundo cadastro de pedido.

Atributo	Tipo	Obrigatório	Regra
`id`	uuid	Gerado	Chave primária.
`request_id`	uuid	Sim	Solicitação; FK RESTRICT.
`item_id`	uuid; null	Condicional	Item alvo, quando aplicável; FK RESTRICT.
`action`	varchar(20)	Derivado	Operação executada.
`idempotency_key`	varchar(100)	Sim	Único entre comandos.
`fingerprint`	char(64)	Derivado	Assinatura do conteúdo para distinguir repetição de divergência.
`created_at`	timestamptz(3)	Gerado	Data de criação.

Rota (`service_routes`)

Configura recorrência e responsáveis.

Atributo	Tipo	Obrigatório	Regra
`id`	uuid	Gerado	Chave primária.
`name`	varchar(160)	Sim	Nome da Rota.
`responsible_nucleus_sigla`	varchar(40)	Sim	Núcleo responsável, validado pelo serviço.
`responsible_user_ids`	uuid[]	Sim	Responsáveis ativos e elegíveis; sem FK por elemento.
`frequency`	enum	Sim	daily, weekly ou monthly.
`interval`	integer; padrão 1 no banco	Sim na criação	Intervalo da recorrência, de 1 a 365.
`weekdays`	integer[]; padrão vazio	Condicional	Dias de 0 a 6; exigidos em recorrência semanal e mensal.
`week_of_month`	integer; null	Condicional	De 1 a 5; exigido na recorrência mensal.
`period`	varchar(80)	Sim	Período da visita.
`transport`	varchar(160)	Sim	Transporte.
`holiday_policy`	enum	Sim	next_business_day, previous_business_day ou skip.
`created_at`	timestamptz(3)	Gerado	Data de criação.
`updated_at`	timestamptz(3)	Gerado	Data da última atualização.

Ocorrência (`service_route_occurrences`)

Representa uma execução da Rota em uma data.

Atributo	Tipo	Obrigatório	Regra
`id`	uuid	Gerado	Chave primária.
`route_id`	uuid	Sim	Rota; FK RESTRICT.
`requested_date`	date	Sim	Data solicitada; única por Rota.
`effective_date`	date; null	Derivado	Data após calendário; única por Rota quando não nula.
`status`	enum	Gerado	planned, in_progress, completed, cancelled ou skipped.
`version`	integer; padrão 1	Gerado	Concorrência nas transições.
`started_at`	timestamptz(3); null	Derivado	Início da execução.
`ended_at`	timestamptz(3); null	Derivado	Fim da execução.
`created_at`	timestamptz(3)	Gerado	Data de criação.
`updated_at`	timestamptz(3)	Gerado	Data da última atualização.

Parada (`service_route_stops`)

Define local e ordem da visita.

Atributo	Tipo	Obrigatório	Regra
`id`	uuid	Gerado	Chave primária.
`occurrence_id`	uuid	Sim	Ocorrência; FK RESTRICT.
`position`	integer	Sim	Posição única na Ocorrência.
`location`	text	Sim	Descrição do local.
`planned_arrival_at`	timestamptz(3); null	Não	Chegada prevista.
`arrived_at`	timestamptz(3); null	Derivado	Primeira chegada.
`left_at`	timestamptz(3); null	Derivado	Primeira saída, após chegada.
`created_at`	timestamptz(3)	Gerado	Data de criação.
`updated_at`	timestamptz(3)	Gerado	Data da última atualização.

Interação (`service_record_interactions`)

Preserva comunicação manual, sincronizada ou enviada.

Atributo	Tipo	Obrigatório	Regra
`id`	uuid	Gerado	Chave primária.
`service_record_id`	uuid	Sim	Registro; FK CASCADE.
`channel`	enum	Sim	WHATSAPP, PHONE, EMAIL, VIDEO, IN_PERSON ou NOTE.
`direction`	enum	Sim	INCOMING, OUTGOING ou INTERNAL.
`delivery`	enum	Derivado	RECORDED, SYNCED, SIMULATED ou SENT.
`idempotency_key`	varchar(200)	Sim	Único dentro do Registro.
`summary`	varchar(4096); null	Condicional	Resumo da comunicação.
`external_message_id`	varchar(255); null	Não	Identificador externo; único dentro do Registro quando presente.
`outbox_entry_id`	uuid; null	Derivado	Entrada de saída; FK RESTRICT.
`actor_user_id`	uuid; null	Derivado	Autor; FK users SET NULL.
`occurred_at`	timestamptz(3)	Sim	Momento da interação.
`created_at`	timestamptz(3)	Gerado	Data de criação.

Comando da interação (`service_record_interaction_commands`)

Recibo interno de envio ou sincronização.

Atributo	Tipo	Obrigatório	Regra
`id`	uuid	Gerado	Chave primária.
`service_record_id`	uuid	Sim	Registro; FK CASCADE.
`idempotency_key`	varchar(200)	Sim	Único dentro do Registro.
`action`	varchar(20)	Derivado	Operação executada.
`fingerprint`	char(64)	Derivado	Assinatura do conteúdo do comando.
`created_at`	timestamptz(3)	Gerado	Data de criação.

Relações e cardinalidades

Relação	Cardinalidade	Obrigatória	Integridade
Registro → detalhe remoto / presencial	1 : 0..1 por modalidade	O detalhe correspondente à modalidade	FK única; CASCADE.
Registro / Pessoa → Solicitações	1 : 0..N	Sim na Solicitação	RESTRICT em ambas as FKs.
Assunto → Solicitações	1 : 0..N	Não na Solicitação	RESTRICT.
Usuário / grupo → Solicitações	1 : 0..N	Exatamente uma das duas FKs	CHECK de um responsável; RESTRICT.
Solicitação → itens	1 : 0..N no banco	Sim no item; criação exige itens	RESTRICT.
Usuário → itens avaliados	1 : 0..N	Não no item	RESTRICT.
Item → apresentações	1 : 0..N	Sim na apresentação	RESTRICT; sequência única por item.
Registro de cumprimento / usuário recebedor → apresentações	1 : 0..N	Sim na apresentação	RESTRICT.
Documento → apresentações	1 : 0..N	Condicional ao tipo DOCUMENT	FK nullable; RESTRICT.
Solicitação / atividade / usuário autor → vínculos de atividade	1 : 0..N	Sim no vínculo	RESTRICT; par Solicitação–atividade único.
Solicitação → comandos	1 : 0..N	Sim no comando	RESTRICT.
Item → comandos	1 : 0..N	Não no comando	RESTRICT.
Rota → Ocorrências	1 : 0..N	Sim na Ocorrência	RESTRICT; data solicitada única por Rota; data efetiva única quando presente.
Ocorrência → Paradas	1 : 0..N	Sim na Parada	RESTRICT; posição única por Ocorrência.
Parada → detalhes presenciais	1 : 0..N	Não no detalhe	SET NULL; vínculo não muda a modalidade.
Registro → interações / comandos de interação	1 : 0..N	Sim no filho	CASCADE.
Outbox → interações	1 : 0..N	Não na interação	RESTRICT.
Usuário → interações	1 : 0..N	Não na interação	SET NULL.

Ciclo de vida

A Solicitação nasce com itens pendentes. Cada apresentação preserva o recebimento; recusar um item permite reapresentação sem apagar as anteriores. Aceite e dispensa resolvem o item. O estado agregado e o atraso são projeções, não colunas adicionais. Cancelar preserva o pedido e seu histórico e impede novos comandos. O encerramento do Registro de origem não encerra automaticamente a Solicitação.

A Rota preserva sua configuração recorrente. Cada Ocorrência evolui de planejada para em andamento e concluída, ou é cancelada; a política de calendário pode produzir uma Ocorrência ignorada. Paradas preservam chegada e saída. Interações e recibos mantêm idempotência sem incrementar a versão do ciclo do Registro. As políticas de FK descrevem exclusão física no banco e não oferecem, por si, operações de exclusão na API.