@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
@@ -102,7 +102,7 @@ export var MATERIALIZED_REPORT_KEY_FILTER_ENUM;
102
102
  // additive: the envelope merely declares which dimensions a key encodes.
103
103
  MATERIALIZED_REPORT_KEY_FILTER_ENUM["DRAWER_ID"] = "DRAWER_ID";
104
104
  MATERIALIZED_REPORT_KEY_FILTER_ENUM["REF_TYPE"] = "REF_TYPE";
105
- // Delivery (M4) encodes <PLATFORM>:<CITY>, both joined from the ORDER - a delivery
105
+ // Delivery (M4) encodes <ORDER_STATUS>:<PLATFORM>:<CITY>, all joined from the ORDER - a delivery
106
106
  // document carries neither, so the report joins by order_id and keys on the
107
107
  // order's dimensions. CITY is a new dimension here.
108
108
  MATERIALIZED_REPORT_KEY_FILTER_ENUM["CITY"] = "CITY";
@@ -384,13 +384,42 @@ export const MATERIALIZED_DELIVERY_REPORT_SCOPES = [
384
384
  MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_YEAR,
385
385
  ];
386
386
  /**
387
- * Ordered key filters of the delivery report - `<PLATFORM>:<CITY>` (decision (b4)).
387
+ * Scopes the delivery ENTRY documents (and their flat drill-down projection) are
388
+ * materialized for. The WRITER materializes at most `localMonth` for rows, and every
389
+ * period scope is PAGE-PARTITIONED by source day.
390
+ *
391
+ * An entry document is ONE PAGE (one source day), never a whole period: a month is
392
+ * covered by its 28-31 pages. Counters remain year-capable
393
+ * (`MATERIALIZED_DELIVERY_REPORT_SCOPES`). The details READ has NO month cap: it
394
+ * resolves a broad selection to the `localMonth` scopes it touches and filters rows
395
+ * to the exact selected days.
396
+ */
397
+ export const MATERIALIZED_DELIVERY_ENTRY_SCOPES = [
398
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE,
399
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK,
400
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK_OF_YEAR,
401
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH,
402
+ ];
403
+ /**
404
+ * Page key of the DAY-scoped entry document - the day scope is already one day, so it
405
+ * needs no per-source-day partition. Every PERIOD entry scope (week / ISO week / month)
406
+ * is partitioned by the SOURCE local date (`page = <source localDate>`), exactly like
407
+ * `materialized_tenant_discount_entries`.
408
+ *
409
+ * This is what bounds an entry document: one page is one day's rows, never a month's.
410
+ */
411
+ export const MATERIALIZED_DELIVERY_ENTRY_PAGE_ALL = 'all';
412
+ /**
413
+ * Ordered key filters of the delivery report - `ORDER_STATUS:PLATFORM:CITY`, all joined
414
+ * from the ORDER. Delivery documents carry none of these dimensions, so the report joins
415
+ * by `order_id` and keys on the order's own values.
388
416
  *
389
417
  * Rider is deliberately NOT a key dimension: rider ids are high-cardinality, so rider
390
418
  * analysis is a bounded `riders` map INSIDE each document rather than a partition of
391
419
  * the key space.
392
420
  */
393
421
  export const DELIVERY_KEY_FILTERS = [
422
+ MATERIALIZED_REPORT_KEY_FILTER_ENUM.ORDER_STATUS,
394
423
  MATERIALIZED_REPORT_KEY_FILTER_ENUM.PLATFORM,
395
424
  MATERIALIZED_REPORT_KEY_FILTER_ENUM.CITY,
396
425
  ];
