evo360-types 1.3.503 → 1.3.507

package/dist/types/evo-integrations/test-suite.ts

@@ -0,0 +1,376 @@
+// ======================================================
+// evo-integrations — bateria de regressão de adapters (feat-123)
+//
+// Porte do script `_regressao-adapters.cjs` para ferramenta de produto no Nexus.
+//
+// A ferramenta é APARTADA: roda por fora, chamando as APIs (`integrations_actions`,
+// `integrations_admin`, `integrations_sync_monitor`) exatamente como o script faz.
+// Quem orquestra a sequência é o FE; quem persiste o resultado é o BE.
+//
+// Este módulo é o contrato COMPARTILHADO entre os dois lados:
+//   · o FE monta a seleção a partir do catálogo de passos;
+//   · o BE valida a seleção contra o MESMO catálogo e calcula o veredito.
+//
+// O catálogo de defeitos CONHECIDOS não mora aqui — mora no backend do Nexus,
+// porque só ele calcula veredito (o FE apenas renderiza o que recebe).
+// ======================================================
+
+import type { IFireDoc } from "../shared";
+
+// Path: /platform/evo-integrations/test-runs/{run_id}
+export const TEST_RUNS_COLLECTION = "test-runs";
+// Path: /platform/evo-integrations/test-runs/{run_id}/steps/{step_id}
+export const TEST_RUN_STEPS_COLLECTION = "steps";
+
+// ======================================================
+// Suítes
+// ======================================================
+
+/**
+ * O agrupamento é derivado da DEPENDÊNCIA REAL DE ESTADO, não de estética:
+ * o `external_id` devolvido pelo create alimenta get/update/confirm/revert/cancel,
+ * e o do patient.create alimenta o round-trip e o delete.
+ */
+export type TestSuiteId =
+  | "reading" // S1 — dicionários e leitura; independentes, zero efeito colateral
+  | "appointment" // S2 — ciclo de vida; ordem estrita
+  | "sync" // S3 — depende do cancel da S2
+  | "patient" // S4 — ordem estrita; opcional
+  | "cleanup"; // Z  — limpeza; selecionável (D11)
+
+export interface ITestSuiteMeta {
+  id: TestSuiteId;
+  label: string;
+  /** Ordem estrita = o passo N depende do estado produzido pelo N-1. */
+  ordered: boolean;
+  description: string;
+}
+
+export const TEST_SUITES: readonly ITestSuiteMeta[] = [
+  {
+    id: "reading",
+    label: "Dicionários e leitura",
+    ordered: false,
+    description:
+      "Capabilities de consulta. Nenhuma escreve — pode rodar sozinha com efeito colateral zero.",
+  },
+  {
+    id: "appointment",
+    label: "Ciclo de vida do agendamento",
+    ordered: true,
+    description:
+      "create → get → update → confirm → revert_confirm → cancel. Cada passo depende do external_id do create.",
+  },
+  {
+    id: "sync",
+    label: "Sync não ressuscita",
+    ordered: true,
+    description:
+      "Força o sync de 1 dia e confere que o agendamento cancelado NÃO volta. Exige o cancel da suíte anterior.",
+  },
+  {
+    id: "patient",
+    label: "Paciente",
+    ordered: true,
+    description:
+      "create → round-trip (get+update) → delete. O create nunca foi exercitado por nenhuma rodada do script.",
+  },
+  {
+    id: "cleanup",
+    label: "Varredura de resíduo",
+    ordered: false,
+    description:
+      "Lê a agenda EXTERNA e cancela o que tiver o marcador. Selecionável — quem roda é o dev de integrações, que responde pelo que escolhe.",
+  },
+] as const;
+
+// ======================================================
+// Passos
+// ======================================================
+
+export type TestStepId =
+  // S1
+  | "caps.list"
+  | "ui.config"
+  | "procedure.list"
+  | "status.list"
+  | "dicts.extra"
+  | "patient.list"
+  | "patient.get"
+  | "appointment.list"
+  // S2
+  | "appointment.create"
+  | "appointment.get"
+  | "appointment.update"
+  | "appointment.confirm"
+  | "appointment.revert_confirm"
+  | "appointment.cancel"
+  // S3
+  | "sync.force"
+  // S4
+  | "patient.create"
+  | "patient.roundtrip"
+  | "patient.delete"
+  // Z
+  | "residue.sweep";
+
+export interface ITestStepMeta {
+  id: TestStepId;
+  suite: TestSuiteId;
+  label: string;
+  /**
+   * `true` = o passo ESCREVE no PMS de produção.
+   *
+   * Usado em dois lugares: para o modo somente-leitura e para classificar o custo
+   * de REPETIR um passo — repetir leitura é livre, repetir escrita duplica efeito.
+   */
+  writes: boolean;
+  /** Passos que precisam ter passado antes. Vazio = pode rodar sozinho. */
+  dependsOn: readonly TestStepId[];
+  /** Capability invocada, quando houver. Nem todo passo tem uma. */
+  capability?: string;
+}
+
+/**
+ * Ordem do array = ordem de execução. Não é 1:1 com capability:
+ *   · `residue.sweep` não invoca capability nenhuma (varre a agenda externa);
+ *   · `sync.force` chama `integrations_sync_monitor`, não uma capability;
+ *   · `appointment.list` aparece em dois passos (leitura e varredura);
+ *   · `patient.roundtrip` combina `patient.get` + `patient.update`.
+ */
+export const TEST_STEPS: readonly ITestStepMeta[] = [
+  // ── S1 — leitura ────────────────────────────────────────────────────────────
+  { id: "caps.list", suite: "reading", label: "capabilities", writes: false, dependsOn: [] },
+  { id: "ui.config", suite: "reading", label: "ui-config", writes: false, dependsOn: [] },
+  { id: "procedure.list", suite: "reading", label: "procedure.list", writes: false, dependsOn: [], capability: "appointment.procedure.list" },
+  { id: "status.list", suite: "reading", label: "status.list", writes: false, dependsOn: [], capability: "appointment.status.list" },
+  { id: "dicts.extra", suite: "reading", label: "dicionários extra", writes: false, dependsOn: [] },
+  { id: "patient.list", suite: "reading", label: "patient.list", writes: false, dependsOn: [], capability: "patient.list" },
+  { id: "patient.get", suite: "reading", label: "patient.get", writes: false, dependsOn: [], capability: "patient.get" },
+  { id: "appointment.list", suite: "reading", label: "appointment.list", writes: false, dependsOn: [], capability: "appointment.list" },
+
+  // ── S2 — ciclo de vida ──────────────────────────────────────────────────────
+  { id: "appointment.create", suite: "appointment", label: "create", writes: true, dependsOn: [], capability: "appointment.create" },
+  { id: "appointment.get", suite: "appointment", label: "get", writes: false, dependsOn: ["appointment.create"], capability: "appointment.get" },
+  { id: "appointment.update", suite: "appointment", label: "update", writes: true, dependsOn: ["appointment.create"], capability: "appointment.update" },
+  { id: "appointment.confirm", suite: "appointment", label: "confirm", writes: true, dependsOn: ["appointment.create"], capability: "appointment.confirm" },
+  { id: "appointment.revert_confirm", suite: "appointment", label: "revert_confirm", writes: true, dependsOn: ["appointment.confirm"], capability: "appointment.revert_confirm" },
+  { id: "appointment.cancel", suite: "appointment", label: "cancel", writes: true, dependsOn: ["appointment.create"], capability: "appointment.cancel" },
+
+  // ── S3 — sync ───────────────────────────────────────────────────────────────
+  { id: "sync.force", suite: "sync", label: "sync (1 dia)", writes: true, dependsOn: ["appointment.cancel"] },
+
+  // ── S4 — paciente ───────────────────────────────────────────────────────────
+  { id: "patient.create", suite: "patient", label: "patient.create", writes: true, dependsOn: [], capability: "patient.create" },
+  { id: "patient.roundtrip", suite: "patient", label: "round-trip (get+update)", writes: true, dependsOn: [], capability: "patient.update" },
+  { id: "patient.delete", suite: "patient", label: "patient.delete", writes: true, dependsOn: ["patient.create"], capability: "patient.delete" },
+
+  // ── Z — limpeza ─────────────────────────────────────────────────────────────
+  { id: "residue.sweep", suite: "cleanup", label: "varredura de resíduo", writes: true, dependsOn: [] },
+] as const;
+
+/**
+ * Suíte padrão (D10) — a LINHA DE BASE COMPARÁVEL: todos os passos.
+ *
+ * Só uma corrida com exatamente esta seleção é comparável com a anterior. Sem isso
+ * o output principal da ferramenta ("nenhum defeito novo") seria infalsificável:
+ * bastaria desmarcar o passo que falha.
+ *
+ * Atenção: a seleção não basta. `comparable` também exige `target.create_patient`
+ * ligado — senão `patient.create`/`patient.delete` são pulados e a cobertura real
+ * fica menor que a nominal. Quem decide isso é o backend, em `computeComparable`.
+ */
+export const STANDARD_SUITE_STEP_IDS: readonly TestStepId[] = TEST_STEPS.map(
+  (s) => s.id,
+);
+
+export const READ_ONLY_STEP_IDS: readonly TestStepId[] = TEST_STEPS.filter(
+  (s) => !s.writes,
+).map((s) => s.id);
+
+// ======================================================
+// Checks
+// ======================================================
+
+export type TestCheckStatus = "pass" | "fail" | "skipped";
+
+export interface ITestCheck {
+  /**
+   * Id ESTÁVEL no formato `<step_id>:<slug>` — ex. `appointment.update:sem_divergencia`.
+   *
+   * É a chave que o catálogo de conhecidos referencia. O script antigo casava por
+   * REGEX no texto do label, o que quebrava nos dois sentidos: mudar a redação
+   * descatalogava um defeito em silêncio, e um regex largo engolia defeito novo de
+   * outra causa. Por isso o id vem antes do texto — o label pode ser reescrito à
+   * vontade.
+   */
+  id: string;
+  label: string;
+  status: TestCheckStatus;
+  detail?: string;
+}
+
+// ======================================================
+// Passo executado
+// ======================================================
+
+export type TestStepStatus =
+  | "pending"
+  | "running"
+  | "pass"
+  | "known" // falhou, mas casa com defeito catalogado — não reprova a corrida
+  | "fail" // defeito NOVO
+  | "skipped"
+  | "error";
+
+export interface ITestSchemaValidation {
+  ok: boolean;
+  errors?: Array<{ path: (string | number)[]; message: string; code?: string }>;
+}
+
+/**
+ * O wire — o que o BACKEND mandou para o n8n, lido de
+ * `integrations_sync_monitor GET /calls?run_id=`.
+ *
+ * É a camada que interessa a quem mantém os workflows: a resposta da action mostra
+ * o que a UI mandou, não o que saiu na linha. `DocumentReference` vivo no payload
+ * (a classe de bug que derrubou produção no revert_confirm) só aparece aqui.
+ */
+export interface ITestStepWire {
+  request_json?: string;
+  response_json?: string;
+  n8n_execution_id?: string | null;
+  n8n_workflow_id?: string | null;
+  workflow_url?: string;
+  http_status?: number | null;
+  timed_out?: boolean | null;
+  error_message?: string | null;
+  request_truncated?: boolean | null;
+  response_truncated?: boolean | null;
+}
+
+export interface ITestRunStep extends IFireDoc {
+  step_id: TestStepId;
+  suite: TestSuiteId;
+  order: number;
+  status: TestStepStatus;
+  started_at?: unknown;
+  finished_at?: unknown;
+  duration_ms?: number;
+
+  /** Camada 1 — o que a UI mandou para `integrations_actions` e o que voltou. */
+  layer1?: { request?: unknown; response?: unknown };
+
+  /** Correlação com o wire: `transport_metadata.run_id` da resposta da action. */
+  n8n_run_id?: string | null;
+
+  /** Camada 2 — o que o BE mandou para o n8n. */
+  wire?: ITestStepWire | null;
+
+  schema_validation?: {
+    request?: ITestSchemaValidation;
+    response?: ITestSchemaValidation;
+  } | null;
+
+  checks: ITestCheck[];
+
+  /** Preenchido quando `status === 'known'`: qual defeito catalogado casou. */
+  known_defects?: Array<{ check_id: string; description: string; ref: string }>;
+
+  error?: string | null;
+}
+
+// ======================================================
+// Corrida
+// ======================================================
+
+export type TestRunStatus = "running" | "finished" | "abandoned";
+
+/** Dados do paciente novo, quando o usuário liga a criação (D3). */
+export interface ITestNewPatient {
+  first_name: string;
+  last_name?: string;
+  mobile_phone?: string;
+  email?: string;
+  social_id?: string;
+  birth_date?: string;
+}
+
+export interface ITestRunTarget {
+  /** Paciente de teste JÁ EXISTENTE, usado na leitura e no agendamento. */
+  patient_id: string;
+  /** Só quando `create_patient` está ligado. */
+  new_patient?: ITestNewPatient | null;
+  create_patient: boolean;
+  /** `YYYY-MM-DD`. Recomendado no passado — é aviso, não trava (D2). */
+  slot_date: string;
+  /** `HH:MM`. */
+  slot_time: string;
+  /** Dia povoado para o `appointment.list`; sem isso usa `slot_date`. */
+  list_date?: string | null;
+}
+
+/**
+ * Diagnóstico de segurança — AVISO, não trava (D2).
+ *
+ * Os dois avisos têm gravidade diferente e a UI precisa refletir isso: data futura
+ * só ativa as varreduras D-2/D-0, que dependem de janela; gatilho de evento ligado
+ * dispara na hora do create.
+ */
+export interface ITestRunPreflight {
+  slot_in_past: boolean;
+  /** Quais dos gatilhos de evento estão ligados na agenda-alvo. */
+  triggers_enabled: string[];
+  /**
+   * `notification_config.configs` vazio.
+   *
+   * Distinguir de "desligado" importa: nada dispara nos dois casos, mas aqui é por
+   * AUSÊNCIA DE CONFIGURAÇÃO, não por decisão de alguém.
+   */
+  notification_config_empty: boolean;
+  evaluated_at?: unknown;
+}
+
+/** O que a corrida criou no PMS — permite enumerar resíduo quando o `Z` é desmarcado (D11). */
+export interface ITestRunInventory {
+  appointment_external_ids: string[];
+  patient_external_id?: string | null;
+}
+
+export interface ITestRunVerdict {
+  ok: number;
+  known: number;
+  new_defects: number;
+}
+
+export interface ITestRun extends IFireDoc {
+  adapter_id: string;
+  tenant: string;
+  calendar_id: string;
+
+  target: ITestRunTarget;
+
+  selection: {
+    preset: "standard" | "read-only" | "custom";
+    step_ids: TestStepId[];
+  };
+
+  /** Quantos passos da suíte padrão esta corrida cobriu. */
+  coverage: { ran: number; total: number };
+  /** `true` só quando a seleção é exatamente a suíte padrão (D10). */
+  comparable: boolean;
+
+  preflight: ITestRunPreflight;
+  inventory: ITestRunInventory;
+  verdict: ITestRunVerdict;
+
+  status: TestRunStatus;
+
+  /**
+   * Dono da corrida. Quem orquestra é o FE, então duas abas conduzindo a mesma
+   * corrida escreveriam na mesma agenda de produção em paralelo — outro usuário
+   * abre em modo leitura até assumir explicitamente.
+   */
+  created_by: string;
+  finished_at?: unknown;
+}

