@managesome/eposmatic-toolkit 0.4.5 → 0.4.8
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 +33 -0
- package/esm/constants/REPORT_CALENDAR.js +47 -0
- package/esm/constants/index.js +1 -0
- package/esm/helpers/materialized-reports/index.js +2 -0
- package/esm/helpers/materialized-reports/materialized-credit-bills-helpers.js +982 -0
- package/esm/helpers/materialized-reports/materialized-reports-read-helpers.js +1 -76
- package/esm/helpers/materialized-reports/materialized-reports-selection-helpers.js +716 -0
- package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +327 -41
- package/esm/helpers/materialized-reports/tenant-sales-overview-formatter.js +72 -11
- package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +118 -235
- package/esm/helpers/types/index.js +1 -0
- package/esm/schemas/models/index.js +1 -0
- package/esm/schemas/models/materialized_credit_bills.js +265 -0
- package/esm/schemas/models/materialized_tenant_reports_iterations.js +13 -0
- package/esm/schemas/models/materialized_tenant_sales_overview_reports.js +39 -97
- package/esm/schemas/types/index.js +1 -0
- package/esm/schemas/types/materialized_credit_bills.js +1 -0
- package/lib/constants/MATERIALIZED_REPORTS.d.ts +28 -2
- package/lib/constants/MATERIALIZED_REPORTS.js +34 -1
- package/lib/constants/REPORT_CALENDAR.d.ts +31 -0
- package/lib/constants/REPORT_CALENDAR.js +50 -0
- package/lib/constants/index.d.ts +1 -0
- package/lib/constants/index.js +1 -0
- 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 +307 -0
- package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.js +1003 -0
- package/lib/helpers/materialized-reports/materialized-reports-read-helpers.d.ts +0 -30
- package/lib/helpers/materialized-reports/materialized-reports-read-helpers.js +0 -76
- package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.d.ts +59 -0
- package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.js +723 -0
- package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +66 -8
- package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +326 -40
- package/lib/helpers/materialized-reports/tenant-sales-overview-formatter.d.ts +18 -2
- package/lib/helpers/materialized-reports/tenant-sales-overview-formatter.js +72 -11
- package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.d.ts +46 -37
- package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +119 -238
- package/lib/helpers/types/index.d.ts +1 -0
- package/lib/helpers/types/index.js +1 -0
- package/lib/helpers/types/materialized-reports-apis.d.ts +46 -17
- package/lib/helpers/types/report-calendar.d.ts +20 -0
- package/lib/helpers/types/report-calendar.js +2 -0
- package/lib/schemas/models/index.d.ts +1 -0
- package/lib/schemas/models/index.js +1 -0
- package/lib/schemas/models/materialized_credit_bills.d.ts +337 -0
- package/lib/schemas/models/materialized_credit_bills.js +268 -0
- package/lib/schemas/models/materialized_tenant_reports_iterations.d.ts +20 -6
- package/lib/schemas/models/materialized_tenant_reports_iterations.js +14 -1
- package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +37 -165
- package/lib/schemas/models/materialized_tenant_sales_overview_reports.js +40 -98
- package/lib/schemas/types/index.d.ts +1 -0
- package/lib/schemas/types/index.js +1 -0
- package/lib/schemas/types/materialized_credit_bills.d.ts +139 -0
- package/lib/schemas/types/materialized_credit_bills.js +2 -0
- package/lib/schemas/types/materialized_tenant_sales_overview_reports.d.ts +32 -77
- package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.d.ts +1 -0
- package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.js +715 -0
- package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.d.ts +1 -0
- package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.js +262 -0
- package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-schema.test.js +9 -0
- package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.js +23 -24
- package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +327 -22
- package/lib/tests/materialized-reports/tenant-sales-overview-formatter-aggregated.test.js +27 -2
- package/lib/tests/materialized-reports/tenant-sales-overview-formatter.test.js +12 -27
- package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +79 -146
- package/package.json +1 -1
- package/lib/tests/materialized-reports/materialized-reports-read-helpers.test.js +0 -100
- /package/{lib/tests/materialized-reports/materialized-reports-read-helpers.test.d.ts → esm/helpers/types/report-calendar.js} +0 -0
|
@@ -93,7 +93,7 @@ const pruneMetricsMap = (keyFilters, metrics, filters) => {
|
|
|
93
93
|
}
|
|
94
94
|
return kept;
|
|
95
95
|
};
|
|
96
|
-
/** Drops non-matching keys from a document's metric map (
|
|
96
|
+
/** Drops non-matching keys from a document's metric map (credit counters included). */
|
|
97
97
|
const pruneReportForFilters = (doc, filters) => {
|
|
98
98
|
const kept = pruneMetricsMap(doc.sale_type_key_filters ?? [], doc.sale_type_metrics, filters);
|
|
99
99
|
return { ...doc, sale_type_metrics: kept };
|
|
@@ -180,7 +180,12 @@ const buildEmptyPageData = (scopeContext, tenantIds) => ({
|
|
|
180
180
|
credit_bills: {
|
|
181
181
|
issued: { count: 0, amount: 0, settled_count: 0, settled_amount: 0 },
|
|
182
182
|
received: { count: 0, amount: 0 },
|
|
183
|
+
outstanding_count: 0,
|
|
183
184
|
outstanding_amount: 0,
|
|
185
|
+
outstanding_now_count: 0,
|
|
186
|
+
outstanding_now_amount: 0,
|
|
187
|
+
collected_at_issue_count: 0,
|
|
188
|
+
collected_at_issue_amount: 0,
|
|
184
189
|
},
|
|
185
190
|
weekday: scopeContext != null && MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX.includes(scopeContext) ? [] : null,
|
|
186
191
|
hourly: scopeContext === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_HOUR ? [] : null,
|
|
@@ -256,6 +261,7 @@ const buildPageDataForDocs = (docs, scopeContext, filters) => {
|
|
|
256
261
|
const supportsDayIndex = scopeContext != null && MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX.includes(scopeContext);
|
|
257
262
|
return buildPageDataFromMetrics(merged, tenantIds, supportsDayIndex ? buildWeekdaySection(scopedDocs, filters) : null, scopeContext === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_HOUR ? buildHourlySection(scopedDocs, filters) : null);
|
|
258
263
|
};
|
|
264
|
+
const creditLedgerCountersOf = (entry) => entry[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS] ?? {};
|
|
259
265
|
/**
|
|
260
266
|
* Shared page assembly — identical for the raw read (one merged document) and
|
|
261
267
|
* the AGGREGATED read (one pipeline record): every section derives from the
|
|
@@ -270,7 +276,18 @@ const buildPageDataFromMetrics = (merged, tenantIds, weekday, hourly) => {
|
|
|
270
276
|
const cancelledRaw = createRawOrderMetric();
|
|
271
277
|
const paymentsMap = {};
|
|
272
278
|
const channelsMap = {};
|
|
273
|
-
const issuedRaw = {
|
|
279
|
+
const issuedRaw = {
|
|
280
|
+
count: 0,
|
|
281
|
+
amount: 0,
|
|
282
|
+
settled_count: 0,
|
|
283
|
+
settled_amount: 0,
|
|
284
|
+
outstanding_count: 0,
|
|
285
|
+
outstanding_amount: 0,
|
|
286
|
+
outstanding_now_count: 0,
|
|
287
|
+
outstanding_now_amount: 0,
|
|
288
|
+
collected_at_issue_count: 0,
|
|
289
|
+
collected_at_issue_amount: 0,
|
|
290
|
+
};
|
|
274
291
|
const receivedRaw = { count: 0, amount: 0 };
|
|
275
292
|
for (const [key, entry] of Object.entries(merged.sale_type_metrics ?? {})) {
|
|
276
293
|
const components = (0, key_helpers_1.parseMaterializedReportKey)(key);
|
|
@@ -278,7 +295,7 @@ const buildPageDataFromMetrics = (merged, tenantIds, weekday, hourly) => {
|
|
|
278
295
|
continue;
|
|
279
296
|
const totalSales = entry[constants_1.REPORT_SALE_TYPE_ENUM.TOTAL_SALES];
|
|
280
297
|
const amountCollected = entry[constants_1.REPORT_SALE_TYPE_ENUM.AMOUNT_COLLECTED];
|
|
281
|
-
const creditBills = entry
|
|
298
|
+
const creditBills = creditLedgerCountersOf(entry);
|
|
282
299
|
// Cancelled facet: cancelled orders are materialized under `CANCELLED:*`
|
|
283
300
|
// keys and excluded from every other facet (payments included).
|
|
284
301
|
if (isCancelledKey(components, keyFilters)) {
|
|
@@ -290,12 +307,30 @@ const buildPageDataFromMetrics = (merged, tenantIds, weekday, hourly) => {
|
|
|
290
307
|
for (const payment of totalSales?.payments ?? []) {
|
|
291
308
|
addRawPayment(paymentsMap, payment);
|
|
292
309
|
}
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
310
|
+
const issuedCounters = creditBills.issued ?? {};
|
|
311
|
+
const receivedCounters = creditBills.received ?? {};
|
|
312
|
+
// Stored documents carry COUNTERS only (the itemized ledger lives in
|
|
313
|
+
// `materialized_tenant_credit_bills`) — sum them per KEPT key (client-side
|
|
314
|
+
// filters included). Range-pure extras (`outstanding*`,
|
|
315
|
+
// `collected_at_issue_*`) ride only on AGGREGATED records; stored
|
|
316
|
+
// documents fall back to the ever-settled / zero basis (direct-
|
|
317
|
+
// inspection seam only — the aggregation is the canonical read).
|
|
318
|
+
issuedRaw.count += issuedCounters.count ?? 0;
|
|
319
|
+
issuedRaw.amount += issuedCounters.amount ?? 0;
|
|
320
|
+
issuedRaw.settled_count += issuedCounters.settled_count ?? 0;
|
|
321
|
+
issuedRaw.settled_amount += issuedCounters.settled_amount ?? 0;
|
|
322
|
+
const outstandingCountFallback = Math.max(0, (issuedCounters.count ?? 0) - (issuedCounters.settled_count ?? 0));
|
|
323
|
+
const outstandingAmountFallback = Math.max(0, (issuedCounters.amount ?? 0) - (issuedCounters.settled_amount ?? 0));
|
|
324
|
+
issuedRaw.outstanding_count += issuedCounters.outstanding_count ?? outstandingCountFallback;
|
|
325
|
+
issuedRaw.outstanding_amount += issuedCounters.outstanding_amount ?? outstandingAmountFallback;
|
|
326
|
+
issuedRaw.outstanding_now_count +=
|
|
327
|
+
issuedCounters.outstanding_now_count ?? issuedCounters.outstanding_count ?? outstandingCountFallback;
|
|
328
|
+
issuedRaw.outstanding_now_amount +=
|
|
329
|
+
issuedCounters.outstanding_now_amount ?? issuedCounters.outstanding_amount ?? outstandingAmountFallback;
|
|
330
|
+
issuedRaw.collected_at_issue_count += issuedCounters.collected_at_issue_count ?? 0;
|
|
331
|
+
issuedRaw.collected_at_issue_amount += issuedCounters.collected_at_issue_amount ?? 0;
|
|
332
|
+
receivedRaw.count += receivedCounters.count ?? 0;
|
|
333
|
+
receivedRaw.amount += receivedCounters.amount ?? 0;
|
|
299
334
|
const platform = getKeyDimValue(components, keyFilters, MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_KEY_FILTER_ENUM.PLATFORM) ?? '';
|
|
300
335
|
const channel = channelsMap[platform] ?? (channelsMap[platform] = { platform, count: 0, gross_amount: 0 });
|
|
301
336
|
channel.count += totalSales?.orders?.count ?? 0;
|
|
@@ -338,7 +373,12 @@ const buildPageDataFromMetrics = (merged, tenantIds, weekday, hourly) => {
|
|
|
338
373
|
settled_amount: toDecimal(issuedRaw.settled_amount),
|
|
339
374
|
},
|
|
340
375
|
received: { count: receivedRaw.count, amount: toDecimal(receivedRaw.amount) },
|
|
341
|
-
|
|
376
|
+
outstanding_count: issuedRaw.outstanding_count,
|
|
377
|
+
outstanding_amount: toDecimal(issuedRaw.outstanding_amount),
|
|
378
|
+
outstanding_now_count: issuedRaw.outstanding_now_count,
|
|
379
|
+
outstanding_now_amount: toDecimal(issuedRaw.outstanding_now_amount),
|
|
380
|
+
collected_at_issue_count: issuedRaw.collected_at_issue_count,
|
|
381
|
+
collected_at_issue_amount: toDecimal(issuedRaw.collected_at_issue_amount),
|
|
342
382
|
},
|
|
343
383
|
weekday,
|
|
344
384
|
hourly,
|
|
@@ -411,7 +451,18 @@ const mergeAggregatedKeyMetrics = (reports) => {
|
|
|
411
451
|
[TOTAL_SALES]: { orders: createRawOrderMetric(), payments: [] },
|
|
412
452
|
[AMOUNT_COLLECTED]: { orders: createRawOrderMetric() },
|
|
413
453
|
[CREDIT_BILLS]: {
|
|
414
|
-
issued: {
|
|
454
|
+
issued: {
|
|
455
|
+
count: 0,
|
|
456
|
+
amount: 0,
|
|
457
|
+
settled_count: 0,
|
|
458
|
+
settled_amount: 0,
|
|
459
|
+
outstanding_count: 0,
|
|
460
|
+
outstanding_amount: 0,
|
|
461
|
+
outstanding_now_count: 0,
|
|
462
|
+
outstanding_now_amount: 0,
|
|
463
|
+
collected_at_issue_count: 0,
|
|
464
|
+
collected_at_issue_amount: 0,
|
|
465
|
+
},
|
|
415
466
|
received: { count: 0, amount: 0 },
|
|
416
467
|
},
|
|
417
468
|
});
|
|
@@ -424,6 +475,16 @@ const mergeAggregatedKeyMetrics = (reports) => {
|
|
|
424
475
|
entry[CREDIT_BILLS].issued.amount += metrics[CREDIT_BILLS]?.issued?.amount ?? 0;
|
|
425
476
|
entry[CREDIT_BILLS].issued.settled_count += metrics[CREDIT_BILLS]?.issued?.settled_count ?? 0;
|
|
426
477
|
entry[CREDIT_BILLS].issued.settled_amount += metrics[CREDIT_BILLS]?.issued?.settled_amount ?? 0;
|
|
478
|
+
entry[CREDIT_BILLS].issued.outstanding_count += metrics[CREDIT_BILLS]?.issued?.outstanding_count ?? 0;
|
|
479
|
+
entry[CREDIT_BILLS].issued.outstanding_amount += metrics[CREDIT_BILLS]?.issued?.outstanding_amount ?? 0;
|
|
480
|
+
entry[CREDIT_BILLS].issued.outstanding_now_count += metrics[CREDIT_BILLS]?.issued?.outstanding_now_count ?? 0;
|
|
481
|
+
entry[CREDIT_BILLS].issued.outstanding_now_amount += metrics[CREDIT_BILLS]?.issued?.outstanding_now_amount ?? 0;
|
|
482
|
+
// At-issue money rides as a COUNTER on aggregated records (derived from
|
|
483
|
+
// the ledger rows server-side); stored documents degrade to 0.
|
|
484
|
+
entry[CREDIT_BILLS].issued.collected_at_issue_count +=
|
|
485
|
+
metrics[CREDIT_BILLS]?.issued?.collected_at_issue_count ?? 0;
|
|
486
|
+
entry[CREDIT_BILLS].issued.collected_at_issue_amount +=
|
|
487
|
+
metrics[CREDIT_BILLS]?.issued?.collected_at_issue_amount ?? 0;
|
|
427
488
|
entry[CREDIT_BILLS].received.count += metrics[CREDIT_BILLS]?.received?.count ?? 0;
|
|
428
489
|
entry[CREDIT_BILLS].received.amount += metrics[CREDIT_BILLS]?.received?.amount ?? 0;
|
|
429
490
|
}
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import mongoose from 'mongoose';
|
|
2
2
|
import { IOrder, IOrderPayment } from '../../schemas';
|
|
3
|
-
import { IMaterializedReportKeyMetrics,
|
|
3
|
+
import { IMaterializedReportKeyMetrics, IMaterializedTenantSalesOverviewReport } from '../../schemas/types/materialized_tenant_sales_overview_reports';
|
|
4
|
+
import { ICreditBillEventCandidate, ICreditBillIssuedCandidate, isMaterializedCreditBillPayment } from './materialized-credit-bills-helpers';
|
|
4
5
|
/**
|
|
5
6
|
* Backend materialization helpers for `materialized_tenant_sales_overview_reports`
|
|
6
7
|
* (see `MATERIALIZED_REPORTS.md` "Backend materialization cycle").
|
|
@@ -9,11 +10,14 @@ import { IMaterializedReportKeyMetrics, IMaterializedReportReceivedCreditBill, I
|
|
|
9
10
|
*
|
|
10
11
|
* 1. **JSON building** — `convertOrdersToMaterializedTenantSalesOverviewReports`
|
|
11
12
|
* compiles one tenant-day of raw orders into plain-JSON scope documents
|
|
12
|
-
* (24h-hour + period scopes) plus the credit
|
|
13
|
+
* (24h-hour + period scopes) plus the credit-bill ledger CANDIDATES
|
|
14
|
+
* collected that day (`credit_bill_issues` + `credit_bill_events` — the
|
|
15
|
+
* close-day plan resolves them and materializes both the report counters
|
|
16
|
+
* and `materialized_tenant_credit_bills` from that ONE resolution).
|
|
13
17
|
* `sumMaterializedTenantSalesOverviewReports` accumulates those into
|
|
14
18
|
* longer-period documents (week → year) and
|
|
15
19
|
* `updateMaterializedTenantSalesOverviewReport` patches an existing document
|
|
16
|
-
* (delta amounts
|
|
20
|
+
* (delta amounts).
|
|
17
21
|
* 2. **Persistence** — `convertMaterializedTenantSalesOverviewReportJsonToBson`
|
|
18
22
|
* casts a JSON document through the mongoose schema so the job can upsert it.
|
|
19
23
|
*
|
|
@@ -24,7 +28,7 @@ import { IMaterializedReportKeyMetrics, IMaterializedReportReceivedCreditBill, I
|
|
|
24
28
|
* - orders are attributed to the tenant-local BUSINESS day held by
|
|
25
29
|
* `order.localDate` (falls back to the `localDate` argument when absent);
|
|
26
30
|
* orders whose business day differs from the day being compiled only
|
|
27
|
-
* produce `
|
|
31
|
+
* produce `credit_bill_events` (credit-bill collections), never sales;
|
|
28
32
|
* - hour buckets: SALES orders use the punch hour (`order.localHour` →
|
|
29
33
|
* `gmtOffset` → `order_settled_at_mins ÷ 60`); credit-bill COLLECTION
|
|
30
34
|
* events use the SETTLEMENT hour (`gmtOffset` + `order_settled_at` →
|
|
@@ -33,13 +37,14 @@ import { IMaterializedReportKeyMetrics, IMaterializedReportReceivedCreditBill, I
|
|
|
33
37
|
* - INPUT CONTRACT: pass plain JSON documents (`.lean()` recommended). A
|
|
34
38
|
* hydrated document's map-cast `sale_type_metrics` is normalized
|
|
35
39
|
* defensively, but its other mongoose internals are not supported;
|
|
36
|
-
* -
|
|
37
|
-
* `
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
40
|
+
* - credit bills (`PAY_LATER`): these documents store COUNTERS ONLY (the
|
|
41
|
+
* `issued` / `settled` / `received` numbers — constant size, no bill rows
|
|
42
|
+
* or ids). The ITEMIZED ledger lives in the SHARED
|
|
43
|
+
* `materialized_tenant_credit_bills` collection: the compile emits
|
|
44
|
+
* `credit_bill_issues` (issue candidates) + `credit_bill_events`
|
|
45
|
+
* (collection candidates) for the close-day plan to resolve — the plan then
|
|
46
|
+
* materializes the credit documents and patches the issue-day documents'
|
|
47
|
+
* SETTLED counters from the same resolution;
|
|
43
48
|
* - cancelled orders are materialized fully under their `CANCELLED:*` keys —
|
|
44
49
|
* the read layer excludes them for TOTAL_SALES parity and derives the
|
|
45
50
|
* Cancelled facet from those keys;
|
|
@@ -77,7 +82,10 @@ export interface IConvertOrdersToMaterializedReportsOptions {
|
|
|
77
82
|
/** Result of a tenant-day compile. */
|
|
78
83
|
export interface IConvertOrdersToMaterializedReportsResult {
|
|
79
84
|
materializedReports: IMaterializedTenantSalesOverviewReport[];
|
|
80
|
-
|
|
85
|
+
/** Issue candidates for `materialized_tenant_credit_bills` (resolved by the close plan). */
|
|
86
|
+
credit_bill_issues: ICreditBillIssuedCandidate[];
|
|
87
|
+
/** Receipt-event candidates for `materialized_tenant_credit_bills` (resolved by the close plan). */
|
|
88
|
+
credit_bill_events: ICreditBillEventCandidate[];
|
|
81
89
|
}
|
|
82
90
|
/** `PAY_LATER` is reported as `UNPAID` (live-aggregation behavior). */
|
|
83
91
|
export declare function normalizeMaterializedPaymentType(paymentType: string): string;
|
|
@@ -94,8 +102,7 @@ export declare function isPaymentIncludedInMaterializedSalesOverview(payment: IO
|
|
|
94
102
|
* - refunded: negative — `-amount_due` for UNPAID, else `-amount_refunded`.
|
|
95
103
|
*/
|
|
96
104
|
export declare function getMaterializedPaymentGross(payment: IOrderPayment): number;
|
|
97
|
-
|
|
98
|
-
export declare function isMaterializedCreditBillPayment(payment: IOrderPayment): boolean;
|
|
105
|
+
export { isMaterializedCreditBillPayment };
|
|
99
106
|
/**
|
|
100
107
|
* Plain-record view of a report's `sale_type_metrics`. The schema stores the
|
|
101
108
|
* map as a mongoose `Map` of subdocuments, so a hydrated document
|
|
@@ -142,10 +149,9 @@ export declare function convertMaterializedTenantSalesOverviewReportJsonToBson(r
|
|
|
142
149
|
* the period document (month / quarter / year …) FIRST so the result keeps its
|
|
143
150
|
* identity while day documents are accumulated into it.
|
|
144
151
|
*
|
|
145
|
-
* Metric trees are summed per key
|
|
146
|
-
*
|
|
147
|
-
*
|
|
148
|
-
* overlapping compiles never double-count.
|
|
152
|
+
* Metric trees are summed per key — including the credit-bill COUNTERS
|
|
153
|
+
* (`issued` / `settled` / `received` numbers; the itemized ledger lives in
|
|
154
|
+
* `materialized_tenant_credit_bills` and is not part of these documents).
|
|
149
155
|
*
|
|
150
156
|
* Returns `null` (never throws) when the inputs cannot be summed — empty list
|
|
151
157
|
* or mismatched tenant / brand / schema version / key filters. `null` means a
|
|
@@ -164,8 +170,9 @@ export declare function sumMaterializedTenantSalesOverviewReports(reports: IMate
|
|
|
164
170
|
* the stored `localDate` doc of day D IS the delta previously folded into the
|
|
165
171
|
* period docs.
|
|
166
172
|
*
|
|
167
|
-
*
|
|
168
|
-
*
|
|
173
|
+
* Credit-bill counters are subtracted numerically (numbers only — these
|
|
174
|
+
* documents carry no bill rows). Returns `null` (never throws) on mismatched
|
|
175
|
+
* inputs.
|
|
169
176
|
*/
|
|
170
177
|
export declare function subtractMaterializedTenantSalesOverviewReports(minuend: IMaterializedTenantSalesOverviewReport, subtrahend: IMaterializedTenantSalesOverviewReport): IMaterializedTenantSalesOverviewReport | null;
|
|
171
178
|
/** Update descriptor of `updateMaterializedTenantSalesOverviewReport`. */
|
|
@@ -188,16 +195,18 @@ export interface IUpdateMaterializedTenantSalesOverviewReportInput {
|
|
|
188
195
|
*/
|
|
189
196
|
additions?: IMaterializedTenantSalesOverviewReport[];
|
|
190
197
|
/**
|
|
191
|
-
* Credit-bill
|
|
192
|
-
*
|
|
193
|
-
*
|
|
194
|
-
* `
|
|
195
|
-
*
|
|
196
|
-
*
|
|
197
|
-
*
|
|
198
|
-
* row), a no-op patch bumps nothing.
|
|
198
|
+
* Credit-bill SETTLEMENT counter patches (numbers only — the itemized
|
|
199
|
+
* ledger lives in `materialized_tenant_credit_bills`): for every entry whose key
|
|
200
|
+
* exists on this document, `issued.settled_count` increases by 1 and
|
|
201
|
+
* `issued.settled_amount` by `amount` — the close-day plan emits an entry
|
|
202
|
+
* ONLY on the stored ledger's unsettled→settled transition, so replays
|
|
203
|
+
* emit nothing and the patch stays idempotent. A changing patch is a
|
|
204
|
+
* versioned write (bumps `iteration` — append its history row).
|
|
199
205
|
*/
|
|
200
|
-
|
|
206
|
+
settled_credit_bills?: {
|
|
207
|
+
key: string;
|
|
208
|
+
amount: number;
|
|
209
|
+
}[];
|
|
201
210
|
}
|
|
202
211
|
/**
|
|
203
212
|
* Versioned write on an existing JSON report (never throws; `null` on
|
|
@@ -206,15 +215,15 @@ export interface IUpdateMaterializedTenantSalesOverviewReportInput {
|
|
|
206
215
|
* 1. metrics: `replacement` swaps the tree wholesale (day/hour docs);
|
|
207
216
|
* otherwise `subtract` first (previously applied deltas), then `additions`
|
|
208
217
|
* (newly calculated ones) — the reconcile/retry pattern;
|
|
209
|
-
* 2. `
|
|
210
|
-
*
|
|
211
|
-
*
|
|
212
|
-
* `received_amount >= amount`);
|
|
218
|
+
* 2. `settled_credit_bills` patches the SETTLED counters of matching keys
|
|
219
|
+
* (`settled_count` +1 / `settled_amount` + `amount` — counters only, the
|
|
220
|
+
* itemized ledger lives in `materialized_tenant_credit_bills`);
|
|
213
221
|
* 3. versioning: metric writes (`replacement` / `subtract` / `additions`) AND
|
|
214
|
-
*
|
|
215
|
-
* returned document is recorded as a
|
|
216
|
-
* row by the caller
|
|
217
|
-
* patches bump nothing,
|
|
222
|
+
* settlement counter patches that change the counters bump `iteration` —
|
|
223
|
+
* the returned document is recorded as a
|
|
224
|
+
* `materialized_tenant_reports_iterations` row by the caller
|
|
225
|
+
* (`buildMaterializedTenantReportIteration`); no-op patches bump nothing,
|
|
226
|
+
* so replays stay churn-free;
|
|
218
227
|
* 4. `source_watermark` advances to the max of the existing and the incoming
|
|
219
228
|
* (`replacement` / `additions`) watermarks — monotonic, never regressed
|
|
220
229
|
* (rollbacks / replays keep the previously folded maximum).
|