@managesome/eposmatic-toolkit 0.4.52 → 0.4.54

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 (164) 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 +6 -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/report-platform/definition.js +508 -0
  18. package/esm/helpers/materialized-reports/report-platform/index.js +4 -0
  19. package/esm/helpers/materialized-reports/report-platform/lifecycle/budget.js +27 -0
  20. package/esm/helpers/materialized-reports/report-platform/lifecycle/cap-metadata.js +12 -0
  21. package/esm/helpers/materialized-reports/report-platform/lifecycle/entry-pages.js +121 -0
  22. package/esm/helpers/materialized-reports/report-platform/lifecycle/flat-projection.js +14 -0
  23. package/esm/helpers/materialized-reports/report-platform/lifecycle/index.js +8 -0
  24. package/esm/helpers/materialized-reports/report-platform/lifecycle/iteration-row.js +10 -0
  25. package/esm/helpers/materialized-reports/report-platform/lifecycle/run-stats.js +42 -0
  26. package/esm/helpers/materialized-reports/report-platform/lifecycle/scope-refs.js +28 -0
  27. package/esm/helpers/materialized-reports/report-platform/lifecycle/top-n.js +24 -0
  28. package/esm/helpers/materialized-reports/report-platform/registry.js +23 -0
  29. package/esm/helpers/materialized-reports/report-platform/validate-report-registry.js +214 -0
  30. package/esm/helpers/materialized-reports/scope-helpers.js +98 -0
  31. package/esm/helpers/materialized-reports/tenant-delivery-formatter.js +70 -20
  32. package/esm/schemas/models/applied_order_discounts.js +103 -0
  33. package/esm/schemas/models/index.js +12 -10
  34. package/esm/schemas/models/materialized_tenant_delivery_entries.js +33 -12
  35. package/esm/schemas/models/materialized_tenant_delivery_geo_cells.js +83 -0
  36. package/esm/schemas/models/materialized_tenant_delivery_geo_scopes.js +35 -0
  37. package/esm/schemas/models/materialized_tenant_delivery_reports.js +10 -1
  38. package/esm/schemas/types/applied_order_discounts.js +1 -0
  39. package/esm/schemas/types/index.js +14 -12
  40. package/esm/schemas/types/materialized_tenant_delivery_geo_cells.js +1 -0
  41. package/esm/schemas/types/materialized_tenant_delivery_geo_scopes.js +1 -0
  42. package/lib/constants/MATERIALIZED_REPORTS.d.ts +95 -1
  43. package/lib/constants/MATERIALIZED_REPORTS.js +108 -4
  44. package/lib/constants/enums/delivery.d.ts +9 -0
  45. package/lib/constants/enums/delivery.js +14 -1
  46. package/lib/helpers/materialized-reports/index.d.ts +6 -0
  47. package/lib/helpers/materialized-reports/index.js +6 -0
  48. package/lib/helpers/materialized-reports/materialized-delivery-accumulator-helpers.js +8 -62
  49. package/lib/helpers/materialized-reports/materialized-delivery-classification-helpers.d.ts +36 -9
  50. package/lib/helpers/materialized-reports/materialized-delivery-classification-helpers.js +94 -72
  51. package/lib/helpers/materialized-reports/materialized-delivery-close-day-helpers.d.ts +23 -26
  52. package/lib/helpers/materialized-reports/materialized-delivery-close-day-helpers.js +121 -150
  53. package/lib/helpers/materialized-reports/materialized-delivery-compile-helpers.d.ts +44 -5
  54. package/lib/helpers/materialized-reports/materialized-delivery-compile-helpers.js +306 -69
  55. package/lib/helpers/materialized-reports/materialized-delivery-entry-pages.d.ts +128 -0
  56. package/lib/helpers/materialized-reports/materialized-delivery-entry-pages.js +322 -0
  57. package/lib/helpers/materialized-reports/materialized-delivery-index-migration.d.ts +48 -0
  58. package/lib/helpers/materialized-reports/materialized-delivery-index-migration.js +108 -0
  59. package/lib/helpers/materialized-reports/materialized-delivery-rows.d.ts +15 -0
  60. package/lib/helpers/materialized-reports/materialized-delivery-rows.js +115 -0
  61. package/lib/helpers/materialized-reports/materialized-delivery-wipe-targets.d.ts +17 -0
  62. package/lib/helpers/materialized-reports/materialized-delivery-wipe-targets.js +35 -0
  63. package/lib/helpers/materialized-reports/materialized-document-size.d.ts +47 -0
  64. package/lib/helpers/materialized-reports/materialized-document-size.js +73 -0
  65. package/lib/helpers/materialized-reports/materialized-index-bootstrap.js +28 -13
  66. package/lib/helpers/materialized-reports/materialized-integer-contract.js +10 -1
  67. package/lib/helpers/materialized-reports/materialized-prep-time-close-day-helpers.js +2 -90
  68. package/lib/helpers/materialized-reports/materialized-tenant-delivery-geo-helpers.d.ts +186 -0
  69. package/lib/helpers/materialized-reports/materialized-tenant-delivery-geo-helpers.js +620 -0
  70. package/lib/helpers/materialized-reports/report-platform/definition.d.ts +133 -0
  71. package/lib/helpers/materialized-reports/report-platform/definition.js +511 -0
  72. package/lib/helpers/materialized-reports/report-platform/index.d.ts +4 -0
  73. package/lib/helpers/materialized-reports/report-platform/index.js +20 -0
  74. package/lib/helpers/materialized-reports/report-platform/lifecycle/budget.d.ts +8 -0
  75. package/lib/helpers/materialized-reports/report-platform/lifecycle/budget.js +31 -0
  76. package/lib/helpers/materialized-reports/report-platform/lifecycle/cap-metadata.d.ts +8 -0
  77. package/lib/helpers/materialized-reports/report-platform/lifecycle/cap-metadata.js +16 -0
  78. package/lib/helpers/materialized-reports/report-platform/lifecycle/entry-pages.d.ts +40 -0
  79. package/lib/helpers/materialized-reports/report-platform/lifecycle/entry-pages.js +130 -0
  80. package/lib/helpers/materialized-reports/report-platform/lifecycle/flat-projection.d.ts +22 -0
  81. package/lib/helpers/materialized-reports/report-platform/lifecycle/flat-projection.js +17 -0
  82. package/lib/helpers/materialized-reports/report-platform/lifecycle/index.d.ts +8 -0
  83. package/lib/helpers/materialized-reports/report-platform/lifecycle/index.js +24 -0
  84. package/lib/helpers/materialized-reports/report-platform/lifecycle/iteration-row.d.ts +13 -0
  85. package/lib/helpers/materialized-reports/report-platform/lifecycle/iteration-row.js +13 -0
  86. package/lib/helpers/materialized-reports/report-platform/lifecycle/run-stats.d.ts +20 -0
  87. package/lib/helpers/materialized-reports/report-platform/lifecycle/run-stats.js +47 -0
  88. package/lib/helpers/materialized-reports/report-platform/lifecycle/scope-refs.d.ts +13 -0
  89. package/lib/helpers/materialized-reports/report-platform/lifecycle/scope-refs.js +31 -0
  90. package/lib/helpers/materialized-reports/report-platform/lifecycle/top-n.d.ts +16 -0
  91. package/lib/helpers/materialized-reports/report-platform/lifecycle/top-n.js +29 -0
  92. package/lib/helpers/materialized-reports/report-platform/registry.d.ts +13 -0
  93. package/lib/helpers/materialized-reports/report-platform/registry.js +31 -0
  94. package/lib/helpers/materialized-reports/report-platform/validate-report-registry.d.ts +20 -0
  95. package/lib/helpers/materialized-reports/report-platform/validate-report-registry.js +218 -0
  96. package/lib/helpers/materialized-reports/scope-helpers.d.ts +8 -0
  97. package/lib/helpers/materialized-reports/scope-helpers.js +99 -0
  98. package/lib/helpers/materialized-reports/tenant-delivery-formatter.d.ts +41 -0
  99. package/lib/helpers/materialized-reports/tenant-delivery-formatter.js +70 -20
  100. package/lib/helpers/order/payment-collection.d.ts +25 -0
  101. package/lib/helpers/order/payment-collection.js +51 -0
  102. package/lib/schemas/models/applied_order_discounts.d.ts +80 -0
  103. package/lib/schemas/models/applied_order_discounts.js +106 -0
  104. package/lib/schemas/models/index.d.ts +12 -10
  105. package/lib/schemas/models/index.js +12 -10
  106. package/lib/schemas/models/materialized_tenant_delivery_entries.d.ts +31 -9
  107. package/lib/schemas/models/materialized_tenant_delivery_entries.js +32 -11
  108. package/lib/schemas/models/materialized_tenant_delivery_geo_cells.d.ts +129 -0
  109. package/lib/schemas/models/materialized_tenant_delivery_geo_cells.js +86 -0
  110. package/lib/schemas/models/materialized_tenant_delivery_geo_scopes.d.ts +71 -0
  111. package/lib/schemas/models/materialized_tenant_delivery_geo_scopes.js +38 -0
  112. package/lib/schemas/models/materialized_tenant_delivery_reports.d.ts +10 -1
  113. package/lib/schemas/models/materialized_tenant_delivery_reports.js +10 -1
  114. package/lib/schemas/models/materialized_tenant_discount_sources.d.ts +15 -15
  115. package/lib/schemas/types/applied_order_discounts.d.ts +22 -0
  116. package/lib/schemas/types/applied_order_discounts.js +2 -0
  117. package/lib/schemas/types/index.d.ts +14 -12
  118. package/lib/schemas/types/index.js +14 -12
  119. package/lib/schemas/types/materialized_tenant_delivery_entries.d.ts +36 -4
  120. package/lib/schemas/types/materialized_tenant_delivery_geo_cells.d.ts +178 -0
  121. package/lib/schemas/types/materialized_tenant_delivery_geo_cells.js +2 -0
  122. package/lib/schemas/types/materialized_tenant_delivery_geo_scopes.d.ts +21 -0
  123. package/lib/schemas/types/materialized_tenant_delivery_geo_scopes.js +2 -0
  124. package/lib/schemas/types/materialized_tenant_delivery_reports.d.ts +49 -7
  125. package/lib/tests/materialized-reports/analytics-growth-helpers.test.d.ts +1 -0
  126. package/lib/tests/materialized-reports/analytics-overview-helpers.test.d.ts +1 -0
  127. package/lib/tests/materialized-reports/analytics-performance-helpers.test.d.ts +1 -0
  128. package/lib/tests/materialized-reports/characterization/delivery.characterization.test.d.ts +1 -0
  129. package/lib/tests/materialized-reports/characterization/delivery.characterization.test.js +229 -0
  130. package/lib/tests/materialized-reports/characterization/discount.characterization.test.d.ts +1 -0
  131. package/lib/tests/materialized-reports/characterization/discount.characterization.test.js +99 -0
  132. package/lib/tests/materialized-reports/characterization/fixtures.d.ts +30 -0
  133. package/lib/tests/materialized-reports/characterization/fixtures.js +402 -0
  134. package/lib/tests/materialized-reports/characterization/golden.d.ts +18 -0
  135. package/lib/tests/materialized-reports/characterization/golden.js +127 -0
  136. package/lib/tests/materialized-reports/characterization/overview.characterization.test.d.ts +1 -0
  137. package/lib/tests/materialized-reports/characterization/overview.characterization.test.js +69 -0
  138. package/lib/tests/materialized-reports/characterization/prep-time.characterization.test.d.ts +1 -0
  139. package/lib/tests/materialized-reports/characterization/prep-time.characterization.test.js +102 -0
  140. package/lib/tests/materialized-reports/materialized-delivery-accumulation.test.js +56 -19
  141. package/lib/tests/materialized-reports/materialized-delivery-budgets.test.d.ts +1 -0
  142. package/lib/tests/materialized-reports/materialized-delivery-budgets.test.js +91 -0
  143. package/lib/tests/materialized-reports/materialized-delivery-compile.test.js +271 -15
  144. package/lib/tests/materialized-reports/materialized-delivery-final-audit.test.d.ts +1 -0
  145. package/lib/tests/materialized-reports/materialized-delivery-final-audit.test.js +128 -0
  146. package/lib/tests/materialized-reports/materialized-delivery-fold.test.js +42 -5
  147. package/lib/tests/materialized-reports/materialized-delivery-formatter.test.js +13 -1
  148. package/lib/tests/materialized-reports/materialized-delivery-geo.test.d.ts +1 -0
  149. package/lib/tests/materialized-reports/materialized-delivery-geo.test.js +446 -0
  150. package/lib/tests/materialized-reports/materialized-delivery-plan.test.js +117 -25
  151. package/lib/tests/materialized-reports/materialized-delivery-practical.test.d.ts +1 -0
  152. package/lib/tests/materialized-reports/materialized-delivery-practical.test.js +344 -0
  153. package/lib/tests/materialized-reports/materialized-integer-contract.test.js +14 -0
  154. package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.js +1 -1
  155. package/lib/tests/materialized-reports/report-platform/lifecycle-primitives.test.d.ts +1 -0
  156. package/lib/tests/materialized-reports/report-platform/lifecycle-primitives.test.js +177 -0
  157. package/lib/tests/materialized-reports/report-platform/registry-conformance.test.d.ts +1 -0
  158. package/lib/tests/materialized-reports/report-platform/registry-conformance.test.js +214 -0
  159. package/lib/tests/materialized-reports/report-platform/registry-validation.test.d.ts +1 -0
  160. package/lib/tests/materialized-reports/report-platform/registry-validation.test.js +103 -0
  161. package/lib/tests/offer-item-resolution.test.js +1 -4
  162. package/lib/tests/payment-collection-timestamps.test.d.ts +1 -0
  163. package/lib/tests/payment-collection-timestamps.test.js +71 -0
  164. package/package.json +6 -2
