@managesome/eposmatic-toolkit 0.4.28 → 0.4.30

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 (89) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +9 -12
  2. package/esm/helpers/materialized-reports/index.js +2 -0
  3. package/esm/helpers/materialized-reports/materialized-credit-bills-helpers.js +178 -40
  4. package/esm/helpers/materialized-reports/materialized-day-input-signature.js +103 -0
  5. package/esm/helpers/materialized-reports/materialized-discount-classification-helpers.js +10 -3
  6. package/esm/helpers/materialized-reports/materialized-discount-close-day-helpers.js +299 -227
  7. package/esm/helpers/materialized-reports/materialized-discount-compile-helpers.js +20 -1
  8. package/esm/helpers/materialized-reports/materialized-discount-source-helpers.js +176 -0
  9. package/esm/helpers/materialized-reports/materialized-index-bootstrap.js +64 -0
  10. package/esm/helpers/materialized-reports/materialized-integer-contract.js +30 -4
  11. package/esm/helpers/materialized-reports/materialized-report-drilldown-rows.js +4 -2
  12. package/esm/helpers/materialized-reports/materialized-reports-selection-helpers.js +7 -0
  13. package/esm/helpers/materialized-reports/scope-helpers.js +27 -0
  14. package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +400 -46
  15. package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +28 -6
  16. package/esm/schemas/models/materialized_credit_bills.js +8 -0
  17. package/esm/schemas/models/materialized_report_drilldown_rows.js +39 -12
  18. package/esm/schemas/models/materialized_tenant_discount_entries.js +18 -12
  19. package/esm/schemas/models/materialized_tenant_discount_reports.js +9 -0
  20. package/esm/schemas/models/materialized_tenant_discount_sources.js +1 -1
  21. package/esm/schemas/models/materialized_tenant_sales_overview_reports.js +9 -0
  22. package/esm/schemas/models/orders.js +5 -0
  23. package/esm/schemas/models/tenant_active_jobs.js +8 -0
  24. package/esm/schemas/models/tenant_calendar.js +12 -0
  25. package/lib/constants/MATERIALIZED_REPORTS.d.ts +9 -12
  26. package/lib/constants/MATERIALIZED_REPORTS.js +11 -14
  27. package/lib/helpers/materialized-reports/index.d.ts +2 -0
  28. package/lib/helpers/materialized-reports/index.js +2 -0
  29. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.d.ts +66 -2
  30. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.js +179 -39
  31. package/lib/helpers/materialized-reports/materialized-day-input-signature.d.ts +66 -0
  32. package/lib/helpers/materialized-reports/materialized-day-input-signature.js +108 -0
  33. package/lib/helpers/materialized-reports/materialized-discount-classification-helpers.js +10 -3
  34. package/lib/helpers/materialized-reports/materialized-discount-close-day-helpers.d.ts +41 -60
  35. package/lib/helpers/materialized-reports/materialized-discount-close-day-helpers.js +298 -226
  36. package/lib/helpers/materialized-reports/materialized-discount-compile-helpers.d.ts +4 -4
  37. package/lib/helpers/materialized-reports/materialized-discount-compile-helpers.js +19 -0
  38. package/lib/helpers/materialized-reports/materialized-discount-source-helpers.d.ts +17 -0
  39. package/lib/helpers/materialized-reports/materialized-discount-source-helpers.js +178 -0
  40. package/lib/helpers/materialized-reports/materialized-index-bootstrap.d.ts +7 -0
  41. package/lib/helpers/materialized-reports/materialized-index-bootstrap.js +68 -0
  42. package/lib/helpers/materialized-reports/materialized-integer-contract.d.ts +3 -1
  43. package/lib/helpers/materialized-reports/materialized-integer-contract.js +30 -4
  44. package/lib/helpers/materialized-reports/materialized-report-drilldown-rows.d.ts +2 -2
  45. package/lib/helpers/materialized-reports/materialized-report-drilldown-rows.js +4 -2
  46. package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.js +7 -0
  47. package/lib/helpers/materialized-reports/scope-helpers.d.ts +22 -0
  48. package/lib/helpers/materialized-reports/scope-helpers.js +28 -0
  49. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +49 -3
  50. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +398 -44
  51. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.d.ts +4 -1
  52. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +28 -6
  53. package/lib/schemas/models/materialized_credit_bills.d.ts +3 -0
  54. package/lib/schemas/models/materialized_credit_bills.js +8 -0
  55. package/lib/schemas/models/materialized_report_drilldown_rows.d.ts +40 -6
  56. package/lib/schemas/models/materialized_report_drilldown_rows.js +39 -12
  57. package/lib/schemas/models/materialized_tenant_discount_entries.d.ts +33 -29
  58. package/lib/schemas/models/materialized_tenant_discount_entries.js +18 -12
  59. package/lib/schemas/models/materialized_tenant_discount_reports.d.ts +3 -0
  60. package/lib/schemas/models/materialized_tenant_discount_reports.js +9 -0
  61. package/lib/schemas/models/materialized_tenant_discount_sources.d.ts +6 -6
  62. package/lib/schemas/models/materialized_tenant_discount_sources.js +1 -1
  63. package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +3 -0
  64. package/lib/schemas/models/materialized_tenant_sales_overview_reports.js +9 -0
  65. package/lib/schemas/models/orders.d.ts +5 -0
  66. package/lib/schemas/models/orders.js +5 -0
  67. package/lib/schemas/models/tenant_active_jobs.d.ts +3 -0
  68. package/lib/schemas/models/tenant_active_jobs.js +8 -0
  69. package/lib/schemas/models/tenant_calendar.d.ts +13 -0
  70. package/lib/schemas/models/tenant_calendar.js +13 -1
  71. package/lib/schemas/types/materialized_credit_bills.d.ts +6 -0
  72. package/lib/schemas/types/materialized_report_drilldown_rows.d.ts +8 -0
  73. package/lib/schemas/types/materialized_tenant_discount_entries.d.ts +9 -5
  74. package/lib/schemas/types/materialized_tenant_discount_reports.d.ts +6 -0
  75. package/lib/schemas/types/materialized_tenant_reports_iterations.d.ts +9 -0
  76. package/lib/schemas/types/materialized_tenant_sales_overview_reports.d.ts +14 -0
  77. package/lib/schemas/types/tenant_active_jobs.d.ts +8 -0
  78. package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.js +56 -1
  79. package/lib/tests/materialized-reports/materialized-day-input-signature.test.d.ts +1 -0
  80. package/lib/tests/materialized-reports/materialized-day-input-signature.test.js +81 -0
  81. package/lib/tests/materialized-reports/materialized-discount-classification.test.js +17 -0
  82. package/lib/tests/materialized-reports/materialized-discount-close-day.test.js +148 -53
  83. package/lib/tests/materialized-reports/materialized-discount-entries-accumulation.test.js +14 -13
  84. package/lib/tests/materialized-reports/materialized-discount-sources.test.js +76 -0
  85. package/lib/tests/materialized-reports/materialized-integer-contract.test.js +11 -0
  86. package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.js +2 -2
  87. package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +311 -4
  88. package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +89 -0
  89. package/package.json +1 -1
