@managesome/eposmatic-toolkit 0.4.28 → 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 (89) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +9 -12
  2. package/esm/helpers/materialized-reports/index.js +2 -0
  3. package/esm/helpers/materialized-reports/materialized-credit-bills-helpers.js +178 -40
  4. package/esm/helpers/materialized-reports/materialized-day-input-signature.js +103 -0
  5. package/esm/helpers/materialized-reports/materialized-discount-classification-helpers.js +10 -3
  6. package/esm/helpers/materialized-reports/materialized-discount-close-day-helpers.js +299 -227
  7. package/esm/helpers/materialized-reports/materialized-discount-compile-helpers.js +20 -1
  8. package/esm/helpers/materialized-reports/materialized-discount-source-helpers.js +176 -0
  9. package/esm/helpers/materialized-reports/materialized-index-bootstrap.js +64 -0
  10. package/esm/helpers/materialized-reports/materialized-integer-contract.js +30 -4
  11. package/esm/helpers/materialized-reports/materialized-report-drilldown-rows.js +4 -2
  12. package/esm/helpers/materialized-reports/materialized-reports-selection-helpers.js +7 -0
  13. package/esm/helpers/materialized-reports/scope-helpers.js +27 -0
  14. package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +400 -46
  15. package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +28 -6
  16. package/esm/schemas/models/materialized_credit_bills.js +8 -0
  17. package/esm/schemas/models/materialized_report_drilldown_rows.js +39 -12
  18. package/esm/schemas/models/materialized_tenant_discount_entries.js +18 -12
  19. package/esm/schemas/models/materialized_tenant_discount_reports.js +9 -0
  20. package/esm/schemas/models/materialized_tenant_discount_sources.js +1 -1
  21. package/esm/schemas/models/materialized_tenant_sales_overview_reports.js +9 -0
  22. package/esm/schemas/models/orders.js +5 -0
  23. package/esm/schemas/models/tenant_active_jobs.js +8 -0
  24. package/esm/schemas/models/tenant_calendar.js +12 -0
  25. package/lib/constants/MATERIALIZED_REPORTS.d.ts +9 -12
  26. package/lib/constants/MATERIALIZED_REPORTS.js +11 -14
  27. package/lib/helpers/materialized-reports/index.d.ts +2 -0
  28. package/lib/helpers/materialized-reports/index.js +2 -0
  29. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.d.ts +66 -2
  30. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.js +179 -39
  31. package/lib/helpers/materialized-reports/materialized-day-input-signature.d.ts +66 -0
  32. package/lib/helpers/materialized-reports/materialized-day-input-signature.js +108 -0
  33. package/lib/helpers/materialized-reports/materialized-discount-classification-helpers.js +10 -3
  34. package/lib/helpers/materialized-reports/materialized-discount-close-day-helpers.d.ts +41 -60
  35. package/lib/helpers/materialized-reports/materialized-discount-close-day-helpers.js +298 -226
  36. package/lib/helpers/materialized-reports/materialized-discount-compile-helpers.d.ts +4 -4
  37. package/lib/helpers/materialized-reports/materialized-discount-compile-helpers.js +19 -0
  38. package/lib/helpers/materialized-reports/materialized-discount-source-helpers.d.ts +17 -0
  39. package/lib/helpers/materialized-reports/materialized-discount-source-helpers.js +178 -0
  40. package/lib/helpers/materialized-reports/materialized-index-bootstrap.d.ts +7 -0
  41. package/lib/helpers/materialized-reports/materialized-index-bootstrap.js +68 -0
  42. package/lib/helpers/materialized-reports/materialized-integer-contract.d.ts +3 -1
  43. package/lib/helpers/materialized-reports/materialized-integer-contract.js +30 -4
  44. package/lib/helpers/materialized-reports/materialized-report-drilldown-rows.d.ts +2 -2
  45. package/lib/helpers/materialized-reports/materialized-report-drilldown-rows.js +4 -2
  46. package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.js +7 -0
  47. package/lib/helpers/materialized-reports/scope-helpers.d.ts +22 -0
  48. package/lib/helpers/materialized-reports/scope-helpers.js +28 -0
  49. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +49 -3
  50. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +398 -44
  51. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.d.ts +4 -1
  52. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +28 -6
  53. package/lib/schemas/models/materialized_credit_bills.d.ts +3 -0
  54. package/lib/schemas/models/materialized_credit_bills.js +8 -0
  55. package/lib/schemas/models/materialized_report_drilldown_rows.d.ts +40 -6
  56. package/lib/schemas/models/materialized_report_drilldown_rows.js +39 -12
  57. package/lib/schemas/models/materialized_tenant_discount_entries.d.ts +33 -29
  58. package/lib/schemas/models/materialized_tenant_discount_entries.js +18 -12
  59. package/lib/schemas/models/materialized_tenant_discount_reports.d.ts +3 -0
  60. package/lib/schemas/models/materialized_tenant_discount_reports.js +9 -0
  61. package/lib/schemas/models/materialized_tenant_discount_sources.d.ts +6 -6
  62. package/lib/schemas/models/materialized_tenant_discount_sources.js +1 -1
  63. package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +3 -0
  64. package/lib/schemas/models/materialized_tenant_sales_overview_reports.js +9 -0
  65. package/lib/schemas/models/orders.d.ts +5 -0
  66. package/lib/schemas/models/orders.js +5 -0
  67. package/lib/schemas/models/tenant_active_jobs.d.ts +3 -0
  68. package/lib/schemas/models/tenant_active_jobs.js +8 -0
  69. package/lib/schemas/models/tenant_calendar.d.ts +13 -0
  70. package/lib/schemas/models/tenant_calendar.js +13 -1
  71. package/lib/schemas/types/materialized_credit_bills.d.ts +6 -0
  72. package/lib/schemas/types/materialized_report_drilldown_rows.d.ts +8 -0
  73. package/lib/schemas/types/materialized_tenant_discount_entries.d.ts +9 -5
  74. package/lib/schemas/types/materialized_tenant_discount_reports.d.ts +6 -0
  75. package/lib/schemas/types/materialized_tenant_reports_iterations.d.ts +9 -0
  76. package/lib/schemas/types/materialized_tenant_sales_overview_reports.d.ts +14 -0
  77. package/lib/schemas/types/tenant_active_jobs.d.ts +8 -0
  78. package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.js +56 -1
  79. package/lib/tests/materialized-reports/materialized-day-input-signature.test.d.ts +1 -0
  80. package/lib/tests/materialized-reports/materialized-day-input-signature.test.js +81 -0
  81. package/lib/tests/materialized-reports/materialized-discount-classification.test.js +17 -0
  82. package/lib/tests/materialized-reports/materialized-discount-close-day.test.js +148 -53
  83. package/lib/tests/materialized-reports/materialized-discount-entries-accumulation.test.js +14 -13
  84. package/lib/tests/materialized-reports/materialized-discount-sources.test.js +76 -0
  85. package/lib/tests/materialized-reports/materialized-integer-contract.test.js +11 -0
  86. package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.js +2 -2
  87. package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +311 -4
  88. package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +89 -0
  89. package/package.json +1 -1
