@tailor-platform/erp-kit 0.5.1 → 0.7.0

package/src/modules/finance-ledger/db/financialStatement.ts

@@ -0,0 +1,92 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { chartOfAccounts as chartOfAccountsStub, company as companyStub } from "../lib/_db_deps";
+import { trialBalance } from "./trialBalance";
+
+export const FINANCIAL_STATEMENT_STATUSES: [string, string] = ["DRAFT", "FINALIZED"];
+
+export const STATEMENT_TYPES: [string, string, string] = [
+  "BALANCE_SHEET",
+  "PROFIT_AND_LOSS",
+  "CASH_FLOW",
+];
+
+export interface CreateFinancialStatementTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  companyType?: TailorAnyDBType;
+  chartOfAccountsType?: TailorAnyDBType;
+  trialBalanceType?: TailorAnyDBType;
+}
+
+export function createFinancialStatementType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateFinancialStatementTypeParams<F>,
+) {
+  return db
+    .type("FinancialStatement", {
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "financialStatements",
+        })
+        .description("Foreign key to Company"),
+      chartOfAccountsId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.chartOfAccountsType ?? chartOfAccountsStub },
+          backward: "financialStatements",
+        })
+        .description("Foreign key to ChartOfAccounts"),
+      trialBalanceId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.trialBalanceType ?? trialBalance },
+          backward: "financialStatements",
+        })
+        .description("Foreign key to the TrialBalance this statement was generated from"),
+      comparativePeriodTrialBalanceId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: params.trialBalanceType ?? trialBalance },
+          backward: "comparativeFinancialStatements",
+        })
+        .description("Optional foreign key to a prior-period TrialBalance for comparative data"),
+      statementType: db.enum(STATEMENT_TYPES).description("Type of financial statement"),
+      status: db
+        .enum(FINANCIAL_STATEMENT_STATUSES)
+        .description("Financial statement lifecycle status"),
+      reportingDate: db
+        .date({ optional: true })
+        .description("As-of date for Balance Sheet statements"),
+      startDate: db
+        .date({ optional: true })
+        .description("Start date of the reporting period for P&L and Cash Flow statements"),
+      endDate: db
+        .date({ optional: true })
+        .description("End date of the reporting period for P&L and Cash Flow statements"),
+      cashFlowMethod: db
+        .string({ optional: true })
+        .description(
+          "Cash flow method — DIRECT or INDIRECT — applicable only to Cash Flow statements",
+        ),
+      generatedAt: db.datetime().description("Timestamp when the statement was generated"),
+      finalizedAt: db
+        .datetime({ optional: true })
+        .description("Timestamp when the statement was finalized"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const financialStatement = createFinancialStatementType({});

package/src/modules/finance-ledger/db/financialStatementLineItem.ts

@@ -0,0 +1,76 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { account as accountStub, accountGroup as accountGroupStub } from "../lib/_db_deps";
+import { financialStatement } from "./financialStatement";
+
+export const FINANCIAL_STATEMENT_LINE_ITEM_LINE_TYPES: [string, string, string] = [
+  "DETAIL",
+  "SUBTOTAL",
+  "TOTAL",
+];
+
+export interface CreateFinancialStatementLineItemTypeParams<
+  F extends Record<string, TailorAnyDBField>,
+> {
+  fields?: F;
+  financialStatementType?: TailorAnyDBType;
+  accountType?: TailorAnyDBType;
+  accountGroupType?: TailorAnyDBType;
+}
+
+export function createFinancialStatementLineItemType<
+  const F extends Record<string, TailorAnyDBField>,
+>(params: CreateFinancialStatementLineItemTypeParams<F>) {
+  return db
+    .type("FinancialStatementLineItem", {
+      financialStatementId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.financialStatementType ?? financialStatement },
+          backward: "lineItems",
+        })
+        .description("Foreign key to FinancialStatement"),
+      accountId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: params.accountType ?? accountStub },
+          backward: "financialStatementLineItems",
+        })
+        .description("Foreign key to Account for DETAIL line items (coa-management)"),
+      accountGroupId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: params.accountGroupType ?? accountGroupStub },
+          backward: "financialStatementLineItems",
+        })
+        .description("Foreign key to AccountGroup (coa-management)"),
+      label: db.string().description("Display label for the line item"),
+      amount: db.float().description("Current period amount in base currency"),
+      comparativeAmount: db
+        .float({ optional: true })
+        .description("Comparative period amount, present when comparative data was requested"),
+      lineType: db
+        .enum(FINANCIAL_STATEMENT_LINE_ITEM_LINE_TYPES)
+        .description("Line type: DETAIL, SUBTOTAL, or TOTAL"),
+      sectionType: db
+        .string()
+        .description(
+          "Report section where this line item appears (e.g., Current Assets, Revenue, Operating Expenses)",
+        ),
+      sortOrder: db.int().description("Display positioning order within the statement"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const financialStatementLineItem = createFinancialStatementLineItemType({});

package/src/modules/finance-ledger/db/fiscalYear.ts

@@ -0,0 +1,41 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { company as companyStub } from "../lib/_db_deps";
+
+export interface CreateFiscalYearTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  companyType?: TailorAnyDBType;
+}
+
+export function createFiscalYearType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateFiscalYearTypeParams<F>,
+) {
+  return db
+    .type("FiscalYear", {
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "fiscalYears",
+        })
+        .description("Foreign key to Company"),
+      name: db.string().description("Display name of the fiscal year"),
+      startDate: db.date().description("Start date of the fiscal year"),
+      endDate: db.date().description("End date of the fiscal year"),
+      yearEndCloseExecuted: db
+        .bool()
+        .description("Tracks whether year-end close has been run for this fiscal year"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const fiscalYear = createFiscalYearType({});

package/src/modules/finance-ledger/db/journalEntry.ts

@@ -0,0 +1,101 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { company as companyStub } from "../lib/_db_deps";
+import { accountingPeriod } from "./accountingPeriod";
+
+export const JOURNAL_ENTRY_STATUSES: [string, string, string] = ["DRAFT", "POSTED", "REVERSED"];
+
+export const JOURNAL_TYPES: [
+  string,
+  string,
+  string,
+  string,
+  string,
+  string,
+  string,
+  string,
+  string,
+] = [
+  "SALES",
+  "PURCHASE",
+  "CASH",
+  "BANK",
+  "MISCELLANEOUS",
+  "OPENING",
+  "CLOSING",
+  "INVENTORY",
+  "MANUFACTURING",
+];
+
+const ADJUSTING_ENTRY_TYPES = ["ACCRUAL", "DEFERRAL", "RECLASSIFICATION"] as const;
+
+export interface CreateJournalEntryTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  companyType?: TailorAnyDBType;
+  accountingPeriodType?: TailorAnyDBType;
+}
+
+export function createJournalEntryType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateJournalEntryTypeParams<F>,
+) {
+  return db
+    .type("JournalEntry", {
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "journalEntries",
+        })
+        .description("Foreign key to Company"),
+      accountingPeriodId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.accountingPeriodType ?? accountingPeriod },
+          backward: "journalEntries",
+        })
+        .description("Foreign key to AccountingPeriod"),
+      entryDate: db.date().description("Journal entry document date"),
+      journalType: db
+        .enum(JOURNAL_TYPES)
+        .description(
+          "Journal type categorizing the business origin (SALES, PURCHASE, CASH, BANK, MISCELLANEOUS, OPENING, CLOSING, INVENTORY, MANUFACTURING)",
+        ),
+      referenceNumber: db.string().description("Reference number unique within the company scope"),
+      status: db
+        .enum(JOURNAL_ENTRY_STATUSES)
+        .description("Journal entry lifecycle status (DRAFT, POSTED, REVERSED)"),
+      description: db
+        .string({ optional: true })
+        .description("Optional description of the journal entry"),
+      sourceDocumentReference: db
+        .string({ optional: true })
+        .description("Optional source document reference (e.g. PurchaseBill:purchase-bill-1)"),
+      adjustingEntryType: db
+        .enum([...ADJUSTING_ENTRY_TYPES], { optional: true })
+        .description(
+          "Optional adjusting entry type for period-end adjustments (ACCRUAL, DEFERRAL, RECLASSIFICATION)",
+        ),
+      reversalOfId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: "self" },
+          backward: "reversals",
+        })
+        .description("Optional self-referencing FK to the original JournalEntry being reversed"),
+      postedAt: db.datetime({ optional: true }).description("Timestamp when the entry was posted"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const journalEntry = createJournalEntryType({});

package/src/modules/finance-ledger/db/journalLine.ts

@@ -0,0 +1,64 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { account as accountStub } from "../lib/_db_deps";
+import { journalEntry } from "./journalEntry";
+
+export interface CreateJournalLineTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  journalEntryType?: TailorAnyDBType;
+  accountType?: TailorAnyDBType;
+}
+
+export function createJournalLineType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateJournalLineTypeParams<F>,
+) {
+  return db
+    .type("JournalLine", {
+      journalEntryId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.journalEntryType ?? journalEntry },
+          backward: "lines",
+        })
+        .description("Foreign key to JournalEntry"),
+      accountId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.accountType ?? accountStub },
+          backward: "journalLines",
+        })
+        .description("Foreign key to Account (coa-management)"),
+      debitAmount: db
+        .float({ optional: true })
+        .description("Debit amount (mutually exclusive with creditAmount)"),
+      creditAmount: db
+        .float({ optional: true })
+        .description("Credit amount (mutually exclusive with debitAmount)"),
+      description: db.string({ optional: true }).description("Optional line-level description"),
+      currencyCode: db
+        .string({ optional: true })
+        .description("Optional foreign currency code referencing Currency in primitives module"),
+      exchangeRate: db
+        .float({ optional: true })
+        .description("Exchange rate to functional currency (defaults to 1.0)"),
+      functionalDebitAmount: db
+        .float({ optional: true })
+        .description("Computed: debitAmount * exchangeRate"),
+      functionalCreditAmount: db
+        .float({ optional: true })
+        .description("Computed: creditAmount * exchangeRate"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const journalLine = createJournalLineType({});

package/src/modules/finance-ledger/db/periodClose.ts

@@ -0,0 +1,97 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { user as userStub } from "../lib/_db_deps";
+import { accountingPeriod } from "./accountingPeriod";
+
+export const PERIOD_CLOSE_STATUSES: [
+  string,
+  string,
+  string,
+  string,
+  string,
+  string,
+  string,
+  string,
+] = [
+  "NOT_STARTED",
+  "IN_PROGRESS",
+  "SUBLEDGERS_VERIFIED",
+  "ADJUSTMENTS_POSTED",
+  "TRIAL_BALANCE_VERIFIED",
+  "UNDER_REVIEW",
+  "SOFT_LOCKED",
+  "PERMANENTLY_CLOSED",
+];
+
+export interface CreatePeriodCloseTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  accountingPeriodType?: TailorAnyDBType;
+  initiatedByUserType?: TailorAnyDBType;
+  approvedByUserType?: TailorAnyDBType;
+  finalizedByUserType?: TailorAnyDBType;
+}
+
+export function createPeriodCloseType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreatePeriodCloseTypeParams<F>,
+) {
+  return db
+    .type("PeriodClose", {
+      accountingPeriodId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.accountingPeriodType ?? accountingPeriod },
+          backward: "periodCloses",
+        })
+        .description("Foreign key to AccountingPeriod"),
+      status: db.enum(PERIOD_CLOSE_STATUSES).description("Period close lifecycle status"),
+      initiatedByUserId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.initiatedByUserType ?? userStub },
+          backward: "initiatedPeriodCloses",
+        })
+        .description("Foreign key to User who initiated the close"),
+      completionPercentage: db
+        .int()
+        .description("Completion percentage incremented per checklist step"),
+      subledgerVerificationDetails: db
+        .string({ optional: true })
+        .description("Serialized JSON details of subledger verification"),
+      trialBalanceId: db
+        .uuid({ optional: true })
+        .description("Reference to generated trial balance after verification"),
+      preliminaryStatementIds: db
+        .string({ optional: true })
+        .description("Serialized JSON array of preliminary statement IDs"),
+      approvedByUserId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: params.approvedByUserType ?? userStub },
+          backward: "approvedPeriodCloses",
+        })
+        .description("Foreign key to User who approved the close"),
+      finalizedByUserId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: params.finalizedByUserType ?? userStub },
+          backward: "finalizedPeriodCloses",
+        })
+        .description("Foreign key to User who finalized the permanent close"),
+      yearEndCloseExecuted: db.bool().description("Whether year-end close has been executed"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const periodClose = createPeriodCloseType({});

package/src/modules/finance-ledger/db/trialBalance.ts

@@ -0,0 +1,63 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { chartOfAccounts as chartOfAccountsStub, company as companyStub } from "../lib/_db_deps";
+import { accountingPeriod } from "./accountingPeriod";
+
+export const TRIAL_BALANCE_VARIANTS: [string, string] = ["PRE_CLOSE", "POST_CLOSE"];
+
+export interface CreateTrialBalanceTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  companyType?: TailorAnyDBType;
+  accountingPeriodType?: TailorAnyDBType;
+  chartOfAccountsType?: TailorAnyDBType;
+}
+
+export function createTrialBalanceType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateTrialBalanceTypeParams<F>,
+) {
+  return db
+    .type("TrialBalance", {
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "trialBalances",
+        })
+        .description("Foreign key to Company"),
+      accountingPeriodId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.accountingPeriodType ?? accountingPeriod },
+          backward: "trialBalances",
+        })
+        .description("Foreign key to AccountingPeriod"),
+      chartOfAccountsId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.chartOfAccountsType ?? chartOfAccountsStub },
+          backward: "trialBalances",
+        })
+        .description("Foreign key to ChartOfAccounts"),
+      variant: db
+        .enum(TRIAL_BALANCE_VARIANTS)
+        .description("Trial balance variant (PRE_CLOSE or POST_CLOSE)"),
+      generatedAt: db.datetime().description("Timestamp when the trial balance was generated"),
+      totalDebits: db.float().description("Sum of all debit balances across accounts"),
+      totalCredits: db.float().description("Sum of all credit balances across accounts"),
+      isBalanced: db.bool().description("Whether totalDebits equals totalCredits"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const trialBalance = createTrialBalanceType({});

package/src/modules/finance-ledger/db/trialBalanceLine.ts

@@ -0,0 +1,63 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { account as accountStub, accountGroup as accountGroupStub } from "../lib/_db_deps";
+import { trialBalance } from "./trialBalance";
+
+export interface CreateTrialBalanceLineTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  trialBalanceType?: TailorAnyDBType;
+  accountType?: TailorAnyDBType;
+  accountGroupType?: TailorAnyDBType;
+}
+
+export function createTrialBalanceLineType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateTrialBalanceLineTypeParams<F>,
+) {
+  return db
+    .type("TrialBalanceLine", {
+      trialBalanceId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.trialBalanceType ?? trialBalance },
+          backward: "trialBalanceLines",
+        })
+        .description("Foreign key to TrialBalance"),
+      accountId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.accountType ?? accountStub },
+          backward: "trialBalanceLines",
+        })
+        .description("Foreign key to Account"),
+      accountGroupId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: params.accountGroupType ?? accountGroupStub },
+          backward: "trialBalanceLines",
+        })
+        .description("Optional foreign key to AccountGroup for hierarchical aggregation"),
+      accountCode: db.string().description("Denormalized account code for display and ordering"),
+      accountName: db.string().description("Denormalized account name for display"),
+      openingBalance: db.float().description("Opening balance for the period"),
+      periodDebits: db.float().description("Total debits for the period"),
+      periodCredits: db.float().description("Total credits for the period"),
+      closingBalance: db
+        .float()
+        .description("Closing balance (computed: openingBalance + periodDebits - periodCredits)"),
+      sortOrder: db.int().description("Sort order within the trial balance"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const trialBalanceLine = createTrialBalanceLineType({});

package/src/modules/finance-ledger/docs/commands/AddJournalLine.md

@@ -0,0 +1,74 @@
+# AddJournalLine
+
+## Overview
+
+addJournalLine adds a new line item to a DRAFT journal entry. Each journal line references a GL account (from coa-management) and specifies either a debit amount or a credit amount. For multi-currency transactions, the line can include a currency code and exchange rate; otherwise it defaults to the company's functional currency with an exchange rate of 1.0. An optional line-level description can be provided for additional detail.
+
+## Business Rules
+
+- Journal entry must exist and be in DRAFT status
+- Lines cannot be added to POSTED or REVERSED entries
+- Each line must reference a valid GL account ID from coa-management
+- Each line must specify either a debit amount or a credit amount (not both, and not zero for both)
+- Debit and credit amounts must be positive values
+- For multi-currency lines, a currency code and exchange rate must be specified
+- Lines without an explicit currency default to the company's functional currency with exchange rate 1.0
+- The functional currency amount is computed as the foreign amount multiplied by the exchange rate
+- Line-level description is optional
+- Emits an audit event recording the line addition, acting user, and timestamp
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive add journal line request] --> B{Journal entry exists?}
+    B -->|No| C[Return error: journal entry not found]
+    B -->|Yes| D{Entry status is DRAFT?}
+    D -->|No| E[Return error: cannot add lines to non-draft entry]
+    D -->|Yes| F{Valid GL account reference?}
+    F -->|No| G[Return error: invalid account]
+    F -->|Yes| H{Debit or credit specified correctly?}
+    H -->|No| I[Return error: invalid debit/credit]
+    H -->|Yes| J{Multi-currency?}
+    J -->|Yes| K[Validate currency and exchange rate]
+    K --> L{Currency valid?}
+    L -->|No| M[Return error: invalid currency]
+    L -->|Yes| N[Compute functional currency amount]
+    J -->|No| N[Use functional currency defaults]
+    N --> O[Create journal line]
+    O --> P[Emit audit event]
+    P --> Q[Return created journal line]
+```
+
+## External Dependencies
+
+- [coa-management::getAccount](../../../coa-management/docs/queries/GetAccount.md) - Validates that the referenced GL account exists
+- [primitives::getCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validates that the referenced currency exists and is active (for multi-currency lines)
+
+## Error Scenarios
+
+- **JOURNAL_ENTRY_NOT_FOUND**: Referenced journal entry does not exist
+- **INVALID_STATUS_FOR_LINE_ADD**: Journal entry is not in DRAFT status
+- **ACCOUNT_NOT_FOUND**: Referenced GL account does not exist
+- **INVALID_DEBIT_CREDIT**: Both debit and credit specified, or both are zero, or amounts are negative
+- **CURRENCY_NOT_FOUND**: Referenced currency does not exist or is not active
+
+## Test Cases
+
+- returns error when journal entry does not exist
+- returns error when journal entry is in POSTED status
+- returns error when journal entry is in REVERSED status
+- returns error when GL account does not exist
+- returns error when GL account is not active
+- returns error when both debit and credit amounts are specified
+- returns error when both debit and credit amounts are zero
+- returns error when debit amount is negative
+- returns error when credit amount is negative
+- returns error when currency does not exist for multi-currency line
+- adds journal line with debit amount to DRAFT entry
+- adds journal line with credit amount to DRAFT entry
+- adds multi-currency journal line with currency and exchange rate
+- defaults to functional currency with exchange rate 1.0 when currency not specified
+- computes functional currency amount as foreign amount multiplied by exchange rate
+- adds journal line with optional description
+- emits audit event recording line addition and acting user