@managesome/eposmatic-toolkit 0.4.51 → 0.4.53

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +106 -2
  2. package/esm/constants/enums/delivery.js +13 -0
  3. package/esm/helpers/materialized-reports/index.js +5 -0
  4. package/esm/helpers/materialized-reports/materialized-delivery-accumulator-helpers.js +8 -62
  5. package/esm/helpers/materialized-reports/materialized-delivery-classification-helpers.js +95 -73
  6. package/esm/helpers/materialized-reports/materialized-delivery-close-day-helpers.js +118 -146
  7. package/esm/helpers/materialized-reports/materialized-delivery-compile-helpers.js +304 -71
  8. package/esm/helpers/materialized-reports/materialized-delivery-entry-pages.js +307 -0
  9. package/esm/helpers/materialized-reports/materialized-delivery-index-migration.js +103 -0
  10. package/esm/helpers/materialized-reports/materialized-delivery-rows.js +109 -0
  11. package/esm/helpers/materialized-reports/materialized-delivery-wipe-targets.js +32 -0
  12. package/esm/helpers/materialized-reports/materialized-document-size.js +65 -0
  13. package/esm/helpers/materialized-reports/materialized-index-bootstrap.js +31 -16
  14. package/esm/helpers/materialized-reports/materialized-integer-contract.js +10 -1
  15. package/esm/helpers/materialized-reports/materialized-prep-time-close-day-helpers.js +3 -91
  16. package/esm/helpers/materialized-reports/materialized-tenant-delivery-geo-helpers.js +597 -0
  17. package/esm/helpers/materialized-reports/scope-helpers.js +98 -0
  18. package/esm/helpers/materialized-reports/tenant-delivery-formatter.js +70 -20
  19. package/esm/helpers/utils/offer-item-resolution.js +39 -0
  20. package/esm/schemas/models/index.js +12 -10
  21. package/esm/schemas/models/materialized_tenant_delivery_entries.js +33 -12
  22. package/esm/schemas/models/materialized_tenant_delivery_geo_cells.js +83 -0
  23. package/esm/schemas/models/materialized_tenant_delivery_geo_scopes.js +35 -0
  24. package/esm/schemas/models/materialized_tenant_delivery_reports.js +10 -1
  25. package/esm/schemas/types/index.js +14 -12
  26. package/esm/schemas/types/materialized_tenant_delivery_geo_cells.js +1 -0
  27. package/esm/schemas/types/materialized_tenant_delivery_geo_scopes.js +1 -0
  28. package/lib/constants/MATERIALIZED_REPORTS.d.ts +95 -1
  29. package/lib/constants/MATERIALIZED_REPORTS.js +108 -4
  30. package/lib/constants/enums/delivery.d.ts +9 -0
  31. package/lib/constants/enums/delivery.js +14 -1
  32. package/lib/helpers/materialized-reports/index.d.ts +5 -0
  33. package/lib/helpers/materialized-reports/index.js +5 -0
  34. package/lib/helpers/materialized-reports/materialized-delivery-accumulator-helpers.js +8 -62
  35. package/lib/helpers/materialized-reports/materialized-delivery-classification-helpers.d.ts +36 -9
  36. package/lib/helpers/materialized-reports/materialized-delivery-classification-helpers.js +94 -72
  37. package/lib/helpers/materialized-reports/materialized-delivery-close-day-helpers.d.ts +23 -26
  38. package/lib/helpers/materialized-reports/materialized-delivery-close-day-helpers.js +121 -150
  39. package/lib/helpers/materialized-reports/materialized-delivery-compile-helpers.d.ts +44 -5
  40. package/lib/helpers/materialized-reports/materialized-delivery-compile-helpers.js +306 -69
  41. package/lib/helpers/materialized-reports/materialized-delivery-entry-pages.d.ts +128 -0
  42. package/lib/helpers/materialized-reports/materialized-delivery-entry-pages.js +322 -0
  43. package/lib/helpers/materialized-reports/materialized-delivery-index-migration.d.ts +48 -0
  44. package/lib/helpers/materialized-reports/materialized-delivery-index-migration.js +108 -0
  45. package/lib/helpers/materialized-reports/materialized-delivery-rows.d.ts +15 -0
  46. package/lib/helpers/materialized-reports/materialized-delivery-rows.js +115 -0
  47. package/lib/helpers/materialized-reports/materialized-delivery-wipe-targets.d.ts +17 -0
  48. package/lib/helpers/materialized-reports/materialized-delivery-wipe-targets.js +35 -0
  49. package/lib/helpers/materialized-reports/materialized-document-size.d.ts +47 -0
  50. package/lib/helpers/materialized-reports/materialized-document-size.js +73 -0
  51. package/lib/helpers/materialized-reports/materialized-index-bootstrap.js +28 -13
  52. package/lib/helpers/materialized-reports/materialized-integer-contract.js +10 -1
  53. package/lib/helpers/materialized-reports/materialized-prep-time-close-day-helpers.js +2 -90
  54. package/lib/helpers/materialized-reports/materialized-tenant-delivery-geo-helpers.d.ts +186 -0
  55. package/lib/helpers/materialized-reports/materialized-tenant-delivery-geo-helpers.js +620 -0
  56. package/lib/helpers/materialized-reports/scope-helpers.d.ts +8 -0
  57. package/lib/helpers/materialized-reports/scope-helpers.js +99 -0
  58. package/lib/helpers/materialized-reports/tenant-delivery-formatter.d.ts +41 -0
  59. package/lib/helpers/materialized-reports/tenant-delivery-formatter.js +70 -20
  60. package/lib/helpers/utils/offer-item-resolution.d.ts +28 -0
  61. package/lib/helpers/utils/offer-item-resolution.js +41 -0
  62. package/lib/schemas/models/index.d.ts +12 -10
  63. package/lib/schemas/models/index.js +12 -10
  64. package/lib/schemas/models/materialized_tenant_delivery_entries.d.ts +31 -9
  65. package/lib/schemas/models/materialized_tenant_delivery_entries.js +32 -11
  66. package/lib/schemas/models/materialized_tenant_delivery_geo_cells.d.ts +129 -0
  67. package/lib/schemas/models/materialized_tenant_delivery_geo_cells.js +86 -0
  68. package/lib/schemas/models/materialized_tenant_delivery_geo_scopes.d.ts +71 -0
  69. package/lib/schemas/models/materialized_tenant_delivery_geo_scopes.js +38 -0
  70. package/lib/schemas/models/materialized_tenant_delivery_reports.d.ts +10 -1
  71. package/lib/schemas/models/materialized_tenant_delivery_reports.js +10 -1
  72. package/lib/schemas/models/materialized_tenant_discount_sources.d.ts +15 -15
  73. package/lib/schemas/types/index.d.ts +14 -12
  74. package/lib/schemas/types/index.js +14 -12
  75. package/lib/schemas/types/materialized_tenant_delivery_entries.d.ts +36 -4
  76. package/lib/schemas/types/materialized_tenant_delivery_geo_cells.d.ts +178 -0
  77. package/lib/schemas/types/materialized_tenant_delivery_geo_cells.js +2 -0
  78. package/lib/schemas/types/materialized_tenant_delivery_geo_scopes.d.ts +21 -0
  79. package/lib/schemas/types/materialized_tenant_delivery_geo_scopes.js +2 -0
  80. package/lib/schemas/types/materialized_tenant_delivery_reports.d.ts +49 -7
  81. package/lib/tests/materialized-reports/materialized-delivery-accumulation.test.js +56 -19
  82. package/lib/tests/materialized-reports/materialized-delivery-budgets.test.d.ts +1 -0
  83. package/lib/tests/materialized-reports/materialized-delivery-budgets.test.js +91 -0
  84. package/lib/tests/materialized-reports/materialized-delivery-compile.test.js +271 -15
  85. package/lib/tests/materialized-reports/materialized-delivery-final-audit.test.d.ts +1 -0
  86. package/lib/tests/materialized-reports/materialized-delivery-final-audit.test.js +128 -0
  87. package/lib/tests/materialized-reports/materialized-delivery-fold.test.js +42 -5
  88. package/lib/tests/materialized-reports/materialized-delivery-formatter.test.js +13 -1
  89. package/lib/tests/materialized-reports/materialized-delivery-geo.test.d.ts +1 -0
  90. package/lib/tests/materialized-reports/materialized-delivery-geo.test.js +446 -0
  91. package/lib/tests/materialized-reports/materialized-delivery-plan.test.js +117 -25
  92. package/lib/tests/materialized-reports/materialized-delivery-practical.test.d.ts +1 -0
  93. package/lib/tests/materialized-reports/materialized-delivery-practical.test.js +344 -0
  94. package/lib/tests/materialized-reports/materialized-integer-contract.test.js +14 -0
  95. package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.js +1 -1
  96. package/lib/tests/offer-item-resolution.test.js +57 -0
  97. package/package.json +4 -2
