Add portable project transfer API

src/db/repositories/project-transfer.repository.ts

@@ -0,0 +1,135 @@
+import crypto from "node:crypto";
+import { eq } from "drizzle-orm";
+import {
+  createProjectTransferEnvelope,
+  parseProjectTransferEnvelope,
+  remapProjectState,
+} from "../../domain/models/project-transfer.model.js";
+import { createProjectStateRestoreCommand } from "../../domain/models/project-state-restore-command.model.js";
+import type { ProjectTransferStore } from "../../domain/ports/project-transfer.store.js";
+import type { AppDatabase } from "../database-context.js";
+import { circuitDeviceRows } from "../schema/circuit-device-rows.js";
+import { circuitLists } from "../schema/circuit-lists.js";
+import { circuitSections } from "../schema/circuit-sections.js";
+import { circuits } from "../schema/circuits.js";
+import { distributionBoards } from "../schema/distribution-boards.js";
+import { floors } from "../schema/floors.js";
+import { projectDevices } from "../schema/project-devices.js";
+import { projects } from "../schema/projects.js";
+import { rooms } from "../schema/rooms.js";
+import {
+  hashProjectStatePayload,
+  readProjectStateSnapshot,
+} from "./project-state-snapshot.persistence.js";
+import { serializeProjectStateSnapshot } from "../../domain/models/project-state-snapshot.model.js";
+
+export class ProjectTransferRepository implements ProjectTransferStore {
+  constructor(private readonly database: AppDatabase) {}
+
+  exportProject(projectId: string) {
+    const snapshot = readProjectStateSnapshot(this.database, projectId);
+    if (!snapshot) {
+      return null;
+    }
+    return createProjectTransferEnvelope(
+      new Date().toISOString(),
+      snapshot.payloadSha256,
+      snapshot.state
+    );
+  }
+
+  prepareReplace(projectId: string, value: unknown) {
+    const transfer = this.parseVerified(value);
+    const current = readProjectStateSnapshot(this.database, projectId);
+    if (!current) {
+      return null;
+    }
+    const targetState =
+      transfer.projectState.project.id === projectId
+        ? transfer.projectState
+        : remapProjectState(
+            transfer.projectState,
+            projectId,
+            () => crypto.randomUUID()
+          );
+    return {
+      command: createProjectStateRestoreCommand(
+        current.payloadSha256,
+        targetState
+      ),
+    };
+  }
+
+  importDuplicate(value: unknown) {
+    const transfer = this.parseVerified(value);
+    const projectId = crypto.randomUUID();
+    const state = remapProjectState(
+      transfer.projectState,
+      projectId,
+      () => crypto.randomUUID(),
+      `${transfer.projectState.project.name} (Kopie)`
+    );
+    this.database.transaction((tx) => insertProjectState(tx, state));
+    return { projectId, name: state.project.name };
+  }
+
+  private parseVerified(value: unknown) {
+    const transfer = parseProjectTransferEnvelope(value);
+    const payloadJson = serializeProjectStateSnapshot(
+      transfer.projectState
+    );
+    if (
+      hashProjectStatePayload(payloadJson) !== transfer.payloadSha256
+    ) {
+      throw new Error("Project transfer checksum verification failed.");
+    }
+    return transfer;
+  }
+}
+
+function insertProjectState(
+  database: AppDatabase,
+  state: ReturnType<typeof remapProjectState>
+) {
+  const existing = database
+    .select({ id: projects.id })
+    .from(projects)
+    .where(eq(projects.id, state.project.id))
+    .get();
+  if (existing) {
+    throw new Error("Project transfer target already exists.");
+  }
+  database
+    .insert(projects)
+    .values({ ...state.project, currentRevision: 0 })
+    .run();
+  insertMany(database, floors, state.floors);
+  insertMany(database, rooms, state.rooms);
+  insertMany(database, projectDevices, state.projectDevices);
+  insertMany(database, distributionBoards, state.distributionBoards);
+  insertMany(database, circuitLists, state.circuitLists);
+  insertMany(database, circuitSections, state.circuitSections);
+  insertMany(
+    database,
+    circuits,
+    state.circuits.map(({ deviceRows: _deviceRows, ...circuit }) => ({
+      ...circuit,
+      isReserve: circuit.isReserve ? 1 : 0,
+    }))
+  );
+  insertMany(
+    database,
+    circuitDeviceRows,
+    state.circuits.flatMap((circuit) => circuit.deviceRows)
+  );
+}
+
+function insertMany<TTable extends Parameters<AppDatabase["insert"]>[0]>(
+  database: AppDatabase,
+  table: TTable,
+  values: unknown[]
+) {
+  if (values.length > 0) {
+    database.insert(table).values(values as never).run();
+  }
+}

