@managesome/eposmatic-toolkit 0.4.29 → 0.4.31

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 (66) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +9 -12
  2. package/esm/helpers/materialized-reports/index.js +1 -0
  3. package/esm/helpers/materialized-reports/materialized-credit-bills-helpers.js +129 -20
  4. package/esm/helpers/materialized-reports/materialized-discount-classification-helpers.js +10 -3
  5. package/esm/helpers/materialized-reports/materialized-discount-close-day-helpers.js +251 -240
  6. package/esm/helpers/materialized-reports/materialized-discount-compile-helpers.js +2 -1
  7. package/esm/helpers/materialized-reports/materialized-discount-source-helpers.js +176 -0
  8. package/esm/helpers/materialized-reports/materialized-index-bootstrap.js +83 -0
  9. package/esm/helpers/materialized-reports/materialized-integer-contract.js +30 -4
  10. package/esm/helpers/materialized-reports/materialized-report-drilldown-rows.js +4 -2
  11. package/esm/helpers/materialized-reports/materialized-reports-selection-helpers.js +7 -0
  12. package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +284 -43
  13. package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +4 -4
  14. package/esm/schemas/models/materialized_report_drilldown_rows.js +39 -12
  15. package/esm/schemas/models/materialized_tenant_discount_entries.js +18 -12
  16. package/esm/schemas/models/materialized_tenant_discount_sources.js +1 -1
  17. package/esm/schemas/models/orders.js +5 -0
  18. package/esm/schemas/models/tenant_active_jobs.js +7 -0
  19. package/esm/schemas/models/tenant_calendar.js +12 -0
  20. package/lib/constants/MATERIALIZED_REPORTS.d.ts +9 -12
  21. package/lib/constants/MATERIALIZED_REPORTS.js +11 -14
  22. package/lib/helpers/materialized-reports/index.d.ts +1 -0
  23. package/lib/helpers/materialized-reports/index.js +1 -0
  24. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.d.ts +38 -0
  25. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.js +129 -19
  26. package/lib/helpers/materialized-reports/materialized-discount-classification-helpers.js +10 -3
  27. package/lib/helpers/materialized-reports/materialized-discount-close-day-helpers.d.ts +23 -61
  28. package/lib/helpers/materialized-reports/materialized-discount-close-day-helpers.js +250 -239
  29. package/lib/helpers/materialized-reports/materialized-discount-compile-helpers.d.ts +4 -4
  30. package/lib/helpers/materialized-reports/materialized-discount-compile-helpers.js +1 -0
  31. package/lib/helpers/materialized-reports/materialized-discount-source-helpers.d.ts +17 -0
  32. package/lib/helpers/materialized-reports/materialized-discount-source-helpers.js +178 -0
  33. package/lib/helpers/materialized-reports/materialized-index-bootstrap.d.ts +7 -0
  34. package/lib/helpers/materialized-reports/materialized-index-bootstrap.js +87 -0
  35. package/lib/helpers/materialized-reports/materialized-integer-contract.d.ts +3 -1
  36. package/lib/helpers/materialized-reports/materialized-integer-contract.js +30 -4
  37. package/lib/helpers/materialized-reports/materialized-report-drilldown-rows.d.ts +2 -2
  38. package/lib/helpers/materialized-reports/materialized-report-drilldown-rows.js +4 -2
  39. package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.js +7 -0
  40. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +8 -0
  41. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +283 -42
  42. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +4 -4
  43. package/lib/schemas/models/materialized_report_drilldown_rows.d.ts +40 -6
  44. package/lib/schemas/models/materialized_report_drilldown_rows.js +39 -12
  45. package/lib/schemas/models/materialized_tenant_discount_entries.d.ts +33 -29
  46. package/lib/schemas/models/materialized_tenant_discount_entries.js +18 -12
  47. package/lib/schemas/models/materialized_tenant_discount_sources.d.ts +6 -6
  48. package/lib/schemas/models/materialized_tenant_discount_sources.js +1 -1
  49. package/lib/schemas/models/orders.d.ts +5 -0
  50. package/lib/schemas/models/orders.js +5 -0
  51. package/lib/schemas/models/tenant_active_jobs.d.ts +7 -0
  52. package/lib/schemas/models/tenant_active_jobs.js +8 -1
  53. package/lib/schemas/models/tenant_calendar.d.ts +13 -0
  54. package/lib/schemas/models/tenant_calendar.js +13 -1
  55. package/lib/schemas/types/materialized_report_drilldown_rows.d.ts +8 -0
  56. package/lib/schemas/types/materialized_tenant_discount_entries.d.ts +9 -5
  57. package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.js +56 -1
  58. package/lib/tests/materialized-reports/materialized-discount-classification.test.js +17 -0
  59. package/lib/tests/materialized-reports/materialized-discount-close-day.test.js +60 -54
  60. package/lib/tests/materialized-reports/materialized-discount-entries-accumulation.test.js +14 -13
  61. package/lib/tests/materialized-reports/materialized-discount-sources.test.js +76 -0
  62. package/lib/tests/materialized-reports/materialized-integer-contract.test.js +11 -0
  63. package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.js +2 -2
  64. package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +152 -7
  65. package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +89 -0
  66. 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,12 @@ 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
