@tailor-platform/erp-kit 0.7.0 → 0.8.0

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

@@ -0,0 +1,103 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AllocationCycleNotFoundError,
+  InvalidStateError,
+  SenderNotFoundError,
+  ReceiverNotFoundError,
+  SenderIsReceiverError,
+  InvalidPercentageError,
+} from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface CreateAllocationRuleInput {
+  allocationCycleId: string;
+  senderCostCenterId: string;
+  receiverType: string;
+  receiverId: string;
+  percentage: number;
+}
+
+export async function run(db: Transaction, input: CreateAllocationRuleInput, 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 DRAFT
+  if (cycle.status !== "DRAFT") {
+    return err(new InvalidStateError(input.allocationCycleId));
+  }
+
+  // Validate sender cost center exists
+  const sender = await db
+    .selectFrom("CostCenter")
+    .where("id", "=", input.senderCostCenterId)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!sender) {
+    return err(new SenderNotFoundError(input.senderCostCenterId));
+  }
+
+  // Validate receiver exists (polymorphic lookup)
+  let receiver: unknown;
+  if (input.receiverType === "CostCenter") {
+    receiver = await db
+      .selectFrom("CostCenter")
+      .where("id", "=", input.receiverId)
+      .selectAll()
+      .executeTakeFirst();
+  } else if (input.receiverType === "ProfitCenter") {
+    receiver = await db
+      .selectFrom("ProfitCenter")
+      .where("id", "=", input.receiverId)
+      .selectAll()
+      .executeTakeFirst();
+  } else if (input.receiverType === "InternalOrder") {
+    receiver = await db
+      .selectFrom("InternalOrder")
+      .where("id", "=", input.receiverId)
+      .selectAll()
+      .executeTakeFirst();
+  }
+
+  if (!receiver) {
+    return err(new ReceiverNotFoundError(input.receiverId));
+  }
+
+  // Validate sender is not receiver
+  if (input.receiverType === "CostCenter" && input.senderCostCenterId === input.receiverId) {
+    return err(new SenderIsReceiverError(input.senderCostCenterId));
+  }
+
+  // Validate percentage is positive
+  if (input.percentage <= 0) {
+    return err(new InvalidPercentageError(input.allocationCycleId));
+  }
+
+  // Create allocation rule
+  const allocationRule = await db
+    .insertInto("AllocationRule")
+    .values({
+      allocationCycleId: input.allocationCycleId,
+      senderCostCenterId: input.senderCostCenterId,
+      receiverType: input.receiverType,
+      receiverId: input.receiverId,
+      percentage: input.percentage,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ allocationRule: allocationRule! });
+}

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

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

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