@@ -17,15 +17,14 @@ import { IMaterializedTenantReportIterationInput } from '../../schemas/types/mat
17
17
  * subtracts the stored DATE document (the day's previous delta) before adding
18
18
  * the fresh compile. Each write carries its
19
19
  * `materialized_tenant_reports_iterations` history row — persist both.
20
- * - **`entryWrites`** — the day's `materialized_tenant_discount_entries`
21
- * documents. Rows are NOT accumulated across days (a row belongs to exactly
22
- * one day), so each scope document is REPLACED by the day's rows; a scope with
23
- * no rows is dropped from the day (and its stored document, if any, becomes
24
- * stale).
25
- * - **`staleDocuments`** / **`staleEntryDocuments`** — stored day-scoped
20
+ * - **`entryWrites`** — the closing day's `materialized_tenant_discount_entries`
21
+ * PAGES. Day/hour pages are `page='all'`; each period scope contributes one
22
+ * page for the source `localDate`. A page is REPLACED wholesale; a page with no
23
+ * rows is deleted. Other days' pages are never in the input and never touched.
24
+ * - **`staleDocuments`** / **`staleEntryDocuments`** — stored day-owned
26
25
  * documents whose activity disappeared (orders deleted / moved) — delete by
27
- * `_id`. Only DAY-scoped documents (date + hour) go stale; period documents
28
- * are corrected by subtraction instead.
26
+ * `_id`. Period COUNTERS are corrected by subtraction; period ENTRY pages are
27
+ * deleted/replaced page-by-page.
29
28
  * - **`skippedDocuments`** / **`skippedEntryDocuments`** — already up to date
30
29
  * (see `needsMaterializedDiscountReportWrite`).
31
30
  *
@@ -65,34 +64,26 @@ export interface IBuildTenantDiscountCloseDayPlanInput {
65
64
  */
66
65
  existing?: IMaterializedTenantDiscountReport[];
67
66
  /**
68
- * Stored ENTRY documents, in plain JSON (`.lean()`).
69
- *
70
- * Required content - **both** of these, and the plan's repairs depend on it:
71
- *
72
- * 1. the day's own scope refs (its `localDate` + `localHour` entry documents and
73
- * the PERIOD entry documents it rolls into);
74
- * 2. **the period's DAY-scoped entry documents** - every `localDate` entry document
75
- * whose period refs (`getMaterializedDiscountScopeRefsForDay`) include one of
76
- * those period scopes.
77
- *
78
- * (2) is not an optimisation. Period rows are DERIVED from day rows, so a period
79
- * document that was never persisted - a partial failure between the counter writes
80
- * and the entry writes, which are persisted separately - can only be rebuilt from
81
- * the day documents still on hand. Without them it is rebuilt from the closing day
82
- * alone and every sibling day silently disappears from the period drill-down.
83
- *
84
- * **Under-fetching is silent.** A caller passing only (1) still gets correct
85
- * emptied-day, correction and shrink behaviour; only the missing-document repair
86
- * degrades. That is why (2) is part of the contract rather than a hint.
67
+ * Stored ENTRY pages owned by THIS close, in plain JSON (`.lean()`):
68
+ * the closing day's date/hour pages (`page = 'all'`) and the closing day's
69
+ * period pages (`page = localDate`). No other page is fetched or touched.
70
+ * A stored entry without a page is inconsistent input and fails the plan.
87
71
  */
88
72
  existingEntries?: IMaterializedTenantDiscountEntries[];
89
73
  /**
90
- * Set only when `existingEntries` contains every stored DAY-scoped entry
91
- * document in the touched periods. A period entry document that is missing
92
- * while its counter document exists can only be repaired from that complete
93
- * set; without this acknowledgement the plan refuses to guess.
74
+ * Stored `localDate` COUNTER documents of the same tenant (the sibling days
75
+ * inside the touched periods, excluding the closing day), used ONLY to
76
+ * rebuild a MISSING period counter document.
77
+ *
78
+ * A period counter document is a running sum. Creating it from the closing
79
+ * day alone would leave every earlier materialized day out of the period
80
+ * while those days' `localDate` documents still exist, so `localMonth` would
81
+ * no longer equal the sum of its days. The plan folds the siblings that
82
+ * belong to the created scope.
94
83
  */
95
- existingEntriesComplete?: boolean;
84
+ existingPeriodDayDocuments?: IMaterializedTenantDiscountReport[];
85
+ /** Stored `localMonth` counters for quarter/semester/year repair (never weeks). */
86
+ existingPeriodMonthDocuments?: IMaterializedTenantDiscountReport[];
96
87
  /** Why this close is applied — stored as every history row's `reason`. */
97
88
  reason: string;
98
89
  /** Force structural writes even when the watermarks are up to date. */
@@ -103,7 +94,10 @@ export interface IBuildTenantDiscountCloseDayPlanInput {
103
94
  export interface ITenantDiscountCloseDayPlan {
104
95
  /** Counter writes (report + history row) — persist in any order. */
105
96
  writes: IMaterializedDiscountCloseDayWrite<IMaterializedTenantDiscountReport>[];
106
- /** Entry writes (rows + history row) — persist after the counter writes. */
97
+ /**
98
+ * Entry PAGE writes (rows + full-page history row) — persist after counters.
99
+ * A period scope contributes ONE page per source day.
100
+ */
107
101
  entryWrites: IMaterializedDiscountCloseDayWrite<IMaterializedTenantDiscountEntries>[];
108
102
  /** Stored DAY-scoped counter docs no longer backed by activity — delete by `_id`. */
109
103
  staleDocuments: IMaterializedTenantDiscountReport[];
@@ -115,32 +109,26 @@ export interface ITenantDiscountCloseDayPlan {
115
109
  skippedEntryDocuments: IMaterializedTenantDiscountEntries[];
116
110
  /** Period counter docs this close CREATED because they were absent. */
117
111
  createdPeriodDocuments: IMaterializedDiscountScopeRef[];
112
+ /**
113
+ * Stored sibling DAY documents folded into those created period counter
114
+ * documents (see `existingPeriodDayDocuments`). 0 = nothing to repair.
115
+ */
116
+ foldedPeriodDayDocuments: number;
118
117
  }
119
118
  /** Every stored scope one local day's plan needs (date + 3 periods + 24 hours). */
120
119
  export declare function getMaterializedDiscountScopeRefsForDay(localDate: string): IMaterializedDiscountScopeRef[] | null;
121
120
  /**
122
- * Every `localDate` day label whose day-scoped ENTRY documents can belong to the
123
- * periods the closing day rolls into (`week`, ISO week, month — whatever
124
- * `MATERIALIZED_DISCOUNT_REPORT_SCOPES` accumulates).
125
- *
126
- * This is the **sibling-day fetch contract** in code: a close caller must fetch
127
- * every `localDate` entry document whose `scope_field` is in this set, in
128
- * addition to the day's own scope refs. Period entry documents are DERIVED from
129
- * day rows, so a period document that was never persisted can only be rebuilt
130
- * from the sibling days — without them the plan rebuilds the period from the
131
- * closing day alone and every other day silently disappears from the period
132
- * drill-down (see `buildTenantDiscountCloseDayPlan`).
133
- *
134
- * The returned set always contains `localDate` itself and is sorted. Returns
135
- * `null` (never throws) for a malformed date or an unparseable period value —
136
- * a `null` means the caller must fail loudly rather than pass an incomplete
137
- * `existingEntries` set with `existingEntriesComplete: true`.
121
+ * Every `localDate` label whose day-scoped COUNTER documents can belong to the
122
+ * periods the closing day rolls into. Used ONLY to repair a missing period
123
+ * counter; entry pages are keyed by the closed day and never use this set.
138
124
  */
139
125
  export declare function getMaterializedDiscountPeriodDayScopeFields(localDate: string): string[] | null;
140
126
  /**
141
127
  * Watermark guard: does the stored document need a structural write?
142
128
  * `false` (skip) when the incoming `source_watermark` is not newer than the
143
- * stored one and the schema version + key grammar match.
129
+ * stored one, the day-input SIGNATURE is unchanged, and the schema version +
130
+ * key grammar match. The signature catches a deleted / moved order whose
131
+ * removal lowered the incoming watermark.
144
132
  */
145
133
  export declare function needsMaterializedDiscountReportWrite(existing: IMaterializedTenantDiscountReport | null | undefined, incoming: IMaterializedTenantDiscountReport | null | undefined): boolean;
146
134
  /**
@@ -182,20 +170,13 @@ export declare const mergeMaterializedDiscountEntrySections: (stored: Record<str
182
170
  */
183
171
  export declare const subtractMaterializedDiscountEntrySections: (stored: Record<string, IMaterializedDiscountKeySection> | null | undefined, removed: Record<string, IMaterializedDiscountKeySection> | null | undefined) => Record<string, IMaterializedDiscountKeySection>;
184
172
  /**
185
- * Updates a stored ENTRY document.
186
- *
187
- * - DAY scopes (`localHour` / `localDate`) are REPLACED wholesale: the day's rows
188
- * are the whole truth for that scope.
189
- * - PERIOD scopes (`localWeek` / `localWeekOfYear` / `localMonth`) MERGE, because
190
- * the compile produces only ONE day of rows: replacing would leave the period
191
- * showing just its final day.
173
+ * Updates ONE stored ENTRY PAGE by replacing it with the compiled page. Rows
174
+ * never merge across pages; a source day is the whole truth for its page.
192
175
  *
193
- * Returns null when the documents disagree on schema/scope (a data issue the
194
- * caller must surface).
176
+ * Returns null when the documents disagree on schema/scope/page.
195
177
  */
196
178
  export declare function updateMaterializedDiscountEntries(existing: IMaterializedTenantDiscountEntries | null | undefined, compiled: IMaterializedTenantDiscountEntries | null | undefined, options?: {
197
179
  computedAt?: Date;
198
- mergePeriodRows?: boolean;
199
180
  }): IMaterializedTenantDiscountEntries | null;
200
181
  /** True when a stored entry document equals the compiled one's rows + watermark. */
201
182
  export declare function needsMaterializedDiscountEntriesWrite(existing: IMaterializedTenantDiscountEntries | null | undefined, incoming: IMaterializedTenantDiscountEntries | null | undefined): boolean;