package/dist/types/evo-task/index.d.ts

@@ -58,6 +58,7 @@ export declare const TaskAutoHandlerEnum: {
     readonly AppointmentConfirmation: "appointment_confirmation";
     readonly AppointmentPostConsultation: "appointment_post_consultation";
     readonly IntegrationsSyncRun: "evo-integrations.sync-run";
+    readonly LeadFormCapture: "lead_form_capture";
     readonly CampaignMaterialize: "campaign.materialize";
     readonly CampaignDispatchBatch: "campaign.dispatch_batch";
 };

package/dist/types/evo-task/index.js

@@ -117,6 +117,12 @@ exports.TaskAutoHandlerEnum = {
     // types/evo-integrations). Permite que o `/force` roteie pelo task-runner e
     // herde retry/backoff/DLQ, em vez de montar a mensagem PubSub na mão.
     IntegrationsSyncRun: "evo-integrations.sync-run",
+    // feat-121: captação de lead por FORMULÁRIO (site/landing). Resolve ou cria o lead
+    // pelo telefone, aplica o pipe que vier no payload (origem/qualificação/tags/campanha)
+    // e inicia a conversa no WhatsApp conforme o `mode` (`contato` | `agenda_demo`).
+    // Tópico do executor: `lead_form_capture.execute_requests` (functions-notifications).
+    // Espelhado à mão em `zTaskAutoHandlerSchema` — sem lá, o POST /tasks estoura ZodError.
+    LeadFormCapture: "lead_form_capture",
     // feat-081 F2: handlers do modulo de campanhas (padrao pontilhado da feat-078 —
     // `resolveHandlerTopic` monta `campaign.materialize.execute_requests`, topico que
     // a CF `campaign_materialize` ja escuta desde a F1, e

package/dist/types/evo-task/index.ts

@@ -128,6 +128,12 @@ export const TaskAutoHandlerEnum = {
   // types/evo-integrations). Permite que o `/force` roteie pelo task-runner e
   // herde retry/backoff/DLQ, em vez de montar a mensagem PubSub na mão.
   IntegrationsSyncRun: "evo-integrations.sync-run",
+  // feat-121: captação de lead por FORMULÁRIO (site/landing). Resolve ou cria o lead
+  // pelo telefone, aplica o pipe que vier no payload (origem/qualificação/tags/campanha)
+  // e inicia a conversa no WhatsApp conforme o `mode` (`contato` | `agenda_demo`).
+  // Tópico do executor: `lead_form_capture.execute_requests` (functions-notifications).
+  // Espelhado à mão em `zTaskAutoHandlerSchema` — sem lá, o POST /tasks estoura ZodError.
+  LeadFormCapture: "lead_form_capture",
   // feat-081 F2: handlers do modulo de campanhas (padrao pontilhado da feat-078 —
   // `resolveHandlerTopic` monta `campaign.materialize.execute_requests`, topico que
   // a CF `campaign_materialize` ja escuta desde a F1, e

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evo360-types",
-  "version": "1.3.503",
+  "version": "1.3.507",
   "description": "HREVO360 Shared Types",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",