@muni-sanfer/types-gestor-documental 0.0.1-beta.5 → 0.0.1-beta.50

package/src/contracts/indicators.contract.ts

@@ -0,0 +1,80 @@
+import {
+  type IndicatorsFileEntity,
+  type ManagementIndicatorsEntity,
+  type QualityMetricSettingResponseEntity,
+  type QualityReportEntity,
+  type ServiceOutageRemoveResponseEntity,
+  type ServiceOutageResponseEntity,
+} from '../entities';
+import { type QualityMetricKey, type ServiceOutageKind } from '../base/entities';
+
+/** Patrones NATS de `indicators`: indicadores de gestión y Plan de Mejora Continua (DS 11/2023). */
+export const IndicatorsPatterns = {
+  getManagement: 'gestorDocumental.indicators.getManagement',
+  getQuality: 'gestorDocumental.indicators.getQuality',
+  export: 'gestorDocumental.indicators.export',
+  updateQualityMetric: 'gestorDocumental.indicators.updateQualityMetric',
+  getOutages: 'gestorDocumental.indicators.getOutages',
+  createOutage: 'gestorDocumental.indicators.createOutage',
+  updateOutage: 'gestorDocumental.indicators.updateOutage',
+  removeOutage: 'gestorDocumental.indicators.removeOutage',
+  getOutageCertificate: 'gestorDocumental.indicators.getOutageCertificate',
+} as const;
+
+/** Período: días de Chile «AAAA-MM-DD», hasta dos años. */
+export interface IndicatorsPeriodQuery {
+  from: string;
+  to: string;
+}
+
+export interface ManagementIndicatorsQuery extends IndicatorsPeriodQuery {
+  documentTypeId?: string | null;
+  directorateCode?: number | null;
+}
+
+export interface ServiceOutageInput {
+  kind: ServiceOutageKind;
+  startedAt: string;
+  endedAt?: string | null;
+  cause: string;
+  affectedServices?: string | null;
+}
+
+export interface IndicatorsContract {
+  [IndicatorsPatterns.getManagement]: { payload: ManagementIndicatorsQuery; response: ManagementIndicatorsEntity };
+  [IndicatorsPatterns.getQuality]: { payload: IndicatorsPeriodQuery; response: QualityReportEntity };
+  /**
+   * Indicadores y Plan de Mejora en una planilla Excel. `generatedBy`: quién la descarga. `unitNames`: nombre de cada
+   * unidad (`c:<código de dirección>` o `d:<id de departamento>`), que el ms no conoce.
+   */
+  [IndicatorsPatterns.export]: {
+    payload: ManagementIndicatorsQuery & { generatedBy: string; unitNames?: Record<string, string> };
+    response: IndicatorsFileEntity;
+  };
+  /** Umbral y, en las métricas declaradas, su valor y respaldo. */
+  [IndicatorsPatterns.updateQualityMetric]: {
+    payload: {
+      key: QualityMetricKey;
+      threshold: number;
+      declaredValue?: number | null;
+      declaredNote?: string | null;
+      actor: { fullName: string };
+    };
+    response: QualityMetricSettingResponseEntity;
+  };
+  [IndicatorsPatterns.getOutages]: { payload: { year: number }; response: ServiceOutageResponseEntity[] };
+  [IndicatorsPatterns.createOutage]: {
+    payload: ServiceOutageInput & { actor: { employeeId: string; fullName: string } };
+    response: ServiceOutageResponseEntity;
+  };
+  [IndicatorsPatterns.updateOutage]: {
+    payload: ServiceOutageInput & { id: string; actor: { employeeId: string; fullName: string } };
+    response: ServiceOutageResponseEntity;
+  };
+  [IndicatorsPatterns.removeOutage]: { payload: { id: string }; response: ServiceOutageRemoveResponseEntity };
+  /** Certificado de indisponibilidad (DS 10/2023) en PDF, de una caída ya terminada. */
+  [IndicatorsPatterns.getOutageCertificate]: {
+    payload: { id: string; generatedBy: string };
+    response: IndicatorsFileEntity;
+  };
+}

