tychat-contracts 1.0.99 → 1.0.101

package/dist/analytics/analytics-query.dto.d.ts

@@ -22,4 +22,51 @@ export declare class AnalyticsDashboardQueryDto {
     startDate: string;
     endDate: string;
 }
+/** Resumo financeiro agregado a partir de eventos de analytics (pagamentos + faturamento). */
+export declare class AnalyticsDashboardFinancialDto {
+    revenue: number;
+    averageTicket: number;
+    pending: number;
+}
+export declare class AnalyticsDashboardTopProcedureDto {
+    name: string;
+    count: number;
+}
+/** Média de `message.sent` por hora do relógio durante o expediente configurado. */
+export declare class AnalyticsDashboardMessageHourDto {
+    hour: number;
+    averageSent: number;
+    totalSent: number;
+    openOccurrencesInPeriod: number;
+}
+export declare class AnalyticsDashboardMessagePeakDto {
+    hour: number;
+    totalSent: number;
+    averageSent: number;
+}
+/**
+ * Resposta enriquecida de `GET /analytics/dashboard` (mantém campos legados `total`, `byEventType`, `byDomain`).
+ */
+export declare class AnalyticsDashboardResponseDto {
+    appointmentsCreated: number;
+    appointmentsFinished: number;
+    proceduresScheduled: number;
+    proceduresFinished: number;
+    satisfactionAverage: number | null;
+    noShowRatePercent: number;
+    financialSummary: AnalyticsDashboardFinancialDto;
+    topProcedures: AnalyticsDashboardTopProcedureDto[];
+    messagesByClinicHour: AnalyticsDashboardMessageHourDto[];
+    messagesPeakHour: AnalyticsDashboardMessagePeakDto | null;
+    clinicTimezone: string;
+    total: number;
+    byEventType: Array<{
+        eventType: string;
+        count: number;
+    }>;
+    byDomain: Array<{
+        domain: string;
+        count: number;
+    }>;
+}
 //# sourceMappingURL=analytics-query.dto.d.ts.map

package/dist/analytics/analytics-query.dto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analytics-query.dto.d.ts","sourceRoot":"","sources":["../../src/analytics/analytics-query.dto.ts"],"names":[],"mappings":"AAYA,OAAO,EAAwB,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAEhF;;GAEG;AACH,eAAO,MAAM,kBAAkB,2CAA4C,CAAC;AAC5E,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE;;GAEG;AACH,qBAAa,uBAAuB;IAMlC,SAAS,EAAE,MAAM,CAAC;IAOlB,OAAO,EAAE,MAAM,CAAC;IAShB,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAS9B,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAO3B,IAAI,CAAC,EAAE,MAAM,CAAC;IAOd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,qBAAa,0BAA0B;IAMrC,SAAS,EAAE,MAAM,CAAC;IAOlB,OAAO,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"analytics-query.dto.d.ts","sourceRoot":"","sources":["../../src/analytics/analytics-query.dto.ts"],"names":[],"mappings":"AAYA,OAAO,EAAwB,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAEhF;;GAEG;AACH,eAAO,MAAM,kBAAkB,2CAA4C,CAAC;AAC5E,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE;;GAEG;AACH,qBAAa,uBAAuB;IAMlC,SAAS,EAAE,MAAM,CAAC;IAOlB,OAAO,EAAE,MAAM,CAAC;IAShB,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAS9B,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAO3B,IAAI,CAAC,EAAE,MAAM,CAAC;IAOd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,qBAAa,0BAA0B;IAMrC,SAAS,EAAE,MAAM,CAAC;IAOlB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8FAA8F;AAC9F,qBAAa,8BAA8B;IAKzC,OAAO,EAAE,MAAM,CAAC;IAMhB,aAAa,EAAE,MAAM,CAAC;IAMtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,iCAAiC;IAE5C,IAAI,EAAE,MAAM,CAAC;IAGb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,oFAAoF;AACpF,qBAAa,gCAAgC;IAE3C,IAAI,EAAE,MAAM,CAAC;IAMb,WAAW,EAAE,MAAM,CAAC;IAGpB,SAAS,EAAE,MAAM,CAAC;IAMlB,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED,qBAAa,gCAAgC;IAE3C,IAAI,EAAE,MAAM,CAAC;IAEE,SAAS,EAAE,MAAM,CAAC;IAElB,WAAW,EAAE,MAAM,CAAC;CACpC;AAED;;GAEG;AACH,qBAAa,6BAA6B;IAExC,mBAAmB,EAAE,MAAM,CAAC;IAG5B,oBAAoB,EAAE,MAAM,CAAC;IAM7B,mBAAmB,EAAE,MAAM,CAAC;IAK5B,kBAAkB,EAAE,MAAM,CAAC;IAO3B,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IAMnC,iBAAiB,EAAE,MAAM,CAAC;IAG1B,gBAAgB,EAAE,8BAA8B,CAAC;IAGjD,aAAa,EAAE,iCAAiC,EAAE,CAAC;IAOnD,oBAAoB,EAAE,gCAAgC,EAAE,CAAC;IAOzD,gBAAgB,EAAE,gCAAgC,GAAG,IAAI,CAAC;IAM1D,cAAc,EAAE,MAAM,CAAC;IAGvB,KAAK,EAAE,MAAM,CAAC;IAKd,WAAW,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAKzD,QAAQ,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD"}

