@managesome/eposmatic-toolkit 0.4.29 → 0.4.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +9 -12
  2. package/esm/helpers/materialized-reports/index.js +1 -0
  3. package/esm/helpers/materialized-reports/materialized-credit-bills-helpers.js +129 -20
  4. package/esm/helpers/materialized-reports/materialized-discount-classification-helpers.js +10 -3
  5. package/esm/helpers/materialized-reports/materialized-discount-close-day-helpers.js +251 -240
  6. package/esm/helpers/materialized-reports/materialized-discount-compile-helpers.js +2 -1
  7. package/esm/helpers/materialized-reports/materialized-discount-source-helpers.js +176 -0
  8. package/esm/helpers/materialized-reports/materialized-index-bootstrap.js +64 -0
  9. package/esm/helpers/materialized-reports/materialized-integer-contract.js +30 -4
  10. package/esm/helpers/materialized-reports/materialized-report-drilldown-rows.js +4 -2
  11. package/esm/helpers/materialized-reports/materialized-reports-selection-helpers.js +7 -0
  12. package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +284 -43
  13. package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +4 -4
  14. package/esm/schemas/models/materialized_report_drilldown_rows.js +39 -12
  15. package/esm/schemas/models/materialized_tenant_discount_entries.js +18 -12
  16. package/esm/schemas/models/materialized_tenant_discount_sources.js +1 -1
  17. package/esm/schemas/models/orders.js +5 -0
  18. package/esm/schemas/models/tenant_calendar.js +12 -0
  19. package/lib/constants/MATERIALIZED_REPORTS.d.ts +9 -12
  20. package/lib/constants/MATERIALIZED_REPORTS.js +11 -14
  21. package/lib/helpers/materialized-reports/index.d.ts +1 -0
  22. package/lib/helpers/materialized-reports/index.js +1 -0
  23. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.d.ts +38 -0
  24. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.js +129 -19
  25. package/lib/helpers/materialized-reports/materialized-discount-classification-helpers.js +10 -3
  26. package/lib/helpers/materialized-reports/materialized-discount-close-day-helpers.d.ts +23 -61
  27. package/lib/helpers/materialized-reports/materialized-discount-close-day-helpers.js +250 -239
  28. package/lib/helpers/materialized-reports/materialized-discount-compile-helpers.d.ts +4 -4
  29. package/lib/helpers/materialized-reports/materialized-discount-compile-helpers.js +1 -0
  30. package/lib/helpers/materialized-reports/materialized-discount-source-helpers.d.ts +17 -0
  31. package/lib/helpers/materialized-reports/materialized-discount-source-helpers.js +178 -0
  32. package/lib/helpers/materialized-reports/materialized-index-bootstrap.d.ts +7 -0
  33. package/lib/helpers/materialized-reports/materialized-index-bootstrap.js +68 -0
  34. package/lib/helpers/materialized-reports/materialized-integer-contract.d.ts +3 -1
  35. package/lib/helpers/materialized-reports/materialized-integer-contract.js +30 -4
  36. package/lib/helpers/materialized-reports/materialized-report-drilldown-rows.d.ts +2 -2
  37. package/lib/helpers/materialized-reports/materialized-report-drilldown-rows.js +4 -2
  38. package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.js +7 -0
  39. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +8 -0
  40. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +283 -42
  41. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +4 -4
  42. package/lib/schemas/models/materialized_report_drilldown_rows.d.ts +40 -6
  43. package/lib/schemas/models/materialized_report_drilldown_rows.js +39 -12
  44. package/lib/schemas/models/materialized_tenant_discount_entries.d.ts +33 -29
  45. package/lib/schemas/models/materialized_tenant_discount_entries.js +18 -12
  46. package/lib/schemas/models/materialized_tenant_discount_sources.d.ts +6 -6
  47. package/lib/schemas/models/materialized_tenant_discount_sources.js +1 -1
  48. package/lib/schemas/models/orders.d.ts +5 -0
  49. package/lib/schemas/models/orders.js +5 -0
  50. package/lib/schemas/models/tenant_calendar.d.ts +13 -0
  51. package/lib/schemas/models/tenant_calendar.js +13 -1
  52. package/lib/schemas/types/materialized_report_drilldown_rows.d.ts +8 -0
  53. package/lib/schemas/types/materialized_tenant_discount_entries.d.ts +9 -5
  54. package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.js +56 -1
  55. package/lib/tests/materialized-reports/materialized-discount-classification.test.js +17 -0
  56. package/lib/tests/materialized-reports/materialized-discount-close-day.test.js +60 -54
  57. package/lib/tests/materialized-reports/materialized-discount-entries-accumulation.test.js +14 -13
  58. package/lib/tests/materialized-reports/materialized-discount-sources.test.js +76 -0
  59. package/lib/tests/materialized-reports/materialized-integer-contract.test.js +11 -0
  60. package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.js +2 -2
  61. package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +152 -7
  62. package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +89 -0
  63. package/package.json +1 -1