@@ -413,6 +442,81 @@ export const MATERIALIZED_DELIVERY_DISTANCE_BUCKETS = [
413
442
  export const MATERIALIZED_DELIVERY_RIDER_LIMIT = 50;
414
443
  /** Cap of the per-document area leaderboard (bounded, display-only). */
415
444
  export const MATERIALIZED_DELIVERY_AREA_LIMIT = 50;
445
+ /**
446
+ * Token of the ONE overflow row every bounded leaderboard keeps after its top-N.
447
+ *
448
+ * A bounded map would otherwise silently DROP the tail, and a report that drops rows
449
+ * without saying so is indistinguishable from one that never saw them. The overflow
450
+ * row carries the summed counts/money of everything below the cap, so the page can
451
+ * still reconcile against the totals. Reserved: a real rider id or city named
452
+ * `__OTHER__` would collide (ids are ObjectIds / names are human text; documented).
453
+ *
454
+ * Ordering of the TOP-N is deterministic: `count DESC, key ASC` - a non-deterministic
455
+ * tie-break would make two closes of the same day produce different documents.
456
+ */
457
+ export const MATERIALIZED_DELIVERY_OTHER_TOKEN = '__OTHER__';
458
+ /* ---------------- Delivery geo heat map (M4.1) ---------------- */
459
+ /**
460
+ * The delivery DEMAND HEAT MAP lives in its OWN collection, never inside the report
461
+ * document: a tenant-day can produce thousands of cells, and the report document is a
462
+ * counters-only document with a hard BSON budget.
463
+ *
464
+ * One document per `tenant_id + scope_context + scope_field + h3_cell`. Only DAY and
465
+ * MONTH scopes are materialized (a heat map is read at those grains); day cells are
466
+ * kept 90 days and month cells 24 months, pruned by the close-day writer.
467
+ */
468
+ export const MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_SCHEMA_VERSION = 1;
469
+ /** Small per-scope cap metadata; deliberately NOT stored on every cell. */
470
+ export const MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_COLLECTION_NAME = 'materialized_tenant_delivery_geo_scopes';
471
+ export const MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_SCHEMA_VERSION = 1;
472
+ /**
473
+ * Bounded by_key map per cell (ORDER_STATUS:PLATFORM:CITY).
474
+ *
475
+ * The CITY is part of the key, so one cell can hold orders from several cities and a
476
+ * city filter can still select the EXACT population inside it. That multiplies the key
477
+ * count by the number of cities in a cell, so the bound is generous: a cell normally
478
+ * holds one or two cities, and the cell's own BSON budget (2 MiB) is the real limit.
479
+ */
480
+ export const MATERIALIZED_DELIVERY_GEO_MAX_KEYS = 256;
481
+ /** H3 resolution of a heat cell. */
482
+ export const MATERIALIZED_DELIVERY_GEO_RESOLUTION = 8;
483
+ /** Scopes the heat map is materialized for - day + month ONLY. */
484
+ export const MATERIALIZED_DELIVERY_GEO_SCOPES = [
485
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE,
486
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH,
487
+ ];
488
+ /** Cells with fewer orders than this are not returned by the heat endpoint. */
489
+ export const MATERIALIZED_DELIVERY_GEO_MIN_ORDERS = 3;
490
+ /**
491
+ * Hard cap of stored cells per tenant × scope × scope_field. Cells are ranked
492
+ * `orders DESC, h3_cell ASC`; the tail is dropped. Totals never come from the cells -
493
+ * the heat response reads them from the report counters - so a capped map can never
494
+ * misstate the business total.
495
+ */
496
+ export const MATERIALIZED_DELIVERY_GEO_MAX_CELLS = 2000;
497
+ /** Day cells are retained 90 days; month cells 24 months. */
498
+ export const MATERIALIZED_DELIVERY_GEO_DAY_RETENTION_DAYS = 90;
499
+ export const MATERIALIZED_DELIVERY_GEO_MONTH_RETENTION_MONTHS = 24;
500
+ /**
501
+ * Sentinel cell for orders whose coordinates are missing, invalid or (0, 0).
502
+ * It is an AGGREGATE, not a location: the document carries NO `location`, so it can
503
+ * never be mistaken for a point on the map.
504
+ */
505
+ export const MATERIALIZED_DELIVERY_GEO_UNKNOWN_CELL = '__UNKNOWN__';
506
+ /**
507
+ * Per-collection BSON budgets (bytes) for the DELIVERY materialization.
508
+ *
509
+ * MongoDB's hard limit is 16 MiB per document. The report and page budgets are the
510
+ * owner-approved practical ceiling (15 MiB), leaving 1 MiB of headroom; a geo cell is
511
+ * a single H3 aggregate and stays at 2 MiB. There is no arbitrary 1 MiB report target.
512
+ *
513
+ * A writer that exceeds its budget fails at COMPILE time with the collection, source day
514
+ * and scope in the message - never midway through the close transaction with a
515
+ * server-side "object too large" error.
516
+ */
517
+ export const MATERIALIZED_DELIVERY_REPORT_MAX_BSON_BYTES = 15 * 1024 * 1024;
518
+ export const MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES = 15 * 1024 * 1024;
519
+ export const MATERIALIZED_DELIVERY_GEO_CELL_MAX_BSON_BYTES = 2 * 1024 * 1024;
416
520
  /* ======================================================================== */
417
521
  /* Prep time report (M2) */
418
522
  /* ======================================================================== */
@@ -40,4 +40,17 @@ export var DELIVERY_STATUS_ENUM;
40
40
  DELIVERY_STATUS_ENUM["CANCELLED"] = "CANCELLED";
41
41
  })(DELIVERY_STATUS_ENUM || (DELIVERY_STATUS_ENUM = {}));