package/dist/analytics/analytics-query.dto.js

@@ -9,7 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AnalyticsDashboardQueryDto = exports.AnalyticsReportQueryDto = exports.ANALYTICS_GROUP_BY = void 0;
+exports.AnalyticsDashboardResponseDto = exports.AnalyticsDashboardMessagePeakDto = exports.AnalyticsDashboardMessageHourDto = exports.AnalyticsDashboardTopProcedureDto = exports.AnalyticsDashboardFinancialDto = exports.AnalyticsDashboardQueryDto = exports.AnalyticsReportQueryDto = exports.ANALYTICS_GROUP_BY = void 0;
 const swagger_1 = require("@nestjs/swagger");
 const class_validator_1 = require("class-validator");
 const class_transformer_1 = require("class-transformer");
@@ -106,3 +106,186 @@ __decorate([
     (0, class_validator_1.IsISO8601)(),
     __metadata("design:type", String)
 ], AnalyticsDashboardQueryDto.prototype, "endDate", void 0);
+/** Resumo financeiro agregado a partir de eventos de analytics (pagamentos + faturamento). */
+class AnalyticsDashboardFinancialDto {
+    revenue;
+    averageTicket;
+    pending;
+}
+exports.AnalyticsDashboardFinancialDto = AnalyticsDashboardFinancialDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Receita no período: soma de `payment.payed` e `billing.invoice_paid` (valores em metadata.amount)',
+    }),
+    __metadata("design:type", Number)
+], AnalyticsDashboardFinancialDto.prototype, "revenue", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Ticket médio: revenue / número de eventos pagos (payment.payed + billing.invoice_paid); 0 se não houver pagamentos',
+    }),
+    __metadata("design:type", Number)
+], AnalyticsDashboardFinancialDto.prototype, "averageTicket", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Valor ainda em aberto no fim do período (exclusive endDate): soma de `payment.created` no intervalo sem `payment.payed` correspondente (mesmo paymentId) com occurredAt anterior a endDate; mais faturas `billing.invoice_created` PENDING/OVERDUE sem `billing.invoice_paid` (mesmo invoiceId). Baseado em eventos de analytics.',
+    }),
+    __metadata("design:type", Number)
+], AnalyticsDashboardFinancialDto.prototype, "pending", void 0);
+class AnalyticsDashboardTopProcedureDto {
+    name;
+    count;
+}
+exports.AnalyticsDashboardTopProcedureDto = AnalyticsDashboardTopProcedureDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Nome do procedimento (agendamento)' }),
+    __metadata("design:type", String)
+], AnalyticsDashboardTopProcedureDto.prototype, "name", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Quantidade de ocorrências no período' }),
+    __metadata("design:type", Number)
+], AnalyticsDashboardTopProcedureDto.prototype, "count", void 0);
+/** Média de `message.sent` por hora do relógio durante o expediente configurado. */
+class AnalyticsDashboardMessageHourDto {
+    hour;
+    averageSent;
+    totalSent;
+    openOccurrencesInPeriod;
+}
+exports.AnalyticsDashboardMessageHourDto = AnalyticsDashboardMessageHourDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Hora local (0–23) no fuso clinicTimezone' }),
+    __metadata("design:type", Number)
+], AnalyticsDashboardMessageHourDto.prototype, "hour", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Média de mensagens enviadas nessa hora: totalSent / openOccurrencesInPeriod (0 se não houve expediente nessa hora no período)',
+    }),
+    __metadata("design:type", Number)
+], AnalyticsDashboardMessageHourDto.prototype, "averageSent", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Total de eventos message.sent nessa hora local, só dentro do horário da clínica' }),
+    __metadata("design:type", Number)
+], AnalyticsDashboardMessageHourDto.prototype, "totalSent", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Quantas vezes essa hora calendário integrou o expediente (dias locais no intervalo × slots de opening_hours)',
+    }),
+    __metadata("design:type", Number)
+], AnalyticsDashboardMessageHourDto.prototype, "openOccurrencesInPeriod", void 0);
+class AnalyticsDashboardMessagePeakDto {
+    hour;
+    totalSent;
+    averageSent;
+}
+exports.AnalyticsDashboardMessagePeakDto = AnalyticsDashboardMessagePeakDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Hora local (0–23) com maior totalSent entre as horas de expediente' }),
+    __metadata("design:type", Number)
+], AnalyticsDashboardMessagePeakDto.prototype, "hour", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)(),
+    __metadata("design:type", Number)
+], AnalyticsDashboardMessagePeakDto.prototype, "totalSent", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)(),
+    __metadata("design:type", Number)
+], AnalyticsDashboardMessagePeakDto.prototype, "averageSent", void 0);
+/**
+ * Resposta enriquecida de `GET /analytics/dashboard` (mantém campos legados `total`, `byEventType`, `byDomain`).
+ */
+class AnalyticsDashboardResponseDto {
+    appointmentsCreated;
+    appointmentsFinished;
+    proceduresScheduled;
+    proceduresFinished;
+    satisfactionAverage;
+    noShowRatePercent;
+    financialSummary;
+    topProcedures;
+    messagesByClinicHour;
+    messagesPeakHour;
+    clinicTimezone;
+    total;
+    byEventType;
+    byDomain;
+}
+exports.AnalyticsDashboardResponseDto = AnalyticsDashboardResponseDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Agendamentos criados no período (`appointment.created`)' }),
+    __metadata("design:type", Number)
+], AnalyticsDashboardResponseDto.prototype, "appointmentsCreated", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Agendamentos finalizados no período (`appointment.finished`)' }),
+    __metadata("design:type", Number)
+], AnalyticsDashboardResponseDto.prototype, "appointmentsFinished", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Procedimentos agendados: soma dos itens em metadata.procedures em `appointment.created` + vínculos posteriores (`appointment.updated` com reason procedure_added)',
+    }),
+    __metadata("design:type", Number)
+], AnalyticsDashboardResponseDto.prototype, "proceduresScheduled", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Procedimentos marcados como concluídos no período (`appointment.procedure_finished`)',
+    }),
+    __metadata("design:type", Number)
+], AnalyticsDashboardResponseDto.prototype, "proceduresFinished", void 0);
+__decorate([
+    (0, swagger_1.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,
+    }),
+    __metadata("design:type", Object)
+], AnalyticsDashboardResponseDto.prototype, "satisfactionAverage", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Taxa de no-show (%): appointment.no_show / appointment.created no período (0 se não houver criações)',
+    }),
+    __metadata("design:type", Number)
+], AnalyticsDashboardResponseDto.prototype, "noShowRatePercent", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ type: AnalyticsDashboardFinancialDto }),
+    __metadata("design:type", AnalyticsDashboardFinancialDto)
+], AnalyticsDashboardResponseDto.prototype, "financialSummary", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ type: [AnalyticsDashboardTopProcedureDto], maxItems: 5 }),
+    __metadata("design:type", Array)
+], AnalyticsDashboardResponseDto.prototype, "topProcedures", void 0);
+__decorate([
+    (0, swagger_1.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],
+    }),
+    __metadata("design:type", Array)
+], AnalyticsDashboardResponseDto.prototype, "messagesByClinicHour", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Hora com maior volume de mensagens no expediente; null se não houver dados ou horário configurado',
+        nullable: true,
+        type: AnalyticsDashboardMessagePeakDto,
+    }),
+    __metadata("design:type", Object)
+], AnalyticsDashboardResponseDto.prototype, "messagesPeakHour", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Fuso IANA usado para hora local e opening_hours (env ANALYTICS_CLINIC_TIMEZONE ou America/Sao_Paulo)',
+        example: 'America/Sao_Paulo',
+    }),
+    __metadata("design:type", String)
+], AnalyticsDashboardResponseDto.prototype, "clinicTimezone", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Total de eventos de analytics no período (legado)' }),
+    __metadata("design:type", Number)
+], AnalyticsDashboardResponseDto.prototype, "total", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Contagens por eventType (legado)',
+    }),
+    __metadata("design:type", Array)
+], AnalyticsDashboardResponseDto.prototype, "byEventType", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Contagens por domínio (prefixo antes do ponto no eventType) (legado)',
+    }),
+    __metadata("design:type", Array)
+], AnalyticsDashboardResponseDto.prototype, "byDomain", void 0);