@@ -0,0 +1,103 @@
1
+ import { Schema } from 'mongoose';
2
+ import { ALL_DISCOUNT_APPLICABILITY_TYPES, ALL_DISCOUNT_TYPES, ALL_PLATFORMS } from '../../constants';
3
+ export const AppliedOrderDiscountsSchema = new Schema({
4
+ _id: {
5
+ type: Schema.Types.ObjectId,
6
+ required: true,
7
+ immutable: true,
8
+ },
9
+ tenant_id: {
10
+ type: String,
11
+ required: true,
12
+ immutable: true,
13
+ ref: 'tenants',
14
+ },
15
+ order_id: {
16
+ type: Schema.Types.ObjectId,
17
+ required: true,
18
+ immutable: true,
19
+ },
20
+ discount_id: {
21
+ type: String,
22
+ required: true,
23
+ },
24
+ type: {
25
+ type: String,
26
+ required: true,
27
+ enum: ALL_DISCOUNT_TYPES,
28
+ },
29
+ applicability: {
30
+ type: String,
31
+ required: true,
32
+ enum: ALL_DISCOUNT_APPLICABILITY_TYPES,
33
+ },
34
+ platform: {
35
+ type: String,
36
+ enum: ALL_PLATFORMS,
37
+ required: true,
38
+ },
39
+ name: {
40
+ type: String,
41
+ required: true,
42
+ },
43
+ order_amount: {
44
+ type: Number,
45
+ required: true,
46
+ min: 0,
47
+ },
48
+ discount_amount: {
49
+ type: Number,
50
+ required: true,
51
+ min: 0,
52
+ },
53
+ discount_rate: {
54
+ type: Number,
55
+ required: false,
56
+ default: null,
57
+ },
58
+ reason: {
59
+ type: String,
60
+ required: true,
61
+ },
62
+ reference_number: {
63
+ type: String,
64
+ required: false,
65
+ },
66
+ staff_id: {
67
+ type: String,
68
+ required: true,
69
+ },
70
+ staff_phone: {
71
+ type: String,
72
+ required: true,
73
+ },
74
+ staff_name: {
75
+ type: String,
76
+ required: true,
77
+ },
78
+ createdAt_mins: {
79
+ type: Number,
80
+ required: true,
81
+ immutable: true,
82
+ default: () => {
83
+ const date = new Date();
84
+ return Math.floor(date.getHours() * 60 + date.getMinutes());
85
+ },
86
+ },
87
+ createdAt: {
88
+ type: Schema.Types.Date,
89
+ required: true,
90
+ default: () => new Date(),
91
+ immutable: true,
92
+ },
93
+ updatedAt: {
94
+ type: Schema.Types.Date,
95
+ required: true,
96
+ default: () => new Date(),
97
+ },
98
+ }, {
99
+ timestamps: true,
100
+ versionKey: false,
101
+ minimize: false,
102
+ });
103
+ export const APPLIED_ORDER_DISCOUNTS_COLLECTION_NAME = 'applied_order_discounts';
@@ -27,24 +27,26 @@ export * from './item_transactions';
27
27
  export * from './items';
