evo360-types 1.3.656 → 1.3.659

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

@@ -0,0 +1,329 @@
+// ======================================================
+// 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'`).
+// ======================================================
+
+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 const EVO_MODULES_APP = "evo-modules";
+export const MODULES_ENTITLEMENT_AUDIT_COLLECTION = "entitlement-audit";
+export const MODULES_PROVISIONING_COLLECTION = "provisioning";
+export const MODULES_ROLLOUT_PLATFORM_PATH = "platform/evo-modules/rollout";
+/** TTL do lock por tenant+módulo durante um apply. */
+export const MODULES_LOCK_TTL_MS = 10 * 60 * 1000;
+
+/** Regex da chave de módulo (`tenants/{t}.modules[key]`). */
+export const MODULE_KEY_PATTERN = /^[a-z][a-z0-9_]{1,40}$/;
+
+export type ModuleAction = "enable" | "disable" | "trial" | "override";
+export const ModuleActionEnum = {
+  Enable: "enable",
+  Disable: "disable",
+  Trial: "trial",
+  Override: "override",
+} as const;
+
+export type ModuleStepKind =
+  | "entitlement"
+  | "rbac_group"
+  | "rbac_recompute"
+  | "contract_allowance"
+  | "contract_check"
+  | "rollout_check";
+export const ModuleStepKindEnum = {
+  Entitlement: "entitlement",
+  RbacGroup: "rbac_group",
+  RbacRecompute: "rbac_recompute",
+  ContractAllowance: "contract_allowance",
+  ContractCheck: "contract_check",
+  RolloutCheck: "rollout_check",
+} as const;
+export const MODULE_STEP_KINDS: readonly ModuleStepKind[] = [
+  "entitlement",
+  "rbac_group",
+  "rbac_recompute",
+  "contract_allowance",
+  "contract_check",
+  "rollout_check",
+];
+
+// ----- Catálogo
+
+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[];
+  };
+}
+
+// ----- Run de provisionamento: tenants/{t}/apps/evo-modules/provisioning/{runId}
+
+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;
+}
+
+// ----- Rollout genérico: platform/evo-modules/rollout/{module}
+
+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;
+}
+
+// ----- Auditoria genérica: tenants/{t}/apps/evo-modules/entitlement-audit/{id}
+
+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;
+}
+
+// ----- Executor de passo injetável
+//
+// Permite que um passo seja implementado fora do `@evo/model` (ex.: a franquia
+// no `@evo/nex-model`) sem dependência entre os packages: quem roda o runner
+// (functions-nexus, CLI) registra o executor.
+
+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>;
+}
+
+// ----- Callables do Nexus (`nex_tenants-*`)
+//
+// Datas atravessam o callable como ISO string.
+
+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-telemedicine/fb_collections.js

@@ -13,7 +13,7 @@ exports.TELEMEDICINE_CONFIG_TRANSCRIPTION_DOC = exports.TELEMEDICINE_CONFIG_ROLL
 // - Events:            .../teleconsultations/{id}/events/{eventId}            (append-only)
 // - Webhook events:    .../teleconsultations/{id}/webhook-events/{providerEventId} (dedup + outbox)
 // - Appointment index: /tenants/{t}/apps/evo-telemedicine/appointment-index/{calendarId}__{appointmentId}
-// - Entitlement audit: /tenants/{t}/apps/evo-telemedicine/entitlement-audit/{id}
+// - Entitlement audit: /tenants/{t}/apps/evo-telemedicine/entitlement-audit/{id}  (congelada; nova: apps/evo-modules, feat-263)
 //
 // Plataforma (só backend; rules negam leitura ao FE):
 // - Legal texts:  /platform/evo-telemedicine/legal-texts/{subject}-{locale}-{version}

package/dist/types/evo-telemedicine/fb_collections.ts

@@ -10,7 +10,7 @@
 // - Events:            .../teleconsultations/{id}/events/{eventId}            (append-only)
 // - Webhook events:    .../teleconsultations/{id}/webhook-events/{providerEventId} (dedup + outbox)
 // - Appointment index: /tenants/{t}/apps/evo-telemedicine/appointment-index/{calendarId}__{appointmentId}
-// - Entitlement audit: /tenants/{t}/apps/evo-telemedicine/entitlement-audit/{id}
+// - Entitlement audit: /tenants/{t}/apps/evo-telemedicine/entitlement-audit/{id}  (congelada; nova: apps/evo-modules, feat-263)
 //
 // Plataforma (só backend; rules negam leitura ao FE):
 // - Legal texts:  /platform/evo-telemedicine/legal-texts/{subject}-{locale}-{version}

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

