@muni-sanfer/types-gestor-documental 0.0.1-beta.0 → 0.0.1-beta.10

package/src/contracts/caseFile.contract.ts

@@ -0,0 +1,141 @@
+import {
+  type CaseFileActorRelation,
+  type CaseFileActorType,
+  type CaseFileActuationType,
+  type CaseFileEntity,
+  type CaseFileStatus,
+  type DocumentAccessLevel,
+} from '../base/entities';
+import {
+  type CaseFileAddBatchResponseEntity,
+  type CaseFileAddEntryResponseEntity,
+  type CaseFileCreateResponseEntity,
+  type CaseFileEntryFileResponseEntity,
+  type CaseFileExportResponseEntity,
+  type CaseFileGetAllResponseEntity,
+  type CaseFileGetByIdResponseEntity,
+  type CaseFileUpdateResponseEntity,
+} from '../entities';
+import { type RpcPage } from './contract';
+import { type DocumentActor } from './document.contract';
+
+/** Patrones NATS de `caseFile`: `<servicio>.<recurso>.<acción>`. */
+export const CaseFilePatterns = {
+  getAll: 'gestorDocumental.caseFile.getAll',
+  getById: 'gestorDocumental.caseFile.getById',
+  create: 'gestorDocumental.caseFile.create',
+  update: 'gestorDocumental.caseFile.update',
+  addEntry: 'gestorDocumental.caseFile.addEntry',
+  addBatch: 'gestorDocumental.caseFile.addBatch',
+  voidEntry: 'gestorDocumental.caseFile.voidEntry',
+  share: 'gestorDocumental.caseFile.share',
+  unshare: 'gestorDocumental.caseFile.unshare',
+  close: 'gestorDocumental.caseFile.close',
+  getEntryFile: 'gestorDocumental.caseFile.getEntryFile',
+  getExport: 'gestorDocumental.caseFile.getExport',
+} as const;
+
+/** Persona u organización relacionada con el expediente (MGDEE54). */
+export interface CaseFileActorInput {
+  relation: CaseFileActorRelation;
+  actorType: CaseFileActorType;
+  identifier?: string | null;
+  name: string;
+}
+
+/** Metadatos del expediente que se ingresan a mano. */
+export interface CaseFileWritePayload {
+  title: string;
+  subject: string;
+  summary?: string | null;
+  procedureId: string;
+  accessLevel: DocumentAccessLevel;
+  hasSensitiveData: boolean;
+  actors?: CaseFileActorInput[];
+}
+
+/** Actuación que se incorpora al índice: un documento del gestor, un archivo subido u otro expediente. */
+export type CaseFileEntryInput =
+  | { kind: 'Document'; actuationType: CaseFileActuationType; documentId: string }
+  | {
+      kind: 'File';
+      actuationType: CaseFileActuationType;
+      fileId: string;
+      fileName: string;
+      title: string;
+      documentTypeName?: string | null;
+      originDate?: string | null;
+      author?: string | null;
+      keywords: string[];
+      accessLevel: DocumentAccessLevel;
+      hasSensitiveData: boolean;
+    }
+  | { kind: 'CaseFile'; actuationType: CaseFileActuationType; linkedCaseFileId: string };
+
+/** Quién hace la operación (de la sesión) y si puede ver todos los expedientes. */
+interface CaseFileActorPayload {
+  actor: DocumentActor;
+  viewAll?: boolean;
+}
+
+/** Ámbito del listado: los expedientes del funcionario (responsable o compartidos con él) o todos. */
+export type CaseFileScope = 'mine' | 'all';
+
+export interface CaseFileContract {
+  [CaseFilePatterns.getAll]: {
+    payload: {
+      pagination?: { page?: number; limit?: number };
+      filters?: { search?: string; status?: CaseFileStatus; procedureId?: string; scope?: CaseFileScope };
+    } & CaseFileActorPayload;
+    response: RpcPage<CaseFileGetAllResponseEntity[]>;
+  };
+  /** Por id o por su identificador (`EXP-2026-00001`), que es el del enlace persistente. Queda en el registro de accesos. */
+  [CaseFilePatterns.getById]: {
+    payload: { id: string } & CaseFileActorPayload;
+    response: CaseFileGetByIdResponseEntity;
+  };
+  [CaseFilePatterns.create]: {
+    payload: CaseFileWritePayload & { actor: DocumentActor };
+    response: CaseFileCreateResponseEntity;
+  };
+  [CaseFilePatterns.update]: {
+    payload: CaseFileWritePayload & Pick<CaseFileEntity, 'id'> & { actor: DocumentActor };
+    response: CaseFileUpdateResponseEntity;
+  };
+  /** Incorpora los documentos finalizados de un lote de firma, en su orden; omite los que ya están en el expediente. */
+  [CaseFilePatterns.addBatch]: {
+    payload: { id: string; batchId: string; actuationType: CaseFileActuationType } & CaseFileActorPayload;
+    response: CaseFileAddBatchResponseEntity;
+  };
+  [CaseFilePatterns.addEntry]: {
+    payload: Pick<CaseFileEntity, 'id'> & { entry: CaseFileEntryInput } & CaseFileActorPayload;
+    response: CaseFileAddEntryResponseEntity;
+  };
+  /** Deja una actuación sin efecto, con su motivo. No se elimina del índice. */
+  [CaseFilePatterns.voidEntry]: {
+    payload: Pick<CaseFileEntity, 'id'> & { entryId: string; reason: string; actor: DocumentActor };
+    response: CaseFileUpdateResponseEntity;
+  };
+  [CaseFilePatterns.share]: {
+    payload: Pick<CaseFileEntity, 'id'> & { employeeIds: string[]; actor: DocumentActor };
+    response: CaseFileUpdateResponseEntity;
+  };
+  [CaseFilePatterns.unshare]: {
+    payload: Pick<CaseFileEntity, 'id'> & { participantId: string; actor: DocumentActor };
+    response: CaseFileUpdateResponseEntity;
+  };
+  [CaseFilePatterns.close]: {
+    payload: Pick<CaseFileEntity, 'id'> & { note?: string | null; actor: DocumentActor };
+    response: CaseFileUpdateResponseEntity;
+  };
+  /** Archivo de una actuación del índice. Queda en el registro de accesos. */
+  [CaseFilePatterns.getEntryFile]: {
+    payload: Pick<CaseFileEntity, 'id'> & { entryId: string } & CaseFileActorPayload;
+    response: CaseFileEntryFileResponseEntity;
+  };
+  /** Metadatos y archivos para exportar el expediente completo. Queda en la trazabilidad y en el registro de accesos. */
+  [CaseFilePatterns.getExport]: {
+    payload: Pick<CaseFileEntity, 'id'> & CaseFileActorPayload;
+    response: CaseFileExportResponseEntity;
+  };
+}

