@open-mercato/core 0.7.1-develop.7178.1.ab93fbaf4e → 0.7.1-develop.7180.1.9717fbbb43

package/dist/modules/staff/commands/timesheets-reports.js

@@ -0,0 +1,1036 @@
+import { registerCommand } from "@open-mercato/shared/lib/commands";
+import { CrudHttpError } from "@open-mercato/shared/lib/crud/errors";
+import { createLogger } from "@open-mercato/shared/lib/logger";
+import { resolveTranslations } from "@open-mercato/shared/lib/i18n/server";
+import { buildChanges, emitCrudSideEffects, emitCrudUndoSideEffects } from "@open-mercato/shared/lib/commands/helpers";
+import { withAtomicFlush } from "@open-mercato/shared/lib/commands/flush";
+import {
+  StaffTimeEntry,
+  StaffTimeProject,
+  StaffTimeReport,
+  StaffTimeReportEntry,
+  StaffTimeReportEvent,
+  StaffTimeReportProject
+} from "../data/entities.js";
+import {
+  staffTimeReportCloseSchema,
+  staffTimeReportCreateSchema,
+  staffTimeReportUnlockSchema,
+  staffTimeReportUpdateSchema
+} from "../data/validators.js";
+import { readTimeTrackingSettings } from "../lib/time-tracking/settings.js";
+import {
+  allocateReportReference,
+  highestReportSequenceNumber,
+  isReportReferenceConflict,
+  reportReferencePrefix,
+  reportReferenceYear,
+  withReportReferenceRetry
+} from "../lib/timesheets-reports/reportReference.js";
+import { loadReportData } from "../lib/timesheets-reports/loadReportData.js";
+import { reportSheetLabels } from "../lib/timesheets-reports/reportLabels.js";
+import {
+  computeReportTotals,
+  resolveEntryValues,
+  resolveReportCurrency,
+  selectIncludedEntries
+} from "../lib/timesheets-reports/reportTotals.js";
+import { emitStaffEvent } from "../events.js";
+import {
+  applyScopeToWhere,
+  commandActorScope,
+  commandInputScope,
+  ensureOrganizationScope,
+  ensureTenantScope,
+  extractUndoPayload,
+  scopedStaffSnapshotWhere,
+  staffSnapshotScopeFromContext,
+  staffSnapshotScopeFromSnapshot
+} from "./shared.js";
+const staffTimeReportCommandIds = {
+  create: "staff.timesheets.reports.create",
+  update: "staff.timesheets.reports.update",
+  delete: "staff.timesheets.reports.delete",
+  close: "staff.timesheets.reports.close",
+  unlock: "staff.timesheets.reports.unlock"
+};
+const STAFF_TIME_REPORT_RESOURCE_KIND = "staff.timesheets.time_report";
+const REPORT_CURRENCY_CONFLICT_CODE = "report_currency_conflict";
+const REPORT_PROJECT_CUSTOMER_MISMATCH_CODE = "report_project_customer_mismatch";
+const REPORT_PROJECT_NOT_FOUND_CODE = "report_project_not_found";
+const REPORT_CLOSED_CODE = "report_closed";
+const REPORT_NOT_CLOSED_CODE = "report_not_closed";
+const REPORT_REFERENCE_CONFLICT_CODE = "report_reference_conflict";
+const REPORT_EMPTY_CODE = "report_empty";
+const logger = createLogger("staff").child({ component: "commands/timesheets-reports" });
+const reportCrudIndexer = {
+  entityType: "staff:staff_time_report"
+};
+const reportCrudEvents = {
+  module: "staff",
+  entity: "timesheets.time_report",
+  persistent: true,
+  buildPayload: (ctx) => ({
+    id: ctx.identifiers.id,
+    organizationId: ctx.identifiers.organizationId,
+    tenantId: ctx.identifiers.tenantId
+  })
+};
+const DIFFED_FIELDS = [
+  "title",
+  "periodKind",
+  "periodFrom",
+  "periodTo",
+  "currencyCode",
+  "grouping",
+  "nonbillableMode",
+  "includeAlreadyReported",
+  "showRates",
+  "status",
+  "totalBillableMinutes",
+  "totalNonbillableMinutes",
+  "totalAmount"
+];
+function toIsoDate(value) {
+  if (!value) return null;
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) return null;
+    const year = value.getFullYear();
+    const month = String(value.getMonth() + 1).padStart(2, "0");
+    const day = String(value.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+  }
+  const text = String(value);
+  return text.length >= 10 ? text.slice(0, 10) : text;
+}
+function snapshotScopeWhere(scope) {
+  const where = {};
+  if (scope?.tenantId) where.tenantId = scope.tenantId;
+  if (scope?.organizationId) where.organizationId = scope.organizationId;
+  return where;
+}
+async function loadReportProjectIds(em, reportId, scope) {
+  const rows = await em.find(StaffTimeReportProject, { reportId, ...snapshotScopeWhere(scope) });
+  return rows.map((row) => row.timeProjectId);
+}
+function toSnapshot(report, timeProjectIds) {
+  return {
+    id: report.id,
+    tenantId: report.tenantId,
+    organizationId: report.organizationId,
+    customerId: report.customerId,
+    customerSnapshot: report.customerSnapshot ?? null,
+    reference: report.reference,
+    title: report.title,
+    periodKind: report.periodKind,
+    periodFrom: toIsoDate(report.periodFrom),
+    periodTo: toIsoDate(report.periodTo),
+    currencyCode: report.currencyCode,
+    grouping: report.grouping,
+    nonbillableMode: report.nonbillableMode,
+    includeAlreadyReported: report.includeAlreadyReported ?? false,
+    showRates: report.showRates ?? true,
+    roundingUnitMinutes: report.roundingUnitMinutes ?? 0,
+    roundingDirection: report.roundingDirection ?? "up",
+    status: report.status,
+    totalBillableMinutes: report.totalBillableMinutes ?? null,
+    totalNonbillableMinutes: report.totalNonbillableMinutes ?? null,
+    totalAmount: report.totalAmount ?? null,
+    closedAt: report.closedAt ? report.closedAt.toISOString() : null,
+    closedByUserId: report.closedByUserId ?? null,
+    timeProjectIds,
+    deletedAt: report.deletedAt ? report.deletedAt.toISOString() : null
+  };
+}
+async function loadReportSnapshot(em, id, scope) {
+  const report = await em.findOne(StaffTimeReport, scopedStaffSnapshotWhere(id, scope));
+  if (!report) return null;
+  const projectIds = await loadReportProjectIds(em, report.id, scope);
+  return toSnapshot(report, projectIds);
+}
+function reportNotFoundError(translate) {
+  return new CrudHttpError(404, {
+    error: translate("staff.time_tracking.reports.errors.notFound", "Report not found or not accessible.")
+  });
+}
+function reportClosedError(translate, reference) {
+  return new CrudHttpError(409, {
+    code: REPORT_CLOSED_CODE,
+    error: translate(
+      "staff.time_tracking.reports.errors.closed",
+      "This report is closed. Unlock it before changing anything."
+    ),
+    reference: reference ?? null
+  });
+}
+function projectsRequiredError(translate) {
+  const message = translate(
+    "staff.time_tracking.reports.errors.projectsRequired",
+    "Pick at least one project for this report."
+  );
+  return new CrudHttpError(422, { error: message, fieldErrors: { timeProjectIds: message } });
+}
+function projectNotFoundError(translate, missingIds) {
+  const message = translate(
+    "staff.time_tracking.reports.errors.projectNotFound",
+    "Some of the selected projects are not available."
+  );
+  return new CrudHttpError(422, {
+    code: REPORT_PROJECT_NOT_FOUND_CODE,
+    error: message,
+    fieldErrors: { timeProjectIds: message },
+    missingProjectIds: missingIds
+  });
+}
+function customerMismatchError(translate, offenders) {
+  const message = translate(
+    "staff.time_tracking.reports.errors.customerMismatch",
+    "A report always covers one customer. These projects belong to someone else: {projects}."
+  ).replace("{projects}", offenders.join(", "));
+  return new CrudHttpError(422, {
+    code: REPORT_PROJECT_CUSTOMER_MISMATCH_CODE,
+    error: message,
+    fieldErrors: { timeProjectIds: message },
+    offenders
+  });
+}
+function currencyConflictError(translate, currencies, offenders) {
+  const message = translate(
+    "staff.time_tracking.reports.errors.currencyConflict",
+    "A report always covers one currency. Selected projects use {currencies}."
+  ).replace("{currencies}", currencies.join(", "));
+  return new CrudHttpError(422, {
+    code: REPORT_CURRENCY_CONFLICT_CODE,
+    error: message,
+    fieldErrors: { timeProjectIds: message },
+    currencies,
+    offenders: offenders.map((project) => ({
+      id: project.id,
+      name: project.name,
+      currencyCode: project.currencyCode ?? null
+    }))
+  });
+}
+function referenceConflictError(translate) {
+  return new CrudHttpError(409, {
+    code: REPORT_REFERENCE_CONFLICT_CODE,
+    error: translate(
+      "staff.time_tracking.reports.errors.referenceConflict",
+      "Could not allocate a report number right now. Try again."
+    )
+  });
+}
+async function resolveReportProjects(em, timeProjectIds, customerId, scope, translate) {
+  const ids = Array.from(new Set(timeProjectIds.filter((id) => typeof id === "string" && id.length > 0)));
+  if (ids.length === 0) throw projectsRequiredError(translate);
+  const projects = await em.find(
+    StaffTimeProject,
+    applyScopeToWhere({ id: { $in: ids }, deletedAt: null }, scope)
+  );
+  if (projects.length !== ids.length) {
+    const found = new Set(projects.map((project) => project.id));
+    throw projectNotFoundError(
+      translate,
+      ids.filter((id) => !found.has(id))
+    );
+  }
+  const mismatched = projects.filter((project) => (project.customerId ?? null) !== customerId);
+  if (mismatched.length > 0) {
+    throw customerMismatchError(
+      translate,
+      mismatched.map((project) => project.name)
+    );
+  }
+  const resolution = resolveReportCurrency(
+    projects.map((project) => ({
+      id: project.id,
+      name: project.name,
+      currencyCode: project.currencyCode ?? null
+    }))
+  );
+  if (!resolution.ok) {
+    throw currencyConflictError(translate, resolution.currencies, resolution.offenders);
+  }
+  return { projects, currencyCode: resolution.currencyCode ?? "" };
+}
+function deriveCustomerSnapshot(projects) {
+  for (const project of projects) {
+    const snapshot = project.customerSnapshot;
+    if (snapshot && typeof snapshot === "object" && Object.keys(snapshot).length > 0) {
+      return snapshot;
+    }
+  }
+  return null;
+}
+async function readRoundingSnapshot(ctx, tenantId) {
+  try {
+    const configService = ctx.container.resolve("moduleConfigService");
+    const settings = await readTimeTrackingSettings(configService, { tenantId });
+    return { unitMinutes: settings.rounding.unitMinutes, direction: settings.rounding.direction };
+  } catch (err) {
+    logger.warn("staff.timesheets.reports rounding snapshot unavailable", { err });
+    return { unitMinutes: 0, direction: "up" };
+  }
+}
+async function replaceReportProjects(em, report, projects) {
+  const existing = await em.find(StaffTimeReportProject, { reportId: report.id });
+  for (const row of existing) em.remove(row);
+  for (const project of projects) {
+    em.persist(
+      em.create(StaffTimeReportProject, {
+        tenantId: report.tenantId,
+        organizationId: report.organizationId,
+        reportId: report.id,
+        timeProjectId: project.id,
+        createdAt: /* @__PURE__ */ new Date()
+      })
+    );
+  }
+}
+function actorUserId(ctx) {
+  return typeof ctx.auth?.sub === "string" ? ctx.auth.sub : null;
+}
+async function readHighestReportSequence(em, year, scope) {
+  const rows = await em.find(
+    StaffTimeReport,
+    applyScopeToWhere({ reference: { $like: `${reportReferencePrefix(year)}%` } }, scope)
+  );
+  return highestReportSequenceNumber(
+    rows.map((row) => row.reference),
+    year
+  );
+}
+const createReportCommand = {
+  id: staffTimeReportCommandIds.create,
+  async execute(rawInput, ctx) {
+    const parsed = staffTimeReportCreateSchema.parse(rawInput);
+    ensureTenantScope(ctx, parsed.tenantId);
+    ensureOrganizationScope(ctx, parsed.organizationId);
+    const scope = commandInputScope(ctx, parsed.tenantId, parsed.organizationId);
+    const { translate } = await resolveTranslations();
+    const baseEm = ctx.container.resolve("em");
+    const createdByUserId = actorUserId(ctx);
+    const rounding = await readRoundingSnapshot(ctx, parsed.tenantId);
+    const issuedAt = /* @__PURE__ */ new Date();
+    const year = reportReferenceYear(issuedAt);
+    let record;
+    try {
+      record = await withReportReferenceRetry(async () => {
+        const em = baseEm.fork();
+        let created = null;
+        let plan = null;
+        await withAtomicFlush(
+          em,
+          [
+            async () => {
+              const resolved = await resolveReportProjects(
+                em,
+                parsed.timeProjectIds,
+                parsed.customerId,
+                scope,
+                translate
+              );
+              plan = {
+                projects: resolved.projects,
+                currencyCode: resolved.currencyCode,
+                highest: await readHighestReportSequence(em, year, scope)
+              };
+            },
+            () => {
+              if (!plan) throw reportNotFoundError(translate);
+              const allocation = allocateReportReference(year, plan.highest);
+              const now = /* @__PURE__ */ new Date();
+              created = em.create(StaffTimeReport, {
+                tenantId: parsed.tenantId,
+                organizationId: parsed.organizationId,
+                customerId: parsed.customerId,
+                customerSnapshot: deriveCustomerSnapshot(plan.projects),
+                reference: allocation.reference,
+                title: parsed.title,
+                periodKind: parsed.periodKind,
+                periodFrom: parsed.periodFrom,
+                periodTo: parsed.periodTo,
+                currencyCode: plan.currencyCode,
+                grouping: parsed.grouping,
+                nonbillableMode: parsed.nonbillableMode,
+                includeAlreadyReported: parsed.includeAlreadyReported,
+                showRates: parsed.showRates,
+                roundingUnitMinutes: rounding.unitMinutes,
+                roundingDirection: rounding.direction,
+                status: "draft",
+                createdByUserId,
+                createdAt: now,
+                updatedAt: now,
+                deletedAt: null
+              });
+              em.persist(created);
+            },
+            async () => {
+              if (!created || !plan) return;
+              await replaceReportProjects(em, created, plan.projects);
+            }
+          ],
+          { transaction: true, label: staffTimeReportCommandIds.create }
+        );
+        if (!created) throw reportNotFoundError(translate);
+        return created;
+      });
+    } catch (err) {
+      if (isReportReferenceConflict(err)) throw referenceConflictError(translate);
+      throw err;
+    }
+    await emitCrudSideEffects({
+      dataEngine: ctx.container.resolve("dataEngine"),
+      action: "created",
+      entity: record,
+      identifiers: { id: record.id, organizationId: record.organizationId, tenantId: record.tenantId },
+      events: reportCrudEvents,
+      indexer: reportCrudIndexer
+    });
+    return { reportId: record.id };
+  },
+  captureAfter: async (_input, result, ctx) => {
+    const em = ctx.container.resolve("em").fork();
+    const snapshot = await loadReportSnapshot(em, result.reportId, staffSnapshotScopeFromContext(ctx));
+    if (!snapshot) return null;
+    return { snapshot };
+  },
+  buildLog: async ({ result, ctx }) => {
+    const em = ctx.container.resolve("em").fork();
+    const snapshot = await loadReportSnapshot(em, result.reportId, staffSnapshotScopeFromContext(ctx));
+    if (!snapshot) return null;
+    const { translate } = await resolveTranslations();
+    return {
+      actionLabel: translate("staff.audit.timesheets.reports.create", "Create report"),
+      resourceKind: STAFF_TIME_REPORT_RESOURCE_KIND,
+      resourceId: snapshot.id,
+      tenantId: snapshot.tenantId,
+      organizationId: snapshot.organizationId,
+      snapshotAfter: snapshot,
+      payload: { undo: { after: snapshot } }
+    };
+  },
+  undo: async ({ logEntry, ctx }) => {
+    const payload = extractUndoPayload(logEntry);
+    const after = payload?.after;
+    if (!after) return;
+    const em = ctx.container.resolve("em").fork();
+    const report = await em.findOne(
+      StaffTimeReport,
+      scopedStaffSnapshotWhere(after.id, staffSnapshotScopeFromSnapshot(after))
+    );
+    if (!report) return;
+    if (report.status === "closed") return;
+    report.deletedAt = /* @__PURE__ */ new Date();
+    report.updatedAt = /* @__PURE__ */ new Date();
+    await em.flush();
+    await emitCrudUndoSideEffects({
+      dataEngine: ctx.container.resolve("dataEngine"),
+      action: "deleted",
+      entity: report,
+      identifiers: { id: report.id, organizationId: report.organizationId, tenantId: report.tenantId },
+      events: reportCrudEvents,
+      indexer: reportCrudIndexer
+    });
+  }
+};
+const updateReportCommand = {
+  id: staffTimeReportCommandIds.update,
+  async prepare(rawInput, ctx) {
+    const parsed = staffTimeReportUpdateSchema.safeParse(rawInput);
+    if (!parsed.success) return {};
+    const em = ctx.container.resolve("em").fork();
+    const before = await loadReportSnapshot(em, parsed.data.id, staffSnapshotScopeFromContext(ctx));
+    if (!before) return {};
+    return { before: { snapshot: before } };
+  },
+  async execute(rawInput, ctx) {
+    const parsed = staffTimeReportUpdateSchema.parse(rawInput);
+    const { translate } = await resolveTranslations();
+    const em = ctx.container.resolve("em").fork();
+    const scope = commandActorScope(ctx);
+    const report = await em.findOne(
+      StaffTimeReport,
+      applyScopeToWhere({ id: parsed.id, deletedAt: null }, scope)
+    );
+    if (!report) throw reportNotFoundError(translate);
+    ensureTenantScope(ctx, report.tenantId);
+    ensureOrganizationScope(ctx, report.organizationId);
+    if (report.status === "closed") throw reportClosedError(translate, report.reference);
+    const targetCustomerId = parsed.customerId ?? report.customerId;
+    let resolved = null;
+    await withAtomicFlush(
+      em,
+      [
+        async () => {
+          const needsProjectCheck = parsed.timeProjectIds !== void 0 || parsed.customerId !== void 0 && parsed.customerId !== report.customerId;
+          if (!needsProjectCheck) return;
+          const ids = parsed.timeProjectIds ?? await loadReportProjectIds(em, report.id, scope);
+          resolved = await resolveReportProjects(em, ids, targetCustomerId, scope, translate);
+        },
+        () => {
+          const now = /* @__PURE__ */ new Date();
+          if (parsed.title !== void 0) report.title = parsed.title;
+          if (parsed.periodKind !== void 0) report.periodKind = parsed.periodKind;
+          if (parsed.periodFrom !== void 0) report.periodFrom = parsed.periodFrom;
+          if (parsed.periodTo !== void 0) report.periodTo = parsed.periodTo;
+          if (parsed.grouping !== void 0) report.grouping = parsed.grouping;
+          if (parsed.nonbillableMode !== void 0) report.nonbillableMode = parsed.nonbillableMode;
+          if (parsed.includeAlreadyReported !== void 0) {
+            report.includeAlreadyReported = parsed.includeAlreadyReported;
+          }
+          if (parsed.showRates !== void 0) report.showRates = parsed.showRates;
+          if (parsed.customerId !== void 0) report.customerId = parsed.customerId;
+          if (resolved) {
+            report.currencyCode = resolved.currencyCode;
+            report.customerSnapshot = deriveCustomerSnapshot(resolved.projects) ?? report.customerSnapshot ?? null;
+          }
+          report.updatedAt = now;
+        },
+        async () => {
+          if (!resolved || parsed.timeProjectIds === void 0) return;
+          await replaceReportProjects(em, report, resolved.projects);
+        }
+      ],
+      { transaction: true, label: staffTimeReportCommandIds.update }
+    );
+    await emitCrudSideEffects({
+      dataEngine: ctx.container.resolve("dataEngine"),
+      action: "updated",
+      entity: report,
+      identifiers: { id: report.id, organizationId: report.organizationId, tenantId: report.tenantId },
+      events: reportCrudEvents,
+      indexer: reportCrudIndexer
+    });
+    return { reportId: report.id };
+  },
+  buildLog: async ({ snapshots, ctx }) => {
+    const before = snapshots.before?.snapshot;
+    if (!before) return null;
+    const em = ctx.container.resolve("em").fork();
+    const after = await loadReportSnapshot(em, before.id, staffSnapshotScopeFromSnapshot(before));
+    if (!after) return null;
+    const { translate } = await resolveTranslations();
+    return {
+      actionLabel: translate("staff.audit.timesheets.reports.update", "Update report"),
+      resourceKind: STAFF_TIME_REPORT_RESOURCE_KIND,
+      resourceId: before.id,
+      tenantId: before.tenantId,
+      organizationId: before.organizationId,
+      snapshotBefore: before,
+      snapshotAfter: after,
+      changes: buildChanges(
+        before,
+        after,
+        [...DIFFED_FIELDS]
+      ),
+      payload: { undo: { before, after } }
+    };
+  },
+  undo: async ({ logEntry, ctx }) => {
+    const payload = extractUndoPayload(logEntry);
+    const before = payload?.before;
+    if (!before) return;
+    const em = ctx.container.resolve("em").fork();
+    const report = await em.findOne(
+      StaffTimeReport,
+      scopedStaffSnapshotWhere(before.id, staffSnapshotScopeFromSnapshot(before))
+    );
+    if (!report) return;
+    if (report.status === "closed") return;
+    const projects = await em.find(StaffTimeProject, {
+      id: { $in: before.timeProjectIds },
+      tenantId: before.tenantId,
+      organizationId: before.organizationId
+    });
+    await withAtomicFlush(
+      em,
+      [
+        () => {
+          report.customerId = before.customerId;
+          report.customerSnapshot = before.customerSnapshot;
+          report.title = before.title;
+          report.periodKind = before.periodKind;
+          if (before.periodFrom) report.periodFrom = new Date(before.periodFrom);
+          if (before.periodTo) report.periodTo = new Date(before.periodTo);
+          report.currencyCode = before.currencyCode;
+          report.grouping = before.grouping;
+          report.nonbillableMode = before.nonbillableMode;
+          report.includeAlreadyReported = before.includeAlreadyReported;
+          report.showRates = before.showRates;
+          report.updatedAt = /* @__PURE__ */ new Date();
+        },
+        async () => {
+          if (projects.length !== before.timeProjectIds.length) return;
+          await replaceReportProjects(em, report, projects);
+        }
+      ],
+      { transaction: true, label: `${staffTimeReportCommandIds.update}.undo` }
+    );
+    await emitCrudUndoSideEffects({
+      dataEngine: ctx.container.resolve("dataEngine"),
+      action: "updated",
+      entity: report,
+      identifiers: { id: report.id, organizationId: report.organizationId, tenantId: report.tenantId },
+      events: reportCrudEvents,
+      indexer: reportCrudIndexer
+    });
+  }
+};
+const deleteReportCommand = {
+  id: staffTimeReportCommandIds.delete,
+  async prepare(input, ctx) {
+    const id = input?.id;
+    if (!id) return {};
+    const em = ctx.container.resolve("em").fork();
+    const before = await loadReportSnapshot(em, id, staffSnapshotScopeFromContext(ctx));
+    if (!before) return {};
+    return { before: { snapshot: before } };
+  },
+  async execute(input, ctx) {
+    const { translate } = await resolveTranslations();
+    const id = input?.id;
+    if (!id) {
+      throw new CrudHttpError(400, {
+        error: translate("staff.time_tracking.reports.errors.idRequired", "Report id is required.")
+      });
+    }
+    const em = ctx.container.resolve("em").fork();
+    const scope = commandActorScope(ctx);
+    const report = await em.findOne(
+      StaffTimeReport,
+      applyScopeToWhere({ id, deletedAt: null }, scope)
+    );
+    if (!report) throw reportNotFoundError(translate);
+    ensureTenantScope(ctx, report.tenantId);
+    ensureOrganizationScope(ctx, report.organizationId);
+    if (report.status === "closed") throw reportClosedError(translate, report.reference);
+    const now = /* @__PURE__ */ new Date();
+    report.deletedAt = now;
+    report.updatedAt = now;
+    await em.flush();
+    await emitCrudSideEffects({
+      dataEngine: ctx.container.resolve("dataEngine"),
+      action: "deleted",
+      entity: report,
+      identifiers: { id: report.id, organizationId: report.organizationId, tenantId: report.tenantId },
+      events: reportCrudEvents,
+      indexer: reportCrudIndexer
+    });
+    return { reportId: report.id };
+  },
+  buildLog: async ({ snapshots }) => {
+    const before = snapshots.before?.snapshot;
+    if (!before) return null;
+    const { translate } = await resolveTranslations();
+    return {
+      actionLabel: translate("staff.audit.timesheets.reports.delete", "Delete report"),
+      resourceKind: STAFF_TIME_REPORT_RESOURCE_KIND,
+      resourceId: before.id,
+      tenantId: before.tenantId,
+      organizationId: before.organizationId,
+      snapshotBefore: before,
+      payload: { undo: { before } }
+    };
+  },
+  undo: async ({ logEntry, ctx }) => {
+    const payload = extractUndoPayload(logEntry);
+    const before = payload?.before;
+    if (!before) return;
+    const em = ctx.container.resolve("em").fork();
+    const report = await em.findOne(
+      StaffTimeReport,
+      scopedStaffSnapshotWhere(before.id, staffSnapshotScopeFromSnapshot(before))
+    );
+    if (!report) return;
+    report.deletedAt = null;
+    report.updatedAt = /* @__PURE__ */ new Date();
+    await em.flush();
+    await emitCrudUndoSideEffects({
+      dataEngine: ctx.container.resolve("dataEngine"),
+      action: "created",
+      entity: report,
+      identifiers: { id: report.id, organizationId: report.organizationId, tenantId: report.tenantId },
+      events: reportCrudEvents,
+      indexer: reportCrudIndexer
+    });
+  }
+};
+registerCommand(createReportCommand);
+registerCommand(updateReportCommand);
+registerCommand(deleteReportCommand);
+function reportNotClosedError(translate) {
+  return new CrudHttpError(409, {
+    code: REPORT_NOT_CLOSED_CODE,
+    error: translate(
+      "staff.time_tracking.reports.errors.notClosed",
+      "This report is not closed, so there is nothing to unlock."
+    )
+  });
+}
+function reportEmptyError(translate) {
+  return new CrudHttpError(422, {
+    code: REPORT_EMPTY_CODE,
+    error: translate(
+      "staff.time_tracking.reports.errors.empty",
+      "This report covers no time entries, so there is nothing to freeze. Adjust the period or the project selection first."
+    )
+  });
+}
+const closeReportCommand = {
+  id: staffTimeReportCommandIds.close,
+  async prepare(rawInput, ctx) {
+    const parsed = staffTimeReportCloseSchema.safeParse(rawInput);
+    if (!parsed.success) return {};
+    const em = ctx.container.resolve("em").fork();
+    const before = await loadReportSnapshot(em, parsed.data.id, staffSnapshotScopeFromContext(ctx));
+    if (!before) return {};
+    return { before: { snapshot: before } };
+  },
+  async execute(rawInput, ctx) {
+    const parsed = staffTimeReportCloseSchema.parse(rawInput);
+    const { translate } = await resolveTranslations();
+    const em = ctx.container.resolve("em").fork();
+    const scope = commandActorScope(ctx);
+    const report = await em.findOne(
+      StaffTimeReport,
+      applyScopeToWhere({ id: parsed.id, deletedAt: null }, scope)
+    );
+    if (!report) throw reportNotFoundError(translate);
+    ensureTenantScope(ctx, report.tenantId);
+    ensureOrganizationScope(ctx, report.organizationId);
+    if (report.status === "closed") throw reportClosedError(translate, report.reference);
+    const dataScope = { tenantId: report.tenantId, organizationId: report.organizationId };
+    const rounding = await readRoundingSnapshot(ctx, report.tenantId);
+    const actorId = actorUserId(ctx);
+    const labels = reportSheetLabels(translate);
+    let lockedEntryCount = 0;
+    let totals = null;
+    let closePlan = [];
+    await withAtomicFlush(
+      em,
+      [
+        async () => {
+          const timeProjectIds = await loadReportProjectIds(em, report.id, dataScope);
+          const data = await loadReportData({
+            em,
+            scope: dataScope,
+            timeProjectIds,
+            periodFrom: report.periodFrom,
+            periodTo: report.periodTo
+          });
+          const options = {
+            grouping: report.grouping,
+            nonbillableMode: report.nonbillableMode,
+            includeAlreadyReported: report.includeAlreadyReported ?? false
+          };
+          const included = selectIncludedEntries(data.entries, options, report.id);
+          if (included.length === 0) throw reportEmptyError(translate);
+          totals = computeReportTotals({
+            entries: data.entries,
+            projects: data.projects,
+            directory: data.directory,
+            options,
+            currentReportId: report.id,
+            labels
+          });
+          const projectById = new Map(data.projects.map((project) => [project.id, project]));
+          const entryRows = await em.find(StaffTimeEntry, {
+            id: { $in: included.map((entry) => entry.id) },
+            tenantId: report.tenantId,
+            organizationId: report.organizationId
+          });
+          const entryById = new Map(entryRows.map((row) => [row.id, row]));
+          closePlan = included.map((entry) => ({
+            entry,
+            row: entryById.get(entry.id) ?? null,
+            values: resolveEntryValues(entry, projectById.get(entry.timeProjectId) ?? null),
+            currencyCode: projectById.get(entry.timeProjectId)?.currencyCode ?? report.currencyCode ?? ""
+          }));
+        },
+        () => {
+          if (!totals) throw reportEmptyError(translate);
+          const now = /* @__PURE__ */ new Date();
+          for (const item of closePlan) {
+            em.persist(
+              em.create(StaffTimeReportEntry, {
+                tenantId: report.tenantId,
+                organizationId: report.organizationId,
+                reportId: report.id,
+                timeEntryId: item.entry.id,
+                frozenRawMinutes: item.values.rawMinutes,
+                frozenRoundedMinutes: item.values.minutes,
+                frozenRateAmount: item.values.rate === null ? null : String(item.values.rate),
+                frozenCurrencyCode: item.currencyCode,
+                frozenAmount: item.values.amount === null ? null : item.values.amount.toFixed(2),
+                frozenIsBillable: item.values.isBillable,
+                createdAt: now
+              })
+            );
+            const row = item.row;
+            if (!row) continue;
+            if (row.lockedReportId) continue;
+            row.lockedReportId = report.id;
+            row.lockedAt = now;
+            row.updatedAt = now;
+            lockedEntryCount += 1;
+          }
+          report.status = "closed";
+          report.closedAt = now;
+          report.closedByUserId = actorId;
+          report.roundingUnitMinutes = rounding.unitMinutes;
+          report.roundingDirection = rounding.direction;
+          report.totalBillableMinutes = totals.billableMinutes;
+          report.totalNonbillableMinutes = totals.nonbillableMinutes;
+          report.totalAmount = totals.totalAmount.toFixed(2);
+          report.updatedAt = now;
+          em.persist(
+            em.create(StaffTimeReportEvent, {
+              tenantId: report.tenantId,
+              organizationId: report.organizationId,
+              reportId: report.id,
+              eventType: "closed",
+              reason: null,
+              actorUserId: actorId,
+              metadata: {
+                frozenEntryCount: closePlan.length,
+                lockedEntryCount,
+                totalAmount: totals.totalAmount,
+                currencyCode: report.currencyCode,
+                roundingUnitMinutes: rounding.unitMinutes,
+                roundingDirection: rounding.direction
+              },
+              createdAt: now
+            })
+          );
+        }
+      ],
+      { transaction: true, label: staffTimeReportCommandIds.close }
+    );
+    const resolved = totals;
+    const result = {
+      reportId: report.id,
+      lockedEntryCount,
+      totalAmount: resolved?.totalAmount ?? 0,
+      totalBillableMinutes: resolved?.billableMinutes ?? 0,
+      totalNonbillableMinutes: resolved?.nonbillableMinutes ?? 0
+    };
+    await emitCrudSideEffects({
+      dataEngine: ctx.container.resolve("dataEngine"),
+      action: "updated",
+      entity: report,
+      identifiers: { id: report.id, organizationId: report.organizationId, tenantId: report.tenantId },
+      events: reportCrudEvents,
+      indexer: reportCrudIndexer
+    });
+    void emitStaffEvent("staff.timesheets.time_report.closed", {
+      id: report.id,
+      tenantId: report.tenantId,
+      organizationId: report.organizationId,
+      reference: report.reference,
+      reportId: result.reportId,
+      lockedEntryCount: result.lockedEntryCount,
+      totalBillableMinutes: result.totalBillableMinutes,
+      totalNonbillableMinutes: result.totalNonbillableMinutes
+    }).catch((err) => {
+      logger.error("staff.timesheets emit time_report.closed failed", { err });
+    });
+    if (lockedEntryCount > 0) {
+      void emitStaffEvent("staff.timesheets.time_entry.locked", {
+        tenantId: report.tenantId,
+        organizationId: report.organizationId,
+        reportId: report.id,
+        lockedEntryCount
+      }).catch((err) => {
+        logger.error("staff.timesheets emit time_entry.locked failed", { err });
+      });
+    }
+    return result;
+  },
+  buildLog: async ({ snapshots, ctx }) => {
+    const before = snapshots.before?.snapshot;
+    if (!before) return null;
+    const em = ctx.container.resolve("em").fork();
+    const after = await loadReportSnapshot(em, before.id, staffSnapshotScopeFromSnapshot(before));
+    if (!after) return null;
+    const { translate } = await resolveTranslations();
+    return {
+      actionLabel: translate("staff.audit.timesheets.reports.close", "Close and lock report"),
+      resourceKind: STAFF_TIME_REPORT_RESOURCE_KIND,
+      resourceId: before.id,
+      tenantId: before.tenantId,
+      organizationId: before.organizationId,
+      snapshotBefore: before,
+      snapshotAfter: after,
+      changes: buildChanges(
+        before,
+        after,
+        [...DIFFED_FIELDS]
+      )
+      // Deliberately no `undo` payload: unwinding a close is the unlock command,
+      // which requires a reason and its own feature. A silent undo of a billing
+      // freeze is exactly what US-G3 forbids.
+    };
+  }
+};
+const unlockReportCommand = {
+  id: staffTimeReportCommandIds.unlock,
+  async prepare(rawInput, ctx) {
+    const parsed = staffTimeReportUnlockSchema.safeParse(rawInput);
+    if (!parsed.success) return {};
+    const em = ctx.container.resolve("em").fork();
+    const before = await loadReportSnapshot(em, parsed.data.id, staffSnapshotScopeFromContext(ctx));
+    if (!before) return {};
+    return { before: { snapshot: before } };
+  },
+  async execute(rawInput, ctx) {
+    const parsed = staffTimeReportUnlockSchema.parse(rawInput);
+    const { translate } = await resolveTranslations();
+    const em = ctx.container.resolve("em").fork();
+    const scope = commandActorScope(ctx);
+    const report = await em.findOne(
+      StaffTimeReport,
+      applyScopeToWhere({ id: parsed.id, deletedAt: null }, scope)
+    );
+    if (!report) throw reportNotFoundError(translate);
+    ensureTenantScope(ctx, report.tenantId);
+    ensureOrganizationScope(ctx, report.organizationId);
+    if (report.status !== "closed") throw reportNotClosedError(translate);
+    const actorId = actorUserId(ctx);
+    let unlockedEntryCount = 0;
+    let frozenEntries = [];
+    let lockedRows = [];
+    const frozenTotals = {
+      totalAmount: report.totalAmount,
+      totalBillableMinutes: report.totalBillableMinutes ?? null,
+      totalNonbillableMinutes: report.totalNonbillableMinutes ?? null
+    };
+    await withAtomicFlush(
+      em,
+      [
+        async () => {
+          frozenEntries = await em.find(StaffTimeReportEntry, {
+            reportId: report.id,
+            tenantId: report.tenantId,
+            organizationId: report.organizationId
+          });
+          lockedRows = await em.find(StaffTimeEntry, {
+            lockedReportId: report.id,
+            tenantId: report.tenantId,
+            organizationId: report.organizationId
+          });
+        },
+        () => {
+          const now = /* @__PURE__ */ new Date();
+          for (const row of lockedRows) {
+            row.lockedReportId = null;
+            row.lockedAt = null;
+            row.updatedAt = now;
+            unlockedEntryCount += 1;
+          }
+          for (const frozen of frozenEntries) em.remove(frozen);
+          report.status = "draft";
+          report.closedAt = null;
+          report.closedByUserId = null;
+          report.totalAmount = null;
+          report.totalBillableMinutes = null;
+          report.totalNonbillableMinutes = null;
+          report.updatedAt = now;
+          em.persist(
+            em.create(StaffTimeReportEvent, {
+              tenantId: report.tenantId,
+              organizationId: report.organizationId,
+              reportId: report.id,
+              eventType: "unlocked",
+              reason: parsed.reason,
+              actorUserId: actorId,
+              metadata: {
+                unlockedEntryCount,
+                frozenEntryCount: frozenEntries.length,
+                frozenTotalAmount: frozenTotals.totalAmount,
+                frozenBillableMinutes: frozenTotals.totalBillableMinutes,
+                frozenNonbillableMinutes: frozenTotals.totalNonbillableMinutes,
+                currencyCode: report.currencyCode
+              },
+              createdAt: now
+            })
+          );
+        }
+      ],
+      { transaction: true, label: staffTimeReportCommandIds.unlock }
+    );
+    await emitCrudSideEffects({
+      dataEngine: ctx.container.resolve("dataEngine"),
+      action: "updated",
+      entity: report,
+      identifiers: { id: report.id, organizationId: report.organizationId, tenantId: report.tenantId },
+      events: reportCrudEvents,
+      indexer: reportCrudIndexer
+    });
+    void emitStaffEvent("staff.timesheets.time_report.unlocked", {
+      id: report.id,
+      tenantId: report.tenantId,
+      organizationId: report.organizationId,
+      reference: report.reference,
+      actorUserId: actorId,
+      unlockedEntryCount
+    }).catch((err) => {
+      logger.error("staff.timesheets emit time_report.unlocked failed", { err });
+    });
+    if (unlockedEntryCount > 0) {
+      void emitStaffEvent("staff.timesheets.time_entry.unlocked", {
+        tenantId: report.tenantId,
+        organizationId: report.organizationId,
+        reportId: report.id,
+        unlockedEntryCount
+      }).catch((err) => {
+        logger.error("staff.timesheets emit time_entry.unlocked failed", { err });
+      });
+    }
+    return { reportId: report.id, unlockedEntryCount };
+  },
+  buildLog: async ({ snapshots, ctx, input }) => {
+    const before = snapshots.before?.snapshot;
+    if (!before) return null;
+    const em = ctx.container.resolve("em").fork();
+    const after = await loadReportSnapshot(em, before.id, staffSnapshotScopeFromSnapshot(before));
+    if (!after) return null;
+    const { translate } = await resolveTranslations();
+    return {
+      actionLabel: translate("staff.audit.timesheets.reports.unlock", "Unlock report entries"),
+      resourceKind: STAFF_TIME_REPORT_RESOURCE_KIND,
+      resourceId: before.id,
+      tenantId: before.tenantId,
+      organizationId: before.organizationId,
+      snapshotBefore: before,
+      snapshotAfter: after,
+      changes: buildChanges(
+        before,
+        after,
+        [...DIFFED_FIELDS]
+      ),
+      payload: { reason: input?.reason ?? null }
+    };
+  }
+};
+registerCommand(closeReportCommand);
+registerCommand(unlockReportCommand);
+export {
+  REPORT_CLOSED_CODE,
+  REPORT_CURRENCY_CONFLICT_CODE,
+  REPORT_EMPTY_CODE,
+  REPORT_NOT_CLOSED_CODE,
+  REPORT_PROJECT_CUSTOMER_MISMATCH_CODE,
+  REPORT_PROJECT_NOT_FOUND_CODE,
+  REPORT_REFERENCE_CONFLICT_CODE,
+  STAFF_TIME_REPORT_RESOURCE_KIND,
+  currencyConflictError,
+  deriveCustomerSnapshot,
+  loadReportProjectIds,
+  loadReportSnapshot,
+  reportClosedError,
+  reportNotFoundError,
+  resolveReportProjects,
+  staffTimeReportCommandIds
+};
+//# sourceMappingURL=timesheets-reports.js.map