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

package/src/entities/document/document.entity.ts

@@ -1,13 +1,17 @@
 import {
+  type CommunicationMeans,
   DocumentAnnulledNumberEntity,
   DocumentAttachmentEntity,
   DocumentDeliveryEntity,
   DocumentEntity,
   DocumentParticipantEntity,
   DocumentRecipientEntity,
+  type DocumentStatus,
   DocumentTrackingEntity,
   DocumentTypeEntity,
 } from '../../base/entities';
+import { type RichLetterhead, type RichPage, type RichSpacing, type RichTextStyle } from './richStyle';
+import { type DocumentDraftingRequestEntity } from '../draftingRequest/draftingRequest.entity';
 
 /** Tipo documental de un documento, con lo necesario para citarlo. */
 export interface DocumentTypeSummaryEntity {
@@ -21,6 +25,8 @@ export interface DocumentParticipantResponseEntity {
   id: DocumentParticipantEntity['id'];
   role: DocumentParticipantEntity['role'];
   order: DocumentParticipantEntity['order'];
+  /** Los visadores de una misma etapa visan a la vez. */
+  stage: DocumentParticipantEntity['stage'];
   status: DocumentParticipantEntity['status'];
   employeeId: DocumentParticipantEntity['employeeId'];
   fullName: DocumentParticipantEntity['fullName'];
@@ -99,6 +105,14 @@ export interface DocumentDispatchResponseEntity {
   returnedAt: string | null;
   returnedByFullName: string | null;
   returnReason: string | null;
+  /** Registro por contingencia: salió por otro medio porque no se pudo por DocDigital. */
+  contingency: {
+    means: CommunicationMeans;
+    sentTo: string | null;
+    reason: string | null;
+    /** Nombre del comprobante, si se adjuntó. */
+    receiptName: string | null;
+  } | null;
 }
 
 export interface DocumentGetAllResponseEntity {
@@ -117,23 +131,49 @@ export interface DocumentGetAllResponseEntity {
   intakeNumber: DocumentEntity['intakeNumber'];
   intakeYear: DocumentEntity['intakeYear'];
   origin: DocumentEntity['origin'];
+  /** Con búsqueda de texto completo: el fragmento donde aparece lo buscado, con lo encontrado entre ⟦ y ⟧. */
+  snippet?: string | null;
   // A quién le toca visar o firmar (null si el documento no está en tramitación).
   currentParticipant: Pick<DocumentParticipantResponseEntity, 'role' | 'employeeId' | 'fullName'> | null;
+  // Cuántos más tienen el turno a la vez (visación en paralelo).
+  otherCurrentCount: number;
   // A cuántos funcionarios llegó y cuántos ya lo abrieron (null si aún no se distribuye a nadie).
   distribution: { total: number; read: number } | null;
 }
 
 /** Una entrada de la bandeja de recibidos: la entrega y el documento al que corresponde. */
+/** Semáforo de un plazo pendiente: a tiempo, por vencer (2 días hábiles o menos) o vencido. */
+export type DocumentDueStatus = 'OnTime' | 'DueSoon' | 'Overdue';
+
 export interface DocumentInboxItemEntity extends DocumentDeliveryResponseEntity {
+  /** Semáforo de lo pendiente con plazo (sin plazo o ya atendido, `null`). */
+  dueStatus: DocumentDueStatus | null;
+  /** Días hábiles que quedan, sin contar hoy (vencido: `null`). */
+  businessDaysLeft: number | null;
   document: DocumentLinkEntity;
 }
 
 export interface DocumentGetByIdResponseEntity {
   id: DocumentEntity['id'];
+  // Quién lo emite: la entidad emisora del tipo (Educación, Salud, Juzgado) o la municipalidad.
+  issuerName: string;
+  // Serie documental del Cuadro de Clasificación (la de su tipo documental; MGDDE1_2).
+  archivalSeries: { id: string; code: string; name: string } | null;
+  // Fin de la restricción de acceso: desde entonces se consulta como público si no tiene datos sensibles.
+  restrictionEndsAt: string | null;
   subject: DocumentEntity['subject'];
+  /** Resumen breve; va a DocDigital como «descripcion» al despacharlo. */
+  description: string | null;
+  /** Procedimiento administrativo al que corresponde. */
+  procedure: { id: string; name: string; cpatCode: string | null } | null;
   keywords: DocumentEntity['keywords'];
   accessLevel: DocumentEntity['accessLevel'];
   hasSensitiveData: DocumentEntity['hasSensitiveData'];
+  /**
+   * Formato del archivo vigente: la conformidad PDF/A que declara («PDF/A-2B») o «PDF». `null` si no se revisó (los
+   * documentos anteriores a esta revisión, o aún sin firmar).
+   */
+  fileFormat: DocumentEntity['fileFormat'];
   status: DocumentEntity['status'];
   correlative: DocumentEntity['correlative'];
   correlativeYear: DocumentEntity['correlativeYear'];
@@ -166,14 +206,27 @@ export interface DocumentGetByIdResponseEntity {
     employeeFullName: DocumentAnnulledNumberEntity['employeeFullName'];
     createdAt: DocumentAnnulledNumberEntity['createdAt'];
   }[];
-  // Plazo en que el redactor espera respuesta de los destinatarios.
+  // Plazo en que el redactor espera respuesta de los destinatarios: una fecha o, mientras no se finaliza, N días
+  // hábiles desde que lo reciban (al finalizar queda la fecha en `responseDueAt`).
   responseDueAt: DocumentEntity['responseDueAt'];
+  responseDueBusinessDays: number | null;
   // A quién va dirigido, como lo indicó el redactor (personas y áreas).
   recipients: DocumentRecipientResponseEntity[];
   // En la bandeja de quién está: destinatarios y derivaciones, con su lectura y atención.
   deliveries: DocumentDeliveryResponseEntity[];
   // Documento al que este responde, y los que le responden (solo los ya finalizados, más los propios de quien consulta).
   replyTo: DocumentLinkEntity | null;
+  /** Lote de firma al que pertenece. */
+  batch: { id: string; name: string } | null;
+  /** Contenido redactado en el sistema con una plantilla, para volver a editarlo (sin valor si se subió un PDF). */
+  composition: DocumentComposition | null;
+  /**
+   * Revisión del borrador antes de enviarlo a tramitación, si su tipo la exige: qué dirección revisa, las rondas (la
+   * más reciente primero) y si la versión vigente ya está aprobada. `null` si el tipo no la exige.
+   */
+  draftReview: DocumentDraftReviewInfoEntity | null;
+  /** Solicitud de redacción que atiende, si se redactó a pedido de otra área. */
+  draftingRequest: DocumentDraftingRequestEntity | null;
   replies: DocumentLinkEntity[];
   /** Expedientes en que está incorporado y que quien consulta puede ver. */
   caseFiles: { id: string; code: string; title: string; status: 'Open' | 'Closed' }[];
@@ -187,7 +240,13 @@ export interface DocumentGetByIdResponseEntity {
   /** Instituciones de DocDigital a quienes va dirigido, y su despacho por Oficina de Partes. */
   externalRecipients: DocumentExternalRecipientResponseEntity[];
   dispatch: DocumentDispatchResponseEntity | null;
+  // Copias por correo a quienes están fuera del Estado, con su envío y apertura.
+  emailCopies: DocumentEmailCopyResponseEntity[];
+  // El tipo como estaba en la versión con que se tramita (nombre, sigla y categoría de entonces).
   documentType: DocumentTypeSummaryEntity;
+  // Versión del tipo con que se tramita: la vigente mientras es borrador; desde que se envía, queda fija. `null` si
+  // el tipo ya no la tiene registrada.
+  documentTypeVersion: { version: number; current: boolean } | null;
   participants: DocumentParticipantResponseEntity[];
   attachments: {
     id: DocumentAttachmentEntity['id'];
@@ -200,6 +259,8 @@ export interface DocumentGetByIdResponseEntity {
     id: DocumentTrackingEntity['id'];
     action: DocumentTrackingEntity['action'];
     observation: DocumentTrackingEntity['observation'];
+    // Huella SHA-256 del PDF en ese hecho (firma, despacho o ingreso por DocDigital).
+    sha256: DocumentTrackingEntity['sha256'];
     employeeId: DocumentTrackingEntity['employeeId'];
     employeeFullName: DocumentTrackingEntity['employeeFullName'];
     createdAt: DocumentTrackingEntity['createdAt'];
@@ -217,6 +278,8 @@ export interface DocumentGetByIdResponseEntity {
     canReassign: boolean;
     /** Quien consulta redactó el documento (o lo ingresó, si llegó por DocDigital). */
     isAuthor: boolean;
+    /** Le toca aprobar o devolver el borrador: es la jefatura de la revisión pendiente. */
+    canResolveDraftReview: boolean;
     // Sus propias entregas de este documento (puede tener más de una si además se lo derivaron).
     inbox: DocumentDeliveryResponseEntity[];
   };
@@ -228,6 +291,12 @@ export interface DocumentGetByIdResponseEntity {
 export interface DocumentGetSummaryResponseEntity {
   toVisa: number;
   toSign: number;
+  /** Borradores que esperan su revisión (como jefatura de la dirección que los revisa). */
+  toReview: number;
+  /** Solicitudes de redacción: sin tomar dirigidas a su dirección, y tomadas por él aún sin atender. */
+  draftingRequests: { pending: number; taken: number };
+  /** Lotes de firma con documentos en su turno (los documentos de un lote no se cuentan en `toVisa` ni `toSign`). */
+  batches: { toVisa: number; toSign: number };
   created: {
     drafted: number;
     inProgress: number;
@@ -258,6 +327,29 @@ export interface DocumentReviewResponseEntity {
   status: DocumentEntity['status'];
 }
 
+/** Resultado de un documento en una firma de varios documentos. */
+export interface DocumentSignManyResultEntity {
+  id: DocumentEntity['id'];
+  ok: boolean;
+  /** Estado en que quedó, si se firmó. */
+  status?: DocumentEntity['status'];
+  /** Por qué no se firmó. */
+  message?: string;
+}
+
+/**
+ * Firma de varios documentos con un solo OTP. FirmaGob admite 5 MB por solicitud: los que no cupieron quedan en
+ * `remaining`, en el turno del firmante, para firmarlos con un OTP nuevo.
+ */
+export interface DocumentSignManyResponseEntity {
+  results: DocumentSignManyResultEntity[];
+  signed: number;
+  failed: number;
+  remaining: DocumentEntity['id'][];
+  /** FirmaGob avisó que el OTP venció antes de firmar todos los documentos de la solicitud. */
+  otpExpired: boolean;
+}
+
 export interface DocumentDiscardResponseEntity {
   id: DocumentEntity['id'];
   ok: boolean;
@@ -284,6 +376,8 @@ export interface DocumentVerifyResponseEntity {
   state: DocumentVerificationState;
   verificationCode: string;
   documentType: Pick<DocumentTypeSummaryEntity, 'name' | 'abbreviation'>;
+  // Quién lo emite: la entidad emisora del tipo (Educación, Salud, Juzgado) o la municipalidad.
+  issuerName: string;
   correlative: DocumentEntity['correlative'];
   correlativeYear: DocumentEntity['correlativeYear'];
   numberedAt: DocumentEntity['numberedAt'];
@@ -322,3 +416,321 @@ export interface DocumentReassignResponseEntity {
   id: DocumentEntity['id'];
   ok: boolean;
 }
+
+/**
+ * Un plazo en la agenda de un funcionario: lo que recibió (como destinatario o por derivación) y debe atender, o un
+ * documento que envió y del que espera respuesta.
+ */
+export interface DocumentAgendaItemEntity {
+  kind: 'Received' | 'Sent';
+  /** Semáforo de lo pendiente (atendido o ya respondido por todos: `null`). */
+  dueStatus: DocumentDueStatus | null;
+  /** Días hábiles que quedan, sin contar hoy (vencido: `null`). */
+  businessDaysLeft: number | null;
+  /** La entrega (lo recibido) o el documento (lo enviado). */
+  id: string;
+  documentId: DocumentEntity['id'];
+  subject: DocumentEntity['subject'];
+  documentType: { name: string; abbreviation: string | null };
+  correlative: DocumentEntity['correlative'];
+  correlativeYear: DocumentEntity['correlativeYear'];
+  intakeNumber: DocumentEntity['intakeNumber'];
+  intakeYear: DocumentEntity['intakeYear'];
+  /** Plazo, en ISO 8601. */
+  dueAt: string;
+  /** Lo recibido: cuándo lo marcó como atendido (sin valor si sigue pendiente). */
+  closedAt: string | null;
+  /** Lo recibido: la providencia y quién lo derivó. */
+  instruction: DocumentDeliveryEntity['instruction'] | null;
+  sentByFullName: string | null;
+  /** Lo enviado: a cuántos les llegó y cuántos aún no lo atienden. */
+  recipients: { total: number; pending: number } | null;
+}
+
+export interface DocumentAgendaResponseEntity {
+  /** Plazos dentro del período pedido. */
+  items: DocumentAgendaItemEntity[];
+  /** Lo recibido con el plazo vencido y sin atender, de cualquier fecha (los 50 más antiguos). */
+  overdue: DocumentAgendaItemEntity[];
+}
+
+/** Trazabilidad de un documento en PDF, lista para descargar. */
+export interface DocumentTrailExportEntity {
+  fileName: string;
+  contentType: string;
+  contentBase64: string;
+}
+
+/** Plantilla oficial con que se redacta un documento en el sistema. */
+export type DocumentTemplateKind = 'Decree' | 'Office' | 'Memorandum' | 'General';
+
+/** Formato de un trozo de texto en el editor del gestor. Superíndice y subíndice no van juntos. */
+export type RichMark = 'bold' | 'italic' | 'underline' | 'strike' | 'superscript' | 'subscript';
+
+/**
+ * Texto con su formato, o un campo de la plantilla (`field`: su clave), que se reemplaza por su valor al armar el PDF.
+ * Un salto de línea dentro del texto (`\n`) es un salto de línea del párrafo.
+ */
+export type RichInline =
+  | { text: string; marks?: RichMark[]; style?: RichTextStyle }
+  | { field: string; marks?: RichMark[]; style?: RichTextStyle };
+
+export type RichAlign = 'left' | 'center' | 'right' | 'justify';
+
+/** Numeración de una lista: viñetas, «1.» o la de los decretos, «1.-». */
+export type RichListStyle = 'bullet' | 'decimal' | 'decree';
+
+/**
+ * Cómo se ve una tabla: con bordes (`grid`), o como las líneas «DE:», «A:», «MAT.:» de un oficio, con la etiqueta en
+ * negrita y sin bordes (`labels`, o `labelsRight`, en la mitad derecha, como «ANT.» y «MAT.» de un oficio).
+ */
+export type RichTableVariant = 'grid' | 'labels' | 'labelsRight';
+
+/**
+ * Un bloque del texto. Los de una plantilla pueden ser fijos (`locked`): quien redacta no los cambia. Las listas son
+ * bloques seguidos del mismo estilo (su nivel es la sangría, desde 0); un título o un párrafo reinicia la numeración.
+ */
+export type RichBlock =
+  | { id: string; type: 'paragraph'; align?: RichAlign; spacing?: RichSpacing; locked?: boolean; content: RichInline[] }
+  | {
+      id: string;
+      type: 'heading';
+      level: 1 | 2;
+      align?: RichAlign;
+      spacing?: RichSpacing;
+      locked?: boolean;
+      content: RichInline[];
+    }
+  | {
+      id: string;
+      type: 'listItem';
+      list: RichListStyle;
+      level: number;
+      spacing?: RichSpacing;
+      locked?: boolean;
+      content: RichInline[];
+    }
+  /** Imagen registrada en el gestor (`imageId`), con su ancho en puntos (sin pasar el del texto) y alineación. */
+  | {
+      id: string;
+      type: 'image';
+      imageId: string;
+      width: number;
+      align?: 'left' | 'center' | 'right';
+      caption?: string;
+      locked?: boolean;
+    }
+  /** `rows[fila][columna]`: el contenido de cada celda. */
+  | { id: string; type: 'table'; variant: RichTableVariant; locked?: boolean; rows: RichInline[][][] }
+  | { id: string; type: 'rule'; locked?: boolean }
+  | { id: string; type: 'pageBreak'; locked?: boolean };
+
+/**
+ * Campo de una plantilla, con el valor que le dio quien redacta. `materia` es el asunto del documento: no se escribe
+ * aparte.
+ */
+export interface RichField {
+  key: string;
+  label: string;
+  value: string;
+  required?: boolean;
+}
+
+/**
+ * Contenido de un documento redactado en el sistema. Cada plantilla tiene su estructura; los párrafos son texto
+ * (un salto de línea dentro de un párrafo se respeta). La materia es el asunto del documento.
+ */
+export type DocumentComposition =
+  | {
+      template: 'Decree';
+      /** VISTOS: las normas y antecedentes. */
+      vistos: string[];
+      /** CONSIDERANDO: cada fundamento, numerado. */
+      considerando: string[];
+      /** DECRETO: cada punto resolutivo, numerado. */
+      resolutive: string[];
+      /** Fórmula de cierre: «Anótese, comuníquese y archívese». */
+      closing: string;
+      distribution: string[];
+    }
+  | {
+      template: 'Office';
+      /** ANT.: antecedentes (otro oficio, una solicitud). */
+      antecedents?: string | null;
+      from: string;
+      to: string;
+      body: string[];
+      closing: string;
+      distribution: string[];
+    }
+  | {
+      template: 'Memorandum';
+      from: string;
+      to: string;
+      body: string[];
+      closing?: string | null;
+      distribution: string[];
+    }
+  | { template: 'General'; title: string; body: string[]; closing?: string | null }
+  /**
+   * Redactado con el editor del gestor: los bloques del texto, los campos de la plantilla con su valor y la
+   * distribución. `templateKey` y `templateVersion`: de qué plantilla salió, si salió de una.
+   */
+  | {
+      template: 'Rich';
+      templateKey?: string | null;
+      templateVersion?: number | null;
+      blocks: RichBlock[];
+      fields: RichField[];
+      distribution: string[];
+      /** Página y membrete. En una plantilla propia los pone su versión: lo que mande el navegador no cuenta. */
+      page?: RichPage;
+      letterhead?: RichLetterhead;
+    };
+
+/** PDF armado con una plantilla: para la vista previa (`contentBase64`) o ya subido (`fileId`). */
+export interface DocumentComposeResponseEntity {
+  fileName: string;
+  fileId?: string;
+  contentBase64?: string;
+}
+
+/** Copia por correo de un documento, como la ve quien lo consulta en el gestor. */
+export interface DocumentEmailCopyResponseEntity {
+  id: string;
+  name: string;
+  email: string;
+  /** Cuándo se envió (sin valor: aún no corresponde). */
+  issuedAt: string | null;
+  expiresAt: string | null;
+  openedAt: string | null;
+  downloadCount: number;
+}
+
+/** Copia recién emitida: el gateway le envía el enlace a su destinatario. El token viaja solo aquí. */
+export interface DocumentEmailCopyIssuedEntity {
+  copyId: string;
+  documentId: string;
+  name: string;
+  email: string;
+  token: string;
+  expiresAt: string;
+  /** Cómo se cita: «D.E. N° 590/2026», o el tipo si no lleva número. */
+  folio: string;
+  subject: string;
+  issuerName: string;
+}
+
+/** El documento como lo ve quien abre su copia por correo. */
+export interface DocumentEmailCopyViewEntity {
+  recipientName: string;
+  expiresAt: string;
+  documentTypeName: string;
+  folio: string;
+  subject: string;
+  issuerName: string;
+  finishedAt: string | null;
+  verificationCode: string | null;
+  signers: { fullName: string; position: string | null; signedAt: string | null }[];
+}
+
+/** Recordatorio de un plazo: al recibido y, si venció, también a su jefatura (la resuelve el gateway). */
+export interface DocumentReminderEntity {
+  deliveryId: string;
+  kind: 'DueSoon' | 'Overdue';
+  employeeId: string;
+  fullName: string;
+  documentId: string;
+  /** Cómo se cita: «D.E. N° 590/2026», el folio de ingreso o el tipo. */
+  folio: string;
+  subject: string;
+  dueAt: string;
+  instruction: DocumentDeliveryEntity['instruction'];
+  sentByFullName: string | null;
+}
+
+/** Quien visó, firmó o rechazó una versión, según la trazabilidad. */
+export interface DocumentVersionReviewEntity {
+  action: 'Visaed' | 'Signed' | 'Rejected';
+  employeeFullName: string;
+  createdAt: string;
+}
+
+/** Una versión de un documento: lo que se guardó cada vez que cambió su PDF, su texto o su asunto. */
+export interface DocumentVersionResponseEntity {
+  number: number;
+  subject: string;
+  fileName: string;
+  sha256: string | null;
+  /** Lo redactado con plantilla, para compararla con otra versión. `null` si se subió un PDF. */
+  composition: DocumentComposition | null;
+  note: string | null;
+  status: DocumentStatus;
+  createdByFullName: string;
+  createdAt: string;
+  /** Visaciones, firmas y rechazos mientras fue la versión vigente. */
+  reviews: DocumentVersionReviewEntity[];
+}
+
+/** Comentario de redacción de un visador, un firmante o el redactor. */
+export interface DocumentCommentResponseEntity {
+  id: string;
+  versionNumber: number;
+  section: string | null;
+  quote: string | null;
+  text: string;
+  authorEmployeeId: string;
+  authorFullName: string;
+  /** `Review`: la jefatura que revisa el borrador antes de enviarlo a tramitación. */
+  authorRole: 'Author' | 'Visa' | 'Signature' | 'Review';
+  createdAt: string;
+  resolvedAt: string | null;
+  resolvedByFullName: string | null;
+  resolutionNote: string | null;
+  /** Quien consulta lo puede marcar como resuelto: el redactor o quien lo escribió, mientras el documento se tramita. */
+  canResolve: boolean;
+}
+
+export interface DocumentCommentsResponseEntity {
+  comments: DocumentCommentResponseEntity[];
+  /** Quien consulta puede comentar: es el redactor o tiene un turno, y el documento no ha terminado. */
+  canComment: boolean;
+  currentVersion: number;
+}
+
+/** Una ronda de revisión del borrador. */
+export interface DocumentDraftReviewRoundEntity {
+  id: string;
+  round: number;
+  /** Versión del borrador que se revisó. */
+  versionNumber: number;
+  directorateName: string;
+  reviewerEmployeeId: string;
+  reviewerFullName: string;
+  requestedByFullName: string;
+  requestedAt: string;
+  status: 'Pending' | 'Approved' | 'Rejected' | 'Cancelled';
+  observation: string | null;
+  resolvedAt: string | null;
+}
+
+/** La revisión del borrador que exige el tipo documental. */
+export interface DocumentDraftReviewInfoEntity {
+  directorateCodeReference: number;
+  directorateName: string;
+  rounds: DocumentDraftReviewRoundEntity[];
+  /** La versión vigente del borrador está aprobada: se puede enviar a tramitación. */
+  approved: boolean;
+  /** Hay una ronda esperando respuesta: el borrador no se edita mientras tanto. */
+  pending: boolean;
+}
+
+/** Resultado de pedir, resolver o retirar una revisión del borrador. */
+export interface DocumentDraftReviewResponseEntity {
+  id: string;
+  ok: boolean;
+  round: number;
+  status: DocumentDraftReviewRoundEntity['status'];
+  /** A quién avisar: la jefatura revisora (al pedirla) o el redactor (al resolverla). */
+  notify: { employeeId: string; fullName: string } | null;
+}

package/src/entities/document/index.ts

@@ -1 +1,2 @@
 export * from './document.entity';
+export * from './richStyle';