shutro-erp 0.3.5 → 0.3.7

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/i18n/bn.d.ts

@@ -0,0 +1,2 @@
+/** Bangla for the module's labels, keyed by their English text (RFC 0023 §3.1; `pnpm i18n:extract`). */
+export declare const bn: Readonly<Record<string, string>>;

package/dist/account_budget/i18n/bn.js

@@ -0,0 +1,63 @@
+/** Bangla for the module's labels, keyed by their English text (RFC 0023 §3.1; `pnpm i18n:extract`). */
+export const bn = {
+    '{{name}}: {{dateFrom}} to {{dateTo}}': '{{name}}: {{dateFrom}} থেকে {{dateTo}}',
+    'A budget ends on or after it starts.': 'বাজেট শুরুর দিন বা তার পরে শেষ হয়।',
+    'A planned amount is not negative.': 'পরিকল্পিত অঙ্ক ঋণাত্মক হতে পারে না।',
+    Account: 'হিসাব',
+    Actual: 'প্রকৃত',
+    'Actual and committed against the planned amount.': 'পরিকল্পিত অঙ্কের বিপরীতে প্রকৃত ও প্রতিশ্রুত।',
+    Approve: 'অনুমোদন করুন',
+    Approved: 'অনুমোদিত',
+    'Approved budgets are compared with the books and checked when purchase orders are submitted.': 'অনুমোদিত বাজেট হিসাবের খাতার সাথে তুলনা করা হয় এবং ক্রয় আদেশ জমা দেওয়ার সময় যাচাই করা হয়।',
+    'Approved budgets are compared with the books every hour and checked when purchase orders are submitted.': 'অনুমোদিত বাজেট প্রতি ঘণ্টায় হিসাবের খাতার সাথে তুলনা করা হয় এবং ক্রয় আদেশ জমা দেওয়ার সময় যাচাই করা হয়।',
+    'Back to draft': 'খসড়ায় ফেরত নিন',
+    'Beyond a budget': 'বাজেটের বাইরে',
+    'Beyond the budget': 'বাজেটের বাইরে',
+    Block: 'আটকে দিন',
+    Budget: 'বাজেট',
+    'Budget against actuals': 'বাজেট বনাম প্রকৃত',
+    'Budget approved': 'বাজেট অনুমোদিত',
+    'Budget check': 'বাজেট যাচাই',
+    'Budget line': 'বাজেটের লাইন',
+    'Budget lines': 'বাজেটের লাইন',
+    Budgets: 'বাজেট',
+    'Budgets (with their lines)': 'বাজেট (লাইনসহ)',
+    'Check budget': 'বাজেট যাচাই করুন',
+    Close: 'বন্ধ করুন',
+    Closed: 'বন্ধ',
+    Committed: 'প্রতিশ্রুত',
+    Company: 'প্রতিষ্ঠান',
+    'Confirmed purchase orders of the period not billed yet (untaxed).': 'এই সময়ের নিশ্চিত ক্রয় আদেশ, যার এখনো বিল হয়নি (করবিহীন)।',
+    Control: 'নিয়ন্ত্রণ',
+    'Cost centre': 'খরচ কেন্দ্র',
+    'Created At': 'তৈরির সময়',
+    'Created By': 'তৈরি করেছেন',
+    'Display Name': 'প্রদর্শিত নাম',
+    Draft: 'খসড়া',
+    'Empty: every cost centre.': 'ফাঁকা থাকলে: সব খরচ কেন্দ্র।',
+    'Empty: every expense account. Purchase orders commit against lines without an account or on the purchases account.': 'ফাঁকা থাকলে: সব খরচের হিসাব। ক্রয় আদেশ হিসাববিহীন লাইন বা ক্রয়ের হিসাবের লাইনের বিপরীতে প্রতিশ্রুত হয়।',
+    From: 'থেকে',
+    ID: 'আইডি',
+    Left: 'অবশিষ্ট',
+    Lines: 'লাইন',
+    Name: 'নাম',
+    Overspent: 'অতিরিক্ত খরচ',
+    'Page {{page}} of {{pages}}': 'পৃষ্ঠা {{page}} / {{pages}}',
+    Planned: 'পরিকল্পিত',
+    'Planned in all': 'মোট পরিকল্পিত',
+    'Planned less actual and committed.': 'পরিকল্পিত থেকে প্রকৃত ও প্রতিশ্রুত বাদে।',
+    'Posted in the period.': 'এই সময়ে পোস্টকৃত।',
+    'Purchases beyond a budget': 'বাজেটের বাইরে ক্রয়',
+    'Report only': 'শুধু প্রতিবেদন',
+    'Set when the order is submitted: an Accounting manager approves it as well.': 'আদেশ জমা দেওয়ার সময় নির্ধারিত হয়: একজন হিসাব ব্যবস্থাপককেও এটি অনুমোদন করতে হয়।',
+    State: 'অবস্থা',
+    'The lines’ planned amounts together.': 'লাইনগুলোর পরিকল্পিত অঙ্কের যোগফল।',
+    To: 'পর্যন্ত',
+    'Updated At': 'হালনাগাদের সময়',
+    'Updated By': 'হালনাগাদ করেছেন',
+    'Used (%)': 'ব্যবহৃত (%)',
+    'Used %': 'ব্যবহৃত %',
+    'Warn: a further approval': 'সতর্কতা: অতিরিক্ত অনুমোদন',
+    'What a purchase order that would go beyond what is left does: needs an Accounting manager’s approval, or is refused.': 'অবশিষ্ট অঙ্কের বাইরে যাওয়া ক্রয় আদেশের কী হবে: হিসাব ব্যবস্থাপকের অনুমোদন লাগবে, নয়তো নামঞ্জুর হবে।',
+    'What for': 'কী উদ্দেশ্যে',
+};

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,237 @@
+/**
+ * @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],
+    // Bangla for the labels it serves (RFC 0023 §3.1; `pnpm i18n:extract`).
+    i18n: { bn: () => import('./i18n/bn.js') },
+    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: [
+                {
+                    insertAfter: 'submit',
+                    nodes: [
+                        {
+                            kind: 'button',
+                            id: 'budget',
+                            transition: 'budget',
+                            label: 'Check budget',
+                            visibleWhen: { state: { in: ['draft', 'sent'] } },
+                        },
+                    ],
+                },
+                {
+                    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'],
+        }),
+    },
+});