@tailor-platform/erp-kit 0.2.2 → 0.4.0

package/src/modules/coa-management/command/updateAccount.ts

@@ -0,0 +1,370 @@
+import { randomUUID } from "node:crypto";
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountNotFoundError,
+  ChartOfAccountsArchivedError,
+  NameRequiredError,
+  InvalidAccountCodeError,
+  DuplicateAccountCodeError,
+  StructuralFieldImmutableError,
+  IncompatibleClassificationError,
+  DuplicateRetainedEarningsError,
+  ReconciliationRequiredError,
+  CurrencyNotFoundError,
+  AccountGroupNotFoundError,
+  CodeOutOfRangeError,
+} from "../lib/errors.generated";
+
+export interface UpdateAccountInput {
+  id: string;
+  name?: string;
+  code?: string;
+  accountType?: "ASSET" | "LIABILITY" | "EQUITY" | "REVENUE" | "EXPENSE";
+  classification?:
+    | "REGULAR"
+    | "RECEIVABLE"
+    | "PAYABLE"
+    | "BANK_CASH"
+    | "FIXED_ASSET"
+    | "RETAINED_EARNINGS"
+    | "NON_POSTING";
+  reconciliation?: boolean;
+  currencyRestriction?: string | null;
+  defaultTaxCode?: string | null;
+  tags?: string | null;
+  accountGroupId?: string | null;
+}
+
+export interface AuditCommands {
+  logAuditEvent: (
+    db: Transaction,
+    input: {
+      eventId: string;
+      actorType: string;
+      actorId: string;
+      entityType: string;
+      entityId: string;
+      operationType: string;
+      companyId?: string;
+      changes: { fieldName: string; oldValue?: unknown; newValue?: unknown }[];
+    },
+    ctx: CommandContext,
+  ) => Promise<{ ok: true; value: unknown }>;
+}
+
+interface GetCurrencyDep {
+  getCurrency: (
+    db: Transaction,
+    input: { id: string },
+    ctx: CommandContext,
+  ) => Promise<{ ok: true; value: { currency: { id: string; isActive: boolean } | null } }>;
+}
+
+const CLASSIFICATION_TYPE_MAP: Record<string, string[]> = {
+  RECEIVABLE: ["ASSET"],
+  BANK_CASH: ["ASSET"],
+  FIXED_ASSET: ["ASSET"],
+  PAYABLE: ["LIABILITY"],
+  RETAINED_EARNINGS: ["EQUITY"],
+};
+
+const RECONCILIATION_REQUIRED_CLASSIFICATIONS = ["RECEIVABLE", "PAYABLE", "BANK_CASH"];
+
+/**
+ * Function: updateAccount
+ *
+ * Modifies attributes of an existing GL account. Structural fields (code,
+ * type, classification, currency restriction) become immutable once the
+ * account has posted transactions.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: UpdateAccountInput & CF,
+  ctx: CommandContext,
+  deps?: GetCurrencyDep,
+  auditCommands?: AuditCommands,
+) {
+  const {
+    id,
+    name,
+    code,
+    accountType,
+    classification,
+    reconciliation,
+    currencyRestriction,
+    defaultTaxCode,
+    tags,
+    accountGroupId,
+    ...customFields
+  } = input;
+
+  // 1. Find account with forUpdate
+  const account = await db
+    .selectFrom("Account")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!account) {
+    return err(new AccountNotFoundError(id));
+  }
+
+  // 2. Look up parent CoA
+  const coa = await db
+    .selectFrom("ChartOfAccounts")
+    .selectAll()
+    .where("id", "=", account.chartOfAccountsId)
+    .executeTakeFirst();
+
+  if (!coa || coa.status === "ARCHIVED") {
+    return err(new ChartOfAccountsArchivedError(account.chartOfAccountsId));
+  }
+
+  // 3. Validate name if provided
+  if (name?.trim() === "") {
+    return err(new NameRequiredError(id));
+  }
+
+  // 4. Check structural field immutability
+  const structuralChanged =
+    (code !== undefined && code !== account.code) ||
+    (accountType !== undefined && accountType !== account.accountType) ||
+    (classification !== undefined && classification !== account.classification) ||
+    (currencyRestriction !== undefined && currencyRestriction !== account.currencyRestriction);
+
+  if (structuralChanged && account.hasPostedTransactions) {
+    return err(new StructuralFieldImmutableError(id));
+  }
+
+  // 5. Validate code if changed
+  const effectiveCode = code ?? account.code;
+  if (code !== undefined && code !== account.code) {
+    if (!/^\d+$/.test(code)) {
+      return err(new InvalidAccountCodeError(code));
+    }
+
+    const existingAccount = await db
+      .selectFrom("Account")
+      .selectAll()
+      .where("chartOfAccountsId", "=", account.chartOfAccountsId)
+      .where("code", "=", code)
+      .executeTakeFirst();
+
+    if (existingAccount && existingAccount.id !== id) {
+      return err(new DuplicateAccountCodeError(code));
+    }
+  }
+
+  // 6. Classification compatibility
+  const effectiveClassification = classification ?? account.classification;
+  const effectiveAccountType = accountType ?? account.accountType;
+  if (classification !== undefined || accountType !== undefined) {
+    const allowedTypes = CLASSIFICATION_TYPE_MAP[effectiveClassification];
+    if (allowedTypes && !allowedTypes.includes(effectiveAccountType)) {
+      return err(new IncompatibleClassificationError(effectiveClassification));
+    }
+  }
+
+  // 7. RETAINED_EARNINGS uniqueness
+  if (classification === "RETAINED_EARNINGS" && account.classification !== "RETAINED_EARNINGS") {
+    const existingRetained = await db
+      .selectFrom("Account")
+      .selectAll()
+      .where("chartOfAccountsId", "=", account.chartOfAccountsId)
+      .where("classification", "=", "RETAINED_EARNINGS")
+      .executeTakeFirst();
+
+    if (existingRetained && existingRetained.id !== id) {
+      return err(new DuplicateRetainedEarningsError(account.chartOfAccountsId));
+    }
+  }
+
+  // 8. Reconciliation invariant
+  const isReconciliationRequired =
+    RECONCILIATION_REQUIRED_CLASSIFICATIONS.includes(effectiveClassification);
+  if (isReconciliationRequired) {
+    if (reconciliation === false) {
+      return err(new ReconciliationRequiredError(effectiveClassification));
+    }
+  }
+
+  // 9. Currency validation
+  if (currencyRestriction !== undefined && currencyRestriction !== null) {
+    if (deps) {
+      const result = await deps.getCurrency(db, { id: currencyRestriction }, ctx);
+      if (!result.value.currency?.isActive) {
+        return err(new CurrencyNotFoundError(currencyRestriction));
+      }
+    }
+  }
+
+  // 10. Group validation
+  const _effectiveGroupId = accountGroupId !== undefined ? accountGroupId : account.accountGroupId;
+  if (accountGroupId !== undefined && accountGroupId !== null) {
+    const group = await db
+      .selectFrom("AccountGroup")
+      .selectAll()
+      .where("id", "=", accountGroupId)
+      .executeTakeFirst();
+
+    if (group?.chartOfAccountsId !== account.chartOfAccountsId) {
+      return err(new AccountGroupNotFoundError(accountGroupId));
+    }
+
+    // Check code within range if range defined
+    if (group.numberRangeStart != null && group.numberRangeEnd != null) {
+      const codeNum = parseInt(effectiveCode, 10);
+      if (codeNum < group.numberRangeStart || codeNum > group.numberRangeEnd) {
+        return err(new CodeOutOfRangeError(effectiveCode));
+      }
+    }
+  } else if (
+    code !== undefined &&
+    code !== account.code &&
+    account.accountGroupId &&
+    accountGroupId === undefined
+  ) {
+    // Code changed, account has existing group, group assignment not being changed
+    const group = await db
+      .selectFrom("AccountGroup")
+      .selectAll()
+      .where("id", "=", account.accountGroupId)
+      .executeTakeFirst();
+
+    if (group?.numberRangeStart != null && group.numberRangeEnd != null) {
+      const codeNum = parseInt(code, 10);
+      if (codeNum < group.numberRangeStart || codeNum > group.numberRangeEnd) {
+        return err(new CodeOutOfRangeError(code));
+      }
+    }
+  }
+
+  // 11. Build update data
+  const RESERVED_KEYS = new Set([
+    "id",
+    "chartOfAccountsId",
+    "name",
+    "code",
+    "accountType",
+    "classification",
+    "reconciliation",
+    "currencyRestriction",
+    "defaultTaxCode",
+    "tags",
+    "accountGroupId",
+    "successorAccountId",
+    "hasPostedTransactions",
+    "status",
+    "createdAt",
+    "updatedAt",
+  ]);
+  const safeCustomFields: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(customFields)) {
+    if (!RESERVED_KEYS.has(key)) {
+      safeCustomFields[key] = value;
+    }
+  }
+
+  const updateData: Record<string, unknown> = {
+    ...safeCustomFields,
+    updatedAt: new Date(),
+  };
+
+  if (name !== undefined) updateData.name = name;
+  if (code !== undefined) updateData.code = code;
+  if (accountType !== undefined) updateData.accountType = accountType;
+  if (classification !== undefined) updateData.classification = classification;
+  if (reconciliation !== undefined) updateData.reconciliation = reconciliation;
+  // Force reconciliation true if classification requires it
+  if (isReconciliationRequired && reconciliation === undefined) {
+    updateData.reconciliation = true;
+  }
+  if (currencyRestriction !== undefined) updateData.currencyRestriction = currencyRestriction;
+  if (defaultTaxCode !== undefined) updateData.defaultTaxCode = defaultTaxCode;
+  if (tags !== undefined) updateData.tags = tags;
+  if (accountGroupId !== undefined) updateData.accountGroupId = accountGroupId;
+
+  const updated = await db
+    .updateTable("Account")
+    .set(updateData)
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirst();
+
+  // 12. Emit audit event
+  if (auditCommands) {
+    const changes: { fieldName: string; oldValue?: unknown; newValue?: unknown }[] = [];
+    if (name !== undefined && name !== account.name) {
+      changes.push({ fieldName: "name", oldValue: account.name, newValue: name });
+    }
+    if (code !== undefined && code !== account.code) {
+      changes.push({ fieldName: "code", oldValue: account.code, newValue: code });
+    }
+    if (accountType !== undefined && accountType !== account.accountType) {
+      changes.push({
+        fieldName: "accountType",
+        oldValue: account.accountType,
+        newValue: accountType,
+      });
+    }
+    if (classification !== undefined && classification !== account.classification) {
+      changes.push({
+        fieldName: "classification",
+        oldValue: account.classification,
+        newValue: classification,
+      });
+    }
+    if (reconciliation !== undefined && reconciliation !== account.reconciliation) {
+      changes.push({
+        fieldName: "reconciliation",
+        oldValue: account.reconciliation,
+        newValue: reconciliation,
+      });
+    }
+    if (currencyRestriction !== undefined && currencyRestriction !== account.currencyRestriction) {
+      changes.push({
+        fieldName: "currencyRestriction",
+        oldValue: account.currencyRestriction,
+        newValue: currencyRestriction,
+      });
+    }
+    if (defaultTaxCode !== undefined && defaultTaxCode !== account.defaultTaxCode) {
+      changes.push({
+        fieldName: "defaultTaxCode",
+        oldValue: account.defaultTaxCode,
+        newValue: defaultTaxCode,
+      });
+    }
+    if (tags !== undefined && tags !== account.tags) {
+      changes.push({ fieldName: "tags", oldValue: account.tags, newValue: tags });
+    }
+    if (accountGroupId !== undefined && accountGroupId !== account.accountGroupId) {
+      changes.push({
+        fieldName: "accountGroupId",
+        oldValue: account.accountGroupId,
+        newValue: accountGroupId,
+      });
+    }
+
+    if (changes.length > 0) {
+      await auditCommands.logAuditEvent(
+        db,
+        {
+          eventId: randomUUID(),
+          actorType: "USER",
+          actorId: ctx.actorId,
+          entityType: "Account",
+          entityId: id,
+          operationType: "UPDATE",
+          companyId: coa.companyId,
+          changes,
+        },
+        ctx,
+      );
+    }
+  }
+
+  return ok({ account: updated! });
+}

package/src/modules/coa-management/command/updateAccountGroup.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { defineCommand } from "../../../shared";
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./updateAccountGroup";
+
+export const updateAccountGroup = defineCommand(permissions.updateAccountGroup, run);

package/src/modules/coa-management/command/updateAccountGroup.test.ts

@@ -0,0 +1,253 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountGroupNotFoundError,
+  ChartOfAccountsArchivedError,
+  NameRequiredError,
+  InvalidNumberRangeError,
+  AccountsOutOfRangeError,
+} from "../lib/errors.generated";
+import {
+  baseActiveCoa,
+  baseArchivedCoa,
+  baseRootGroup,
+  baseChildGroup,
+  baseGroupNoRange,
+  baseActiveAccount,
+} from "../testing/fixtures";
+import { run } from "./updateAccountGroup";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["coa-management:updateAccountGroup"],
+};
+
+describe("updateAccountGroup", () => {
+  it("returns error when group does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // Group lookup
+
+    const result = await run(db, { id: "nonexistent", name: "New Name" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(AccountGroupNotFoundError);
+    }
+  });
+
+  it("returns error when parent CoA is ARCHIVED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const groupInArchivedCoa = { ...baseRootGroup, chartOfAccountsId: baseArchivedCoa.id };
+    spies.select
+      .mockReturnValueOnce(groupInArchivedCoa) // Group lookup
+      .mockReturnValueOnce(baseArchivedCoa); // CoA lookup
+
+    const result = await run(db, { id: groupInArchivedCoa.id, name: "New Name" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ChartOfAccountsArchivedError);
+    }
+  });
+
+  it("returns error when name is empty", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseRootGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa); // CoA lookup
+
+    const result = await run(db, { id: baseRootGroup.id, name: "" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(NameRequiredError);
+    }
+  });
+
+  it("returns error when new number range is invalid", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseRootGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa); // CoA lookup
+
+    const result = await run(
+      db,
+      { id: baseRootGroup.id, numberRangeStart: 2000, numberRangeEnd: 1000 },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidNumberRangeError);
+    }
+  });
+
+  it("returns error when updating to one-sided number range (start only)", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const groupNoRange = { ...baseGroupNoRange };
+    spies.select
+      .mockReturnValueOnce(groupNoRange) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa); // CoA lookup
+
+    const result = await run(db, { id: groupNoRange.id, numberRangeStart: 2000 }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidNumberRangeError);
+    }
+  });
+
+  it("returns error when updating to one-sided number range (end only)", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const groupNoRange = { ...baseGroupNoRange };
+    spies.select
+      .mockReturnValueOnce(groupNoRange) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa); // CoA lookup
+
+    const result = await run(db, { id: groupNoRange.id, numberRangeEnd: 2999 }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidNumberRangeError);
+    }
+  });
+
+  it("returns error when new number range overlaps with another group", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const otherGroup = { ...baseGroupNoRange, numberRangeStart: 2000, numberRangeEnd: 2999 };
+    spies.select
+      .mockReturnValueOnce(baseRootGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce([baseRootGroup, otherGroup]) // Existing groups for overlap check
+      .mockReturnValueOnce([]); // No assigned accounts
+
+    const result = await run(
+      db,
+      { id: baseRootGroup.id, numberRangeStart: 1500, numberRangeEnd: 2500 },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidNumberRangeError);
+    }
+  });
+
+  it("returns error when existing accounts fall outside new number range", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const groupWithRange = { ...baseChildGroup, id: "group-with-accounts" };
+    const accountOutOfRange = {
+      ...baseActiveAccount,
+      code: "1500",
+      accountGroupId: "group-with-accounts",
+    };
+    spies.select
+      .mockReturnValueOnce(groupWithRange) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce([groupWithRange]) // Existing groups (only self, no overlap)
+      .mockReturnValueOnce([accountOutOfRange]); // Assigned accounts out of new range
+
+    const result = await run(
+      db,
+      { id: groupWithRange.id, numberRangeStart: 1100, numberRangeEnd: 1199 },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(AccountsOutOfRangeError);
+    }
+  });
+
+  it("updates group name", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedGroup = { ...baseRootGroup, name: "Updated Assets" };
+    spies.select
+      .mockReturnValueOnce(baseRootGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa); // CoA lookup
+    spies.update.mockReturnValue(updatedGroup);
+
+    const result = await run(db, { id: baseRootGroup.id, name: "Updated Assets" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.accountGroup.name).toBe("Updated Assets");
+    }
+  });
+
+  it("updates sort order", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedGroup = { ...baseRootGroup, sortOrder: 10 };
+    spies.select
+      .mockReturnValueOnce(baseRootGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa); // CoA lookup
+    spies.update.mockReturnValue(updatedGroup);
+
+    const result = await run(db, { id: baseRootGroup.id, sortOrder: 10 }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.accountGroup.sortOrder).toBe(10);
+    }
+  });
+
+  it("updates number range", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedGroup = { ...baseRootGroup, numberRangeStart: 1000, numberRangeEnd: 1499 };
+    spies.select
+      .mockReturnValueOnce(baseRootGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce([baseRootGroup]) // Existing groups (only self)
+      .mockReturnValueOnce([]); // No assigned accounts
+    spies.update.mockReturnValue(updatedGroup);
+
+    const result = await run(
+      db,
+      { id: baseRootGroup.id, numberRangeStart: 1000, numberRangeEnd: 1499 },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.accountGroup.numberRangeStart).toBe(1000);
+      expect(result.value.accountGroup.numberRangeEnd).toBe(1499);
+    }
+  });
+
+  it("emits audit event recording previous and new field values", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedGroup = { ...baseRootGroup, name: "Renamed Assets", updatedAt: new Date() };
+    spies.select
+      .mockReturnValueOnce(baseRootGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa); // CoA lookup
+    spies.update.mockReturnValue(updatedGroup);
+
+    const result = await run(db, { id: baseRootGroup.id, name: "Renamed Assets" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      // The returned value contains all updated fields for audit logging
+      expect(result.value.accountGroup.name).toBe("Renamed Assets");
+      expect(result.value.accountGroup.updatedAt).toBeDefined();
+    }
+    expect(spies.update).toHaveBeenCalled();
+    expect(spies.set).toHaveBeenCalledWith(expect.objectContaining({ name: "Renamed Assets" }));
+  });
+
+  it("passes custom fields through to update", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedGroup = { ...baseRootGroup, customField: "custom-value" };
+    spies.select
+      .mockReturnValueOnce(baseRootGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa); // CoA lookup
+    spies.update.mockReturnValue(updatedGroup);
+
+    await run(db, { id: baseRootGroup.id, name: "Updated", customField: "custom-value" }, ctx);
+
+    expect(spies.set).toHaveBeenCalledWith(
+      expect.objectContaining({ customField: "custom-value" }),
+    );
+  });
+});