@@ -1,6 +1,6 @@
 export * from "./fb_collections";
 import type { IFireDoc, IFireGlobalDoc } from "../shared";
-import type { ITenantModuleEntitlement } from "../evo-tenant";
+import type { IModuleEntitlementAudit } from "../evo-modules";
 import type { VirtualCareRecordingMode } from "../evo-med/calendar";
 export declare const EvoTelemedicinePermissions: {
     /** Ver estado e dados operacionais básicos. */
@@ -816,17 +816,13 @@ export interface IEntitlementAuditActor {
     type: "user" | "system" | "script";
     id?: string;
 }
-/** Fora do doc do tenant, como pede o data-model. `before/after` são a projeção sanitizada (sem preço/contrato). */
-export interface ITelemedicineEntitlementAudit extends IFireDoc {
-    module: string;
-    action: EntitlementAuditAction;
-    before?: ITenantModuleEntitlement | null;
-    after: ITenantModuleEntitlement;
-    actor: IEntitlementAuditActor;
-    reason: string;
-    occurred_at: Date;
-    correlation_id?: string;
-}
+/**
+ * Fora do doc do tenant, como pede o data-model. `before/after` são a projeção sanitizada (sem preço/contrato).
+ * feat-263: alias da auditoria genérica. Docs novos vão para
+ * `tenants/{t}/apps/evo-modules/entitlement-audit/{id}`; a trilha antiga em
+ * `apps/evo-telemedicine/entitlement-audit` fica congelada (só leitura).
+ */
+export type ITelemedicineEntitlementAudit = IModuleEntitlementAudit;
 export declare const TelemedicineErrorCode: {
     /** 403 — entitlement ausente/inativo (sem bypass de super admin). */
     readonly TenantModuleDisabled: "TENANT_MODULE_DISABLED";

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

@@ -1,6 +1,6 @@
 export * from "./fb_collections";
 import type { IFireDoc, IFireGlobalDoc } from "../shared";
-import type { ITenantModuleEntitlement } from "../evo-tenant";
+import type { IModuleEntitlementAudit } from "../evo-modules";
 // feat-160 F15/F16 — a política da sala é projeção do `calendar.virtual_care`:
 // o MODO de gravação é o mesmo tipo dos dois lados, de propósito.
 import type { VirtualCareRecordingMode } from "../evo-med/calendar";
@@ -930,17 +930,13 @@ export interface IEntitlementAuditActor {
   id?: string;
 }
 
-/** Fora do doc do tenant, como pede o data-model. `before/after` são a projeção sanitizada (sem preço/contrato). */
-export interface ITelemedicineEntitlementAudit extends IFireDoc {
-  module: string;
-  action: EntitlementAuditAction;
-  before?: ITenantModuleEntitlement | null;
-  after: ITenantModuleEntitlement;
-  actor: IEntitlementAuditActor;
-  reason: string;
-  occurred_at: Date;
-  correlation_id?: string;
-}
+/**
+ * Fora do doc do tenant, como pede o data-model. `before/after` são a projeção sanitizada (sem preço/contrato).
+ * feat-263: alias da auditoria genérica. Docs novos vão para
+ * `tenants/{t}/apps/evo-modules/entitlement-audit/{id}`; a trilha antiga em
+ * `apps/evo-telemedicine/entitlement-audit` fica congelada (só leitura).
+ */
+export type ITelemedicineEntitlementAudit = IModuleEntitlementAudit;
 
 // ======================================================
 // Códigos de erro (plan §4 — `{ ok: false, error: '<CODE>', message? }` com status estável)

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

@@ -58,7 +58,9 @@ export enum ITenantStatus {
 // - ausência da chave em `modules` equivale a desabilitado;
 // - `enabled=false`, `suspended`, `cancelled` ou trial expirado bloqueia usos novos;
 // - capability ausente equivale a `false`;
-// - alteração gera auditoria FORA do doc do tenant (`entitlement-audit` do módulo);
+// - alteração gera auditoria FORA do doc do tenant, no caminho genérico
+//   `tenants/{t}/apps/evo-modules/entitlement-audit/{id}` (feat-263; a trilha
+//   antiga da telemedicina em `apps/evo-telemedicine/entitlement-audit` fica só leitura);
 // - super admin NÃO ignora entitlement (D6) — exceção só via `override_until`,
 //   temporária e auditada.
 export type TenantModuleStatus = "active" | "trial" | "suspended" | "cancelled";