@managesome/eposmatic-toolkit 0.4.28 → 0.4.29
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/helpers/materialized-reports/index.js +1 -0
- package/esm/helpers/materialized-reports/materialized-credit-bills-helpers.js +49 -20
- package/esm/helpers/materialized-reports/materialized-day-input-signature.js +103 -0
- package/esm/helpers/materialized-reports/materialized-discount-close-day-helpers.js +63 -2
- package/esm/helpers/materialized-reports/materialized-discount-compile-helpers.js +18 -0
- package/esm/helpers/materialized-reports/scope-helpers.js +27 -0
- package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +122 -9
- package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +24 -2
- package/esm/schemas/models/materialized_credit_bills.js +8 -0
- package/esm/schemas/models/materialized_tenant_discount_reports.js +9 -0
- package/esm/schemas/models/materialized_tenant_sales_overview_reports.js +9 -0
- package/esm/schemas/models/tenant_active_jobs.js +8 -0
- package/lib/helpers/materialized-reports/index.d.ts +1 -0
- package/lib/helpers/materialized-reports/index.js +1 -0
- package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.d.ts +28 -2
- package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.js +50 -20
- 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-close-day-helpers.d.ts +20 -1
- package/lib/helpers/materialized-reports/materialized-discount-close-day-helpers.js +63 -2
- package/lib/helpers/materialized-reports/materialized-discount-compile-helpers.js +18 -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 +41 -3
- package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +120 -7
- package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.d.ts +4 -1
- package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +24 -2
- 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_tenant_discount_reports.d.ts +3 -0
- package/lib/schemas/models/materialized_tenant_discount_reports.js +9 -0
- 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/tenant_active_jobs.d.ts +3 -0
- package/lib/schemas/models/tenant_active_jobs.js +8 -0
- package/lib/schemas/types/materialized_credit_bills.d.ts +6 -0
- 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-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-close-day.test.js +89 -0
- package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +162 -0
- package/package.json +1 -1
|
@@ -3,6 +3,7 @@ import { PAYMENT_STATUS_ENUM, PAYMENT_TYPE_ENUM, REPORT_SALE_TYPE_ENUM } from '.
|
|
|
3
3
|
import { MATERIALIZED_REPORT_SCOPE_ENUM, MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX, SALES_OVERVIEW_KEY_FILTERS, } from '../../constants/MATERIALIZED_REPORTS';
|
|
4
4
|
import { MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_COLLECTION_NAME, MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_SCHEMA_VERSION, MaterializedTenantSalesOverviewReportSchema, } from '../../schemas/models/materialized_tenant_sales_overview_reports';
|
|
5
5
|
import { buildMaterializedReportKey } from './key-helpers';
|
|
6
|
+
import { buildMaterializedDayInputSignature, } from './materialized-day-input-signature';
|
|
6
7
|
import { buildCreditBillEventCandidatesFromOrder, buildCreditBillIssuedCandidatesFromOrder, isMaterializedCreditBillPayment, resolveOrderLocalHour, resolveReceivedLocalHour, } from './materialized-credit-bills-helpers';
|
|
7
8
|
import { getDayIndexFromLocalDate, getMaterializedHourScopeField, getMaterializedPeriodScopeFields, parseMaterializedLocalDate, } from './scope-helpers';
|
|
8
9
|
/* ------------------------------------------------------------------------ */
|
|
@@ -506,13 +507,26 @@ export function convertOrdersToMaterializedTenantSalesOverviewReports(localDate,
|
|
|
506
507
|
// `source_watermark` = max `order.updatedAt` folded in; a day with no
|
|
507
508
|
// orders folds nothing → epoch. Stable across recompiles, so the
|
|
508
509
|
// watermark guard skips unchanged (order-less) days instead of churning.
|
|
509
|
-
|
|
510
|
+
//
|
|
511
|
+
// `source_input_signature` is the SET-shaped companion: the watermark only
|
|
512
|
+
// advances, so a delete / move that removes the maximum-`updatedAt` order
|
|
513
|
+
// would leave the incoming watermark LOWER than the stored one and the
|
|
514
|
+
// guard would skip the correction. The digest changes with the input set,
|
|
515
|
+
// so the close is still applied. Both are computed from the SAME
|
|
516
|
+
// `tenantOrders` array the compile consumed.
|
|
517
|
+
// Both change-detection signals describe the orders this day ACTUALLY
|
|
518
|
+
// materializes: a deleted order must never keep the day "fresh" (or
|
|
519
|
+
// contribute a watermark the remaining orders cannot reproduce).
|
|
520
|
+
const consideredOrders = tenantOrders.filter((order) => order.is_deleted === false);
|
|
521
|
+
const watermark = consideredOrders.reduce((latest, order) => {
|
|
510
522
|
const updatedAt = new Date(order.updatedAt ?? now);
|
|
511
523
|
return updatedAt.getTime() > latest.getTime() ? updatedAt : latest;
|
|
512
524
|
}, new Date(0));
|
|
525
|
+
const sourceInputSignature = buildMaterializedDayInputSignature(consideredOrders) ?? undefined;
|
|
513
526
|
for (const { doc, metrics } of [...periodDocs, ...hourDocs.values()]) {
|
|
514
527
|
doc.sale_type_metrics = finalizeMetrics(metrics);
|
|
515
528
|
doc.source_watermark = watermark;
|
|
529
|
+
doc.source_input_signature = sourceInputSignature;
|
|
516
530
|
materializedReports.push(doc);
|
|
517
531
|
}
|
|
518
532
|
}
|
|
@@ -736,7 +750,10 @@ export function subtractMaterializedTenantSalesOverviewReports(minuend, subtrahe
|
|
|
736
750
|
* so replays stay churn-free;
|
|
737
751
|
* 4. `source_watermark` advances to the max of the existing and the incoming
|
|
738
752
|
* (`replacement` / `additions`) watermarks — monotonic, never regressed
|
|
739
|
-
* (rollbacks / replays keep the previously folded maximum)
|
|
753
|
+
* (rollbacks / replays keep the previously folded maximum);
|
|
754
|
+
* 5. `source_input_signature` follows a `replacement` (the fresh day compile)
|
|
755
|
+
* and is KEPT on period accumulates — a period's payload is a running sum,
|
|
756
|
+
* not one day's input set.
|
|
740
757
|
*
|
|
741
758
|
* Returns a new JSON report; the input is not mutated.
|
|
742
759
|
*/
|
|
@@ -794,6 +811,11 @@ export function updateMaterializedTenantSalesOverviewReport(existing, updates, o
|
|
|
794
811
|
// Reconcile artifacts: a fully-subtracted key is pruned so accumulated
|
|
795
812
|
// period documents keep the same key set as day / hour reads.
|
|
796
813
|
sale_type_metrics: pruneZeroReportKeys(finalizeMetrics(metrics)),
|
|
814
|
+
// The day-input digest travels with a REPLACEMENT write (the freshly
|
|
815
|
+
// compiled day/hour document) so the next close can compare it. Period
|
|
816
|
+
// accumulates keep the stored value: their payload is a running sum, not
|
|
817
|
+
// one day's input set.
|
|
818
|
+
source_input_signature: updates.replacement?.source_input_signature ?? existing.source_input_signature,
|
|
797
819
|
// Version metric writes AND ledger-changing received-payment patches (both
|
|
798
820
|
// append a history row via the caller). No-op patches bump nothing, so
|
|
799
821
|
// replays stay churn-free.
|
|
@@ -201,6 +201,14 @@ export const MaterializedTenantCreditBillsReportSchema = new Schema({
|
|
|
201
201
|
type: Schema.Types.Date,
|
|
202
202
|
required: true,
|
|
203
203
|
},
|
|
204
|
+
// Day-input digest (`v1:<count>:<hash>`) — set-shaped change detection
|
|
205
|
+
// for the credit ledger, mirroring the sales-overview reports. A deleted /
|
|
206
|
+
// moved order must remove its bill even when the watermark regresses.
|
|
207
|
+
source_input_signature: {
|
|
208
|
+
type: String,
|
|
209
|
+
required: false,
|
|
210
|
+
default: undefined,
|
|
211
|
+
},
|
|
204
212
|
computed_at: {
|
|
205
213
|
type: Schema.Types.Date,
|
|
206
214
|
required: true,
|
|
@@ -207,6 +207,15 @@ export const MaterializedTenantDiscountReportSchema = new Schema({
|
|
|
207
207
|
type: Schema.Types.Date,
|
|
208
208
|
required: true,
|
|
209
209
|
},
|
|
210
|
+
// Day-input digest (`v1:<count>:<hash>`) — set-shaped change detection
|
|
211
|
+
// for the discount counters, mirroring the sales-overview reports. A
|
|
212
|
+
// deleted / moved order must remove its discount even when the watermark
|
|
213
|
+
// regresses.
|
|
214
|
+
source_input_signature: {
|
|
215
|
+
type: String,
|
|
216
|
+
required: false,
|
|
217
|
+
default: undefined,
|
|
218
|
+
},
|
|
210
219
|
computed_at: {
|
|
211
220
|
type: Schema.Types.Date,
|
|
212
221
|
required: true,
|
|
@@ -264,6 +264,15 @@ export const MaterializedTenantSalesOverviewReportSchema = new Schema({
|
|
|
264
264
|
type: Schema.Types.Date,
|
|
265
265
|
required: true,
|
|
266
266
|
},
|
|
267
|
+
// Day-input digest (`v1:<count>:<hash>`) — the SET-shaped half of change
|
|
268
|
+
// detection. A delete / move can lower the incoming watermark; the digest
|
|
269
|
+
// changes instead, so the close still performs the corrective writes.
|
|
270
|
+
// Optional: documents written before it existed are rewritten once.
|
|
271
|
+
source_input_signature: {
|
|
272
|
+
type: String,
|
|
273
|
+
required: false,
|
|
274
|
+
default: undefined,
|
|
275
|
+
},
|
|
267
276
|
computed_at: {
|
|
268
277
|
type: Schema.Types.Date,
|
|
269
278
|
required: true,
|
|
@@ -27,6 +27,14 @@ export const TenantActiveJobSchema = new Schema({
|
|
|
27
27
|
enum: ALL_TENANT_ACTIVE_JOBS_NAMES,
|
|
28
28
|
default: null,
|
|
29
29
|
},
|
|
30
|
+
// Fencing token of the current owner — fresh per acquisition. Updates,
|
|
31
|
+
// completion and failure filter on it so a stale owner cannot touch the
|
|
32
|
+
// job after a takeover. `null` when the job is free.
|
|
33
|
+
lease_id: {
|
|
34
|
+
type: String,
|
|
35
|
+
required: false,
|
|
36
|
+
default: null,
|
|
37
|
+
},
|
|
30
38
|
failed_jobs: {
|
|
31
39
|
type: [String],
|
|
32
40
|
enum: ALL_TENANT_ACTIVE_JOBS_NAMES,
|
|
@@ -18,6 +18,7 @@ export * from './materialized-delivery-accumulator-helpers';
|
|
|
18
18
|
export * from './materialized-delivery-compile-helpers';
|
|
19
19
|
export * from './materialized-delivery-classification-helpers';
|
|
20
20
|
export * from './materialized-delivery-close-day-helpers';
|
|
21
|
+
export * from './materialized-day-input-signature';
|
|
21
22
|
export * from './materialized-cash-classification-helpers';
|
|
22
23
|
export * from './materialized-cash-close-day-helpers';
|
|
23
24
|
export * from './materialized-cash-compile-helpers';
|
|
@@ -34,6 +34,7 @@ __exportStar(require("./materialized-delivery-accumulator-helpers"), exports);
|
|
|
34
34
|
__exportStar(require("./materialized-delivery-compile-helpers"), exports);
|
|
35
35
|
__exportStar(require("./materialized-delivery-classification-helpers"), exports);
|
|
36
36
|
__exportStar(require("./materialized-delivery-close-day-helpers"), exports);
|
|
37
|
+
__exportStar(require("./materialized-day-input-signature"), exports);
|
|
37
38
|
__exportStar(require("./materialized-cash-classification-helpers"), exports);
|
|
38
39
|
__exportStar(require("./materialized-cash-close-day-helpers"), exports);
|
|
39
40
|
__exportStar(require("./materialized-cash-compile-helpers"), exports);
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM, MATERIALIZED_REPORT_SCOPE_ENUM } from '../../constants/MATERIALIZED_REPORTS';
|
|
2
2
|
import { IOrder, IOrderPayment } from '../../schemas';
|
|
3
|
-
import { IMaterializedCreditBillIssuedEntry, IMaterializedCreditBillReceivedEntry, IMaterializedTenantCreditBillsReport } from '../../schemas/types/materialized_credit_bills';
|
|
3
|
+
import { IMaterializedCreditBillIssuedEntry, IMaterializedCreditBillKeySection, IMaterializedCreditBillReceivedEntry, IMaterializedTenantCreditBillsReport } from '../../schemas/types/materialized_credit_bills';
|
|
4
4
|
import { IGetMaterializedReportScopeGroup } from '../types/materialized-reports-apis';
|
|
5
5
|
/**
|
|
6
6
|
* The shared credit-bill ledger (`materialized_tenant_credit_bills`) —
|
|
@@ -174,7 +174,28 @@ export interface IBuildMaterializedCreditBillDayReportsInput {
|
|
|
174
174
|
localDate: string;
|
|
175
175
|
resolution: ICreditBillDayResolution;
|
|
176
176
|
computedAt: Date;
|
|
177
|
+
/**
|
|
178
|
+
* Day-input digest (`buildMaterializedDayInputSignature`) of the orders the
|
|
179
|
+
* resolution was compiled from — the SET-shaped half of change detection
|
|
180
|
+
* (a delete / move must correct the ledger even when the watermark
|
|
181
|
+
* regresses). Optional so existing callers keep working; a document without
|
|
182
|
+
* one is re-materialized by the guard on its next close.
|
|
183
|
+
*/
|
|
184
|
+
sourceInputSignature?: string | null;
|
|
177
185
|
}
|
|
186
|
+
/**
|
|
187
|
+
* Folds `source` sections INTO `target` (mutating it), identity-matched:
|
|
188
|
+
* an ISSUED entry is one `(order_id, payment_id)` bill; a RECEIVED entry is one
|
|
189
|
+
* `(order_id, payment_id, event_local_date)` collection event. A source entry
|
|
190
|
+
* REPLACES its target counterpart (fresh wins), so re-applying the same day is
|
|
191
|
+
* idempotent.
|
|
192
|
+
*
|
|
193
|
+
* Exported because the close-day plan uses the SAME merge when it rebuilds a
|
|
194
|
+
* MISSING period document from the stored day documents (a deleted period
|
|
195
|
+
* document must not be recreated from the closing day alone; see
|
|
196
|
+
* `buildTenantSalesOverviewCloseDayPlan`'s period repair).
|
|
197
|
+
*/
|
|
198
|
+
export declare function mergeMaterializedCreditBillSections(target: Record<string, IMaterializedCreditBillKeySection>, source: Record<string, IMaterializedCreditBillKeySection> | null | undefined): void;
|
|
178
199
|
/**
|
|
179
200
|
* Materializes ONE day's credit documents from its resolution — the
|
|
180
201
|
* month-capped scope set (`MATERIALIZED_CREDIT_BILLS_SCOPES`): one document per
|
|
@@ -208,7 +229,12 @@ export interface IMaterializedCreditBillScopeRef {
|
|
|
208
229
|
scope_context: MATERIALIZED_REPORT_SCOPE_ENUM;
|
|
209
230
|
scope_field: string;
|
|
210
231
|
}
|
|
211
|
-
/**
|
|
232
|
+
/**
|
|
233
|
+
* `Writes the watermarks / day-input signature / schema / key-filter grammar
|
|
234
|
+
* allow a write?` (mirrors the sales-report guard). The signature is checked
|
|
235
|
+
* FIRST so a deleted / moved order still corrects the ledger when the incoming
|
|
236
|
+
* watermark regressed.
|
|
237
|
+
*/
|
|
212
238
|
export declare const needsMaterializedCreditBillsReportWrite: (existing: IMaterializedTenantCreditBillsReport | null | undefined, incoming: IMaterializedTenantCreditBillsReport) => boolean;
|
|
213
239
|
/**
|
|
214
240
|
* The day-close fetch plan: every scope document one compiled day may touch —
|
|
@@ -7,6 +7,7 @@ exports.needsMaterializedCreditBillsReportWrite = exports.toMaterializedHourLabe
|
|
|
7
7
|
exports.buildCreditBillIssuedCandidatesFromOrder = buildCreditBillIssuedCandidatesFromOrder;
|
|
8
8
|
exports.buildCreditBillEventCandidatesFromOrder = buildCreditBillEventCandidatesFromOrder;
|
|
9
9
|
exports.resolveCreditBillDay = resolveCreditBillDay;
|
|
10
|
+
exports.mergeMaterializedCreditBillSections = mergeMaterializedCreditBillSections;
|
|
10
11
|
exports.buildMaterializedCreditBillDayReports = buildMaterializedCreditBillDayReports;
|
|
11
12
|
exports.updateMaterializedCreditBillsReport = updateMaterializedCreditBillsReport;
|
|
12
13
|
exports.getMaterializedCreditBillScopeRefsForDay = getMaterializedCreditBillScopeRefsForDay;
|
|
@@ -20,6 +21,7 @@ const MATERIALIZED_REPORTS_1 = require("../../constants/MATERIALIZED_REPORTS");
|
|
|
20
21
|
const materialized_credit_bills_1 = require("../../schemas/models/materialized_credit_bills");
|
|
21
22
|
const time_helpers_1 = require("../utils/time-helpers");
|
|
22
23
|
const key_helpers_1 = require("./key-helpers");
|
|
24
|
+
const materialized_day_input_signature_1 = require("./materialized-day-input-signature");
|
|
23
25
|
const scope_helpers_1 = require("./scope-helpers");
|
|
24
26
|
/**
|
|
25
27
|
* The shared credit-bill ledger (`materialized_tenant_credit_bills`) —
|
|
@@ -361,6 +363,39 @@ function resolveCreditBillDay(input) {
|
|
|
361
363
|
}
|
|
362
364
|
const emptySection = () => ({ issued: [], received: [] });
|
|
363
365
|
const sectionFor = (map, key) => map[key] ?? (map[key] = emptySection());
|
|
366
|
+
/**
|
|
367
|
+
* Folds `source` sections INTO `target` (mutating it), identity-matched:
|
|
368
|
+
* an ISSUED entry is one `(order_id, payment_id)` bill; a RECEIVED entry is one
|
|
369
|
+
* `(order_id, payment_id, event_local_date)` collection event. A source entry
|
|
370
|
+
* REPLACES its target counterpart (fresh wins), so re-applying the same day is
|
|
371
|
+
* idempotent.
|
|
372
|
+
*
|
|
373
|
+
* Exported because the close-day plan uses the SAME merge when it rebuilds a
|
|
374
|
+
* MISSING period document from the stored day documents (a deleted period
|
|
375
|
+
* document must not be recreated from the closing day alone; see
|
|
376
|
+
* `buildTenantSalesOverviewCloseDayPlan`'s period repair).
|
|
377
|
+
*/
|
|
378
|
+
function mergeMaterializedCreditBillSections(target, source) {
|
|
379
|
+
for (const [key, section] of Object.entries(source ?? {})) {
|
|
380
|
+
const bucket = target[key] ?? (target[key] = emptySection());
|
|
381
|
+
for (const entry of section?.issued ?? []) {
|
|
382
|
+
const identity = creditBillIdentityKey(entry.order_id, entry.payment_id);
|
|
383
|
+
const index = bucket.issued.findIndex((current) => creditBillIdentityKey(current.order_id, current.payment_id) === identity);
|
|
384
|
+
if (index >= 0)
|
|
385
|
+
bucket.issued[index] = entry;
|
|
386
|
+
else
|
|
387
|
+
bucket.issued.push(entry);
|
|
388
|
+
}
|
|
389
|
+
for (const entry of section?.received ?? []) {
|
|
390
|
+
const identity = `${creditBillIdentityKey(entry.order_id, entry.payment_id)}|${entry.event_local_date}`;
|
|
391
|
+
const index = bucket.received.findIndex((current) => `${creditBillIdentityKey(current.order_id, current.payment_id)}|${current.event_local_date}` === identity);
|
|
392
|
+
if (index >= 0)
|
|
393
|
+
bucket.received[index] = entry;
|
|
394
|
+
else
|
|
395
|
+
bucket.received.push(entry);
|
|
396
|
+
}
|
|
397
|
+
}
|
|
398
|
+
}
|
|
364
399
|
/**
|
|
365
400
|
* Materializes ONE day's credit documents from its resolution — the
|
|
366
401
|
* month-capped scope set (`MATERIALIZED_CREDIT_BILLS_SCOPES`): one document per
|
|
@@ -371,6 +406,7 @@ function buildMaterializedCreditBillDayReports(input) {
|
|
|
371
406
|
if (input == null)
|
|
372
407
|
return null;
|
|
373
408
|
const { tenantId, brandId, localDate, resolution, computedAt } = input;
|
|
409
|
+
const sourceInputSignature = input.sourceInputSignature ?? undefined;
|
|
374
410
|
const periodFields = (0, scope_helpers_1.getMaterializedPeriodScopeFields)(localDate);
|
|
375
411
|
if (periodFields == null)
|
|
376
412
|
return null;
|
|
@@ -440,6 +476,7 @@ function buildMaterializedCreditBillDayReports(input) {
|
|
|
440
476
|
iteration: 1,
|
|
441
477
|
schema_version: materialized_credit_bills_1.MATERIALIZED_CREDIT_BILLS_SCHEMA_VERSION,
|
|
442
478
|
source_watermark: sourceWatermark,
|
|
479
|
+
source_input_signature: sourceInputSignature,
|
|
443
480
|
computed_at: computedAt,
|
|
444
481
|
createdAt: computedAt,
|
|
445
482
|
updatedAt: computedAt,
|
|
@@ -540,25 +577,7 @@ function updateMaterializedCreditBillsReport(existing, updates, options = {}) {
|
|
|
540
577
|
}
|
|
541
578
|
}
|
|
542
579
|
for (const delta of updates.additions ?? []) {
|
|
543
|
-
|
|
544
|
-
const target = sections[key] ?? (sections[key] = emptySection());
|
|
545
|
-
for (const entry of section.issued) {
|
|
546
|
-
const identity = creditBillIdentityKey(entry.order_id, entry.payment_id);
|
|
547
|
-
const index = target.issued.findIndex((current) => creditBillIdentityKey(current.order_id, current.payment_id) === identity);
|
|
548
|
-
if (index >= 0)
|
|
549
|
-
target.issued[index] = entry;
|
|
550
|
-
else
|
|
551
|
-
target.issued.push(entry);
|
|
552
|
-
}
|
|
553
|
-
for (const entry of section.received) {
|
|
554
|
-
const identity = `${creditBillIdentityKey(entry.order_id, entry.payment_id)}|${entry.event_local_date}`;
|
|
555
|
-
const index = target.received.findIndex((current) => `${creditBillIdentityKey(current.order_id, current.payment_id)}|${current.event_local_date}` === identity);
|
|
556
|
-
if (index >= 0)
|
|
557
|
-
target.received[index] = entry;
|
|
558
|
-
else
|
|
559
|
-
target.received.push(entry);
|
|
560
|
-
}
|
|
561
|
-
}
|
|
580
|
+
mergeMaterializedCreditBillSections(sections, toMutableSections(delta.credit_bills));
|
|
562
581
|
}
|
|
563
582
|
for (const delta of updates.additions ?? []) {
|
|
564
583
|
sourceWatermark = maxDate(sourceWatermark, delta.source_watermark) ?? sourceWatermark;
|
|
@@ -591,6 +610,9 @@ function updateMaterializedCreditBillsReport(existing, updates, options = {}) {
|
|
|
591
610
|
...existing,
|
|
592
611
|
credit_bills: pruned,
|
|
593
612
|
iteration: (existing.iteration ?? 1) + (changed || ledgerPatched ? 1 : 0),
|
|
613
|
+
// A REPLACEMENT carries the freshly compiled day digest; period folds keep
|
|
614
|
+
// the stored value (their payload is a running ledger, not one day's input).
|
|
615
|
+
source_input_signature: updates.replacement?.source_input_signature ?? existing.source_input_signature,
|
|
594
616
|
source_watermark: sourceWatermark,
|
|
595
617
|
computed_at: computedAt,
|
|
596
618
|
updatedAt: computedAt,
|
|
@@ -616,7 +638,12 @@ const creditPeriodRefs = (localDate) => {
|
|
|
616
638
|
},
|
|
617
639
|
];
|
|
618
640
|
};
|
|
619
|
-
/**
|
|
641
|
+
/**
|
|
642
|
+
* `Writes the watermarks / day-input signature / schema / key-filter grammar
|
|
643
|
+
* allow a write?` (mirrors the sales-report guard). The signature is checked
|
|
644
|
+
* FIRST so a deleted / moved order still corrects the ledger when the incoming
|
|
645
|
+
* watermark regressed.
|
|
646
|
+
*/
|
|
620
647
|
const needsMaterializedCreditBillsReportWrite = (existing, incoming) => {
|
|
621
648
|
if (existing == null)
|
|
622
649
|
return true;
|
|
@@ -625,6 +652,9 @@ const needsMaterializedCreditBillsReportWrite = (existing, incoming) => {
|
|
|
625
652
|
if (JSON.stringify(existing.sale_type_key_filters ?? []) !== JSON.stringify(incoming.sale_type_key_filters ?? [])) {
|
|
626
653
|
return true;
|
|
627
654
|
}
|
|
655
|
+
if ((0, materialized_day_input_signature_1.materializedDayInputSignatureChanged)(existing.source_input_signature, incoming.source_input_signature)) {
|
|
656
|
+
return true;
|
|
657
|
+
}
|
|
628
658
|
return new Date(incoming.source_watermark).getTime() > new Date(existing.source_watermark).getTime();
|
|
629
659
|
};
|
|
630
660
|
exports.needsMaterializedCreditBillsReportWrite = needsMaterializedCreditBillsReportWrite;
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import { IOrder } from '../../schemas/types/orders';
|
|
2
|
+
/**
|
|
3
|
+
* Day-input SIGNATURE — the change-detection token of a materialized day.
|
|
4
|
+
*
|
|
5
|
+
* ## Why a watermark alone is not enough
|
|
6
|
+
*
|
|
7
|
+
* Every report document stores `source_watermark` = the MAX `orders.updatedAt`
|
|
8
|
+
* folded into it, and the close-day plans skip a document when the incoming
|
|
9
|
+
* watermark is not NEWER than the stored one. That is sound for an UPDATE of an
|
|
10
|
+
* order (its `updatedAt` advances), but it is blind to the order set SHRINKING:
|
|
11
|
+
*
|
|
12
|
+
* - delete the order that carried the maximum `updatedAt`, then re-close the
|
|
13
|
+
* day → the incoming max is LOWER than the stored watermark, the guard
|
|
14
|
+
* reports "nothing new", and the deleted order stays in every report
|
|
15
|
+
* (date/hour/period/credit/discount) forever;
|
|
16
|
+
* - move that order to another `localDate` → same regression on the old day,
|
|
17
|
+
* so the old day keeps a sale it no longer owns.
|
|
18
|
+
*
|
|
19
|
+
* The fix is a SECOND, set-shaped signal: a deterministic digest of the exact
|
|
20
|
+
* order identities (and their versions) the day was compiled from. A delete or
|
|
21
|
+
* a move changes the digest even when the watermark regresses, so the guard can
|
|
22
|
+
* trigger the corrective writes. A re-close of the SAME input reproduces the
|
|
23
|
+
* same digest, so the no-churn skip is preserved.
|
|
24
|
+
*
|
|
25
|
+
* ## Shape
|
|
26
|
+
*
|
|
27
|
+
* `v1:<count>:<hash>` where
|
|
28
|
+
* - `count` is the number of orders in the input (cheap first check);
|
|
29
|
+
* - `hash` is two independent 32-bit FNV-1a passes over the sorted
|
|
30
|
+
* `id|updatedAt` lines, emitted as 16 hex chars (a ~64-bit digest).
|
|
31
|
+
*
|
|
32
|
+
* The leading `v1:` version tag makes the value a non-numeric string, which
|
|
33
|
+
* keeps it outside the integer-only storage contract's numeric-string rule; a
|
|
34
|
+
* future algorithm change must bump the tag so old documents are re-materialized
|
|
35
|
+
* exactly once instead of being silently compared with a different digest.
|
|
36
|
+
*
|
|
37
|
+
* The digest is NOT a security primitive — it detects accidental divergence,
|
|
38
|
+
* and a full re-close always repairs the document regardless.
|
|
39
|
+
*/
|
|
40
|
+
/** Version tag of the digest algorithm; bump when the line format changes. */
|
|
41
|
+
export declare const MATERIALIZED_DAY_INPUT_SIGNATURE_VERSION = "v1";
|
|
42
|
+
/**
|
|
43
|
+
* Builds the day-input signature for the orders a materializer compiled.
|
|
44
|
+
*
|
|
45
|
+
* The caller passes the SAME array the compile used (and the same tenant
|
|
46
|
+
* filter); the digest is order-independent (lines are sorted) and idempotent
|
|
47
|
+
* (identical input → identical value). An empty input yields the stable
|
|
48
|
+
* `v1:0:<hash of ''>` value, which is deliberately DIFFERENT from "no stored
|
|
49
|
+
* signature" (`undefined`) — a legacy document with no signature is therefore
|
|
50
|
+
* rewritten once, and an order-less day keeps skipping on later re-closes.
|
|
51
|
+
*
|
|
52
|
+
* Returns `null` (never throws) when the input is not an array.
|
|
53
|
+
*/
|
|
54
|
+
export declare function buildMaterializedDayInputSignature(orders: readonly IOrder[] | null | undefined): string | null;
|
|
55
|
+
/**
|
|
56
|
+
* Does a stored / incoming signature pair require a write?
|
|
57
|
+
*
|
|
58
|
+
* - BOTH missing → `false`: neither side describes an input set (legacy
|
|
59
|
+
* fixtures / documents), so the watermark guard decides — exactly the
|
|
60
|
+
* pre-signature behaviour;
|
|
61
|
+
* - exactly ONE missing → `true`: a legacy stored document meets a compiled
|
|
62
|
+
* day (or the reverse), so the corrective write happens once;
|
|
63
|
+
* - different values → `true` (the input SET changed, e.g. a delete or move);
|
|
64
|
+
* - identical → `false` (the watermark guard then decides).
|
|
65
|
+
*/
|
|
66
|
+
export declare const materializedDayInputSignatureChanged: (stored: string | null | undefined, incoming: string | null | undefined) => boolean;
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.materializedDayInputSignatureChanged = exports.MATERIALIZED_DAY_INPUT_SIGNATURE_VERSION = void 0;
|
|
4
|
+
exports.buildMaterializedDayInputSignature = buildMaterializedDayInputSignature;
|
|
5
|
+
/**
|
|
6
|
+
* Day-input SIGNATURE — the change-detection token of a materialized day.
|
|
7
|
+
*
|
|
8
|
+
* ## Why a watermark alone is not enough
|
|
9
|
+
*
|
|
10
|
+
* Every report document stores `source_watermark` = the MAX `orders.updatedAt`
|
|
11
|
+
* folded into it, and the close-day plans skip a document when the incoming
|
|
12
|
+
* watermark is not NEWER than the stored one. That is sound for an UPDATE of an
|
|
13
|
+
* order (its `updatedAt` advances), but it is blind to the order set SHRINKING:
|
|
14
|
+
*
|
|
15
|
+
* - delete the order that carried the maximum `updatedAt`, then re-close the
|
|
16
|
+
* day → the incoming max is LOWER than the stored watermark, the guard
|
|
17
|
+
* reports "nothing new", and the deleted order stays in every report
|
|
18
|
+
* (date/hour/period/credit/discount) forever;
|
|
19
|
+
* - move that order to another `localDate` → same regression on the old day,
|
|
20
|
+
* so the old day keeps a sale it no longer owns.
|
|
21
|
+
*
|
|
22
|
+
* The fix is a SECOND, set-shaped signal: a deterministic digest of the exact
|
|
23
|
+
* order identities (and their versions) the day was compiled from. A delete or
|
|
24
|
+
* a move changes the digest even when the watermark regresses, so the guard can
|
|
25
|
+
* trigger the corrective writes. A re-close of the SAME input reproduces the
|
|
26
|
+
* same digest, so the no-churn skip is preserved.
|
|
27
|
+
*
|
|
28
|
+
* ## Shape
|
|
29
|
+
*
|
|
30
|
+
* `v1:<count>:<hash>` where
|
|
31
|
+
* - `count` is the number of orders in the input (cheap first check);
|
|
32
|
+
* - `hash` is two independent 32-bit FNV-1a passes over the sorted
|
|
33
|
+
* `id|updatedAt` lines, emitted as 16 hex chars (a ~64-bit digest).
|
|
34
|
+
*
|
|
35
|
+
* The leading `v1:` version tag makes the value a non-numeric string, which
|
|
36
|
+
* keeps it outside the integer-only storage contract's numeric-string rule; a
|
|
37
|
+
* future algorithm change must bump the tag so old documents are re-materialized
|
|
38
|
+
* exactly once instead of being silently compared with a different digest.
|
|
39
|
+
*
|
|
40
|
+
* The digest is NOT a security primitive — it detects accidental divergence,
|
|
41
|
+
* and a full re-close always repairs the document regardless.
|
|
42
|
+
*/
|
|
43
|
+
/** Version tag of the digest algorithm; bump when the line format changes. */
|
|
44
|
+
exports.MATERIALIZED_DAY_INPUT_SIGNATURE_VERSION = 'v1';
|
|
45
|
+
/** One stable line per order: identity + the version that produced its numbers. */
|
|
46
|
+
const signatureLine = (order) => {
|
|
47
|
+
const id = order._id == null ? '' : String(order._id);
|
|
48
|
+
const updatedAt = order.updatedAt == null ? '' : new Date(order.updatedAt).toISOString();
|
|
49
|
+
return `${id}|${updatedAt}`;
|
|
50
|
+
};
|
|
51
|
+
/** Two independent FNV-1a 32-bit passes over `value`, as 16 hex chars. */
|
|
52
|
+
const hashSignatureLines = (value) => {
|
|
53
|
+
let first = 0x811c9dc5;
|
|
54
|
+
let second = 0x01000193 ^ 0x9e3779b9;
|
|
55
|
+
for (let index = 0; index < value.length; index += 1) {
|
|
56
|
+
const code = value.charCodeAt(index);
|
|
57
|
+
first ^= code;
|
|
58
|
+
first = Math.imul(first, 0x01000193) >>> 0;
|
|
59
|
+
second = Math.imul(second ^ code, 0x85ebca6b) >>> 0;
|
|
60
|
+
second = (second ^ (second >>> 13)) >>> 0;
|
|
61
|
+
}
|
|
62
|
+
return `${first.toString(16).padStart(8, '0')}${second.toString(16).padStart(8, '0')}`;
|
|
63
|
+
};
|
|
64
|
+
/**
|
|
65
|
+
* Builds the day-input signature for the orders a materializer compiled.
|
|
66
|
+
*
|
|
67
|
+
* The caller passes the SAME array the compile used (and the same tenant
|
|
68
|
+
* filter); the digest is order-independent (lines are sorted) and idempotent
|
|
69
|
+
* (identical input → identical value). An empty input yields the stable
|
|
70
|
+
* `v1:0:<hash of ''>` value, which is deliberately DIFFERENT from "no stored
|
|
71
|
+
* signature" (`undefined`) — a legacy document with no signature is therefore
|
|
72
|
+
* rewritten once, and an order-less day keeps skipping on later re-closes.
|
|
73
|
+
*
|
|
74
|
+
* Returns `null` (never throws) when the input is not an array.
|
|
75
|
+
*/
|
|
76
|
+
function buildMaterializedDayInputSignature(orders) {
|
|
77
|
+
if (!Array.isArray(orders))
|
|
78
|
+
return null;
|
|
79
|
+
const lines = [];
|
|
80
|
+
for (const order of orders) {
|
|
81
|
+
if (order == null)
|
|
82
|
+
continue;
|
|
83
|
+
lines.push(signatureLine(order));
|
|
84
|
+
}
|
|
85
|
+
lines.sort();
|
|
86
|
+
return `${exports.MATERIALIZED_DAY_INPUT_SIGNATURE_VERSION}:${lines.length}:${hashSignatureLines(lines.join('\n'))}`;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Does a stored / incoming signature pair require a write?
|
|
90
|
+
*
|
|
91
|
+
* - BOTH missing → `false`: neither side describes an input set (legacy
|
|
92
|
+
* fixtures / documents), so the watermark guard decides — exactly the
|
|
93
|
+
* pre-signature behaviour;
|
|
94
|
+
* - exactly ONE missing → `true`: a legacy stored document meets a compiled
|
|
95
|
+
* day (or the reverse), so the corrective write happens once;
|
|
96
|
+
* - different values → `true` (the input SET changed, e.g. a delete or move);
|
|
97
|
+
* - identical → `false` (the watermark guard then decides).
|
|
98
|
+
*/
|
|
99
|
+
const materializedDayInputSignatureChanged = (stored, incoming) => {
|
|
100
|
+
const storedMissing = typeof stored !== 'string';
|
|
101
|
+
const incomingMissing = typeof incoming !== 'string';
|
|
102
|
+
if (storedMissing && incomingMissing)
|
|
103
|
+
return false;
|
|
104
|
+
if (storedMissing || incomingMissing)
|
|
105
|
+
return true;
|
|
106
|
+
return stored !== incoming;
|
|
107
|
+
};
|
|
108
|
+
exports.materializedDayInputSignatureChanged = materializedDayInputSignatureChanged;
|
|
@@ -93,6 +93,18 @@ export interface IBuildTenantDiscountCloseDayPlanInput {
|
|
|
93
93
|
* set; without this acknowledgement the plan refuses to guess.
|
|
94
94
|
*/
|
|
95
95
|
existingEntriesComplete?: boolean;
|
|
96
|
+
/**
|
|
97
|
+
* Stored `localDate` COUNTER documents of the same tenant (the sibling days
|
|
98
|
+
* inside the touched periods, excluding the closing day), used ONLY to
|
|
99
|
+
* rebuild a MISSING period counter document.
|
|
100
|
+
*
|
|
101
|
+
* A period counter document is a running sum. Creating it from the closing
|
|
102
|
+
* day alone would leave every earlier materialized day out of the period
|
|
103
|
+
* while those days' `localDate` documents still exist, so `localMonth` would
|
|
104
|
+
* no longer equal the sum of its days. The plan folds the siblings that
|
|
105
|
+
* belong to the created scope.
|
|
106
|
+
*/
|
|
107
|
+
existingPeriodDayDocuments?: IMaterializedTenantDiscountReport[];
|
|
96
108
|
/** Why this close is applied — stored as every history row's `reason`. */
|
|
97
109
|
reason: string;
|
|
98
110
|
/** Force structural writes even when the watermarks are up to date. */
|
|
@@ -115,6 +127,11 @@ export interface ITenantDiscountCloseDayPlan {
|
|
|
115
127
|
skippedEntryDocuments: IMaterializedTenantDiscountEntries[];
|
|
116
128
|
/** Period counter docs this close CREATED because they were absent. */
|
|
117
129
|
createdPeriodDocuments: IMaterializedDiscountScopeRef[];
|
|
130
|
+
/**
|
|
131
|
+
* Stored sibling DAY documents folded into those created period counter
|
|
132
|
+
* documents (see `existingPeriodDayDocuments`). 0 = nothing to repair.
|
|
133
|
+
*/
|
|
134
|
+
foldedPeriodDayDocuments: number;
|
|
118
135
|
}
|
|
119
136
|
/** Every stored scope one local day's plan needs (date + 3 periods + 24 hours). */
|
|
120
137
|
export declare function getMaterializedDiscountScopeRefsForDay(localDate: string): IMaterializedDiscountScopeRef[] | null;
|
|
@@ -140,7 +157,9 @@ export declare function getMaterializedDiscountPeriodDayScopeFields(localDate: s
|
|
|
140
157
|
/**
|
|
141
158
|
* Watermark guard: does the stored document need a structural write?
|
|
142
159
|
* `false` (skip) when the incoming `source_watermark` is not newer than the
|
|
143
|
-
* stored one and the schema version +
|
|
160
|
+
* stored one, the day-input SIGNATURE is unchanged, and the schema version +
|
|
161
|
+
* key grammar match. The signature catches a deleted / moved order whose
|
|
162
|
+
* removal lowered the incoming watermark.
|
|
144
163
|
*/
|
|
145
164
|
export declare function needsMaterializedDiscountReportWrite(existing: IMaterializedTenantDiscountReport | null | undefined, incoming: IMaterializedTenantDiscountReport | null | undefined): boolean;
|
|
146
165
|
/**
|