Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
// The journals of the period runs and the manual scrap: depreciation,
// deferred tax, disposal and revenue recognition. Pure: no database, no
// clock, no random values. Two callers write them:
// - the ERP's posting (`postDepreciationRun`, `postDisposal`,
// `postRevenueRecognitionRun`, apps/erp/app/modules/accounting/
// accounting.service.ts): Posted, in the periods the operation resolved;
// - the enable's legacy backfill (`buildLegacyDepreciationJournals` and its
// siblings, same file): Provisional, from the stored rows.
// The caller gathers the facts and writes the result. The journal id, the
// entry number, the period, the status, each line's `journalLineReference`
// and the dimension ids are the caller's.
//
// A line's `dimensions` holds its values by entity type, null when it has
// none. The caller writes a row for each value whose dimension the company
// has.
import { type AccountClass, toStoredAmount } from "./ledger.ts";
import { equals } from "./precision.ts";
import { RUN_SOURCE_TYPE, type RunType } from "./run-type.ts";
import type { Database } from "./types.ts";
type Enums = Database["public"]["Enums"];
/**
* A deferred tax journal, and each line of it, books only an amount above
* this. The legacy detection (`deferredTaxMonth`, legacy-documents.ts) tests
* the same amount in SQL.
*/
export const DEFERRED_TAX_MIN_AMOUNT = 0.01;
export type RunLineDimensions = Partial<
Record<Enums["dimensionEntityType"], string | null>
>;
/** A journal line, with its natural-signed stored amount. */
export type RunJournalLine = {
accountId: string;
description: string;
amount: number;
documentType?: Enums["journalLineDocumentType"];
documentId?: string;
/** The document's line: a lessee lease row's asset (`leaseLine`). */
documentLineReference?: string | null;
dimensions: RunLineDimensions;
};
export type RunJournal = {
description: string;
sourceType: Enums["journalEntrySourceType"];
/** Can be empty: the ERP still writes the journal (see each builder). */
lines: RunJournalLine[];
};
type Asset = { locationId: string | null; fixedAssetClassId: string };
function assetDimensions(asset: Asset): RunLineDimensions {
return {
Location: asset.locationId,
FixedAssetClass: asset.fixedAssetClassId
};
}
// ---------------------------------------------------------------------------
// Depreciation
// ---------------------------------------------------------------------------
/** A depreciation run line, with its asset and the asset's class accounts. */
export type DepreciationRunLine = Asset & {
id: string;
/** The line's month, else the run's period end. */
monthEnd: string;
amount: number;
taxAmount: number | null;
assetReadableId: string;
depreciationExpenseAccountId: string;
accumulatedDepreciationAccountId: string;
};
export type DepreciationJournal = RunJournal & {
lineId: string;
monthEnd: string;
};
/**
* One journal per line with a book amount: Dr depreciation expense, Cr
* accumulated depreciation. A line with no book amount (tax only) has none;
* it still counts toward the month's deferred tax.
*
* Quirk: the amount goes through `toStoredAmount` as a debit, so a negative
* amount stores 0 on the expense line and its magnitude on the accumulated
* line, an unbalanced journal. The ERP has always written it so.
*/
export function buildDepreciationJournals(
lines: DepreciationRunLine[]
): DepreciationJournal[] {
return lines
.filter((line) => !equals(line.amount, 0))
.map((line) => ({
lineId: line.id,
monthEnd: line.monthEnd,
description: `Depreciation: ${line.assetReadableId}`,
sourceType: "Asset Depreciation",
lines: [
{
accountId: line.depreciationExpenseAccountId,
description: "Depreciation Expense",
amount: toStoredAmount(line.amount, 0, "Expense"),
dimensions: assetDimensions(line)
},
{
accountId: line.accumulatedDepreciationAccountId,
description: "Accumulated Depreciation",
amount: toStoredAmount(0, line.amount, "Asset"),
dimensions: assetDimensions(line)
}
]
}));
}
export type DeferredTaxSettings = {
/** Percent, e.g. 25. */
taxRate: number;
dtlAccountId: string;
dtExpenseAccountId: string;
};
/** The deferred tax settings, or null when tax depreciation does not book
* deferred tax: off, no rate, or a deferred tax account missing. */
export function deferredTaxSettings(args: {
enabled: boolean | null | undefined;
taxRate: number | null | undefined;
dtlAccountId: string | null | undefined;
dtExpenseAccountId: string | null | undefined;
}): DeferredTaxSettings | null {
const { enabled, taxRate, dtlAccountId, dtExpenseAccountId } = args;
return enabled && taxRate && dtlAccountId && dtExpenseAccountId
? { taxRate, dtlAccountId, dtExpenseAccountId }
: null;
}
export type DeferredTaxJournal = RunJournal & {
/** Every line of the month, which stores this journal's id. */
lineIds: string[];
monthEnd: string;
};
/**
* One deferred tax journal per month of a run, for the temporary difference
* (tax − book, a missing tax amount is 0) at the tax rate, when it is above
* `DEFERRED_TAX_MIN_AMOUNT`. Tax ahead of book is a liability (Dr expense,
* Cr liability); book ahead of tax unwinds it (Dr liability, Cr benefit).
* Two lines per location and asset class whose own amount is above the
* minimum. Months come in the order of their first line.
*
* Quirks the ERP has always had: the amounts are not rounded; and when the
* month's total is above the minimum but no group's is, the journal has no
* lines and its lines still store its id.
*/
export function buildDeferredTaxJournals(args: {
runReadableId: string;
lines: DepreciationRunLine[];
settings: DeferredTaxSettings | null;
}): DeferredTaxJournal[] {
const { runReadableId, lines, settings } = args;
if (!settings) return [];
const { taxRate, dtlAccountId, dtExpenseAccountId } = settings;
const linesByMonth = new Map<string, DepreciationRunLine[]>();
for (const line of lines) {
const monthLines = linesByMonth.get(line.monthEnd) ?? [];
monthLines.push(line);
linesByMonth.set(line.monthEnd, monthLines);
}
const journals: DeferredTaxJournal[] = [];
for (const [monthEnd, monthLines] of linesByMonth) {
const diffByGroup = new Map<string, Asset & { diff: number }>();
for (const line of monthLines) {
const diff = (line.taxAmount ?? 0) - line.amount;
const key = `${line.locationId ?? ""}|${line.fixedAssetClassId}`;
const existing = diffByGroup.get(key);
if (existing) {
existing.diff += diff;
} else {
diffByGroup.set(key, {
locationId: line.locationId,
fixedAssetClassId: line.fixedAssetClassId,
diff
});
}
}
const total = [...diffByGroup.values()].reduce(
(sum, group) => sum + group.diff,
0
);
if (!(Math.abs(total * (taxRate / 100)) > DEFERRED_TAX_MIN_AMOUNT)) {
continue;
}
const isLiability = total > 0;
journals.push({
lineIds: monthLines.map((line) => line.id),
monthEnd,
description: `Deferred Tax: Depreciation ${runReadableId}`,
sourceType: "Asset Depreciation",
lines: [...diffByGroup.values()]
.filter(
(group) =>
Math.abs(group.diff * (taxRate / 100)) > DEFERRED_TAX_MIN_AMOUNT
)
.flatMap((group) => {
const amount = Math.abs(group.diff * (taxRate / 100));
const dimensions = assetDimensions(group);
return [
{
accountId: isLiability ? dtExpenseAccountId : dtlAccountId,
description: isLiability
? "Deferred Tax Expense"
: "Deferred Tax Liability",
amount: toStoredAmount(
amount,
0,
isLiability ? "Expense" : "Liability"
),
dimensions
},
{
accountId: isLiability ? dtlAccountId : dtExpenseAccountId,
description: isLiability
? "Deferred Tax Liability"
: "Deferred Tax Benefit",
amount: toStoredAmount(
0,
amount,
isLiability ? "Liability" : "Expense"
),
dimensions
}
];
})
});
}
return journals;
}
// ---------------------------------------------------------------------------
// Disposal
// ---------------------------------------------------------------------------
/** An asset leaving the books with no proceeds, with its class accounts. */
export type Disposal = Asset & {
assetReadableId: string;
disposalMethod: Enums["disposalMethod"];
disposalDate: string;
acquisitionCost: number;
accumulatedDepreciation: number;
assetAccountId: string;
accumulatedDepreciationAccountId: string;
lossOnDisposalAccountId: string;
};
/**
* The scrap journal: Dr accumulated depreciation, Dr loss on disposal for the
* whole net book value (no proceeds, so gain/loss = 0 − NBV, booked to the
* dedicated Loss on Disposal account), Cr the asset at cost.
*/
export function buildDisposalJournal(
disposal: Disposal
): RunJournal & { postingDate: string; netBookValue: number } {
const netBookValue =
disposal.acquisitionCost - disposal.accumulatedDepreciation;
const dimensions = assetDimensions(disposal);
const lines: RunJournalLine[] = [];
if (disposal.accumulatedDepreciation > 0) {
lines.push({
accountId: disposal.accumulatedDepreciationAccountId,
description: "Clear accumulated depreciation",
amount: toStoredAmount(disposal.accumulatedDepreciation, 0, "Asset"),
dimensions
});
}
if (netBookValue > 0) {
lines.push({
accountId: disposal.lossOnDisposalAccountId,
description: "Loss on disposal (scrap)",
amount: toStoredAmount(netBookValue, 0, "Expense"),
dimensions
});
}
lines.push({
accountId: disposal.assetAccountId,
description: "Remove asset at cost",
amount: toStoredAmount(0, disposal.acquisitionCost, "Asset"),
dimensions
});
return {
description: `Asset Disposal: ${disposal.assetReadableId} (${disposal.disposalMethod})`,
postingDate: disposal.disposalDate,
sourceType: "Asset Disposal",
lines,
netBookValue
};
}
// ---------------------------------------------------------------------------
// Revenue recognition
// ---------------------------------------------------------------------------
type RevenueScheduleType = Enums["revenueScheduleType"];
const REVENUE_LINE_DESCRIPTIONS: Record<
RevenueScheduleType,
{ debit: string; credit: string }
> = {
Deferral: {
debit: "Deferred revenue released",
credit: "Revenue recognized"
},
Accrual: { debit: "Unbilled rent accrued", credit: "Rental income accrued" },
Interest: {
debit: "Net investment interest",
credit: "Lease interest income"
},
Amortization: {
debit: "Lease cost recognized",
credit: "Right-of-use asset amortized"
}
};
/** A lessee lease's rows: interest accretes the liability; the ROU asset
* amortizes. Operating leases book both legs to the lease cost account. */
const LESSEE_LINE_DESCRIPTIONS: Partial<
Record<RevenueScheduleType, { debit: string; credit: string }>
> = {
Interest: { debit: "Lease interest", credit: "Lease liability accretion" },
Amortization: {
debit: "Lease cost recognized",
credit: "Right-of-use asset amortized"
}
};
const CONTRACT_ACCRUAL_DESCRIPTIONS = {
debit: "Contract asset accrued",
credit: "Revenue recognized"
};
/** A revenue recognition schedule row, with the amount its run posts. */
export type RecognitionScheduleRow = {
scheduleId: string;
/** The date the row's journal posts on: its month's end, or the date the
* caller posts that month on. Rows of one date share a journal. */
postingDate: string;
type: RevenueScheduleType;
amount: number;
debitAccountId: string;
creditAccountId: string;
salesInvoiceLineId: string | null;
rentalAgreementLineId: string | null;
customerContractLineId: string | null;
rentalLeaseScheduleLineId: string | null;
/** A lessee lease's row: the lease, and the schedule line it posts. */
leaseId: string | null;
leaseScheduleLineId: string | null;
};
/** The documents the rows' journal lines reference, by source line id. */
export type RecognitionSources = {
invoiceLines: Map<
string,
{
invoiceId: string;
customerId: string | null;
itemId: string | null;
locationId: string | null;
}
>;
rentalLines: Map<
string,
{
rentalAgreementId: string;
customerId: string | null;
itemId: string | null;
locationId: string | null;
}
>;
contractLines: Map<
string,
{
customerContractId: string;
customerId: string | null;
itemId: string | null;
/** The contract line's project, else the contract's. */
projectId: string | null;
}
>;
/** Lessee leases, by lease id. Every lessee row's lease must be here. */
leases: Map<string, { supplierId: string; locationId: string | null }>;
/** Each lessee schedule line's asset and the asset's location, by
* `leaseScheduleLine` id. Every lessee row's line must be here. */
leaseAssets: Map<string, { leaseLineId: string; locationId: string | null }>;
};
export type RecognitionJournal = RunJournal & {
postingDate: string;
/** The schedule rows that store this journal's id. */
scheduleIds: string[];
/** The contract rows among them: their ledger entries store it too. */
contractScheduleIds: string[];
/** The rental (sales-type) lease schedule lines whose Interest rows it posts. */
leaseScheduleLineIds: string[];
/** The lessee lease schedule lines whose rows it posts. */
lesseeScheduleLineIds: string[];
};
/** The first debit or credit account of the rows with no class, in row
* order, or undefined when every account has one. */
export function recognitionAccountWithoutClass(
rows: Pick<RecognitionScheduleRow, "debitAccountId" | "creditAccountId">[],
classById: Map<string, AccountClass>
): string | undefined {
for (const row of rows) {
if (!classById.has(row.debitAccountId)) return row.debitAccountId;
if (!classById.has(row.creditAccountId)) return row.creditAccountId;
}
return undefined;
}
function recognitionSource(
row: RecognitionScheduleRow,
sources: RecognitionSources
): Pick<
RunJournalLine,
"documentType" | "documentId" | "documentLineReference" | "dimensions"
> {
// A lessee lease's row references the lease and its asset, with the
// supplier and the asset's location (else the lease's). Both must be
// loaded: a line with no supplier or asset would post untraceably.
if (row.leaseId) {
const lease = sources.leases.get(row.leaseId);
if (!lease) {
throw new Error(
`Lease ${row.leaseId} of schedule row ${row.scheduleId} was not loaded`
);
}
const asset = row.leaseScheduleLineId
? sources.leaseAssets.get(row.leaseScheduleLineId)
: undefined;
if (!asset) {
throw new Error(
`The leased asset of schedule row ${row.scheduleId} was not loaded`
);
}
return {
documentType: "Lease",
documentId: row.leaseId,
documentLineReference: asset.leaseLineId,
dimensions: {
Supplier: lease.supplierId,
Location: asset.locationId ?? lease.locationId
}
};
}
// A row references its invoice, else its rental agreement, else its
// contract.
const invoice = row.salesInvoiceLineId
? sources.invoiceLines.get(row.salesInvoiceLineId)
: undefined;
const rental =
!invoice && row.rentalAgreementLineId
? sources.rentalLines.get(row.rentalAgreementLineId)
: undefined;
const contract =
!invoice && !rental && row.customerContractLineId
? sources.contractLines.get(row.customerContractLineId)
: undefined;
const document = invoice
? { documentType: "Invoice" as const, documentId: invoice.invoiceId }
: rental
? {
documentType: "Rental Agreement" as const,
documentId: rental.rentalAgreementId
}
: contract
? {
documentType: "Contract" as const,
documentId: contract.customerContractId
}
: {};
const source = invoice ?? rental ?? contract;
return {
...document,
dimensions: {
Customer: source?.customerId ?? null,
Item: source?.itemId ?? null,
Location: (invoice ?? rental)?.locationId ?? null,
Project: contract?.projectId ?? null
}
};
}
/**
* The journals of one revenue recognition run: one per posting date, in date
* order, and two lines per row with an amount, each on the row's own
* accounts, signed by the account's class. A negative row (a credit memo's
* deferral) reverses the legs: the debit leg of a negative row is a credit
* of its magnitude, and the reverse. A date whose rows all have no amount
* still gets a journal, with no lines. The run's journal is the one of its
* own period end, else the latest.
*
* Throws when an account of any row has no class, or when a lessee row's
* lease or leased asset is not in `sources`.
*/
export function buildRecognitionJournals(args: {
/** A lease run posts as 'Lease Run', a revenue recognition run as
* 'Revenue Recognition'. */
runType: RunType;
runReadableId: string;
runPeriodEnd: string;
rows: RecognitionScheduleRow[];
sources: RecognitionSources;
classById: Map<string, AccountClass>;
}): { journals: RecognitionJournal[]; runJournal: RecognitionJournal | null } {
const { runType, runReadableId, runPeriodEnd, rows, sources, classById } =
args;
const unclassified = recognitionAccountWithoutClass(rows, classById);
if (unclassified) {
throw new Error(
`Account ${unclassified} on the revenue schedule has no class`
);
}
const classOf = (accountId: string) => classById.get(accountId)!;
const byDate = new Map<string, RecognitionJournal>();
for (const row of rows) {
const journal = byDate.get(row.postingDate) ?? {
description: `${RUN_SOURCE_TYPE[runType]} ${runReadableId}`,
sourceType: RUN_SOURCE_TYPE[runType],
postingDate: row.postingDate,
lines: [],
scheduleIds: [],
contractScheduleIds: [],
leaseScheduleLineIds: [],
lesseeScheduleLineIds: []
};
byDate.set(row.postingDate, journal);
journal.scheduleIds.push(row.scheduleId);
if (row.customerContractLineId) {
journal.contractScheduleIds.push(row.scheduleId);
}
if (
row.rentalLeaseScheduleLineId &&
!journal.leaseScheduleLineIds.includes(row.rentalLeaseScheduleLineId)
) {
journal.leaseScheduleLineIds.push(row.rentalLeaseScheduleLineId);
}
if (
row.leaseScheduleLineId &&
!journal.lesseeScheduleLineIds.includes(row.leaseScheduleLineId)
) {
journal.lesseeScheduleLineIds.push(row.leaseScheduleLineId);
}
if (row.amount === 0) continue;
const descriptions =
(row.leaseId ? LESSEE_LINE_DESCRIPTIONS[row.type] : undefined) ??
(row.customerContractLineId && row.type === "Accrual"
? CONTRACT_ACCRUAL_DESCRIPTIONS
: REVENUE_LINE_DESCRIPTIONS[row.type]);
const magnitude = Math.abs(row.amount);
const debitClass = classOf(row.debitAccountId);
const creditClass = classOf(row.creditAccountId);
const source = recognitionSource(row, sources);
journal.lines.push(
{
accountId: row.debitAccountId,
description: descriptions.debit,
amount:
row.amount > 0
? toStoredAmount(magnitude, 0, debitClass)
: toStoredAmount(0, magnitude, debitClass),
...source
},
{
accountId: row.creditAccountId,
description: descriptions.credit,
amount:
row.amount > 0
? toStoredAmount(0, magnitude, creditClass)
: toStoredAmount(magnitude, 0, creditClass),
...source
}
);
}
const journals = [...byDate.values()].sort((a, b) =>
a.postingDate.localeCompare(b.postingDate)
);
return {
journals,
runJournal:
byDate.get(runPeriodEnd) ?? journals[journals.length - 1] ?? null
};
}