evo360-types 1.3.656 → 1.3.659

package/dist/types/evo-modules/catalog.ts

@@ -0,0 +1,131 @@
+import type { IPlatformModuleDefinition } from "./index";
+
+/**
+ * Versão do catálogo, gravada em `IModuleProvisioningRun.types_version`.
+ * Mudou capability, passo, grupo ou métrica de algum módulo ⇒ incrementar: o
+ * run antigo precisa dizer com que catálogo foi planejado.
+ */
+export const PLATFORM_MODULE_CATALOG_VERSION = "2026-10-06.1";
+
+export const PLATFORM_MODULE_TELEMEDICINE = "telemedicine";
+export const PLATFORM_MODULE_CSQ = "csq";
+
+/**
+ * Catálogo de módulos da plataforma (feat-263). É código, não Firestore: carrega
+ * comportamento (passos, grupos, métricas) e precisa de versionamento e tipos.
+ *
+ * Módulo novo = uma entrada aqui + publish. O estado por tenant continua em
+ * `tenants/{t}.modules[key]`.
+ */
+export const PLATFORM_MODULE_CATALOG: Readonly<Record<string, IPlatformModuleDefinition>> = {
+  telemedicine: {
+    key: PLATFORM_MODULE_TELEMEDICINE,
+    label: "Virtual Care (Telemedicina)",
+    description:
+      "Teleconsultas por vídeo integradas à agenda, com gravação e admissão automática.",
+    app_id: "evo-telemedicine",
+    // Defaults idênticos ao `TELEMEDICINE_DEFAULT_CAPABILITIES` da R5 (feat-160):
+    // transcrição NUNCA nasce ligada (gate documental D12).
+    capabilities: {
+      recording: { label: "Gravação", default: true },
+      transcription: { label: "Transcrição", default: false },
+      auto_admit: { label: "Admissão automática", default: true },
+    },
+    // `active/contract` sem `expires_at`: a franquia faz parte do contrato; um
+    // `expires_at` desligaria a base inteira numa data, em silêncio.
+    default_entitlement: { status: "active", source: "contract" },
+    default_for_new_tenants: true,
+    rbac_groups: ["evo-telemedicine"],
+    allowance_metrics: [{ metric: "teleconsultations_unrecorded", default_included: 5 }],
+    rollout: {
+      path: "platform/evo-telemedicine/config/rollout",
+      layout: "legacy_fields",
+      flags: {
+        create: "create_enabled",
+        join: "join_enabled",
+        recording: "recording_enabled",
+        transcription: "transcription_enabled",
+      },
+    },
+    depends_on: [],
+    provisioning: {
+      enable: ["entitlement", "rbac_group", "rbac_recompute", "contract_allowance", "rollout_check"],
+      // O grupo RBAC fica no disable (Q7): o upsell depende de `evo_telemedicine_read`.
+      disable: ["entitlement", "contract_check"],
+    },
+    legacy: { audit_collections: ["apps/evo-telemedicine/entitlement-audit"] },
+  },
+  csq: {
+    key: PLATFORM_MODULE_CSQ,
+    label: "CSQ — Qualidade do atendimento",
+    description:
+      "Avaliação automática da qualidade das conversas encerradas (laudo por ticket).",
+    app_id: "evo-csq",
+    capabilities: {},
+    default_entitlement: { status: "active", source: "manual" },
+    default_for_new_tenants: false,
+    rbac_groups: [],
+    allowance_metrics: [],
+    rollout: null,
+    depends_on: [],
+    provisioning: {
+      enable: ["entitlement"],
+      disable: ["entitlement"],
+    },
+  },
+};
+
+export function getModuleDefinition(key: string | null | undefined): IPlatformModuleDefinition | null {
+  if (!key || typeof key !== "string") return null;
+  if (!Object.prototype.hasOwnProperty.call(PLATFORM_MODULE_CATALOG, key)) return null;
+  return PLATFORM_MODULE_CATALOG[key];
+}
+
+/** Definições em ordem estável (ordem de declaração). */
+export function listModuleDefinitions(): IPlatformModuleDefinition[] {
+  const out: IPlatformModuleDefinition[] = [];
+  for (const key in PLATFORM_MODULE_CATALOG) {
+    if (Object.prototype.hasOwnProperty.call(PLATFORM_MODULE_CATALOG, key)) {
+      out.push(PLATFORM_MODULE_CATALOG[key]);
+    }
+  }
+  return out;
+}
+
+/** Chaves do catálogo em ordem de declaração. */
+export function listModuleKeys(): string[] {
+  const out: string[] = [];
+  for (const key in PLATFORM_MODULE_CATALOG) {
+    if (Object.prototype.hasOwnProperty.call(PLATFORM_MODULE_CATALOG, key)) out.push(key);
+  }
+  return out;
+}
+
+/** Capabilities default do módulo (mapa novo a cada chamada). */
+export function buildModuleDefaultCapabilities(
+  definition: IPlatformModuleDefinition,
+): Record<string, boolean | number | string> {
+  const out: Record<string, boolean | number | string> = {};
+  for (const cap in definition.capabilities) {
+    if (Object.prototype.hasOwnProperty.call(definition.capabilities, cap)) {
+      out[cap] = definition.capabilities[cap].default;
+    }
+  }
+  return out;
+}
+
+/** Módulos que tenant novo recebe habilitados. */
+export function listDefaultModulesForNewTenants(): IPlatformModuleDefinition[] {
+  return listModuleDefinitions().filter((d) => d.default_for_new_tenants);
+}
+
+/** União, sem repetição e em ordem, dos grupos RBAC dos módulos default de tenant novo. */
+export function listDefaultTenantRbacGroups(): string[] {
+  const out: string[] = [];
+  for (const def of listDefaultModulesForNewTenants()) {
+    for (const g of def.rbac_groups) {
+      if (out.indexOf(g) === -1) out.push(g);
+    }
+  }
+  return out;
+}

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

