@tailor-platform/erp-kit 0.7.0 → 0.9.0

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);

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

@@ -0,0 +1,179 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  DuplicateCostCenterCodeError,
+  InvalidCategoryError,
+  HierarchyNodeNotFoundError,
+  CompanyMismatchError,
+  InvalidValidityPeriodError,
+  InvalidNameError,
+} from "../lib/errors.generated";
+import {
+  baseCompany,
+  baseCostCenter,
+  baseCostCenterHierarchy,
+  childCostCenterNode,
+  baseDepartment,
+  baseUser,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./createCostCenter";
+
+const validInput = {
+  companyId: baseCompany.id,
+  code: "CC-NEW",
+  name: "New Cost Center",
+  category: "overhead",
+  hierarchyNodeId: childCostCenterNode.id,
+  validFrom: new Date("2024-01-01"),
+  responsiblePersonId: baseUser.id,
+  departmentId: baseDepartment.id,
+};
+
+describe("createCostCenter", () => {
+  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 name is empty", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany);
+
+    const result = await run(db, { ...validInput, name: "" }, commandCtx);
+
+    expectErr(result, InvalidNameError);
+  });
+
+  it("returns error when code already exists within company", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany) // company exists
+      .mockReturnValueOnce(baseCostCenter); // duplicate code found
+
+    const result = await run(db, { ...validInput, code: baseCostCenter.code }, commandCtx);
+
+    expectErr(result, DuplicateCostCenterCodeError);
+  });
+
+  it("returns error when category is invalid", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany) // company exists
+      .mockReturnValueOnce(undefined); // no duplicate code
+
+    const result = await run(db, { ...validInput, category: "invalid_category" }, commandCtx);
+
+    expectErr(result, InvalidCategoryError);
+  });
+
+  it("returns error when hierarchy node does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany) // company exists
+      .mockReturnValueOnce(undefined) // no duplicate code
+      .mockReturnValueOnce(undefined); // hierarchy node not found
+
+    const result = await run(db, { ...validInput, hierarchyNodeId: "missing-node" }, commandCtx);
+
+    expectErr(result, HierarchyNodeNotFoundError);
+  });
+
+  it("returns error when hierarchy node belongs to different company", async () => {
+    const otherCompanyHierarchy = { ...baseCostCenterHierarchy, companyId: "other-company" };
+
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany) // company exists
+      .mockReturnValueOnce(undefined) // no duplicate code
+      .mockReturnValueOnce(childCostCenterNode) // hierarchy node found
+      .mockReturnValueOnce(otherCompanyHierarchy); // hierarchy belongs to different company
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectErr(result, CompanyMismatchError);
+  });
+
+  it("returns error when validTo is before validFrom", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany) // company exists
+      .mockReturnValueOnce(undefined) // no duplicate code
+      .mockReturnValueOnce(childCostCenterNode) // hierarchy node found
+      .mockReturnValueOnce(baseCostCenterHierarchy); // hierarchy in same company
+
+    const result = await run(
+      db,
+      {
+        ...validInput,
+        validFrom: new Date("2024-12-31"),
+        validTo: new Date("2024-01-01"),
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidValidityPeriodError);
+  });
+
+  it("creates cost center with valid inputs", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany) // company exists
+      .mockReturnValueOnce(undefined) // no duplicate code
+      .mockReturnValueOnce(childCostCenterNode) // hierarchy node found
+      .mockReturnValueOnce(baseCostCenterHierarchy); // hierarchy in same company
+    spies.insert.mockReturnValueOnce(baseCostCenter);
+
+    const result = await run(db, validInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.costCenter).toEqual(baseCostCenter);
+  });
+
+  it("creates cost center without optional fields", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(childCostCenterNode)
+      .mockReturnValueOnce(baseCostCenterHierarchy);
+    spies.insert.mockReturnValueOnce({
+      ...baseCostCenter,
+      responsiblePersonId: null,
+      departmentId: null,
+      description: null,
+      validTo: null,
+    });
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        code: "CC-NEW",
+        name: "New Cost Center",
+        category: "overhead",
+        hierarchyNodeId: childCostCenterNode.id,
+        validFrom: new Date("2024-01-01"),
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.costCenter).toBeDefined();
+  });
+});

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

@@ -0,0 +1,112 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  DuplicateCostCenterCodeError,
+  InvalidCategoryError,
+  HierarchyNodeNotFoundError,
+  CompanyMismatchError,
+  InvalidValidityPeriodError,
+  InvalidNameError,
+} from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+const VALID_CATEGORIES = ["overhead", "production", "administration", "sales", "research"];
+
+export interface CreateCostCenterInput {
+  companyId: string;
+  code: string;
+  name: string;
+  description?: string | null;
+  category: string;
+  responsiblePersonId?: string | null;
+  departmentId?: string | null;
+  hierarchyNodeId: string;
+  validFrom: Date;
+  validTo?: Date | null;
+}
+
+export async function run(db: Transaction, input: CreateCostCenterInput, ctx: CommandContext) {
+  void ctx;
+
+  // 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 name is non-empty
+  if (!input.name || input.name.trim() === "") {
+    return err(new InvalidNameError(input.companyId));
+  }
+
+  // Validate code uniqueness within company
+  const existingCode = await db
+    .selectFrom("CostCenter")
+    .where("companyId", "=", input.companyId)
+    .where("code", "=", input.code)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (existingCode) {
+    return err(new DuplicateCostCenterCodeError(input.code));
+  }
+
+  // Validate category
+  if (!VALID_CATEGORIES.includes(input.category)) {
+    return err(new InvalidCategoryError(input.category));
+  }
+
+  // Validate hierarchy node exists
+  const hierarchyNode = await db
+    .selectFrom("CostCenterHierarchyNode")
+    .where("id", "=", input.hierarchyNodeId)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!hierarchyNode) {
+    return err(new HierarchyNodeNotFoundError(input.hierarchyNodeId));
+  }
+
+  // Validate hierarchy node belongs to same company via hierarchy
+  const hierarchy = await db
+    .selectFrom("CostCenterHierarchy")
+    .where("id", "=", hierarchyNode.hierarchyId)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (hierarchy?.companyId !== input.companyId) {
+    return err(new CompanyMismatchError(input.hierarchyNodeId));
+  }
+
+  // Validate validity dates
+  if (input.validTo && input.validFrom > input.validTo) {
+    return err(new InvalidValidityPeriodError(input.code));
+  }
+
+  // Create cost center
+  const costCenter = await db
+    .insertInto("CostCenter")
+    .values({
+      companyId: input.companyId,
+      code: input.code,
+      name: input.name,
+      description: input.description ?? null,
+      category: input.category,
+      responsiblePersonId: input.responsiblePersonId ?? null,
+      departmentId: input.departmentId ?? null,
+      hierarchyNodeId: input.hierarchyNodeId,
+      validFrom: input.validFrom,
+      validTo: input.validTo ?? null,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ costCenter: costCenter! });
+}

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

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