@@ -121,24 +121,21 @@ export const SALES_OVERVIEW_KEY_FILTERS = [
121
121
  /* Discounts report (M1) */
122
122
  /* ======================================================================== */
123
123
  /**
124
- * Scopes materialized by `materialized_tenant_discount_reports` — the same
125
- * month-capped set as the credit ledger, for the same reason: the itemized
126
- * discount rows live in the SIBLING entries collection
127
- * (`materialized_tenant_discount_entries`), capped at `LOCAL_MONTH` so a
128
- * document can never grow unboundedly.
124
+ * Scopes materialized by `materialized_tenant_discount_reports`.
129
125
  *
130
- * DELIBERATELY MONTH-CAPPED: quarter / semester / year are NOT materialized.
131
- * The entry documents accumulate every day's rows for their scope, so a
132
- * quarter-scoped entry document grows without a natural bound and can reach the
133
- * 16 MB document ceiling at high volume (the credit-ledger reason). The
134
- * counter documents would be safe to widen, but the scope list is shared by
135
- * BOTH collections and the entries are the binding constraint. A selection that
136
- * decodes to a wider scope is refused by the historical route
126
+ * Period ENTRY documents are now day-partitioned (`page = source localDate`), so
127
+ * the old 16 MB constraint no longer binds. The scope set intentionally stays
128
+ * at `LOCAL_MONTH` for this change: widening the report surface is a report
129
+ * calculation/API change, not part of the page redesign. The page rule itself is
130
+ * generic and already supports quarter/semester/year if they are enabled.
131
+ * A selection that decodes to a wider scope is refused by the historical route
137
132
  * (`allowedScopeContexts`), never silently narrowed to a month.
138
133
  *
139
134
  * The report documents themselves are COUNTERS ONLY (see
140
135
  * `schemas/types/materialized_tenant_discount_reports.ts`).
141
136
  */
137
+ /** Entry-document page key for the day/hour scopes (they are already day-bounded). */
138
+ export const MATERIALIZED_DISCOUNT_ENTRY_PAGE_ALL = 'all';
142
139
  export const MATERIALIZED_DISCOUNT_REPORT_SCOPES = [
143
140
  MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_HOUR,
144
141
  MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE,
@@ -1,5 +1,6 @@
1
1
  export * from './key-helpers';
2
2
  export * from './materialized-credit-bills-helpers';
3
+ export * from './materialized-index-bootstrap';
3
4
  export * from './materialized-integer-contract';
4
5
  export * from './materialized-discount-accumulator-helpers';
5
6
  export * from './materialized-discount-classification-helpers';
@@ -1,5 +1,5 @@
1
1
  import mongoose from 'mongoose';
2
- import { PAYMENT_TYPE_ENUM } from '../../constants';
2
+ import { PAYMENT_TYPE_ENUM, REPORT_SALE_TYPE_ENUM } from '../../constants';
3
3
  import { ALL_MATERIALIZED_REPORT_SCOPES, MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM, MATERIALIZED_REPORT_SCOPE_ENUM, SALES_OVERVIEW_KEY_FILTERS, } from '../../constants/MATERIALIZED_REPORTS';
4
4
  import { MATERIALIZED_CREDIT_BILLS_SCHEMA_VERSION } from '../../schemas/models/materialized_credit_bills';
5
5
  import { getLocalDocumentFields, getLocalFieldsFromLocalDate } from '../utils/time-helpers';
@@ -112,11 +112,11 @@ export function buildCreditBillIssuedCandidatesFromOrder(order, orderLocalDate,
112
112
  const paymentId = payment.payment_id ?? payment._id ?? null;
113
113
  if (paymentId == null || paymentId.length === 0)
114
114
  return null; // un-keyable bill — data issue
115
- // Money is integer CENTS: the payment amounts are rounded to the cent at
116
- // this writer boundary, because a materialized ledger document may not
117
- // hold a decimal.
118
- const amount = Math.round(payment.amount_due ?? 0);
119
- const receivedAmount = Math.round(payment.amount_paid ?? 0);
115
+ // Money is integer CENTS. Do NOT round here: a fractional source amount is
116
+ // a data defect and the materialized-write integer gate must fail the close
117
+ // loudly, never silently change the ledger.
118
+ const amount = payment.amount_due ?? 0;
119
+ const receivedAmount = payment.amount_paid ?? 0;
120
120
  const settled = !settledLater && receivedAmount >= amount;
121
121
  candidates.push({
122
122
  order_id: order._id,
@@ -152,7 +152,7 @@ export function buildCreditBillEventCandidatesFromOrder(order, eventLocalDate, o
152
152
  if (paymentId == null || paymentId.length === 0)
153
153
  return null; // un-keyable bill — data issue
154
154
  // Money is integer CENTS (see the issued-bill candidate above).
155
- const receivedAmount = Math.round(payment.amount_paid ?? 0);
155
+ const receivedAmount = payment.amount_paid ?? 0;
156
156
  if (receivedAmount <= 0)
157
157
  continue; // nothing collected yet
158
158
  candidates.push({
@@ -161,7 +161,7 @@ export function buildCreditBillEventCandidatesFromOrder(order, eventLocalDate, o
161
161
  order_status: order.order_status,
162
162
  platform: order.platform,
163
163
  // Money is integer CENTS.
164
- amount: Math.round(payment.amount_due ?? 0),
164
+ amount: payment.amount_due ?? 0,
165
165
  issued_at: issuedAt,
166
166
  issued_local_date: orderLocalDate,
167
167
  issued_local_hour: issuedHourLabel,
@@ -218,12 +218,12 @@ export function resolveCreditBillDay(input) {
218
218
  for (const report of input.stored ?? []) {
219
219
  if (report == null || report.tenant_id !== tenantId)
220
220
  continue;
221
- for (const [, section] of sectionsOf(report)) {
221
+ for (const [sectionKey, section] of sectionsOf(report)) {
222
222
  for (const entry of section?.issued ?? []) {
223
- const key = creditBillIdentityKey(entry.order_id, entry.payment_id);
224
- const prior = storedIssuedByKey.get(key);
225
- if (prior == null || (entry.received_amount ?? 0) > (prior.received_amount ?? 0)) {
226
- storedIssuedByKey.set(key, entry);
223
+ const identity = creditBillIdentityKey(entry.order_id, entry.payment_id);
224
+ const prior = storedIssuedByKey.get(identity);
225
+ if (prior == null || (entry.received_amount ?? 0) > (prior.entry.received_amount ?? 0)) {
226
+ storedIssuedByKey.set(identity, { entry, key: sectionKey });
227
227
  }
228
228
  }
229
229
  for (const entry of section?.received ?? []) {
@@ -244,7 +244,7 @@ export function resolveCreditBillDay(input) {
244
244
  const key = buildMaterializedReportKey([candidate.order_status, candidate.platform]);
245
245
  if (key == null)
246
246
  return null; // un-keyable sale-type fields — data issue
247
- const stored = storedIssuedByKey.get(creditBillIdentityKey(candidate.order_id, candidate.payment_id));
247
+ const stored = storedIssuedByKey.get(creditBillIdentityKey(candidate.order_id, candidate.payment_id))?.entry;
248
248
  issued.push({
249
249
  key,
250
250
  source_watermark: candidate.source_watermark,
@@ -265,12 +265,14 @@ export function resolveCreditBillDay(input) {
265
265
  }
266
266
  const received_events = [];
267
267
  const settled_bills = [];
268
+ const receipt_bills = [];
268
269
  for (const candidate of input.events ?? []) {
269
270
  const key = buildMaterializedReportKey([candidate.order_status, candidate.platform]);
270
271
  if (key == null)
271
272
  return null; // un-keyable sale-type fields — data issue
272
273
  const identity = creditBillIdentityKey(candidate.order_id, candidate.payment_id);
273
- const storedIssued = storedIssuedByKey.get(identity) ?? null;
274
+ const storedIssuedRecord = storedIssuedByKey.get(identity) ?? null;
275
+ const storedIssued = storedIssuedRecord?.entry ?? null;
274
276
  const storedEvent = storedReceivedByKey.get(`${identity}|${candidate.event.event_local_date}`) ?? null;
275
277
  let delta;
276
278
  let cumulativeAfter;
@@ -320,11 +322,15 @@ export function resolveCreditBillDay(input) {
320
322
  });
321
323
  // The issue scopes must be patched exactly once per settlement — only
322
324
  // for EARLIER issue days (a same-day settlement rides the issued payload).
323
- if (settled && storedIssued != null && candidate.issued_local_date !== localDate) {
325
+ // The section key comes from the STORED entry, not the current order
326
+ // status/platform: an order may move PLACED -> COMPLETED between issue and
327
+ // collection, and the issue documents remain under the old key.
328
+ if (storedIssued != null && candidate.issued_local_date !== localDate) {
324
329
  const alreadySettled = storedIssued.settled_at != null || storedIssued.settled_local_date != null;
325
- if (!alreadySettled) {
330
+ if (settled && !alreadySettled) {
326
331
  settled_bills.push({
327
332
  key,
333
+ stored_key: storedIssuedRecord?.key ?? null,
328
334
  order_id: candidate.order_id,
329
335
  payment_id: candidate.payment_id,
330
336
  amount,
@@ -336,9 +342,83 @@ export function resolveCreditBillDay(input) {
336
342
  issued_local_hour: storedIssued.issued_local_hour ?? candidate.issued_local_hour ?? null,
337
343
  });
338
344
  }
345
+ else if (!settled && (storedIssued.received_amount ?? 0) < cumulativeAfter) {
346
+ // PARTIAL receipt: update the SAME bill's cumulative received_amount so
347
+ // outstanding_now reflects every installment, not only the final one.
348
+ receipt_bills.push({
349
+ key,
350
+ stored_key: storedIssuedRecord?.key ?? null,
351
+ order_id: candidate.order_id,
352
+ payment_id: candidate.payment_id,
353
+ amount,
354
+ received_amount: cumulativeAfter,
355
+ credit_note: candidate.event.credit_note ?? storedIssued.credit_note ?? null,
356
+ issued_local_date: candidate.issued_local_date,
357
+ issued_local_hour: storedIssued.issued_local_hour ?? candidate.issued_local_hour ?? null,
358
+ });
359
+ }
339
360
  }
340
361
  }
341
- return { issued, received_events, settled_bills };
362
+ return { issued, received_events, settled_bills, receipt_bills };
363
+ }
364
+ /**
365
+ * Applies one day's credit resolution to the compiled Overview documents:
366
+ * overwrites each key's received counters from the resolved event deltas and
367
+ * its issued settled counters from the stored anchors. Shared by the close-day
368
+ * plan and the LIVE Overview adapter so both use one rule.
369
+ */
370
+ export function applyCreditResolutionToReportDocuments(reports, resolution) {
371
+ const receivedByScopeKey = new Map();
372
+ for (const resolved of resolution.received_events) {
373
+ const delta = resolved.entry.received_delta ?? 0;
374
+ for (const doc of reports) {
375
+ if (doc.scope_context === MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_HOUR &&
376
+ doc.scope_field !== resolved.entry.event_local_hour) {
377
+ continue;
378
+ }
379
+ const mapKey = doc.scope_context + '|' + doc.scope_field + '|' + resolved.key;
380
+ const entry = receivedByScopeKey.get(mapKey) ?? { count: 0, amount: 0 };
381
+ entry.count += 1;
382
+ entry.amount += delta;
383
+ receivedByScopeKey.set(mapKey, entry);
384
+ }
385
+ }
386
+ for (const doc of reports) {
387
+ const metrics = doc.sale_type_metrics;
388
+ for (const [key, metric] of Object.entries(metrics ?? {})) {
389
+ const entry = receivedByScopeKey.get(doc.scope_context + '|' + doc.scope_field + '|' + key);
390
+ metric[REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].received = entry != null ? { ...entry } : { count: 0, amount: 0 };
391
+ }
392
+ }
393
+ const settledByKey = new Map();
394
+ for (const resolved of resolution.issued) {
395
+ const entry = resolved.entry;
396
+ if (entry.settled_at == null && entry.settled_local_date == null)
397
+ continue;
398
+ const totals = settledByKey.get(resolved.key) ?? { count: 0, amount: 0 };
399
+ totals.count += 1;
400
+ totals.amount += entry.amount ?? 0;
401
+ settledByKey.set(resolved.key, totals);
402
+ }
403
+ for (const doc of reports) {
404
+ const metrics = doc.sale_type_metrics;
405
+ for (const [key, metric] of Object.entries(metrics ?? {})) {
406
+ const entry = settledByKey.get(key);
407
+ metric[REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].issued.settled_count = entry?.count ?? 0;
408
+ metric[REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].issued.settled_amount = entry?.amount ?? 0;
409
+ }
410
+ }
411
+ const collectedAtIssue = {};
412
+ for (const resolved of resolution.issued) {
413
+ const atIssue = resolved.entry.received_at_issue ?? 0;
414
+ if (atIssue <= 0)
415
+ continue;
416
+ const totals = collectedAtIssue[resolved.key] ?? { count: 0, amount: 0 };
417
+ totals.count += 1;
418
+ totals.amount += atIssue;
419
+ collectedAtIssue[resolved.key] = totals;
420
+ }
421
+ return { collected_at_issue: collectedAtIssue };
342
422
  }
343
423
  const emptySection = () => ({ issued: [], received: [] });
344
424
  const sectionFor = (map, key) => map[key] ?? (map[key] = emptySection());
@@ -562,9 +642,15 @@ export function updateMaterializedCreditBillsReport(existing, updates, options =
562
642
  sourceWatermark = maxDate(sourceWatermark, delta.source_watermark) ?? sourceWatermark;
563
643
  }
564
644
  }
645
+ /** Find the issue section by the stored key (status drift), then fall back to the current key. */
646
+ const findIssueTarget = (key, storedKey) => {
647
+ if (storedKey != null && sections[storedKey] != null)
648
+ return sections[storedKey];
649
+ return sections[key] ?? null;
650
+ };
565
651
  let ledgerPatched = false;
566
652
  for (const settlement of updates.settled_bills ?? []) {
567
- const target = sections[settlement.key];
653
+ const target = findIssueTarget(settlement.key, settlement.stored_key);
568
654
  if (target == null)
569
655
  continue;
570
656
  const index = target.issued.findIndex((entry) => creditBillIdentityKey(entry.order_id, entry.payment_id) ===
@@ -583,12 +669,35 @@ export function updateMaterializedCreditBillsReport(existing, updates, options =
583
669
  };
584
670
  ledgerPatched = true;
585
671
  }
672
+ // Partial receipts update the SAME issue entry's cumulative amount. They are
673
+ // not new bills and never create a second receivable.
674
+ for (const receipt of updates.receipt_bills ?? []) {
675
+ const target = findIssueTarget(receipt.key, receipt.stored_key);
676
+ if (target == null)
677
+ continue;
678
+ const index = target.issued.findIndex((entry) => creditBillIdentityKey(entry.order_id, entry.payment_id) ===
679
+ creditBillIdentityKey(receipt.order_id, receipt.payment_id));
680
+ if (index < 0)
681
+ continue;
682
+ const entry = target.issued[index];
683
+ if ((entry.received_amount ?? 0) >= receipt.received_amount)
684
+ continue; // idempotent
685
+ target.issued[index] = {
686
+ ...entry,
687
+ received_amount: receipt.received_amount,
688
+ credit_note: receipt.credit_note ?? entry.credit_note ?? null,
689
+ };
690
+ ledgerPatched = true;
691
+ }
586
692
  const pruned = pruneSections(sections);
587
693
  const changed = serializeSections(pruned) !== serializeSections(toMutableSections(existing.credit_bills));
694
+ const envelopeChanged = (updates.replacement != null &&
695
+ (updates.replacement.source_input_signature ?? null) !== (existing.source_input_signature ?? null)) ||
696
+ new Date(sourceWatermark).getTime() > new Date(existing.source_watermark).getTime();
588
697
  return {
589
698
  ...existing,
590
699
  credit_bills: pruned,
591
- iteration: (existing.iteration ?? 1) + (changed || ledgerPatched ? 1 : 0),
700
+ iteration: (existing.iteration ?? 1) + (changed || ledgerPatched || envelopeChanged ? 1 : 0),
592
701
  // A REPLACEMENT carries the freshly compiled day digest; period folds keep
593
702
  // the stored value (their payload is a running ledger, not one day's input).
594
703
  source_input_signature: updates.replacement?.source_input_signature ?? existing.source_input_signature,
@@ -139,13 +139,20 @@ export function resolveRowMoney(details, rowTotal) {
139
139
  return { perSlot, row_total: total, allocated: resolved, unallocated: Math.max(0, total - resolved) };
140
140
  }
141
141
  // Several active slots (allocated offers): every slot is a FIXED amount when
142
- // more than one is active in practice, so assign each its own value and let
143
- // the remainder be unattributed rather than guessing a split.
142
+ // more than one is active in practice. Allocate in slot order against the
143
+ // headline, EXACTLY like a single fixed slot: a slot can never contribute
144
+ // more than the remaining discount. This prevents 500 + 300 against a 600
145
+ // headline from emitting 800 of entry money while the report total is 600.
144
146
  let allocated = 0;
145
147
  for (const reading of readings) {
146
148
  if (reading.is_percentage)
147
149
  continue; // a % mixed with other slots is unsplittable
148
- const value = Math.max(0, reading.rate);
150
+ const remaining = Math.max(0, total - allocated);
151
+ if (remaining <= 0)
152
+ break;
153
+ const value = Math.min(Math.max(0, reading.rate), remaining);
154
+ if (value <= 0)
155
+ continue;
149
156
  perSlot.set(reading.slot, value);
150
157
  allocated += value;
151
158
  }