@tailor-platform/erp-kit 0.6.0 → 0.7.0

package/src/modules/finance-ledger/command/generatePreliminaryStatements.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  PeriodCloseNotFoundError,
+  InvalidStatusTransitionError,
+  TrialBalanceNotFoundError,
+} from "../lib/errors.generated";
+import {
+  trialBalanceVerifiedPeriodClose,
+  softLockedPeriodClose,
+  basePeriodClose,
+  baseTrialBalance,
+  baseAccountingPeriod,
+  baseChartOfAccounts,
+  baseFinancialStatement,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./generatePreliminaryStatements";
+
+describe("generatePreliminaryStatements", () => {
+  const tbVerifiedWithTrialBalance = {
+    ...trialBalanceVerifiedPeriodClose,
+    trialBalanceId: baseTrialBalance.id,
+  };
+
+  it("returns error when PeriodClose record does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // PeriodClose lookup
+
+    const result = await run(db, { id: "nonexistent" }, commandCtx);
+
+    expectErr(result, PeriodCloseNotFoundError);
+  });
+
+  it("returns error when PeriodClose is in SOFT_LOCKED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(softLockedPeriodClose); // PeriodClose lookup
+
+    const result = await run(db, { id: softLockedPeriodClose.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when PeriodClose is in IN_PROGRESS status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce({ ...basePeriodClose, status: "IN_PROGRESS" }); // PeriodClose lookup
+
+    const result = await run(db, { id: basePeriodClose.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when trial balance is not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(tbVerifiedWithTrialBalance) // PeriodClose lookup
+      .mockReturnValueOnce(undefined); // TrialBalance lookup
+
+    const result = await run(db, { id: tbVerifiedWithTrialBalance.id }, commandCtx);
+
+    expectErr(result, TrialBalanceNotFoundError);
+  });
+
+  it("generates both BS and P&L and transitions to UNDER_REVIEW with completionPercentage=75", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    const bsStatement = {
+      ...baseFinancialStatement,
+      id: "fs-bs-1",
+      statementType: "BALANCE_SHEET",
+      status: "DRAFT",
+    };
+    const plStatement = {
+      ...baseFinancialStatement,
+      id: "fs-pl-1",
+      statementType: "PROFIT_AND_LOSS",
+      status: "DRAFT",
+    };
+    const updatedPeriodClose = {
+      ...tbVerifiedWithTrialBalance,
+      status: "UNDER_REVIEW",
+      completionPercentage: 75,
+      preliminaryStatementIds: [bsStatement.id, plStatement.id],
+    };
+
+    spies.select
+      .mockReturnValueOnce(tbVerifiedWithTrialBalance) // PeriodClose lookup
+      .mockReturnValueOnce(baseTrialBalance) // TrialBalance lookup
+      .mockReturnValueOnce(baseAccountingPeriod) // AccountingPeriod lookup
+      .mockReturnValueOnce(baseChartOfAccounts); // ChartOfAccounts lookup
+    spies.insert
+      .mockReturnValueOnce(bsStatement) // BalanceSheet insert
+      .mockReturnValueOnce(plStatement); // P&L insert
+    spies.update.mockReturnValueOnce(updatedPeriodClose);
+
+    const result = await run(db, { id: tbVerifiedWithTrialBalance.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.periodClose.status).toBe("UNDER_REVIEW");
+    expect(value.periodClose.completionPercentage).toBe(75);
+    expect(value.statements).toHaveLength(2);
+    expect(value.statements[0].statementType).toBe("BALANCE_SHEET");
+    expect(value.statements[1].statementType).toBe("PROFIT_AND_LOSS");
+    expect(value.statements[0].status).toBe("DRAFT");
+    expect(value.statements[1].status).toBe("DRAFT");
+    expect(value.periodClose.preliminaryStatementIds).toEqual([bsStatement.id, plStatement.id]);
+  });
+
+  it("emits audit event recording status transition and statement ids", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    const bsStatement = {
+      ...baseFinancialStatement,
+      id: "fs-bs-2",
+      statementType: "BALANCE_SHEET",
+      status: "DRAFT",
+    };
+    const plStatement = {
+      ...baseFinancialStatement,
+      id: "fs-pl-2",
+      statementType: "PROFIT_AND_LOSS",
+      status: "DRAFT",
+    };
+    const updatedPeriodClose = {
+      ...tbVerifiedWithTrialBalance,
+      status: "UNDER_REVIEW",
+      completionPercentage: 75,
+      preliminaryStatementIds: [bsStatement.id, plStatement.id],
+    };
+
+    spies.select
+      .mockReturnValueOnce(tbVerifiedWithTrialBalance) // PeriodClose lookup
+      .mockReturnValueOnce(baseTrialBalance) // TrialBalance lookup
+      .mockReturnValueOnce(baseAccountingPeriod) // AccountingPeriod lookup
+      .mockReturnValueOnce(baseChartOfAccounts); // ChartOfAccounts lookup
+    spies.insert.mockReturnValueOnce(bsStatement).mockReturnValueOnce(plStatement);
+    spies.update.mockReturnValueOnce(updatedPeriodClose);
+
+    const result = await run(db, { id: tbVerifiedWithTrialBalance.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.auditTrail).toBeDefined();
+    expect(value.auditTrail).toHaveLength(1);
+    expect(value.auditTrail[0].type).toBe("STATUS_TRANSITION");
+    expect(value.auditTrail[0].from).toBe("TRIAL_BALANCE_VERIFIED");
+    expect(value.auditTrail[0].to).toBe("UNDER_REVIEW");
+    expect(value.auditTrail[0].actorId).toBe(commandCtx.actorId);
+    expect(value.auditTrail[0].timestamp).toBeInstanceOf(Date);
+    expect(value.auditTrail[0].statementIds).toEqual([bsStatement.id, plStatement.id]);
+  });
+});

package/src/modules/finance-ledger/command/generatePreliminaryStatements.ts

@@ -0,0 +1,140 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  PeriodCloseNotFoundError,
+  InvalidStatusTransitionError,
+  TrialBalanceNotFoundError,
+} from "../lib/errors.generated";
+
+export interface GeneratePreliminaryStatementsInput {
+  id: string;
+}
+
+/**
+ * Function: generatePreliminaryStatements
+ *
+ * Generates preliminary Balance Sheet and P&L statements, transitions
+ * PeriodClose from TRIAL_BALANCE_VERIFIED to UNDER_REVIEW. Statements
+ * are DRAFT for management review. Requires TRIAL_BALANCE_VERIFIED status.
+ * Verifies trial balance remains balanced. Records operator's userId.
+ */
+export async function run(
+  db: Transaction,
+  input: GeneratePreliminaryStatementsInput,
+  ctx: CommandContext,
+) {
+  const { id } = input;
+
+  // 1. Find PeriodClose record
+  const periodClose = await db
+    .selectFrom("PeriodClose")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!periodClose) {
+    return err(new PeriodCloseNotFoundError(id));
+  }
+
+  // 2. Validate status is TRIAL_BALANCE_VERIFIED
+  if (periodClose.status !== "TRIAL_BALANCE_VERIFIED") {
+    return err(new InvalidStatusTransitionError(id));
+  }
+
+  // 3. Find the trial balance and verify it remains balanced
+  const trialBalance = await db
+    .selectFrom("TrialBalance")
+    .selectAll()
+    .where("id", "=", periodClose.trialBalanceId!)
+    .executeTakeFirst();
+
+  if (!trialBalance?.isBalanced) {
+    return err(new TrialBalanceNotFoundError(id));
+  }
+
+  // 4. Find accounting period for company context
+  const accountingPeriod = await db
+    .selectFrom("AccountingPeriod")
+    .selectAll()
+    .where("id", "=", periodClose.accountingPeriodId)
+    .executeTakeFirst();
+
+  // 5. Find active CoA for the company
+  const chartOfAccounts = await db
+    .selectFrom("ChartOfAccounts")
+    .selectAll()
+    .where("companyId", "=", accountingPeriod!.companyId)
+    .where("status", "=", "ACTIVE")
+    .executeTakeFirst();
+
+  // 6. Generate two DRAFT FinancialStatement records
+  const now = new Date();
+
+  const balanceSheet = await db
+    .insertInto("FinancialStatement")
+    .values({
+      companyId: accountingPeriod!.companyId,
+      chartOfAccountsId: chartOfAccounts!.id,
+      trialBalanceId: trialBalance.id,
+      comparativePeriodTrialBalanceId: null,
+      statementType: "BALANCE_SHEET",
+      status: "DRAFT",
+      reportingDate: accountingPeriod!.endDate,
+      startDate: null,
+      endDate: null,
+      cashFlowMethod: null,
+      generatedAt: now,
+      finalizedAt: null,
+      createdAt: now,
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  const profitAndLoss = await db
+    .insertInto("FinancialStatement")
+    .values({
+      companyId: accountingPeriod!.companyId,
+      chartOfAccountsId: chartOfAccounts!.id,
+      trialBalanceId: trialBalance.id,
+      comparativePeriodTrialBalanceId: null,
+      statementType: "PROFIT_AND_LOSS",
+      status: "DRAFT",
+      reportingDate: accountingPeriod!.endDate,
+      startDate: accountingPeriod!.startDate,
+      endDate: accountingPeriod!.endDate,
+      cashFlowMethod: null,
+      generatedAt: now,
+      finalizedAt: null,
+      createdAt: now,
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // 7. Update PeriodClose to UNDER_REVIEW
+  const updated = await db
+    .updateTable("PeriodClose")
+    .set({
+      status: "UNDER_REVIEW",
+      completionPercentage: 75,
+      preliminaryStatementIds: JSON.stringify([balanceSheet.id, profitAndLoss.id]),
+      updatedAt: now,
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // 8. Emit audit trail
+  const auditTrail = [
+    {
+      type: "STATUS_TRANSITION",
+      from: "TRIAL_BALANCE_VERIFIED",
+      to: "UNDER_REVIEW",
+      actorId: ctx.actorId,
+      timestamp: now,
+      statementIds: [balanceSheet.id, profitAndLoss.id],
+    },
+  ];
+
+  return ok({ periodClose: updated, statements: [balanceSheet, profitAndLoss], auditTrail });
+}

package/src/modules/finance-ledger/command/generateTrialBalance.generated.ts

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