@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.
- package/esm/constants/MATERIALIZED_REPORTS.js +9 -12
- package/esm/helpers/materialized-reports/index.js +2 -0
- package/esm/helpers/materialized-reports/materialized-credit-bills-helpers.js +178 -40
- package/esm/helpers/materialized-reports/materialized-day-input-signature.js +103 -0
- package/esm/helpers/materialized-reports/materialized-discount-classification-helpers.js +10 -3
- package/esm/helpers/materialized-reports/materialized-discount-close-day-helpers.js +299 -227
- package/esm/helpers/materialized-reports/materialized-discount-compile-helpers.js +20 -1
- package/esm/helpers/materialized-reports/materialized-discount-source-helpers.js +176 -0
- package/esm/helpers/materialized-reports/materialized-index-bootstrap.js +64 -0
- package/esm/helpers/materialized-reports/materialized-integer-contract.js +30 -4
- package/esm/helpers/materialized-reports/materialized-report-drilldown-rows.js +4 -2
- package/esm/helpers/materialized-reports/materialized-reports-selection-helpers.js +7 -0
- package/esm/helpers/materialized-reports/scope-helpers.js +27 -0
- package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +400 -46
- package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +28 -6
- package/esm/schemas/models/materialized_credit_bills.js +8 -0
- package/esm/schemas/models/materialized_report_drilldown_rows.js +39 -12
- package/esm/schemas/models/materialized_tenant_discount_entries.js +18 -12
- package/esm/schemas/models/materialized_tenant_discount_reports.js +9 -0
- package/esm/schemas/models/materialized_tenant_discount_sources.js +1 -1
- package/esm/schemas/models/materialized_tenant_sales_overview_reports.js +9 -0
- package/esm/schemas/models/orders.js +5 -0
- package/esm/schemas/models/tenant_active_jobs.js +8 -0
- package/esm/schemas/models/tenant_calendar.js +12 -0
- package/lib/constants/MATERIALIZED_REPORTS.d.ts +9 -12
- package/lib/constants/MATERIALIZED_REPORTS.js +11 -14
- package/lib/helpers/materialized-reports/index.d.ts +2 -0
- package/lib/helpers/materialized-reports/index.js +2 -0
- package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.d.ts +66 -2
- package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.js +179 -39
- package/lib/helpers/materialized-reports/materialized-day-input-signature.d.ts +66 -0
- package/lib/helpers/materialized-reports/materialized-day-input-signature.js +108 -0
- package/lib/helpers/materialized-reports/materialized-discount-classification-helpers.js +10 -3
- package/lib/helpers/materialized-reports/materialized-discount-close-day-helpers.d.ts +41 -60
- package/lib/helpers/materialized-reports/materialized-discount-close-day-helpers.js +298 -226
- package/lib/helpers/materialized-reports/materialized-discount-compile-helpers.d.ts +4 -4
- package/lib/helpers/materialized-reports/materialized-discount-compile-helpers.js +19 -0
- package/lib/helpers/materialized-reports/materialized-discount-source-helpers.d.ts +17 -0
- package/lib/helpers/materialized-reports/materialized-discount-source-helpers.js +178 -0
- package/lib/helpers/materialized-reports/materialized-index-bootstrap.d.ts +7 -0
- package/lib/helpers/materialized-reports/materialized-index-bootstrap.js +68 -0
- package/lib/helpers/materialized-reports/materialized-integer-contract.d.ts +3 -1
- package/lib/helpers/materialized-reports/materialized-integer-contract.js +30 -4
- package/lib/helpers/materialized-reports/materialized-report-drilldown-rows.d.ts +2 -2
- package/lib/helpers/materialized-reports/materialized-report-drilldown-rows.js +4 -2
- package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.js +7 -0
- package/lib/helpers/materialized-reports/scope-helpers.d.ts +22 -0
- package/lib/helpers/materialized-reports/scope-helpers.js +28 -0
- package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +49 -3
- package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +398 -44
- package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.d.ts +4 -1
- package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +28 -6
- package/lib/schemas/models/materialized_credit_bills.d.ts +3 -0
- package/lib/schemas/models/materialized_credit_bills.js +8 -0
- package/lib/schemas/models/materialized_report_drilldown_rows.d.ts +40 -6
- package/lib/schemas/models/materialized_report_drilldown_rows.js +39 -12
- package/lib/schemas/models/materialized_tenant_discount_entries.d.ts +33 -29
- package/lib/schemas/models/materialized_tenant_discount_entries.js +18 -12
- package/lib/schemas/models/materialized_tenant_discount_reports.d.ts +3 -0
- package/lib/schemas/models/materialized_tenant_discount_reports.js +9 -0
- package/lib/schemas/models/materialized_tenant_discount_sources.d.ts +6 -6
- package/lib/schemas/models/materialized_tenant_discount_sources.js +1 -1
- package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +3 -0
- package/lib/schemas/models/materialized_tenant_sales_overview_reports.js +9 -0
- package/lib/schemas/models/orders.d.ts +5 -0
- package/lib/schemas/models/orders.js +5 -0
- package/lib/schemas/models/tenant_active_jobs.d.ts +3 -0
- package/lib/schemas/models/tenant_active_jobs.js +8 -0
- package/lib/schemas/models/tenant_calendar.d.ts +13 -0
- package/lib/schemas/models/tenant_calendar.js +13 -1
- package/lib/schemas/types/materialized_credit_bills.d.ts +6 -0
- package/lib/schemas/types/materialized_report_drilldown_rows.d.ts +8 -0
- package/lib/schemas/types/materialized_tenant_discount_entries.d.ts +9 -5
- package/lib/schemas/types/materialized_tenant_discount_reports.d.ts +6 -0
- package/lib/schemas/types/materialized_tenant_reports_iterations.d.ts +9 -0
- package/lib/schemas/types/materialized_tenant_sales_overview_reports.d.ts +14 -0
- package/lib/schemas/types/tenant_active_jobs.d.ts +8 -0
- package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.js +56 -1
- package/lib/tests/materialized-reports/materialized-day-input-signature.test.d.ts +1 -0
- package/lib/tests/materialized-reports/materialized-day-input-signature.test.js +81 -0
- package/lib/tests/materialized-reports/materialized-discount-classification.test.js +17 -0
- package/lib/tests/materialized-reports/materialized-discount-close-day.test.js +148 -53
- package/lib/tests/materialized-reports/materialized-discount-entries-accumulation.test.js +14 -13
- package/lib/tests/materialized-reports/materialized-discount-sources.test.js +76 -0
- package/lib/tests/materialized-reports/materialized-integer-contract.test.js +11 -0
- package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.js +2 -2
- package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +311 -4
- package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +89 -0
- 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
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
|
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
|
-
|
|
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 +
|
|
171
|
-
*
|
|
172
|
-
*
|
|
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
|
/**
|