42
42
  export const ALL_DELIVERY_STATUS = Object.values(DELIVERY_STATUS_ENUM);
43
+ /**
44
+ * OPEN delivery statuses: not yet delivered and not cancelled.
45
+ *
46
+ * This is the ONE definition the statement's "In progress" view, the volume
47
+ * chart's "Open" bucket and the delivery summary use. Do not hard-code a
48
+ * subset in a reader: a PENDING/ASSIGNED record is still open work even though
49
+ * its stored status is not literally `IN_PROGRESS`.
50
+ */
51
+ export const DELIVERY_OPEN_STATUSES = [
52
+ DELIVERY_STATUS_ENUM.PENDING,
53
+ DELIVERY_STATUS_ENUM.ASSIGNED,
54
+ DELIVERY_STATUS_ENUM.IN_PROGRESS,
55
+ ];
43
56
  // ======================>> <<====================== //
@@ -16,9 +16,14 @@ export * from './materialized-payments-comparison-close-day-helpers';
16
16
  export * from './materialized-payments-comparison-compile-helpers';
17
17
  export * from './materialized-cash-accumulator-helpers';
18
18
  export * from './materialized-delivery-accumulator-helpers';
19
+ export * from './materialized-delivery-rows';
20
+ export * from './materialized-delivery-entry-pages';
21
+ export * from './materialized-document-size';
22
+ export * from './materialized-tenant-delivery-geo-helpers';
19
23
  export * from './materialized-delivery-compile-helpers';
20
24
  export * from './materialized-delivery-classification-helpers';
21
25
  export * from './materialized-delivery-close-day-helpers';
26
+ export * from './materialized-delivery-index-migration';
22
27
  export * from './materialized-day-input-signature';
23
28
  export * from './materialized-cash-classification-helpers';
24
29
  export * from './materialized-cash-close-day-helpers';
@@ -1,4 +1,5 @@
1
1
  import { MATERIALIZED_DELIVERY_DISTANCE_BUCKETS } from '../../constants/MATERIALIZED_REPORTS';
2
+ import { emptyMaterializedDeliveryAreaRow, emptyMaterializedDeliveryRiderRow, mergeMaterializedDeliveryAreaRow, mergeMaterializedDeliveryRiderRow, } from './materialized-delivery-rows';
2
3
  /**
3
4
  * M4 delivery - folding counters across days into a PERIOD document.
4
5
  *
@@ -21,47 +22,6 @@ import { MATERIALIZED_DELIVERY_DISTANCE_BUCKETS } from '../../constants/MATERIAL
21
22
  * exactly one bucket per document.
22
23
  */
23
24
  const num = (value) => Number(value) || 0;