package/src/contracts/internalReview.contract.ts

@@ -0,0 +1,48 @@
+import {
+  type DocumentInternalNoteResponseEntity,
+  type DocumentInternalNotesResponseEntity,
+  type InternalReviewQueueItemEntity,
+} from '../entities';
+
+/** Patrones NATS de `internalReview`: la revisión para la jefatura y sus observaciones internas. */
+export const InternalReviewPatterns = {
+  getQueue: 'gestorDocumental.internalReview.getQueue',
+  getNotes: 'gestorDocumental.internalReview.getNotes',
+  addNote: 'gestorDocumental.internalReview.addNote',
+} as const;
+
+/**
+ * Dirección para la que actúa quien consulta: como revisora de su jefatura (integra la dirección y tiene el permiso de
+ * revisar) o como la jefatura misma (la dirige hoy y tiene el permiso de jefatura). La resuelve el gateway: ni quiénes
+ * la dirigen hoy (titular y subrogante) ni quiénes tienen cada permiso los dice el navegador.
+ */
+export interface InternalReviewScope {
+  directorateCode: number;
+  directorateName: string;
+  headEmployeeIds: string[];
+  role: 'Reviewer' | 'Head';
+  /** Como jefatura, al dejar una observación: quiénes revisan hoy para ella (a quienes se avisa). */
+  reviewerEmployeeIds?: string[];
+}
+
+export interface InternalReviewContract {
+  /** Documentos que esperan a las jefaturas para las que revisa quien consulta. */
+  [InternalReviewPatterns.getQueue]: {
+    payload: { actor: { employeeId: string }; scopes: InternalReviewScope[] };
+    response: InternalReviewQueueItemEntity[];
+  };
+  [InternalReviewPatterns.getNotes]: {
+    payload: { documentId: string; actor: { employeeId: string }; scopes: InternalReviewScope[] };
+    response: DocumentInternalNotesResponseEntity;
+  };
+  [InternalReviewPatterns.addNote]: {
+    payload: {
+      documentId: string;
+      directorateCode: number;
+      text: string;
+      actor: { employeeId: string; fullName: string };
+      scopes: InternalReviewScope[];
+    };
+    response: DocumentInternalNoteResponseEntity;
+  };
+}

package/src/contracts/issuingEntity.contract.ts

@@ -0,0 +1,55 @@
+import { type IssuingEntityEntity } from '../base/entities';
+import {
+  type IssuingEntityCreateResponseEntity,
+  type IssuingEntityGetAllResponseEntity,
+  type IssuingEntityGetByIdResponseEntity,
+  type IssuingEntityUpdateResponseEntity,
+} from '../entities';
+import { type RpcPage } from './contract';
+
+/** Patrones NATS de `issuingEntity`: `<servicio>.<recurso>.<acción>`. */
+export const IssuingEntityPatterns = {
+  getAll: 'gestorDocumental.issuingEntity.getAll',
+  getById: 'gestorDocumental.issuingEntity.getById',
+  create: 'gestorDocumental.issuingEntity.create',
+  update: 'gestorDocumental.issuingEntity.update',
+  setEnabled: 'gestorDocumental.issuingEntity.setEnabled',
+} as const;
+
+/** Datos de una entidad emisora al crearla o editarla. */
+export interface IssuingEntityWritePayload {
+  name: string;
+  shortName?: string | null;
+  /** Direcciones (código de caschile) cuyos funcionarios actúan por la entidad. */
+  directorateCodeReferences: number[];
+  /** Su entidad en DocDigital, entre las asociadas a las credenciales del gestor. */
+  docDigitalEntityId?: number | null;
+  enabled?: boolean;
+}
+
+export interface IssuingEntityContract {
+  [IssuingEntityPatterns.getAll]: {
+    // sin `page` y `limit` responde todas en una sola página
+    payload: {
+      pagination?: { page?: number; limit?: number };
+      filters?: { search?: string; enabled?: boolean };
+    };
+    response: RpcPage<IssuingEntityGetAllResponseEntity[]>;
+  };
+  [IssuingEntityPatterns.getById]: {
+    payload: Pick<IssuingEntityEntity, 'id'>;
+    response: IssuingEntityGetByIdResponseEntity;
+  };
+  [IssuingEntityPatterns.create]: {
+    payload: IssuingEntityWritePayload;
+    response: IssuingEntityCreateResponseEntity;
+  };
+  [IssuingEntityPatterns.update]: {
+    payload: IssuingEntityWritePayload & Pick<IssuingEntityEntity, 'id'>;
+    response: IssuingEntityUpdateResponseEntity;
+  };
+  [IssuingEntityPatterns.setEnabled]: {
+    payload: Pick<IssuingEntityEntity, 'id' | 'enabled'>;
+    response: IssuingEntityUpdateResponseEntity;
+  };
+}

