Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -0,0 +1,431 @@
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<KwpProjectInboundSnapshot> {
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<KwpProjectInboundSnapshot> {
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<KwpArchiveDiscoveryBatch> {
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<KwpInboundAppointment[]> {
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<KwpInboundTask[]> {
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<KwpInboundMaterialPosition[]> {
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<typeof archiveEntrySchema>[]): 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<Row>(
area: "activity" | "archive" | "material",
loadPage: (offset: number) => Promise<readonly Row[]>,
): Promise<Row[]> {
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<Row extends { readonly externalId: string }>(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,
});