- /**
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.
94
- */
95
- existingEntriesComplete?: boolean;
96
73
  /**
97
74
  * Stored `localDate` COUNTER documents of the same tenant (the sibling days
98
75
  * inside the touched periods, excluding the closing day), used ONLY to
@@ -105,6 +82,8 @@ export interface IBuildTenantDiscountCloseDayPlanInput {
105
82
  * belong to the created scope.
106
83
  */
107
84
  existingPeriodDayDocuments?: IMaterializedTenantDiscountReport[];
85
+ /** Stored `localMonth` counters for quarter/semester/year repair (never weeks). */
86
+ existingPeriodMonthDocuments?: IMaterializedTenantDiscountReport[];
108
87
  /** Why this close is applied — stored as every history row's `reason`. */
109
88
  reason: string;
110
89
  /** Force structural writes even when the watermarks are up to date. */
@@ -115,7 +94,10 @@ export interface IBuildTenantDiscountCloseDayPlanInput {
115
94
  export interface ITenantDiscountCloseDayPlan {
116
95
  /** Counter writes (report + history row) — persist in any order. */
117
96
  writes: IMaterializedDiscountCloseDayWrite<IMaterializedTenantDiscountReport>[];
118
- /** 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
+ */
119
101
  entryWrites: IMaterializedDiscountCloseDayWrite<IMaterializedTenantDiscountEntries>[];
120
102
  /** Stored DAY-scoped counter docs no longer backed by activity — delete by `_id`. */
121
103
  staleDocuments: IMaterializedTenantDiscountReport[];
@@ -136,22 +118,9 @@ export interface ITenantDiscountCloseDayPlan {
136
118
  /** Every stored scope one local day's plan needs (date + 3 periods + 24 hours). */
137
119
  export declare function getMaterializedDiscountScopeRefsForDay(localDate: string): IMaterializedDiscountScopeRef[] | null;
138
120
  /**
139
- * Every `localDate` day label whose day-scoped ENTRY documents can belong to the
140
- * periods the closing day rolls into (`week`, ISO week, month — whatever
141
- * `MATERIALIZED_DISCOUNT_REPORT_SCOPES` accumulates).
142
- *
143
- * This is the **sibling-day fetch contract** in code: a close caller must fetch
144
- * every `localDate` entry document whose `scope_field` is in this set, in
145
- * addition to the day's own scope refs. Period entry documents are DERIVED from
146
- * day rows, so a period document that was never persisted can only be rebuilt
147
- * from the sibling days — without them the plan rebuilds the period from the
148
- * closing day alone and every other day silently disappears from the period
149
- * drill-down (see `buildTenantDiscountCloseDayPlan`).
150
- *
151
- * The returned set always contains `localDate` itself and is sorted. Returns
152
- * `null` (never throws) for a malformed date or an unparseable period value —
153
- * a `null` means the caller must fail loudly rather than pass an incomplete
154
- * `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.
155
124
  */
156
125
  export declare function getMaterializedDiscountPeriodDayScopeFields(localDate: string): string[] | null;
157
126
  /**
@@ -201,20 +170,13 @@ export declare const mergeMaterializedDiscountEntrySections: (stored: Record<str
201
170
  */
202
171
  export declare const subtractMaterializedDiscountEntrySections: (stored: Record<string, IMaterializedDiscountKeySection> | null | undefined, removed: Record<string, IMaterializedDiscountKeySection> | null | undefined) => Record<string, IMaterializedDiscountKeySection>;
203
172
  /**
204
- * Updates a stored ENTRY document.
205
- *
206
- * - DAY scopes (`localHour` / `localDate`) are REPLACED wholesale: the day's rows
207
- * are the whole truth for that scope.
208
- * - PERIOD scopes (`localWeek` / `localWeekOfYear` / `localMonth`) MERGE, because
209
- * the compile produces only ONE day of rows: replacing would leave the period
210
- * 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.
211
175
  *
212
- * Returns null when the documents disagree on schema/scope (a data issue the
213
- * caller must surface).
176
+ * Returns null when the documents disagree on schema/scope/page.
214
177
  */
215
178
  export declare function updateMaterializedDiscountEntries(existing: IMaterializedTenantDiscountEntries | null | undefined, compiled: IMaterializedTenantDiscountEntries | null | undefined, options?: {
216
179
  computedAt?: Date;
217
- mergePeriodRows?: boolean;
218
180
  }): IMaterializedTenantDiscountEntries | null;
219
181
  /** True when a stored entry document equals the compiled one's rows + watermark. */
220
182
  export declare function needsMaterializedDiscountEntriesWrite(existing: IMaterializedTenantDiscountEntries | null | undefined, incoming: IMaterializedTenantDiscountEntries | null | undefined): boolean;