shutro-erp 0.3.5 → 0.3.7

package/dist/payroll_account/module.js

@@ -0,0 +1,256 @@
+/**
+ * Payroll in the books (RFC 0024 §2.3, `payroll_account`): each rule may name its account; an approved run is
+ * **booked** as one posted entry in the Payroll journal (`PAY`) — basic, allowances and company contributions to
+ * their expense accounts (Salaries, 6000, by default), deductions to their payables (Payroll deductions payable,
+ * 2191), contributions against Payroll contributions payable (2192), the net to Salaries payable (2190) — and its
+ * **payment** clears Salaries payable against the bank or cash journal chosen on the run. A correction books only
+ * its differences, line by line, against the payslips it corrects. Accounts and the journal are made when missing.
+ */
+import { accountingShutro } from '../accounting/index.js';
+import { payrollShutro } from '../payroll/index.js';
+import { orm } from '../server/orm.js';
+import { defineModule, extendModel, f } from './.kosh/bindings.js';
+const ZERO = orm.toDecimal(0);
+export const PAYROLL_ACCOUNTS = {
+    salaries: { code: '6000', name: 'Salaries', type: 'expense', reconcile: false },
+    payable: { code: '2190', name: 'Salaries payable', type: 'liability_current', reconcile: true },
+    deductions: {
+        code: '2191',
+        name: 'Payroll deductions payable',
+        type: 'liability_current',
+        reconcile: true,
+    },
+    contributions: {
+        code: '2192',
+        name: 'Payroll contributions payable',
+        type: 'liability_current',
+        reconcile: true,
+    },
+};
+/** The company's payroll accounts and the Payroll journal (`PAY`); `null` without a chart. */
+export async function payrollAccountsOf(env, company) {
+    const chart = await env.model('account.account').search({ where: { company }, limit: 1 });
+    if (chart.length === 0)
+        return null;
+    const out = {};
+    for (const [key, spec] of Object.entries(PAYROLL_ACCOUNTS))
+        out[key] =
+            (await env.model('account.account').search({ where: { company, code: spec.code }, limit: 1 }))
+                .ids[0] ??
+                (await env.model('account.account').create([{ ...spec, company }]))
+                    .ids[0];
+    out.journal = ((await env.model('account.journal').search({ where: { company, code: 'PAY' }, limit: 1 })).ids[0] ??
+        (await env
+            .model('account.journal')
+            .create([{ company, code: 'PAY', name: 'Payroll', type: 'general' }])).ids[0]);
+    return out;
+}
+async function post(env, company, journal, ref, lines) {
+    const kept = lines
+        .map((l) => {
+        // A negative amount on one side is a positive one on the other.
+        const net = l.debit.minus(l.credit);
+        return { ...l, debit: net.gt(0) ? net : ZERO, credit: net.lt(0) ? net.neg() : ZERO };
+    })
+        .filter((l) => !l.debit.isZero() || !l.credit.isZero());
+    if (kept.length === 0)
+        return null;
+    const [c] = await env.model('res.company').browse([company]).load({});
+    const made = await env.model('account.move').create([
+        {
+            kind: 'entry',
+            journal,
+            company,
+            currency: c?.currency.id,
+            date: env.today(),
+            ref,
+            lines: {
+                create: kept.map((l) => ({
+                    account: l.account,
+                    name: l.name,
+                    debit: l.debit.toDecimalPlaces(2).toString(),
+                    credit: l.credit.toDecimalPlaces(2).toString(),
+                })),
+            },
+        },
+    ]);
+    await env.withGrants({ grants: ['account.post'], reason: `payroll ${ref}` }, (e) => e.model('account.move').browse(made.ids).post());
+    return made.ids[0];
+}
+const noChart = () => new orm.ValidationError('payroll.run', ['state'], 'The company has no chart of accounts yet.', 'Install a chart in Accounting first.');
+/** Each payslip's line amounts by rule (a correction: less the corrected payslip's), with the rule's account. */
+async function amountsOf(env, runId) {
+    const [run] = await env
+        .model('payroll.run')
+        .browse([runId])
+        .load({ company: true, correctionOf: true });
+    if (run === undefined)
+        return null;
+    const linesOf = async (where) => [
+        ...(await (await env.model('payroll.slip.line').search({ where: where })).load({ rule: true, slip: true })),
+    ];
+    const current = await linesOf({ 'slip.run': run.id });
+    const before = run.correctionOf === null ? [] : await linesOf({ 'slip.run': run.correctionOf.id });
+    const key = (l) => `${l.slip.employee.id}:${l.code}`;
+    const out = new Map();
+    for (const l of current)
+        out.set(key(l), {
+            category: l.category,
+            name: l.name,
+            account: l.rule?.account?.id ?? null,
+            amount: (out.get(key(l))?.amount ?? ZERO).plus(l.amount),
+        });
+    for (const l of before) {
+        const slot = out.get(key(l)) ?? {
+            category: l.category,
+            name: l.name,
+            account: l.rule?.account?.id ?? null,
+            amount: ZERO,
+        };
+        slot.amount = slot.amount.minus(l.amount);
+        out.set(key(l), slot);
+    }
+    return { run, amounts: [...out.values()] };
+}
+export const RuleAccount = extendModel('payroll.rule', {
+    fields: {
+        account: f.many2one('account.account', {
+            ondelete: 'restrict',
+            label: 'Account',
+            help: 'Basic, allowances and contributions: the expense; deductions: the payable. Empty: Salaries (6000) or Payroll deductions payable (2191).',
+        }),
+    },
+});
+export const RunBooks = extendModel('payroll.run', {
+    fields: {
+        entry: f.many2one('account.move', { ondelete: 'restrict', label: 'Journal entry' }),
+        paymentJournal: f.many2one('account.journal', {
+            ondelete: 'restrict',
+            label: 'Paid from',
+            help: 'The bank or cash journal the net pay leaves from.',
+        }),
+        paymentEntry: f.many2one('account.move', { ondelete: 'restrict', label: 'Payment entry' }),
+    },
+    overrides: {
+        approvedOut: async function (next) {
+            await next();
+            const runs = this;
+            const env = runs.env;
+            await env.asSuperuser({ reason: 'book payroll' }, async (su) => {
+                for (const id of runs.ids) {
+                    const found = await amountsOf(su, id);
+                    if (found === null)
+                        continue;
+                    const accounts = await payrollAccountsOf(su, found.run.company.id);
+                    if (accounts === null)
+                        throw noChart();
+                    const lines = [];
+                    let net = ZERO;
+                    let contributions = ZERO;
+                    for (const a of found.amounts) {
+                        if (a.category === 'info' || a.amount.isZero())
+                            continue;
+                        if (a.category === 'deduction') {
+                            lines.push({
+                                account: a.account ?? accounts.deductions,
+                                debit: ZERO,
+                                credit: a.amount,
+                                name: a.name,
+                            });
+                            net = net.minus(a.amount);
+                        }
+                        else {
+                            lines.push({
+                                account: a.account ?? accounts.salaries,
+                                debit: a.amount,
+                                credit: ZERO,
+                                name: a.name,
+                            });
+                            if (a.category === 'contribution')
+                                contributions = contributions.plus(a.amount);
+                            else
+                                net = net.plus(a.amount);
+                        }
+                    }
+                    lines.push({
+                        account: accounts.contributions,
+                        debit: ZERO,
+                        credit: contributions,
+                        name: `${found.run.name} contributions`,
+                    });
+                    lines.push({
+                        account: accounts.payable,
+                        debit: ZERO,
+                        credit: net,
+                        name: `${found.run.name} net pay`,
+                    });
+                    // Same accounts and names summed: one line each.
+                    const merged = new Map();
+                    for (const l of lines) {
+                        const k = `${l.account}:${l.name}`;
+                        const m = merged.get(k);
+                        if (m === undefined)
+                            merged.set(k, { ...l });
+                        else {
+                            m.debit = m.debit.plus(l.debit);
+                            m.credit = m.credit.plus(l.credit);
+                        }
+                    }
+                    const entry = await post(su, found.run.company.id, accounts.journal, found.run.name, [
+                        ...merged.values(),
+                    ]);
+                    if (entry !== null)
+                        await su
+                            .model('payroll.run')
+                            .browse([found.run.id])
+                            .write({ entry });
+                }
+            });
+        },
+        paidOut: async function (next) {
+            await next();
+            const runs = this;
+            const env = runs.env;
+            await env.asSuperuser({ reason: 'pay payroll' }, async (su) => {
+                for (const run of await su
+                    .model('payroll.run')
+                    .browse(runs.ids)
+                    .load({ company: true, slips: true })) {
+                    const accounts = await payrollAccountsOf(su, run.company.id);
+                    if (accounts === null)
+                        throw noChart();
+                    if (run.paymentJournal === null)
+                        throw new orm.ValidationError('payroll.run', ['paymentJournal'], 'Choose the bank or cash journal the pay leaves from.', 'Set “Paid from” on the run, then mark it as paid.');
+                    const [j] = await su.model('account.journal').browse([run.paymentJournal.id]).load({});
+                    const money = j?.defaultAccount?.id;
+                    if (j === undefined || money === undefined || (j.type !== 'bank' && j.type !== 'cash'))
+                        throw new orm.ValidationError('payroll.run', ['paymentJournal'], 'Pay from a bank or cash journal with its account.', 'Choose a bank or cash journal.');
+                    const total = [...run.slips].reduce((s, x) => s.plus(run.kind === 'correction' ? (x.difference ?? ZERO) : x.net), ZERO);
+                    const entry = await post(su, run.company.id, run.paymentJournal.id, `${run.name} paid`, [
+                        { account: accounts.payable, debit: total, credit: ZERO, name: `${run.name} net pay` },
+                        { account: money, debit: ZERO, credit: total, name: `${run.name} net pay` },
+                    ]);
+                    if (entry !== null)
+                        await su
+                            .model('payroll.run')
+                            .browse([run.id])
+                            .write({ paymentEntry: entry });
+                }
+            });
+        },
+    },
+});
+export const payrollAccountShutro = defineModule({
+    name: 'payroll_account',
+    version: '0.1.0',
+    depends: [payrollShutro, accountingShutro],
+    groups: [
+        orm.defineGroup({
+            code: 'payroll_account.user',
+            label: 'Payroll in the books',
+            implies: ['payroll.user'],
+        }),
+    ],
+    models: [],
+    extensions: [RuleAccount, RunBooks],
+});

