import { z } from "zod"; import { executeKwpReadOperation } from "./resource-client.server.js"; const PAGE_SIZE = 100; const MAX_PAGED_ITEMS = 500; const ARCHIVE_FOLDER_BATCH_SIZE = 5; const MAX_ARCHIVE_FOLDERS = 1_000; const MAX_ARCHIVE_FILE_BYTES = 100 * 1024 * 1024; const MIN_KWP_FOLDER_ID = -2_147_483_648; const MAX_KWP_FOLDER_ID = 2_147_483_647; const PROJECT_RESULT_KIND = 1; const PROJECT_ARCHIVE_REFERENCE_KIND = 1; const nullableText = z.string().nullable().optional(); const nullableDate = z.string().datetime({ offset: true }).nullable().optional(); const appointmentSchema = z.object({ terminId: z.number().int(), terminVon: nullableDate, terminBis: nullableDate, betreff: nullableText, beschreibung: nullableText, statusId: z.number().int(), typId: z.number().int(), privat: z.boolean(), }).passthrough(); const projectScheduleSchema = z.object({ projektnummer: nullableText, termine: z.array(appointmentSchema).nullable().optional(), }).passthrough(); const activitySchema = z.object({ aktivitaetenId: z.number().int(), betreff: nullableText, datumWiedervorlage: nullableDate, datumZuErledigenBis: nullableDate, datumErledigt: nullableDate, status: z.union([z.literal(100), z.literal(200), z.literal(210), z.literal(300)]), privat: z.boolean().nullable().optional(), }).passthrough(); const materialPositionSchema = z.object({ positionNummer: nullableText, menge: z.number().finite().nullable().optional(), text: nullableText, einheit: nullableText, positionKennzeichen: z.number().int(), einzelpreis: z.number().finite().nullable().optional(), gesamtpreis: z.number().finite().nullable().optional(), langtext: nullableText, }).passthrough(); const archiveFolderSchema = z.object({ id: z.number().int(), bezeichnung: nullableText, anzahlEintraege: z.number().int(), gesperrt: z.boolean(), }).passthrough(); const archiveDirectorySchema = z.object({ verzeichnisId: z.number().int(), benutzerOrdner: z.array(archiveFolderSchema).nullable().optional(), standardOrdner: z.array(archiveFolderSchema).nullable().optional(), anzahlEintraege: z.number().int(), }).passthrough(); const archiveEntryFileSchema = z.object({ id: z.number().int(), revisionId: z.number().int(), revision: z.number().int(), dateityp: nullableText, dateiname: nullableText, link: z.boolean(), sizeInByte: z.number().int().nullable().optional(), }).passthrough(); const archiveEntrySchema = z.object({ betreff: nullableText, dokumenttyp: nullableText, letzteAenderungAm: nullableDate, headerId: z.number().int(), ordnerId: z.number().int(), files: z.array(archiveEntryFileSchema).nullable().optional(), }).passthrough(); export type KwpInboundAppointment = { readonly externalId: string; readonly title: string; readonly description: string | null; readonly startsAt: string; readonly endsAt: string | null; readonly statusId: number; readonly typeId: number; }; export type KwpInboundTask = { readonly externalId: string; readonly title: string; readonly status: "open" | "in_progress" | "blocked" | "done"; readonly deadline: string | null; readonly completedAt: string | null; }; export type KwpInboundMaterialPosition = { readonly externalId: string; readonly positionNumber: string | null; readonly text: string; readonly longText: string | null; readonly quantity: number | null; readonly unit: string | null; readonly unitPrice: number | null; readonly totalPrice: number | null; readonly positionMarker: number; }; export type KwpInboundArchiveFile = { readonly externalId: string; readonly headerId: number; readonly revisionId: number; readonly revision: number; readonly folderId: number; readonly displayName: string; readonly documentType: string | null; readonly providerFileType: string | null; readonly providerSizeBytes: number | null; readonly lastModifiedAt: string | null; }; export type KwpProjectInboundSnapshot = { readonly appointments: readonly KwpInboundAppointment[]; readonly tasks: readonly KwpInboundTask[]; readonly materialPositions: readonly KwpInboundMaterialPosition[]; }; export type KwpInboundArea = "appointments" | "tasks" | "material"; export type KwpArchiveDiscoveryCursor = { readonly pendingFolderIds: readonly number[]; readonly visitedFolderIds: readonly number[]; }; export type KwpArchiveDiscoveryBatch = { readonly archiveFiles: readonly KwpInboundArchiveFile[]; readonly processedFolders: number; readonly cursor: KwpArchiveDiscoveryCursor | null; }; export class KwpInboundLimitError extends Error { constructor(readonly area: "activity" | "archive" | "material") { super(`KWP inbound ${area} result exceeded the bounded import window.`); this.name = "KwpInboundLimitError"; } } export async function loadKwpProjectInboundSnapshot(input: { readonly connectionId: string; readonly externalProjectNumber: string; readonly now?: Date; }): Promise { const projectNumber = normalizeProjectNumber(input.externalProjectNumber); const now = input.now ?? new Date(); const [appointments, tasks, materialPositions] = await Promise.all([ loadAppointments(input.connectionId, projectNumber, now), loadTasks(input.connectionId, projectNumber), loadMaterialPositions(input.connectionId, projectNumber), ]); return { appointments, tasks, materialPositions }; } export async function loadKwpProjectInboundArea(input: { readonly area: KwpInboundArea; readonly connectionId: string; readonly externalProjectNumber: string; readonly now?: Date; }): Promise { const projectNumber = normalizeProjectNumber(input.externalProjectNumber); const empty = { appointments: [], tasks: [], materialPositions: [] } satisfies KwpProjectInboundSnapshot; if (input.area === "appointments") { return { ...empty, appointments: await loadAppointments(input.connectionId, projectNumber, input.now ?? new Date()) }; } if (input.area === "tasks") { return { ...empty, tasks: await loadTasks(input.connectionId, projectNumber) }; } return { ...empty, materialPositions: await loadMaterialPositions(input.connectionId, projectNumber) }; } export async function loadKwpArchiveDiscoveryBatch(input: { readonly connectionId: string; readonly externalProjectNumber: string; readonly cursor?: KwpArchiveDiscoveryCursor; }): Promise { const projectNumber = normalizeProjectNumber(input.externalProjectNumber); const cursor = normalizeArchiveCursor(input.cursor); const pending = [...cursor.pendingFolderIds]; const visited = new Set(cursor.visitedFolderIds); const files: KwpInboundArchiveFile[] = []; let processedFolders = 0; while (pending.length > 0 && processedFolders < ARCHIVE_FOLDER_BATCH_SIZE) { const folderId = pending.shift()!; if (visited.has(folderId)) continue; if (visited.size >= MAX_ARCHIVE_FOLDERS) throw new KwpInboundLimitError("archive"); visited.add(folderId); processedFolders += 1; const directory = archiveDirectorySchema.parse(await executeKwpReadOperation({ connectionId: input.connectionId, operationId: "archivExternalLoadVerzeichnisse", operationInput: { query: { bezugsart: PROJECT_ARCHIVE_REFERENCE_KIND, bezugsnummer: projectNumber, verzeichnisId: folderId, }, }, })); for (const folder of [...(directory.benutzerOrdner ?? []), ...(directory.standardOrdner ?? [])]) { if (!folder.gesperrt && !visited.has(folder.id) && !pending.includes(folder.id)) pending.push(folder.id); } if (new Set([...visited, ...pending]).size > MAX_ARCHIVE_FOLDERS) throw new KwpInboundLimitError("archive"); const entries = await loadPaged("archive", async (offset) => { const response = await executeKwpReadOperation({ connectionId: input.connectionId, operationId: "archivExternalLoadDateienByVerzeichnisId", operationInput: { query: { bezugsart: PROJECT_ARCHIVE_REFERENCE_KIND, bezugsnummer: projectNumber, verzeichnisId: folderId, offset, count: PAGE_SIZE, }, }, }); return z.array(archiveEntrySchema).parse(response); }); files.push(...mapArchiveFiles(entries)); } return { archiveFiles: deduplicateByExternalId(files), processedFolders, cursor: pending.length > 0 ? { pendingFolderIds: pending, visitedFolderIds: [...visited] } : null, }; } async function loadAppointments(connectionId: string, projectNumber: string, now: Date): Promise { const from = new Date(now); from.setUTCMonth(from.getUTCMonth() - 3); const until = new Date(now); until.setUTCFullYear(until.getUTCFullYear() + 1); const response = await executeKwpReadOperation({ connectionId, operationId: "monteursteuerungLoadTermineProjektplanung", operationInput: { body: { von: from.toISOString(), bis: until.toISOString(), nurProjekteMitTerminen: true, maxAnzahlProjekte: 1_000, }, }, }); const projects = z.array(projectScheduleSchema).parse(response); const project = projects.find((entry) => entry.projektnummer?.trim() === projectNumber); return (project?.termine ?? []) .filter((entry) => entry.privat !== true && Boolean(entry.terminVon)) .map((entry) => ({ externalId: String(entry.terminId), title: normalizeText(entry.betreff, `KWP-Termin ${entry.terminId}`), description: normalizeOptionalText(entry.beschreibung), startsAt: entry.terminVon!, endsAt: entry.terminBis ?? null, statusId: entry.statusId, typeId: entry.typId, })); } async function loadTasks(connectionId: string, projectNumber: string): Promise { const rows = await loadPaged("activity", async (offset) => { const response = await executeKwpReadOperation({ connectionId, operationId: "aktivitaetenverwaltungLoadAktivitaetenByVorgang", operationInput: { query: { vorgangNr: projectNumber, vorgangArt: 0, offset, count: PAGE_SIZE, filterTyp: 0, }, }, }); return z.array(activitySchema).parse(response); }); return rows .filter((entry) => entry.privat !== true) .map((entry) => ({ externalId: String(entry.aktivitaetenId), title: normalizeText(entry.betreff, `KWP-Aktivität ${entry.aktivitaetenId}`), status: mapActivityStatus(entry.status), deadline: entry.datumZuErledigenBis ?? entry.datumWiedervorlage ?? null, completedAt: entry.status === 300 ? (entry.datumErledigt ?? null) : null, })); } async function loadMaterialPositions(connectionId: string, projectNumber: string): Promise { const rows = await loadPaged("material", async (offset) => { const response = await executeKwpReadOperation({ connectionId, operationId: "vorgangAnzeigeLoadPositionen", operationInput: { body: { art: PROJECT_RESULT_KIND, vorgangNr: projectNumber, count: PAGE_SIZE, offset, mitLangtext: true, }, }, }); return z.array(materialPositionSchema).parse(response); }); return rows.map((entry, index) => { const positionNumber = normalizeOptionalText(entry.positionNummer); const stablePart = positionNumber ?? `unnummeriert-${index + 1}`; return { externalId: `${projectNumber}:${stablePart}`, positionNumber, text: normalizeText(entry.text, `KWP-Position ${stablePart}`), longText: normalizeOptionalText(entry.langtext), quantity: entry.menge ?? null, unit: normalizeOptionalText(entry.einheit), unitPrice: entry.einzelpreis ?? null, totalPrice: entry.gesamtpreis ?? null, positionMarker: entry.positionKennzeichen, }; }); } function mapArchiveFiles(entries: readonly z.infer[]): KwpInboundArchiveFile[] { const files: KwpInboundArchiveFile[] = []; for (const entry of entries) { for (const file of entry.files ?? []) { if (file.link || (file.sizeInByte ?? 0) > MAX_ARCHIVE_FILE_BYTES) continue; files.push({ externalId: `${entry.headerId}:${file.id}:${file.revisionId}`, headerId: entry.headerId, revisionId: file.revisionId, revision: file.revision, folderId: entry.ordnerId, displayName: normalizeText(file.dateiname, normalizeText(entry.betreff, `KWP-Datei ${file.id}`)), documentType: normalizeOptionalText(entry.dokumenttyp), providerFileType: normalizeOptionalText(file.dateityp), providerSizeBytes: file.sizeInByte ?? null, lastModifiedAt: entry.letzteAenderungAm ?? null, }); } } return files; } function normalizeArchiveCursor(cursor: KwpArchiveDiscoveryCursor | undefined): KwpArchiveDiscoveryCursor { if (!cursor) return { pendingFolderIds: [0], visitedFolderIds: [] }; const pendingFolderIds = normalizeFolderIds(cursor.pendingFolderIds); const visitedFolderIds = normalizeFolderIds(cursor.visitedFolderIds); if (pendingFolderIds.length === 0 || pendingFolderIds.length + visitedFolderIds.length > MAX_ARCHIVE_FOLDERS) { throw new KwpInboundLimitError("archive"); } return { pendingFolderIds, visitedFolderIds }; } function normalizeFolderIds(values: readonly number[]): number[] { if ( !Array.isArray(values) || values.some((value) => !Number.isInteger(value) || value < MIN_KWP_FOLDER_ID || value > MAX_KWP_FOLDER_ID) ) { throw new Error("KWP archive cursor is invalid."); } return [...new Set(values)]; } async function loadPaged( area: "activity" | "archive" | "material", loadPage: (offset: number) => Promise, ): Promise { const rows: Row[] = []; while (rows.length < MAX_PAGED_ITEMS) { const page = await loadPage(rows.length); rows.push(...page); if (page.length < PAGE_SIZE) return rows; } throw new KwpInboundLimitError(area); } function mapActivityStatus(status: 100 | 200 | 210 | 300): KwpInboundTask["status"] { if (status === 200) return "in_progress"; if (status === 210) return "blocked"; if (status === 300) return "done"; return "open"; } function normalizeProjectNumber(value: string): string { const normalized = value.trim(); if (!normalized || normalized.length > 191) throw new Error("KWP project number is invalid."); return normalized; } function normalizeText(value: string | null | undefined, fallback: string): string { return normalizeOptionalText(value) ?? fallback; } function normalizeOptionalText(value: string | null | undefined): string | null { const normalized = value?.trim(); return normalized ? normalized.slice(0, 2_000) : null; } function deduplicateByExternalId(rows: readonly Row[]): Row[] { return [...new Map(rows.map((row) => [row.externalId, row])).values()]; } export const KWP_INBOUND_BOUNDS = Object.freeze({ archiveFolderBatchSize: ARCHIVE_FOLDER_BATCH_SIZE, maxArchiveFileBytes: MAX_ARCHIVE_FILE_BYTES, maxArchiveFolders: MAX_ARCHIVE_FOLDERS, maxPagedItems: MAX_PAGED_ITEMS, pageSize: PAGE_SIZE, });