@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
@@ -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
  */
@@ -191,6 +191,7 @@ function compileTenantDiscountReports(input) {
191
191
  brand_id: brandId,
192
192
  scope_context: scope,
193
193
  scope_field: scopeField,
194
+ page: isDateScoped ? MATERIALIZED_REPORTS_1.MATERIALIZED_DISCOUNT_ENTRY_PAGE_ALL : localDate,
194
195
  day_index: isDateScoped ? dayIndex : null,
195
196
  sale_type_key_filters: [
196
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)
@@ -107,6 +107,12 @@ export interface IBuildTenantSalesOverviewCloseDayPlanInput {
107
107
  * day-level read gives, so the two scopes stay equivalent.
108
108
  */
109
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[];
110
116
  /**
111
117
  * Stored `localDate` `materialized_tenant_credit_bills` documents of the
112
118
  * same tenant, used to rebuild a missing credit PERIOD document from the
@@ -152,6 +158,8 @@ export interface ITenantSalesOverviewCloseDayPlan {
152
158
  * `creditWrites` (computed against the post-write documents).
153
159
  */
154
160
  creditSettlementPatches: ITenantCreditBillsCloseDayWrite[];
161
+ /** Partial-receipt issue-scope patches (same bill identity, cumulative amount). */
162
+ creditReceiptPatches: ITenantCreditBillsCloseDayWrite[];
155
163
  /**
156
164
  * Issued-day SETTLED counter patches (versioned writes, counters only) —
157
165
  * persist AFTER `writes` (computed against the post-write documents).