@@ -1,8 +1,9 @@
1
1
  import mongoose from 'mongoose';
2
- import { MATERIALIZED_DISCOUNT_REPORT_SCOPES, MATERIALIZED_REPORT_KEY_FILTER_ENUM, MATERIALIZED_REPORT_SCOPE_ENUM, } from '../../constants/MATERIALIZED_REPORTS';
2
+ import { MATERIALIZED_DISCOUNT_ENTRY_PAGE_ALL, MATERIALIZED_DISCOUNT_REPORT_SCOPES, MATERIALIZED_REPORT_KEY_FILTER_ENUM, MATERIALIZED_REPORT_SCOPE_ENUM, } from '../../constants/MATERIALIZED_REPORTS';
3
3
  import { accumulateOrderDiscounts, toDiscountHourLabel, } from './materialized-discount-accumulator-helpers';
4
4
  import { createEmptyDiscountOrderCounters } from './materialized-discount-classification-helpers';
5
5
  import { buildMaterializedReportKey } from './key-helpers';
6
+ import { buildMaterializedDayInputSignature } from './materialized-day-input-signature';
6
7
  import { getDayIndexFromLocalDate, getMaterializedHourScopeField, getMaterializedPeriodScopeFields, } from './scope-helpers';
7
8
  import { resolveOrderLocalHour } from './materialized-credit-bills-helpers';
