From 8c89cd05c9aa045ece3d957aab94c7c0ff43749a Mon Sep 17 00:00:00 2001
From: enlineawork <enlinea.work@gmail.com>
Date: Tue, 8 Sep 2026 10:23:49 -0300
Subject: [PATCH] feat(f4): add explicit act lifecycle web contract

---
 web-v2/src/lib/inspectionActF4Api.ts | 204 +++++++++++++++++++++++++++
 1 file changed, 204 insertions(+)
 create mode 100644 web-v2/src/lib/inspectionActF4Api.ts

diff --git a/web-v2/src/lib/inspectionActF4Api.ts b/web-v2/src/lib/inspectionActF4Api.ts
new file mode 100644
index 0000000..e42373f
--- /dev/null
+++ b/web-v2/src/lib/inspectionActF4Api.ts
@@ -0,0 +1,204 @@
+import {
+  apiRequest,
+  type InspectionActResponsible,
+  type InspectionActSignature,
+  type InspectionActUploadMode,
+  type InspectionAssetSummary,
+  type InspectionPerson,
+  type InspectionReportPdfStatus,
+  type InspectionReportStatus,
+  type InspectionVisitStatus,
+  type PageMeta,
+} from './api';
+
+export type InspectionActStatusF4 =
+  | 'DRAFT'
+  | 'LOCKED'
+  | 'SEALED'
+  | 'CANCELLED'
+  // Valores históricos conservados sólo para lectura de registros anteriores a F4.
+  | 'READY'
+  | 'CLOSED'
+  | 'RECTIFIED';
+
+export type InspectionActVersionEventF4 =
+  | 'CREATED'
+  | 'UPDATED'
+  | 'LOCKED'
+  | 'SEALED'
+  | 'CANCELLED'
+  // Eventos históricos conservados sólo para lectura.
+  | 'READY'
+  | 'REOPENED'
+  | 'CLOSED';
+
+export type InspectionActUrgencyF4 = 'URGENT' | 'NON_URGENT';
+export type InspectionDeadlineDayTypeF4 = 'BUSINESS' | 'CALENDAR';
+export type InspectionDeadlineBasisF4 = 'ACT_DATE' | 'GEDO_DATE';
+
+export interface InspectionActListItemF4 {
+  id: string;
+  visitId: string;
+  visit: {
+    id: string;
+    code: string;
+    status: InspectionVisitStatus;
+    actualStartedAt: string | null;
+  };
+  actYear: number;
+  actNumber: number;
+  code: string;
+  status: InspectionActStatusF4;
+  occurredAt: string;
+  title: string;
+  summary: string;
+  observations: string | null;
+  urgency: InspectionActUrgencyF4;
+  deadlineDays: number | null;
+  deadlineDayType: InspectionDeadlineDayTypeF4 | null;
+  deadlineBasis: InspectionDeadlineBasisF4 | null;
+  deadlineBaseAt: string | null;
+  deadlineAt: string | null;
+  lockedAt: string | null;
+  lockedBy: string | null;
+  lockedSha256: string | null;
+  sealedAt: string | null;
+  sealedBy: string | null;
+  currentVersion: number;
+  cancellationReason: string | null;
+  closedAt: string | null;
+  closedBy: string | null;
+  closureSha256: string | null;
+  assetCount: number;
+  findingCount: number;
+  companies: Array<{ id: string; code: string; name: string }>;
+  areas: Array<{ id: string; code: string; name: string }>;
+  report: null | {
+    id: string;
+    code: string;
+    status: InspectionReportStatus;
+    pdfStatus: InspectionReportPdfStatus;
+    generatedAt: string;
+  };
+  createdBy: InspectionPerson | null;
+  updatedBy: InspectionPerson | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface InspectionActVersionF4 {
+  id: string;
+  versionNumber: number;
+  event: InspectionActVersionEventF4;
+  snapshot: Record<string, unknown>;
+  actorUserId: string | null;
+  actorUsername: string | null;
+  createdAt: string;
+}
+
+export interface InspectionActF4 extends InspectionActListItemF4 {
+  assets: InspectionAssetSummary[];
+  versions: InspectionActVersionF4[];
+}
+
+export interface InspectionClosureF4 {
+  act: {
+    id: string;
+    code: string;
+    status: InspectionActStatusF4;
+    visitId: string;
+    urgency: InspectionActUrgencyF4;
+    deadlineDays: number | null;
+    deadlineDayType: InspectionDeadlineDayTypeF4 | null;
+    deadlineBasis: InspectionDeadlineBasisF4 | null;
+    deadlineBaseAt: string | null;
+    deadlineAt: string | null;
+    lockedAt: string | null;
+    lockedSha256: string | null;
+    sealedAt: string | null;
+    currentVersion: number;
+    closedAt: string | null;
+    closedBy: string | null;
+    closureSha256: string | null;
+  };
+  visit: {
+    id: string;
+    code: string;
+    status: InspectionVisitStatus;
+    actualClosedAt: string | null;
+  };
+  responsible: InspectionActResponsible | null;
+  closure: null | {
+    schemaVersion: string;
+    preparedSha256: string;
+    preparedAt: string;
+    preparedBy: string;
+    finalSha256: string | null;
+    deviceClosedAt: string | null;
+    serverClosedAt: string | null;
+    uploadMode: InspectionActUploadMode | null;
+    closedBy: string | null;
+    isCurrent: boolean;
+  };
+  signatures: InspectionActSignature[];
+  consents: {
+    version: string;
+    inspector: string;
+    company: string;
+  };
+}
+
+export interface InspectionActPageF4 {
+  data: InspectionActListItemF4[];
+  meta: PageMeta;
+}
+
+export function listInspectionActsF4(visitId: string, params: {
+  page?: number;
+  pageSize?: number;
+  search?: string;
+  status?: InspectionActStatusF4 | '';
+} = {}) {
+  const query = new URLSearchParams({
+    page: String(params.page ?? 1),
+    pageSize: String(params.pageSize ?? 25),
+  });
+  if (params.search) query.set('search', params.search);
+  if (params.status) query.set('status', params.status);
+  return apiRequest<InspectionActPageF4>(`/inspection-visits/${visitId}/acts?${query}`);
+}
+
+export function listInspectionActsGlobalF4(params: {
+  page?: number;
+  pageSize?: number;
+  search?: string;
+  status?: InspectionActStatusF4 | '';
+  year?: number | '';
+  companyId?: string;
+  areaId?: string;
+  inspectorId?: string;
+  dateFrom?: string;
+  dateTo?: string;
+} = {}) {
+  const query = new URLSearchParams({
+    page: String(params.page ?? 1),
+    pageSize: String(params.pageSize ?? 25),
+  });
+  if (params.search) query.set('search', params.search);
+  if (params.status) query.set('status', params.status);
+  if (params.year) query.set('year', String(params.year));
+  if (params.companyId) query.set('companyId', params.companyId);
+  if (params.areaId) query.set('areaId', params.areaId);
+  if (params.inspectorId) query.set('inspectorId', params.inspectorId);
+  if (params.dateFrom) query.set('dateFrom', params.dateFrom);
+  if (params.dateTo) query.set('dateTo', params.dateTo);
+  return apiRequest<InspectionActPageF4>(`/inspection-acts?${query}`);
+}
+
+export function getInspectionActF4(id: string) {
+  return apiRequest<InspectionActF4>(`/inspection-acts/${id}`);
+}
+
+export function getInspectionClosureF4(actId: string) {
+  return apiRequest<InspectionClosureF4>(`/inspection-acts/${actId}/closure`);
+}