@tailor-platform/erp-kit 0.6.0 → 0.8.0

package/src/modules/accounting/command/executeAllocationCycle.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { AllocationCycleNotFoundError, InvalidStateError } from "../lib/errors.generated";
+import {
+  validatedAllocationCycle,
+  baseAllocationCycle,
+  baseAllocationRule,
+  baseAllocationResult,
+  activeCostElement,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./executeAllocationCycle";
+
+describe("executeAllocationCycle", () => {
+  it("executes a VALIDATED allocation cycle in ACTUAL mode transitioning it to EXECUTED status", async () => {
+    const executed = { ...validatedAllocationCycle, status: "EXECUTED" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(validatedAllocationCycle) // cycle lookup
+      .mockReturnValueOnce([baseAllocationRule]); // rules lookup
+    spies.insert.mockReturnValueOnce(baseAllocationResult);
+    spies.update.mockReturnValueOnce(executed);
+
+    const result = await run(
+      db,
+      {
+        allocationCycleId: validatedAllocationCycle.id,
+        costElementId: activeCostElement.id,
+        mode: "ACTUAL",
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.allocationCycle.status).toBe("EXECUTED");
+  });
+
+  it("creates AllocationResult records in ACTUAL mode", async () => {
+    const executed = { ...validatedAllocationCycle, status: "EXECUTED" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(validatedAllocationCycle)
+      .mockReturnValueOnce([baseAllocationRule]);
+    spies.insert.mockReturnValueOnce(baseAllocationResult);
+    spies.update.mockReturnValueOnce(executed);
+
+    const result = await run(
+      db,
+      {
+        allocationCycleId: validatedAllocationCycle.id,
+        costElementId: activeCostElement.id,
+        mode: "ACTUAL",
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.allocationResults).toHaveLength(1);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("executes in TEST_RUN mode returning preview results without status change", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(validatedAllocationCycle)
+      .mockReturnValueOnce([baseAllocationRule]);
+
+    const result = await run(
+      db,
+      {
+        allocationCycleId: validatedAllocationCycle.id,
+        costElementId: activeCostElement.id,
+        mode: "TEST_RUN",
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.allocationCycle.status).toBe("VALIDATED");
+    expect(value.allocationResults).toHaveLength(1);
+    expect(value.allocationResults[0].costElementId).toBe(activeCostElement.id);
+    expect(spies.update).not.toHaveBeenCalled();
+    expect(spies.insert).not.toHaveBeenCalled();
+  });
+
+  it("returns error when allocation cycle does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        allocationCycleId: "missing-id",
+        costElementId: activeCostElement.id,
+        mode: "ACTUAL",
+      },
+      commandCtx,
+    );
+
+    expectErr(result, AllocationCycleNotFoundError);
+  });
+
+  it("returns error when allocation cycle is not in VALIDATED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseAllocationCycle);
+
+    const result = await run(
+      db,
+      {
+        allocationCycleId: baseAllocationCycle.id,
+        costElementId: activeCostElement.id,
+        mode: "ACTUAL",
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("each AllocationResult references cycle, sender, receiver, amount, and cost element", async () => {
+    const executed = { ...validatedAllocationCycle, status: "EXECUTED" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(validatedAllocationCycle)
+      .mockReturnValueOnce([baseAllocationRule]);
+    spies.insert.mockReturnValueOnce(baseAllocationResult);
+    spies.update.mockReturnValueOnce(executed);
+
+    const result = await run(
+      db,
+      {
+        allocationCycleId: validatedAllocationCycle.id,
+        costElementId: activeCostElement.id,
+        mode: "ACTUAL",
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    const ar = value.allocationResults[0];
+    expect(ar).toBeDefined();
+  });
+
+  it("emits audit event recording the execution and acting user", async () => {
+    const executed = { ...validatedAllocationCycle, status: "EXECUTED" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(validatedAllocationCycle)
+      .mockReturnValueOnce([baseAllocationRule]);
+    spies.insert.mockReturnValueOnce(baseAllocationResult);
+    spies.update.mockReturnValueOnce(executed);
+
+    const result = await run(
+      db,
+      {
+        allocationCycleId: validatedAllocationCycle.id,
+        costElementId: activeCostElement.id,
+        mode: "ACTUAL",
+      },
+      commandCtx,
+    );
+
+    expectOk(result);
+    expect(spies.update).toHaveBeenCalled();
+  });
+});

package/src/modules/accounting/command/executeAllocationCycle.ts

@@ -0,0 +1,94 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import { AllocationCycleNotFoundError, InvalidStateError } from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface ExecuteAllocationCycleInput {
+  allocationCycleId: string;
+  costElementId: string;
+  mode: "ACTUAL" | "TEST_RUN";
+}
+
+export async function run(
+  db: Transaction,
+  input: ExecuteAllocationCycleInput,
+  ctx: CommandContext,
+) {
+  void ctx;
+
+  // Validate allocation cycle exists
+  const cycle = await db
+    .selectFrom("AllocationCycle")
+    .where("id", "=", input.allocationCycleId)
+    .selectAll()
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!cycle) {
+    return err(new AllocationCycleNotFoundError(input.allocationCycleId));
+  }
+
+  // Validate status is VALIDATED
+  if (cycle.status !== "VALIDATED") {
+    return err(new InvalidStateError(input.allocationCycleId));
+  }
+
+  // Fetch all rules for this cycle
+  const rules = await db
+    .selectFrom("AllocationRule")
+    .selectAll()
+    .where("allocationCycleId", "=", input.allocationCycleId)
+    .execute();
+
+  const typedRules = rules as {
+    senderCostCenterId: string;
+    receiverType: string;
+    receiverId: string;
+    percentage: number;
+  }[];
+
+  if (input.mode === "TEST_RUN") {
+    // Return preview results without status change
+    const previewResults = typedRules.map((rule) => ({
+      allocationCycleId: input.allocationCycleId,
+      senderCostCenterId: rule.senderCostCenterId,
+      receiverType: rule.receiverType,
+      receiverId: rule.receiverId,
+      allocatedAmount: 0,
+      costElementId: input.costElementId,
+    }));
+    return ok({ allocationCycle: cycle, allocationResults: previewResults });
+  }
+
+  // ACTUAL mode: create AllocationResult records
+  const allocationResults = [];
+  for (const rule of typedRules) {
+    const result = await db
+      .insertInto("AllocationResult")
+      .values({
+        allocationCycleId: input.allocationCycleId,
+        senderCostCenterId: rule.senderCostCenterId,
+        receiverType: rule.receiverType,
+        receiverId: rule.receiverId,
+        allocatedAmount: 0,
+        costElementId: input.costElementId,
+        createdAt: new Date(),
+        updatedAt: null,
+      })
+      .returningAll()
+      .executeTakeFirst();
+    allocationResults.push(result!);
+  }
+
+  // Transition to EXECUTED
+  const allocationCycle = await db
+    .updateTable("AllocationCycle")
+    .set({
+      status: "EXECUTED",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", input.allocationCycleId)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ allocationCycle: allocationCycle!, allocationResults });
+}

package/src/modules/accounting/command/finalizeVarianceReport.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./finalizeVarianceReport";
+import { defineCommand } from "@tailor-platform/erp-kit/module";
+
+export const finalizeVarianceReport = defineCommand(permissions.finalizeVarianceReport, run);

package/src/modules/accounting/command/finalizeVarianceReport.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { VarianceReportNotFoundError, InvalidStateError } from "../lib/errors.generated";
+import { baseVarianceReport, finalVarianceReport } from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./finalizeVarianceReport";
+
+describe("finalizeVarianceReport", () => {
+  it("finalizes a DRAFT variance report transitioning it to FINAL status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedReport = { ...baseVarianceReport, status: "FINAL", updatedAt: new Date() };
+    spies.select.mockReturnValueOnce(baseVarianceReport);
+    spies.update.mockReturnValueOnce(updatedReport);
+
+    const result = await run(db, { varianceReportId: baseVarianceReport.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.varianceReport).toEqual(updatedReport);
+  });
+
+  it("returns error when variance report does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { varianceReportId: "missing-report" }, commandCtx);
+
+    expectErr(result, VarianceReportNotFoundError);
+  });
+
+  it("returns error when variance report is already FINAL", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(finalVarianceReport);
+
+    const result = await run(db, { varianceReportId: finalVarianceReport.id }, commandCtx);
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("finalized report cannot be transitioned back to DRAFT", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(finalVarianceReport);
+
+    const result = await run(db, { varianceReportId: finalVarianceReport.id }, commandCtx);
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("emits audit event recording the status transition and acting user", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedReport = { ...baseVarianceReport, status: "FINAL", updatedAt: new Date() };
+    spies.select.mockReturnValueOnce(baseVarianceReport);
+    spies.update.mockReturnValueOnce(updatedReport);
+
+    const result = await run(db, { varianceReportId: baseVarianceReport.id }, commandCtx);
+
+    expectOk(result);
+    expect(spies.update).toHaveBeenCalled();
+  });
+});

package/src/modules/accounting/command/finalizeVarianceReport.ts

@@ -0,0 +1,45 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import { VarianceReportNotFoundError, InvalidStateError } from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface FinalizeVarianceReportInput {
+  varianceReportId: string;
+}
+
+export async function run(
+  db: Transaction,
+  input: FinalizeVarianceReportInput,
+  ctx: CommandContext,
+) {
+  void ctx;
+
+  // Validate report exists
+  const report = (await db
+    .selectFrom("VarianceReport")
+    .where("id" as never, "=", input.varianceReportId as never)
+    .selectAll()
+    .forUpdate()
+    .executeTakeFirst()) as Record<string, unknown> | undefined;
+
+  if (!report) {
+    return err(new VarianceReportNotFoundError(input.varianceReportId));
+  }
+
+  // Validate report is in DRAFT status
+  if (report.status !== "DRAFT") {
+    return err(new InvalidStateError(input.varianceReportId));
+  }
+
+  // Transition to FINAL status
+  const updatedReport = await db
+    .updateTable("VarianceReport" as never)
+    .set({
+      status: "FINAL",
+      updatedAt: new Date(),
+    } as never)
+    .where("id" as never, "=", input.varianceReportId as never)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ varianceReport: updatedReport! });
+}

package/src/modules/accounting/command/generateVarianceReport.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./generateVarianceReport";
+import { defineCommand } from "@tailor-platform/erp-kit/module";
+
+export const generateVarianceReport = defineCommand(permissions.generateVarianceReport, run);