package/dist/permissions/approvals.d.ts

@@ -10,10 +10,14 @@
  * ```
  *
  * `requestApprovals` creates one request per policy level whose condition (a Shutro domain) matches the record.
- * Levels are decided in order (a level waits for the lower ones), by holders of the level's role in the record's
- * company; the requester never approves their own record (separation of duties, administrators included). The
- * last approval runs the policy's `onApproved` transition, a rejection its `onRejected` one, as the system
- * (attributed to the approver in the audit log). Every step is audited and emitted as an event for notifications.
+ * Levels are decided in order (a level waits for the lower ones; levels with the same sequence side by side), by
+ * the level's approvers in the record's company — a role's holders, named people, the requester's manager
+ * (Workforce; the level's role when there is none) or the person in a field of the record —, by any one of them,
+ * all of them or a number (RFC 0025): each decision is a vote. The requester never approves their own record
+ * (separation of duties, administrators included). The last approval runs the policy's `onApproved` transition, a
+ * rejection its `onRejected` one, sending back for changes its `onSentBack` one (a reason required unless the policy
+ * says otherwise), a withdrawal by the requester its `onWithdrawn` one — as the system, attributed in the audit log.
+ * A resubmission is the next round; earlier rounds stay as history. Every step is audited and emitted as an event.
  */
 import type { KoshModule } from '../modules-sdk/index.js';
 import type { Env } from '../server/orm.js';
@@ -27,30 +31,241 @@ export interface ApprovalRequestInfo {
     readonly targetId: number;
     readonly company: number | null;
     readonly approverRole: string;
-    readonly state: 'pending' | 'approved' | 'rejected' | 'cancelled';
+    /** The people who decide (empty: the role's holders). */
+    readonly approvers: readonly number[];
+    /** Backups who may decide it too. */
+    readonly backups: readonly number[];
+    /** How many approvals it needs, and how many it has. */
+    readonly required: number;
+    readonly approvals: number;
+    readonly round: number;
+    /** When it should be decided by, and the role it was escalated to once late. */
+    readonly dueAt: string | null;
+    readonly escalatedTo: string | null;
+    /** When its turn came (null: earlier levels still decide), and how its approvers were found. */
+    readonly startedAt: string | null;
+    readonly explanation: string | null;
+    readonly state: 'pending' | 'approved' | 'rejected' | 'sent_back' | 'cancelled';
     readonly requestedBy: number | null;
     readonly decidedBy: number | null;
     readonly decidedAt: string | null;
     readonly comment: string | null;
 }
 /**
- * Creates the approval requests of `records` (a recordset: `env`, `modelName`, `ids`) from the matching policies
- * and levels; earlier pending requests of the records are cancelled (a resubmission starts a new round). Returns
- * the number of requests created.
+ * Which of the last `limit` records of the policy's model each of its levels would have asked about (RFC 0025 step
+ * 4: the editor's preview), as the system; the policy's own condition first.
  */
+export declare function previewPolicy(su: Env, policyId: number, limit?: number): Promise<{
+    records: number;
+    levels: {
+        id: number;
+        name: string;
+        matched: number[];
+    }[];
+    covers: {
+        all: boolean;
+        companies: string[];
+    };
+}>;
+/** The matrix log of a record's requests, when `env` may read the record. */
+export declare function eventsOf(env: Env, model: string, id: number): Promise<{
+    id: number;
+    request: number;
+    at: string;
+    user: number | null;
+    kind: string;
+    note: string | null;
+}[]>;
 export declare function requestApprovals(records: unknown): Promise<number>;
 /** `none` (no level applied), `pending`, `approved` or `rejected`, for the record's current round. */
-export declare function approvalState(env: Env, model: string, id: number): Promise<'none' | 'pending' | 'approved' | 'rejected'>;
+export declare function approvalState(env: Env, model: string, id: number): Promise<'none' | 'pending' | 'approved' | 'rejected' | 'sent_back'>;
 /** Transition guard: the records whose approvals are pending or rejected (records no level applied to may go). */
 export declare function approvalGuard(records: unknown): Promise<number[]>;
+/** A user deciding: their groups, and who delegated their approvals to them today (with those people's roles). */
+export interface Who {
+    readonly uid: number;
+    readonly administrator: boolean;
+    readonly groups: ReadonlySet<string>;
+    readonly companyId: number | null;
+    readonly delegators: readonly {
+        readonly user: number;
+        readonly roles: readonly {
+            readonly group: string;
+            readonly company: number | null;
+        }[];
+    }[];
+}
+/** `env`'s user as a decider (RFC 0025 §3.3: delegations active today count). */
+export declare function whoIs(su: Env, env: Env): Promise<Who>;
+export type Decision = 'approve' | 'reject' | 'send_back';
+/**
+ * Decides a request as `env`'s user: approves (the request is approved once it has the approvals it needs), rejects
+ * or sends back for changes (with a reason, unless the policy says otherwise; the other open requests of the round are
+ * cancelled). @throws {HttpProblem} 404 unknown, 409 decided / not its turn / decided by them already, 403 not an
+ * approver, the requester, or another company, 422 a reason missing
+ */
+export declare function decide(env: Env, requestId: number, decision: Decision, comment?: string, from?: {
+    readonly ip?: string;
+}): Promise<ApprovalRequestInfo>;
+/**
+ * The requester withdraws the pending requests of their record's current round; the policy's `onWithdrawn`
+ * transition runs. @throws {HttpProblem} 404 when nothing is pending, 403 when they did not ask
+ */
+export declare function withdraw(env: Env, model: string, id: number): Promise<number>;
+/**
+ * Reassigns a pending request (RFC 0027 §2.6), for Approvals managers: its approvers replaced by `users`, or `users`
+ * added to them (a role's holders named first); never the requester; a reason required; logged, audited and
+ * announced (`approval.reassigned`, with the people added). @throws {HttpProblem} 403 / 404 / 409 / 422
+ */
+export declare function reassign(env: Env, requestId: number, users: readonly number[], mode: 'replace' | 'add', reason: string): Promise<ApprovalRequestInfo>;
+/**
+ * Tells a current request's backups that it waits (RFC 0027 §2.6): for Approvals managers and the request's
+ * approvers; logged and announced (`approval.backups`). @throws {HttpProblem} 403 / 404 / 409
+ */
+export declare function notifyBackups(env: Env, requestId: number): Promise<number>;
+/** The fields of a level that decide its approvers: a change to one is synced to its waiting requests. */
+export declare const APPROVER_KEYS: readonly string[];
+/**
+ * Keeps waiting requests in step with their levels (RFC 0027 §2.6), as the system: each pending request of these
+ * levels gets its approvers found again — added to the ones it has, or replacing them, as its policy says (`mode`
+ * overrides it, for "Sync now") — logged when they change. Returns what changed, with the people added to requests
+ * whose turn it is (to tell, when the policy says so).
+ */
+export declare function syncLevels(su: Env, levelIds: readonly number[], mode?: 'add' | 'replace'): Promise<{
+    request: ApprovalRequestInfo;
+    added: number[];
+    notify: boolean;
+}[]>;
+/** A request as the Approvals app shows it (RFC 0025 §3.1): the record, who asked, since when, every level. */
+export interface ApprovalCard {
+    readonly id: number;
+    readonly levelName: string;
+    readonly state: ApprovalRequestInfo['state'];
+    readonly round: number;
+    readonly approvals: number;
+    readonly required: number;
+    readonly waitingSince: string;
+    readonly decidedAt: string | null;
+    /** When it should be decided by, and the role it was escalated to once late. */
+    readonly dueAt: string | null;
+    readonly escalatedTo: string | null;
+    readonly comment: string | null;
+    readonly record: {
+        readonly model: string;
+        readonly id: number;
+        readonly name: string;
+        readonly label: string;
+    };
+    readonly requester: {
+        readonly id: number;
+        readonly name: string;
+    } | null;
+    readonly steps: readonly {
+        id: number;
+        levelName: string;
+        sequence: number;
+        state: ApprovalRequestInfo['state'];
+        approvals: number;
+        required: number;
+    }[];
+}
+/**
+ * The Approvals app's lists (RFC 0025 §3.1): `inbox` — what waits for the user's decision, oldest first —, `mine`
+ * — the records they asked approvals for, the latest round of each, where it stands —, `history` — what they decided,
+ * newest first.
+ */
+export declare function approvalCards(env: Env, list: 'inbox' | 'mine' | 'history'): Promise<ApprovalCard[]>;
+/** Approves many requests (each checked as one decision); the ones refused say why. */
+export declare function approveMany(env: Env, ids: readonly number[], comment?: string): Promise<{
+    approved: number;
+    failed: {
+        id: number;
+        reason: string;
+    }[];
+}>;
+/** The inbox's header: waiting, waiting over three days, decided this month, the median hours to decide them. */
+export declare function approvalStats(env: Env): Promise<{
+    waiting: number;
+    overdue: number;
+    decidedThisMonth: number;
+    medianHours: number | null;
+}>;
+/** The periods of the matrix dashboard, in days (`all`: no limit). */
+declare const MATRIX_DAYS: {
+    readonly '7d': 7;
+    readonly '30d': 30;
+    readonly '3m': 91;
+    readonly '6m': 182;
+    readonly '1y': 365;
+    readonly all: null;
+};
+export type MatrixPeriod = keyof typeof MATRIX_DAYS;
+export declare const MATRIX_PERIODS: readonly MatrixPeriod[];
+/** One card of the matrix: a policy's requests the user decides, by state. */
+export interface MatrixCard {
+    readonly policy: number | null;
+    readonly title: string;
+    readonly waiting: number;
+    readonly approved: number;
+    readonly rejected: number;
+    readonly total: number;
+}
+/**
+ * The matrix dashboard (RFC 0027 §2.7): the requests of the period the user decides — directly (named, or holding
+ * the role) or delegated (as a backup or for someone away) — a card per policy with what waits, what was approved
+ * and rejected; for Approvals managers also the hours each level takes to decide and the bottlenecks (who has the
+ * most requests late).
+ */
+export declare function approvalMatrix(env: Env, period: MatrixPeriod, mode: 'direct' | 'delegated'): Promise<{
+    cards: MatrixCard[];
+    direct: number;
+    delegated: number;
+    levels: {
+        policy: string;
+        level: string;
+        decided: number;
+        averageHours: number;
+    }[] | null;
+    bottlenecks: {
+        user: number;
+        name: string;
+        late: number;
+        waiting: number;
+    }[] | null;
+}>;
+/** The people who may decide `request` now: its approvers (or its role's holders), the escalation role's once late,
+ * and whoever they delegated to today; never the requester. */
+export declare function decidersOf(su: Env, request: ApprovalRequestInfo, today: string): Promise<number[]>;
+/** The pending requests of a record whose turn it is (every lower level approved). */
+export declare function turnOf(su: Env, model: string, id: number): Promise<ApprovalRequestInfo[]>;
 /**
- * Approves or rejects a request as `env`'s user. @throws {HttpProblem} 404 unknown, 409 decided / not its turn,
- * 403 not an approver, the requester, or another company
+ * Deadlines (RFC 0025 §3.3), as the system: each pending request with a deadline is reminded once at half of it and,
+ * once late, escalated to its level's role (who may then decide too), audited; returns what was done, with who to
+ * tell.
  */
-export declare function decide(env: Env, requestId: number, decision: 'approve' | 'reject', comment?: string): Promise<ApprovalRequestInfo>;
+export declare function sweepDeadlines(su: Env, now?: Date): Promise<{
+    kind: 'reminded' | 'escalated';
+    request: ApprovalRequestInfo;
+}[]>;
+/** One-time links deciding `request` from an email, one per person who may decide it now (7 days). */
+export declare function issueLinks(su: Env, request: ApprovalRequestInfo, today: string, newToken: () => string, digestOf: (token: string) => string, only?: readonly number[]): Promise<{
+    user: number;
+    token: string;
+}[]>;
+/** The link of a token, while it is unused and not expired: who decides, which request. */
+export declare function linkOf(su: Env, tokenHash: string): Promise<{
+    id: number;
+    user: number;
+    request: ApprovalRequestInfo;
+} | null>;
+/** Marks a link used (as the system). */
+export declare function useLink(su: Env, id: number): Promise<void>;
+/** A user's groups in a company (direct grants), to act as them from a link. */
+export declare function groupsOf(su: Env, user: number, company: number | null): Promise<string[]>;
 /** The pending requests `env`'s user may decide now, in the current company. */
 export declare function inbox(env: Env): Promise<ApprovalRequestInfo[]>;
 /** The requests of a record, when `env` may read the record (record rules apply: 404 otherwise). */
 export declare function requestsOf(env: Env, model: string, id: number): Promise<ApprovalRequestInfo[]>;
 /** Installs the default policies the modules declare (`approvals` in manifests) that do not exist yet, by name. */
 export declare function installApprovalPolicies(env: Env, modules: readonly KoshModule[]): Promise<number>;
+export {};