evo360-types 1.3.634 → 1.3.637

package/dist/types/shared/external-links.ts

@@ -47,11 +47,129 @@ export const ExternalOwnerSystemEnum = {
 export type ExternalOwnerSystem =
   (typeof ExternalOwnerSystemEnum)[keyof typeof ExternalOwnerSystemEnum];
 
+/**
+ * feat-193 — natureza do vínculo lead/paciente (`crm_lead` <-> `med_patient`,
+ * `med_patient` <-> `med_patient`, `crm_lead` <-> `crm_lead`).
+ *
+ * `identity` = mesma pessoa; `representation` = "fala/agenda/paga por". Vínculo
+ * inferido nasce `representation`: é a afirmação mais fraca e sempre verdadeira.
+ * Só `identity` CONFIRMADA grava `patient.lead_id`, e há no máximo uma por paciente.
+ */
+export const ExternalLinkKindEnum = {
+  Identity: "identity",
+  Representation: "representation",
+} as const;
+
+export type ExternalLinkKind =
+  (typeof ExternalLinkKindEnum)[keyof typeof ExternalLinkKindEnum];
+
+/**
+ * feat-193 — ÚNICA fonte de verdade do estado do vínculo (não existe campo
+ * `confirmed`). Automação só cria `suggested` ou re-observa; confirmar, rejeitar,
+ * promover e rebaixar são ações humanas. `rejected` fica em `externalLinks` como
+ * lápide e sai de `externalLinkKeys`.
+ */
+export const ExternalLinkStatusEnum = {
+  Suggested: "suggested",
+  Confirmed: "confirmed",
+  Rejected: "rejected",
+} as const;
+
+export type ExternalLinkStatus =
+  (typeof ExternalLinkStatusEnum)[keyof typeof ExternalLinkStatusEnum];
+
+/** feat-193 — origem de quem criou/observou/confirmou o vínculo. */
+export const ExternalLinkSourceEnum = {
+  UiAppointment: "ui_appointment",
+  UiManual: "ui_manual",
+  UiFamily: "ui_family",
+  SyncInferred: "sync_inferred",
+  ReminderInferred: "reminder_inferred",
+  SendInferred: "send_inferred",
+  LeadAutocreate: "lead_autocreate",
+  Inherited: "inherited",
+  Merge: "merge",
+  /** Aresta sintetizada a partir de um `patient.lead_id` sem `crm_lead:*`. */
+  Legacy: "legacy",
+} as const;
+
+export type ExternalLinkSource =
+  (typeof ExternalLinkSourceEnum)[keyof typeof ExternalLinkSourceEnum];
+
+/**
+ * feat-193 — par de relação (chave neutra de gênero). O rótulo exibido vem do
+ * dicionário `link-relations`; o inverso de cada papel é tabela de código.
+ */
+export const LinkRelationPairEnum = {
+  ParentChild: "parent_child",
+  Spouse: "spouse",
+  GuardianDependent: "guardian_dependent",
+  Family: "family",
+  CompanyEmployee: "company_employee",
+  ThirdPartyCompany: "third_party_company",
+  Other: "other",
+} as const;
+
+export type LinkRelationPair =
+  (typeof LinkRelationPairEnum)[keyof typeof LinkRelationPairEnum];
+
+export const LinkRelationRoleEnum = {
+  Parent: "parent",
+  Child: "child",
+  Spouse: "spouse",
+  Guardian: "guardian",
+  Dependent: "dependent",
+  Family: "family",
+  Company: "company",
+  Employee: "employee",
+  ThirdParty: "third_party",
+  Represented: "represented",
+  Other: "other",
+} as const;
+
+export type LinkRelationRole =
+  (typeof LinkRelationRoleEnum)[keyof typeof LinkRelationRoleEnum];
+
+/**
+ * feat-193 — relação qualificada. `other_role` é o papel do objeto APONTADO em
+ * relação a quem guarda o link: no paciente B filho do lead A, o link para A
+ * carrega `{ pair: 'parent_child', other_role: 'parent' }`; no lead A, o link
+ * para B carrega `{ pair: 'parent_child', other_role: 'child' }`.
+ */
+export interface IExternalLinkRelation {
+  pair: LinkRelationPair;
+  other_role: LinkRelationRole;
+}
+
 export interface IExternalLink {
   type: ExternalObjectType;
   id: string;
   label?: string;
   ref?: FirestoreDocumentReference;
+  // ----- feat-193: contrato do vínculo lead/paciente. Todos opcionais: só os
+  // pares `crm_lead`/`med_patient` gravados pelo serviço de vínculo os carregam.
+  // Link desse par SEM `status` é legado (feat-095): o serviço o normaliza para
+  // `suggested` com `created_source: 'legacy'` na primeira vez que tocar o doc.
+  kind?: ExternalLinkKind;
+  relation?: IExternalLinkRelation | null;
+  status?: ExternalLinkStatus;
+  /**
+   * sha256(evidence_type|e164_completo|a_type:a_id|b_type:b_id|normalizer_version).
+   * Hash, sem PII. Uma rejeição só bloqueia a re-inferência da MESMA evidência.
+   */
+  evidence_fingerprint?: string | null;
+  created_source?: ExternalLinkSource;
+  created_by?: FirestoreDocumentReference | null;
+  created_at?: Date | null;
+  /** Última automação que reviu a evidência (nunca muda `status`/`kind`). */
+  last_observed_source?: ExternalLinkSource | null;
+  last_observed_at?: Date | null;
+  confirmed_source?: ExternalLinkSource | null;
+  confirmed_by?: FirestoreDocumentReference | null;
+  confirmed_at?: Date | null;
+  rejected_by?: FirestoreDocumentReference | null;
+  rejected_at?: Date | null;
+  rejection_reason?: string | null;
   /**
    * feat-125 — sistema dono do objeto quando ele NÃO vive no tenant.
    *

package/package.json

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