@@ -0,0 +1,227 @@
+import type { IFireDoc, IFireGlobalDoc } from "../shared";
+import type { ITenantModuleEntitlement, TenantModuleSource, TenantModuleStatus } from "../evo-tenant";
+import type { EntitlementAuditAction, IEntitlementAuditActor } from "../evo-telemedicine";
+export * from "./catalog";
+export * from "./activation";
+export declare const EVO_MODULES_APP = "evo-modules";
+export declare const MODULES_ENTITLEMENT_AUDIT_COLLECTION = "entitlement-audit";
+export declare const MODULES_PROVISIONING_COLLECTION = "provisioning";
+export declare const MODULES_ROLLOUT_PLATFORM_PATH = "platform/evo-modules/rollout";
+/** TTL do lock por tenant+módulo durante um apply. */
+export declare const MODULES_LOCK_TTL_MS: number;
+/** Regex da chave de módulo (`tenants/{t}.modules[key]`). */
+export declare const MODULE_KEY_PATTERN: RegExp;
+export type ModuleAction = "enable" | "disable" | "trial" | "override";
+export declare const ModuleActionEnum: {
+    readonly Enable: "enable";
+    readonly Disable: "disable";
+    readonly Trial: "trial";
+    readonly Override: "override";
+};
+export type ModuleStepKind = "entitlement" | "rbac_group" | "rbac_recompute" | "contract_allowance" | "contract_check" | "rollout_check";
+export declare const ModuleStepKindEnum: {
+    readonly Entitlement: "entitlement";
+    readonly RbacGroup: "rbac_group";
+    readonly RbacRecompute: "rbac_recompute";
+    readonly ContractAllowance: "contract_allowance";
+    readonly ContractCheck: "contract_check";
+    readonly RolloutCheck: "rollout_check";
+};
+export declare const MODULE_STEP_KINDS: readonly ModuleStepKind[];
+export interface IModuleRolloutDescriptor {
+    /** Path completo do doc (4 segmentos: `platform/<app>/<col>/<doc>`). */
+    path: string;
+    /**
+     * `flags_map`: doc genérico `{ flags: { [flag]: boolean }, emergency_kill }`.
+     * `legacy_fields`: doc com um campo booleano por flag (telemedicina).
+     */
+    layout: "flags_map" | "legacy_fields";
+    /** flag -> campo do doc (`legacy_fields`) ou chave em `flags` (`flags_map`). */
+    flags: Record<string, string>;
+}
+export interface IModuleCapabilityDefinition {
+    label: string;
+    default: boolean | number | string;
+}
+export interface IModuleAllowanceMetric {
+    /** Chave de `NexFinopsMetricCatalog`. */
+    metric: string;
+    /** Gravado no contrato vigente quando a chave está ausente (Q6). */
+    default_included: number;
+}
+export interface IPlatformModuleDefinition {
+    /** `MODULE_KEY_PATTERN`; é a chave em `tenants/{t}.modules`. */
+    key: string;
+    label: string;
+    description?: string;
+    /** App do Firestore onde vivem os dados do módulo (`evo-telemedicine`, `evo-csq`). */
+    app_id: string;
+    capabilities: Record<string, IModuleCapabilityDefinition>;
+    /** Status/origem gravados no `enable` de um tenant sem entitlement. */
+    default_entitlement: {
+        status: TenantModuleStatus;
+        source: TenantModuleSource;
+    };
+    /** Tenant novo nasce com o módulo (`createTenant`). */
+    default_for_new_tenants: boolean;
+    /** Grupos RBAC globais que tornam os papéis do módulo atribuíveis. */
+    rbac_groups: string[];
+    allowance_metrics: IModuleAllowanceMetric[];
+    rollout: IModuleRolloutDescriptor | null;
+    depends_on: string[];
+    provisioning: {
+        enable: ModuleStepKind[];
+        disable: ModuleStepKind[];
+    };
+    legacy?: {
+        /** Trilhas antigas (relativas a `tenants/{t}/`), lidas pelo histórico e nunca escritas. */
+        audit_collections?: string[];
+    };
+}
+export type ModuleStepStatus = "pending" | "noop" | "change" | "done" | "failed" | "blocked" | "skipped";
+export interface IModuleProvisioningStep {
+    kind: ModuleStepKind;
+    status: ModuleStepStatus;
+    summary: string;
+    before?: unknown;
+    after?: unknown;
+    error?: string | null;
+    started_at?: Date | null;
+    finished_at?: Date | null;
+}
+export type ModuleRunMode = "plan" | "apply";
+export type ModuleRunStatus = "planned" | "running" | "done" | "failed" | "blocked" | "superseded";
+export interface IModuleChangeParams {
+    /** `trial`: obrigatório. */
+    expires_at?: Date | null;
+    /** `override`: obrigatório. */
+    override_until?: Date | null;
+    /** `enable`: libera o passo `contract_allowance` quando ele vem `blocked` (Q6). */
+    allow_without_contract?: boolean;
+    /** `disable`: remove o grupo RBAC se nenhum outro módulo ativo o declara (Q7). */
+    purge_rbac?: boolean;
+    /** `disable`: grava `suspended` em vez de `cancelled`. */
+    suspend?: boolean;
+}
+export interface IModuleRunActor extends IEntitlementAuditActor {
+    login_id?: string;
+}
+export interface IModuleProvisioningRun extends IFireDoc {
+    tenant: string;
+    module: string;
+    action: ModuleAction;
+    mode: ModuleRunMode;
+    status: ModuleRunStatus;
+    params: IModuleChangeParams;
+    /** Hash estável dos passos planejados (kind+status+after). Muda ⇒ `PLAN_DRIFT`. */
+    plan_hash: string;
+    /** `PLATFORM_MODULE_CATALOG_VERSION` de quem planejou/aplicou. */
+    types_version: string;
+    steps: IModuleProvisioningStep[];
+    actor: IModuleRunActor;
+    reason: string;
+    /** Run `apply` que este retoma. */
+    resumed_from?: string | null;
+    /** Run `plan` que originou este `apply`. */
+    plan_run_id?: string | null;
+    error?: string | null;
+    finished_at?: Date | null;
+}
+/** Lock no doc `tenants/{t}/apps/evo-modules`, campo `locks.{module}`. */
+export interface IModuleLock {
+    run_id: string;
+    expires_at: Date;
+}
+export interface IModuleRolloutDoc extends IFireGlobalDoc {
+    flags: Record<string, boolean>;
+    emergency_kill: boolean;
+    updated_at: Date;
+    updated_by: string;
+}
+/** Estado de rollout normalizado (o mesmo para os dois layouts). */
+export interface IModuleRolloutState {
+    module: string;
+    path: string;
+    /** `false` ⇒ doc ausente/ilegível: tudo negado. */
+    exists: boolean;
+    flags: Record<string, boolean>;
+    emergency_kill: boolean;
+    updated_at: Date | null;
+    updated_by: string | null;
+}
+export interface IModuleEntitlementAudit extends IFireDoc {
+    module: string;
+    action: EntitlementAuditAction;
+    before?: ITenantModuleEntitlement | null;
+    after: ITenantModuleEntitlement;
+    actor: IEntitlementAuditActor;
+    reason: string;
+    occurred_at: Date;
+    correlation_id?: string;
+    run_id?: string;
+}
+export interface IModuleStepContext {
+    tenant: string;
+    module: IPlatformModuleDefinition;
+    action: ModuleAction;
+    params: IModuleChangeParams;
+    actor_user_id: string | null;
+    /** Passos anteriores do mesmo run (estado corrente). */
+    previous_steps?: IModuleProvisioningStep[];
+}
+export type ModuleStepPlanResult = Pick<IModuleProvisioningStep, "status" | "summary" | "before" | "after">;
+export type ModuleStepApplyResult = Pick<IModuleProvisioningStep, "status" | "summary" | "after">;
+export interface IModuleStepExecutor {
+    plan(ctx: IModuleStepContext): Promise<ModuleStepPlanResult>;
+    apply(ctx: IModuleStepContext): Promise<ModuleStepApplyResult>;
+}
+export interface IModuleChangeRequest {
+    tenant: string;
+    module: string;
+    action: ModuleAction;
+    params?: IModuleChangeParams;
+    reason: string;
+}
+export interface IModuleApplyRequest {
+    tenant: string;
+    /** Aplica o plano deste run (`mode: 'plan'`). Exclusivo com `resume_run_id`. */
+    plan_run_id?: string;
+    /** Retoma um run `apply` em `failed`/`blocked`. */
+    resume_run_id?: string;
+    /** Sobrepõe params do plano (só `allow_without_contract` faz sentido aqui). */
+    params?: Pick<IModuleChangeParams, "allow_without_contract">;
+}
+export interface IModuleOverviewRequest {
+    tenant: string;
+}
+export interface IModuleOverviewEntry {
+    definition: IPlatformModuleDefinition;
+    entitlement: ITenantModuleEntitlement | null;
+    active: boolean;
+    rollout: IModuleRolloutState | null;
+}
+export interface IModuleOverviewResponse {
+    ok: true;
+    tenant: string;
+    catalog_version: string;
+    modules: IModuleOverviewEntry[];
+    /** Últimos 10 runs (plan e apply), mais recentes primeiro. */
+    runs: IModuleProvisioningRun[];
+    /** Últimas 30 entradas de auditoria (caminho genérico + legados), por `occurred_at` desc. */
+    audit: IModuleEntitlementAudit[];
+}
+export interface IModulePlanResponse {
+    ok: true;
+    run: IModuleProvisioningRun;
+}
+export type ModuleApplyErrorCode = "PLAN_DRIFT" | "MODULE_LOCKED" | "RUN_NOT_FOUND" | "RUN_NOT_RESUMABLE";
+export type IModuleApplyResponse = {
+    ok: true;
+    run: IModuleProvisioningRun;
+}
+/** O estado mudou desde o plano: `plan` é o run novo (`mode: 'plan'`) para revisar. */
+ | {
+    ok: false;
+    error: "PLAN_DRIFT";
+    plan: IModuleProvisioningRun;
+};

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