@@ -0,0 +1,159 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  FiscalYearNotFoundError,
+  CostObjectNotFoundError,
+  PlanVersionNotFoundError,
+  InvalidNameError,
+  BudgetHolderRequiredError,
+} from "../lib/errors.generated";
+import {
+  baseCompany,
+  baseFiscalYear,
+  baseCostCenter,
+  basePlanVersion,
+  baseBudget,
+  baseUser,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./createBudget";
+
+const validInput = {
+  companyId: baseCompany.id,
+  name: "IT Budget 2024",
+  description: "Information Technology budget for FY2024",
+  budgetHolderId: baseUser.id,
+  fiscalYearId: baseFiscalYear.id,
+  costObjectType: "CostCenter" as const,
+  costObjectId: baseCostCenter.id,
+  planVersionId: basePlanVersion.id,
+};
+
+describe("createBudget", () => {
+  it("creates budget in DRAFT status with required fields", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseFiscalYear)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(basePlanVersion);
+    spies.insert.mockReturnValueOnce(baseBudget);
+
+    const result = await run(db, validInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.budget).toEqual(baseBudget);
+  });
+
+  it("returns error when company does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { ...validInput, companyId: "missing" }, commandCtx);
+
+    expectErr(result, CompanyNotFoundError);
+  });
+
+  it("returns error when company is not ACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce({ ...baseCompany, status: "INACTIVE" });
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectErr(result, CompanyNotFoundError);
+  });
+
+  it("returns error when fiscal year does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(undefined);
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectErr(result, FiscalYearNotFoundError);
+  });
+
+  it("returns error when cost object does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseFiscalYear)
+      .mockReturnValueOnce(undefined);
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectErr(result, CostObjectNotFoundError);
+  });
+
+  it("returns error when plan version does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseFiscalYear)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(undefined);
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectErr(result, PlanVersionNotFoundError);
+  });
+
+  it("returns error when name is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseFiscalYear)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(basePlanVersion);
+
+    const result = await run(db, { ...validInput, name: "" }, commandCtx);
+
+    expectErr(result, InvalidNameError);
+  });
+
+  it("returns error when budget holder is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseFiscalYear)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(basePlanVersion);
+
+    const result = await run(db, { ...validInput, budgetHolderId: null }, commandCtx);
+
+    expectErr(result, BudgetHolderRequiredError);
+  });
+
+  it("budgets from different companies are isolated", async () => {
+    const companyB = { id: "company-2", status: "ACTIVE" };
+    const budgetCompanyB = { ...baseBudget, id: "budget-company-b", companyId: companyB.id };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(companyB)
+      .mockReturnValueOnce(baseFiscalYear)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(basePlanVersion);
+    spies.insert.mockReturnValueOnce(budgetCompanyB);
+
+    const result = await run(db, { ...validInput, companyId: companyB.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.budget.companyId).toBe(companyB.id);
+  });
+
+  it("emits audit event recording acting user, timestamp, and initial field values", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseFiscalYear)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(basePlanVersion);
+    spies.insert.mockReturnValueOnce(baseBudget);
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectOk(result);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,100 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  FiscalYearNotFoundError,
+  CostObjectNotFoundError,
+  PlanVersionNotFoundError,
+  InvalidNameError,
+  BudgetHolderRequiredError,
+} from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface CreateBudgetInput {
+  companyId: string;
+  name: string;
+  description?: string | null;
+  budgetHolderId: string | null;
+  fiscalYearId: string;
+  costObjectType: "CostCenter" | "ProfitCenter" | "InternalOrder";
+  costObjectId: string;
+  planVersionId: string;
+}
+
+export async function run(db: Transaction, input: CreateBudgetInput, ctx: CommandContext) {
+  // Validate company exists and is ACTIVE
+  const company = await db
+    .selectFrom("Company" as never)
+    .where("id" as never, "=", input.companyId as never)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!company || (company as Record<string, unknown>).status !== "ACTIVE") {
+    return err(new CompanyNotFoundError(input.companyId));
+  }
+
+  // Validate fiscal year exists
+  const fiscalYear = await db
+    .selectFrom("FiscalYear" as never)
+    .where("id" as never, "=", input.fiscalYearId as never)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!fiscalYear) {
+    return err(new FiscalYearNotFoundError(input.fiscalYearId));
+  }
+
+  // Validate cost object exists (polymorphic lookup)
+  const costObject = await db
+    .selectFrom(input.costObjectType as never)
+    .where("id" as never, "=", input.costObjectId as never)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!costObject) {
+    return err(new CostObjectNotFoundError(input.costObjectId));
+  }
+
+  // Validate plan version exists
+  const planVersion = await db
+    .selectFrom("PlanVersion")
+    .where("id", "=", input.planVersionId)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!planVersion) {
+    return err(new PlanVersionNotFoundError(input.planVersionId));
+  }
+
+  // Validate name is non-empty
+  if (!input.name || input.name.trim() === "") {
+    return err(new InvalidNameError(input.companyId));
+  }
+
+  // Validate budget holder is provided
+  if (!input.budgetHolderId) {
+    return err(new BudgetHolderRequiredError(input.companyId));
+  }
+
+  // Create budget in DRAFT status
+  const budget = await db
+    .insertInto("Budget")
+    .values({
+      companyId: input.companyId,
+      name: input.name,
+      description: input.description ?? null,
+      budgetHolderId: input.budgetHolderId,
+      fiscalYearId: input.fiscalYearId,
+      costObjectType: input.costObjectType,
+      costObjectId: input.costObjectId,
+      planVersionId: input.planVersionId,
+      totalAmount: 0,
+      status: "DRAFT",
+      createdByUserId: ctx.actorId,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ budget: budget! });
+}

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

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

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