package/src/contracts/mailIntake.contract.ts

@@ -0,0 +1,49 @@
+import {
+  type DeskFileResponseEntity,
+  type DeskOkResponseEntity,
+  type DocumentPublicFileResponseEntity,
+  type MailIntakeInboxEntity,
+  type MailIntakeSyncEntity,
+} from '../entities';
+import { type DocumentActor } from './document.contract';
+
+/**
+ * Patrones NATS de `mailIntake`: el ingreso por correo. Un funcionario reenvía un correo a la casilla del gestor y
+ * después elige qué adjuntos entran a su escritorio. `email` es el correo institucional de la sesión, que agrega el
+ * gateway: solo con él se ven los correos que envió.
+ */
+export const MailIntakePatterns = {
+  getMine: 'gestorDocumental.mailIntake.getMine',
+  accept: 'gestorDocumental.mailIntake.accept',
+  discard: 'gestorDocumental.mailIntake.discard',
+  getEml: 'gestorDocumental.mailIntake.getEml',
+  sync: 'gestorDocumental.mailIntake.sync',
+} as const;
+
+export interface MailIntakeContract {
+  /** Los correos pendientes que envió quien tiene la sesión, del más reciente al más antiguo. */
+  [MailIntakePatterns.getMine]: {
+    payload: { email: string | null; actor: DocumentActor };
+    response: MailIntakeInboxEntity;
+  };
+  /**
+   * Lleva al escritorio los adjuntos elegidos (por su `index`) y, si se pide, el correo completo en EML. El correo
+   * queda aceptado: no se puede volver a procesar.
+   */
+  [MailIntakePatterns.accept]: {
+    payload: { id: string; email: string | null; attachments: number[]; includeEml: boolean; actor: DocumentActor };
+    response: DeskFileResponseEntity[];
+  };
+  /** Lo descarta sin traer nada. El EML se conserva. */
+  [MailIntakePatterns.discard]: {
+    payload: { id: string; email: string | null; actor: DocumentActor };
+    response: DeskOkResponseEntity;
+  };
+  /** El correo completo (EML), para su remitente. */
+  [MailIntakePatterns.getEml]: {
+    payload: { id: string; email: string | null; actor: DocumentActor };
+    response: DocumentPublicFileResponseEntity;
+  };
+  /** Revisa la casilla ahora, sin esperar a la revisión periódica. */
+  [MailIntakePatterns.sync]: { payload: Record<string, never>; response: MailIntakeSyncEntity };
+}

package/src/contracts/partsOffice.contract.ts

