shutro-erp 0.3.5 → 0.3.6

package/dist/account_budget/budget.d.ts

@@ -0,0 +1,5 @@
+import type { Env } from './.kosh/bindings.js';
+/** Refreshes the actual and committed amounts of the approved budgets' lines (those of `budgets`, or all). */
+export declare function refreshBudgets(env: Env, budgets?: readonly number[]): Promise<number>;
+/** The submitted orders against the approved budget lines of their dates: refused beyond a block, marked beyond a warn. */
+export declare function checkOrders(env: Env, ids: readonly number[]): Promise<void>;

package/dist/account_budget/budget.js

@@ -0,0 +1,142 @@
+/**
+ * Budgets against the books (RFC 0024 §2.5): each approved line's **actual** — the posted journal lines of the
+ * budget's period on its account (every expense account when none) and cost centre (every one when none), debit
+ * less credit — and **committed** — the untaxed lines of confirmed purchase orders of the period with its cost centre
+ * that are not billed yet (lines without an account, or on the purchases journal's account). A purchase order
+ * submitted is checked against the lines it touches: beyond a **block** line it is refused with the shortfall; beyond
+ * a **warn** line it is marked `overBudget`, which brings an Accounting manager's approval.
+ */
+import { orm } from '../server/orm.js';
+const ZERO = orm.toDecimal(0);
+const EXPENSES = ['expense', 'expense_direct_cost', 'expense_depreciation'];
+/** A date-only value as `YYYY-MM-DD` (PostgreSQL dates read as local midnights). */
+function isoDate(v) {
+    if (!(v instanceof Date))
+        return String(v ?? '').slice(0, 10);
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${v.getFullYear()}-${pad(v.getMonth() + 1)}-${pad(v.getDate())}`;
+}
+/** Whether purchase orders commit against a line: no account, or the company's purchases account. */
+async function commitsOn(env, line) {
+    if (line.account === null)
+        return true;
+    const [journal] = await (await env
+        .model('account.journal')
+        .search({ where: { company: line.company, type: 'purchase' }, limit: 1 })).load({});
+    return journal?.defaultAccount?.id === line.account;
+}
+async function actualOf(env, line) {
+    const found = await env.model('account.move.line').search({
+        where: {
+            posted: true,
+            'move.company': line.company,
+            date: { gte: line.from, lte: line.to },
+            ...(line.account === null
+                ? { accountType: { in: EXPENSES } }
+                : { account: line.account }),
+            ...(line.analytic === null ? {} : { analytic: line.analytic }),
+        },
+    });
+    return [...(await found.load(['debit', 'credit']))].reduce((s, l) => s.plus(l.debit.amount).minus(l.credit.amount), ZERO);
+}
+/** Untaxed amounts of purchase order lines of the line's scope; `orders` limits it (confirmed, not billed, by default). */
+async function purchasesOf(env, line, orders) {
+    if (!(await commitsOn(env, line)))
+        return ZERO;
+    const where = orders === undefined
+        ? {
+            'order.state': { in: ['purchase', 'done'] },
+            'order.billState': { ne: 'billed' },
+            'order.company': line.company,
+            'order.dateOrder': { gte: line.from, lte: line.to },
+        }
+        : { order: { in: orders } };
+    const found = await env.model('purchase.order.line').search({
+        where: { ...where, ...(line.analytic === null ? {} : { analytic: line.analytic }) },
+    });
+    return [...(await found.load(['subtotal']))].reduce((s, l) => s.plus(l.subtotal?.amount ?? ZERO), ZERO);
+}
+/** Refreshes the actual and committed amounts of the approved budgets' lines (those of `budgets`, or all). */
+export async function refreshBudgets(env, budgets) {
+    const found = await env.model('account.budget').search({
+        where: {
+            state: 'approved',
+            ...(budgets === undefined ? {} : { id: { in: budgets } }),
+        },
+    });
+    let count = 0;
+    for (const b of await found.load({ lines: true, company: true })) {
+        for (const l of b.lines) {
+            const scope = {
+                from: isoDate(b.dateFrom),
+                to: isoDate(b.dateTo),
+                analytic: l.analytic?.id ?? null,
+                account: l.account?.id ?? null,
+                company: b.company.id,
+            };
+            await env
+                .model('account.budget.line')
+                .browse([l.id])
+                .write({
+                actual: (await actualOf(env, scope)).toString(),
+                committed: (await purchasesOf(env, scope)).toString(),
+            });
+            count += 1;
+        }
+    }
+    await env.flush();
+    return count;
+}
+/** The submitted orders against the approved budget lines of their dates: refused beyond a block, marked beyond a warn. */
+export async function checkOrders(env, ids) {
+    for (const o of await env
+        .model('purchase.order')
+        .browse(ids)
+        .load({ company: true })) {
+        const date = isoDate(o.dateOrder);
+        const budgets = await (await env.model('account.budget').search({
+            where: {
+                state: 'approved',
+                company: o.company.id,
+                dateFrom: { lte: date },
+                dateTo: { gte: date },
+            },
+        })).load({ lines: true });
+        const notes = [];
+        let over = false;
+        for (const b of budgets)
+            for (const l of b.lines) {
+                if (l.control === 'none')
+                    continue;
+                const scope = {
+                    from: isoDate(b.dateFrom),
+                    to: isoDate(b.dateTo),
+                    analytic: l.analytic?.id ?? null,
+                    account: l.account?.id ?? null,
+                    company: o.company.id,
+                };
+                const thisOrder = await purchasesOf(env, scope, [o.id]);
+                if (thisOrder.isZero())
+                    continue;
+                const left = l.planned
+                    .minus(await actualOf(env, scope))
+                    .minus(await purchasesOf(env, scope));
+                const short = thisOrder.minus(left);
+                if (short.lte(0))
+                    continue;
+                const what = `${b.name} › ${l.name}: ${left.toFixed(2)} left, this order ${thisOrder.toFixed(2)} (${short.toFixed(2)} beyond)`;
+                if (l.control === 'block')
+                    throw new orm.ValidationError('purchase.order', ['lines'], `Beyond the budget — ${what}.`, 'Lower the order, choose another cost centre, or ask an Accounting manager to raise the budget.');
+                over = true;
+                notes.push(what);
+            }
+        await env
+            .model('purchase.order')
+            .browse([o.id])
+            .write({
+            overBudget: over,
+            budgetNote: notes.length === 0 ? null : notes.join('\n'),
+        });
+    }
+    await env.flush();
+}

package/dist/account_budget/demo.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Budgets' demo data (RFC 0008 §5.8): two cost centres and this year's budget — the operations team's purchases (a
+ * warning beyond them), office expenses (report only) — approved, with its figures from the books.
+ */
+import type { DemoContext } from '../modules-sdk/index.js';
+export declare function budgetDemo(ctx: DemoContext): Promise<string>;

package/dist/account_budget/demo.js

@@ -0,0 +1,30 @@
+const DINA = { login: 'dina', name: 'Dina Rahman', groups: ['account.manager'] };
+export async function budgetDemo(ctx) {
+    return ctx.as(DINA, async (raw) => {
+        const env = raw;
+        const office = (await env.model('account.account').search({ where: { code: '6300' }, limit: 1 })).ids[0];
+        if (office === undefined)
+            return 'Budgets: no chart of accounts, nothing made.';
+        const centre = async (code, name) => (await env.model('account.analytic').search({ where: { code }, limit: 1 })).ids[0] ??
+            (await env.model('account.analytic').create([{ code, name }])).ids[0];
+        const ops = await centre('OPS', 'Operations');
+        await centre('SALES', 'Sales team');
+        const year = ctx.date(0).slice(0, 4);
+        const made = await env.model('account.budget').create([
+            {
+                name: `Budget ${year}`,
+                dateFrom: `${year}-01-01`,
+                dateTo: `${year}-12-31`,
+                lines: {
+                    create: [
+                        { name: 'Operations purchases', analytic: ops, planned: '1500000', control: 'warn' },
+                        { name: 'Office expenses', account: office, planned: '300000', control: 'none' },
+                    ],
+                },
+            },
+        ]);
+        await env.flush();
+        await env.model('account.budget').browse(made.ids).approve();
+        return `Budgets: the ${year} budget with two lines, approved.`;
+    });
+}

package/dist/account_budget/index.d.ts

@@ -0,0 +1,4 @@
+import { defineModule } from '../modules-sdk/index.js';
+export { checkOrders, refreshBudgets } from './budget.js';
+export { accountBudgetShutro, Budget, BudgetLine, PurchaseBudget } from './module.js';
+export declare const accountBudget: ReturnType<typeof defineModule>;

package/dist/account_budget/index.js

@@ -0,0 +1,223 @@
+/**
+ * @packageDocumentation
+ * `shutro-erp/account_budget` (RFC 0024 §2.5): **Budgets** in Accounting. A budget for a period with lines by cost centre
+ * and / or account; each line's actual (posted) and committed amount (confirmed purchase orders not billed), what is
+ * left and how much is used; and a control on purchase orders — beyond a **warn** line an order needs an Accounting
+ * manager's approval as well, beyond a **block** line it is refused with the shortfall.
+ *
+ * - `POST /api/v1/budgets/refresh`   `{ budgets? }`: the actual and committed amounts, now (daily on the server)
+ */
+import { accounting } from '../accounting/index.js';
+import { defineModule } from '../modules-sdk/index.js';
+import { purchaseAccount } from '../purchase_account/index.js';
+import { HttpProblem } from '../server/index.js';
+import { action, field, form, list, pivot, search } from '../views/index.js';
+import { refreshBudgets } from './budget.js';
+import { budgetDemo } from './demo.js';
+import { accountBudgetShutro, Budget, BudgetLine } from './module.js';
+export { checkOrders, refreshBudgets } from './budget.js';
+export { accountBudgetShutro, Budget, BudgetLine, PurchaseBudget } from './module.js';
+function registerBudgetRoutes(context) {
+    const { app } = context;
+    app.post('/api/v1/budgets/refresh', async (request) => {
+        const given = request.body?.['budgets'];
+        const budgets = Array.isArray(given) ? given.map(Number) : undefined;
+        return request.env(async (raw) => {
+            const env = raw;
+            if (!env.administrator && !env.groups.has('account.user'))
+                throw new HttpProblem(403, 'access', 'Accountants', 'This needs the Accountant role.');
+            return env.asSuperuser({ reason: 'budget figures' }, async (su) => ({
+                lines: await refreshBudgets(su, budgets),
+            }));
+        }, { write: true });
+    });
+    if (process.env['KOSH_SCHEDULES'] === 'off')
+        return;
+    const run = async () => {
+        try {
+            const companies = await context.shutro.bootstrap({ reason: 'budget figures' }, async (env) => (await env.model('res.company').search({})).ids);
+            for (const company of companies)
+                await context.shutro.bootstrap({ reason: 'budget figures', company }, (env) => env.asSuperuser({ reason: 'budget figures' }, (su) => refreshBudgets(su)));
+        }
+        catch (error) {
+            app.log.error({ err: error }, 'budget figures');
+        }
+    };
+    const timer = setInterval(() => void run(), 3_600_000);
+    timer.unref();
+    app.addHook('onClose', async () => clearInterval(timer));
+}
+export const accountBudget = defineModule({
+    shutro: accountBudgetShutro,
+    kosh: '^0.1.0',
+    hooks: { demo: budgetDemo },
+    depends: [accounting, purchaseAccount],
+    accessLevels: { user: { label: 'Budgets', groups: ['account_budget.user'] } },
+    routes: (context) => registerBudgetRoutes(context),
+    // Beyond a budget's warn line, a purchase order needs an Accounting manager as well (RFC 0003 approvals).
+    approvals: [
+        {
+            name: 'Purchases beyond a budget',
+            model: 'purchase.order',
+            onApproved: 'confirm',
+            onRejected: 'reject',
+            levels: [
+                {
+                    name: 'Beyond the budget',
+                    condition: { overBudget: true },
+                    approverRole: 'account.manager',
+                },
+            ],
+        },
+    ],
+    events: [{ topic: 'account.budget.approved', model: 'account.budget', label: 'Budget approved' }],
+    documents: [
+        {
+            key: 'budget_report',
+            name: 'Budget against actuals',
+            model: 'account.budget',
+            layout: {
+                paper: 'A4',
+                orientation: 'landscape',
+                header: '{{company.name}} — {{name}}',
+                footer: 'Page {{page}} of {{pages}}',
+                blocks: [
+                    { kind: 'heading', id: 'title', text: '{{name}}: {{dateFrom}} to {{dateTo}}', level: 1 },
+                    {
+                        kind: 'table',
+                        id: 'lines',
+                        bind: 'lines',
+                        columns: [
+                            { label: 'What for', bind: 'name' },
+                            { label: 'Cost centre', bind: 'analytic.name' },
+                            { label: 'Account', bind: 'account.displayName' },
+                            { label: 'Planned', bind: 'planned' },
+                            { label: 'Actual', bind: 'actual' },
+                            { label: 'Committed', bind: 'committed' },
+                            { label: 'Left', bind: 'available' },
+                            { label: 'Used %', bind: 'used' },
+                        ],
+                    },
+                    { kind: 'fields', id: 'totals', items: [{ label: 'Planned in all', bind: 'planned' }] },
+                ],
+            },
+        },
+    ],
+    importTemplates: [
+        {
+            key: 'budgets',
+            model: 'account.budget',
+            label: 'Budgets (with their lines)',
+            columns: [
+                { header: 'Budget', field: 'name' },
+                { header: 'From', field: 'dateFrom' },
+                { header: 'To', field: 'dateTo' },
+                { header: 'What for', field: 'lines.name' },
+                { header: 'Cost centre', field: 'lines.analytic' },
+                { header: 'Account', field: 'lines.account' },
+                { header: 'Planned', field: 'lines.planned' },
+                { header: 'Control', field: 'lines.control' },
+            ],
+        },
+    ],
+    actions: {
+        'accounting.action_budgets': action(Budget, { label: 'Budgets', views: ['list', 'form'] }),
+        'accounting.action_budget_lines': action(BudgetLine, {
+            label: 'Budget lines',
+            views: ['list', 'pivot'],
+        }),
+    },
+    menus: [
+        {
+            id: 'accounting.budgets',
+            parent: 'accounting.root',
+            label: 'Budgets',
+            action: 'accounting.action_budgets',
+            sequence: 7,
+        },
+        {
+            id: 'accounting.budget_lines',
+            parent: 'accounting.reporting',
+            label: 'Budget against actuals',
+            action: 'accounting.action_budget_lines',
+            sequence: 9,
+        },
+    ],
+    views: {
+        'account.budget.list': list(Budget, {
+            columns: ['name', 'dateFrom', 'dateTo', 'planned', 'state'],
+        }),
+        'account.budget.form': form(Budget, (k) => ({
+            header: {
+                statusbar: 'state',
+                buttons: [
+                    k.button('approve', { primary: true, label: 'Approve' }),
+                    k.button('close', { label: 'Close' }),
+                    k.button('redraft', { label: 'Back to draft' }),
+                ],
+            },
+            sheet: [
+                k.group('main', ['name', 'dateFrom', 'dateTo', 'planned'], {
+                    description: 'Approved budgets are compared with the books every hour and checked when purchase orders are submitted.',
+                }),
+                k.lines('lines', [
+                    { field: 'name', id: 'line_name' },
+                    'analytic',
+                    'account',
+                    { field: 'planned', id: 'line_planned' },
+                    'control',
+                    'actual',
+                    'committed',
+                    'available',
+                    { field: 'used', id: 'line_used', widget: 'progress' },
+                ]),
+            ],
+            chatter: true,
+        })),
+        'account.budget.line.list': list(BudgetLine, {
+            columns: [
+                'budget',
+                'name',
+                'analytic',
+                'account',
+                'planned',
+                'actual',
+                'committed',
+                'available',
+                { field: 'used', widget: 'progress' },
+            ],
+            decorations: { danger: { available: { lt: 0 } } },
+        }),
+        'account.budget.line.pivot': pivot(BudgetLine, {
+            rows: ['analytic'],
+            cols: ['budget'],
+            measures: [{ sum: 'planned' }, { sum: 'actual' }, { sum: 'committed' }, { sum: 'available' }],
+        }),
+    },
+    viewExtensions: [
+        {
+            view: 'purchase.order.form',
+            operations: [
+                {
+                    append: 'dates',
+                    nodes: [
+                        field({ field: 'overBudget', id: 'order_over_budget' }),
+                        field({ field: 'budgetNote', id: 'order_budget_note' }),
+                    ],
+                },
+            ],
+        },
+    ],
+    search: {
+        'account.budget': search(Budget, {
+            fields: ['name'],
+            filters: { approved: { label: 'Approved', domain: { state: 'approved' }, group: 'state' } },
+            groupBy: ['state'],
+        }),
+        'account.budget.line': search(BudgetLine, {
+            fields: ['name', 'analytic.name'],
+            filters: { over: { label: 'Overspent', domain: { available: { lt: 0 } }, group: 'state' } },
+            groupBy: ['budget', 'analytic', 'account', 'control'],
+        }),
+    },
+});