tychat-contracts 1.6.21 → 1.6.24

package/src/analytics/analytics-query.dto.ts

@@ -1,222 +1,222 @@
-import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import {
-  IsIn,
-  IsISO8601,
-  IsNotEmpty,
-  IsOptional,
-  IsPositive,
-  IsString,
-  MaxLength,
-  Min,
-} from 'class-validator';
-import { Type } from 'class-transformer';
-import { EVENT_ANALYTIC_TYPES, EventAnalyticType } from './event-analytic.enum';
-
-/**
- * Grouping granularity for time-series report data.
- */
-export const ANALYTICS_GROUP_BY = ['hour', 'day', 'week', 'month'] as const;
-export type AnalyticsGroupBy = (typeof ANALYTICS_GROUP_BY)[number];
-
-/**
- * Query DTO used to request analytics reports.
- */
-export class AnalyticsReportQueryDto {
-  @ApiProperty({
-    description: 'Start of the reporting period (inclusive)',
-    example: '2026-03-01T00:00:00.000Z',
-  })
-  @IsISO8601()
-  startDate: string;
-
-  @ApiProperty({
-    description: 'End of the reporting period (exclusive)',
-    example: '2026-04-01T00:00:00.000Z',
-  })
-  @IsISO8601()
-  endDate: string;
-
-  @ApiPropertyOptional({
-    description: 'Filter by event type',
-    enum: EVENT_ANALYTIC_TYPES,
-    example: 'patient.created',
-  })
-  @IsOptional()
-  @IsIn([...EVENT_ANALYTIC_TYPES])
-  eventType?: EventAnalyticType;
-
-  @ApiPropertyOptional({
-    description: 'Group results by time granularity',
-    enum: ANALYTICS_GROUP_BY,
-    example: 'day',
-  })
-  @IsOptional()
-  @IsIn([...ANALYTICS_GROUP_BY])
-  groupBy?: AnalyticsGroupBy;
-
-  @ApiPropertyOptional({ description: 'Page number (starts at 1)', example: 1 })
-  @IsOptional()
-  @Type(() => Number)
-  @IsPositive()
-  @Min(1)
-  page?: number;
-
-  @ApiPropertyOptional({ description: 'Records per page', example: 20 })
-  @IsOptional()
-  @Type(() => Number)
-  @IsPositive()
-  @Min(1)
-  limit?: number;
-}
-
-/**
- * Query DTO for the dashboard summary endpoint.
- */
-export class AnalyticsDashboardQueryDto {
-  @ApiProperty({
-    description: 'Start of the reporting period (inclusive)',
-    example: '2026-03-01T00:00:00.000Z',
-  })
-  @IsISO8601()
-  startDate: string;
-
-  @ApiProperty({
-    description: 'End of the reporting period (exclusive)',
-    example: '2026-04-01T00:00:00.000Z',
-  })
-  @IsISO8601()
-  endDate: string;
-}
-
-/** Resumo financeiro agregado a partir de eventos de analytics (pagamentos + faturamento). */
-export class AnalyticsDashboardFinancialDto {
-  @ApiProperty({
-    description:
-      'Receita no período: soma de `payment.payed` e `billing.invoice_paid` (valores em metadata.amount)',
-  })
-  revenue: number;
-
-  @ApiProperty({
-    description:
-      'Ticket médio: revenue / número de eventos pagos (payment.payed + billing.invoice_paid); 0 se não houver pagamentos',
-  })
-  averageTicket: number;
-
-  @ApiProperty({
-    description:
-      'Valor total de procedimentos dos agendamentos ainda pendentes (status pending/processing/sended) no período: soma de `appointment_procedures.value` via JOIN com `appointments`.',
-  })
-  pending: number;
-}
-
-export class AnalyticsDashboardTopProcedureDto {
-  @ApiProperty({ description: 'Nome do procedimento (agendamento)' })
-  name: string;
-
-  @ApiProperty({ description: 'Quantidade de ocorrências no período' })
-  count: number;
-}
-
-/** Média de `message.sent` por hora do relógio durante o expediente configurado. */
-export class AnalyticsDashboardMessageHourDto {
-  @ApiProperty({ description: 'Hora local (0–23) no fuso clinicTimezone' })
-  hour: number;
-
-  @ApiProperty({
-    description:
-      'Média de mensagens enviadas nessa hora: totalSent / openOccurrencesInPeriod (0 se não houve expediente nessa hora no período)',
-  })
-  averageSent: number;
-
-  @ApiProperty({ description: 'Total de eventos message.sent nessa hora local, só dentro do horário da clínica' })
-  totalSent: number;
-
-  @ApiProperty({
-    description:
-      'Quantas vezes essa hora calendário integrou o expediente (dias locais no intervalo × slots de opening_hours)',
-  })
-  openOccurrencesInPeriod: number;
-}
-
-export class AnalyticsDashboardMessagePeakDto {
-  @ApiProperty({ description: 'Hora local (0–23) com maior totalSent entre as horas de expediente' })
-  hour: number;
-
-  @ApiProperty() totalSent: number;
-
-  @ApiProperty() averageSent: number;
-}
-
-/**
- * Resposta enriquecida de `GET /analytics/dashboard` (mantém campos legados `total`, `byEventType`, `byDomain`).
- */
-export class AnalyticsDashboardResponseDto {
-  @ApiProperty({ description: 'Total de agendamentos no período (direto da tabela `appointments` filtrado por `date`)' })
-  appointmentsCreated: number;
-
-  @ApiProperty({ description: 'Agendamentos com status `finished` no período (direto da tabela `appointments`)' })
-  appointmentsFinished: number;
-
-  @ApiProperty({
-    description:
-      'Total de procedimentos vinculados a agendamentos no período (direto da tabela `appointment_procedures` via JOIN com `appointments.date`)',
-  })
-  proceduresScheduled: number;
-
-  @ApiProperty({
-    description: 'Procedimentos com `finished = true` vinculados a agendamentos no período (direto da tabela `appointment_procedures`)',
-  })
-  proceduresFinished: number;
-
-  @ApiProperty({
-    description:
-      'Média das notas 1–5 em respostas de satisfação (followup booking + pós-atendimento); null se não houver respostas',
-    nullable: true,
-  })
-  satisfactionAverage: number | null;
-
-  @ApiProperty({
-    description:
-      'Taxa de no-show (%): appointment.no_show / appointment.created no período (0 se não houver criações)',
-  })
-  noShowRatePercent: number;
-
-  @ApiProperty({ type: AnalyticsDashboardFinancialDto })
-  financialSummary: AnalyticsDashboardFinancialDto;
-
-  @ApiProperty({ type: [AnalyticsDashboardTopProcedureDto], maxItems: 5 })
-  topProcedures: AnalyticsDashboardTopProcedureDto[];
-
-  @ApiProperty({
-    description:
-      'Pico / distribuição de mensagens no horário da clínica: médias por hora local (só `message.sent` dentro de opening_hours). Ordenado por hora crescente. Vazio se não houver opening_hours.',
-    type: [AnalyticsDashboardMessageHourDto],
-  })
-  messagesByClinicHour: AnalyticsDashboardMessageHourDto[];
-
-  @ApiProperty({
-    description: 'Hora com maior volume de mensagens no expediente; null se não houver dados ou horário configurado',
-    nullable: true,
-    type: AnalyticsDashboardMessagePeakDto,
-  })
-  messagesPeakHour: AnalyticsDashboardMessagePeakDto | null;
-
-  @ApiProperty({
-    description: 'Fuso IANA usado para hora local e opening_hours (env ANALYTICS_CLINIC_TIMEZONE ou America/Sao_Paulo)',
-    example: 'America/Sao_Paulo',
-  })
-  clinicTimezone: string;
-
-  @ApiProperty({ description: 'Total de eventos de analytics no período (legado)' })
-  total: number;
-
-  @ApiProperty({
-    description: 'Contagens por eventType (legado)',
-  })
-  byEventType: Array<{ eventType: string; count: number }>;
-
-  @ApiProperty({
-    description: 'Contagens por domínio (prefixo antes do ponto no eventType) (legado)',
-  })
-  byDomain: Array<{ domain: string; count: number }>;
-}
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import {
+  IsIn,
+  IsISO8601,
+  IsNotEmpty,
+  IsOptional,
+  IsPositive,
+  IsString,
+  MaxLength,
+  Min,
+} from 'class-validator';
+import { Type } from 'class-transformer';
+import { EVENT_ANALYTIC_TYPES, EventAnalyticType } from './event-analytic.enum';
+
+/**
+ * Grouping granularity for time-series report data.
+ */
+export const ANALYTICS_GROUP_BY = ['hour', 'day', 'week', 'month'] as const;
+export type AnalyticsGroupBy = (typeof ANALYTICS_GROUP_BY)[number];
+
+/**
+ * Query DTO used to request analytics reports.
+ */
+export class AnalyticsReportQueryDto {
+  @ApiProperty({
+    description: 'Start of the reporting period (inclusive)',
+    example: '2026-03-01T00:00:00.000Z',
+  })
+  @IsISO8601()
+  startDate: string;
+
+  @ApiProperty({
+    description: 'End of the reporting period (exclusive)',
+    example: '2026-04-01T00:00:00.000Z',
+  })
+  @IsISO8601()
+  endDate: string;
+
+  @ApiPropertyOptional({
+    description: 'Filter by event type',
+    enum: EVENT_ANALYTIC_TYPES,
+    example: 'patient.created',
+  })
+  @IsOptional()
+  @IsIn([...EVENT_ANALYTIC_TYPES])
+  eventType?: EventAnalyticType;
+
+  @ApiPropertyOptional({
+    description: 'Group results by time granularity',
+    enum: ANALYTICS_GROUP_BY,
+    example: 'day',
+  })
+  @IsOptional()
+  @IsIn([...ANALYTICS_GROUP_BY])
+  groupBy?: AnalyticsGroupBy;
+
+  @ApiPropertyOptional({ description: 'Page number (starts at 1)', example: 1 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsPositive()
+  @Min(1)
+  page?: number;
+
+  @ApiPropertyOptional({ description: 'Records per page', example: 20 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsPositive()
+  @Min(1)
+  limit?: number;
+}
+
+/**
+ * Query DTO for the dashboard summary endpoint.
+ */
+export class AnalyticsDashboardQueryDto {
+  @ApiProperty({
+    description: 'Start of the reporting period (inclusive)',
+    example: '2026-03-01T00:00:00.000Z',
+  })
+  @IsISO8601()
+  startDate: string;
+
+  @ApiProperty({
+    description: 'End of the reporting period (exclusive)',
+    example: '2026-04-01T00:00:00.000Z',
+  })
+  @IsISO8601()
+  endDate: string;
+}
+
+/** Resumo financeiro agregado a partir de eventos de analytics (pagamentos + faturamento). */
+export class AnalyticsDashboardFinancialDto {
+  @ApiProperty({
+    description:
+      'Receita no período: soma de `payment.payed` e `billing.invoice_paid` (valores em metadata.amount)',
+  })
+  revenue: number;
+
+  @ApiProperty({
+    description:
+      'Ticket médio: revenue / número de eventos pagos (payment.payed + billing.invoice_paid); 0 se não houver pagamentos',
+  })
+  averageTicket: number;
+
+  @ApiProperty({
+    description:
+      'Valor total de procedimentos dos agendamentos ainda pendentes (status pending/processing/sended) no período: soma de `appointment_procedures.value` via JOIN com `appointments`.',
+  })
+  pending: number;
+}
+
+export class AnalyticsDashboardTopProcedureDto {
+  @ApiProperty({ description: 'Nome do procedimento (agendamento)' })
+  name: string;
+
+  @ApiProperty({ description: 'Quantidade de ocorrências no período' })
+  count: number;
+}
+
+/** Média de `message.sent` por hora do relógio durante o expediente configurado. */
+export class AnalyticsDashboardMessageHourDto {
+  @ApiProperty({ description: 'Hora local (0–23) no fuso clinicTimezone' })
+  hour: number;
+
+  @ApiProperty({
+    description:
+      'Média de mensagens enviadas nessa hora: totalSent / openOccurrencesInPeriod (0 se não houve expediente nessa hora no período)',
+  })
+  averageSent: number;
+
+  @ApiProperty({ description: 'Total de eventos message.sent nessa hora local, só dentro do horário da clínica' })
+  totalSent: number;
+
+  @ApiProperty({
+    description:
+      'Quantas vezes essa hora calendário integrou o expediente (dias locais no intervalo × slots de opening_hours)',
+  })
+  openOccurrencesInPeriod: number;
+}
+
+export class AnalyticsDashboardMessagePeakDto {
+  @ApiProperty({ description: 'Hora local (0–23) com maior totalSent entre as horas de expediente' })
+  hour: number;
+
+  @ApiProperty() totalSent: number;
+
+  @ApiProperty() averageSent: number;
+}
+
+/**
+ * Resposta enriquecida de `GET /analytics/dashboard` (mantém campos legados `total`, `byEventType`, `byDomain`).
+ */
+export class AnalyticsDashboardResponseDto {
+  @ApiProperty({ description: 'Total de agendamentos no período (direto da tabela `appointments` filtrado por `date`)' })
+  appointmentsCreated: number;
+
+  @ApiProperty({ description: 'Agendamentos com status `finished` no período (direto da tabela `appointments`)' })
+  appointmentsFinished: number;
+
+  @ApiProperty({
+    description:
+      'Total de procedimentos vinculados a agendamentos no período (direto da tabela `appointment_procedures` via JOIN com `appointments.date`)',
+  })
+  proceduresScheduled: number;
+
+  @ApiProperty({
+    description: 'Procedimentos com `finished = true` vinculados a agendamentos no período (direto da tabela `appointment_procedures`)',
+  })
+  proceduresFinished: number;
+
+  @ApiProperty({
+    description:
+      'Média das notas 1–5 em respostas de satisfação (followup booking + pós-atendimento); null se não houver respostas',
+    nullable: true,
+  })
+  satisfactionAverage: number | null;
+
+  @ApiProperty({
+    description:
+      'Taxa de no-show (%): appointment.no_show / appointment.created no período (0 se não houver criações)',
+  })
+  noShowRatePercent: number;
+
+  @ApiProperty({ type: AnalyticsDashboardFinancialDto })
+  financialSummary: AnalyticsDashboardFinancialDto;
+
+  @ApiProperty({ type: [AnalyticsDashboardTopProcedureDto], maxItems: 5 })
+  topProcedures: AnalyticsDashboardTopProcedureDto[];
+
+  @ApiProperty({
+    description:
+      'Pico / distribuição de mensagens no horário da clínica: médias por hora local (só `message.sent` dentro de opening_hours). Ordenado por hora crescente. Vazio se não houver opening_hours.',
+    type: [AnalyticsDashboardMessageHourDto],
+  })
+  messagesByClinicHour: AnalyticsDashboardMessageHourDto[];
+
+  @ApiProperty({
+    description: 'Hora com maior volume de mensagens no expediente; null se não houver dados ou horário configurado',
+    nullable: true,
+    type: AnalyticsDashboardMessagePeakDto,
+  })
+  messagesPeakHour: AnalyticsDashboardMessagePeakDto | null;
+
+  @ApiProperty({
+    description: 'Fuso IANA usado para hora local e opening_hours (env ANALYTICS_CLINIC_TIMEZONE ou America/Sao_Paulo)',
+    example: 'America/Sao_Paulo',
+  })
+  clinicTimezone: string;
+
+  @ApiProperty({ description: 'Total de eventos de analytics no período (legado)' })
+  total: number;
+
+  @ApiProperty({
+    description: 'Contagens por eventType (legado)',
+  })
+  byEventType: Array<{ eventType: string; count: number }>;
+
+  @ApiProperty({
+    description: 'Contagens por domínio (prefixo antes do ponto no eventType) (legado)',
+  })
+  byDomain: Array<{ domain: string; count: number }>;
+}

package/src/analytics/create-analytic-event.dto.ts

@@ -1,85 +1,85 @@
-import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import {
-  IsIn,
-  IsISO8601,
-  IsNotEmpty,
-  IsObject,
-  IsOptional,
-  IsString,
-  IsUUID,
-  MaxLength,
-  MinLength,
-} from 'class-validator';
-import { EVENT_ANALYTIC_TYPES, EventAnalyticType } from './event-analytic.enum';
-
-/**
- * Payload that every microservice must send to the analytics topic.
- */
-export class CreateAnalyticEventDto {
-  @ApiProperty({
-    description: 'Unique event ID for idempotent processing',
-    example: 'f3f50ecb-fb71-4d4b-a0dd-910ef6e3fd0a',
-  })
-  @IsUUID()
-  eventId: string;
-
-  @ApiProperty({
-    description: 'Tenant slug that originated the event',
-    example: 'homolog',
-  })
-  @IsString()
-  @IsNotEmpty()
-  @MinLength(1)
-  @MaxLength(255)
-  tenant: string;
-
-  @ApiProperty({
-    description: 'Type of analytic event',
-    enum: EVENT_ANALYTIC_TYPES,
-    example: 'patient.created',
-  })
-  @IsIn([...EVENT_ANALYTIC_TYPES])
-  eventType: EventAnalyticType;
-
-  @ApiPropertyOptional({
-    description: 'ID of the entity related to this event (patient, appointment, etc.)',
-    example: '3c593727-4505-495a-a054-c052acb4cf19',
-  })
-  @IsOptional()
-  @IsString()
-  @MaxLength(255)
-  entityId?: string;
-
-  @ApiPropertyOptional({
-    description: 'Name of the source microservice',
-    example: 'tychat-patient-service',
-  })
-  @IsOptional()
-  @IsString()
-  @MaxLength(255)
-  source?: string;
-
-  @ApiPropertyOptional({
-    description: 'Optional user ID who triggered the action',
-    example: 'a1b2c3d4-e5f6-4789-abcd-ef0123456789',
-  })
-  @IsOptional()
-  @IsString()
-  @MaxLength(255)
-  userId?: string;
-
-  @ApiPropertyOptional({
-    description: 'Additional metadata for the event (flexible JSON)',
-    example: { previousStatus: 'pending', newStatus: 'finished' },
-  })
-  @IsOptional()
-  @IsObject()
-  metadata?: Record<string, unknown>;
-
-  @ApiProperty({
-    description: 'ISO 8601 timestamp when the event occurred',
-    example: '2026-04-02T12:00:00.000Z',
-  })
-  @IsISO8601()
-  occurredAt: string;
-}
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import {
+  IsIn,
+  IsISO8601,
+  IsNotEmpty,
+  IsObject,
+  IsOptional,
+  IsString,
+  IsUUID,
+  MaxLength,
+  MinLength,
+} from 'class-validator';
+import { EVENT_ANALYTIC_TYPES, EventAnalyticType } from './event-analytic.enum';
+
+/**
+ * Payload that every microservice must send to the analytics topic.
+ */
+export class CreateAnalyticEventDto {
+  @ApiProperty({
+    description: 'Unique event ID for idempotent processing',
+    example: 'f3f50ecb-fb71-4d4b-a0dd-910ef6e3fd0a',
+  })
+  @IsUUID()
+  eventId: string;
+
+  @ApiProperty({
+    description: 'Tenant slug that originated the event',
+    example: 'homolog',
+  })
+  @IsString()
+  @IsNotEmpty()
+  @MinLength(1)
+  @MaxLength(255)
+  tenant: string;
+
+  @ApiProperty({
+    description: 'Type of analytic event',
+    enum: EVENT_ANALYTIC_TYPES,
+    example: 'patient.created',
+  })
+  @IsIn([...EVENT_ANALYTIC_TYPES])
+  eventType: EventAnalyticType;
+
+  @ApiPropertyOptional({
+    description: 'ID of the entity related to this event (patient, appointment, etc.)',
+    example: '3c593727-4505-495a-a054-c052acb4cf19',
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  entityId?: string;
+
+  @ApiPropertyOptional({
+    description: 'Name of the source microservice',
+    example: 'tychat-patient-service',
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  source?: string;
+
+  @ApiPropertyOptional({
+    description: 'Optional user ID who triggered the action',
+    example: 'a1b2c3d4-e5f6-4789-abcd-ef0123456789',
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  userId?: string;
+
+  @ApiPropertyOptional({
+    description: 'Additional metadata for the event (flexible JSON)',
+    example: { previousStatus: 'pending', newStatus: 'finished' },
+  })
+  @IsOptional()
+  @IsObject()
+  metadata?: Record<string, unknown>;
+
+  @ApiProperty({
+    description: 'ISO 8601 timestamp when the event occurred',
+    example: '2026-04-02T12:00:00.000Z',
+  })
+  @IsISO8601()
+  occurredAt: string;
+}