@things-factory/accounting 10.1.155 → 10.1.156

package/dist-server/service/expenditure-request/expenditure-request-rules.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * The rules of an expenditure request (ADR-0135) - who may change it when, what it pays, what a decision means, and
+ * the monthly summary.
+ *
+ * ── The life of a request ──────────────────────────────────────────────────────────────────────
+ *   DRAFT ──submit──▶ SUBMITTED ──approved──▶ APPROVED ──bank lines pay it──▶ (paid, then reconciled)
+ *     ▲                  │  │
+ *     │                  │  └─rejected──▶ REJECTED ──edit & submit again──▶ SUBMITTED
+ *     └────withdraw──────┘ (WITHDRAWN, editable again)
+ *
+ * Only the requester edits, and only while nobody is judging it (DRAFT, REJECTED, WITHDRAWN). What approvers saw is
+ * what is paid: once submitted the lines and the payee's account are frozen.
+ *
+ * Paid and reconciled are not states stored here; they are read from the payments (§`paymentStateFrom`).
+ *
+ * Pure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPayable = exports.monthOf = exports.EDITABLE = void 0;
+exports.dayOf = dayOf;
+exports.canEdit = canEdit;
+exports.totalsOf = totalsOf;
+exports.submitRefusal = submitRefusal;
+exports.decisionOf = decisionOf;
+exports.requestForLine = requestForLine;
+exports.payeeAccountDrift = payeeAccountDrift;
+exports.monthlySummary = monthlySummary;
+exports.statusCounts = statusCounts;
+const shell_1 = require("@things-factory/shell");
+exports.EDITABLE = ['DRAFT', 'REJECTED', 'WITHDRAWN'];
+/** A day as people write it - 2026-09-03, 2026.9.3, 2026/9/3 - in YYYY-MM-DD, or undefined when it is not one. */
+function dayOf(value) {
+    const match = String(value ?? '').trim().match(/^(\d{4})[-./](\d{1,2})[-./](\d{1,2})\.?$/);
+    if (!match)
+        return undefined;
+    const [year, month, day] = match.slice(1).map(Number);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    if (date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day)
+        return undefined;
+    return `${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
+}
+/** A month as YYYY-MM, or undefined. */
+const monthOf = (value) => (/^\d{4}-(0[1-9]|1[0-2])$/.test(String(value ?? '')) ? String(value) : undefined);
+exports.monthOf = monthOf;
+function canEdit(status) {
+    return exports.EDITABLE.includes(status);
+}
+/** A line the company pays - everything but what the corporate card already paid. */
+const isPayable = (line) => line.paymentMethod !== 'CORPORATE_CARD';
+exports.isPayable = isPayable;
+/**
+ * What a request totals, and what of it the company is to pay. **The one place this is decided** - the request's
+ * stored totals, the payment queue and every reader take it from here.
+ */
+function totalsOf(lines) {
+    let total = 0;
+    let payable = 0;
+    for (const line of lines) {
+        total += line.amount || 0;
+        if ((0, exports.isPayable)(line))
+            payable += line.amount || 0;
+    }
+    return { total, payable, count: lines.length };
+}
+/** Why a request cannot be submitted, or undefined when it can. */
+function submitRefusal(head, lines) {
+    const { kind, status, month } = head;
+    if (!canEdit(status))
+        return new shell_1.Refusal('expenditure-submitted-already', { status: status.toLowerCase() }, `a ${status.toLowerCase()} request cannot be submitted again`);
+    if (kind === 'VENDOR') {
+        if (!head.counterpartyId)
+            return new shell_1.Refusal('expenditure-payee-missing', {}, 'choose who is paid');
+        if (!head.payeeAccountId)
+            return new shell_1.Refusal('expenditure-payee-account-missing', {}, "choose the counterparty's account to pay into");
+        if (!head.dueDate)
+            return new shell_1.Refusal('expenditure-due-date-missing', {}, 'set the day it is to be paid');
+    }
+    if (!lines.length)
+        return new shell_1.Refusal('expenditure-no-lines', {}, 'the request has no lines');
+    if (lines.some(line => !(line.amount > 0)))
+        return new shell_1.Refusal('expenditure-line-amount-missing', {}, 'every line needs an amount above zero');
+    if (lines.some(line => !line.spentDate))
+        return new shell_1.Refusal('expenditure-line-day-missing', {}, 'every line needs its day');
+    if (lines.some(line => !line.category && !line.accountId))
+        return new shell_1.Refusal('expenditure-line-category-missing', {}, 'every line needs a category or an account');
+    if (month && lines.some(line => line.spentDate && line.spentDate.slice(0, 7) > month))
+        return new shell_1.Refusal('expenditure-line-after-month', { month }, 'a line is dated after the month the request is for');
+    return undefined;
+}
+/**
+ * What an approval outcome does to the request.
+ *
+ * worklist calls the activity's callback on every state change, and more than once for the same one. A decision lands
+ * only on the request **still waiting on that very instance** - once it has moved on (decided, or withdrawn and
+ * submitted again as a new instance) a late call changes nothing.
+ */
+function decisionOf(instance, causedBy, request) {
+    if (request.status !== 'SUBMITTED' || request.activityInstanceId !== instance.id)
+        return undefined;
+    const state = String(instance.state).toLowerCase();
+    if (state === 'ended')
+        return 'APPROVED';
+    if (state === 'aborted')
+        return 'WITHDRAWN';
+    /* A rejection does not end the instance - the rejected thread is the only sign of it. */
+    if (causedBy.some(one => String(one.state).toLowerCase() === 'rejected'))
+        return 'REJECTED';
+    return undefined;
+}
+/**
+ * Which reimbursement a line added on the go joins - **the requester's editable one of that month.**
+ *
+ * The phone flow has no "request" step: a person snaps a receipt, types the amount and is done. The line goes to the
+ * month's draft; with none, to one sent back (rejected or withdrawn) so it can go up again with the rest; with none of
+ * those either, a new draft is started (undefined here). A request already with approvers or decided is never added
+ * to - what they saw stays what it was.
+ */
+function requestForLine(requests, month) {
+    const order = ['DRAFT', 'REJECTED', 'WITHDRAWN'];
+    const candidates = requests
+        .filter(one => one.month === month && order.includes(one.status))
+        .sort((a, b) => order.indexOf(a.status) - order.indexOf(b.status) || String(b.updatedAt ?? '').localeCompare(String(a.updatedAt ?? '')));
+    return candidates[0]?.id;
+}
+/**
+ * Whether the account approvers saw is still the one on file - `gone` when the counterparty's account was deleted
+ * (deleting a counterparty deletes its accounts), `changed` when its number or holder is no longer what was written at
+ * submission, or the account was moved to another counterparty. Finance is told before paying.
+ */
+function payeeAccountDrift(approved, current, keyOf) {
+    if (!current || current.deletedAt)
+        return 'gone';
+    if ((current.counterpartyId ?? null) !== (approved.counterpartyId ?? null))
+        return 'changed';
+    if (keyOf(current.accountNumber) !== keyOf(approved.payeeAccountNumber))
+        return 'changed';
+    if ((current.holderName ?? '').trim() !== (approved.payeeHolderName ?? '').trim())
+        return 'changed';
+    return undefined;
+}
+/**
+ * The monthly summary - per month, requester and category.
+ *
+ * Only approved requests count; a draft or a rejected one is not spending the company agreed to. The caller shows the
+ * others as counts by status.
+ */
+function monthlySummary(requests) {
+    const rows = new Map();
+    for (const request of requests) {
+        if (request.status !== 'APPROVED' || !request.month)
+            continue;
+        for (const item of request.items) {
+            const category = item.category || '기타';
+            const key = `${request.month}|${request.requesterId}|${category}`;
+            const row = rows.get(key) ?? {
+                month: request.month,
+                requesterId: request.requesterId,
+                requesterName: request.requesterName ?? null,
+                category,
+                total: 0,
+                payable: 0,
+                count: 0
+            };
+            row.total += item.amount || 0;
+            if ((0, exports.isPayable)(item))
+                row.payable += item.amount || 0;
+            row.count++;
+            rows.set(key, row);
+        }
+    }
+    return [...rows.values()].sort((a, b) => b.month.localeCompare(a.month) ||
+        String(a.requesterName ?? '').localeCompare(String(b.requesterName ?? '')) ||
+        a.category.localeCompare(b.category));
+}
+/** Requests per status - so drafts and pending ones are seen, not summed. */
+function statusCounts(requests) {
+    const counts = { DRAFT: 0, SUBMITTED: 0, APPROVED: 0, REJECTED: 0, WITHDRAWN: 0 };
+    for (const request of requests)
+        counts[request.status]++;
+    return counts;
+}
+//# sourceMappingURL=expenditure-request-rules.js.map

package/dist-server/service/expenditure-request/expenditure-request-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expenditure-request-rules.js","sourceRoot":"","sources":["../../../server/service/expenditure-request/expenditure-request-rules.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAoBH,sBAOC;AAKD,0BAEC;AASD,4BAQC;AAYD,sCAiBC;AASD,gCAcC;AAUD,wCASC;AAOD,8CAUC;AA0BD,wCA8BC;AAGD,oCAIC;AAxMD,iDAA+C;AAKlC,QAAA,QAAQ,GAA6B,CAAC,OAAO,EAAE,UAAU,EAAE,WAAW,CAAC,CAAA;AAYpF,kHAAkH;AAClH,SAAgB,KAAK,CAAC,KAAc;IAClC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAA;IAC1F,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAA;IAC5B,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IACrD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;IACrD,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,KAAK,GAAG;QAAE,OAAO,SAAS,CAAA;IACnF,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAA;AACpF,CAAC;AAED,wCAAwC;AACjC,MAAM,OAAO,GAAG,CAAC,KAAc,EAAsB,EAAE,CAAC,CAAC,yBAAyB,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;AAAnI,QAAA,OAAO,WAA4H;AAEhJ,SAAgB,OAAO,CAAC,MAAqB;IAC3C,OAAO,gBAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;AAClC,CAAC;AAED,qFAAqF;AAC9E,MAAM,SAAS,GAAG,CAAC,IAAwC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,KAAK,gBAAgB,CAAA;AAAjG,QAAA,SAAS,aAAwF;AAE9G;;;GAGG;AACH,SAAgB,QAAQ,CAAC,KAA6B;IACpD,IAAI,KAAK,GAAG,CAAC,CAAA;IACb,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,CAAA;QACzB,IAAI,IAAA,iBAAS,EAAC,IAAI,CAAC;YAAE,OAAO,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,CAAA;IAClD,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,CAAA;AAChD,CAAC;AAWD,mEAAmE;AACnE,SAAgB,aAAa,CAAC,IAAmB,EAAE,KAA6B;IAC9E,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAA;IACpC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;QAClB,OAAO,IAAI,eAAO,CAAC,+BAA+B,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,EAAE,EAAE,KAAK,MAAM,CAAC,WAAW,EAAE,oCAAoC,CAAC,CAAA;IACtJ,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,IAAI,CAAC,IAAI,CAAC,cAAc;YAAE,OAAO,IAAI,eAAO,CAAC,2BAA2B,EAAE,EAAE,EAAE,oBAAoB,CAAC,CAAA;QACnG,IAAI,CAAC,IAAI,CAAC,cAAc;YAAE,OAAO,IAAI,eAAO,CAAC,mCAAmC,EAAE,EAAE,EAAE,+CAA+C,CAAC,CAAA;QACtI,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,eAAO,CAAC,8BAA8B,EAAE,EAAE,EAAE,8BAA8B,CAAC,CAAA;IAC3G,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,IAAI,eAAO,CAAC,sBAAsB,EAAE,EAAE,EAAE,0BAA0B,CAAC,CAAA;IAC7F,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,eAAO,CAAC,iCAAiC,EAAE,EAAE,EAAE,uCAAuC,CAAC,CAAA;IAC9I,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,eAAO,CAAC,8BAA8B,EAAE,EAAE,EAAE,0BAA0B,CAAC,CAAA;IAC3H,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;QACvD,OAAO,IAAI,eAAO,CAAC,mCAAmC,EAAE,EAAE,EAAE,2CAA2C,CAAC,CAAA;IAC1G,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC;QACnF,OAAO,IAAI,eAAO,CAAC,8BAA8B,EAAE,EAAE,KAAK,EAAE,EAAE,oDAAoD,CAAC,CAAA;IACrH,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,UAAU,CACxB,QAAuC,EACvC,QAAuC,EACvC,OAAsE;IAEtE,IAAI,OAAO,CAAC,MAAM,KAAK,WAAW,IAAI,OAAO,CAAC,kBAAkB,KAAK,QAAQ,CAAC,EAAE;QAAE,OAAO,SAAS,CAAA;IAElG,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAA;IAClD,IAAI,KAAK,KAAK,OAAO;QAAE,OAAO,UAAU,CAAA;IACxC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,WAAW,CAAA;IAC3C,yFAAyF;IACzF,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,KAAK,UAAU,CAAC;QAAE,OAAO,UAAU,CAAA;IAE3F,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,cAAc,CAC5B,QAAmH,EACnH,KAAa;IAEb,MAAM,KAAK,GAAoB,CAAC,OAAO,EAAE,UAAU,EAAE,WAAW,CAAC,CAAA;IACjE,MAAM,UAAU,GAAG,QAAQ;SACxB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,KAAK,KAAK,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;SAChE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;IAC1I,OAAO,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAA;AAC1B,CAAC;AAED;;;;GAIG;AACH,SAAgB,iBAAiB,CAC/B,QAAiH,EACjH,OAA2J,EAC3J,KAAiC;IAEjC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,SAAS;QAAE,OAAO,MAAM,CAAA;IAChD,IAAI,CAAC,OAAO,CAAC,cAAc,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,cAAc,IAAI,IAAI,CAAC;QAAE,OAAO,SAAS,CAAA;IAC5F,IAAI,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,KAAK,KAAK,CAAC,QAAQ,CAAC,kBAAkB,CAAC;QAAE,OAAO,SAAS,CAAA;IACzF,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;QAAE,OAAO,SAAS,CAAA;IACnG,OAAO,SAAS,CAAA;AAClB,CAAC;AAoBD;;;;;GAKG;AACH,SAAgB,cAAc,CAAC,QAAmC;IAChE,MAAM,IAAI,GAAG,IAAI,GAAG,EAA2B,CAAA;IAE/C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,MAAM,KAAK,UAAU,IAAI,CAAC,OAAO,CAAC,KAAK;YAAE,SAAQ;QAC7D,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAA;YACtC,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,WAAW,IAAI,QAAQ,EAAE,CAAA;YACjE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI;gBAC3B,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,IAAI;gBAC5C,QAAQ;gBACR,KAAK,EAAE,CAAC;gBACR,OAAO,EAAE,CAAC;gBACV,KAAK,EAAE,CAAC;aACT,CAAA;YACD,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,CAAA;YAC7B,IAAI,IAAA,iBAAS,EAAC,IAAI,CAAC;gBAAE,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,CAAA;YACpD,GAAG,CAAC,KAAK,EAAE,CAAA;YACX,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;QACpB,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAC5B,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC;QAC9B,MAAM,CAAC,CAAC,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC;QAC1E,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CACvC,CAAA;AACH,CAAC;AAED,6EAA6E;AAC7E,SAAgB,YAAY,CAAC,QAA8C;IACzE,MAAM,MAAM,GAAkC,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAA;IAChH,KAAK,MAAM,OAAO,IAAI,QAAQ;QAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAA;IACxD,OAAO,MAAM,CAAA;AACf,CAAC","sourcesContent":["/**\n * The rules of an expenditure request (ADR-0135) - who may change it when, what it pays, what a decision means, and\n * the monthly summary.\n *\n * ── The life of a request ──────────────────────────────────────────────────────────────────────\n *   DRAFT ──submit──▶ SUBMITTED ──approved──▶ APPROVED ──bank lines pay it──▶ (paid, then reconciled)\n *     ▲                  │  │\n *     │                  │  └─rejected──▶ REJECTED ──edit & submit again──▶ SUBMITTED\n *     └────withdraw──────┘ (WITHDRAWN, editable again)\n *\n * Only the requester edits, and only while nobody is judging it (DRAFT, REJECTED, WITHDRAWN). What approvers saw is\n * what is paid: once submitted the lines and the payee's account are frozen.\n *\n * Paid and reconciled are not states stored here; they are read from the payments (§`paymentStateFrom`).\n *\n * Pure.\n */\n\nimport { Refusal } from '@things-factory/shell'\n\nexport type RequestStatus = 'DRAFT' | 'SUBMITTED' | 'APPROVED' | 'REJECTED' | 'WITHDRAWN'\nexport type RequestKind = 'VENDOR' | 'REIMBURSEMENT'\n\nexport const EDITABLE: readonly RequestStatus[] = ['DRAFT', 'REJECTED', 'WITHDRAWN']\n\nexport interface RequestLine {\n  amount: number\n  vatAmount?: number | null\n  paymentMethod?: string | null\n  category?: string | null\n  accountId?: string | null\n  spentDate?: string | null\n  taxInvoiceId?: string | null\n}\n\n/** A day as people write it - 2026-09-03, 2026.9.3, 2026/9/3 - in YYYY-MM-DD, or undefined when it is not one. */\nexport function dayOf(value: unknown): string | undefined {\n  const match = String(value ?? '').trim().match(/^(\\d{4})[-./](\\d{1,2})[-./](\\d{1,2})\\.?$/)\n  if (!match) return undefined\n  const [year, month, day] = match.slice(1).map(Number)\n  const date = new Date(Date.UTC(year, month - 1, day))\n  if (date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) return undefined\n  return `${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`\n}\n\n/** A month as YYYY-MM, or undefined. */\nexport const monthOf = (value: unknown): string | undefined => (/^\\d{4}-(0[1-9]|1[0-2])$/.test(String(value ?? '')) ? String(value) : undefined)\n\nexport function canEdit(status: RequestStatus): boolean {\n  return EDITABLE.includes(status)\n}\n\n/** A line the company pays - everything but what the corporate card already paid. */\nexport const isPayable = (line: Pick<RequestLine, 'paymentMethod'>) => line.paymentMethod !== 'CORPORATE_CARD'\n\n/**\n * What a request totals, and what of it the company is to pay. **The one place this is decided** - the request's\n * stored totals, the payment queue and every reader take it from here.\n */\nexport function totalsOf(lines: readonly RequestLine[]): { total: number; payable: number; count: number } {\n  let total = 0\n  let payable = 0\n  for (const line of lines) {\n    total += line.amount || 0\n    if (isPayable(line)) payable += line.amount || 0\n  }\n  return { total, payable, count: lines.length }\n}\n\nexport interface SubmittedHead {\n  kind: RequestKind\n  status: RequestStatus\n  month?: string | null\n  dueDate?: string | null\n  counterpartyId?: string | null\n  payeeAccountId?: string | null\n}\n\n/** Why a request cannot be submitted, or undefined when it can. */\nexport function submitRefusal(head: SubmittedHead, lines: readonly RequestLine[]): Refusal | undefined {\n  const { kind, status, month } = head\n  if (!canEdit(status))\n    return new Refusal('expenditure-submitted-already', { status: status.toLowerCase() }, `a ${status.toLowerCase()} request cannot be submitted again`)\n  if (kind === 'VENDOR') {\n    if (!head.counterpartyId) return new Refusal('expenditure-payee-missing', {}, 'choose who is paid')\n    if (!head.payeeAccountId) return new Refusal('expenditure-payee-account-missing', {}, \"choose the counterparty's account to pay into\")\n    if (!head.dueDate) return new Refusal('expenditure-due-date-missing', {}, 'set the day it is to be paid')\n  }\n  if (!lines.length) return new Refusal('expenditure-no-lines', {}, 'the request has no lines')\n  if (lines.some(line => !(line.amount > 0))) return new Refusal('expenditure-line-amount-missing', {}, 'every line needs an amount above zero')\n  if (lines.some(line => !line.spentDate)) return new Refusal('expenditure-line-day-missing', {}, 'every line needs its day')\n  if (lines.some(line => !line.category && !line.accountId))\n    return new Refusal('expenditure-line-category-missing', {}, 'every line needs a category or an account')\n  if (month && lines.some(line => line.spentDate && line.spentDate.slice(0, 7) > month))\n    return new Refusal('expenditure-line-after-month', { month }, 'a line is dated after the month the request is for')\n  return undefined\n}\n\n/**\n * What an approval outcome does to the request.\n *\n * worklist calls the activity's callback on every state change, and more than once for the same one. A decision lands\n * only on the request **still waiting on that very instance** - once it has moved on (decided, or withdrawn and\n * submitted again as a new instance) a late call changes nothing.\n */\nexport function decisionOf(\n  instance: { id: string; state: string },\n  causedBy: readonly { state?: string }[],\n  request: { status: RequestStatus; activityInstanceId?: string | null }\n): 'APPROVED' | 'REJECTED' | 'WITHDRAWN' | undefined {\n  if (request.status !== 'SUBMITTED' || request.activityInstanceId !== instance.id) return undefined\n\n  const state = String(instance.state).toLowerCase()\n  if (state === 'ended') return 'APPROVED'\n  if (state === 'aborted') return 'WITHDRAWN'\n  /* A rejection does not end the instance - the rejected thread is the only sign of it. */\n  if (causedBy.some(one => String(one.state).toLowerCase() === 'rejected')) return 'REJECTED'\n\n  return undefined\n}\n\n/**\n * Which reimbursement a line added on the go joins - **the requester's editable one of that month.**\n *\n * The phone flow has no \"request\" step: a person snaps a receipt, types the amount and is done. The line goes to the\n * month's draft; with none, to one sent back (rejected or withdrawn) so it can go up again with the rest; with none of\n * those either, a new draft is started (undefined here). A request already with approvers or decided is never added\n * to - what they saw stays what it was.\n */\nexport function requestForLine(\n  requests: readonly { id: string; status: RequestStatus; month?: string | null; updatedAt?: Date | string | null }[],\n  month: string\n): string | undefined {\n  const order: RequestStatus[] = ['DRAFT', 'REJECTED', 'WITHDRAWN']\n  const candidates = requests\n    .filter(one => one.month === month && order.includes(one.status))\n    .sort((a, b) => order.indexOf(a.status) - order.indexOf(b.status) || String(b.updatedAt ?? '').localeCompare(String(a.updatedAt ?? '')))\n  return candidates[0]?.id\n}\n\n/**\n * Whether the account approvers saw is still the one on file - `gone` when the counterparty's account was deleted\n * (deleting a counterparty deletes its accounts), `changed` when its number or holder is no longer what was written at\n * submission, or the account was moved to another counterparty. Finance is told before paying.\n */\nexport function payeeAccountDrift(\n  approved: { counterpartyId?: string | null; payeeAccountNumber?: string | null; payeeHolderName?: string | null },\n  current: { counterpartyId?: string | null; accountNumber?: string | null; holderName?: string | null; deletedAt?: Date | string | null } | null | undefined,\n  keyOf: (value: unknown) => string\n): 'gone' | 'changed' | undefined {\n  if (!current || current.deletedAt) return 'gone'\n  if ((current.counterpartyId ?? null) !== (approved.counterpartyId ?? null)) return 'changed'\n  if (keyOf(current.accountNumber) !== keyOf(approved.payeeAccountNumber)) return 'changed'\n  if ((current.holderName ?? '').trim() !== (approved.payeeHolderName ?? '').trim()) return 'changed'\n  return undefined\n}\n\nexport interface SummaryRequest {\n  month?: string | null\n  requesterId: string\n  requesterName?: string | null\n  status: RequestStatus\n  items: RequestLine[]\n}\n\nexport interface MonthSummaryRow {\n  month: string\n  requesterId: string\n  requesterName: string | null\n  category: string\n  total: number\n  payable: number\n  count: number\n}\n\n/**\n * The monthly summary - per month, requester and category.\n *\n * Only approved requests count; a draft or a rejected one is not spending the company agreed to. The caller shows the\n * others as counts by status.\n */\nexport function monthlySummary(requests: readonly SummaryRequest[]): MonthSummaryRow[] {\n  const rows = new Map<string, MonthSummaryRow>()\n\n  for (const request of requests) {\n    if (request.status !== 'APPROVED' || !request.month) continue\n    for (const item of request.items) {\n      const category = item.category || '기타'\n      const key = `${request.month}|${request.requesterId}|${category}`\n      const row = rows.get(key) ?? {\n        month: request.month,\n        requesterId: request.requesterId,\n        requesterName: request.requesterName ?? null,\n        category,\n        total: 0,\n        payable: 0,\n        count: 0\n      }\n      row.total += item.amount || 0\n      if (isPayable(item)) row.payable += item.amount || 0\n      row.count++\n      rows.set(key, row)\n    }\n  }\n\n  return [...rows.values()].sort(\n    (a, b) =>\n      b.month.localeCompare(a.month) ||\n      String(a.requesterName ?? '').localeCompare(String(b.requesterName ?? '')) ||\n      a.category.localeCompare(b.category)\n  )\n}\n\n/** Requests per status - so drafts and pending ones are seen, not summed. */\nexport function statusCounts(requests: readonly { status: RequestStatus }[]): Record<RequestStatus, number> {\n  const counts: Record<RequestStatus, number> = { DRAFT: 0, SUBMITTED: 0, APPROVED: 0, REJECTED: 0, WITHDRAWN: 0 }\n  for (const request of requests) counts[request.status]++\n  return counts\n}\n"]}

package/dist-server/service/expenditure-request/expenditure-request-service.d.ts

@@ -0,0 +1,92 @@
+import { EntityManager } from 'typeorm';
+import { Refusal } from '@things-factory/shell';
+import { ExpenditureRequest } from './expenditure-request';
+import { ExpenditureRequestItem } from './expenditure-request-item';
+import { type PaymentState } from './expenditure-payment-state';
+export declare const RECEIPT_REF_TYPE = "ExpenditureRequestItem";
+export interface RequestHead {
+    id?: string;
+    kind?: string;
+    title?: string;
+    month?: string;
+    dueDate?: string;
+    counterparty?: {
+        id: string;
+    } | null;
+    payeeAccount?: {
+        id: string;
+    } | null;
+    notes?: string;
+}
+export interface ItemPatch {
+    id?: string;
+    cuFlag?: string;
+    spentDate?: string;
+    category?: string;
+    account?: {
+        id: string;
+    } | null;
+    merchant?: string;
+    description?: string;
+    amount?: number;
+    vatAmount?: number;
+    paymentMethod?: string;
+    taxInvoice?: {
+        id: string;
+    } | null;
+}
+/** A request somebody is judging (or that is decided) - it changes only after it is withdrawn. */
+export declare const lockedRequest: (status: string) => Refusal;
+/** The request of this domain, refusing one that is not the caller's own. */
+export declare function ownRequest(tx: EntityManager, id: string, domain: {
+    id: string;
+}, user: {
+    id: string;
+}): Promise<ExpenditureRequest>;
+/**
+ * Save a request and its lines in one go - the head, then the lines. A new request belongs to the caller; an existing
+ * one only to its requester, and only while it is editable.
+ */
+export declare function saveRequest(tx: EntityManager, domain: any, user: any, head: RequestHead, items: ItemPatch[]): Promise<ExpenditureRequest>;
+/** Put a request up for approval. The approval carries what the approver needs to judge it. */
+export declare function submitRequest(tx: EntityManager, domain: any, user: any, id: string, context: ResolverContext): Promise<ExpenditureRequest>;
+/** Take a request back from its approvers. worklist's abort does not call the activity back, so the request is set here. */
+export declare function withdrawRequest(tx: EntityManager, domain: any, user: any, id: string, context: ResolverContext): Promise<ExpenditureRequest>;
+/** Delete one of the caller's requests that nobody is judging - with its lines. */
+export declare function deleteRequest(tx: EntityManager, domain: any, user: any, id: string): Promise<boolean>;
+/**
+ * Add one line from the phone. It joins the caller's editable reimbursement of that month (§`requestForLine`), or
+ * starts one. The receipt photo is attached to the line.
+ */
+export declare function addLine(tx: EntityManager, domain: any, user: any, line: ItemPatch & {
+    month?: string;
+    receipt?: any;
+}, context: ResolverContext): Promise<ExpenditureRequest>;
+/** Put a receipt on a line - replacing the one it had. Only the requester, only while editable. */
+export declare function replaceReceipt(tx: EntityManager, domain: any, user: any, itemId: string, file: any, context: ResolverContext): Promise<ExpenditureRequestItem>;
+/** Approved requests with their lines and how far each is paid - what the payment queue and payments are made of. */
+export declare function approvedWithStates(tx: EntityManager, domain: {
+    id: string;
+}, ids?: string[]): Promise<{
+    requests: ExpenditureRequest[];
+    states: Map<string, PaymentState>;
+}>;
+/** Whether the account approvers saw is still the one on file (§`payeeAccountDrift`); `missing` when none was written. */
+export declare function driftOf(tx: EntityManager, request: ExpenditureRequest): Promise<string | undefined>;
+export interface PaymentRecord {
+    paidDate: string;
+    bankAccount?: {
+        id: string;
+    } | null;
+}
+/**
+ * Pay approved requests - finance transferred the money at the bank and records it. Each request gets a withdrawal of
+ * what it still asks, written as a person's line; the next bank statement import matches it, and then the payment is
+ * reconciled (§`bank-reconcile`).
+ */
+export declare function payRequests(tx: EntityManager, domain: any, user: any, ids: string[], record: PaymentRecord): Promise<ExpenditureRequest[]>;
+/**
+ * Pay a request with a withdrawal already in the books - a bank statement brought it in first. The part put on the
+ * request is what it still asks unless a smaller amount is given.
+ */
+export declare function payWithLine(tx: EntityManager, domain: any, user: any, requestId: string, transactionId: string, amount?: number | null): Promise<ExpenditureRequest>;