@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
@@ -8,16 +8,16 @@ import { IMaterializedTenantDiscountReport } from '../../schemas/types/materiali
8
8
  *
9
9
  * - `materialized_tenant_discount_reports` — COUNTERS per key per scope,
10
10
  * - `materialized_tenant_discount_entries` — the drill-down ROWS per key per
11
- * scope (month-capped, like the credit ledger).
11
+ * scope, PAGE-PARTITIONED by source day. Day/hour pages are `'all'`; period
12
+ * pages are the compiled `localDate`, so no period document accumulates every
13
+ * day.
12
14
  *
13
15
  * Both come from ONE pass of the accumulator, so a document's counters and its
14
16
  * rows can never disagree.
15
17
  *
16
18
  * Scope fan-out: an order contributes to its punch HOUR, the DATE, the WEEK,
17
19
  * the ISO WEEK-OF-YEAR and the MONTH — exactly `MATERIALIZED_DISCOUNT_REPORT_SCOPES`.
18
- * Quarter / semester / year are deliberately NOT materialized: period ENTRY
19
- * documents accumulate their days' rows, so a wider scope would grow without a
20
- * natural bound (see the constant's comment).
20
+ * Wider period scopes are supported by the page rule if enabled later.
21
21
  *
22
22
  * Pure and total: `null` on malformed input, never a throw.
23
23
  */
@@ -10,6 +10,7 @@ const MATERIALIZED_REPORTS_1 = require("../../constants/MATERIALIZED_REPORTS");
10
10
  const materialized_discount_accumulator_helpers_1 = require("./materialized-discount-accumulator-helpers");
11
11
  const materialized_discount_classification_helpers_1 = require("./materialized-discount-classification-helpers");
12
12
  const key_helpers_1 = require("./key-helpers");
13
+ const materialized_day_input_signature_1 = require("./materialized-day-input-signature");
13
14
  const scope_helpers_1 = require("./scope-helpers");
14
15
  const materialized_credit_bills_helpers_1 = require("./materialized-credit-bills-helpers");
15
16
  /** Adds every numeric field of `source` into `target`, recursively. */
@@ -60,6 +61,16 @@ function compileTenantDiscountReports(input) {
60
61
  if (periodFields == null)
61
62
  return null;
62
63
  const dayIndex = (0, scope_helpers_1.getDayIndexFromLocalDate)(localDate);
64
+ // Day-input digest: the discount counter documents are guarded by a
65
+ // watermark that only advances, so deleting / moving the order with the
66
+ // highest `updatedAt` would otherwise skip the correction and leave its
67
+ // discount behind. The digest covers EVERY order the day compiled (a removed
68
+ // non-discount order changes nothing, but rewriting one document is cheaper
69
+ // than a missed correction). Computed once — the same value is stamped on
70
+ // every scope document of the day.
71
+ const sourceInputSignature = (0, materialized_day_input_signature_1.buildMaterializedDayInputSignature)(orders.filter((order) => order != null &&
72
+ order.is_deleted === false &&
73
+ (order.tenant_id == null || String(order.tenant_id) === tenantId))) ?? undefined;
63
74
  // DERIVED from the report's scope list (as prep / cash / delivery do). This used to be a
64
75
  // second, hand-maintained copy of the same four scopes - so widening the report's scopes
65
76
  // compiled the new ones nowhere and the documents silently never appeared.
@@ -86,6 +97,12 @@ function compileTenantDiscountReports(input) {
86
97
  for (const order of orders) {
87
98
  if (order == null)
88
99
  continue;
100
+ // DELETED orders never contribute (defence in depth: the worker loader
101
+ // already filters `is_deleted: false`, but the compile is also used by the
102
+ // live adapter and by tests — a deleted order must never re-appear through
103
+ // a caller passing a wider query).
104
+ if (order.is_deleted !== false)
105
+ continue;
89
106
  // Only orders of this tenant compile into this tenant's documents.
90
107
  if (order.tenant_id != null && String(order.tenant_id) !== tenantId)
91
108
  continue;
@@ -161,6 +178,7 @@ function compileTenantDiscountReports(input) {
161
178
  top_sources: null,
162
179
  schema_version: 1,
163
180
  source_watermark: docWatermark,
181
+ source_input_signature: sourceInputSignature,
164
182
  computed_at: computedAt,
165
183
  createdAt: computedAt,
166
184
  updatedAt: computedAt,
@@ -173,6 +191,7 @@ function compileTenantDiscountReports(input) {
173
191
  brand_id: brandId,
174
192
  scope_context: scope,
175
193
  scope_field: scopeField,
194
+ page: isDateScoped ? MATERIALIZED_REPORTS_1.MATERIALIZED_DISCOUNT_ENTRY_PAGE_ALL : localDate,
176
195
  day_index: isDateScoped ? dayIndex : null,
177
196
  sale_type_key_filters: [
178
197
  MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_KEY_FILTER_ENUM.ORDER_STATUS,
@@ -71,3 +71,20 @@ export interface IBuildDiscountSourcesInput {
71
71
  * that scope). Returns `null` on malformed input.
72
72
  */
73
73
  export declare function buildDiscountSourcesForScope(input: IBuildDiscountSourcesInput | null | undefined): IMaterializedTenantDiscountSource[] | null;
74
+ /**
75
+ * Adds or subtracts one DAY's source contribution from a PERIOD source document.
76
+ *
77
+ * This is the INCREMENTAL source projection: a new close adds the day's
78
+ * contribution; a re-close subtracts the stored day first and adds the fresh
79
+ * one. No period entry rows are read or rebuilt. Returns:
80
+ * - a new document when the source survives;
81
+ * - `null` when the source becomes empty (the caller deletes it);
82
+ * - `null` when the delta cannot be applied safely (negative metrics,
83
+ * identity/schema/scope mismatch) — the caller must fail the close.
84
+ */
85
+ /**
86
+ * Whether `existing` currently contains at least `delta`'s additive metrics
87
+ * (so a subtraction can be applied without going negative).
88
+ */
89
+ export declare function discountSourceDeltaCovers(existing: IMaterializedTenantDiscountSource | null, delta: IMaterializedTenantDiscountSource): boolean;
90
+ export declare function applyDiscountSourceDelta(existing: IMaterializedTenantDiscountSource | null, delta: IMaterializedTenantDiscountSource, direction: 1 | -1, computedAt: Date): IMaterializedTenantDiscountSource | null;
@@ -7,6 +7,8 @@ exports.normalizeDiscountSourceKeyPart = normalizeDiscountSourceKeyPart;
7
7
  exports.getPaymentTypeFromDiscountReason = getPaymentTypeFromDiscountReason;
8
8
  exports.classifyDiscountEntrySource = classifyDiscountEntrySource;
9
9
  exports.buildDiscountSourcesForScope = buildDiscountSourcesForScope;
10
+ exports.discountSourceDeltaCovers = discountSourceDeltaCovers;
11
+ exports.applyDiscountSourceDelta = applyDiscountSourceDelta;
10
12
  const mongoose_1 = __importDefault(require("mongoose"));
11
13
  const MATERIALIZED_REPORTS_1 = require("../../constants/MATERIALIZED_REPORTS");
12
14
  const materialized_tenant_discount_sources_1 = require("../../schemas/models/materialized_tenant_discount_sources");
@@ -432,3 +434,179 @@ function buildDiscountSourcesForScope(input) {
432
434
  a.source_name.localeCompare(b.source_name) ||
433
435
  a.level.localeCompare(b.level));
434
436
  }
437
+ const sourceDeltaMetrics = (doc) => ({
438
+ order_count: doc.order_count ?? 0,
439
+ row_count: doc.row_count ?? 0,
440
+ discount_amount: doc.discount_amount ?? 0,
441
+ free_item_count: doc.free_item_count ?? 0,
442
+ free_item_value: doc.free_item_value ?? 0,
443
+ covered_amount: doc.covered_amount ?? 0,
444
+ percentage_row_count: doc.percentage_row_count ?? 0,
445
+ percentage_rate_sum: doc.percentage_rate_sum ?? 0,
446
+ fixed_row_count: doc.fixed_row_count ?? 0,
447
+ });
448
+ const applySourceDelta = (target, delta, sign) => {
449
+ for (const key of Object.keys(target)) {
450
+ target[key] += sign * (delta[key] ?? 0);
451
+ if (!Number.isFinite(target[key]) || target[key] < 0)
452
+ return false;
453
+ }
454
+ return true;
455
+ };
456
+ const sourceKindOf = (sourceClass, metrics) => {
457
+ if (sourceClass === MATERIALIZED_REPORTS_1.MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM.COMPLIMENTARY) {
458
+ return MATERIALIZED_REPORTS_1.MATERIALIZED_DISCOUNT_ENTRY_KIND_ENUM.COMPLIMENTARY;
459
+ }
460
+ if (metrics.free_item_count > 0 && metrics.free_item_count === metrics.row_count) {
461
+ return MATERIALIZED_REPORTS_1.MATERIALIZED_DISCOUNT_ENTRY_KIND_ENUM.FREE_ITEM;
462
+ }
463
+ return MATERIALIZED_REPORTS_1.MATERIALIZED_DISCOUNT_ENTRY_KIND_ENUM.DISCOUNT;
464
+ };
465
+ /**
466
+ * Adds or subtracts one DAY's source contribution from a PERIOD source document.
467
+ *
468
+ * This is the INCREMENTAL source projection: a new close adds the day's
469
+ * contribution; a re-close subtracts the stored day first and adds the fresh
470
+ * one. No period entry rows are read or rebuilt. Returns:
471
+ * - a new document when the source survives;
472
+ * - `null` when the source becomes empty (the caller deletes it);
473
+ * - `null` when the delta cannot be applied safely (negative metrics,
474
+ * identity/schema/scope mismatch) — the caller must fail the close.
475
+ */
476
+ /**
477
+ * Whether `existing` currently contains at least `delta`'s additive metrics
478
+ * (so a subtraction can be applied without going negative).
479
+ */
480
+ function discountSourceDeltaCovers(existing, delta) {
481
+ if (existing == null || delta == null)
482
+ return false;
483
+ const left = sourceDeltaMetrics(existing);
484
+ const right = sourceDeltaMetrics(delta);
485
+ for (const key of Object.keys(left)) {
486
+ if (left[key] < right[key])
487
+ return false;
488
+ }
489
+ for (const keyMetric of delta.key_metrics ?? []) {
490
+ const current = (existing.key_metrics ?? []).find((entry) => entry.key === keyMetric.key);
491
+ if (current == null)
492
+ return false;
493
+ for (const field of [
494
+ 'order_count',
495
+ 'row_count',
496
+ 'discount_amount',
497
+ 'free_item_count',
498
+ 'free_item_value',
499
+ 'covered_amount',
500
+ 'percentage_row_count',
501
+ 'percentage_rate_sum',
502
+ 'fixed_row_count',
503
+ ]) {
504
+ if ((current[field] ?? 0) < (keyMetric[field] ?? 0))
505
+ return false;
506
+ }
507
+ }
508
+ return true;
509
+ }
510
+ function applyDiscountSourceDelta(existing, delta, direction, computedAt) {
511
+ if (delta == null)
512
+ return null;
513
+ if (existing == null) {
514
+ if (direction < 0)
515
+ return null;
516
+ return {
517
+ ...delta,
518
+ computed_at: computedAt,
519
+ createdAt: delta.createdAt ?? computedAt,
520
+ updatedAt: computedAt,
521
+ };
522
+ }
523
+ if (existing.tenant_id !== delta.tenant_id ||
524
+ existing.brand_id !== delta.brand_id ||
525
+ existing.scope_context !== delta.scope_context ||
526
+ existing.scope_field !== delta.scope_field ||
527
+ existing.source_key !== delta.source_key ||
528
+ existing.level !== delta.level ||
529
+ existing.schema_version !== delta.schema_version ||
530
+ (existing.sale_type_key_filters ?? []).join(':') !== (delta.sale_type_key_filters ?? []).join(':')) {
531
+ return null;
532
+ }
533
+ const totals = sourceDeltaMetrics(existing);
534
+ if (!applySourceDelta(totals, sourceDeltaMetrics(delta), direction))
535
+ return null;
536
+ const byKey = new Map();
537
+ for (const keyMetric of existing.key_metrics ?? []) {
538
+ byKey.set(keyMetric.key, {
539
+ order_count: keyMetric.order_count,
540
+ row_count: keyMetric.row_count,
541
+ discount_amount: keyMetric.discount_amount,
542
+ free_item_count: keyMetric.free_item_count,
543
+ free_item_value: keyMetric.free_item_value,
544
+ covered_amount: keyMetric.covered_amount,
545
+ percentage_row_count: keyMetric.percentage_row_count,
546
+ percentage_rate_sum: keyMetric.percentage_rate_sum,
547
+ fixed_row_count: keyMetric.fixed_row_count,
548
+ });
549
+ }
550
+ for (const keyMetric of delta.key_metrics ?? []) {
551
+ const current = byKey.get(keyMetric.key) ?? {
552
+ order_count: 0,
553
+ row_count: 0,
554
+ discount_amount: 0,
555
+ free_item_count: 0,
556
+ free_item_value: 0,
557
+ covered_amount: 0,
558
+ percentage_row_count: 0,
559
+ percentage_rate_sum: 0,
560
+ fixed_row_count: 0,
561
+ };
562
+ if (!applySourceDelta(current, {
563
+ order_count: keyMetric.order_count,
564
+ row_count: keyMetric.row_count,
565
+ discount_amount: keyMetric.discount_amount,
566
+ free_item_count: keyMetric.free_item_count,
567
+ free_item_value: keyMetric.free_item_value,
568
+ covered_amount: keyMetric.covered_amount,
569
+ percentage_row_count: keyMetric.percentage_row_count,
570
+ percentage_rate_sum: keyMetric.percentage_rate_sum,
571
+ fixed_row_count: keyMetric.fixed_row_count,
572
+ }, direction)) {
573
+ return null;
574
+ }
575
+ byKey.set(keyMetric.key, current);
576
+ }
577
+ const keyMetrics = [...byKey.entries()]
578
+ .filter(([, metrics]) => Object.values(metrics).some((value) => typeof value === 'number' && value !== 0))
579
+ .sort(([a], [b]) => a.localeCompare(b))
580
+ .map(([key, metrics]) => ({ key, ...metrics }));
581
+ const empty = totals.row_count === 0 &&
582
+ totals.order_count === 0 &&
583
+ totals.discount_amount === 0 &&
584
+ totals.free_item_count === 0 &&
585
+ totals.free_item_value === 0 &&
586
+ totals.covered_amount === 0 &&
587
+ totals.percentage_row_count === 0 &&
588
+ totals.percentage_rate_sum === 0 &&
589
+ totals.fixed_row_count === 0;
590
+ if (empty || keyMetrics.length === 0)
591
+ return null;
592
+ return {
593
+ ...existing,
594
+ kind: sourceKindOf(existing.source_class, totals),
595
+ rate_kind: rateKindOf(totals),
596
+ percentage_row_count: totals.percentage_row_count,
597
+ percentage_rate_sum: totals.percentage_rate_sum,
598
+ fixed_row_count: totals.fixed_row_count,
599
+ order_count: totals.order_count,
600
+ row_count: totals.row_count,
601
+ discount_amount: totals.discount_amount,
602
+ free_item_count: totals.free_item_count,
603
+ free_item_value: totals.free_item_value,
604
+ covered_amount: totals.covered_amount,
605
+ key_metrics: keyMetrics,
606
+ source_watermark: direction > 0
607
+ ? new Date(Math.max(new Date(existing.source_watermark).getTime(), new Date(delta.source_watermark).getTime()))
608
+ : existing.source_watermark,
609
+ computed_at: computedAt,
610
+ updatedAt: computedAt,
611
+ };
612
+ }
@@ -0,0 +1,7 @@
1
+ import type { Connection } from 'mongoose';
2
+ export declare const MATERIALIZED_REPORT_INDEX_COLLECTIONS: string[];
3
+ export interface IEnsureMaterializedReportIndexesOptions {
4
+ /** Restrict to these collections (e.g. items-service only needs tenant_calendar). */
5
+ collections?: readonly string[];
6
+ }
7
+ export declare function ensureMaterializedReportIndexes(connection: Connection, options?: IEnsureMaterializedReportIndexesOptions): Promise<void>;
@@ -0,0 +1,68 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.MATERIALIZED_REPORT_INDEX_COLLECTIONS = void 0;
4
+ exports.ensureMaterializedReportIndexes = ensureMaterializedReportIndexes;
5
+ const materialized_credit_bills_1 = require("../../schemas/models/materialized_credit_bills");
6
+ const materialized_tenant_discount_entries_1 = require("../../schemas/models/materialized_tenant_discount_entries");
7
+ const materialized_tenant_discount_reports_1 = require("../../schemas/models/materialized_tenant_discount_reports");
8
+ const materialized_tenant_discount_sources_1 = require("../../schemas/models/materialized_tenant_discount_sources");
9
+ const materialized_tenant_reports_iterations_1 = require("../../schemas/models/materialized_tenant_reports_iterations");
10
+ const materialized_tenant_sales_overview_reports_1 = require("../../schemas/models/materialized_tenant_sales_overview_reports");
11
+ const materialized_report_drilldown_rows_1 = require("../../schemas/models/materialized_report_drilldown_rows");
12
+ const tenant_calendar_1 = require("../../schemas/models/tenant_calendar");
13
+ /**
14
+ * BOOTSTRAP the indexes the materialized reads/writes assume.
15
+ *
16
+ * The services run with `autoIndex: false`, and the model schemas deliberately
17
+ * do not declare these compound indexes. Until now the only creator was a
18
+ * manual simulation script; a fresh deployment therefore failed every
19
+ * `.hint()` read and could create duplicate scope/year documents. This helper
20
+ * is called after `mongoose.connect` by items/workers/operations and fails the
21
+ * startup if an expected unique index is missing afterwards.
22
+ *
23
+ * It creates indexes with `createIndexes` (never drops unrelated indexes).
24
+ */
25
+ const INDEXES = {
26
+ [materialized_tenant_sales_overview_reports_1.MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_COLLECTION_NAME]: materialized_tenant_sales_overview_reports_1.MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_INDEX_OPTIONS,
27
+ [materialized_credit_bills_1.MATERIALIZED_TENANT_CREDIT_BILLS_COLLECTION_NAME]: materialized_credit_bills_1.MATERIALIZED_TENANT_CREDIT_BILLS_INDEX_OPTIONS,
28
+ [materialized_tenant_discount_reports_1.MATERIALIZED_TENANT_DISCOUNT_REPORTS_COLLECTION_NAME]: materialized_tenant_discount_reports_1.MATERIALIZED_TENANT_DISCOUNT_REPORTS_INDEX_OPTIONS,
29
+ [materialized_tenant_discount_entries_1.MATERIALIZED_TENANT_DISCOUNT_ENTRIES_COLLECTION_NAME]: materialized_tenant_discount_entries_1.MATERIALIZED_TENANT_DISCOUNT_ENTRIES_INDEX_OPTIONS,
30
+ [materialized_tenant_discount_sources_1.MATERIALIZED_TENANT_DISCOUNT_SOURCES_COLLECTION_NAME]: materialized_tenant_discount_sources_1.MATERIALIZED_TENANT_DISCOUNT_SOURCES_INDEX_OPTIONS,
31
+ [materialized_tenant_reports_iterations_1.MATERIALIZED_TENANT_REPORTS_ITERATIONS_COLLECTION_NAME]: materialized_tenant_reports_iterations_1.MATERIALIZED_TENANT_REPORTS_ITERATIONS_INDEX_OPTIONS,
32
+ [materialized_report_drilldown_rows_1.MATERIALIZED_REPORT_DRILLDOWN_ROWS_COLLECTION_NAME]: materialized_report_drilldown_rows_1.MATERIALIZED_REPORT_DRILLDOWN_ROWS_INDEX_OPTIONS,
33
+ [materialized_report_drilldown_rows_1.MATERIALIZED_REPORT_DRILLDOWN_SCOPES_COLLECTION_NAME]: materialized_report_drilldown_rows_1.MATERIALIZED_REPORT_DRILLDOWN_SCOPES_INDEX_OPTIONS,
34
+ [tenant_calendar_1.TENANT_CALENDAR_COLLECTION_NAME]: tenant_calendar_1.TENANT_CALENDAR_INDEX_OPTIONS,
35
+ };
36
+ exports.MATERIALIZED_REPORT_INDEX_COLLECTIONS = Object.keys(INDEXES);
37
+ async function ensureMaterializedReportIndexes(connection, options = {}) {
38
+ const db = connection.db;
39
+ if (db == null)
40
+ throw new Error('ensureMaterializedReportIndexes: no database connection');
41
+ const collections = options.collections ?? exports.MATERIALIZED_REPORT_INDEX_COLLECTIONS;
42
+ for (const collectionName of collections) {
43
+ const definitions = INDEXES[collectionName];
44
+ if (definitions == null) {
45
+ throw new Error('ensureMaterializedReportIndexes: unknown collection ' + collectionName);
46
+ }
47
+ const collection = db.collection(collectionName);
48
+ const indexes = definitions.filter((definition) => definition.name !== '_id_');
49
+ try {
50
+ await collection.createIndexes(indexes);
51
+ }
52
+ catch (error) {
53
+ throw new Error('ensureMaterializedReportIndexes: failed to create indexes for ' +
54
+ collectionName +
55
+ ': ' +
56
+ (error instanceof Error ? error.message : String(error)));
57
+ }
58
+ const existing = await collection.listIndexes().toArray();
59
+ const names = new Set(existing.map((index) => index.name));
60
+ const missing = indexes.filter((index) => !names.has(index.name));
61
+ if (missing.length > 0) {
62
+ throw new Error('ensureMaterializedReportIndexes: ' +
63
+ collectionName +
64
+ ' is missing expected indexes ' +
65
+ missing.map((index) => index.name).join(', '));
66
+ }
67
+ }
68
+ }
@@ -31,7 +31,9 @@ export type TMaterializedNumericViolationReason =
31
31
  /** `NaN` / `Infinity` / `-Infinity`. */
32
32
  | 'non-finite'
33
33
  /** A numeric string (`'131.25'`) — a decimal smuggled in as text. */
34
- | 'numeric-string';
34
+ | 'numeric-string'
35
+ /** A BSON numeric value (Decimal128 / Long / Double / Int32) — not a JS integer. */
36
+ | 'bson-numeric';
35
37
  export interface IMaterializedNumericViolation {
36
38
  /** Dotted path of the offending leaf (`discount_counters.X.payments[].amount`). */
37
39
  path: string;
@@ -48,21 +48,43 @@ const IDENTIFIER_FIELD = /^(scope_field|day_index|key|_id|.*_id)$/;
48
48
  * integer contract applies to money/rate/count/duration leaves. Only reject a
49
49
  * numeric-looking string when it sits in a field that is not one of these.
50
50
  */
51
- const TEXT_FIELD = /(name|label|title|reason|note|description|reference|code|currency|platform|status|type|source_key|order_number)$/i;
51
+ const TEXT_FIELD = /(name|label|title|reason|note|description|reference|reference_number|code|currency|platform|status|type|source_key|order_number)$/i;
52
52
  /**
53
- * Mongo ObjectId / BSON values are identity, not numbers.
53
+ * BSON values: only IDENTITY types are ignored. A numeric BSON value
54
+ * (Decimal128 / Long / Double / Int32) is storage of a number and must obey the
55
+ * same integer contract as a JS number — otherwise a Decimal128 decimal would
56
+ * bypass the validator entirely.
54
57
  *
55
58
  * Duck-typed on `_bsontype` so the toolkit keeps no mongoose dependency
56
59
  * (it is published to the frontends too).
57
60
  */
58
- const isBsonLike = (value) => typeof value === 'object' && value !== null && typeof value._bsontype === 'string';
61
+ const BSON_NUMERIC_TYPES = new Set([
62
+ 'Decimal128',
63
+ 'Long',
64
+ 'Double',
65
+ 'Int32',
66
+ 'NumberDecimal',
67
+ 'NumberDouble',
68
+ 'NumberLong',
69
+ 'NumberInt',
70
+ ]);
71
+ const getBsonType = (value) => {
72
+ if (typeof value !== 'object' || value === null)
73
+ return null;
74
+ const type = value._bsontype;
75
+ return typeof type === 'string' ? type : null;
76
+ };
77
+ const isBsonNumeric = (value) => {
78
+ const type = getBsonType(value);
79
+ return type != null && BSON_NUMERIC_TYPES.has(type);
80
+ };
59
81
  /** Dates, buffers and other non-numeric leaves are ignored. */
60
82
  const isIgnoredLeaf = (value) => value === null ||
61
83
  typeof value === 'boolean' ||
62
84
  value instanceof Date ||
63
85
  value instanceof RegExp ||
64
86
  (typeof Buffer !== 'undefined' && Buffer.isBuffer(value)) ||
65
- isBsonLike(value);
87
+ (getBsonType(value) != null && !isBsonNumeric(value));
66
88
  const childPath = (parent, key) => (parent.length === 0 ? key : `${parent}.${key}`);
67
89
  /**
68
90
  * Collects every numeric leaf that violates the integer-only contract.
@@ -78,6 +100,10 @@ function findNonIntegerNumericLeaves(document) {
78
100
  const walk = (node, path) => {
79
101
  if (node === undefined)
80
102
  return;
103
+ if (isBsonNumeric(node)) {
104
+ violations.push({ path, value: node, reason: 'bson-numeric' });
105
+ return;
106
+ }
81
107
  if (isIgnoredLeaf(node))
82
108
  return;
83
109
  if (typeof node === 'number') {
@@ -32,9 +32,9 @@ export interface IBuildDrilldownRowsResult {
32
32
  * usable time anchor are skipped and counted; the writer can decide whether to
33
33
  * fail loudly.
34
34
  */
35
- export declare function buildMaterializedDrilldownRows(reportType: TDrilldownReportType, document: IEntryDocumentLike | null | undefined): IBuildDrilldownRowsResult;
35
+ export declare function buildMaterializedDrilldownRows(reportType: TDrilldownReportType, document: IEntryDocumentLike | null | undefined, sourceLocalDate?: string | null): IBuildDrilldownRowsResult;
36
36
  /** Flattens many entry documents of one report (used by backfill/demo). */
37
37
  export declare function buildMaterializedDrilldownRowsFromDocuments(reportType: TDrilldownReportType, documents: IEntryDocumentLike[] | null | undefined): IBuildDrilldownRowsResult;
38
38
  /** Scope metadata (row count + delivery off-app count) for the flat reader. */
39
- export declare function buildMaterializedDrilldownScope(reportType: TDrilldownReportType, document: IEntryDocumentLike | null | undefined, rows: IMaterializedReportDrilldownRow[]): IMaterializedReportDrilldownScope | null;
39
+ export declare function buildMaterializedDrilldownScope(reportType: TDrilldownReportType, document: IEntryDocumentLike | null | undefined, rows: IMaterializedReportDrilldownRow[], sourceLocalDate?: string | null): IMaterializedReportDrilldownScope | null;
40
40
  export {};
@@ -73,7 +73,7 @@ exports.getDrilldownRowsKey = getDrilldownRowsKey;
73
73
  * usable time anchor are skipped and counted; the writer can decide whether to
74
74
  * fail loudly.
75
75
  */
76
- function buildMaterializedDrilldownRows(reportType, document) {
76
+ function buildMaterializedDrilldownRows(reportType, document, sourceLocalDate = null) {
77
77
  if (document == null)
78
78
  return { rows: [], skipped: 0 };
79
79
  const spec = ROW_SPECS[reportType];
@@ -124,6 +124,7 @@ function buildMaterializedDrilldownRows(reportType, document) {
124
124
  cursor_id: cursorId,
125
125
  time,
126
126
  data: row,
127
+ source_local_date: sourceLocalDate,
127
128
  schema_version: materialized_report_drilldown_rows_1.MATERIALIZED_REPORT_DRILLDOWN_ROWS_SCHEMA_VERSION,
128
129
  computed_at: computedAt,
129
130
  });
@@ -143,7 +144,7 @@ function buildMaterializedDrilldownRowsFromDocuments(reportType, documents) {
143
144
  return { rows, skipped };
144
145
  }
145
146
  /** Scope metadata (row count + delivery off-app count) for the flat reader. */
146
- function buildMaterializedDrilldownScope(reportType, document, rows) {
147
+ function buildMaterializedDrilldownScope(reportType, document, rows, sourceLocalDate = null) {
147
148
  if (document == null)
148
149
  return null;
149
150
  const tenantId = asString(document.tenant_id);
@@ -163,6 +164,7 @@ function buildMaterializedDrilldownScope(reportType, document, rows) {
163
164
  scope_field: scopeField,
164
165
  row_count: rows.length,
165
166
  off_app_order_count: offApp,
167
+ source_local_date: sourceLocalDate,
166
168
  schema_version: materialized_report_drilldown_rows_1.MATERIALIZED_REPORT_DRILLDOWN_ROWS_SCHEMA_VERSION,
167
169
  computed_at: toDate(document.computed_at) ?? new Date(),
168
170
  };
@@ -647,6 +647,13 @@ const decodeMaterializedReportScopeGroups = (selection) => {
647
647
  // never disagree.
648
648
  const window = resolveTimeOfDayWindow(selection);
649
649
  const weekdayFilter = getActiveWeekdayFilter(selection.weekdays);
650
+ // A half-set / invalid / unservable time window must NEVER silently fall
651
+ // through to the full period: the caller asked for a time refinement, so an
652
+ // unresolvable one is an invalid selection (the read parser turns this null
653
+ // into a 400).
654
+ if ((selection.timeStart != null || selection.timeEnd != null) && window == null) {
655
+ return null;
656
+ }
650
657
  if (window != null || weekdayFilter != null) {
651
658
  const days = (0, exports.getDayKeysFromCalendarSelection)(selection);
652
659
  if (days.length === 0)
@@ -55,3 +55,25 @@ export declare function getMaterializedPeriodScopeFields(localDate: string): IMa
55
55
  * hour.
56
56
  */
57
57
  export declare function getMaterializedHourScopeField(localDate: string, hour: number): string | null;
58
+ /** Inclusive `YYYY-MM-DD` range of day documents that can belong to a date's periods. */
59
+ export interface IMaterializedPeriodDayScopeRange {
60
+ gte: string;
61
+ lte: string;
62
+ }
63
+ /**
64
+ * The `scope_field` RANGE a close must scan to find every stored `localDate`
65
+ * document that can share a period with `localDate` — used to REPAIR a missing
66
+ * period document from its sibling days (a period is a running sum; creating it
67
+ * from the closing day alone would make it disagree with the sum of the day
68
+ * documents).
69
+ *
70
+ * This is a deliberately generous SUPERSET: the ISO week / calendar week of a
71
+ * date can start in the previous calendar year (e.g. `2027-01-01` belongs to
72
+ * `2026-W53`), and the calendar week can extend into the next one. Membership
73
+ * is decided afterwards by comparing each candidate's
74
+ * `getMaterializedPeriodScopeFields` / scope refs to the created period; the
75
+ * range only bounds the query (one indexed range scan, no `$in` of 366 keys).
76
+ *
77
+ * Returns `null` (never throws) for a malformed date.
78
+ */
79
+ export declare function getMaterializedPeriodDayScopeRange(localDate: string): IMaterializedPeriodDayScopeRange | null;
@@ -5,6 +5,7 @@ exports.getIsoWeekYear = getIsoWeekYear;
5
5
  exports.getDayIndexFromLocalDate = getDayIndexFromLocalDate;
6
6
  exports.getMaterializedPeriodScopeFields = getMaterializedPeriodScopeFields;
7
7
  exports.getMaterializedHourScopeField = getMaterializedHourScopeField;
8
+ exports.getMaterializedPeriodDayScopeRange = getMaterializedPeriodDayScopeRange;
8
9
  const ENUMS_1 = require("../../constants/ENUMS");
9
10
  const MATERIALIZED_REPORTS_1 = require("../../constants/MATERIALIZED_REPORTS");
10
11
  const time_helpers_1 = require("../utils/time-helpers");
@@ -112,3 +113,30 @@ function getMaterializedHourScopeField(localDate, hour) {
112
113
  return null;
113
114
  return `${localDate} ${pad(hour)}`;
114
115
  }
116
+ /**
117
+ * The `scope_field` RANGE a close must scan to find every stored `localDate`
118
+ * document that can share a period with `localDate` — used to REPAIR a missing
119
+ * period document from its sibling days (a period is a running sum; creating it
120
+ * from the closing day alone would make it disagree with the sum of the day
121
+ * documents).
122
+ *
123
+ * This is a deliberately generous SUPERSET: the ISO week / calendar week of a
124
+ * date can start in the previous calendar year (e.g. `2027-01-01` belongs to
125
+ * `2026-W53`), and the calendar week can extend into the next one. Membership
126
+ * is decided afterwards by comparing each candidate's
127
+ * `getMaterializedPeriodScopeFields` / scope refs to the created period; the
128
+ * range only bounds the query (one indexed range scan, no `$in` of 366 keys).
129
+ *
130
+ * Returns `null` (never throws) for a malformed date.
131
+ */
132
+ function getMaterializedPeriodDayScopeRange(localDate) {
133
+ const parts = parseMaterializedLocalDate(localDate);
134
+ if (parts == null)
135
+ return null;
136
+ const { year } = parts;
137
+ const toKey = (date) => `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}`;
138
+ return {
139
+ gte: toKey(new Date(Date.UTC(year, 0, 1 - 7))),
140
+ lte: toKey(new Date(Date.UTC(year, 11, 31 + 7))),
141
+ };
142
+ }
@@ -92,6 +92,33 @@ export interface IBuildTenantSalesOverviewCloseDayPlanInput {
92
92
  * one scope key → `null`.
93
93
  */
94
94
  existingCreditBills?: IMaterializedTenantCreditBillsReport[];
95
+ /**
96
+ * Stored `localDate` documents of the SAME tenant (any day of the year,
97
+ * excluding the closing day), fetched by the job so a MISSING period
98
+ * document can be rebuilt from the days that were already materialized.
99
+ *
100
+ * Why: a period document is a running sum, so creating it from the closing
101
+ * day alone would make `localMonth` disagree with the SUM of the month's
102
+ * `localDate` documents whenever the document is missing (a partial failure
103
+ * between the history and the period write, a manual delete, a backfill).
104
+ * The plan folds the sibling days that BELONG to the created scope, so the
105
+ * period equals the sum of its days again. Days that were never
106
+ * materialized have no document and contribute nothing — the same answer the
107
+ * day-level read gives, so the two scopes stay equivalent.
108
+ */
109
+ existingPeriodDayDocuments?: IMaterializedTenantSalesOverviewReport[];
110
+ /**
111
+ * Stored `localMonth` Overview documents of the same tenant. Used ONLY when
112
+ * creating a missing quarter/semester/year: the hierarchy is
113
+ * date -> month -> quarter/semester/year, NEVER week -> month.
114
+ */
115
+ existingPeriodMonthDocuments?: IMaterializedTenantSalesOverviewReport[];
116
+ /**
117
+ * Stored `localDate` `materialized_tenant_credit_bills` documents of the
118
+ * same tenant, used to rebuild a missing credit PERIOD document from the
119
+ * sibling days (same contract as `existingPeriodDayDocuments`).
120
+ */
121
+ existingPeriodDayCreditDocuments?: IMaterializedTenantCreditBillsReport[];
95
122
  /** Force structural writes even when the watermarks are up to date. */
96
123
  force?: boolean;
97
124
  /** Override for write timestamps (tests, replays). */
@@ -131,6 +158,8 @@ export interface ITenantSalesOverviewCloseDayPlan {
131
158
  * `creditWrites` (computed against the post-write documents).
132
159
  */
133
160
  creditSettlementPatches: ITenantCreditBillsCloseDayWrite[];
161
+ /** Partial-receipt issue-scope patches (same bill identity, cumulative amount). */
162
+ creditReceiptPatches: ITenantCreditBillsCloseDayWrite[];
134
163
  /**
135
164
  * Issued-day SETTLED counter patches (versioned writes, counters only) —
136
165
  * persist AFTER `writes` (computed against the post-write documents).
@@ -149,6 +178,20 @@ export interface ITenantSalesOverviewCloseDayPlan {
149
178
  * when the day is not the period's first materialized close.
150
179
  */
151
180
  createdPeriodDocuments: IMaterializedReportScopeRef[];
181
+ /**
182
+ * How many stored sibling DAY documents were folded into period documents
183
+ * this close CREATED (see `existingPeriodDayDocuments`). 0 means either no
184
+ * period document was created or the period genuinely had no materialized
185
+ * earlier day; a non-zero value means a missing period document was REPAIRED
186
+ * from the day level instead of being seeded with the closing day alone.
187
+ */
188
+ foldedPeriodDayDocuments: number;
189
+ /**
190
+ * Same repair count for `materialized_tenant_credit_bills` period documents
191
+ * rebuilt from the sibling days (see
192
+ * `existingPeriodDayCreditDocuments`).
193
+ */
194
+ foldedPeriodDayCreditDocuments: number;
152
195
  }
153
196
  /** `(scope_context, scope_field)` pair of a stored / compiled document. */
154
197
  export interface IMaterializedReportScopeRef {
@@ -167,9 +210,12 @@ export declare function getMaterializedTenantSalesOverviewScopeRefsForDay(localD
167
210
  * structural write for the incoming compiled version?
168
211
  *
169
212
  * `false` (skip) when the incoming `source_watermark` is not newer than the
170
- * stored one and the schema version + key-filter grammar match. Watermarks are
171
- * monotonic (`updateMaterializedTenantSalesOverviewReport` never regresses
172
- * them). A missing stored document always needs a write.
213
+ * stored one, the day-input SIGNATURE is unchanged, and the schema version +
214
+ * key-filter grammar match. Watermarks are monotonic
215
+ * (`updateMaterializedTenantSalesOverviewReport` never regresses them); the
216
+ * signature is the SET-shaped signal that detects a deleted / moved order even
217
+ * when the incoming watermark is lower than the stored one. A missing stored
218
+ * document always needs a write.
173
219
  */
174
220
  export declare function needsMaterializedTenantSalesOverviewReportWrite(existing: IMaterializedTenantSalesOverviewReport | null | undefined, incoming: IMaterializedTenantSalesOverviewReport | null | undefined): boolean;
175
221
  /**