@managesome/eposmatic-toolkit 0.4.5 → 0.4.8

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 (68) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +33 -0
  2. package/esm/constants/REPORT_CALENDAR.js +47 -0
  3. package/esm/constants/index.js +1 -0
  4. package/esm/helpers/materialized-reports/index.js +2 -0
  5. package/esm/helpers/materialized-reports/materialized-credit-bills-helpers.js +982 -0
  6. package/esm/helpers/materialized-reports/materialized-reports-read-helpers.js +1 -76
  7. package/esm/helpers/materialized-reports/materialized-reports-selection-helpers.js +716 -0
  8. package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +327 -41
  9. package/esm/helpers/materialized-reports/tenant-sales-overview-formatter.js +72 -11
  10. package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +118 -235
  11. package/esm/helpers/types/index.js +1 -0
  12. package/esm/schemas/models/index.js +1 -0
  13. package/esm/schemas/models/materialized_credit_bills.js +265 -0
  14. package/esm/schemas/models/materialized_tenant_reports_iterations.js +13 -0
  15. package/esm/schemas/models/materialized_tenant_sales_overview_reports.js +39 -97
  16. package/esm/schemas/types/index.js +1 -0
  17. package/esm/schemas/types/materialized_credit_bills.js +1 -0
  18. package/lib/constants/MATERIALIZED_REPORTS.d.ts +28 -2
  19. package/lib/constants/MATERIALIZED_REPORTS.js +34 -1
  20. package/lib/constants/REPORT_CALENDAR.d.ts +31 -0
  21. package/lib/constants/REPORT_CALENDAR.js +50 -0
  22. package/lib/constants/index.d.ts +1 -0
  23. package/lib/constants/index.js +1 -0
  24. package/lib/helpers/materialized-reports/index.d.ts +2 -0
  25. package/lib/helpers/materialized-reports/index.js +2 -0
  26. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.d.ts +307 -0
  27. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.js +1003 -0
  28. package/lib/helpers/materialized-reports/materialized-reports-read-helpers.d.ts +0 -30
  29. package/lib/helpers/materialized-reports/materialized-reports-read-helpers.js +0 -76
  30. package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.d.ts +59 -0
  31. package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.js +723 -0
  32. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +66 -8
  33. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +326 -40
  34. package/lib/helpers/materialized-reports/tenant-sales-overview-formatter.d.ts +18 -2
  35. package/lib/helpers/materialized-reports/tenant-sales-overview-formatter.js +72 -11
  36. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.d.ts +46 -37
  37. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +119 -238
  38. package/lib/helpers/types/index.d.ts +1 -0
  39. package/lib/helpers/types/index.js +1 -0
  40. package/lib/helpers/types/materialized-reports-apis.d.ts +46 -17
  41. package/lib/helpers/types/report-calendar.d.ts +20 -0
  42. package/lib/helpers/types/report-calendar.js +2 -0
  43. package/lib/schemas/models/index.d.ts +1 -0
  44. package/lib/schemas/models/index.js +1 -0
  45. package/lib/schemas/models/materialized_credit_bills.d.ts +337 -0
  46. package/lib/schemas/models/materialized_credit_bills.js +268 -0
  47. package/lib/schemas/models/materialized_tenant_reports_iterations.d.ts +20 -6
  48. package/lib/schemas/models/materialized_tenant_reports_iterations.js +14 -1
  49. package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +37 -165
  50. package/lib/schemas/models/materialized_tenant_sales_overview_reports.js +40 -98
  51. package/lib/schemas/types/index.d.ts +1 -0
  52. package/lib/schemas/types/index.js +1 -0
  53. package/lib/schemas/types/materialized_credit_bills.d.ts +139 -0
  54. package/lib/schemas/types/materialized_credit_bills.js +2 -0
  55. package/lib/schemas/types/materialized_tenant_sales_overview_reports.d.ts +32 -77
  56. package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.d.ts +1 -0
  57. package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.js +715 -0
  58. package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.d.ts +1 -0
  59. package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.js +262 -0
  60. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-schema.test.js +9 -0
  61. package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.js +23 -24
  62. package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +327 -22
  63. package/lib/tests/materialized-reports/tenant-sales-overview-formatter-aggregated.test.js +27 -2
  64. package/lib/tests/materialized-reports/tenant-sales-overview-formatter.test.js +12 -27
  65. package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +79 -146
  66. package/package.json +1 -1
  67. package/lib/tests/materialized-reports/materialized-reports-read-helpers.test.js +0 -100
  68. /package/{lib/tests/materialized-reports/materialized-reports-read-helpers.test.d.ts → esm/helpers/types/report-calendar.js} +0 -0
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_COLLECTION_INDEXES = exports.MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_COLLECTION_NAME = exports.MaterializedTenantSalesOverviewReportSchema = exports.MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_SCHEMA_VERSION = void 0;
3
+ exports.MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_INDEX_OPTIONS = exports.MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_COLLECTION_INDEXES = exports.MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_COLLECTION_NAME = exports.MaterializedTenantSalesOverviewReportSchema = exports.MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_SCHEMA_VERSION = void 0;
4
4
  const mongoose_1 = require("mongoose");