@@ -0,0 +1,178 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  BudgetNotFoundError,
+  InvalidStateError,
+  InvalidCostElementError,
+  AccountingPeriodNotFoundError,
+  InvalidPlannedAmountError,
+  DuplicateLineItemError,
+} from "../lib/errors.generated";
+import {
+  baseBudget,
+  submittedBudget,
+  activeCostElement,
+  secondaryCostElement,
+  inactiveCostElement,
+  baseAccountingPeriod,
+  baseBudgetLineItem,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./createBudgetLineItem";
+
+const validInput = {
+  budgetId: baseBudget.id,
+  costElementId: activeCostElement.id,
+  accountingPeriodId: baseAccountingPeriod.id,
+  plannedAmount: 10000,
+};
+
+describe("createBudgetLineItem", () => {
+  it("adds a line item to a DRAFT budget with valid cost element, period, and amount", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseBudget)
+      .mockReturnValueOnce(activeCostElement)
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(undefined); // no duplicate
+    spies.insert.mockReturnValueOnce(baseBudgetLineItem);
+
+    const result = await run(db, validInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.budgetLineItem).toEqual(baseBudgetLineItem);
+  });
+
+  it("derives GL account automatically from the primary cost element", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseBudget)
+      .mockReturnValueOnce(activeCostElement)
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce(baseBudgetLineItem);
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectOk(result);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("returns error when budget does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { ...validInput, budgetId: "missing" }, commandCtx);
+
+    expectErr(result, BudgetNotFoundError);
+  });
+
+  it("returns error when budget is not in DRAFT status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(submittedBudget);
+
+    const result = await run(db, { ...validInput, budgetId: submittedBudget.id }, commandCtx);
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("returns error when cost element does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseBudget).mockReturnValueOnce(undefined);
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectErr(result, InvalidCostElementError);
+  });
+
+  it("returns error when cost element is not PRIMARY type", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseBudget).mockReturnValueOnce(secondaryCostElement);
+
+    const result = await run(
+      db,
+      { ...validInput, costElementId: secondaryCostElement.id },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidCostElementError);
+  });
+
+  it("returns error when cost element is not in ACTIVE status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseBudget).mockReturnValueOnce(inactiveCostElement);
+
+    const result = await run(
+      db,
+      { ...validInput, costElementId: inactiveCostElement.id },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidCostElementError);
+  });
+
+  it("returns error when accounting period does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseBudget)
+      .mockReturnValueOnce(activeCostElement)
+      .mockReturnValueOnce(undefined);
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectErr(result, AccountingPeriodNotFoundError);
+  });
+
+  it("returns error when planned amount is zero", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseBudget)
+      .mockReturnValueOnce(activeCostElement)
+      .mockReturnValueOnce(baseAccountingPeriod);
+
+    const result = await run(db, { ...validInput, plannedAmount: 0 }, commandCtx);
+
+    expectErr(result, InvalidPlannedAmountError);
+  });
+
+  it("returns error when planned amount is negative", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseBudget)
+      .mockReturnValueOnce(activeCostElement)
+      .mockReturnValueOnce(baseAccountingPeriod);
+
+    const result = await run(db, { ...validInput, plannedAmount: -100 }, commandCtx);
+
+    expectErr(result, InvalidPlannedAmountError);
+  });
+
+  it("returns error when duplicate line item exists (same cost element and period)", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseBudget)
+      .mockReturnValueOnce(activeCostElement)
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(baseBudgetLineItem); // duplicate found
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectErr(result, DuplicateLineItemError);
+  });
+
+  it("emits audit event recording the line item creation and acting user", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseBudget)
+      .mockReturnValueOnce(activeCostElement)
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce(baseBudgetLineItem);
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectOk(result);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,104 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  BudgetNotFoundError,
+  InvalidStateError,
+  InvalidCostElementError,
+  AccountingPeriodNotFoundError,
+  InvalidPlannedAmountError,
+  DuplicateLineItemError,
+} from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface CreateBudgetLineItemInput {
+  budgetId: string;
+  costElementId: string;
+  accountingPeriodId: string;
+  plannedAmount: number;
+}
+
+export async function run(db: Transaction, input: CreateBudgetLineItemInput, ctx: CommandContext) {
+  void ctx;
+
+  // Validate budget exists and is DRAFT
+  const budget = await db
+    .selectFrom("Budget")
+    .where("id", "=", input.budgetId)
+    .selectAll()
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!budget) {
+    return err(new BudgetNotFoundError(input.budgetId));
+  }
+
+  if (budget.status !== "DRAFT") {
+    return err(new InvalidStateError(input.budgetId));
+  }
+
+  // Validate cost element exists, is PRIMARY, and ACTIVE
+  const costElement = await db
+    .selectFrom("CostElement")
+    .where("id", "=", input.costElementId)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (costElement?.type !== "PRIMARY" || costElement.status !== "ACTIVE") {
+    return err(new InvalidCostElementError(input.costElementId));
+  }
+
+  // Validate accounting period exists
+  const accountingPeriod = await db
+    .selectFrom("AccountingPeriod" as never)
+    .where("id" as never, "=", input.accountingPeriodId as never)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!accountingPeriod) {
+    return err(new AccountingPeriodNotFoundError(input.accountingPeriodId));
+  }
+
+  // Validate planned amount is positive
+  if (input.plannedAmount <= 0) {
+    return err(new InvalidPlannedAmountError(input.budgetId));
+  }
+
+  // Check for duplicate line item (same cost element + period)
+  const duplicate = await db
+    .selectFrom("BudgetLineItem")
+    .where("budgetId", "=", input.budgetId)
+    .where("costElementId", "=", input.costElementId)
+    .where("accountingPeriodId", "=", input.accountingPeriodId)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (duplicate) {
+    return err(new DuplicateLineItemError(input.budgetId));
+  }
+
+  // Create the line item
+  const lineItem = await db
+    .insertInto("BudgetLineItem")
+    .values({
+      budgetId: input.budgetId,
+      costElementId: input.costElementId,
+      accountingPeriodId: input.accountingPeriodId,
+      glAccountId: costElement.glAccountId ?? null, // Derive from cost element
+      plannedAmount: input.plannedAmount,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  // Update budget totalAmount
+  await db
+    .updateTable("Budget")
+    .set({
+      totalAmount: budget.totalAmount + input.plannedAmount,
+      updatedAt: new Date(),
+    })
+    .where("id", "=", input.budgetId)
+    .execute();
+
+  return ok({ budgetLineItem: lineItem! });
+}

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

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