package/src/contracts/document.contract.ts

@@ -1,30 +1,53 @@
 import {
   type DocumentAccessLevel,
   type DocumentAttachmentEntity,
+  type DocumentDeliveryEntity,
   type DocumentEntity,
+  type DocumentInstruction,
+  type DocumentParticipantEntity,
   type DocumentStatus,
 } from '../base/entities';
 import {
+  type DocumentAnnulResponseEntity,
+  type DocumentCloseDeliveryResponseEntity,
   type DocumentCreateResponseEntity,
+  type DocumentDeriveResponseEntity,
   type DocumentDiscardResponseEntity,
   type DocumentGetAllResponseEntity,
   type DocumentGetByIdResponseEntity,
   type DocumentGetSummaryResponseEntity,
+  type DocumentInboxItemEntity,
+  type DocumentPublicFileResponseEntity,
+  type DocumentReassignResponseEntity,
   type DocumentReviewResponseEntity,
+  type DocumentSignManyResponseEntity,
+  type DocumentAgendaResponseEntity,
+  type DocumentTrailExportEntity,
   type DocumentUpdateResponseEntity,
+  type DocumentVerifyResponseEntity,
 } from '../entities';
 import { type RpcPage } from './contract';
 
 /** Patrones NATS de `document`: `<servicio>.<recurso>.<acción>`. */
 export const DocumentPatterns = {
   getAll: 'gestorDocumental.document.getAll',
+  getInbox: 'gestorDocumental.document.getInbox',
   getSummary: 'gestorDocumental.document.getSummary',
   getById: 'gestorDocumental.document.getById',
   create: 'gestorDocumental.document.create',
   update: 'gestorDocumental.document.update',
   review: 'gestorDocumental.document.review',
+  signMany: 'gestorDocumental.document.signMany',
+  reassign: 'gestorDocumental.document.reassign',
   discard: 'gestorDocumental.document.discard',
+  annul: 'gestorDocumental.document.annul',
+  derive: 'gestorDocumental.document.derive',
+  closeDelivery: 'gestorDocumental.document.closeDelivery',
+  verify: 'gestorDocumental.document.verify',
+  getPublicFile: 'gestorDocumental.document.getPublicFile',
   getFilesFolder: 'gestorDocumental.document.getFilesFolder',
+  getAgenda: 'gestorDocumental.document.getAgenda',
+  exportTrail: 'gestorDocumental.document.exportTrail',
 } as const;
 
 /**
@@ -40,11 +63,24 @@ export interface DocumentActor {
 /** Bandeja desde la que se lista. Todas son del funcionario (`actor`), salvo `all`. */
 export type DocumentBucket =
   | 'created' // los que redactó