24
- const earlierOf = (current, candidate) => {
25
- const time = candidate == null ? NaN : new Date(candidate).getTime();
26
- if (Number.isNaN(time))
27
- return current;
28
- if (current == null || time < new Date(current).getTime())
29
- return new Date(time);
30
- return current;
31
- };
32
- const laterOf = (current, candidate) => {
33
- const time = candidate == null ? NaN : new Date(candidate).getTime();
34
- if (Number.isNaN(time))
35
- return current;
36
- if (current == null || time > new Date(current).getTime())
37
- return new Date(time);
38
- return current;
39
- };
40
- /** Merges one rider row into another, MIN/MAX on the tenure bounds. */
41
- function mergeRiderRow(target, source) {
42
- target.count += num(source?.count);
43
- target.completed_count += num(source?.completed_count);
44
- target.cancelled_count += num(source?.cancelled_count);
45
- target.in_progress_count += num(source?.in_progress_count);
46
- target.rider_revenue_amount += num(source?.rider_revenue_amount);
47
- target.distance_sum_meters += num(source?.distance_sum_meters);
48
- target.rider_name ?? (target.rider_name = source?.rider_name ?? null);
49
- // MIN / MAX - never a sum, and never just the newest document value.
50
- target.first_delivery_at = earlierOf(target.first_delivery_at, source?.first_delivery_at);
51
- target.last_delivery_at = laterOf(target.last_delivery_at, source?.last_delivery_at);
52
- }
53
- /** Merges one area row into another, summing the hour heat map. */
54
- function mergeAreaRow(target, source) {
55
- target.count += num(source?.count);
56
- target.completed_count += num(source?.completed_count);
57
- target.cancelled_count += num(source?.cancelled_count);
58
- target.rider_revenue_amount += num(source?.rider_revenue_amount);
59
- target.distance_sum_meters += num(source?.distance_sum_meters);
60
- target.by_hour ?? (target.by_hour = {});
61
- for (const [hour, value] of Object.entries(source?.by_hour ?? {})) {
62
- target.by_hour[hour] = num(target.by_hour[hour]) + num(value);
63
- }
64
- }
65
25
  /**
66
26
  * Merges `source` into `target`, IN PLACE. Null-safe: a source block missing a sub-object
67
27
  * is treated as zeroes rather than throwing, so one malformed historical document cannot
@@ -119,6 +79,9 @@ export function mergeMaterializedDeliveryCounters(target, source) {
119
79
  const tt = target.timing;
120
80
  const st = source.timing;
121
81
  tt.graded_count += num(st.graded_count);
82
+ tt.dispatch_lag_count += num(st.dispatch_lag_count);
83
+ tt.complete_count += num(st.complete_count);
84
+ tt.total_count += num(st.total_count);
122
85
  tt.dispatch_lag_sum_minutes += num(st.dispatch_lag_sum_minutes);
123
86
  tt.complete_sum_minutes += num(st.complete_sum_minutes);
124
87
  tt.total_sum_minutes += num(st.total_sum_minutes);
@@ -141,30 +104,13 @@ export function mergeMaterializedDeliveryCounters(target, source) {
141
104
  }
142
105
  for (const [riderId, row] of Object.entries(source.riders ?? {})) {
143
106
  target.riders ?? (target.riders = {});
144
- (_a = target.riders)[riderId] ?? (_a[riderId] = {
145
- rider_name: null,
146
- count: 0,
147
- completed_count: 0,
148
- cancelled_count: 0,
149
- in_progress_count: 0,
150
- rider_revenue_amount: 0,
151
- distance_sum_meters: 0,
152
- first_delivery_at: null,
153
- last_delivery_at: null,
154
- });
155
- mergeRiderRow(target.riders[riderId], row);
107
+ (_a = target.riders)[riderId] ?? (_a[riderId] = emptyMaterializedDeliveryRiderRow());
108
+ mergeMaterializedDeliveryRiderRow(target.riders[riderId], row);
156
109
  }
157
110
  for (const [city, row] of Object.entries(source.areas ?? {})) {
158
111
  target.areas ?? (target.areas = {});
159
- (_b = target.areas)[city] ?? (_b[city] = {
160
- count: 0,
161
- completed_count: 0,
162
- cancelled_count: 0,
163
- rider_revenue_amount: 0,
164
- distance_sum_meters: 0,
165
- by_hour: {},
166
- });
167
- mergeAreaRow(target.areas[city], row);
112
+ (_b = target.areas)[city] ?? (_b[city] = emptyMaterializedDeliveryAreaRow());
113
+ mergeMaterializedDeliveryAreaRow(target.areas[city], row);
168
114
  }
169
115
  return target;
170
116
  }
@@ -1,5 +1,6 @@
1
1
  import { DELIVERY_STATUS_ENUM, RIDER_EARNINGS_STATUS_ENUM } from '../../constants/enums/delivery';
2
- import { MATERIALIZED_DELIVERY_AREA_LIMIT, MATERIALIZED_DELIVERY_DISTANCE_BUCKETS, MATERIALIZED_DELIVERY_RIDER_LIMIT, } from '../../constants/MATERIALIZED_REPORTS';
2
+ import { MATERIALIZED_DELIVERY_DISTANCE_BUCKETS } from '../../constants/MATERIALIZED_REPORTS';
3
+ import { emptyMaterializedDeliveryAreaRow, emptyMaterializedDeliveryRiderRow } from './materialized-delivery-rows';
3
4
  /**
4
5
  * M4 delivery - key grammar, the order join, and the accumulators.
5
6
  *
@@ -16,7 +17,7 @@ import { MATERIALIZED_DELIVERY_AREA_LIMIT, MATERIALIZED_DELIVERY_DISTANCE_BUCKET
16
17
  * ## The join
17
18
  *
18
19
  * A delivery document carries neither the platform nor the city, so the key
19
- * `<PLATFORM>:<CITY>` and every order-derived money figure come from joining by
20
+ * `<ORDER_STATUS>:<PLATFORM>:<CITY>` and every order-derived money figure come from joining by
20
21
  * `order_id`. An order with no platform/city details falls into an explicit UNKNOWN
21
22
  * bucket rather than being dropped silently - a missing dimension must still show up in
22
23
  * the totals.
@@ -32,9 +33,13 @@ import { MATERIALIZED_DELIVERY_AREA_LIMIT, MATERIALIZED_DELIVERY_DISTANCE_BUCKET
32
33
  /** The key token used when a dimension is missing, so nothing is silently dropped. */