28
28
  export * from './marketing_fingerprints';
29
29
  export * from './materialized_credit_bills';
30
- export * from './materialized_tenant_discount_entries';
31
- export * from './materialized_tenant_discount_reports';
32
- export * from './materialized_tenant_discount_sources';
30
+ export * from './materialized_report_drilldown_rows';
31
+ export * from './materialized_rider_daily_reports';
33
32
  export * from './materialized_tenant_cash_entries';
33
+ export * from './materialized_tenant_cash_reports';
34
34
  export * from './materialized_tenant_delivery_entries';
35
+ export * from './materialized_tenant_delivery_geo_cells';
36
+ export * from './materialized_tenant_delivery_geo_scopes';
35
37
  export * from './materialized_tenant_delivery_reports';
36
- export * from './materialized_rider_daily_reports';
37
- export * from './materialized_tenant_cash_reports';
38
+ export * from './materialized_tenant_discount_entries';
39
+ export * from './materialized_tenant_discount_reports';
40
+ export * from './materialized_tenant_discount_sources';
41
+ export * from './materialized_tenant_hourly_comparison_entries';
42
+ export * from './materialized_tenant_hourly_comparison_reports';
43
+ export * from './materialized_tenant_payments_comparison_entries';
44
+ export * from './materialized_tenant_payments_comparison_reports';
38
45
  export * from './materialized_tenant_prep_time_entries';