+  | 'sent' // de los que redactó, los ya finalizados que tienen destinatarios
   | 'toVisa' // le toca visarlos
   | 'toSign' // le toca firmarlos
   | 'participated' // ya los visó, firmó o rechazó
   | 'all'; // todos los que están en tramitación o finalizados (historial)
 
+/**
+ * Destinatario de un documento o de una derivación: una persona o un área completa. El gateway resuelve el nombre del
+ * área y quiénes la integran hoy; el navegador solo indica cuál es.
+ */
+export type DocumentRecipientInput =
+  | { type: 'Employee'; employeeId: string }
+  | { type: 'Directorate'; directorateCodeReference: number; name: string; memberEmployeeIds: string[] }
+  | { type: 'Department'; departmentId: string; name: string; memberEmployeeIds: string[] };
+
+/** Qué parte de la bandeja de recibidos se lista: lo que falta atender, lo ya atendido, o todo. */
+export type DocumentInboxState = 'pending' | 'closed' | 'all';
+
 /** Qué hace con el documento quien tiene el turno. */
 export type DocumentReviewAction = 'Visa' | 'Sign' | 'Reject';
 
@@ -63,15 +99,48 @@ export interface DocumentWritePayload extends Pick<DocumentEntity, 'subject' | '
   attachments?: Pick<DocumentAttachmentEntity, 'name' | 'type' | 'fileId' | 'url'>[];
   // Funcionarios que visan y que firman, en el orden en que les toca. Primero visan todos y después firman.
   visaEmployeeIds: string[];
+  // Etapa de cada visador, en su orden ([1, 1, 2]: los dos primeros visan a la vez). Sin etapas, visan en cadena.
+  visaStages?: number[] | null;
+  // Al reenviar un documento rechazado, pedir de nuevo las visaciones ya hechas en vez de seguir donde quedó.
+  restartFlow?: boolean;
   signatureEmployeeIds: string[];
+  // Firmas y visaciones en una hoja aparte al final, en vez de al pie de la última página.
+  signatureSheet?: boolean;
+  // A quién va dirigido: le llega a su bandeja cuando el documento termina su tramitación.
+  recipients?: DocumentRecipientInput[];
+  // Plazo en que se espera respuesta de los destinatarios (ISO 8601).
+  responseDueAt?: string | null;
+  // Documento al que este responde.
+  replyToDocumentId?: string | null;
+  // Instituciones (y usuarios) de DocDigital a quienes va: al terminar la firma pasa a Oficina de Partes.
+  externalRecipients?: DocumentExternalRecipientInput[];
   action?: 'Submit';
   actor: DocumentActor;
 }
 