package/dist/analytics/event-analytic.enum.d.ts

@@ -2,6 +2,6 @@
  * Enum of all analytic event types emitted by microservices.
  * Each value follows the pattern: `domain.action`.
  */
-export declare const EVENT_ANALYTIC_TYPES: readonly ["patient.created", "patient.updated", "patient.deleted", "patient.status_changed", "appointment.created", "appointment.updated", "appointment.canceled", "appointment.rescheduled", "appointment.no_show", "appointment.finished", "checkin.effectued", "checkout.effectued", "message.sent", "message.received", "conversation.session_started", "conversation.session_ended", "conversation.transferred_to_human", "followup.abandonment.sent", "followup.appointment_confirmation.sent", "followup.satisfaction_booking.sent", "followup.satisfaction_finished.sent", "followup.no_show_reschedule.sent", "followup.wellness_check.sent", "followup.return_suggestion.sent", "followup.satisfaction_booking.response_received", "followup.satisfaction_finished.response_received", "followup.config_updated", "payment.created", "payment.payed", "payment.refunded", "payment.canceled", "payment.overdue", "payment_gateway.payment_created", "payment_gateway.payment_confirmed", "payment_gateway.payment_failed", "payment_gateway.payment_refunded", "payment_gateway.payment_canceled", "payment_gateway.payment_expired", "payment_gateway.webhook_received", "billing.invoice_created", "billing.invoice_paid", "ai.interaction", "ai.fallback", "auth.login", "auth.logout", "auth.password_reset", "user.created", "user.updated", "user.deleted", "notification.sent", "notification.failed", "whatsapp.connection_established", "whatsapp.connection_lost", "procedure.created", "procedure.updated", "procedure.deleted", "specialty.created", "specialty.updated", "specialty.deleted", "professional.created", "professional.updated", "professional.deleted", "configuration.updated", "storage.file_uploaded", "storage.file_deleted", "tenant.created", "tenant.updated"];
+export declare const EVENT_ANALYTIC_TYPES: readonly ["patient.created", "patient.updated", "patient.deleted", "patient.status_changed", "appointment.created", "appointment.updated", "appointment.canceled", "appointment.rescheduled", "appointment.no_show", "appointment.finished", "appointment.procedure_finished", "checkin.effectued", "checkout.effectued", "message.sent", "message.received", "conversation.session_started", "conversation.session_ended", "conversation.transferred_to_human", "followup.abandonment.sent", "followup.appointment_confirmation.sent", "followup.satisfaction_booking.sent", "followup.satisfaction_finished.sent", "followup.no_show_reschedule.sent", "followup.wellness_check.sent", "followup.return_suggestion.sent", "followup.satisfaction_booking.response_received", "followup.satisfaction_finished.response_received", "followup.config_updated", "payment.created", "payment.payed", "payment.refunded", "payment.canceled", "payment.overdue", "payment_gateway.payment_created", "payment_gateway.payment_confirmed", "payment_gateway.payment_failed", "payment_gateway.payment_refunded", "payment_gateway.payment_canceled", "payment_gateway.payment_expired", "payment_gateway.webhook_received", "billing.invoice_created", "billing.invoice_paid", "ai.interaction", "ai.fallback", "auth.login", "auth.logout", "auth.password_reset", "user.created", "user.updated", "user.deleted", "notification.sent", "notification.failed", "whatsapp.connection_established", "whatsapp.connection_lost", "procedure.created", "procedure.updated", "procedure.deleted", "specialty.created", "specialty.updated", "specialty.deleted", "professional.created", "professional.updated", "professional.deleted", "configuration.updated", "storage.file_uploaded", "storage.file_deleted", "tenant.created", "tenant.updated"];
 export type EventAnalyticType = (typeof EVENT_ANALYTIC_TYPES)[number];
 //# sourceMappingURL=event-analytic.enum.d.ts.map