39
46
  export * from './materialized_tenant_prep_time_reports';
40
47
  export * from './materialized_tenant_reports_iterations';
41
- export * from './materialized_report_drilldown_rows';
42
48
  export * from './materialized_tenant_sales_comparison_entries';
43
49
  export * from './materialized_tenant_sales_comparison_reports';
44
- export * from './materialized_tenant_hourly_comparison_entries';
45
- export * from './materialized_tenant_hourly_comparison_reports';
46
- export * from './materialized_tenant_payments_comparison_entries';
47
- export * from './materialized_tenant_payments_comparison_reports';
48
50
  export * from './materialized_tenant_sales_overview_reports';
49
51
  export * from './menus';
50
52
  export * from './messaging_devices';
@@ -1,19 +1,32 @@
1
1
  import { Schema } from 'mongoose';
2
2
  import { ALL_DAY_INDEX } from '../../constants/ENUMS';
3
- import { ALL_MATERIALIZED_REPORT_KEY_FILTERS, DELIVERY_KEY_FILTERS, MATERIALIZED_DELIVERY_REPORT_SCOPES, } from '../../constants/MATERIALIZED_REPORTS';
3
+ import { ALL_MATERIALIZED_REPORT_KEY_FILTERS, DELIVERY_KEY_FILTERS, MATERIALIZED_DELIVERY_ENTRY_SCOPES, } from '../../constants/MATERIALIZED_REPORTS';
4
4
  /**
5
5
  * Mongoose schema for `materialized_tenant_delivery_entries` (M4).
6
6
  *
7
- * `delivery_entries` is `Mixed` on purpose: it is a key-addressed map of
8
- * bounded sub-documents (rider / area leaderboards with an hour heat map), which Mongoose
9
- * cannot type precisely without a fixed key set - the keys ARE the data.
7
+ * PAGE-PARTITIONED by source day, exactly like the discounts entries: the day scope uses
8
+ * `page='all'`, and every period entry scope (week / ISO week / month) uses
9
+ * `page=<source localDate>`, so a document is bounded by ONE day's rows. Quarter /
10
+ * semester / year entry documents do not exist.
11
+ *
12
+ * `delivery_entries` is `Mixed` on purpose: it is a key-addressed map of rows whose keys
13
+ * are the report's `ORDER_STATUS:PLATFORM:CITY` grammar, which Mongoose cannot type precisely without
14
+ * a fixed key set - the keys ARE the data.
15
+ */
16
+ /**
17
+ * v3 - PAGE-PARTITIONED entry documents (one page per source day, max scope
18
+ * `localMonth`). v2 was one document per period scope, which made a month an unbounded
19
+ * document. Historical v2 documents are not readable by the page-aware read layer and
20
+ * must be re-materialized (re-close the days); the writer deletes the pages it owns.
10
21
  */
