mirror of
https://github.com/Tria-plc/edr-platform.git
synced 2026-08-29 21:08:12 +00:00
Muluhabt ERP modules
This commit is contained in:
Mulu Mehari
458
apps/finance-api/src/modules/reports/reports.service.ts
Normal file
458
apps/finance-api/src/modules/reports/reports.service.ts
Normal file
@@ -0,0 +1,458 @@
|
||||
import { BadRequestException, Injectable } from "@nestjs/common";
|
||||
import { DataSource } from "typeorm";
|
||||
|
||||
import type { ActorContext } from "../../common/current-actor.util";
|
||||
import { LEDGER_CURRENCY, roundMoney } from "../../common/money";
|
||||
|
||||
/**
|
||||
* Module 4.6 — financial reports.
|
||||
*
|
||||
* Read-only, raw SQL, exactly the approach HR's 3.7 reports settled on: these
|
||||
* are cross-table aggregates over posted entries, and expressing them through
|
||||
* an ORM would obscure arithmetic that has to be readable to be trusted.
|
||||
*
|
||||
* Two rules hold throughout:
|
||||
*
|
||||
* 1. **Only POSTED entries count.** A draft has not happened. Every query
|
||||
* filters `status <> 'DRAFT'`, and REVERSED entries ARE included — a
|
||||
* reversal is a real transaction, and its own mirrored entry is what
|
||||
* cancels it out. Excluding reversed entries would leave the reversal
|
||||
* unmatched and unbalance the books.
|
||||
*
|
||||
* 2. **Sign by normal balance.** A debit-balance account reports
|
||||
* debits − credits; a credit-balance account the reverse. Reporting raw
|
||||
* debits − credits everywhere would show all revenue as negative.
|
||||
*/
|
||||
const num = (v: unknown): number => Number(v ?? 0);
|
||||
|
||||
/** Posted, non-deleted, in this organization — the base every report shares. */
|
||||
const POSTED = `e.status <> 'DRAFT' AND e.deleted_at IS NULL AND e.organization_id = $1`;
|
||||
|
||||
export type TrialBalanceRow = {
|
||||
accountCode: string;
|
||||
accountName: { am: string; en: string };
|
||||
accountType: string;
|
||||
normalBalance: string;
|
||||
debit: number;
|
||||
credit: number;
|
||||
};
|
||||
|
||||
@Injectable()
|
||||
export class ReportsService {
|
||||
constructor(private readonly dataSource: DataSource) {}
|
||||
|
||||
/**
|
||||
* Trial balance — every account's net movement, in the column its balance
|
||||
* naturally falls in.
|
||||
*
|
||||
* The totals MUST match. If they do not, something has bypassed the journal
|
||||
* service (a hand-written UPDATE, a restore from a bad backup), and the
|
||||
* report says so rather than presenting two different numbers side by side
|
||||
* and leaving the reader to notice.
|
||||
*/
|
||||
async trialBalance(
|
||||
actor: ActorContext,
|
||||
dateFrom: string,
|
||||
dateTo: string,
|
||||
): Promise<{
|
||||
rows: TrialBalanceRow[];
|
||||
totalDebit: number;
|
||||
totalCredit: number;
|
||||
balanced: boolean;
|
||||
difference: number;
|
||||
}> {
|
||||
const organizationId = this.requireOrganization(actor);
|
||||
|
||||
const rows = await this.dataSource.query<Record<string, unknown>[]>(
|
||||
`SELECT a.code AS "accountCode",
|
||||
a.name AS "accountName",
|
||||
a.account_type AS "accountType",
|
||||
a.normal_balance AS "normalBalance",
|
||||
ROUND(COALESCE(SUM(l.debit), 0), 2) AS "debitTotal",
|
||||
ROUND(COALESCE(SUM(l.credit), 0), 2) AS "creditTotal"
|
||||
FROM finance.accounts a
|
||||
JOIN finance.journal_lines l ON l.account_id = a.id
|
||||
JOIN finance.journal_entries e ON e.id = l.journal_entry_id
|
||||
WHERE ${POSTED}
|
||||
AND e.entry_date >= $2::date
|
||||
AND e.entry_date <= $3::date
|
||||
AND a.deleted_at IS NULL
|
||||
GROUP BY a.id, a.code, a.name, a.account_type, a.normal_balance
|
||||
HAVING COALESCE(SUM(l.debit), 0) <> 0 OR COALESCE(SUM(l.credit), 0) <> 0
|
||||
ORDER BY a.code ASC`,
|
||||
[organizationId, dateFrom, dateTo],
|
||||
);
|
||||
|
||||
const mapped: TrialBalanceRow[] = rows.map((row) => {
|
||||
const debitTotal = num(row.debitTotal);
|
||||
const creditTotal = num(row.creditTotal);
|
||||
const net = roundMoney(debitTotal - creditTotal);
|
||||
// Each account reports ONE side — its net, in the column it belongs in.
|
||||
// Showing gross debits and credits for every account would inflate both
|
||||
// totals and hide whether the account is actually in an odd position.
|
||||
return {
|
||||
accountCode: String(row.accountCode),
|
||||
accountName: row.accountName as { am: string; en: string },
|
||||
accountType: String(row.accountType),
|
||||
normalBalance: String(row.normalBalance),
|
||||
debit: net > 0 ? net : 0,
|
||||
credit: net < 0 ? roundMoney(-net) : 0,
|
||||
};
|
||||
});
|
||||
|
||||
const totalDebit = roundMoney(mapped.reduce((s, r) => s + r.debit, 0));
|
||||
const totalCredit = roundMoney(mapped.reduce((s, r) => s + r.credit, 0));
|
||||
const difference = roundMoney(totalDebit - totalCredit);
|
||||
|
||||
return {
|
||||
rows: mapped,
|
||||
totalDebit,
|
||||
totalCredit,
|
||||
balanced: Math.abs(difference) < 0.005,
|
||||
difference,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Profit and loss for a date range.
|
||||
*
|
||||
* `is_contra` is deliberately NOT applied as a sign flip here. Signing by the
|
||||
* account's normal balance already produces the right answer: a contra
|
||||
* revenue account (sales returns) accrues on the debit side, so
|
||||
* `credit − debit` comes out negative and reduces revenue on its own.
|
||||
* Flipping again would turn a deduction into an addition. The flag is
|
||||
* presentational — it tells the UI to indent the line, not the arithmetic to
|
||||
* invert it.
|
||||
*/
|
||||
async profitAndLoss(actor: ActorContext, dateFrom: string, dateTo: string) {
|
||||
const organizationId = this.requireOrganization(actor);
|
||||
|
||||
const rows = await this.dataSource.query<Record<string, unknown>[]>(
|
||||
`SELECT a.code AS "accountCode",
|
||||
a.name AS "accountName",
|
||||
a.account_type AS "accountType",
|
||||
a.is_contra AS "isContra",
|
||||
ROUND(COALESCE(SUM(
|
||||
CASE WHEN a.normal_balance = 'CREDIT'
|
||||
THEN l.credit - l.debit
|
||||
ELSE l.debit - l.credit END), 0), 2) AS amount
|
||||
FROM finance.accounts a
|
||||
JOIN finance.journal_lines l ON l.account_id = a.id
|
||||
JOIN finance.journal_entries e ON e.id = l.journal_entry_id
|
||||
WHERE ${POSTED}
|
||||
AND e.entry_date >= $2::date
|
||||
AND e.entry_date <= $3::date
|
||||
AND a.account_type IN ('REVENUE','EXPENSE')
|
||||
AND a.deleted_at IS NULL
|
||||
GROUP BY a.id, a.code, a.name, a.account_type, a.is_contra
|
||||
HAVING COALESCE(SUM(l.debit), 0) <> 0 OR COALESCE(SUM(l.credit), 0) <> 0
|
||||
ORDER BY a.code ASC`,
|
||||
[organizationId, dateFrom, dateTo],
|
||||
);
|
||||
|
||||
const signed = rows.map((row) => ({
|
||||
accountCode: String(row.accountCode),
|
||||
accountName: row.accountName as { am: string; en: string },
|
||||
accountType: String(row.accountType),
|
||||
isContra: Boolean(row.isContra),
|
||||
amount: num(row.amount),
|
||||
}));
|
||||
|
||||
const revenue = signed.filter((r) => r.accountType === "REVENUE");
|
||||
const expenses = signed.filter((r) => r.accountType === "EXPENSE");
|
||||
const totalRevenue = roundMoney(revenue.reduce((s, r) => s + r.amount, 0));
|
||||
const totalExpenses = roundMoney(expenses.reduce((s, r) => s + r.amount, 0));
|
||||
|
||||
return {
|
||||
dateFrom,
|
||||
dateTo,
|
||||
currency: LEDGER_CURRENCY,
|
||||
revenue,
|
||||
expenses,
|
||||
totalRevenue,
|
||||
totalExpenses,
|
||||
netResult: roundMoney(totalRevenue - totalExpenses),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Balance sheet as at a date.
|
||||
*
|
||||
* Everything up to `asOf`, not a range — a balance sheet is a position, not a
|
||||
* movement. The accounting equation is checked and reported: assets must
|
||||
* equal liabilities plus equity plus the result earned so far, and that last
|
||||
* term is why the P&L has to be folded in rather than shown separately.
|
||||
*
|
||||
* As in the P&L, `is_contra` is NOT applied as a sign flip. Accumulated
|
||||
* depreciation is an ASSET-type account that carries a credit balance, so
|
||||
* signing by type already yields a negative figure that reduces total assets.
|
||||
* Flipping it as well made it positive and ADDED the depreciation to the
|
||||
* asset side — which is precisely how the equation came out wrong by twice
|
||||
* the accumulated depreciation.
|
||||
*/
|
||||
async balanceSheet(actor: ActorContext, asOf: string) {
|
||||
const organizationId = this.requireOrganization(actor);
|
||||
|
||||
const rows = await this.dataSource.query<Record<string, unknown>[]>(
|
||||
`SELECT a.code AS "accountCode",
|
||||
a.name AS "accountName",
|
||||
a.account_type AS "accountType",
|
||||
a.is_contra AS "isContra",
|
||||
ROUND(COALESCE(SUM(
|
||||
CASE WHEN a.normal_balance = 'DEBIT'
|
||||
THEN l.debit - l.credit
|
||||
ELSE l.credit - l.debit END), 0), 2) AS balance
|
||||
FROM finance.accounts a
|
||||
JOIN finance.journal_lines l ON l.account_id = a.id
|
||||
JOIN finance.journal_entries e ON e.id = l.journal_entry_id
|
||||
WHERE ${POSTED}
|
||||
AND e.entry_date <= $2::date
|
||||
AND a.account_type IN ('ASSET','LIABILITY','EQUITY')
|
||||
AND a.deleted_at IS NULL
|
||||
GROUP BY a.id, a.code, a.name, a.account_type, a.is_contra
|
||||
HAVING COALESCE(SUM(l.debit), 0) <> 0 OR COALESCE(SUM(l.credit), 0) <> 0
|
||||
ORDER BY a.code ASC`,
|
||||
[organizationId, asOf],
|
||||
);
|
||||
|
||||
const signed = rows.map((row) => ({
|
||||
accountCode: String(row.accountCode),
|
||||
accountName: row.accountName as { am: string; en: string },
|
||||
accountType: String(row.accountType),
|
||||
isContra: Boolean(row.isContra),
|
||||
balance: num(row.balance),
|
||||
}));
|
||||
|
||||
const assets = signed.filter((r) => r.accountType === "ASSET");
|
||||
const liabilities = signed.filter((r) => r.accountType === "LIABILITY");
|
||||
const equity = signed.filter((r) => r.accountType === "EQUITY");
|
||||
|
||||
const totalAssets = roundMoney(assets.reduce((s, r) => s + r.balance, 0));
|
||||
const totalLiabilities = roundMoney(
|
||||
liabilities.reduce((s, r) => s + r.balance, 0),
|
||||
);
|
||||
const totalEquity = roundMoney(equity.reduce((s, r) => s + r.balance, 0));
|
||||
|
||||
// Revenue less expenses to date is part of equity but has not been closed
|
||||
// into it. Omitting it is why a balance sheet "does not balance".
|
||||
const [result] = await this.dataSource.query<Record<string, unknown>[]>(
|
||||
// Revenue counts positively, expenses negatively. No contra flip, for the
|
||||
// same reason as above — the natural side of the account already carries
|
||||
// the sign.
|
||||
`SELECT ROUND(COALESCE(SUM(
|
||||
CASE WHEN a.account_type = 'REVENUE'
|
||||
THEN l.credit - l.debit
|
||||
ELSE -(l.debit - l.credit) END), 0), 2) AS "netResult"
|
||||
FROM finance.accounts a
|
||||
JOIN finance.journal_lines l ON l.account_id = a.id
|
||||
JOIN finance.journal_entries e ON e.id = l.journal_entry_id
|
||||
WHERE ${POSTED}
|
||||
AND e.entry_date <= $2::date
|
||||
AND a.account_type IN ('REVENUE','EXPENSE')
|
||||
AND a.deleted_at IS NULL`,
|
||||
[organizationId, asOf],
|
||||
);
|
||||
const retainedResult = num(result?.netResult);
|
||||
const equityWithResult = roundMoney(totalEquity + retainedResult);
|
||||
const difference = roundMoney(
|
||||
totalAssets - (totalLiabilities + equityWithResult),
|
||||
);
|
||||
|
||||
return {
|
||||
asOf,
|
||||
currency: LEDGER_CURRENCY,
|
||||
assets,
|
||||
liabilities,
|
||||
equity,
|
||||
totalAssets,
|
||||
totalLiabilities,
|
||||
totalEquity,
|
||||
/** Revenue less expenses to date — part of equity, not yet closed into it. */
|
||||
retainedResult,
|
||||
equityWithResult,
|
||||
balanced: Math.abs(difference) < 0.005,
|
||||
difference,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Cash movement over a range, by cash/bank account.
|
||||
*
|
||||
* A direct cash view rather than an indirect cash-flow statement: the
|
||||
* indirect method needs opening/closing working-capital positions that only
|
||||
* mean something once a full year has been posted, and presenting a
|
||||
* half-derived one would be worse than presenting the movements plainly.
|
||||
*/
|
||||
async cashMovement(actor: ActorContext, dateFrom: string, dateTo: string) {
|
||||
const organizationId = this.requireOrganization(actor);
|
||||
|
||||
const rows = await this.dataSource.query<Record<string, unknown>[]>(
|
||||
`SELECT a.code AS "accountCode",
|
||||
a.name AS "accountName",
|
||||
ROUND(COALESCE(SUM(
|
||||
CASE WHEN e.entry_date < $2::date THEN l.debit - l.credit ELSE 0 END), 0), 2) AS "opening",
|
||||
ROUND(COALESCE(SUM(
|
||||
CASE WHEN e.entry_date BETWEEN $2::date AND $3::date THEN l.debit ELSE 0 END), 0), 2) AS "cashIn",
|
||||
ROUND(COALESCE(SUM(
|
||||
CASE WHEN e.entry_date BETWEEN $2::date AND $3::date THEN l.credit ELSE 0 END), 0), 2) AS "cashOut",
|
||||
ROUND(COALESCE(SUM(
|
||||
CASE WHEN e.entry_date <= $3::date THEN l.debit - l.credit ELSE 0 END), 0), 2) AS "closing"
|
||||
FROM finance.accounts a
|
||||
JOIN finance.journal_lines l ON l.account_id = a.id
|
||||
JOIN finance.journal_entries e ON e.id = l.journal_entry_id
|
||||
WHERE ${POSTED}
|
||||
AND a.account_type = 'ASSET'
|
||||
AND a.code LIKE '111%'
|
||||
AND a.deleted_at IS NULL
|
||||
GROUP BY a.id, a.code, a.name
|
||||
ORDER BY a.code ASC`,
|
||||
[organizationId, dateFrom, dateTo],
|
||||
);
|
||||
|
||||
const accounts = rows.map((row) => ({
|
||||
accountCode: String(row.accountCode),
|
||||
accountName: row.accountName as { am: string; en: string },
|
||||
opening: num(row.opening),
|
||||
cashIn: num(row.cashIn),
|
||||
cashOut: num(row.cashOut),
|
||||
closing: num(row.closing),
|
||||
}));
|
||||
|
||||
return {
|
||||
dateFrom,
|
||||
dateTo,
|
||||
currency: LEDGER_CURRENCY,
|
||||
accounts,
|
||||
totalOpening: roundMoney(accounts.reduce((s, a) => s + a.opening, 0)),
|
||||
totalIn: roundMoney(accounts.reduce((s, a) => s + a.cashIn, 0)),
|
||||
totalOut: roundMoney(accounts.reduce((s, a) => s + a.cashOut, 0)),
|
||||
totalClosing: roundMoney(accounts.reduce((s, a) => s + a.closing, 0)),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* The general ledger for one account — every line, with a running balance.
|
||||
*
|
||||
* The running balance is computed in SQL with a window function rather than
|
||||
* in JavaScript, so a paged view still shows the correct balance at each row
|
||||
* instead of one that restarts at the top of every page.
|
||||
*/
|
||||
async generalLedger(
|
||||
actor: ActorContext,
|
||||
accountId: string,
|
||||
dateFrom: string,
|
||||
dateTo: string,
|
||||
) {
|
||||
const organizationId = this.requireOrganization(actor);
|
||||
|
||||
const [opening] = await this.dataSource.query<Record<string, unknown>[]>(
|
||||
`SELECT ROUND(COALESCE(SUM(
|
||||
CASE WHEN a.normal_balance = 'DEBIT'
|
||||
THEN l.debit - l.credit
|
||||
ELSE l.credit - l.debit END), 0), 2) AS "openingBalance"
|
||||
FROM finance.journal_lines l
|
||||
JOIN finance.journal_entries e ON e.id = l.journal_entry_id
|
||||
JOIN finance.accounts a ON a.id = l.account_id
|
||||
WHERE ${POSTED} AND l.account_id = $2 AND e.entry_date < $3::date`,
|
||||
[organizationId, accountId, dateFrom],
|
||||
);
|
||||
|
||||
const lines = await this.dataSource.query<Record<string, unknown>[]>(
|
||||
`SELECT e.entry_date::text AS "entryDate",
|
||||
e.entry_number AS "entryNumber",
|
||||
e.memo,
|
||||
e.journal_type AS "journalType",
|
||||
l.description,
|
||||
l.debit,
|
||||
l.credit,
|
||||
cc.code AS "costCenterCode",
|
||||
SUM(CASE WHEN a.normal_balance = 'DEBIT'
|
||||
THEN l.debit - l.credit
|
||||
ELSE l.credit - l.debit END)
|
||||
OVER (ORDER BY e.entry_date, e.entry_number, l.line_number
|
||||
ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) AS "movementToDate"
|
||||
FROM finance.journal_lines l
|
||||
JOIN finance.journal_entries e ON e.id = l.journal_entry_id
|
||||
JOIN finance.accounts a ON a.id = l.account_id
|
||||
LEFT JOIN finance.cost_centers cc ON cc.id = l.cost_center_id
|
||||
WHERE ${POSTED}
|
||||
AND l.account_id = $2
|
||||
AND e.entry_date >= $3::date
|
||||
AND e.entry_date <= $4::date
|
||||
ORDER BY e.entry_date ASC, e.entry_number ASC, l.line_number ASC`,
|
||||
[organizationId, accountId, dateFrom, dateTo],
|
||||
);
|
||||
|
||||
const openingBalance = num(opening?.openingBalance);
|
||||
return {
|
||||
openingBalance,
|
||||
lines: lines.map((row) => ({
|
||||
entryDate: String(row.entryDate),
|
||||
entryNumber: String(row.entryNumber),
|
||||
memo: String(row.memo ?? ""),
|
||||
journalType: String(row.journalType),
|
||||
description: row.description ? String(row.description) : null,
|
||||
costCenterCode: row.costCenterCode ? String(row.costCenterCode) : null,
|
||||
debit: num(row.debit),
|
||||
credit: num(row.credit),
|
||||
balance: roundMoney(openingBalance + num(row.movementToDate)),
|
||||
})),
|
||||
closingBalance: roundMoney(
|
||||
openingBalance + num(lines[lines.length - 1]?.movementToDate),
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Revenue by mapped category — what the revenue mappings are for.
|
||||
*
|
||||
* Grouped on the mapping's `revenue_category` rather than the account, so
|
||||
* several accounts rolling up to one commercial category report as one line.
|
||||
*/
|
||||
async revenueByCategory(actor: ActorContext, dateFrom: string, dateTo: string) {
|
||||
const organizationId = this.requireOrganization(actor);
|
||||
|
||||
const rows = await this.dataSource.query<Record<string, unknown>[]>(
|
||||
`SELECT COALESCE(m.revenue_category, 'UNMAPPED') AS category,
|
||||
a.code AS "accountCode",
|
||||
a.name AS "accountName",
|
||||
ROUND(COALESCE(SUM(l.credit - l.debit), 0), 2) AS amount
|
||||
FROM finance.accounts a
|
||||
JOIN finance.journal_lines l ON l.account_id = a.id
|
||||
JOIN finance.journal_entries e ON e.id = l.journal_entry_id
|
||||
LEFT JOIN LATERAL (
|
||||
SELECT rm.revenue_category
|
||||
FROM finance.revenue_mappings rm
|
||||
WHERE rm.account_id = a.id
|
||||
AND rm.organization_id = $1
|
||||
AND rm.deleted_at IS NULL
|
||||
LIMIT 1
|
||||
) m ON TRUE
|
||||
WHERE ${POSTED}
|
||||
AND e.entry_date >= $2::date
|
||||
AND e.entry_date <= $3::date
|
||||
AND a.account_type = 'REVENUE'
|
||||
AND a.deleted_at IS NULL
|
||||
GROUP BY m.revenue_category, a.id, a.code, a.name
|
||||
HAVING COALESCE(SUM(l.credit - l.debit), 0) <> 0
|
||||
ORDER BY 1 ASC, 2 ASC`,
|
||||
[organizationId, dateFrom, dateTo],
|
||||
);
|
||||
|
||||
return rows.map((row) => ({
|
||||
category: String(row.category),
|
||||
accountCode: String(row.accountCode),
|
||||
accountName: row.accountName as { am: string; en: string },
|
||||
amount: num(row.amount),
|
||||
}));
|
||||
}
|
||||
|
||||
private requireOrganization(actor: ActorContext): string {
|
||||
if (!actor.organizationId) {
|
||||
throw new BadRequestException(
|
||||
"This account has no organization context, so it cannot read finance reports",
|
||||
);
|
||||
}
|
||||
return actor.organizationId;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user