@@ -1,9 +1,12 @@
-import { type DocumentAccessLevel, type DocumentInstruction } from '../base/entities';
+import { type CommunicationMeans, type DocumentAccessLevel, type DocumentInstruction } from '../base/entities';
 import {
+  type CaseFileAddEntryResponseEntity,
   type DocDigitalDocumentTypeEntity,
   type DocDigitalEntityEntity,
   type PartsOfficeInboundEntity,
   type DocDigitalUserEntity,
+  type EnablementPersonInput,
+  type PartsOfficeEnablementEntity,
   type PartsOfficeDispatchEntity,
   type PartsOfficeFileEntity,
   type PartsOfficeOkResponseEntity,
@@ -20,6 +23,7 @@ export const PartsOfficePatterns = {
   getStatus: 'gestorDocumental.partsOffice.getStatus',
   getSummary: 'gestorDocumental.partsOffice.getSummary',
   getEntities: 'gestorDocumental.partsOffice.getEntities',
+  getOwnEntities: 'gestorDocumental.partsOffice.getOwnEntities',
   getUsers: 'gestorDocumental.partsOffice.getUsers',
   getDocumentTypes: 'gestorDocumental.partsOffice.getDocumentTypes',
   getDispatches: 'gestorDocumental.partsOffice.getDispatches',
@@ -33,6 +37,10 @@ export const PartsOfficePatterns = {
   acknowledgeInbound: 'gestorDocumental.partsOffice.acknowledgeInbound',
   returnInbound: 'gestorDocumental.partsOffice.returnInbound',
   getInboundFile: 'gestorDocumental.partsOffice.getInboundFile',
+  checkEnablement: 'gestorDocumental.partsOffice.checkEnablement',
+  dispatchByContingency: 'gestorDocumental.partsOffice.dispatchByContingency',
+  registerManualIntake: 'gestorDocumental.partsOffice.registerManualIntake',
+  addCaseFileReceipt: 'gestorDocumental.partsOffice.addCaseFileReceipt',
 } as const;
 
 /** Destinatario interno de un ingreso, ya resuelto por el gateway (las áreas con sus integrantes). */
@@ -46,11 +54,37 @@ interface IListPayload<S> {
   filters?: { search?: string; status?: S };
 }
 
+/** Lo que llegó fuera de DocDigital y Oficina de Partes ingresa a mano. */
+export interface ManualIntakePayload {
+  file: { fileId: string; name: string };
+  attachments?: { fileId: string; name: string }[];
+  means: CommunicationMeans;
+  /** Cuándo llegó (ISO); sin él, ahora. */
+  receivedAt?: string | null;
+  senderEntityName: string;
+  senderName?: string | null;
+  externalFolio?: string | null;
+  externalDate?: string | null;
+  subject: string;
+  documentTypeId: string;
+  keywords: string[];
+  accessLevel?: DocumentAccessLevel;
+  hasSensitiveData?: boolean;
+  recipients: unknown[];
+  instruction: DocumentInstruction;
+  note?: string | null;
+  dueAt?: string | null;
+  dueBusinessDays?: number | null;
+  actor: DocumentActor;
+}
+
 export interface PartsOfficeContract {
   [PartsOfficePatterns.getStatus]: { payload: Record<string, never>; response: PartsOfficeStatusEntity };
   [PartsOfficePatterns.getSummary]: { payload: Record<string, never>; response: PartsOfficeSummaryEntity };
   /** Directorio de DocDigital: instituciones por nombre. */
   [PartsOfficePatterns.getEntities]: { payload: { search?: string }; response: DocDigitalEntityEntity[] };
+  /** Entidades asociadas a las credenciales del gestor: la del municipio y las de sus entidades emisoras. */
+  [PartsOfficePatterns.getOwnEntities]: { payload: Record<string, never>; response: DocDigitalEntityEntity[] };
   [PartsOfficePatterns.getUsers]: {
     payload: { entityId: number; search?: string };
     response: DocDigitalUserEntity[];
@@ -76,7 +110,11 @@ export interface PartsOfficeContract {
     response: PartsOfficeOkResponseEntity;
   };
   /** PDF firmado de un documento por despachar, para que Oficina de Partes lo revise. */
-  [PartsOfficePatterns.getDispatchFile]: { payload: { id: string }; response: PartsOfficeFileEntity };
+  [PartsOfficePatterns.getDispatchFile]: {
+    // con `receipt`, el comprobante del despacho por contingencia
+    payload: { id: string; receipt?: boolean };
+    response: PartsOfficeFileEntity;
+  };
   [PartsOfficePatterns.getInbound]: {
     payload: IListPayload<'Pending' | 'Registered' | 'Returned'>;
     response: RpcPage<PartsOfficeInboundEntity[]>;
@@ -117,4 +155,45 @@ export interface PartsOfficeContract {
     payload: { id: string; attachment?: number };
     response: PartsOfficeFileEntity;
   };
+  /**
+   * Quiénes de `people` están habilitados como usuarios de DocDigital en la municipalidad o en sus entidades emisoras
+   * (por RUN). El directorio de cada entidad se guarda 10 minutos.
+   */
+  [PartsOfficePatterns.checkEnablement]: {
+    payload: { people: EnablementPersonInput[] };
+    response: PartsOfficeEnablementEntity;
+  };
+  /**
+   * Registro por contingencia: el documento no se pudo despachar por DocDigital y salió por otro medio. Queda
+   * despachado, con el medio, a quién, el motivo y el comprobante; si después se registra en DocDigital, su número.
+   */
+  [PartsOfficePatterns.dispatchByContingency]: {
+    payload: {
+      id: string;
+      means: CommunicationMeans;
+      sentAt: string;
+      sentTo: string;
+      reason: string;
+      receipt?: { fileId: string; name: string } | null;
+      docDigitalDocumentId?: string | null;
+      actor: DocumentActor;
+    };
+    response: PartsOfficeOkResponseEntity;
+  };
+  /**
+   * Ingreso manual: lo que llegó fuera de DocDigital (papel, correo) entra con folio de ingreso, como lo recibido
+   * por DocDigital, y se deriva.
+   */
+  [PartsOfficePatterns.registerManualIntake]: {
+    payload: ManualIntakePayload;
+    response: PartsOfficeRegisterResponseEntity;
+  };
+  /**
+   * Comprobante de trazabilidad de DocDigital de un documento del índice de un expediente (despachado o recibido por
+   * DocDigital): se arma con el estado y el historial que informa DocDigital y entra como comunicación oficial.
+   */
+  [PartsOfficePatterns.addCaseFileReceipt]: {
+    payload: { caseFileId: string; documentId: string; actor: { employeeId: string } };
+    response: CaseFileAddEntryResponseEntity;
+  };
 }

package/src/contracts/procedure.contract.ts

@@ -1,30 +1,23 @@
 import { type ProcedureEntity } from '../base/entities';
 import {
-  type ProcedureCreateResponseEntity,
+  type ProcedureCpatStatusEntity,
   type ProcedureGetAllResponseEntity,
   type ProcedureGetByIdResponseEntity,
-  type ProcedureUpdateResponseEntity,
+  type ProcedureSyncResponseEntity,
 } from '../entities';
 import { type RpcPage } from './contract';
 
-/** Patrones NATS de `procedure`: `<servicio>.<recurso>.<acción>`. */
+/**
+ * Patrones NATS de `procedure`: los procedimientos administrativos vienen del CPAT (nómina en datos.gob.cl) y no se
+ * crean ni editan en el gestor.
+ */
 export const ProcedurePatterns = {
   getAll: 'gestorDocumental.procedure.getAll',
   getById: 'gestorDocumental.procedure.getById',
-  create: 'gestorDocumental.procedure.create',
-  update: 'gestorDocumental.procedure.update',
-  setEnabled: 'gestorDocumental.procedure.setEnabled',
+  getCpatStatus: 'gestorDocumental.procedure.getCpatStatus',
+  sync: 'gestorDocumental.procedure.sync',
 } as const;
 
-/** Datos de un procedimiento administrativo al crearlo o editarlo. */
-export interface ProcedureWritePayload {
-  name: string;
-  cpatId?: string | null;
-  cpatCode?: string | null;
-  description?: string | null;
-  enabled?: boolean;
-}
-
 export interface ProcedureContract {
   [ProcedurePatterns.getAll]: {
     // sin `page` y `limit` responde todos en una sola página
@@ -38,16 +31,7 @@ export interface ProcedureContract {
     payload: Pick<ProcedureEntity, 'id'>;
     response: ProcedureGetByIdResponseEntity;
   };
-  [ProcedurePatterns.create]: {
-    payload: ProcedureWritePayload;
-    response: ProcedureCreateResponseEntity;
-  };
-  [ProcedurePatterns.update]: {
-    payload: ProcedureWritePayload & Pick<ProcedureEntity, 'id'>;
-    response: ProcedureUpdateResponseEntity;
-  };
-  [ProcedurePatterns.setEnabled]: {
-    payload: Pick<ProcedureEntity, 'id' | 'enabled'>;
-    response: ProcedureUpdateResponseEntity;
-  };
+  [ProcedurePatterns.getCpatStatus]: { payload: Record<string, never>; response: ProcedureCpatStatusEntity };
+  /** Trae del CPAT los procedimientos de la institución `CPAT_INSTITUTION_CODE`. */
+  [ProcedurePatterns.sync]: { payload: Record<string, never>; response: ProcedureSyncResponseEntity };
 }

package/src/contracts/push.contract.ts

@@ -0,0 +1,41 @@
+import {
+  type PushConfigResponseEntity,
+  type PushNotificationInput,
+  type PushOkResponseEntity,
+  type PushSendResultEntity,
+} from '../entities';
+import { type DocumentActor } from './document.contract';
+
+/**
+ * Patrones NATS de `push`: avisos en el celular o el computador (Web Push), además del correo. Cada funcionario los
+ * activa en sus dispositivos; el gateway los envía junto con los correos de aviso.
+ */
+export const PushPatterns = {
+  getConfig: 'gestorDocumental.push.getConfig',
+  subscribe: 'gestorDocumental.push.subscribe',
+  unsubscribe: 'gestorDocumental.push.unsubscribe',
+  test: 'gestorDocumental.push.test',
+  send: 'gestorDocumental.push.send',
+} as const;
+
+export interface PushContract {
+  [PushPatterns.getConfig]: { payload: { actor: DocumentActor }; response: PushConfigResponseEntity };
+  /** Registra el dispositivo (o lo actualiza, si ya estaba) a nombre de quien tiene la sesión. */
+  [PushPatterns.subscribe]: {
+    payload: {
+      subscription: { endpoint: string; keys: { p256dh: string; auth: string } };
+      userAgent?: string | null;
+      actor: DocumentActor;
+    };
+    response: PushOkResponseEntity;
+  };
+  /** Quita el dispositivo, solo si es de quien tiene la sesión. */
+  [PushPatterns.unsubscribe]: { payload: { endpoint: string; actor: DocumentActor }; response: PushOkResponseEntity };
+  /** Un aviso de prueba a los dispositivos de quien tiene la sesión. */
+  [PushPatterns.test]: { payload: { actor: DocumentActor }; response: PushSendResultEntity };
+  /** Envía un aviso a los dispositivos de esos funcionarios. Lo usa el gateway, no el navegador. */
+  [PushPatterns.send]: {
+    payload: { employeeIds: string[]; notification: PushNotificationInput };
+    response: PushSendResultEntity;
+  };
+}

package/src/contracts/registerBook.contract.ts

@@ -0,0 +1,24 @@
+import { type RegisterBookEntity, type RegisterBookExportEntity, type RegisterBookKind } from '../entities';
+
+/** Patrones NATS de `registerBook` (libros de registro): `<servicio>.<recurso>.<acción>`. */
+export const RegisterBookPatterns = {
+  get: 'gestorDocumental.registerBook.get',
+  export: 'gestorDocumental.registerBook.export',
+} as const;
+
+/** Qué libro y qué período: un año y, si se indica, un mes. El de un tipo documental exige el tipo. */
+export interface RegisterBookQuery {
+  kind: RegisterBookKind;
+  documentTypeId?: string;
+  year: number;
+  month?: number | null;
+}
+
+export interface RegisterBookContract {
+  [RegisterBookPatterns.get]: { payload: RegisterBookQuery; response: RegisterBookEntity };
+  /** El libro en Excel o PDF. `generatedBy`: quién lo descarga (va en el encabezado). */
+  [RegisterBookPatterns.export]: {
+    payload: RegisterBookQuery & { format: 'xlsx' | 'pdf'; generatedBy: string };
+    response: RegisterBookExportEntity;
+  };
+}

package/src/contracts/repositoryExport.contract.ts

@@ -0,0 +1,54 @@
+import {
+  type RepositoryExportCaseFilesPageEntity,
+  type RepositoryExportRecordResponseEntity,
+  type RepositoryExportDocumentsPageEntity,
+  type RepositoryExportScope,
+  type RepositoryExportSummaryEntity,
+} from '../entities';
+
+/**
+ * Patrones NATS de `repositoryExport`: exportación completa del repositorio (portabilidad). El ms entrega los datos
+ * por páginas, porque un mensaje NATS no admite más de 1 MB; el gateway arma el ZIP con ellos y los archivos.
+ */
+export const RepositoryExportPatterns = {
+  getSummary: 'gestorDocumental.repositoryExport.getSummary',
+  getDocuments: 'gestorDocumental.repositoryExport.getDocuments',
+  getCaseFiles: 'gestorDocumental.repositoryExport.getCaseFiles',
+  record: 'gestorDocumental.repositoryExport.record',
+} as const;
+
+/** Período por fecha de creación (días de Chile «AAAA-MM-DD»); sin él, todo. */
+export interface RepositoryExportQuery {
+  from?: string | null;
+  to?: string | null;
+  scope?: RepositoryExportScope;
+  /** Solo lo incluido en un acta de transferencia: el paquete para el Archivo Nacional. */
+  dispositionId?: string | null;
+}
+
+export interface RepositoryExportContract {
+  [RepositoryExportPatterns.getSummary]: { payload: RepositoryExportQuery; response: RepositoryExportSummaryEntity };
+  /** Hasta 50 documentos por página, en orden de creación. */
+  [RepositoryExportPatterns.getDocuments]: {
+    payload: RepositoryExportQuery & { cursor?: string | null; limit?: number };
+    response: RepositoryExportDocumentsPageEntity;
+  };
+  /** Hasta 10 expedientes por página; cada uno queda con «Exportó» en su trazabilidad, a nombre de quien exporta. */
+  [RepositoryExportPatterns.getCaseFiles]: {
+    payload: Omit<RepositoryExportQuery, 'scope'> & {
+      cursor?: string | null;
+      limit?: number;
+      actor: { employeeId: string | null; fullName: string };
+    };
+    response: RepositoryExportCaseFilesPageEntity;
+  };
+  /** Deja la exportación en la bitácora: quién, qué período y si llevó archivos. */
+  [RepositoryExportPatterns.record]: {
+    payload: RepositoryExportQuery & {
+      includeFiles: boolean;
+      complete: boolean;
+      actor: { employeeId: string | null; fullName: string };
+    };
+    response: RepositoryExportRecordResponseEntity;
+  };
+}

package/src/contracts/retention.contract.ts

@@ -0,0 +1,44 @@
+import { type DispositionKind } from '../base/entities';
+import {
+  type DispositionRecordResponseEntity,
+  type IndicatorsFileEntity,
+  type RetentionDueItemEntity,
+  type RetentionSummaryEntity,
+} from '../entities';
+import { type RpcPage } from './contract';
+
+/** Patrones NATS de `retention`: plazos de retención por serie y actas de transferencia o eliminación. */
+export const RetentionPatterns = {
+  getSummary: 'gestorDocumental.retention.getSummary',
+  getDueItems: 'gestorDocumental.retention.getDueItems',
+  createRecord: 'gestorDocumental.retention.createRecord',
+  getRecords: 'gestorDocumental.retention.getRecords',
+  getRecordPdf: 'gestorDocumental.retention.getRecordPdf',
+} as const;
+
+export interface RetentionContract {
+  [RetentionPatterns.getSummary]: { payload: Record<string, never>; response: RetentionSummaryEntity };
+  /** Lo vencido de una serie, de lo más antiguo a lo más reciente. */
+  [RetentionPatterns.getDueItems]: {
+    payload: { seriesId: string; page?: number; limit?: number };
+    response: RpcPage<RetentionDueItemEntity[]>;
+  };
+  /**
+   * Emite el acta con lo elegido (todo debe estar vencido y sin acta). Según la serie: conservación permanente →
+   * transferencia; eliminación → eliminación; selección → cualquiera de las dos.
+   */
+  [RetentionPatterns.createRecord]: {
+    payload: {
+      kind: DispositionKind;
+      seriesId: string;
+      documentIds: string[];
+      caseFileIds: string[];
+      observation?: string | null;
+      actor: { employeeId: string; fullName: string };
+    };
+    response: DispositionRecordResponseEntity;
+  };
+  [RetentionPatterns.getRecords]: { payload: { year: number }; response: DispositionRecordResponseEntity[] };
+  /** El acta en PDF, con lo que incluye, para firmarla y archivarla. */
+  [RetentionPatterns.getRecordPdf]: { payload: { id: string; generatedBy: string }; response: IndicatorsFileEntity };
+}

package/src/contracts/richImage.contract.ts

@@ -0,0 +1,23 @@
+import { type RichImageResponseEntity } from '../entities';
+
+/** Patrones NATS de `richImage`: imágenes del editor (logos de membrete e imágenes del texto). */
+export const RichImagePatterns = {
+  register: 'gestorDocumental.richImage.register',
+  getFile: 'gestorDocumental.richImage.getFile',
+} as const;
+
+export interface RichImageContract {
+  /**
+   * Registra una imagen ya subida a Drive por el gateway (en la carpeta de los documentos). El ms descarga el archivo, comprueba que sea PNG o JPEG y de
+   * tamaño aceptable, y guarda sus medidas y su huella.
+   */
+  [RichImagePatterns.register]: {
+    payload: { fileId: string; name: string; actor: { employeeId: string } };
+    response: RichImageResponseEntity;
+  };
+  /** El archivo de una imagen registrada, para mostrarla en el editor. */
+  [RichImagePatterns.getFile]: {
+    payload: { id: string };
+    response: { fileId: string; fileName: string; mimeType: string };
+  };
+}

package/src/contracts/scan.contract.ts

@@ -0,0 +1,52 @@
+import {
+  type ScanSessionCreateResponseEntity,
+  type ScanSessionFileResponseEntity,
+  type ScanSessionPublicEntity,
+  type ScanSessionResponseEntity,
+} from '../entities';
+import { type DocumentActor } from './document.contract';
+
+/** Patrones NATS de `scan`: escanear con el celular. */
+export const ScanPatterns = {
+  create: 'gestorDocumental.scan.create',
+  getById: 'gestorDocumental.scan.getById',
+  getFile: 'gestorDocumental.scan.getFile',
+  getByToken: 'gestorDocumental.scan.getByToken',
+  addPage: 'gestorDocumental.scan.addPage',
+  finish: 'gestorDocumental.scan.finish',
+} as const;
+
+export interface ScanContract {
+  /**
+   * Abre una sesión de escaneo para el funcionario. `url` es la dirección pública del celular (sin el token): con ella
+   * se arma el QR que se muestra en el escritorio.
+   */
+  [ScanPatterns.create]: {
+    payload: { url: string; actor: DocumentActor };
+    response: ScanSessionCreateResponseEntity;
+  };
+  /** Estado de la sesión, para quien la abrió: el escritorio la consulta hasta que el PDF esté listo. */
+  [ScanPatterns.getById]: {
+    payload: { id: string; actor: DocumentActor };
+    response: ScanSessionResponseEntity;
+  };
+  [ScanPatterns.getFile]: {
+    payload: { id: string; actor: DocumentActor };
+    response: ScanSessionFileResponseEntity;
+  };
+  /** Sin sesión, desde el celular, con el token del QR. */
+  [ScanPatterns.getByToken]: {
+    payload: { token: string };
+    response: ScanSessionPublicEntity;
+  };
+  /** Agrega una foto ya subida al gestor de archivos (la sube el gateway). */
+  [ScanPatterns.addPage]: {
+    payload: { token: string; fileId: string; contentType: string; size: number };
+    response: ScanSessionPublicEntity;
+  };
+  /** Junta las fotos en un PDF y cierra la sesión. */
+  [ScanPatterns.finish]: {
+    payload: { token: string };
+    response: ScanSessionPublicEntity;
+  };
+}