package/dist/analytics/event-analytic.enum.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-analytic.enum.d.ts","sourceRoot":"","sources":["../../src/analytics/event-analytic.enum.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,oBAAoB,4sDA2GvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"event-analytic.enum.d.ts","sourceRoot":"","sources":["../../src/analytics/event-analytic.enum.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,oBAAoB,8uDA6GvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/analytics/event-analytic.enum.js

@@ -18,6 +18,8 @@ exports.EVENT_ANALYTIC_TYPES = [
     'appointment.rescheduled',
     'appointment.no_show',
     'appointment.finished',
+    /** Procedimento do agendamento marcado como concluído (add/update com finished). */
+    'appointment.procedure_finished',
     // ── Check-in / Check-out events ─────────────────────────────────
     'checkin.effectued',
     'checkout.effectued',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tychat-contracts",
-  "version": "1.0.99",
+  "version": "1.0.101",
   "description": "DTOs compartilhados com class-validator (API e microserviços)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -87,3 +87,136 @@ export class AnalyticsDashboardQueryDto {
   @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 ainda em aberto no fim do período (exclusive endDate): soma de `payment.created` no intervalo sem `payment.payed` correspondente (mesmo paymentId) com occurredAt anterior a endDate; mais faturas `billing.invoice_created` PENDING/OVERDUE sem `billing.invoice_paid` (mesmo invoiceId). Baseado em eventos de analytics.',
+  })
+  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: 'Agendamentos criados no período (`appointment.created`)' })
+  appointmentsCreated: number;
+
+  @ApiProperty({ description: 'Agendamentos finalizados no período (`appointment.finished`)' })
+  appointmentsFinished: number;
+
+  @ApiProperty({
+    description:
+      'Procedimentos agendados: soma dos itens em metadata.procedures em `appointment.created` + vínculos posteriores (`appointment.updated` com reason procedure_added)',
+  })
+  proceduresScheduled: number;
+
+  @ApiProperty({
+    description: 'Procedimentos marcados como concluídos no período (`appointment.procedure_finished`)',
+  })
+  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/event-analytic.enum.ts

@@ -16,6 +16,8 @@ export const EVENT_ANALYTIC_TYPES = [
   'appointment.rescheduled',
   'appointment.no_show',
   'appointment.finished',
+  /** Procedimento do agendamento marcado como concluído (add/update com finished). */
+  'appointment.procedure_finished',
 
   // ── Check-in / Check-out events ─────────────────────────────────
   'checkin.effectued',