+/** Destinatario externo: una institución de DocDigital y, si se indica, uno de sus usuarios. */
+export interface DocumentExternalRecipientInput {
+  entityId: number;
+  userId?: number | null;
+}
+
 /**
  * Qué se envía y qué se responde en cada patrón. Generado desde los handlers y los DTO del microservicio.
  */
 export interface DocumentContract {
+  /** Plazos del funcionario entre `from` y `to` (hasta 62 días), y lo que tiene vencido sin atender. */
+  [DocumentPatterns.getAgenda]: {
+    payload: { from: string; to: string; actor: DocumentActor };
+    response: DocumentAgendaResponseEntity;
+  };
+  /**
+   * Trazabilidad del documento en PDF: datos, flujo, hechos y huella de sus archivos. Con las mismas reglas de acceso
+   * del detalle. `generatedBy`: quién la descarga (va al pie).
+   */
+  [DocumentPatterns.exportTrail]: {
+    payload: Pick<DocumentEntity, 'id'> & { actor?: DocumentActor; viewAll?: boolean; generatedBy: string };
+    response: DocumentTrailExportEntity;
+  };
   [DocumentPatterns.getAll]: {
     payload: {
       pagination?: { page?: number; limit?: number };
@@ -83,12 +152,29 @@ export interface DocumentContract {
         // Rango de fechas de creación (ISO 8601).
         dateFrom?: string;
         dateTo?: string;
+        // Búsqueda avanzada: número (del documento o folio de ingreso) y año, firmante, redactor y unidad emisora.
+        number?: number;
+        year?: number;
+        signerEmployeeId?: string;
+        authorEmployeeId?: string;
+        directorateCodeReference?: number;
+        // Texto completo, en el asunto y en el contenido del PDF.
+        text?: string;
       };
       // Obligatorio en todas las bandejas salvo `all`.
       actor?: DocumentActor;
     };
     response: RpcPage<DocumentGetAllResponseEntity[]>;
   };
+  /** Bandeja de recibidos de un funcionario: lo que le llegó como destinatario o por derivación. */
+  [DocumentPatterns.getInbox]: {
+    payload: {
+      pagination?: { page?: number; limit?: number };
+      filters?: { search?: string; state?: DocumentInboxState };
+      actor: DocumentActor;
+    };
+    response: RpcPage<DocumentInboxItemEntity[]>;
+  };
   [DocumentPatterns.getSummary]: {
     payload: { actor: DocumentActor };
     response: DocumentGetSummaryResponseEntity;
@@ -121,10 +207,77 @@ export interface DocumentContract {
     };
     response: DocumentReviewResponseEntity;
   };
+  /**
+   * Firma con un solo OTP varios documentos que el funcionario tiene en su turno de firma (los de un lote, o los que
+   * marcó en su bandeja). Cada uno queda firmado aparte; los que no caben en la solicitud quedan en `remaining`.
+   */
+  [DocumentPatterns.signMany]: {
+    payload: {
+      ids: DocumentEntity['id'][];
+      observation?: string | null;
+      // Datos de quien firma, para el sello de la firma (los resuelve el gateway desde la sesión).
+      signer: { rut: string; fullName: string; role: string; areaName: string };
+      otp?: string;
+      actor: DocumentActor;
+    };
+    response: DocumentSignManyResponseEntity;
+  };
+  /**
+   * Pasa un turno pendiente (de visación o de firma) a otro funcionario, por ausencia o por error, y lo deja en la
+   * trazabilidad con su motivo. Puede hacerlo quien redactó el documento; con `anyDocument`, quien lleva el registro.
+   */
+  [DocumentPatterns.reassign]: {
+    payload: Pick<DocumentEntity, 'id'> & {
+      participantId: DocumentParticipantEntity['id'];
+      // Funcionario que toma el turno.
+      employeeId: string;
+      reason: string;
+      actor: DocumentActor;
+      anyDocument?: boolean;
+    };
+    response: DocumentReassignResponseEntity;
+  };
   [DocumentPatterns.discard]: {
     payload: Pick<DocumentEntity, 'id'> & { actor: DocumentActor };
     response: DocumentDiscardResponseEntity;
   };
+  /** Deja sin efecto un documento ya finalizado. Conserva su número, que no se reutiliza. */
+  [DocumentPatterns.annul]: {
+    payload: Pick<DocumentEntity, 'id'> & { reason: string; actor: DocumentActor };
+    response: DocumentAnnulResponseEntity;
+  };
+  /**
+   * Deriva un documento finalizado a otros funcionarios o áreas, con su providencia (qué se espera de ellos) y,
+   * si corresponde, un plazo. Puede hacerlo quien lo tiene a su alcance: su redactor, quien lo visó o firmó, quien lo
+   * recibió y, con `viewAll`, quien consulta el historial.
+   */
+  [DocumentPatterns.derive]: {
+    payload: Pick<DocumentEntity, 'id'> & {
+      recipients: DocumentRecipientInput[];
+      instruction: DocumentInstruction;
+      note?: string | null;
+      // Plazo para atenderlo (ISO 8601).
+      dueAt?: string | null;
+      actor: DocumentActor;
+      viewAll?: boolean;
+    };
+    response: DocumentDeriveResponseEntity;
+  };
+  /** Quien recibió un documento lo marca como atendido, con una nota opcional. */
+  [DocumentPatterns.closeDelivery]: {
+    payload: { deliveryId: DocumentDeliveryEntity['id']; note?: string | null; actor: DocumentActor };
+    response: DocumentCloseDeliveryResponseEntity;
+  };
+  /** Comprobación pública de un documento con el código que lleva impreso. No exige sesión. */
+  [DocumentPatterns.verify]: {
+    payload: { code: string };
+    response: DocumentVerifyResponseEntity;
+  };
+  /** Archivo de un documento finalizado y de acceso público, para quien lo verificó con su código. */
+  [DocumentPatterns.getPublicFile]: {
+    payload: { code: string };
+    response: DocumentPublicFileResponseEntity;
+  };
   /** Carpeta de Drive de los documentos y sus anexos: el gateway la pide antes de subir cada archivo. */
   [DocumentPatterns.getFilesFolder]: {
     payload: Record<string, never>;

package/src/contracts/documentType.contract.ts

@@ -1,4 +1,4 @@
-import { type DocumentCategory, type DocumentTypeEntity } from '../base/entities';
+import { type DocumentCategory, type DocumentParticipantRole, type DocumentTypeEntity } from '../base/entities';
 import {
   type DocumentTypeCreateResponseEntity,
   type DocumentTypeGetAllResponseEntity,
@@ -16,6 +16,15 @@ export const DocumentTypePatterns = {
   setEnabled: 'gestorDocumental.documentType.setEnabled',
 } as const;
 
+/**
+ * Paso del flujo sugerido de un tipo documental: un funcionario en particular, o quien dirija una dirección al
+ * momento de redactar (su jefatura o, con subrogancia activa, el subrogante). El nombre de la dirección lo resuelve
+ * el gateway; el navegador solo indica cuál es.
+ */
+export type DocumentFlowStepInput =
+  | { role: DocumentParticipantRole; type: 'Employee'; employeeId: string }
+  | { role: DocumentParticipantRole; type: 'DirectorateHead'; directorateCodeReference: number; name: string };
+
 /** Datos de un tipo documental al crearlo o editarlo. */
 export interface DocumentTypeWritePayload {
   name: string;
@@ -25,8 +34,12 @@ export interface DocumentTypeWritePayload {
   // Próximo número que se asignará: permite partir desde el correlativo que la municipalidad ya lleva.
   nextCorrelative?: number;
   resetsYearly?: boolean;
+  // Sus documentos llevan número (por omisión, sí).
+  numbered?: boolean;
   directorateCodeReference?: number | null;
   enabled?: boolean;
+  // Flujo sugerido, en el orden en que les toca dentro de cada rol. Al editar, si no viene, el flujo no cambia.
+  flowSteps?: DocumentFlowStepInput[];
 }
 
 /**

package/src/contracts/index.ts

@@ -1,15 +1,40 @@
+import { CaseFilePatterns, type CaseFileContract } from './caseFile.contract';
 import { DocumentPatterns, type DocumentContract } from './document.contract';
 import { DocumentTypePatterns, type DocumentTypeContract } from './documentType.contract';
+import { PartsOfficePatterns, type PartsOfficeContract } from './partsOffice.contract';
+import { ProcedurePatterns, type ProcedureContract } from './procedure.contract';
+import { RegisterBookPatterns, type RegisterBookContract } from './registerBook.contract';
+import { SignatureBatchPatterns, type SignatureBatchContract } from './signatureBatch.contract';
+import { WorkFolderPatterns, type WorkFolderContract } from './workFolder.contract';
 
 export * from './contract';
 export * from './document.contract';
 export * from './documentType.contract';
+export * from './procedure.contract';
+export * from './caseFile.contract';
+export * from './partsOffice.contract';
+export * from './registerBook.contract';
+export * from './signatureBatch.contract';
+export * from './workFolder.contract';
 
 /** Patrones NATS de gestor-documental-ms, por recurso: `gestorDocumental.<recurso>.<acción>`. */
 export const GestorDocumentalPatterns = {
   documentType: DocumentTypePatterns,
   document: DocumentPatterns,
+  procedure: ProcedurePatterns,
+  caseFile: CaseFilePatterns,
+  partsOffice: PartsOfficePatterns,
+  registerBook: RegisterBookPatterns,
+  signatureBatch: SignatureBatchPatterns,
+  workFolder: WorkFolderPatterns,
 } as const;
 
 /** Contrato completo de gestor-documental-ms: la unión de los contratos de sus recursos. */
-export type GestorDocumentalContract = DocumentTypeContract & DocumentContract;
+export type GestorDocumentalContract = DocumentTypeContract &
+  DocumentContract &
+  ProcedureContract &
+  CaseFileContract &
+  PartsOfficeContract &
+  RegisterBookContract &
+  SignatureBatchContract &
+  WorkFolderContract;

package/src/contracts/partsOffice.contract.ts

@@ -0,0 +1,120 @@
+import { type DocumentAccessLevel, type DocumentInstruction } from '../base/entities';
+import {
+  type DocDigitalDocumentTypeEntity,
+  type DocDigitalEntityEntity,
+  type PartsOfficeInboundEntity,
+  type DocDigitalUserEntity,
+  type PartsOfficeDispatchEntity,
+  type PartsOfficeFileEntity,
+  type PartsOfficeOkResponseEntity,
+  type PartsOfficeRegisterResponseEntity,
+  type PartsOfficeStatusEntity,
+  type PartsOfficeSummaryEntity,
+  type PartsOfficeSyncResponseEntity,
+} from '../entities';
+import { type RpcPage } from './contract';
+import { type DocumentActor, type DocumentExternalRecipientInput } from './document.contract';
+
+/** Patrones NATS de `partsOffice` (Oficina de Partes y DocDigital): `<servicio>.<recurso>.<acción>`. */
+export const PartsOfficePatterns = {
+  getStatus: 'gestorDocumental.partsOffice.getStatus',
+  getSummary: 'gestorDocumental.partsOffice.getSummary',
+  getEntities: 'gestorDocumental.partsOffice.getEntities',
+  getUsers: 'gestorDocumental.partsOffice.getUsers',
+  getDocumentTypes: 'gestorDocumental.partsOffice.getDocumentTypes',
+  getDispatches: 'gestorDocumental.partsOffice.getDispatches',
+  dispatch: 'gestorDocumental.partsOffice.dispatch',
+  returnDispatch: 'gestorDocumental.partsOffice.returnDispatch',
+  resendDispatch: 'gestorDocumental.partsOffice.resendDispatch',
+  getDispatchFile: 'gestorDocumental.partsOffice.getDispatchFile',
+  getInbound: 'gestorDocumental.partsOffice.getInbound',
+  syncInbound: 'gestorDocumental.partsOffice.syncInbound',
+  registerInbound: 'gestorDocumental.partsOffice.registerInbound',
+  acknowledgeInbound: 'gestorDocumental.partsOffice.acknowledgeInbound',
+  returnInbound: 'gestorDocumental.partsOffice.returnInbound',
+  getInboundFile: 'gestorDocumental.partsOffice.getInboundFile',
+} as const;
+
+/** Destinatario interno de un ingreso, ya resuelto por el gateway (las áreas con sus integrantes). */
+export type PartsOfficeRecipientInput =
+  | { type: 'Employee'; employeeId: string }
+  | { type: 'Directorate'; directorateCodeReference: number; name: string; memberEmployeeIds: string[] }
+  | { type: 'Department'; departmentId: string; name: string; memberEmployeeIds: string[] };
+
+interface IListPayload<S> {
+  pagination?: { page?: number; limit?: number };
+  filters?: { search?: string; status?: S };
+}
+
+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[] };
+  [PartsOfficePatterns.getUsers]: {
+    payload: { entityId: number; search?: string };
+    response: DocDigitalUserEntity[];
+  };
+  [PartsOfficePatterns.getDocumentTypes]: { payload: Record<string, never>; response: DocDigitalDocumentTypeEntity[] };
+  [PartsOfficePatterns.getDispatches]: {
+    payload: IListPayload<'Pending' | 'Dispatched' | 'Returned'>;
+    response: RpcPage<PartsOfficeDispatchEntity[]>;
+  };
+  /** Despacha por DocDigital, con el número del documento como folio. `operatorRun`: RUN de quien despacha. */
+  [PartsOfficePatterns.dispatch]: {
+    payload: { id: string; docDigitalTypeId: number; operatorRun?: string | null; actor: DocumentActor };
+    response: PartsOfficeOkResponseEntity & { docDigitalDocumentId: string };
+  };
+  /** Devuelve el despacho al redactor, con el motivo (por ejemplo, un destinatario equivocado). */
+  [PartsOfficePatterns.returnDispatch]: {
+    payload: { id: string; reason: string; actor: DocumentActor };
+    response: PartsOfficeOkResponseEntity;
+  };
+  /** El redactor corrige las instituciones de destino de un despacho devuelto y lo envía de nuevo a Partes. */
+  [PartsOfficePatterns.resendDispatch]: {
+    payload: { id: string; externalRecipients: DocumentExternalRecipientInput[]; actor: DocumentActor };
+    response: PartsOfficeOkResponseEntity;
+  };
+  /** PDF firmado de un documento por despachar, para que Oficina de Partes lo revise. */
+  [PartsOfficePatterns.getDispatchFile]: { payload: { id: string }; response: PartsOfficeFileEntity };
+  [PartsOfficePatterns.getInbound]: {
+    payload: IListPayload<'Pending' | 'Registered' | 'Returned'>;
+    response: RpcPage<PartsOfficeInboundEntity[]>;
+  };
+  /** Trae de DocDigital lo recibido que aún no tiene acuse de recibo. */
+  [PartsOfficePatterns.syncInbound]: { payload: Record<string, never>; response: PartsOfficeSyncResponseEntity };
+  /**
+   * Ingresa un recibido al gestor: le da folio de ingreso, lo deriva a quienes corresponda y da el acuse de recibo
+   * en DocDigital.
+   */
+  [PartsOfficePatterns.registerInbound]: {
+    payload: {
+      id: string;
+      documentTypeId: string;
+      keywords: string[];
+      accessLevel: DocumentAccessLevel;
+      hasSensitiveData: boolean;
+      recipients: PartsOfficeRecipientInput[];
+      instruction: DocumentInstruction;
+      note?: string | null;
+      dueAt?: string | null;
+      actor: DocumentActor;
+    };
+    response: PartsOfficeRegisterResponseEntity;
+  };
+  /** Reintenta el acuse de recibo de un recibido ya ingresado. */
+  [PartsOfficePatterns.acknowledgeInbound]: {
+    payload: { id: string; actor: DocumentActor };
+    response: PartsOfficeOkResponseEntity;
+  };
+  /** Devuelve el recibido a la institución que lo envió, con el motivo (entre 3 y 255 caracteres). */
+  [PartsOfficePatterns.returnInbound]: {
+    payload: { id: string; reason: string; actor: DocumentActor };
+    response: PartsOfficeOkResponseEntity;
+  };
+  /** Archivo de un recibido: el principal o, con `attachment`, uno de sus anexos (por su posición). */
+  [PartsOfficePatterns.getInboundFile]: {
+    payload: { id: string; attachment?: number };
+    response: PartsOfficeFileEntity;
+  };
+}

package/src/contracts/procedure.contract.ts

@@ -0,0 +1,53 @@
+import { type ProcedureEntity } from '../base/entities';
+import {
+  type ProcedureCreateResponseEntity,
+  type ProcedureGetAllResponseEntity,
+  type ProcedureGetByIdResponseEntity,
+  type ProcedureUpdateResponseEntity,
+} from '../entities';
+import { type RpcPage } from './contract';
+
+/** Patrones NATS de `procedure`: `<servicio>.<recurso>.<acción>`. */
+export const ProcedurePatterns = {
+  getAll: 'gestorDocumental.procedure.getAll',
+  getById: 'gestorDocumental.procedure.getById',
+  create: 'gestorDocumental.procedure.create',
+  update: 'gestorDocumental.procedure.update',
+  setEnabled: 'gestorDocumental.procedure.setEnabled',
+} 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
+    payload: {
+      pagination?: { page?: number; limit?: number };
+      filters?: { search?: string; enabled?: boolean };
+    };
+    response: RpcPage<ProcedureGetAllResponseEntity[]>;
+  };
+  [ProcedurePatterns.getById]: {
+    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;
+  };
+}

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;
+  };
+}