33
34
  export const DELIVERY_UNKNOWN_TOKEN = 'UNKNOWN';
34
35
  export const MATERIALIZED_DELIVERY_KEY_SEPARATOR = ':';
35
- /** Builds `<PLATFORM>:<CITY>`, substituting UNKNOWN for missing dimensions. */
36
- export function buildMaterializedDeliveryKey(platform, city) {
37
- return normalizeDimension(platform) + MATERIALIZED_DELIVERY_KEY_SEPARATOR + normalizeDimension(city);
36
+ /** Builds `<ORDER_STATUS>:<PLATFORM>:<CITY>`, substituting UNKNOWN for missing dimensions. */
37
+ export function buildMaterializedDeliveryKey(orderStatus, platform, city) {
38
+ return (normalizeDimension(orderStatus) +
39
+ MATERIALIZED_DELIVERY_KEY_SEPARATOR +
40
+ normalizeDimension(platform) +
41
+ MATERIALIZED_DELIVERY_KEY_SEPARATOR +
42
+ normalizeDimension(city));
38
43
  }
39
44
  function normalizeDimension(value) {
40
45
  if (value == null)
@@ -51,32 +56,15 @@ export function parseMaterializedDeliveryKey(key) {
51
56
  if (key == null)
52
57
  return null;
53
58
  const parts = String(key).split(MATERIALIZED_DELIVERY_KEY_SEPARATOR);
54
- if (parts.length !== 2)
59
+ if (parts.length !== 3)
55
60
  return null;
56
- const [platform, city] = parts;
57
- if (platform === '' || city === '')
61
+ const [order_status, platform, city] = parts;
62
+ if (order_status === '' || platform === '' || city === '')
58
63
  return null;
59
- return { platform, city };
64
+ return { order_status, platform, city };
60
65
  }
61
- const emptyRiderRow = (name) => ({
62
- rider_name: name,
63
- count: 0,
64
- completed_count: 0,
65
- cancelled_count: 0,
66
- in_progress_count: 0,
67
- rider_revenue_amount: 0,
68
- distance_sum_meters: 0,
69
- first_delivery_at: null,
70
- last_delivery_at: null,
71
- });
72
- const emptyAreaRow = () => ({
73
- count: 0,
74
- completed_count: 0,
75
- cancelled_count: 0,
76
- rider_revenue_amount: 0,
77
- distance_sum_meters: 0,
78
- by_hour: {},
79
- });
66
+ const emptyRiderRow = emptyMaterializedDeliveryRiderRow;
67
+ const emptyAreaRow = emptyMaterializedDeliveryAreaRow;
80
68
  /** A zeroed counter block. */
81
69
  export function freshDeliveryCounters() {
82
70
  const distance = { sum_meters: 0, count: 0 };
@@ -117,6 +105,9 @@ export function freshDeliveryCounters() {
117
105
  areas: {},
118
106
  timing: {
119
107
  graded_count: 0,
108
+ dispatch_lag_count: 0,
109
+ complete_count: 0,
110
+ total_count: 0,
120
111
  dispatch_lag_sum_minutes: 0,
121
112
  complete_sum_minutes: 0,
122
113
  total_sum_minutes: 0,
@@ -201,7 +192,7 @@ export function isDeliveryOrder(order) {
201
192
  * Order-side money is counted HERE rather than on the delivery, because a cancelled
202
193
  * delivery must not lose the order figures the operator recognises.
203
194
  */
204
- export function addDeliveryOrder(acc, order) {
195
+ export function addDeliveryOrder(acc, order, key = buildMaterializedDeliveryKey(order?.order_status, order?.platform, order?.delivery_details?.city ?? order?.delivery_details?.state ?? null)) {
205
196
  if (acc == null || order == null)
206
197
  return;
207
198
  const orderId = order._id == null ? null : String(order._id);
@@ -215,12 +206,20 @@ export function addDeliveryOrder(acc, order) {
215
206
  const details = order.delivery_details ?? {};
216
207
  // Money is integer CENTS: each source amount is rounded to the cent at this
217
208
  // writer boundary, because a materialized document may not hold a decimal.
218
- counters.money.net_sale_amount += cents(order.net_sale_amount ?? order.amount_earned);
219
- counters.money.collected_amount += cents(order.amount_collected);
220
- counters.money.tip_amount += cents(order.tip_amount);
221
- counters.money.discount_amount += cents(order.total_discount_applied);
222
- counters.money.refund_amount += cents(order.amount_refunded);
223
- counters.money.tax_amount += cents(order.gst_amount) + cents(order.tax_amount);
209
+ const netSale = cents(order.net_sale_amount ?? order.amount_earned);
210
+ const collected = cents(order.amount_collected);
211
+ const tip = cents(order.tip_amount);
212
+ const discount = cents(order.total_discount_applied);
213
+ // REFUNDS: `IOrder` declares no order-level `amount_refunded`; the money exists only
214
+ // on the payment rows, so it is summed from that declared source.
215
+ const refund = (order.payments ?? []).reduce((total, payment) => total + cents(payment?.amount_refunded), 0);
216
+ const tax = cents(order.gst_amount) + cents(order.tax_amount);
217
+ counters.money.net_sale_amount += netSale;
218
+ counters.money.collected_amount += collected;
219
+ counters.money.tip_amount += tip;
220
+ counters.money.discount_amount += discount;
221
+ counters.money.refund_amount += refund;
222
+ counters.money.tax_amount += tax;
224
223
  // `delivery_cost` is the field IOrderDeliveryDetails ACTUALLY declares; the other two
225
224
  // names are tolerated fallbacks. Reading the wrong one silently reported every charge
226
225
  // as ZERO while the statement row (which used the right field) showed the real value -
@@ -231,6 +230,16 @@ export function addDeliveryOrder(acc, order) {
231
230
  counters.money.delivery_charge_amount += charge;
232
231
  counters.money.delivery_charge_count += 1;
233
232
  }
233
+ // ---- the ORDER side of the area row ----
234
+ // Off-app orders are the whole point: they belong in the area's demand (and its money)
235
+ // even though no delivery document will ever describe them.
236
+ const area = areaRowFor(counters, key);
237
+ area.delivery_orders += 1;
238
+ area.net_sale_amount += netSale;
239
+ area.delivery_charge_amount += charge;
240
+ const hour = orderHourKey(order);
241
+ if (hour != null)
242
+ area.by_hour[hour] = (area.by_hour[hour] ?? 0) + 1;
234
243
  acc.watermark = laterOf(acc.watermark, order.updatedAt ?? order.createdAt);
235
244
  }
236
245
  /**
@@ -241,7 +250,7 @@ export function addDeliveryOrder(acc, order) {
241
250
  * attributed, so it lands in the UNKNOWN bucket.
242
251
  */
243
252
  export function addDelivery(acc, delivery, order, key) {
244
- var _a, _b;
253
+ var _a;
245
254
  if (acc == null || delivery == null)
246
255
  return;
247
256
  const counters = acc.counters;
@@ -305,12 +314,12 @@ export function addDelivery(acc, delivery, order, key) {
305
314
  row.first_delivery_at = earlierOf(row.first_delivery_at, delivery.createdAt);
306
315
  row.last_delivery_at = laterOf(row.last_delivery_at, delivery.createdAt);
307
316
  }
308
- // ---- the bounded area heat map (city from the JOIN) ----
309
- const parsed = parseMaterializedDeliveryKey(key);
310
- const city = parsed == null ? DELIVERY_UNKNOWN_TOKEN : parsed.city;
311
- counters.areas ?? (counters.areas = {});
312
- const area = ((_b = counters.areas)[city] ?? (_b[city] = emptyAreaRow()));
313
- area.count += 1;
317
+ // ---- the APP side of the area row (city from the JOIN) ----
318
+ // The row already exists when the area's orders were consumed; a delivery whose order
319
+ // was not staged creates the UNKNOWN row, so its record is still counted (its money
320
+ // and area attribution simply cannot be known).
321
+ const area = areaRowFor(counters, key);
322
+ area.delivery_records += 1;
314
323
  if (status === DELIVERY_STATUS_ENUM.COMPLETED)
315
324
  area.completed_count += 1;
316
325
  else if (status === DELIVERY_STATUS_ENUM.CANCELLED)
@@ -318,9 +327,7 @@ export function addDelivery(acc, delivery, order, key) {
318
327
  if (isFinalPayout)
319
328
  area.rider_revenue_amount += revenue;
320
329
  area.distance_sum_meters += meters;
321
- const hour = hourKeyOf(delivery);
322
- if (hour != null)
323
- area.by_hour[hour] = (area.by_hour[hour] ?? 0) + 1;
330
+ // NO hour here: demand is bucketed by the ORDER's local hour (see addDeliveryOrder).
324
331
  // ---- timing ----
325
332
  const timing = (counters.timing ?? (counters.timing = freshDeliveryCounters().timing));
326
333
  let graded = false;
@@ -328,6 +335,7 @@ export function addDelivery(acc, delivery, order, key) {
328
335
  const dispatchLag = minutesBetween(orderCreatedAt, delivery.createdAt);
329
336
  if (dispatchLag != null) {
330
337
  timing.dispatch_lag_sum_minutes += dispatchLag;
338
+ timing.dispatch_lag_count += 1;
331
339
  graded = true;
332
340
  }
333
341
  if (status === DELIVERY_STATUS_ENUM.COMPLETED) {
@@ -339,13 +347,16 @@ export function addDelivery(acc, delivery, order, key) {
339
347
  const complete = minutesBetween(delivery.createdAt, completedAt);
340
348
  if (complete != null) {
341
349
  timing.complete_sum_minutes += complete;
350
+ timing.complete_count += 1;
342
351
  graded = true;
343
352
  if (exact)
344
353
  timing.exact_completion_count += 1;
345
354
  }
346
355
  const total = minutesBetween(orderCreatedAt, completedAt);
347
- if (total != null)
356
+ if (total != null) {
348
357
  timing.total_sum_minutes += total;
358
+ timing.total_count += 1;
359
+ }
349
360
  // Explicit ETA only. ASAP orders need tenant settings the compile does not
350
361
  // receive, so they stay UNMEASURED rather than being given an invented promise.
351
362
  const expectedRaw = delivery.expected_delivery_at ?? order?.delivery_details?.estimated_delivery_time;
@@ -397,46 +408,57 @@ export function addDelivery(acc, delivery, order, key) {
397
408
  }
398
409
  acc.watermark = laterOf(acc.watermark, delivery.updatedAt ?? delivery.createdAt);
399
410
  }
400
- /** `HH` of a delivery, from the local hour when present. */
401
- function hourKeyOf(delivery) {
402
- const explicit = delivery.localHour;
403
- if (typeof explicit === 'number' && Number.isFinite(explicit)) {
404
- return String(Math.max(0, Math.min(23, Math.floor(explicit)))).padStart(2, '0');
405
- }
406
- const raw = delivery.createdAt;
407
- if (raw == null)
411
+ /**
412
+ * `HH` of an ORDER's tenant-local hour.
413
+ *
414
+ * The ONLY hour source allowed in this report: the delivery write path carries no
415
+ * `localHour`, and deriving one from `createdAt` on the server would report UTC (or the
416
+ * server's zone) as if it were tenant-local - silently shifting the demand heat map in
417
+ * every non-UTC tenant.
418
+ *
419
+ * Returns null when the hour is absent or out of range: an unmeasured hour is not hour 0.
420
+ */
421
+ function orderHourKey(order) {
422
+ const hour = Number(order?.localHour);
423
+ if (!Number.isFinite(hour))
408
424
  return null;
409
- const date = new Date(raw);
410
- if (Number.isNaN(date.getTime()))
425
+ const whole = Math.floor(hour);
426
+ if (whole < 0 || whole > 23)
411
427
  return null;
412
- return String(date.getHours()).padStart(2, '0');
428
+ return String(whole).padStart(2, '0');
429
+ }
430
+ /** The area row of this accumulator, created on first use (key -> city). */
431
+ function areaRowFor(counters, key) {
432
+ var _a;
433
+ const parsed = parseMaterializedDeliveryKey(key);
434
+ const city = parsed == null ? DELIVERY_UNKNOWN_TOKEN : parsed.city;
435
+ counters.areas ?? (counters.areas = {});
436
+ return ((_a = counters.areas)[city] ?? (_a[city] = emptyAreaRow()));
413
437
  }
414
438
  /**
415
- * Computes the DERIVED adoption figures and prunes the bounded maps.
439
+ * Computes the DERIVED adoption figures of one key.
416
440
  *
417
441
  * Call ONCE per key, after both stages have been consumed. `off_app_count` is a set
418
442
  * difference, so an order reassigned to a second rider is NOT counted as off-app even
419
443
  * though there are more deliveries than orders.
444
+ *
445
+ * The per-key ORDER SETS are also what fill the area row's order-side adoption counters:
446
+ * a key maps to exactly one RESOLVED area, so `delivery_order_count` /
447
+ * `delivered_via_app_count` of the key ARE that area's figures for this document.
448
+ *
449
+ * The bounded maps are NOT pruned here: the rider cap applies to the whole DOCUMENT
450
+ * (`pruneDocumentDeliveryRiders`) and the city cap is applied when the key is resolved
451
+ * (`buildDeliveryCityResolver`).
420
452
  */
421
453
  export function finalizeDeliveryAccumulator(acc) {
422
454
  const counters = acc.counters;
423
455
  const deliveredOrders = [...acc.deliveredOrderIds].filter((id) => acc.deliveryOrderIds.has(id)).length;
424
456
  counters.adoption.delivered_via_app_count = deliveredOrders;
425
457
  counters.adoption.off_app_count = Math.max(0, acc.deliveryOrderIds.size - deliveredOrders);
426
- counters.riders = pruneMap(counters.riders, MATERIALIZED_DELIVERY_RIDER_LIMIT, (row) => Number(row.count) || 0);
427
- counters.areas = pruneMap(counters.areas, MATERIALIZED_DELIVERY_AREA_LIMIT, (row) => Number(row.count) || 0);
458
+ for (const row of Object.values(counters.areas ?? {})) {
459
+ row.delivery_orders = acc.deliveryOrderIds.size;
460
+ row.app_orders = deliveredOrders;
461
+ row.off_app_orders = counters.adoption.off_app_count;
462
+ }
428
463
  return counters;
429
464
  }
430
- /** Keeps the N busiest entries, so a document stays bounded. */
431
- function pruneMap(source, limit, weightOf) {
432
- if (source == null)
433
- return null;
434
- const entries = Object.entries(source);
435
- if (entries.length <= limit)
436
- return source;
437
- entries.sort((a, b) => weightOf(b[1]) - weightOf(a[1]));
438
- const kept = {};
439
- for (const [key, value] of entries.slice(0, limit))
440
- kept[key] = value;
441
- return kept;
442
- }