5
5
  const constants_1 = require("../../constants");
6
6
  const ENUMS_1 = require("../../constants/ENUMS");
@@ -15,17 +15,20 @@ const MATERIALIZED_REPORTS_1 = require("../../constants/MATERIALIZED_REPORTS");
15
15
  * `MATERIALIZED_REPORTS.md`). The report's time-bias toggle (Punched At /
16
16
  * `createdAt`) is out of scope. `scope_field` formats are documented on
17
17
  * `MATERIALIZED_REPORT_SCOPE_ENUM` and in `MATERIALIZED_REPORTS.md`.
18
- * Credit bills (`PAY_LATER`) live in each `sale_type_metrics` key's
19
- * `CREDIT_BILLS` slot as a ledger (issued + settled tracking / received);
20
- * gross stays sales-only and report views are derived by the frontend
21
- * formatter. Iteration history (every structural write's full post-write
22
- * snapshot) lives in the shared `materialized_tenant_reports_iterations` collection.
18
+ * NUMBERS ONLY: credit-bill COUNTERS (issued / settled / received) live in
19
+ * each `sale_type_metrics` key's `CREDIT_BILLS` slot — constant-size numbers.
20
+ * The ITEMIZED ledger (one row per bill + its receipt events) lives in the
21
+ * SHARED `materialized_tenant_credit_bills` collection, so these documents carry no
22
+ * bill rows/ids and their size no longer grows with the ledger over time.
23
+ * Iteration history (every structural write's full post-write snapshot)
24
+ * lives in the shared `materialized_tenant_reports_iterations` collection.
23
25
  */
24
26
  /**
25
27
  * Version of the key grammar + metric rules of this collection. Bump when
26
28
  * `sale_type_key_filters`, their order, or metric semantics change —
27
29
  * historical documents must then be re-materialized (readers may branch on
28
- * this value during a rollout).
30
+ * this value during a rollout). PRE-RELEASE: the collection has no live
31
+ * tenants/consumers yet, so every change so far folds into version `1`.
29
32
  */
30
33
  exports.MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_SCHEMA_VERSION = 1;
31
34
  const ReportDiscountByTypeSchema = new mongoose_1.Schema({
@@ -129,77 +132,9 @@ const ReportSaleTypeMetricSchema = new mongoose_1.Schema({
129
132
  default: [],
130
133
  },
131
134
  }, { _id: false, minimize: false });
132
- const ReportCreditBillSchema = new mongoose_1.Schema({
133
- order_id: {
134
- type: String,
135
- required: true,
136
- },
137
- payment_id: {
138
- type: String,
139
- required: true,
140
- },
141
- amount: {
142
- type: Number, // cents — the bill's amount at issue
143
- required: true,
144
- },
145
- // Cumulative amount received against this bill so far (0 while unpaid;
146
- // less than `amount` while partially paid). Replaces the old `is_settled`
147
- // flag: the bill is settled when `received_amount >= amount` (`settled_at`
148
- // is stamped by the collection patch). Never an event delta, so patches
149
- // stay idempotent.
150
- received_amount: {
151
- type: Number,
152
- required: true,
153
- default: 0,
154
- },
155
- credit_note: {
156
- type: String, // optional note/reference recorded with the collection
157
- default: null,
158
- },
159
- issued_at: {
160
- type: mongoose_1.Schema.Types.Date,
161
- required: true,
162
- },
163
- // Stamped when the bill is fully collected (received_amount >= amount).
164
- settled_at: {
165
- type: mongoose_1.Schema.Types.Date,
166
- default: null,
167
- },
168
- }, { _id: false, minimize: false });
169
- const ReportReceivedCreditBillSchema = new mongoose_1.Schema({
170
- order_id: {
171
- type: String,
172
- required: true,
173
- },
174
- payment_id: {
175
- type: String,
176
- required: true,
177
- },
178
- amount: {
179
- type: Number, // cents — the bill's amount at issue
180
- required: true,
181
- },
182
- // Cumulative amount received for this bill as of the collection compile
183
- // (≤ `amount` while partially paid; reaches `amount` when fully collected).
184
- received_amount: {
185
- type: Number,
186
- required: true,
187
- },
188
- credit_note: {
189
- type: String, // optional note/reference recorded with the collection
190
- default: null,
191
- },
192
- issued_local_date: {
193
- type: String, // 'YYYY-MM-DD' — the sale's day (bill issue day)
194
- required: true,
195
- },
196
- // Collection timestamp (`order_settled_at`) when known — stamped onto the
197
- // issue-day bill's `settled_at` by the collection patch.
198
- settled_at: {
199
- type: mongoose_1.Schema.Types.Date,
200
- default: null,
201
- },
202
- }, { _id: false, minimize: false });
135
+ // Credit-bill COUNTERS live here (numbers only — the itemized ledger lives in
136
+ // the shared `materialized_tenant_credit_bills` collection; these documents never
137
+ // carry bill rows/ids, so their size is stable over time).
203
138
  const ReportCreditBillsSchema = new mongoose_1.Schema({
204
139
  issued: {
205
140
  count: {
@@ -213,8 +148,9 @@ const ReportCreditBillsSchema = new mongoose_1.Schema({
213
148
  required: true,
214
149
  default: 0,
215
150
  },
216
- // How much of the issued bills has been collected since — patched on
217
- // settlement (tracking only; the money is counted on the collection day).
151
+ // How many / how much (Σ amount) of the issued bills have been FULLY
152
+ // collected — patched when a collection covers the bill (partial
153
+ // receipts never count here).
218
154
  settled_count: {
219
155
  type: Number,
220
156
  required: true,
@@ -226,10 +162,6 @@ const ReportCreditBillsSchema = new mongoose_1.Schema({
226
162
  required: true,
227
163
  default: 0,
228
164
  },
229
- bills: {
230
- type: [ReportCreditBillSchema],
231
- default: [],
232
- },
233
165
  },
234
166
  received: {
235
167
  count: {
@@ -243,15 +175,8 @@ const ReportCreditBillsSchema = new mongoose_1.Schema({
243
175
  required: true,
244
176
  default: 0,
245
177
  },
246
- bills: {
247
- type: [ReportReceivedCreditBillSchema],
248
- default: [],
249
- },
250
178
  },
251
179
  }, { _id: false, minimize: false });
252
- // Credit bills carry the PAY_LATER ledger (issued + settled tracking /
253
- // received) — report views (including the Credit Bills sale-type numbers) are
254
- // derived by the frontend formatter, not stored separately.
255
180
  const ReportKeyMetricsSchema = new mongoose_1.Schema({
256
181
  [constants_1.REPORT_SALE_TYPE_ENUM.TOTAL_SALES]: {
257
182
  type: ReportSaleTypeMetricSchema,
@@ -265,8 +190,8 @@ const ReportKeyMetricsSchema = new mongoose_1.Schema({
265
190
  type: ReportCreditBillsSchema,
266
191
  required: true,
267
192
  default: () => ({
268
- issued: { count: 0, amount: 0, settled_count: 0, settled_amount: 0, bills: [] },
269
- received: { count: 0, amount: 0, bills: [] },
193
+ issued: { count: 0, amount: 0, settled_count: 0, settled_amount: 0 },
194
+ received: { count: 0, amount: 0 },
270
195
  }),
271
196
  },
272
197
  }, { _id: false, minimize: false });
@@ -320,11 +245,12 @@ exports.MaterializedTenantSalesOverviewReportSchema = new mongoose_1.Schema({
320
245
  default: {},
321
246
  },
322
247
  // Versioned writes: bumped by `updateMaterializedTenantSalesOverviewReport`
323
- // on metric changes (replacement / period deltas) AND on received-payment
324
- // patches that change the ledger; 1 = first materialization. Every bump is
325
- // recorded in the shared `materialized_tenant_reports_iterations` history
326
- // (full post-write snapshot + reason) — this document carries no embedded
327
- // snapshot.
248
+ // on metric changes (replacement / period deltas) AND on credit-bill
249
+ // collection patches that change the counters (the itemized ledger lives
250
+ // in `materialized_tenant_credit_bills` and is never embedded here); 1 = first
251
+ // materialization. Every bump is recorded in the shared
252
+ // `materialized_tenant_reports_iterations` history (full post-write
253
+ // snapshot + reason) — this document carries no embedded snapshot.
328
254
  iteration: {
329
255
  type: Number,
330
256
  required: true,
@@ -394,3 +320,19 @@ exports.MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_COLLECTION_INDEXES = {
394
320
  day_index: 1,
395
321
  },
396
322
  };
323
+ /**
324
+ * Index OPTIONS the materializer must CREATE — the identity index is a UNIQUE
325
+ * business invariant (one document per tenant × scope context × scope value;
326
+ * the close-day writes upsert against it and silently degrade without it),
327
+ * so it must be created with `unique: true`. The key patterns above are what
328
+ * the read `.hint()` consumes; these options are what creation must apply.
329
+ * The materializer boot should assert them (`listIndexes`, fail closed — the
330
+ * read hint already fails closed without the index itself).
331
+ */
332
+ exports.MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_INDEX_OPTIONS = [
333
+ {
334
+ key: { tenant_id: 1, scope_context: 1, scope_field: 1, day_index: 1 },
335
+ name: 'tenant_id__scope_context__scope_field__day_index',
336
+ unique: true,
337
+ },
338
+ ];
@@ -31,6 +31,7 @@ export * from './inventory_transactions';
31
31
  export * from './item_transactions';
32
32
  export * from './items';
33
33
  export * from './marketing_fingerprints';
34
+ export * from './materialized_credit_bills';
34
35
  export * from './materialized_tenant_reports_iterations';
35
36
  export * from './materialized_tenant_sales_overview_reports';
36
37
  export * from './menus';
@@ -47,6 +47,7 @@ __exportStar(require("./inventory_transactions"), exports);
47
47
  __exportStar(require("./item_transactions"), exports);
48
48
  __exportStar(require("./items"), exports);
49
49
  __exportStar(require("./marketing_fingerprints"), exports);
50
+ __exportStar(require("./materialized_credit_bills"), exports);
50
51
  __exportStar(require("./materialized_tenant_reports_iterations"), exports);
51
52
  __exportStar(require("./materialized_tenant_sales_overview_reports"), exports);
52
53
  __exportStar(require("./menus"), exports);
@@ -0,0 +1,139 @@
1
+ import { DAY_INDEX_ENUM } from '../../constants/ENUMS';
2
+ import { MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM, MATERIALIZED_REPORT_KEY_FILTER_ENUM, MATERIALIZED_REPORT_SCOPE_ENUM } from '../../constants/MATERIALIZED_REPORTS';
3
+ /**
4
+ * Document types for `materialized_tenant_credit_bills` — the SHARED
5
+ * credit-bill ledger of the materialized reports (see `MATERIALIZED_REPORTS.md`).
6
+ *
7
+ * ONE document per (tenant, scope context, scope value) — the same
8
+ * materialization convention as every other report collection, but the scope
9
+ * set is CAPPED AT `LOCAL_MONTH` (`MATERIALIZED_CREDIT_BILLS_SCOPES`): a
10
+ * month bounds how many bills a document accumulates, so no document can
11
+ * grow unboundedly over time. Whole-year / multi-year reads simply cover
12
+ * their range with the month documents (plus date/hour documents at range
13
+ * edges and for hour-precise windows).
14
+ *
15
+ * Every document carries a per-key map `credit_bills`:
16
+ * `{ [sale_type_key]: { issued: [...], received: [...] } }` — the key
17
+ * grammar is the same `ORDER_STATUS:PLATFORM` grammar as the report
18
+ * documents, so platform / status filters apply to credit numbers and
19
+ * drill-downs alike. Entries keep the identity IDS (`order_id`,
20
+ * `payment_id`) and are slim by design: the order document remains the
21
+ * single source of the sale, this collection only materializes the CREDIT
22
+ * timeline + an indexed, paginated identity list.
23
+ *
24
+ * - `issued[]` = bills ISSUED in the document's scope (one entry per bill):
25
+ * amount + issue anchors + the stateful receipt anchors (`received_at_issue`
26
+ * carried forward; `received_amount` cumulative NOW; `settled_at` /
27
+ * `settled_local_date` filled when the bill settles). Settlement closes
28
+ * PATCH these entries on the issue-scope documents (bounded fan-out).
29
+ * - `received[]` = receipt events COLLECTED in the document's scope (one entry
30
+ * per `(bill, event day)`): `received_delta` is the money collected BY that
31
+ * event (incremental, never a running total) plus the cumulative
32
+ * `received_amount` and the display anchors (`issued_local_date`,
33
+ * `received_at` for ordering, note).
34
+ * - Hour labels exist on entries so hour-precise selections (time windows)
35
+ * can match like the report documents' `localHour` scopes do (null =
36
+ * unresolvable).
37
+ *
38
+ * Amounts are CENTS. Reads pin `schema_version`. The iteration history of
39
+ * these documents lives in the shared `materialized_tenant_reports_iterations`
40
+ * collection like every other materialized report.
41
+ */
42
+ /** One receipt event of a credit bill (money collected on one business day). */
43
+ export interface IMaterializedCreditBillEvent {
44
+ /** `'YYYY-MM-DD'` tenant-local day the money was collected on. */
45
+ event_local_date: string;
46
+ /** `'YYYY-MM-DD HH'` tenant-local hour of the collection (null when unknown). */
47
+ event_local_hour: string | null;
48
+ /** Cents collected BY this event — incremental, never cumulative. */
49
+ received_delta: number;
50
+ /** Reserved ledger kind — `RECEIPT` today (`REFUND` / `WRITE_OFF` would be signed). */
51
+ event_type: MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM;
52
+ credit_note?: string | null;
53
+ /** Collection timestamp (`order_settled_at`) when known. */
54
+ settled_at?: Date | null;
55
+ }
56
+ /** ISSUE entry — one issued bill, slim (ids + credit facts, no order body). */
57
+ export interface IMaterializedCreditBillIssuedEntry {
58
+ order_id: string;
59
+ payment_id: string;
60
+ /** Cents — the bill's amount at issue. */
61
+ amount: number;
62
+ /** Punch time (`order.createdAt`) — never `order_settled_at`. */
63
+ issued_at: Date;
64
+ /** `'YYYY-MM-DD HH'` punch hour (null when unresolvable). */
65
+ issued_local_hour: string | null;
66
+ /** Cents received BEFORE the issue day closed (prepaid + same-day settled). */
67
+ received_at_issue: number;
68
+ /** Cumulative received so far (NOW state) — patched by collection closes. */
69
+ received_amount: number;
70
+ settled_at: Date | null;
71
+ /** `'YYYY-MM-DD'` of the settling receipt event. */
72
+ settled_local_date: string | null;
73
+ credit_note?: string | null;
74
+ }
75
+ /** RECEIPT entry — one collection event of a bill, keyed by its event day. */
76
+ export interface IMaterializedCreditBillReceivedEntry {
77
+ order_id: string;
78
+ payment_id: string;
79
+ /** `'YYYY-MM-DD'` tenant-local day the money was collected on — entry identity. */
80
+ event_local_date: string;
81
+ /** Cents — the bill's amount at issue (context for the receipt). */
82
+ amount: number;
83
+ /** Cumulative received right AFTER this event — idempotence anchor. */
84
+ received_amount: number;
85
+ /** Cents collected BY this event — incremental, never cumulative. */
86
+ received_delta: number;
87
+ /** Collection timestamp (`order_settled_at`) when known — drill-down ordering. */
88
+ received_at: Date | null;
89
+ /** `'YYYY-MM-DD HH'` settlement hour (null when unknown). */
90
+ event_local_hour: string | null;
91
+ credit_note?: string | null;
92
+ /** `'YYYY-MM-DD'` the bill was issued on — display anchor. */
93
+ issued_local_date: string;
94
+ }
95
+ /** Per-key credit section of one document (arrays may be empty, never absent-on-zero). */
96
+ export interface IMaterializedCreditBillKeySection {
97
+ issued: IMaterializedCreditBillIssuedEntry[];
98
+ received: IMaterializedCreditBillReceivedEntry[];
99
+ }
100
+ /**
101
+ * One `materialized_tenant_credit_bills` document — tenant × scope context ×
102
+ * scope value. `scope_context` is always one of the month-capped credit scopes
103
+ * (`MATERIALIZED_CREDIT_BILLS_SCOPES`).
104
+ */
105
+ export interface IMaterializedTenantCreditBillsReport {
106
+ _id: string;
107
+ tenant_id: string;
108
+ /** Required for brand-level reads (sum across the brand's tenants). */
109
+ brand_id: string;
110
+ scope_context: MATERIALIZED_REPORT_SCOPE_ENUM;
111
+ /** Format depends on `scope_context` (see `MATERIALIZED_REPORT_SCOPE_ENUM`). */
112
+ scope_field: string;
113
+ /** Denormalized weekday — set ONLY on `LOCAL_HOUR` / `LOCAL_DATE` documents. */
114
+ day_index?: DAY_INDEX_ENUM | null;
115
+ /**
116
+ * Ordered filter dimensions encoded into `credit_bills` keys; the order
117
+ * defines the key grammar (`"COMPLETED:POS_WALK-IN"`).
118
+ */
119
+ sale_type_key_filters: MATERIALIZED_REPORT_KEY_FILTER_ENUM[];
120
+ /**
121
+ * One section per observed filter-combination key. Keys with no entries in
122
+ * the document's scope are absent (pruned); an empty map is never written.
123
+ */
124
+ credit_bills: Record<string, IMaterializedCreditBillKeySection> | null;
125
+ /**
126
+ * Versioned writes applied to this document (replacement / deltas /
127
+ * settlement patches; 1 = first materialization). Every bump is recorded in
128
+ * the shared `materialized_tenant_reports_iterations` history.
129
+ */
130
+ iteration?: number;
131
+ /** Bump on entry-rule changes; readers pin it. PRE-RELEASE folds into `1`. */
132
+ schema_version: number;
133
+ /** Max source `orders.updatedAt` folded into this document. */
134
+ source_watermark: Date;
135
+ /** When the materializer last rebuilt this document. */
136
+ computed_at: Date;
137
+ createdAt: Date;
138
+ updatedAt: Date;
139
+ }
@@ -0,0 +1,2 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
@@ -19,14 +19,13 @@ import { MATERIALIZED_REPORT_KEY_FILTER_ENUM, MATERIALIZED_REPORT_SCOPE_ENUM } f
19
19
  * - `payment_type` is an open string — live stores contain values outside
20
20
  * `PAYMENT_TYPE_ENUM` (`CARD_PAYMENT`, `FOODPANDA`, …) and they must pass
21
21
  * through untouched;
22
- * - the `CREDIT_BILLS` slot of each `sale_type_metrics` key carries the
23
- * PAY_LATER ledger (issued + settled tracking / received) so platform and
24
- * status filters apply to credit bills too; report views (the Credit Bills
25
- * sale-type numbers and the credit-settlement payments line) are derived by
26
- * the frontend formatter (see `MATERIALIZED_REPORTS.md`);
27
- * - every structural write's full post-write snapshot is recorded in the
28
- * shared `materialized_tenant_reports_iterations` history — this document carries no
29
- * embedded iteration snapshot.
22
+ * NUMBERS ONLY: credit-bill COUNTERS (issued / settled / received) live in
23
+ * each `sale_type_metrics` key's `CREDIT_BILLS` slot — constant-size numbers.
24
+ * The ITEMIZED ledger (one row per bill + its receipt events) lives in the
25
+ * SHARED `materialized_tenant_credit_bills` collection, so these documents carry no
26
+ * bill rows/ids and their size no longer grows with the ledger over time.
27
+ * Iteration history (every structural write's full post-write snapshot)
28
+ * lives in the shared `materialized_tenant_reports_iterations` collection.
30
29
  */
31
30
  /** Order-level discount sums per source (`order_discount_details`), cents. */
32
31
  export interface IMaterializedReportDiscountByType {
@@ -93,79 +92,38 @@ export interface IMaterializedReportSaleTypeMetric {
93
92
  payments: IMaterializedReportPaymentMetric[];
94
93
  }
95
94
  /**
96
- * One credit bill (`PAY_LATER`) tracked by a `sale_type_metrics` key. Issued
97
- * when a day closes with an unpaid order marked as a credit bill;
98
- * `received_amount` / `settled_at` are patched when the bill is collected on
99
- * a later day.
100
- */
101
- export interface IMaterializedReportCreditBill {
102
- order_id: string;
103
- payment_id: string;
104
- /** Cents — the bill's amount at issue. */
105
- amount: number;
106
- /**
107
- * Cumulative amount received against the bill so far (0 while unpaid, less
108
- * than `amount` while partially paid). Replaces the old `is_settled` flag:
109
- * the bill is SETTLED when `received_amount >= amount` (`settled_at` is
110
- * stamped). Never an event delta — collection patches write absolute
111
- * values, so replays are idempotent.
112
- */
113
- received_amount: number;
114
- credit_note?: string;
115
- /**
116
- * When the bill was issued — the order's punch time (`createdAt`), never
117
- * `order_settled_at` (for deferred bills that is the collection moment).
118
- */
119
- issued_at: Date;
120
- settled_at: Date | null;
121
- }
122
- /** A previously-issued credit bill collected within this scope's slice. */
123
- export interface IMaterializedReportReceivedCreditBill {
124
- order_id: string;
125
- payment_id: string;
126
- /** Cents — the collected amount. */
127
- amount: number;
128
- /** Cumulative amount received as of the collection compile (reaches `amount` when fully collected). */
129
- received_amount: number;
130
- credit_note?: string;
131
- /** `YYYY-MM-DD` local day the bill was issued on (the sale's day). */
132
- issued_local_date: string;
133
- /**
134
- * Collection timestamp (`order_settled_at`) when known — stamped onto the
135
- * issue-day bill's `settled_at` by the collection patch (falls back to the
136
- * close's `computedAt`).
137
- */
138
- settled_at?: Date | null;
139
- }
140
- /**
141
- * Credit-bill (`PAY_LATER`) ledger of one `sale_type_metrics` key (see
142
- * `MATERIALIZED_REPORTS.md`):
143
- * - `issued` — bills created for this filter combination (tracking; NOT
144
- * money-in), including `settled_count` / `settled_amount` — how much of
145
- * them has been collected since (patched on settlement; analysis only);
146
- * - `received` — previous days' bills of this combination collected in this
147
- * scope (tracking; the frontend formatter derives the credit-settlement
148
- * payments line from it).
95
+ * Credit-bill counters of one `sale_type_metrics` key — NUMBERS ONLY (the
96
+ * itemized ledger lives in the shared `materialized_tenant_credit_bills` collection;
97
+ * these documents never carry bill rows/ids, so the slot is constant-size):
98
+ * - `issued` — bills created for this filter combination in this scope
99
+ * (tracking; NOT money-in); `settled_count` / `settled_amount` track how
100
+ * many / how much (Σ `amount`) have been FULLY collected — patched when a
101
+ * collection covers the bill (partial receipts never count here). These are
102
+ * EVER-SETTLED (NOW state) counters: a bill settled on any later day counts
103
+ * here. The range-pure as-of-end answer (`settled_local_date` ≤ the
104
+ * selection end) is computed from the credit documents by
105
+ * `computeMaterializedCreditBillTotalsFromReports` — the two legitimately
106
+ * differ for historical ranges (audit R5-4) and must not be rendered
107
+ * side-by-side without labeling;
108
+ * - `received` — receipt EVENTS collected in this scope: `count` = the events
109
+ * themselves (a bill collected in two installments counts twice — audit
110
+ * R5-2), `amount` = money received (Σ `received_delta`).
149
111
  *
150
112
  * Amounts are cents. The ledger never feeds gross — gross stays sales-only so
151
- * cross-day gross sums stay equal to total sales.
113
+ * cross-day gross sums stay equal to total sales. Range-pure extras
114
+ * (`outstanding*`, `collected_at_issue_*`) are READ-derived (the aggregation
115
+ * reads the shared ledger rows); they are not stored here.
152
116
  */
153
117
  export interface IMaterializedReportCreditBills {
154
118
  issued: {
155
119
  count: number;
156
120
  amount: number;
157
- /**
158
- * Of the issued bills: how many / how much (cents) have been collected
159
- * since — patched when the collection event is detected.
160
- */
161
121
  settled_count: number;
162
122
  settled_amount: number;
163
- bills: IMaterializedReportCreditBill[];
164
123
  };
165
124
  received: {
166
125
  count: number;
167
126
  amount: number;
168
- bills: IMaterializedReportReceivedCreditBill[];
169
127
  };
170
128
  }
171
129
  /**
@@ -177,11 +135,7 @@ export interface IMaterializedReportKeyMetrics {
177
135
  [REPORT_SALE_TYPE_ENUM.TOTAL_SALES]: IMaterializedReportSaleTypeMetric;
178
136
  /** Orders with `amount_collected > 0`. */
179
137
  [REPORT_SALE_TYPE_ENUM.AMOUNT_COLLECTED]: IMaterializedReportSaleTypeMetric;
180
- /**
181
- * Credit-bill (`PAY_LATER`) ledger of this filter combination — the Credit
182
- * Bills sale-type numbers are derived from it by the frontend formatter
183
- * (not stored separately).
184
- */
138
+ /** Credit-bill counters (numbers only — see `IMaterializedReportCreditBills`). */
185
139
  [REPORT_SALE_TYPE_ENUM.CREDIT_BILLS]: IMaterializedReportCreditBills;
186
140
  }
187
141
  export interface IMaterializedTenantSalesOverviewReport {
@@ -222,10 +176,11 @@ export interface IMaterializedTenantSalesOverviewReport {
222
176
  sale_type_metrics: Record<string, IMaterializedReportKeyMetrics> | null;
223
177
  /**
224
178
  * Versioned writes applied to this document (replacement / deltas; 1 = first
225
- * materialization). Received-payment patches that change the ledger bump it
226
- * too (no-op patches don't). Every bump is recorded as a row in the shared
227
- * `materialized_tenant_reports_iterations` history (full post-write snapshot;
228
- * see `MATERIALIZED_REPORTS.md`).
179
+ * materialization). Credit-bill collection closes that settle a bill patch
180
+ * this document's CREDIT_BILLS COUNTERS (the itemized ledger lives in
181
+ * `materialized_tenant_credit_bills` and is never embedded here). Every bump is
182
+ * recorded as a row in the shared `materialized_tenant_reports_iterations`
183
+ * history (full post-write snapshot; see `MATERIALIZED_REPORTS.md`).
229
184
  */
230
185
  iteration?: number;
231
186
  /** Bump on key-grammar / metric-rule changes; requires re-materialization. */