8
9
  /** Adds every numeric field of `source` into `target`, recursively. */
@@ -53,6 +54,16 @@ export function compileTenantDiscountReports(input) {
53
54
  if (periodFields == null)
54
55
  return null;
55
56
  const dayIndex = getDayIndexFromLocalDate(localDate);
57
+ // Day-input digest: the discount counter documents are guarded by a
58
+ // watermark that only advances, so deleting / moving the order with the
59
+ // highest `updatedAt` would otherwise skip the correction and leave its
60
+ // discount behind. The digest covers EVERY order the day compiled (a removed
61
+ // non-discount order changes nothing, but rewriting one document is cheaper
62
+ // than a missed correction). Computed once — the same value is stamped on
63
+ // every scope document of the day.
64
+ const sourceInputSignature = buildMaterializedDayInputSignature(orders.filter((order) => order != null &&
65
+ order.is_deleted === false &&
66
+ (order.tenant_id == null || String(order.tenant_id) === tenantId))) ?? undefined;
56
67
  // DERIVED from the report's scope list (as prep / cash / delivery do). This used to be a
57
68
  // second, hand-maintained copy of the same four scopes - so widening the report's scopes
58
69
  // compiled the new ones nowhere and the documents silently never appeared.
@@ -79,6 +90,12 @@ export function compileTenantDiscountReports(input) {
79
90
  for (const order of orders) {
80
91
  if (order == null)
81
92
  continue;
93
+ // DELETED orders never contribute (defence in depth: the worker loader
94
+ // already filters `is_deleted: false`, but the compile is also used by the
95
+ // live adapter and by tests — a deleted order must never re-appear through
96
+ // a caller passing a wider query).
97
+ if (order.is_deleted !== false)
98
+ continue;
82
99
  // Only orders of this tenant compile into this tenant's documents.
83
100
  if (order.tenant_id != null && String(order.tenant_id) !== tenantId)
84
101
  continue;
@@ -154,6 +171,7 @@ export function compileTenantDiscountReports(input) {
154
171
  top_sources: null,
155
172
  schema_version: 1,
156
173
  source_watermark: docWatermark,
174
+ source_input_signature: sourceInputSignature,
157
175
  computed_at: computedAt,
158
176
  createdAt: computedAt,
159
177
  updatedAt: computedAt,
@@ -166,6 +184,7 @@ export function compileTenantDiscountReports(input) {
166
184
  brand_id: brandId,
167
185
  scope_context: scope,
168
186
  scope_field: scopeField,
187
+ page: isDateScoped ? MATERIALIZED_DISCOUNT_ENTRY_PAGE_ALL : localDate,
169
188
  day_index: isDateScoped ? dayIndex : null,
170
189
  sale_type_key_filters: [
171
190
  MATERIALIZED_REPORT_KEY_FILTER_ENUM.ORDER_STATUS,
@@ -423,3 +423,179 @@ export function buildDiscountSourcesForScope(input) {
423
423
  a.source_name.localeCompare(b.source_name) ||
424
424
  a.level.localeCompare(b.level));
425
425
  }
426
+ const sourceDeltaMetrics = (doc) => ({
427
+ order_count: doc.order_count ?? 0,
428
+ row_count: doc.row_count ?? 0,
429
+ discount_amount: doc.discount_amount ?? 0,
430
+ free_item_count: doc.free_item_count ?? 0,
431
+ free_item_value: doc.free_item_value ?? 0,
432
+ covered_amount: doc.covered_amount ?? 0,
433
+ percentage_row_count: doc.percentage_row_count ?? 0,
434
+ percentage_rate_sum: doc.percentage_rate_sum ?? 0,
435
+ fixed_row_count: doc.fixed_row_count ?? 0,
436
+ });
437
+ const applySourceDelta = (target, delta, sign) => {
438
+ for (const key of Object.keys(target)) {
439
+ target[key] += sign * (delta[key] ?? 0);
440
+ if (!Number.isFinite(target[key]) || target[key] < 0)
441
+ return false;
442
+ }
443
+ return true;
444
+ };
445
+ const sourceKindOf = (sourceClass, metrics) => {
446
+ if (sourceClass === MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM.COMPLIMENTARY) {
447
+ return MATERIALIZED_DISCOUNT_ENTRY_KIND_ENUM.COMPLIMENTARY;
448
+ }
449
+ if (metrics.free_item_count > 0 && metrics.free_item_count === metrics.row_count) {
450
+ return MATERIALIZED_DISCOUNT_ENTRY_KIND_ENUM.FREE_ITEM;
451
+ }
452
+ return MATERIALIZED_DISCOUNT_ENTRY_KIND_ENUM.DISCOUNT;
453
+ };
454
+ /**
455
+ * Adds or subtracts one DAY's source contribution from a PERIOD source document.
456
+ *
457
+ * This is the INCREMENTAL source projection: a new close adds the day's
458
+ * contribution; a re-close subtracts the stored day first and adds the fresh
459
+ * one. No period entry rows are read or rebuilt. Returns:
460
+ * - a new document when the source survives;
461
+ * - `null` when the source becomes empty (the caller deletes it);
462
+ * - `null` when the delta cannot be applied safely (negative metrics,
463
+ * identity/schema/scope mismatch) — the caller must fail the close.
464
+ */
465
+ /**
466
+ * Whether `existing` currently contains at least `delta`'s additive metrics
467
+ * (so a subtraction can be applied without going negative).
468
+ */
469
+ export function discountSourceDeltaCovers(existing, delta) {
470
+ if (existing == null || delta == null)
471
+ return false;
472
+ const left = sourceDeltaMetrics(existing);
473
+ const right = sourceDeltaMetrics(delta);
474
+ for (const key of Object.keys(left)) {
475
+ if (left[key] < right[key])
476
+ return false;
477
+ }
478
+ for (const keyMetric of delta.key_metrics ?? []) {
479
+ const current = (existing.key_metrics ?? []).find((entry) => entry.key === keyMetric.key);
480
+ if (current == null)
481
+ return false;
482
+ for (const field of [
483
+ 'order_count',
484
+ 'row_count',
485
+ 'discount_amount',
486
+ 'free_item_count',
487
+ 'free_item_value',
488
+ 'covered_amount',
489
+ 'percentage_row_count',
490
+ 'percentage_rate_sum',
491
+ 'fixed_row_count',
492
+ ]) {
493
+ if ((current[field] ?? 0) < (keyMetric[field] ?? 0))
494
+ return false;
495
+ }
496
+ }
497
+ return true;
498
+ }
499
+ export function applyDiscountSourceDelta(existing, delta, direction, computedAt) {
500
+ if (delta == null)
501
+ return null;
502
+ if (existing == null) {
503
+ if (direction < 0)
504
+ return null;
505
+ return {
506
+ ...delta,
507
+ computed_at: computedAt,
508
+ createdAt: delta.createdAt ?? computedAt,
509
+ updatedAt: computedAt,
510
+ };
511
+ }
512
+ if (existing.tenant_id !== delta.tenant_id ||
513
+ existing.brand_id !== delta.brand_id ||
514
+ existing.scope_context !== delta.scope_context ||
515
+ existing.scope_field !== delta.scope_field ||
516
+ existing.source_key !== delta.source_key ||
517
+ existing.level !== delta.level ||
518
+ existing.schema_version !== delta.schema_version ||
519
+ (existing.sale_type_key_filters ?? []).join(':') !== (delta.sale_type_key_filters ?? []).join(':')) {
520
+ return null;
521
+ }
522
+ const totals = sourceDeltaMetrics(existing);
523
+ if (!applySourceDelta(totals, sourceDeltaMetrics(delta), direction))
524
+ return null;
525
+ const byKey = new Map();
526
+ for (const keyMetric of existing.key_metrics ?? []) {
527
+ byKey.set(keyMetric.key, {
528
+ order_count: keyMetric.order_count,
529
+ row_count: keyMetric.row_count,
530
+ discount_amount: keyMetric.discount_amount,
531
+ free_item_count: keyMetric.free_item_count,
532
+ free_item_value: keyMetric.free_item_value,
533
+ covered_amount: keyMetric.covered_amount,
534
+ percentage_row_count: keyMetric.percentage_row_count,
535
+ percentage_rate_sum: keyMetric.percentage_rate_sum,
536
+ fixed_row_count: keyMetric.fixed_row_count,
537
+ });
538
+ }
539
+ for (const keyMetric of delta.key_metrics ?? []) {
540
+ const current = byKey.get(keyMetric.key) ?? {
541
+ order_count: 0,
542
+ row_count: 0,
543
+ discount_amount: 0,
544
+ free_item_count: 0,
545
+ free_item_value: 0,
546
+ covered_amount: 0,
547
+ percentage_row_count: 0,
548
+ percentage_rate_sum: 0,
549
+ fixed_row_count: 0,
550
+ };
551
+ if (!applySourceDelta(current, {
552
+ order_count: keyMetric.order_count,
553
+ row_count: keyMetric.row_count,
554
+ discount_amount: keyMetric.discount_amount,
555
+ free_item_count: keyMetric.free_item_count,
556
+ free_item_value: keyMetric.free_item_value,
557
+ covered_amount: keyMetric.covered_amount,
558
+ percentage_row_count: keyMetric.percentage_row_count,
559
+ percentage_rate_sum: keyMetric.percentage_rate_sum,
560
+ fixed_row_count: keyMetric.fixed_row_count,
561
+ }, direction)) {
562
+ return null;
563
+ }
564
+ byKey.set(keyMetric.key, current);
565
+ }
566
+ const keyMetrics = [...byKey.entries()]
567
+ .filter(([, metrics]) => Object.values(metrics).some((value) => typeof value === 'number' && value !== 0))
568
+ .sort(([a], [b]) => a.localeCompare(b))
569
+ .map(([key, metrics]) => ({ key, ...metrics }));
570
+ const empty = totals.row_count === 0 &&
571
+ totals.order_count === 0 &&
572
+ totals.discount_amount === 0 &&
573
+ totals.free_item_count === 0 &&
574
+ totals.free_item_value === 0 &&
575
+ totals.covered_amount === 0 &&
576
+ totals.percentage_row_count === 0 &&
577
+ totals.percentage_rate_sum === 0 &&
578
+ totals.fixed_row_count === 0;
579
+ if (empty || keyMetrics.length === 0)
580
+ return null;
581
+ return {
582
+ ...existing,
583
+ kind: sourceKindOf(existing.source_class, totals),
584
+ rate_kind: rateKindOf(totals),
585
+ percentage_row_count: totals.percentage_row_count,
586
+ percentage_rate_sum: totals.percentage_rate_sum,
587
+ fixed_row_count: totals.fixed_row_count,
588
+ order_count: totals.order_count,
589
+ row_count: totals.row_count,
590
+ discount_amount: totals.discount_amount,
591
+ free_item_count: totals.free_item_count,
592
+ free_item_value: totals.free_item_value,
593
+ covered_amount: totals.covered_amount,
594
+ key_metrics: keyMetrics,
595
+ source_watermark: direction > 0
596
+ ? new Date(Math.max(new Date(existing.source_watermark).getTime(), new Date(delta.source_watermark).getTime()))
597
+ : existing.source_watermark,
598
+ computed_at: computedAt,
599
+ updatedAt: computedAt,
600
+ };
601
+ }
@@ -0,0 +1,64 @@
1
+ import { MATERIALIZED_TENANT_CREDIT_BILLS_COLLECTION_NAME, MATERIALIZED_TENANT_CREDIT_BILLS_INDEX_OPTIONS, } from '../../schemas/models/materialized_credit_bills';
2
+ import { MATERIALIZED_TENANT_DISCOUNT_ENTRIES_INDEX_OPTIONS, MATERIALIZED_TENANT_DISCOUNT_ENTRIES_COLLECTION_NAME, } from '../../schemas/models/materialized_tenant_discount_entries';
3
+ import { MATERIALIZED_TENANT_DISCOUNT_REPORTS_INDEX_OPTIONS, MATERIALIZED_TENANT_DISCOUNT_REPORTS_COLLECTION_NAME, } from '../../schemas/models/materialized_tenant_discount_reports';
4
+ import { MATERIALIZED_TENANT_DISCOUNT_SOURCES_INDEX_OPTIONS, MATERIALIZED_TENANT_DISCOUNT_SOURCES_COLLECTION_NAME, } from '../../schemas/models/materialized_tenant_discount_sources';
5
+ import { MATERIALIZED_TENANT_REPORTS_ITERATIONS_COLLECTION_NAME, MATERIALIZED_TENANT_REPORTS_ITERATIONS_INDEX_OPTIONS, } from '../../schemas/models/materialized_tenant_reports_iterations';
6
+ import { MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_COLLECTION_NAME, MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_INDEX_OPTIONS, } from '../../schemas/models/materialized_tenant_sales_overview_reports';
7
+ import { MATERIALIZED_REPORT_DRILLDOWN_ROWS_COLLECTION_NAME, MATERIALIZED_REPORT_DRILLDOWN_ROWS_INDEX_OPTIONS, MATERIALIZED_REPORT_DRILLDOWN_SCOPES_COLLECTION_NAME, MATERIALIZED_REPORT_DRILLDOWN_SCOPES_INDEX_OPTIONS, } from '../../schemas/models/materialized_report_drilldown_rows';
8
+ import { TENANT_CALENDAR_COLLECTION_NAME, TENANT_CALENDAR_INDEX_OPTIONS } from '../../schemas/models/tenant_calendar';
9
+ /**
10
+ * BOOTSTRAP the indexes the materialized reads/writes assume.
11
+ *
12
+ * The services run with `autoIndex: false`, and the model schemas deliberately
13
+ * do not declare these compound indexes. Until now the only creator was a
14
+ * manual simulation script; a fresh deployment therefore failed every
15
+ * `.hint()` read and could create duplicate scope/year documents. This helper
16
+ * is called after `mongoose.connect` by items/workers/operations and fails the
17
+ * startup if an expected unique index is missing afterwards.
18
+ *
19
+ * It creates indexes with `createIndexes` (never drops unrelated indexes).
20
+ */
21
+ const INDEXES = {
22
+ [MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_COLLECTION_NAME]: MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_INDEX_OPTIONS,
23
+ [MATERIALIZED_TENANT_CREDIT_BILLS_COLLECTION_NAME]: MATERIALIZED_TENANT_CREDIT_BILLS_INDEX_OPTIONS,
24
+ [MATERIALIZED_TENANT_DISCOUNT_REPORTS_COLLECTION_NAME]: MATERIALIZED_TENANT_DISCOUNT_REPORTS_INDEX_OPTIONS,
25
+ [MATERIALIZED_TENANT_DISCOUNT_ENTRIES_COLLECTION_NAME]: MATERIALIZED_TENANT_DISCOUNT_ENTRIES_INDEX_OPTIONS,
26
+ [MATERIALIZED_TENANT_DISCOUNT_SOURCES_COLLECTION_NAME]: MATERIALIZED_TENANT_DISCOUNT_SOURCES_INDEX_OPTIONS,
27
+ [MATERIALIZED_TENANT_REPORTS_ITERATIONS_COLLECTION_NAME]: MATERIALIZED_TENANT_REPORTS_ITERATIONS_INDEX_OPTIONS,
28
+ [MATERIALIZED_REPORT_DRILLDOWN_ROWS_COLLECTION_NAME]: MATERIALIZED_REPORT_DRILLDOWN_ROWS_INDEX_OPTIONS,
29
+ [MATERIALIZED_REPORT_DRILLDOWN_SCOPES_COLLECTION_NAME]: MATERIALIZED_REPORT_DRILLDOWN_SCOPES_INDEX_OPTIONS,
30
+ [TENANT_CALENDAR_COLLECTION_NAME]: TENANT_CALENDAR_INDEX_OPTIONS,
31
+ };
32
+ export const MATERIALIZED_REPORT_INDEX_COLLECTIONS = Object.keys(INDEXES);
33
+ export async function ensureMaterializedReportIndexes(connection, options = {}) {
34
+ const db = connection.db;
35
+ if (db == null)
36
+ throw new Error('ensureMaterializedReportIndexes: no database connection');
37
+ const collections = options.collections ?? MATERIALIZED_REPORT_INDEX_COLLECTIONS;
38
+ for (const collectionName of collections) {
39
+ const definitions = INDEXES[collectionName];
40
+ if (definitions == null) {
41
+ throw new Error('ensureMaterializedReportIndexes: unknown collection ' + collectionName);
42
+ }
43
+ const collection = db.collection(collectionName);
44
+ const indexes = definitions.filter((definition) => definition.name !== '_id_');
45
+ try {
46
+ await collection.createIndexes(indexes);
47
+ }
48
+ catch (error) {
49
+ throw new Error('ensureMaterializedReportIndexes: failed to create indexes for ' +
50
+ collectionName +
51
+ ': ' +
52
+ (error instanceof Error ? error.message : String(error)));
53
+ }
54
+ const existing = await collection.listIndexes().toArray();
55
+ const names = new Set(existing.map((index) => index.name));
56
+ const missing = indexes.filter((index) => !names.has(index.name));
57
+ if (missing.length > 0) {
58
+ throw new Error('ensureMaterializedReportIndexes: ' +
59
+ collectionName +
60
+ ' is missing expected indexes ' +
61
+ missing.map((index) => index.name).join(', '));
62
+ }
63
+ }
64
+ }
@@ -43,21 +43,43 @@ const IDENTIFIER_FIELD = /^(scope_field|day_index|key|_id|.*_id)$/;
43
43
  * integer contract applies to money/rate/count/duration leaves. Only reject a
44
44
  * numeric-looking string when it sits in a field that is not one of these.
45
45
  */
46
- const TEXT_FIELD = /(name|label|title|reason|note|description|reference|code|currency|platform|status|type|source_key|order_number)$/i;
46
+ const TEXT_FIELD = /(name|label|title|reason|note|description|reference|reference_number|code|currency|platform|status|type|source_key|order_number)$/i;
47
47
  /**
48
- * Mongo ObjectId / BSON values are identity, not numbers.
48
+ * BSON values: only IDENTITY types are ignored. A numeric BSON value
49
+ * (Decimal128 / Long / Double / Int32) is storage of a number and must obey the
50
+ * same integer contract as a JS number — otherwise a Decimal128 decimal would
51
+ * bypass the validator entirely.
49
52
  *
50
53
  * Duck-typed on `_bsontype` so the toolkit keeps no mongoose dependency
51
54
  * (it is published to the frontends too).
52
55
  */
53
- const isBsonLike = (value) => typeof value === 'object' && value !== null && typeof value._bsontype === 'string';
56
+ const BSON_NUMERIC_TYPES = new Set([
57
+ 'Decimal128',
58
+ 'Long',
59
+ 'Double',
60
+ 'Int32',
61
+ 'NumberDecimal',
62
+ 'NumberDouble',
63
+ 'NumberLong',
64
+ 'NumberInt',
65
+ ]);
66
+ const getBsonType = (value) => {
67
+ if (typeof value !== 'object' || value === null)
68
+ return null;
69
+ const type = value._bsontype;
70
+ return typeof type === 'string' ? type : null;
71
+ };
72
+ const isBsonNumeric = (value) => {
73
+ const type = getBsonType(value);
74
+ return type != null && BSON_NUMERIC_TYPES.has(type);
75
+ };
54
76
  /** Dates, buffers and other non-numeric leaves are ignored. */
55
77
  const isIgnoredLeaf = (value) => value === null ||
56
78
  typeof value === 'boolean' ||
57
79
  value instanceof Date ||
58
80
  value instanceof RegExp ||
59
81
  (typeof Buffer !== 'undefined' && Buffer.isBuffer(value)) ||
60
- isBsonLike(value);
82
+ (getBsonType(value) != null && !isBsonNumeric(value));
61
83
  const childPath = (parent, key) => (parent.length === 0 ? key : `${parent}.${key}`);
62
84
  /**
63
85
  * Collects every numeric leaf that violates the integer-only contract.
@@ -73,6 +95,10 @@ export function findNonIntegerNumericLeaves(document) {
73
95
  const walk = (node, path) => {
74
96
  if (node === undefined)
75
97
  return;
98
+ if (isBsonNumeric(node)) {
99
+ violations.push({ path, value: node, reason: 'bson-numeric' });
100
+ return;
101
+ }
76
102
  if (isIgnoredLeaf(node))
77
103
  return;
78
104
  if (typeof node === 'number') {
@@ -66,7 +66,7 @@ export const getDrilldownRowsKey = (reportType) => ROW_SPECS[reportType].rowsKey
66
66
  * usable time anchor are skipped and counted; the writer can decide whether to
67
67
  * fail loudly.
68
68
  */
69
- export function buildMaterializedDrilldownRows(reportType, document) {
69
+ export function buildMaterializedDrilldownRows(reportType, document, sourceLocalDate = null) {
70
70
  if (document == null)
71
71
  return { rows: [], skipped: 0 };
72
72
  const spec = ROW_SPECS[reportType];
@@ -117,6 +117,7 @@ export function buildMaterializedDrilldownRows(reportType, document) {
117
117
  cursor_id: cursorId,
118
118
  time,
119
119
  data: row,
120
+ source_local_date: sourceLocalDate,
120
121
  schema_version: MATERIALIZED_REPORT_DRILLDOWN_ROWS_SCHEMA_VERSION,
121
122
  computed_at: computedAt,
122
123
  });
@@ -136,7 +137,7 @@ export function buildMaterializedDrilldownRowsFromDocuments(reportType, document
136
137
  return { rows, skipped };
137
138
  }
138
139
  /** Scope metadata (row count + delivery off-app count) for the flat reader. */
139
- export function buildMaterializedDrilldownScope(reportType, document, rows) {
140
+ export function buildMaterializedDrilldownScope(reportType, document, rows, sourceLocalDate = null) {
140
141
  if (document == null)
141
142
  return null;
142
143
  const tenantId = asString(document.tenant_id);
@@ -156,6 +157,7 @@ export function buildMaterializedDrilldownScope(reportType, document, rows) {
156
157
  scope_field: scopeField,
157
158
  row_count: rows.length,
158
159
  off_app_order_count: offApp,
160
+ source_local_date: sourceLocalDate,
159
161
  schema_version: MATERIALIZED_REPORT_DRILLDOWN_ROWS_SCHEMA_VERSION,
160
162
  computed_at: toDate(document.computed_at) ?? new Date(),
161
163
  };
@@ -640,6 +640,13 @@ const decodeMaterializedReportScopeGroups = (selection) => {
640
640
  // never disagree.
641
641
  const window = resolveTimeOfDayWindow(selection);
642
642
  const weekdayFilter = getActiveWeekdayFilter(selection.weekdays);
643
+ // A half-set / invalid / unservable time window must NEVER silently fall
644
+ // through to the full period: the caller asked for a time refinement, so an
645
+ // unresolvable one is an invalid selection (the read parser turns this null
646
+ // into a 400).
647
+ if ((selection.timeStart != null || selection.timeEnd != null) && window == null) {
648
+ return null;
649
+ }
643
650
  if (window != null || weekdayFilter != null) {
644
651
  const days = getDayKeysFromCalendarSelection(selection);
645
652
  if (days.length === 0)
@@ -105,3 +105,30 @@ export function getMaterializedHourScopeField(localDate, hour) {
105
105
  return null;
106
106
  return `${localDate} ${pad(hour)}`;
107
107
  }
108
+ /**
109
+ * The `scope_field` RANGE a close must scan to find every stored `localDate`
110
+ * document that can share a period with `localDate` — used to REPAIR a missing
111
+ * period document from its sibling days (a period is a running sum; creating it
112
+ * from the closing day alone would make it disagree with the sum of the day
113
+ * documents).
114
+ *
115
+ * This is a deliberately generous SUPERSET: the ISO week / calendar week of a
116
+ * date can start in the previous calendar year (e.g. `2027-01-01` belongs to
117
+ * `2026-W53`), and the calendar week can extend into the next one. Membership
118
+ * is decided afterwards by comparing each candidate's
119
+ * `getMaterializedPeriodScopeFields` / scope refs to the created period; the
120
+ * range only bounds the query (one indexed range scan, no `$in` of 366 keys).
121
+ *
122
+ * Returns `null` (never throws) for a malformed date.
123
+ */
124
+ export function getMaterializedPeriodDayScopeRange(localDate) {
125
+ const parts = parseMaterializedLocalDate(localDate);
126
+ if (parts == null)
127
+ return null;
128
+ const { year } = parts;
129
+ const toKey = (date) => `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}`;
130
+ return {
131
+ gte: toKey(new Date(Date.UTC(year, 0, 1 - 7))),
132
+ lte: toKey(new Date(Date.UTC(year, 11, 31 + 7))),
133
+ };
134
+ }