ActivityNoteService

Visão Geral

O ActivityNoteService gerencia check-ins/visitas (activity notes) de usuários: listar atividades por usuário, consultar por id, registrar, atualizar, finalizar e excluir atividades. Suporta chamadas paginadas e uso de FormData-like payloads via schema validado.

Localização: services/activity-note/activity-note.service.ts

Endpoints

Método	Endpoint	Descrição
GET	/checkin/porUsuario/{userId}	Lista atividades de um usuário (paginado)
GET	/checkin/{id}	Recupera uma atividade por ID
POST	/checkin	Registra nova atividade
PUT	/checkin/{id}	Atualiza atividade existente
DELETE	/checkin/{id}	Remove atividade
PATCH	/checkin/checkout/{id}	Finaliza atividade (checkout)

Métodos

fetchRemoteByUser(userId, params)

Busca atividades do usuário com paginação.

Parâmetros

Nome	Tipo	Obrigatório
userId	string	Sim
params	{ page?: number; size?: number }	Não

Retorno: Promise<ActivityNote[]>

Exemplo

const notes = await activityNoteService.fetchRemoteByUser("usr-101", {
  page: 0,
  size: 10,
});

Erros

Status	Descrição
4xx/5xx	Lança Error: ActivityNoteService.fetchRemoteByUser failed: {userId}

---

fetchRemoteById(activityNoteId)

Recupera atividade por ID.

Retorno: Promise<ActivityNote>

Exemplo

const note = await activityNoteService.fetchRemoteById("act-001");

Erros

Status	Descrição
4xx/5xx	Lança Error: ActivityNoteService.fetchRemoteById failed: {id}

---

registerActivityNote(activityNote)

Registra nova atividade usando o schema ActivityNoteRegisterSchema.

Retorno: Promise<ActivityNote>

Exemplo

import { activityNotePayloadMock } from "@/__mocks__/activity-note.mock";
const created = await activityNoteService.registerActivityNote(
  activityNotePayloadMock,
);

---

updateActivityNote(activityNoteId, activityNote)

Atualiza atividade existente.

Retorno: Promise<ActivityNote>

Exemplo

const updated = await activityNoteService.updateActivityNote(
  "act-001",
  activityNotePayloadMock,
);

---

deleteActivityNote(activityNoteId)

Remove atividade por ID.

Retorno: Promise<void>

Exemplo

await activityNoteService.deleteActivityNote("act-001");

---

finishActivityNote(activityNoteId, finishDate)

Marca a atividade como finalizada (checkout) enviando a data de checkout.

Parâmetros

Nome	Tipo
finishDate	Required<Pick<ActivityNote, "dhCheckout">>

Retorno: Promise<ActivityNote>

Exemplo

const finished = await activityNoteService.finishActivityNote("act-001", {
  dhCheckout: new Date().toISOString(),
});

Estruturas de Dados

ActivityNoteRegisterSchema

// Schema (zod) usado para registro/atualização
type ActivityNoteRegisterSchema = {
  idCliente: string;
  idUsuario: string;
  idAtividades: string[];
  idMotivoNaoVenda?: string;
  dhCheckin?: string;
  dhCheckout?: string;
  observacao?: string;
  latitude?: number;
  longitude?: number;
  latitudeParceiro?: number;
  longitudeParceiro?: number;
};

ActivityNote

interface ActivityNote {
  id: string;
  idOrganization: string;
  organization: string;
  idCliente: string;
  cliente: string;
  idUsuario: string;
  idMotivoNaoVenda?: string;
  motivoNaoVenda?: string;
  dhCheckin?: Date;
  dhCheckout?: Date | null;
  distancia?: number | null;
  observacao?: string;
  latitude?: number | null;
  longitude?: number | null;
  latitudeParceiro?: number | null;
  longitudeParceiro?: number | null;
  atividades: any[]; // lista de ActivityType
  dhCriacao: Date;
  dhAlteracao: Date;
}

Componentes Relacionados

Componente	Descrição
buildQueryParams	Serializa os parâmetros de query para a requisição
apiWithoutAccessToken	Instância Axios sem token de acesso utilizada nas chamadas
PageResponse<T>	Tipo genérico de resposta paginada da API
activity-note.types	ActivityNote / ActivityNoteRegisterSchema

Casos de Uso

Listar atividades de um usuário:

const notes = await activityNoteService.fetchRemoteByUser("usr-101");

Registrar nova atividade (check-in):

const created = await activityNoteService.registerActivityNote(
  activityNotePayloadMock,
);

Finalizar atividade (checkout):

await activityNoteService.finishActivityNote(created.id, {
  dhCheckout: new Date().toISOString(),
});

Testes

Localização: services/activity-note/activity-note.service.test.ts

Cenário	Resultado esperado
fetchRemoteByUser status 200	Retorna pageActivityNotesResponseMock.content
fetchRemoteByUser status 4xx/5xx	Lança Error: ActivityNoteService.fetchRemoteByUser failed
fetchRemoteById status 200	Retorna ActivityNote
registerActivityNote status 2xx	Retorna ActivityNote
updateActivityNote status 2xx	Retorna ActivityNote
deleteActivityNote status 2xx	Resolve sem erro (void)
finishActivityNote status 2xx	Retorna ActivityNote com dhCheckout atualizado

Mocks

Localização: __mocks__/activity-note.mock.ts

• activityNotesResponseMock / pageActivityNotesResponseMock — listas e objeto paginado de ActivityNote
• activityNotePayloadMock — payload válido para registro/atualização

Exemplo de uso em testes:

import {
  activityNotePayloadMock,
  pageActivityNotesResponseMock,
} from "@/__mocks__/activity-note.mock";

const api: any = {
  get: jest.fn(async () => ({
    status: 200,
    data: pageActivityNotesResponseMock,
  })),
};
const service = new ActivityNoteService({ apiWithoutAccessToken: api });
const result = await service.fetchRemoteByUser("usr-101");
expect(result).toStrictEqual(pageActivityNotesResponseMock.content);