11
- export const MATERIALIZED_TENANT_DELIVERY_ENTRIES_SCHEMA_VERSION = 1;
22
+ export const MATERIALIZED_TENANT_DELIVERY_ENTRIES_SCHEMA_VERSION = 3;
12
23
  export const MaterializedTenantDeliveryEntriesSchema = new Schema({
13
24
  tenant_id: { type: String, required: true },
14
25
  brand_id: { type: String, required: true },
15
- scope_context: { type: String, required: true, enum: MATERIALIZED_DELIVERY_REPORT_SCOPES },
26
+ scope_context: { type: String, required: true, enum: MATERIALIZED_DELIVERY_ENTRY_SCOPES },
16
27
  scope_field: { type: String, required: true },
28
+ /** `'all'` for the day scope; the source `YYYY-MM-DD` for a period scope. */
29
+ page: { type: String, required: true, immutable: true },
17
30
  day_index: { type: String, default: null, enum: [...ALL_DAY_INDEX, null] },
18
31
  sale_type_key_filters: {
19
32
  type: [String],
@@ -42,22 +55,30 @@ export const MaterializedTenantDeliveryEntriesSchema = new Schema({
42
55
  }, { timestamps: true, versionKey: false, minimize: false });
43
56
  export const MATERIALIZED_TENANT_DELIVERY_ENTRIES_COLLECTION_NAME = 'materialized_tenant_delivery_entries';
44
57
  /**
45
- * The single UNIQUE compound identity index, like every materialized collection. No
46
- * `brand_id` index - a brand's scopes are resolved before the read.
58
+ * ONE unique index per PAGE: `tenant_id + scope_context + scope_field + page`.
59
+ *
60
+ * The OLD index `{ tenant_id, scope_context, scope_field, day_index }` must NOT survive:
61
+ * period pages all carry `day_index: null`, so it would reject the second page of a
62
+ * month. The OWNER deploy step
63
+ * (`simulations/migrate-delivery-report-indexes.ts --apply`) drops the legacy index by
64
+ * name/key before creating this one. No service calls `ensureMaterializedReportIndexes`
65
+ * automatically; the discounts entry collection has the same migration posture.
66
+ *
67
+ * The same key also serves the multi-page read (tenant + scope prefix, then the pages).
47
68
  */
48
69
  export const MATERIALIZED_TENANT_DELIVERY_ENTRIES_COLLECTION_INDEXES = {
49
70
  _id: { _id: 1 },
50
- tenant_id__scope_context__scope_field__day_index: {
71
+ tenant_id__scope_context__scope_field__page: {
51
72
  tenant_id: 1,
52
73
  scope_context: 1,
53
74
  scope_field: 1,
54
- day_index: 1,
75
+ page: 1,
55
76
  },
56
77
  };
57
78
  export const MATERIALIZED_TENANT_DELIVERY_ENTRIES_INDEX_OPTIONS = [
58
79
  {
59
- key: { tenant_id: 1, scope_context: 1, scope_field: 1, day_index: 1 },
60
- name: 'tenant_id__scope_context__scope_field__day_index',
80
+ key: { tenant_id: 1, scope_context: 1, scope_field: 1, page: 1 },
81
+ name: 'tenant_id__scope_context__scope_field__page',
61
82
  unique: true,
62
83
  },
63
84
  ];
@@ -0,0 +1,83 @@
1
+ import { Schema } from 'mongoose';
2
+ import { MATERIALIZED_DELIVERY_GEO_SCOPES, MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_SCHEMA_VERSION, } from '../../constants/MATERIALIZED_REPORTS';
3
+ /**
4
+ * Mongoose schema for `materialized_tenant_delivery_geo_cells`.
5
+ *
6
+ * `location` is `Mixed` and DELIBERATELY has no default: the unknown bucket must be
7
+ * written WITHOUT the field, because a 2dsphere index cannot extract a geo key from
8
+ * `null`. A missing field is simply not indexed, which is exactly the intent - the
9
+ * unknown aggregate must never be plottable.
10
+ *
11
+ * `city` is nullable: an order whose joined `delivery_details` has no city still
12
+ * counts in the cell (the position is what the heat map plots), it just carries no
13
+ * label.
14
+ */
15
+ export const MaterializedTenantDeliveryGeoCellSchema = new Schema({
16
+ tenant_id: { type: String, required: true },
17
+ brand_id: { type: String, required: true },
18
+ scope_context: { type: String, required: true, enum: MATERIALIZED_DELIVERY_GEO_SCOPES },
19
+ scope_field: { type: String, required: true },
20
+ city: { type: String, default: null },
21
+ h3_cell: { type: String, required: true },
22
+ resolution: { type: Number, required: true, min: 0, max: 15 },
23
+ location: { type: Schema.Types.Mixed, required: false },
24
+ /** Bounded ORDER_STATUS:PLATFORM:CITY counters; sum equals the top-level counters. */
25
+ by_key: { type: Schema.Types.Mixed, required: false, default: null },
26
+ // ---- counters (integer counts; money in CENTS) ----
27
+ orders: { type: Number, required: true, min: 0, default: 0 },
28
+ app_orders: { type: Number, required: true, min: 0, default: 0 },
29
+ delivery_records: { type: Number, required: true, min: 0, default: 0 },
30
+ completed: { type: Number, required: true, min: 0, default: 0 },
31
+ cancelled: { type: Number, required: true, min: 0, default: 0 },
32
+ net_sale_amount: { type: Number, required: true, default: 0 },
33
+ delivery_charge_amount: { type: Number, required: true, default: 0 },
34
+ rider_revenue_amount: { type: Number, required: true, default: 0 },
35
+ schema_version: {
36
+ type: Number,
37
+ required: true,
38
+ immutable: true,
39
+ default: MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_SCHEMA_VERSION,
40
+ },
41
+ computed_at: { type: Schema.Types.Date, required: true },
42
+ createdAt: { type: Schema.Types.Date, required: true, default: () => new Date(), immutable: true },
43
+ updatedAt: { type: Schema.Types.Date, required: true, default: () => new Date() },
44
+ }, { timestamps: true, versionKey: false });
45
+ export const MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_COLLECTION_NAME = 'materialized_tenant_delivery_geo_cells';
46
+ /**
47
+ * The indexes the heat reads/writes assume:
48
+ * 1. the UNIQUE cell identity (one document per tenant/scope/cell);
49
+ * 2. the map's read path - a scope, busiest cells first;
50
+ * 3. the 2dsphere index a future viewport `$geoWithin` read needs.
51
+ *
52
+ * The unknown bucket has no `location`, so it is absent from (3) by design.
53
+ */
54
+ export const MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_COLLECTION_INDEXES = {
55
+ _id: { _id: 1 },
56
+ tenant_id__scope_context__scope_field__h3_cell: {
57
+ tenant_id: 1,
58
+ scope_context: 1,
59
+ scope_field: 1,
60
+ h3_cell: 1,
61
+ },
62
+ scope_context__scope_field__orders: {
63
+ scope_context: 1,
64
+ scope_field: 1,
65
+ orders: -1,
66
+ },
67
+ location__2dsphere: { location: '2dsphere' },
68
+ };
69
+ export const MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_INDEX_OPTIONS = [
70
+ {
71
+ key: { tenant_id: 1, scope_context: 1, scope_field: 1, h3_cell: 1 },
72
+ name: 'tenant_id__scope_context__scope_field__h3_cell',
73
+ unique: true,
74
+ },
75
+ {
76
+ key: { scope_context: 1, scope_field: 1, orders: -1 },
77
+ name: 'scope_context__scope_field__orders',
78
+ },
79
+ {
80
+ key: { location: '2dsphere' },
81
+ name: 'location__2dsphere',
82
+ },
83
+ ];
@@ -0,0 +1,35 @@
1
+ import { Schema } from 'mongoose';
2
+ import { MATERIALIZED_DELIVERY_GEO_SCOPES, MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_SCHEMA_VERSION, } from '../../constants/MATERIALIZED_REPORTS';
3
+ /** Per-scope cap metadata; never one document per cell. */
4
+ export const MaterializedTenantDeliveryGeoScopeSchema = new Schema({
5
+ tenant_id: { type: String, required: true },
6
+ brand_id: { type: String, required: true },
7
+ scope_context: { type: String, required: true, enum: MATERIALIZED_DELIVERY_GEO_SCOPES },
8
+ scope_field: { type: String, required: true },
9
+ capped_cell_count: { type: Number, required: true, min: 0, default: 0 },
10
+ capped_order_count: { type: Number, required: true, min: 0, default: 0 },
11
+ schema_version: {
12
+ type: Number,
13
+ required: true,
14
+ immutable: true,
15
+ default: MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_SCHEMA_VERSION,
16
+ },
17
+ computed_at: { type: Schema.Types.Date, required: true },
18
+ createdAt: { type: Schema.Types.Date, required: true, default: () => new Date(), immutable: true },
19
+ updatedAt: { type: Schema.Types.Date, required: true, default: () => new Date() },
20
+ }, { timestamps: true, versionKey: false });
21
+ export const MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_COLLECTION_INDEXES = {
22
+ _id: { _id: 1 },
23
+ tenant_id__scope_context__scope_field: {
24
+ tenant_id: 1,
25
+ scope_context: 1,
26
+ scope_field: 1,
27
+ },
28
+ };
29
+ export const MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_INDEX_OPTIONS = [
30
+ {
31
+ key: { tenant_id: 1, scope_context: 1, scope_field: 1 },
32
+ name: 'tenant_id__scope_context__scope_field',
33
+ unique: true,
34
+ },
35
+ ];
@@ -8,7 +8,16 @@ import { ALL_MATERIALIZED_REPORT_KEY_FILTERS, DELIVERY_KEY_FILTERS, MATERIALIZED
8
8
  * bounded sub-documents (rider / area leaderboards with an hour heat map), which Mongoose
9
9
  * cannot type precisely without a fixed key set - the keys ARE the data.
10
10
  */
11
- export const MATERIALIZED_TENANT_DELIVERY_REPORTS_SCHEMA_VERSION = 1;
11
+ /**
12
+ * v2 - the production day-close writer.
13
+ *
14
+ * v1 was the pre-production shape. v2 splits the AREA row into the ORDER-side
15
+ * (`delivery_orders`, net sale, fees) and the APP-side (`delivery_records`, payout)
16
+ * populations, keys the demand heat on the joined ORDER's `localHour`, and fixes the
17
+ * refund source to the payment rows. A v1 document is still readable: the formatter
18
+ * falls back to the old `count` field for the record total.
19
+ */
20
+ export const MATERIALIZED_TENANT_DELIVERY_REPORTS_SCHEMA_VERSION = 2;
12
21
  export const MaterializedTenantDeliveryReportSchema = new Schema({
13
22
  tenant_id: { type: String, required: true },
14
23
  brand_id: { type: String, required: true },
@@ -0,0 +1 @@
1
+ export {};
@@ -31,17 +31,26 @@ export * from './item_transactions';
31
31
  export * from './items';
32
32
  export * from './marketing_fingerprints';
33
33
  export * from './materialized_credit_bills';
34
- export * from './materialized_tenant_discount_entries';
35
- export * from './materialized_tenant_discount_reports';
36
- export * from './materialized_tenant_discount_sources';
34
+ export * from './materialized_report_drilldown_rows';
35
+ export * from './materialized_rider_daily_reports';
37
36
  export * from './materialized_tenant_cash_entries';
37
+ export * from './materialized_tenant_cash_reports';
38
38
  export * from './materialized_tenant_delivery_entries';
39
+ export * from './materialized_tenant_delivery_geo_cells';
40
+ export * from './materialized_tenant_delivery_geo_scopes';
39
41
  export * from './materialized_tenant_delivery_reports';
40
- export * from './materialized_rider_daily_reports';
41
- export * from './materialized_tenant_cash_reports';
42
+ export * from './materialized_tenant_discount_entries';
43
+ export * from './materialized_tenant_discount_reports';
44
+ export * from './materialized_tenant_discount_sources';
45
+ export * from './materialized_tenant_hourly_comparison_entries';
46
+ export * from './materialized_tenant_hourly_comparison_reports';
47
+ export * from './materialized_tenant_payments_comparison_entries';
48
+ export * from './materialized_tenant_payments_comparison_reports';
42
49
  export * from './materialized_tenant_prep_time_entries';
43
50
  export * from './materialized_tenant_prep_time_reports';
44
51
  export * from './materialized_tenant_reports_iterations';
52
+ export * from './materialized_tenant_sales_comparison_entries';
53
+ export * from './materialized_tenant_sales_comparison_reports';
45
54
  export * from './materialized_tenant_sales_overview_reports';
46
55
  export * from './menus';
47
56
  export * from './messaging_devices';
@@ -124,10 +133,3 @@ export * from './warehouse_vendors';
124
133
  export * from './warehouse_void_purchase_order_items';
125
134
  export * from './warehouse_void_sale_order_items';
126
135
  export * from './warehouses';
127
- export * from './materialized_tenant_sales_comparison_reports';
128
- export * from './materialized_tenant_sales_comparison_entries';
129
- export * from './materialized_tenant_hourly_comparison_reports';
130
- export * from './materialized_tenant_hourly_comparison_entries';
131
- export * from './materialized_tenant_payments_comparison_reports';
132
- export * from './materialized_tenant_payments_comparison_entries';
133
- export * from './materialized_report_drilldown_rows';
@@ -313,7 +313,30 @@ export declare const MATERIALIZED_CASH_SOURCE_LIMIT = 12;
313
313
  */
314
314
  export declare const MATERIALIZED_DELIVERY_REPORT_SCOPES: MATERIALIZED_REPORT_SCOPE_ENUM[];
315
315
  /**
316
- * Ordered key filters of the delivery report - `<PLATFORM>:<CITY>` (decision (b4)).
316
+ * Scopes the delivery ENTRY documents (and their flat drill-down projection) are
317
+ * materialized for. The WRITER materializes at most `localMonth` for rows, and every
318
+ * period scope is PAGE-PARTITIONED by source day.
319
+ *
320
+ * An entry document is ONE PAGE (one source day), never a whole period: a month is
321
+ * covered by its 28-31 pages. Counters remain year-capable
322
+ * (`MATERIALIZED_DELIVERY_REPORT_SCOPES`). The details READ has NO month cap: it
323
+ * resolves a broad selection to the `localMonth` scopes it touches and filters rows
324
+ * to the exact selected days.
325
+ */
326
+ export declare const MATERIALIZED_DELIVERY_ENTRY_SCOPES: MATERIALIZED_REPORT_SCOPE_ENUM[];
327
+ /**
328
+ * Page key of the DAY-scoped entry document - the day scope is already one day, so it
329
+ * needs no per-source-day partition. Every PERIOD entry scope (week / ISO week / month)
330
+ * is partitioned by the SOURCE local date (`page = <source localDate>`), exactly like
331
+ * `materialized_tenant_discount_entries`.
332
+ *
333
+ * This is what bounds an entry document: one page is one day's rows, never a month's.
334
+ */
335
+ export declare const MATERIALIZED_DELIVERY_ENTRY_PAGE_ALL = "all";
336
+ /**
337
+ * Ordered key filters of the delivery report - `ORDER_STATUS:PLATFORM:CITY`, all joined
338
+ * from the ORDER. Delivery documents carry none of these dimensions, so the report joins
339
+ * by `order_id` and keys on the order's own values.
317
340
  *
318
341
  * Rider is deliberately NOT a key dimension: rider ids are high-cardinality, so rider
319
342
  * analysis is a bounded `riders` map INSIDE each document rather than a partition of
@@ -336,6 +359,77 @@ export declare const MATERIALIZED_DELIVERY_DISTANCE_BUCKETS: {
336
359
  export declare const MATERIALIZED_DELIVERY_RIDER_LIMIT = 50;
337
360
  /** Cap of the per-document area leaderboard (bounded, display-only). */
338
361
  export declare const MATERIALIZED_DELIVERY_AREA_LIMIT = 50;
362
+ /**
363
+ * Token of the ONE overflow row every bounded leaderboard keeps after its top-N.
364
+ *
365
+ * A bounded map would otherwise silently DROP the tail, and a report that drops rows
366
+ * without saying so is indistinguishable from one that never saw them. The overflow
367
+ * row carries the summed counts/money of everything below the cap, so the page can
368
+ * still reconcile against the totals. Reserved: a real rider id or city named
369
+ * `__OTHER__` would collide (ids are ObjectIds / names are human text; documented).
370
+ *
371
+ * Ordering of the TOP-N is deterministic: `count DESC, key ASC` - a non-deterministic
372
+ * tie-break would make two closes of the same day produce different documents.
373
+ */
374
+ export declare const MATERIALIZED_DELIVERY_OTHER_TOKEN = "__OTHER__";
375
+ /**
376
+ * The delivery DEMAND HEAT MAP lives in its OWN collection, never inside the report
377
+ * document: a tenant-day can produce thousands of cells, and the report document is a
378
+ * counters-only document with a hard BSON budget.
379
+ *
380
+ * One document per `tenant_id + scope_context + scope_field + h3_cell`. Only DAY and
381
+ * MONTH scopes are materialized (a heat map is read at those grains); day cells are
382
+ * kept 90 days and month cells 24 months, pruned by the close-day writer.
383
+ */
384
+ export declare const MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_SCHEMA_VERSION = 1;
385
+ /** Small per-scope cap metadata; deliberately NOT stored on every cell. */
386
+ export declare const MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_COLLECTION_NAME = "materialized_tenant_delivery_geo_scopes";
387
+ export declare const MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_SCHEMA_VERSION = 1;
388
+ /**
389
+ * Bounded by_key map per cell (ORDER_STATUS:PLATFORM:CITY).
390
+ *
391
+ * The CITY is part of the key, so one cell can hold orders from several cities and a
392
+ * city filter can still select the EXACT population inside it. That multiplies the key
393
+ * count by the number of cities in a cell, so the bound is generous: a cell normally
394
+ * holds one or two cities, and the cell's own BSON budget (2 MiB) is the real limit.
395
+ */
396
+ export declare const MATERIALIZED_DELIVERY_GEO_MAX_KEYS = 256;
397
+ /** H3 resolution of a heat cell. */
398
+ export declare const MATERIALIZED_DELIVERY_GEO_RESOLUTION = 8;
399
+ /** Scopes the heat map is materialized for - day + month ONLY. */
400
+ export declare const MATERIALIZED_DELIVERY_GEO_SCOPES: MATERIALIZED_REPORT_SCOPE_ENUM[];
401
+ /** Cells with fewer orders than this are not returned by the heat endpoint. */
402
+ export declare const MATERIALIZED_DELIVERY_GEO_MIN_ORDERS = 3;
403
+ /**
404
+ * Hard cap of stored cells per tenant × scope × scope_field. Cells are ranked
405
+ * `orders DESC, h3_cell ASC`; the tail is dropped. Totals never come from the cells -
406
+ * the heat response reads them from the report counters - so a capped map can never
407
+ * misstate the business total.
408
+ */
409
+ export declare const MATERIALIZED_DELIVERY_GEO_MAX_CELLS = 2000;
410
+ /** Day cells are retained 90 days; month cells 24 months. */
411
+ export declare const MATERIALIZED_DELIVERY_GEO_DAY_RETENTION_DAYS = 90;
412
+ export declare const MATERIALIZED_DELIVERY_GEO_MONTH_RETENTION_MONTHS = 24;
413
+ /**
414
+ * Sentinel cell for orders whose coordinates are missing, invalid or (0, 0).
415
+ * It is an AGGREGATE, not a location: the document carries NO `location`, so it can
416
+ * never be mistaken for a point on the map.
417
+ */
418
+ export declare const MATERIALIZED_DELIVERY_GEO_UNKNOWN_CELL = "__UNKNOWN__";
419
+ /**
420
+ * Per-collection BSON budgets (bytes) for the DELIVERY materialization.
421
+ *
422
+ * MongoDB's hard limit is 16 MiB per document. The report and page budgets are the
423
+ * owner-approved practical ceiling (15 MiB), leaving 1 MiB of headroom; a geo cell is
424
+ * a single H3 aggregate and stays at 2 MiB. There is no arbitrary 1 MiB report target.
425
+ *
426
+ * A writer that exceeds its budget fails at COMPILE time with the collection, source day
427
+ * and scope in the message - never midway through the close transaction with a
428
+ * server-side "object too large" error.
429
+ */
430
+ export declare const MATERIALIZED_DELIVERY_REPORT_MAX_BSON_BYTES: number;
431
+ export declare const MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES: number;
432
+ export declare const MATERIALIZED_DELIVERY_GEO_CELL_MAX_BSON_BYTES: number;
339
433
  /**
340
434
  * Scopes materialized by `materialized_tenant_prep_time_reports` — the SUMMARY
341
435
  * range (and the writer's COUNTER scopes).