@@ -0,0 +1,75 @@
+"use strict";
+// ======================================================
+// evo-modules (feat-263 — Módulos da plataforma)
+//
+// Entitlement de módulos por tenant: "este cliente tem direito ao módulo X?".
+// NÃO é feature flag: o kill switch operacional de cada módulo é o `rollout`
+// (doc de plataforma), um gate independente.
+//
+// Storage do estado continua em `tenants/{t}.modules[key]`
+// (`ITenantModuleEntitlement`, feat-160 D5). Este namespace acrescenta:
+// - o catálogo em código (`PLATFORM_MODULE_CATALOG`), que carrega
+//   comportamento (passos de provisionamento, grupos RBAC, métricas de franquia);
+// - a decisão única `isModuleActive` / `hasModuleCapability`, usada por
+//   backend, web-app e Nexus (o Flutter espelha pela fixture de paridade);
+// - os tipos do run de provisionamento, do doc de rollout genérico e da
+//   auditoria genérica.
+//
+// Firestore (por tenant):
+// - App doc (locks):     /tenants/{t}/apps/evo-modules                       campo `locks.{module}`
+// - Auditoria:           /tenants/{t}/apps/evo-modules/entitlement-audit/{id}
+// - Provisionamento:     /tenants/{t}/apps/evo-modules/provisioning/{runId}
+//
+// Plataforma (só backend):
+// - Rollout genérico:    /platform/evo-modules/rollout/{module}
+//   (a telemedicina continua em `platform/evo-telemedicine/config/rollout`,
+//   lida pelo mesmo reader via `rollout.layout = 'legacy_fields'`).
+// ======================================================
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODULE_STEP_KINDS = exports.ModuleStepKindEnum = exports.ModuleActionEnum = exports.MODULE_KEY_PATTERN = exports.MODULES_LOCK_TTL_MS = exports.MODULES_ROLLOUT_PLATFORM_PATH = exports.MODULES_PROVISIONING_COLLECTION = exports.MODULES_ENTITLEMENT_AUDIT_COLLECTION = exports.EVO_MODULES_APP = void 0;
+__exportStar(require("./catalog"), exports);
+__exportStar(require("./activation"), exports);
+exports.EVO_MODULES_APP = "evo-modules";
+exports.MODULES_ENTITLEMENT_AUDIT_COLLECTION = "entitlement-audit";
+exports.MODULES_PROVISIONING_COLLECTION = "provisioning";
+exports.MODULES_ROLLOUT_PLATFORM_PATH = "platform/evo-modules/rollout";
+/** TTL do lock por tenant+módulo durante um apply. */
+exports.MODULES_LOCK_TTL_MS = 10 * 60 * 1000;
+/** Regex da chave de módulo (`tenants/{t}.modules[key]`). */
+exports.MODULE_KEY_PATTERN = /^[a-z][a-z0-9_]{1,40}$/;
+exports.ModuleActionEnum = {
+    Enable: "enable",
+    Disable: "disable",
+    Trial: "trial",
+    Override: "override",
+};
+exports.ModuleStepKindEnum = {
+    Entitlement: "entitlement",
+    RbacGroup: "rbac_group",
+    RbacRecompute: "rbac_recompute",
+    ContractAllowance: "contract_allowance",
+    ContractCheck: "contract_check",
+    RolloutCheck: "rollout_check",
+};
+exports.MODULE_STEP_KINDS = [
+    "entitlement",
+    "rbac_group",
+    "rbac_recompute",
+    "contract_allowance",
+    "contract_check",
+    "rollout_check",
+];