@@ -0,0 +1,307 @@
1
+ import { MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES, MATERIALIZED_DELIVERY_ENTRY_PAGE_ALL, MATERIALIZED_DELIVERY_ENTRY_SCOPES, MATERIALIZED_DELIVERY_GEO_DAY_RETENTION_DAYS, MATERIALIZED_REPORT_SCOPE_ENUM, } from '../../constants/MATERIALIZED_REPORTS';
2
+ import { materializedDocumentBsonBytes } from './materialized-document-size';
3
+ import { getMaterializedPeriodScopeFields } from './scope-helpers';
4
+ /**
5
+ * Delivery ENTRY PAGES — the page identity of `materialized_tenant_delivery_entries`.
6
+ *
7
+ * ## One page per source day
8
+ *
9
+ * The entry collection follows the Discounts split exactly: the report document is
10
+ * counters only, and an entry document is ONE PAGE bounded by ONE source day.
11
+ *
12
+ * | scope | page |
13
+ * | --- | --- |
14
+ * | `localDate` | `'all'` (the scope is already one day) |
15
+ * | `localWeek` | `<source localDate>` |
16
+ * | `localWeekOfYear` | `<source localDate>` |
17
+ * | `localMonth` | `<source localDate>` |
18
+ *
19
+ * There is NO quarter / semester / year entry scope: a whole month of statement rows
20
+ * in one document is exactly the unbounded shape this replaces. A month is covered by
21
+ * its 28-31 pages.
22
+ *
23
+ * An oversized page is split into deterministic `#0`, `#1` sub-pages. The unsuffixed
24
+ * identity is used while the page fits; every sub-page still belongs to the same source
25
+ * day and is unioned by the flat/details and close readers.
26
+ *
27
+ * ## Broad selections
28
+ *
29
+ * A details reader resolves its exact selected DAYS into either the single day group
30
+ * (one day) or the set of MONTH groups that contain them. The pages of those months are
31
+ * scanned, and the rows are filtered to the exact days using each row's
32
+ * `source_local_date` - so a custom multi-month range is exact, not month-rounded.
33
+ */
34
+ /** True when a scope context carries entry pages (day + the three period scopes). */
35
+ export function isMaterializedDeliveryEntryScope(scope) {
36
+ return MATERIALIZED_DELIVERY_ENTRY_SCOPES.includes(String(scope));
37
+ }
38
+ /**
39
+ * The `page` value a compiled entry document of `scopeContext` must carry for the
40
+ * closing day `localDate`, or null for a scope that carries no entry pages.
41
+ */
42
+ export function deliveryEntryPageOf(scopeContext, localDate) {
43
+ const scope = String(scopeContext);
44
+ if (!isMaterializedDeliveryEntryScope(scope))
45
+ return null;
46
+ if (scope === MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE) {
47
+ return MATERIALIZED_DELIVERY_ENTRY_PAGE_ALL;
48
+ }
49
+ if (typeof localDate !== 'string' || localDate === '')
50
+ return null;
51
+ return localDate;
52
+ }
53
+ const SUB_PAGE_PATTERN = /^(.*)#(\d+)$/;
54
+ /** The unsuffixed source-day page (`all` / `YYYY-MM-DD`). */
55
+ export function deliveryEntryPageBase(page) {
56
+ const text = String(page ?? '');
57
+ const match = SUB_PAGE_PATTERN.exec(text);
58
+ return match == null ? text : match[1];
59
+ }
60
+ /** True when a stored page belongs to the source day. */
61
+ export function isDeliveryEntryPageForSourceDay(scopeContext, page, localDate) {
62
+ const base = deliveryEntryPageOf(scopeContext, localDate);
63
+ if (base == null)
64
+ return false;
65
+ return deliveryEntryPageBase(page) === base;
66
+ }
67
+ /** The deterministic page identity of one chunk. */
68
+ export function materializedDeliveryEntrySubPage(basePage, index) {
69
+ return `${basePage}#${Math.max(0, Math.floor(index))}`;
70
+ }
71
+ /**
72
+ * Splits ONE source-day entry page when it exceeds the 15 MiB budget.
73
+ *
74
+ * Rows are walked in their deterministic key/row order and packed until the next row
75
+ * would cross the budget; the resulting chunks are `page#0`, `page#1`, ... . A page
76
+ * that fits keeps its original identity (no suffix), so existing pages are untouched
77
+ * until they actually grow. The pages are disjoint: every row appears exactly once.
78
+ */
79
+ export function splitMaterializedDeliveryEntryPage(doc, maxBytes = MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES) {
80
+ if (doc == null)
81
+ return [];
82
+ if (materializedDocumentBsonBytes(doc) <= maxBytes)
83
+ return [doc];
84
+ const sections = doc.delivery_entries ?? null;
85
+ if (sections == null)
86
+ return [doc];
87
+ const basePage = deliveryEntryPageBase(doc.page);
88
+ const baseDoc = { ...doc, page: basePage, delivery_entries: {} };
89
+ const envelopeBytes = materializedDocumentBsonBytes(baseDoc);
90
+ const chunks = [];
91
+ let current = {};
92
+ let currentBytes = envelopeBytes;
93
+ let currentRows = 0;
94
+ const flush = () => {
95
+ if (currentRows > 0)
96
+ chunks.push(current);
97
+ current = {};
98
+ currentBytes = envelopeBytes;
99
+ currentRows = 0;
100
+ };
101
+ for (const key of Object.keys(sections)) {
102
+ for (const row of sections[key]?.rows ?? []) {
103
+ const rowBytes = materializedDocumentBsonBytes(row) + key.length + 24;
104
+ if (currentRows > 0 && currentBytes + rowBytes > maxBytes - 512)
105
+ flush();
106
+ if (current[key] == null)
107
+ current[key] = { rows: [] };
108
+ current[key].rows.push(row);
109
+ currentBytes += rowBytes;
110
+ currentRows += 1;
111
+ if (currentBytes > maxBytes) {
112
+ throw new Error(`Delivery entry page ${String(doc.scope_context)}:${String(doc.scope_field)}:` +
113
+ `${basePage} cannot split below the budget (one row is too large)`);
114
+ }
115
+ }
116
+ }
117
+ flush();
118
+ if (chunks.length <= 1) {
119
+ const allRows = [];
120
+ for (const key of Object.keys(sections)) {
121
+ for (const row of sections[key]?.rows ?? [])
122
+ allRows.push({ key, row });
123
+ }
124
+ if (allRows.length < 2) {
125
+ throw new Error(`Delivery entry page ${String(doc.scope_context)}:${String(doc.scope_field)}:` +
126
+ `${basePage} is over budget and has no splittable row`);
127
+ }
128
+ const mid = Math.ceil(allRows.length / 2);
129
+ const toChunk = (rows) => {
130
+ const chunk = {};
131
+ for (const { key, row } of rows) {
132
+ if (chunk[key] == null)
133
+ chunk[key] = { rows: [] };
134
+ chunk[key].rows.push(row);
135
+ }
136
+ return chunk;
137
+ };
138
+ chunks.push(toChunk(allRows.slice(0, mid)), toChunk(allRows.slice(mid)));
139
+ }
140
+ return chunks.map((chunk, index) => {
141
+ const page = {
142
+ ...doc,
143
+ page: materializedDeliveryEntrySubPage(basePage, index),
144
+ delivery_entries: chunk,
145
+ };
146
+ if (materializedDocumentBsonBytes(page) > maxBytes) {
147
+ throw new Error(`Delivery entry sub-page ${String(doc.scope_context)}:${String(doc.scope_field)}:` +
148
+ `${page.page} exceeds the entry-page budget`);
149
+ }
150
+ return page;
151
+ });
152
+ }
153
+ /**
154
+ * Unions all pages of ONE source day (the base page or its #N sub-pages) into a single
155
+ * logical document. Used by the flat-projection writer and by any in-process details
156
+ * read; rows are disjoint by construction, and the delivery_id/entry_key dedupe makes a
157
+ * duplicate page harmless instead of doubling a row.
158
+ */
159
+ export function mergeMaterializedDeliveryEntryPages(pages, identity) {
160
+ const list = (pages ?? []).filter((page) => page != null);
161
+ if (list.length === 0)
162
+ return null;
163
+ const sections = {};
164
+ const seen = new Set();
165
+ let offApp = 0;
166
+ for (const page of list) {
167
+ offApp = Math.max(offApp, Math.max(0, Number(page.off_app_order_count) || 0));
168
+ for (const [key, section] of Object.entries(page.delivery_entries ?? {})) {
169
+ for (const row of section?.rows ?? []) {
170
+ const rowIdentity = String(row.delivery_id ?? row.entry_key ?? '');
171
+ if (rowIdentity !== '') {
172
+ if (seen.has(rowIdentity))
173
+ continue;
174
+ seen.add(rowIdentity);
175
+ }
176
+ if (sections[key] == null)
177
+ sections[key] = { rows: [] };
178
+ sections[key].rows.push(row);
179
+ }
180
+ }
181
+ }
182
+ const first = list[0];
183
+ return {
184
+ ...first,
185
+ ...(identity ?? {}),
186
+ delivery_entries: sections,
187
+ off_app_order_count: offApp,
188
+ };
189
+ }
190
+ /**
191
+ * The BASE page refs belonging to ONE source day. The close reader expands each ref to
192
+ * the base plus any deterministic `#N` sub-pages; no other day's page is ever fetched.
193
+ *
194
+ * Returns null for a malformed date.
195
+ */
196
+ export function buildMaterializedDeliveryEntryPageRefs(localDate) {
197
+ const fields = getMaterializedPeriodScopeFields(localDate);
198
+ if (fields == null)
199
+ return null;
200
+ const refs = [];
201
+ for (const scope of MATERIALIZED_DELIVERY_ENTRY_SCOPES) {
202
+ const scopeField = fields[String(scope)];
203
+ const page = deliveryEntryPageOf(scope, localDate);
204
+ if (typeof scopeField !== 'string' || scopeField === '' || page == null)
205
+ return null;
206
+ refs.push({ scope_context: scope, scope_field: scopeField, page });
207
+ }
208
+ return refs;
209
+ }
210
+ /** Stable identity string of one entry page (tests / diagnostics). */
211
+ export function materializedDeliveryEntryPageKey(ref) {
212
+ return `${String(ref?.scope_context)}|${String(ref?.scope_field)}|${String(ref?.page)}`;
213
+ }
214
+ /** The distinct `YYYY-MM` scope values of a day set, ascending. */
215
+ export function deliveryMonthScopeFieldsOfDays(days) {
216
+ const months = new Set();
217
+ for (const day of days ?? []) {
218
+ const match = /^(\d{4})-(\d{2})-\d{2}$/.exec(String(day));
219
+ if (match == null)
220
+ continue;
221
+ months.add(`${match[1]}-${match[2]}`);
222
+ }
223
+ return [...months].sort();
224
+ }
225
+ /**
226
+ * Resolves the EXACT selected days into the scope groups a DELIVERY DETAILS read uses.
227
+ *
228
+ * - one day -> the `localDate` page (`page='all'`) - the direct path;
229
+ * - many days -> the `localMonth` groups that contain them. The reader scans every page
230
+ * of those months and filters rows to the exact days, so a quarter / semester / year
231
+ * / custom multi-month range is served from monthly pages instead of being refused.
232
+ */
233
+ export function buildMaterializedDeliveryDetailsScopeGroups(days) {
234
+ const unique = [...new Set((days ?? []).map((day) => String(day)))].sort();
235
+ if (unique.length === 0)
236
+ return null;
237
+ if (unique.length === 1) {
238
+ return [{ scope_context: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE, scope_field: [unique[0]] }];
239
+ }
240
+ const months = deliveryMonthScopeFieldsOfDays(unique);
241
+ if (months.length === 0)
242
+ return null;
243
+ return [{ scope_context: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH, scope_field: months }];
244
+ }
245
+ const DAY_KEY_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
246
+ /** UTC day key — the report's local dates are already tenant-local keys. */
247
+ const utcDayKey = (date) => date.toISOString().slice(0, 10);
248
+ const dayKeyOffset = (day, offsetDays) => {
249
+ const match = DAY_KEY_PATTERN.exec(day);
250
+ if (match == null)
251
+ return null;
252
+ const date = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])));
253
+ if (Number.isNaN(date.getTime()))
254
+ return null;
255
+ date.setUTCDate(date.getUTCDate() + offsetDays);
256
+ return utcDayKey(date);
257
+ };
258
+ /**
259
+ * THE canonical GEO resolver, shared by LIVE and HISTORICAL.
260
+ *
261
+ * - all selected days are inside the DAY-cell retention window -> exact DAY cells;
262
+ * - otherwise -> whole-MONTH cells for every month the selection touches.
263
+ *
264
+ * It never mixes DAY cells for some days with MONTH cells for others. The caller must
265
+ * expose `granularity` / `exact_days` so the UI can say when the map is month-granular.
266
+ */
267
+ export function resolveMaterializedDeliveryGeoRead(days, options) {
268
+ const unique = [...new Set((days ?? []).map((day) => String(day)))].sort();
269
+ if (unique.length === 0)
270
+ return null;
271
+ if (unique.some((day) => DAY_KEY_PATTERN.exec(day) == null))
272
+ return null;
273
+ const now = options?.now == null ? new Date() : new Date(options.now);
274
+ if (Number.isNaN(now.getTime()))
275
+ return null;
276
+ const retentionDays = Number.isFinite(Number(options?.retentionDays))
277
+ ? Math.max(0, Math.floor(Number(options?.retentionDays)))
278
+ : MATERIALIZED_DELIVERY_GEO_DAY_RETENTION_DAYS;
279
+ const cutoff = dayKeyOffset(utcDayKey(now), -retentionDays);
280
+ if (cutoff == null)
281
+ return null;
282
+ const allWithinRetention = unique.every((day) => day >= cutoff);
283
+ if (allWithinRetention) {
284
+ return {
285
+ groups: [{ scope_context: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE, scope_field: unique }],
286
+ granularity: 'DAY',
287
+ exact_days: true,
288
+ day_cutoff: cutoff,
289
+ };
290
+ }
291
+ const months = deliveryMonthScopeFieldsOfDays(unique);
292
+ if (months.length === 0)
293
+ return null;
294
+ return {
295
+ groups: [{ scope_context: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH, scope_field: months }],
296
+ granularity: 'MONTH',
297
+ exact_days: false,
298
+ day_cutoff: cutoff,
299
+ };
300
+ }
301
+ /**
302
+ * Scope groups for the GEO read. Kept as the public group-only helper; prefer
303
+ * `resolveMaterializedDeliveryGeoRead` when the response must carry granularity.
304
+ */
305
+ export function buildMaterializedDeliveryGeoScopeGroups(days) {
306
+ return resolveMaterializedDeliveryGeoRead(days)?.groups ?? null;
307
+ }
@@ -0,0 +1,103 @@
1
+ import { MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_COLLECTION_NAME } from '../../constants/MATERIALIZED_REPORTS';
2
+ import { MATERIALIZED_TENANT_DELIVERY_ENTRIES_COLLECTION_NAME } from '../../schemas/models/materialized_tenant_delivery_entries';
3
+ import { MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_COLLECTION_NAME } from '../../schemas/models/materialized_tenant_delivery_geo_cells';
4
+ import { MATERIALIZED_TENANT_DELIVERY_REPORTS_COLLECTION_NAME } from '../../schemas/models/materialized_tenant_delivery_reports';
5
+ /**
6
+ * Delivery report index migration (pure helper; no automatic execution).
7
+ *
8
+ * Drops the legacy entry identity index and creates the page identity index. Also
9
+ * exposes the owner-approved SOURCE index definition for `deliveries`.
10
+ *
11
+ * The deployable CLI is `simulations/migrate-delivery-report-indexes.ts`; it passes a
12
+ * live Db and `apply`. Tests pass an in-memory Db.
13
+ */
14
+ export const DELIVERY_ENTRY_LEGACY_INDEX_NAME = 'tenant_id__scope_context__scope_field__day_index';
15
+ export const DELIVERY_ENTRY_PAGE_INDEX_NAME = 'tenant_id__scope_context__scope_field__page';
16
+ export const DELIVERIES_SOURCE_INDEX_NAME = 'tenant_id__localDate__updatedAt';
17
+ export const DELIVERY_GEO_SCOPE_INDEX_NAME = 'tenant_id__scope_context__scope_field';
18
+ export const DELIVERY_ENTRY_PAGE_INDEX_KEY = {
19
+ tenant_id: 1,
20
+ scope_context: 1,
21
+ scope_field: 1,
22
+ page: 1,
23
+ };
24
+ /** Approved source index: staging and cross-day reads by order-local day. */
25
+ export const DELIVERIES_SOURCE_INDEX_KEY = {
26
+ tenant_id: 1,
27
+ localDate: 1,
28
+ updatedAt: -1,
29
+ };
30
+ /** One cap-metadata document per tenant + geo scope + scope field. */
31
+ export const DELIVERY_GEO_SCOPE_INDEX_KEY = {
32
+ tenant_id: 1,
33
+ scope_context: 1,
34
+ scope_field: 1,
35
+ };
36
+ /** Collections the migration/index bootstrap may touch. */
37
+ export const DELIVERY_MATERIALIZED_COLLECTIONS = [
38
+ MATERIALIZED_TENANT_DELIVERY_REPORTS_COLLECTION_NAME,
39
+ MATERIALIZED_TENANT_DELIVERY_ENTRIES_COLLECTION_NAME,
40
+ MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_COLLECTION_NAME,
41
+ MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_COLLECTION_NAME,
42
+ ];
43
+ /** Create a collection if it does not exist; tolerate NamespaceExists (code 48). */
44
+ async function ensureCollection(db, name) {
45
+ try {
46
+ await db.createCollection(name);
47
+ }
48
+ catch (error) {
49
+ if (Number(error?.code) !== 48)
50
+ throw error;
51
+ }
52
+ }
53
+ /** Inspect the indexes without mutating anything. */
54
+ export async function planDeliveryReportIndexMigration(db) {
55
+ const existing = await db
56
+ .collection(MATERIALIZED_TENANT_DELIVERY_ENTRIES_COLLECTION_NAME)
57
+ .listIndexes()
58
+ .toArray()
59
+ .catch(() => []);
60
+ const legacy = existing.find((index) => index.name === DELIVERY_ENTRY_LEGACY_INDEX_NAME ||
61
+ (index.unique === true &&
62
+ index.key?.tenant_id === 1 &&
63
+ index.key?.scope_context === 1 &&
64
+ index.key?.scope_field === 1 &&
65
+ index.key?.day_index === 1 &&
66
+ index.key?.page == null));
67
+ return {
68
+ legacyEntryIndex: legacy?.name ?? null,
69
+ createEntryPageIndex: true,
70
+ createSourceIndex: true,
71
+ createGeoScopeIndex: true,
72
+ };
73
+ }
74
+ /**
75
+ * Apply the migration. Caller must have a backup and must NOT run this during a close.
76
+ * Idempotent: a missing legacy index is a no-op; createIndex is idempotent by name/key.
77
+ */
78
+ export async function migrateDeliveryReportIndexes(db, options) {
79
+ const plan = await planDeliveryReportIndexMigration(db);
80
+ if (!options.apply)
81
+ return plan;
82
+ for (const collectionName of DELIVERY_MATERIALIZED_COLLECTIONS) {
83
+ await ensureCollection(db, collectionName);
84
+ }
85
+ const entries = db.collection(MATERIALIZED_TENANT_DELIVERY_ENTRIES_COLLECTION_NAME);
86
+ if (plan.legacyEntryIndex != null) {
87
+ await entries.dropIndex(plan.legacyEntryIndex);
88
+ }
89
+ await entries.createIndex(DELIVERY_ENTRY_PAGE_INDEX_KEY, {
90
+ name: DELIVERY_ENTRY_PAGE_INDEX_NAME,
91
+ unique: true,
92
+ });
93
+ await db.collection('deliveries').createIndex(DELIVERIES_SOURCE_INDEX_KEY, {
94
+ name: DELIVERIES_SOURCE_INDEX_NAME,
95
+ });
96
+ await db
97
+ .collection(MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_COLLECTION_NAME)
98
+ .createIndex(DELIVERY_GEO_SCOPE_INDEX_KEY, {
99
+ name: DELIVERY_GEO_SCOPE_INDEX_NAME,
100
+ unique: true,
101
+ });
102
+ return plan;
103
+ }
@@ -0,0 +1,109 @@
1
+ /**
2
+ * Row helpers for the two BOUNDED leaderboards of a delivery report document.
3
+ *
4
+ * ## Bounded, and honest about it
5
+ *
6
+ * `riders` and `areas` are keyed maps whose key space is unbounded in principle (rider
7
+ * churn, city sprawl). Each is capped, and the tail is NOT dropped: it is folded into a
8
+ * single `__OTHER__` row, so the leaderboard still reconciles against the document
9
+ * totals.
10
+ *
11
+ * ## Deterministic order
12
+ *
13
+ * The top-N is ranked `count DESC, key ASC`. Without the key tie-break two closes of the
14
+ * same day could keep different rows (and different `__OTHER__` sums), which would make
15
+ * `iteration` churn on an unchanged day.
16
+ *
17
+ * ## MIN/MAX tenure bounds
18
+ *
19
+ * A rider row carries `first_delivery_at` / `last_delivery_at`. When two rows are merged
20
+ * (a period fold, or the `__OTHER__` fold) the bounds must stay a MINIMUM and a MAXIMUM -
21
+ * summing them, or keeping the newest value, would report a rider's tenure as starting
22
+ * after it did.
23
+ */
24
+ const num = (value) => Number(value) || 0;
25
+ const earlierOf = (current, candidate) => {
26
+ const time = candidate == null ? NaN : new Date(candidate).getTime();
27
+ if (Number.isNaN(time))
28
+ return current;
29
+ if (current == null || time < new Date(current).getTime())
30
+ return new Date(time);
31
+ return current;
32
+ };
33
+ const laterOf = (current, candidate) => {
34
+ const time = candidate == null ? NaN : new Date(candidate).getTime();
35
+ if (Number.isNaN(time))
36
+ return current;
37
+ if (current == null || time > new Date(current).getTime())
38
+ return new Date(time);
39
+ return current;
40
+ };
41
+ /** A zeroed rider row. */
42
+ export function emptyMaterializedDeliveryRiderRow(riderName = null) {
43
+ return {
44
+ rider_name: riderName,
45
+ count: 0,
46
+ completed_count: 0,
47
+ cancelled_count: 0,
48
+ in_progress_count: 0,
49
+ rider_revenue_amount: 0,
50
+ distance_sum_meters: 0,
51
+ first_delivery_at: null,
52
+ last_delivery_at: null,
53
+ };
54
+ }
55
+ /** A zeroed area row. */
56
+ export function emptyMaterializedDeliveryAreaRow() {
57
+ return {
58
+ delivery_orders: 0,
59
+ app_orders: 0,
60
+ off_app_orders: 0,
61
+ delivery_records: 0,
62
+ completed_count: 0,
63
+ cancelled_count: 0,
64
+ net_sale_amount: 0,
65
+ delivery_charge_amount: 0,
66
+ rider_revenue_amount: 0,
67
+ distance_sum_meters: 0,
68
+ by_hour: {},
69
+ };
70
+ }
71
+ /** Merges one rider row into another, MIN/MAX on the tenure bounds. */
72
+ export function mergeMaterializedDeliveryRiderRow(target, source) {
73
+ target.count += num(source?.count);
74
+ target.completed_count += num(source?.completed_count);
75
+ target.cancelled_count += num(source?.cancelled_count);
76
+ target.in_progress_count += num(source?.in_progress_count);
77
+ target.rider_revenue_amount += num(source?.rider_revenue_amount);
78
+ target.distance_sum_meters += num(source?.distance_sum_meters);
79
+ target.rider_name ?? (target.rider_name = source?.rider_name ?? null);
80
+ // MIN / MAX - never a sum, and never just the newest document value.
81
+ target.first_delivery_at = earlierOf(target.first_delivery_at, source?.first_delivery_at);
82
+ target.last_delivery_at = laterOf(target.last_delivery_at, source?.last_delivery_at);
83
+ }
84
+ /**
85
+ * Merges one AREA row into another.
86
+ *
87
+ * Both populations are additive within an area: order-side figures count every delivery
88
+ * order (off-app included) and app-side figures count delivery records. `by_hour` is the
89
+ * order-demand histogram, so it sums too.
90
+ */
91
+ export function mergeMaterializedDeliveryAreaRow(target, source) {
92
+ target.delivery_orders += num(source?.delivery_orders);
93
+ target.app_orders += num(source?.app_orders);
94
+ target.off_app_orders += num(source?.off_app_orders);
95
+ // Historical tolerance: documents written before the area row split stored the
96
+ // delivery-record count as `count`. Reading both keeps a period fold exact across the
97
+ // schema boundary instead of silently dropping the old days' records.
98
+ target.delivery_records += num(source?.delivery_records ?? source?.count);
99
+ target.completed_count += num(source?.completed_count);
100
+ target.cancelled_count += num(source?.cancelled_count);
101
+ target.net_sale_amount += num(source?.net_sale_amount);
102
+ target.delivery_charge_amount += num(source?.delivery_charge_amount);
103
+ target.rider_revenue_amount += num(source?.rider_revenue_amount);
104
+ target.distance_sum_meters += num(source?.distance_sum_meters);
105
+ target.by_hour ?? (target.by_hour = {});
106
+ for (const [hour, value] of Object.entries(source?.by_hour ?? {})) {
107
+ target.by_hour[hour] = num(target.by_hour[hour]) + num(value);
108
+ }
109
+ }
@@ -0,0 +1,32 @@
1
+ import { MATERIALIZED_REPORT_TYPE_ENUM, MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_COLLECTION_NAME, } from '../../constants/MATERIALIZED_REPORTS';
2
+ import { MATERIALIZED_REPORT_DRILLDOWN_ROWS_COLLECTION_NAME, MATERIALIZED_REPORT_DRILLDOWN_SCOPES_COLLECTION_NAME, } from '../../schemas/models/materialized_report_drilldown_rows';
3
+ import { MATERIALIZED_TENANT_DELIVERY_ENTRIES_COLLECTION_NAME } from '../../schemas/models/materialized_tenant_delivery_entries';
4
+ import { MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_COLLECTION_NAME } from '../../schemas/models/materialized_tenant_delivery_geo_cells';
5
+ import { MATERIALIZED_TENANT_DELIVERY_REPORTS_COLLECTION_NAME } from '../../schemas/models/materialized_tenant_delivery_reports';
6
+ import { MATERIALIZED_TENANT_REPORTS_ITERATIONS_COLLECTION_NAME } from '../../schemas/models/materialized_tenant_reports_iterations';
7
+ export function buildDeliveryMaterializationWipeTargets(tenantId) {
8
+ const selectedTenant = typeof tenantId === 'string' && tenantId.trim() !== '' ? tenantId.trim() : null;
9
+ const tenantFilter = selectedTenant == null ? {} : { tenant_id: selectedTenant };
10
+ const flatFilter = {
11
+ report_type: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_DELIVERY_ENTRIES,
12
+ ...tenantFilter,
13
+ };
14
+ const iterationFilter = {
15
+ report_type: {
16
+ $in: [
17
+ MATERIALIZED_REPORT_TYPE_ENUM.TENANT_DELIVERY_REPORTS,
18
+ MATERIALIZED_REPORT_TYPE_ENUM.TENANT_DELIVERY_ENTRIES,
19
+ ],
20
+ },
21
+ ...(selectedTenant == null ? {} : { 'snapshot.tenant_id': selectedTenant }),
22
+ };
23
+ return [
24
+ { name: MATERIALIZED_TENANT_DELIVERY_REPORTS_COLLECTION_NAME, filter: tenantFilter },
25
+ { name: MATERIALIZED_TENANT_DELIVERY_ENTRIES_COLLECTION_NAME, filter: tenantFilter },
26
+ { name: MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_COLLECTION_NAME, filter: tenantFilter },
27
+ { name: MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_COLLECTION_NAME, filter: tenantFilter },
28
+ { name: MATERIALIZED_REPORT_DRILLDOWN_ROWS_COLLECTION_NAME, filter: flatFilter },
29
+ { name: MATERIALIZED_REPORT_DRILLDOWN_SCOPES_COLLECTION_NAME, filter: flatFilter },
30
+ { name: MATERIALIZED_TENANT_REPORTS_ITERATIONS_COLLECTION_NAME, filter: iterationFilter },
31
+ ];
32
+ }
@@ -0,0 +1,65 @@
1
+ import mongoose from 'mongoose';
2
+ /**
3
+ * The BSON SIZE BUDGET of a materialized report/entry/geo document.
4
+ *
5
+ * ## Why compile-time, and why PER COLLECTION
6
+ *
7
+ * MongoDB rejects a document above 16 MiB. Without a guard, an entry page that folded
8
+ * one delivery row too many would fail at `insert`/`bulkWrite` time - i.e. in the middle
9
+ * of the day-close transaction, after the counters and iterations had been computed,
10
+ * with a server-side "object too large" error that names nothing.
11
+ *
12
+ * The guard moves that failure to the COMPILE, names the collection (and, for an entry
13
+ * page, the day and scope), and uses a PRACTICAL budget per collection rather than one
14
+ * global "almost 16 MiB" target:
15
+ *
16
+ * - `MATERIALIZED_DELIVERY_REPORT_MAX_BSON_BYTES` (15 MiB) - counters only;
17
+ * - `MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES` (15 MiB) - ONE source day's page
18
+ * (oversized pages split into deterministic `#0`, `#1` sub-pages);
19
+ * - `MATERIALIZED_DELIVERY_GEO_CELL_MAX_BSON_BYTES` (2 MiB) - one H3 cell.
20
+ *
21
+ * `maxBytes` is REQUIRED: a caller must choose the budget that belongs to its document
22
+ * shape, so a new collection cannot silently inherit the wrong one.
23
+ *
24
+ * ## What it measures
25
+ *
26
+ * The exact BSON encoding MongoDB would store (`BSON.calculateObjectSize`), not
27
+ * `JSON.stringify` - a JSON estimate is meaningless for Dates/ObjectIds and misses the
28
+ * type tags that make up a large part of a materialized document.
29
+ */
30
+ /** The measured size of one document, in bytes. */
31
+ export function materializedDocumentBsonBytes(document) {
32
+ if (document == null)
33
+ return 0;
34
+ return mongoose.mongo.BSON.calculateObjectSize(document);
35
+ }
36
+ /**
37
+ * Throws when ONE document exceeds its budget.
38
+ *
39
+ * The message carries the label/collection, the budget and the actual size, so a writer
40
+ * that produced the document can be found from the error alone.
41
+ */
42
+ export function assertMaterializedDocumentSize(document, context) {
43
+ if (context == null || !Number.isFinite(context.maxBytes) || context.maxBytes <= 0) {
44
+ throw new Error('assertMaterializedDocumentSize: an explicit maxBytes budget is required');
45
+ }
46
+ const budget = context.maxBytes;
47
+ const size = materializedDocumentBsonBytes(document);
48
+ if (size <= budget)
49
+ return;
50
+ const scope = context.label ?? context.collection ?? 'materialized document';
51
+ throw new Error(`BSON size budget exceeded in ${scope}: ${size} > ${budget} bytes. ` +
52
+ 'Split or bound the document at the writer (one page per source day, top-N maps) ' +
53
+ 'instead of writing a document MongoDB will reject.');
54
+ }
55
+ /** Asserts a whole SET of documents (a scope, a plan, a batch) in one call. */
56
+ export function assertMaterializedDocumentsSize(documents, context) {
57
+ if (documents == null)
58
+ return;
59
+ const scope = context.collection;
60
+ documents.forEach((document, index) => assertMaterializedDocumentSize(document, {
61
+ collection: scope,
62
+ label: context.label ?? (scope != null ? `${scope}[${index}]` : undefined),
63
+ maxBytes: context.maxBytes,
64
+ }));
65
+ }