src/domain/models/project-transfer.model.ts

@@ -0,0 +1,164 @@
+import {
+  parseProjectStateSnapshot,
+  projectStateSnapshotSchemaVersion,
+  type ProjectStateSnapshot,
+} from "./project-state-snapshot.model.js";
+
+export const projectTransferFormat = "leistungsbilanz.project" as const;
+export const projectTransferFormatVersion = 1 as const;
+
+export interface ProjectTransferEnvelope {
+  format: typeof projectTransferFormat;
+  formatVersion: typeof projectTransferFormatVersion;
+  exportedAtIso: string;
+  payloadSha256: string;
+  projectState: ProjectStateSnapshot;
+}
+
+export function createProjectTransferEnvelope(
+  exportedAtIso: string,
+  payloadSha256: string,
+  projectState: ProjectStateSnapshot
+): ProjectTransferEnvelope {
+  return parseProjectTransferEnvelope({
+    format: projectTransferFormat,
+    formatVersion: projectTransferFormatVersion,
+    exportedAtIso,
+    payloadSha256,
+    projectState,
+  });
+}
+
+export function parseProjectTransferEnvelope(
+  value: unknown
+): ProjectTransferEnvelope {
+  if (!isPlainObject(value)) {
+    throw new Error("Project transfer file must be an object.");
+  }
+  if (
+    value.format !== projectTransferFormat ||
+    value.formatVersion !== projectTransferFormatVersion
+  ) {
+    throw new Error("Project transfer format is not supported.");
+  }
+  if (
+    typeof value.exportedAtIso !== "string" ||
+    !Number.isFinite(Date.parse(value.exportedAtIso))
+  ) {
+    throw new Error("Project transfer timestamp is invalid.");
+  }
+  if (
+    typeof value.payloadSha256 !== "string" ||
+    !/^[a-f0-9]{64}$/.test(value.payloadSha256)
+  ) {
+    throw new Error("Project transfer checksum is invalid.");
+  }
+  const projectState = parseProjectStateSnapshot(value.projectState);
+  if (projectState.schemaVersion !== projectStateSnapshotSchemaVersion) {
+    throw new Error("Project transfer snapshot version is not supported.");
+  }
+  if (Object.keys(value).length !== 5) {
+    throw new Error("Project transfer file contains unknown fields.");
+  }
+  return {
+    format: projectTransferFormat,
+    formatVersion: projectTransferFormatVersion,
+    exportedAtIso: value.exportedAtIso,
+    payloadSha256: value.payloadSha256,
+    projectState,
+  };
+}
+
+export function remapProjectState(
+  source: ProjectStateSnapshot,
+  targetProjectId: string,
+  createId: () => string,
+  name: string = source.project.name
+): ProjectStateSnapshot {
+  const boardIds = idMap(source.distributionBoards, createId);
+  const listIds = idMap(source.circuitLists, createId);
+  const sectionIds = idMap(source.circuitSections, createId);
+  const circuitIds = idMap(source.circuits, createId);
+  const deviceIds = idMap(source.projectDevices, createId);
+  const floorIds = idMap(source.floors, createId);
+  const roomIds = idMap(source.rooms, createId);
+  const rowIds = new Map(
+    source.circuits.flatMap((circuit) =>
+      circuit.deviceRows.map((row) => [row.id, createId()] as const)
+    )
+  );
+  return parseProjectStateSnapshot({
+    ...source,
+    project: { ...source.project, id: targetProjectId, name },
+    distributionBoards: source.distributionBoards.map((board) => ({
+      ...board,
+      id: requiredId(boardIds, board.id),
+      projectId: targetProjectId,
+    })),
+    circuitLists: source.circuitLists.map((list) => ({
+      ...list,
+      id: requiredId(listIds, list.id),
+      projectId: targetProjectId,
+      distributionBoardId: requiredId(boardIds, list.distributionBoardId),
+    })),
+    circuitSections: source.circuitSections.map((section) => ({
+      ...section,
+      id: requiredId(sectionIds, section.id),
+      circuitListId: requiredId(listIds, section.circuitListId),
+    })),
+    circuits: source.circuits.map((circuit) => ({
+      ...circuit,
+      id: requiredId(circuitIds, circuit.id),
+      circuitListId: requiredId(listIds, circuit.circuitListId),
+      sectionId: requiredId(sectionIds, circuit.sectionId),
+      deviceRows: circuit.deviceRows.map((row) => ({
+        ...row,
+        id: requiredId(rowIds, row.id),
+        circuitId: requiredId(circuitIds, circuit.id),
+        linkedProjectDeviceId:
+          row.linkedProjectDeviceId === null
+            ? null
+            : requiredId(deviceIds, row.linkedProjectDeviceId),
+        legacyConsumerId: null,
+        roomId:
+          row.roomId === null ? null : requiredId(roomIds, row.roomId),
+      })),
+    })),
+    projectDevices: source.projectDevices.map((device) => ({
+      ...device,
+      id: requiredId(deviceIds, device.id),
+      projectId: targetProjectId,
+    })),
+    floors: source.floors.map((floor) => ({
+      ...floor,
+      id: requiredId(floorIds, floor.id),
+      projectId: targetProjectId,
+    })),
+    rooms: source.rooms.map((room) => ({
+      ...room,
+      id: requiredId(roomIds, room.id),
+      projectId: targetProjectId,
+      floorId:
+        room.floorId === null ? null : requiredId(floorIds, room.floorId),
+    })),
+  });
+}
+
+function idMap(
+  entries: ReadonlyArray<{ id: string }>,
+  createId: () => string
+) {
+  return new Map(entries.map((entry) => [entry.id, createId()]));
+}
+
+function requiredId(ids: ReadonlyMap<string, string>, sourceId: string) {
+  const targetId = ids.get(sourceId);
+  if (!targetId) {
+    throw new Error(`Project transfer reference "${sourceId}" is invalid.`);
+  }
+  return targetId;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

src/domain/ports/project-transfer.store.ts

@@ -0,0 +1,15 @@
+import type { ProjectStateRestoreCommand } from "../models/project-state-restore-command.model.js";
+import type { ProjectTransferEnvelope } from "../models/project-transfer.model.js";
+
+export interface PreparedProjectTransferReplace {
+  command: ProjectStateRestoreCommand;
+}
+
+export interface ProjectTransferStore {
+  exportProject(projectId: string): ProjectTransferEnvelope | null;
+  prepareReplace(
+    projectId: string,
+    transfer: unknown
+  ): PreparedProjectTransferReplace | null;
+  importDuplicate(transfer: unknown): { projectId: string; name: string };
+}

src/server/composition/project-transfer-store.ts

@@ -0,0 +1,4 @@
+import { db } from "../../db/client.js";
+import { ProjectTransferRepository } from "../../db/repositories/project-transfer.repository.js";
+
+export const projectTransferStore = new ProjectTransferRepository(db);

src/server/controllers/project-transfer.controller.ts

@@ -0,0 +1,100 @@
+import type { NextFunction, Request, Response } from "express";
+import { ProjectRevisionConflictError } from "../../domain/errors/project-revision-conflict.error.js";
+import { ProjectStateConflictError } from "../../domain/errors/project-state-conflict.error.js";
+import { importProjectTransferSchema } from "../../shared/validation/project-transfer.schemas.js";
+import { projectCommandService } from "../composition/project-command-stores.js";
+import { projectTransferStore } from "../composition/project-transfer-store.js";
+
+export function exportProjectTransfer(req: Request, res: Response) {
+  const projectId = getProjectId(req, res);
+  if (!projectId) {
+    return;
+  }
+  const transfer = projectTransferStore.exportProject(projectId);
+  if (!transfer) {
+    return res.status(404).json({ error: "Project not found" });
+  }
+  const filename = safeFilename(transfer.projectState.project.name);
+  res.setHeader(
+    "Content-Disposition",
+    `attachment; filename="${filename}.leistungsbilanz.json"`
+  );
+  return res.json(transfer);
+}
+
+export function importProjectTransfer(
+  req: Request,
+  res: Response,
+  next: NextFunction
+) {
+  const projectId = getProjectId(req, res);
+  if (!projectId) {
+    return;
+  }
+  const parsed = importProjectTransferSchema.safeParse(req.body);
+  if (!parsed.success) {
+    return res.status(400).json({ error: parsed.error.flatten() });
+  }
+  try {
+    if (parsed.data.mode === "duplicate") {
+      return res
+        .status(201)
+        .json(projectTransferStore.importDuplicate(parsed.data.transfer));
+    }
+    const prepared = projectTransferStore.prepareReplace(
+      projectId,
+      parsed.data.transfer
+    );
+    if (!prepared) {
+      return res.status(404).json({ error: "Project not found" });
+    }
+    const result = projectCommandService.executeRestore({
+      projectId,
+      expectedRevision: parsed.data.expectedRevision,
+      description: "Projektimport wiederherstellen",
+      command: prepared.command,
+    });
+    return res.json(result);
+  } catch (error) {
+    if (error instanceof ProjectRevisionConflictError) {
+      return res.status(409).json({
+        error: error.message,
+        code: "PROJECT_REVISION_CONFLICT",
+        expectedRevision: error.expectedRevision,
+        currentRevision: error.actualRevision,
+      });
+    }
+    if (error instanceof ProjectStateConflictError) {
+      return res
+        .status(409)
+        .json({ error: error.message, code: "PROJECT_STATE_CONFLICT" });
+    }
+    if (
+      error instanceof Error &&
+      (error.message.startsWith("Project transfer") ||
+        error.message.startsWith("Snapshot"))
+    ) {
+      return res.status(400).json({ error: error.message });
+    }
+    return next(error);
+  }
+}
+
+function getProjectId(req: Request, res: Response) {
+  const { projectId } = req.params;
+  if (typeof projectId !== "string" || !projectId.trim()) {
+    res.status(400).json({ error: "Invalid projectId" });
+    return null;
+  }
+  return projectId;
+}
+
+function safeFilename(name: string) {
+  return (
+    name
+      .normalize("NFKD")
+      .replace(/[^a-zA-Z0-9_-]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 80) || "projekt"
+  );
+}

src/server/index.ts

@@ -8,7 +8,7 @@ import { errorMiddleware } from "./middleware/error.middleware.js";
 const app = express();
 const port = Number(process.env.PORT || 3000);
 
-app.use(express.json());
+app.use(express.json({ limit: "25mb" }));
 
 app.get("/health", (_req, res) => {
   res.json({ ok: true });

src/server/routes/project.routes.ts

@@ -27,12 +27,18 @@ import {
   listProjectSnapshots,
   restoreProjectSnapshot,
 } from "../controllers/project-snapshot.controller.js";
+import {
+  exportProjectTransfer,
+  importProjectTransfer,
+} from "../controllers/project-transfer.controller.js";
 
 export const projectRouter = Router();
 
 projectRouter.get("/", listProjects);
 projectRouter.post("/", createProject);
 projectRouter.get("/:projectId", getProject);
+projectRouter.get("/:projectId/export", exportProjectTransfer);
+projectRouter.post("/:projectId/import", importProjectTransfer);
 projectRouter.get("/:projectId/history", getProjectHistory);
 projectRouter.get("/:projectId/history/revisions", listProjectRevisions);
 projectRouter.post("/:projectId/commands", executeProjectCommand);

src/shared/validation/project-transfer.schemas.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { expectedProjectRevisionSchema } from "./project-command.schemas.js";
+
+export const importProjectTransferSchema = z.discriminatedUnion("mode", [
+  z
+    .object({
+      mode: z.literal("replace"),
+      expectedRevision: expectedProjectRevisionSchema,
+      transfer: z.unknown(),
+    })
+    .strict(),
+  z
+    .object({
+      mode: z.literal("duplicate"),
+      transfer: z.unknown(),
+    })
+    .strict(),
+]);