@managesome/eposmatic-toolkit 0.3.11 → 0.4.1
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.
- package/esm/constants/MATERIALIZED_REPORTS.js +105 -0
- package/esm/constants/index.js +1 -0
- package/esm/helpers/index.js +1 -0
- package/esm/helpers/materialized-reports/index.js +5 -0
- package/esm/helpers/materialized-reports/key-helpers.js +59 -0
- package/esm/helpers/materialized-reports/materialized-tenant-reports-iterations-helpers.js +60 -0
- package/esm/helpers/materialized-reports/scope-helpers.js +107 -0
- package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +251 -0
- package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +860 -0
- package/esm/schemas/models/index.js +2 -0
- package/esm/schemas/models/materialized_tenant_reports_iterations.js +82 -0
- package/esm/schemas/models/materialized_tenant_sales_overview_reports.js +399 -0
- package/esm/schemas/types/index.js +2 -0
- package/esm/schemas/types/materialized_tenant_reports_iterations.js +1 -0
- package/esm/schemas/types/materialized_tenant_sales_overview_reports.js +1 -0
- package/lib/constants/MATERIALIZED_REPORTS.d.ts +96 -0
- package/lib/constants/MATERIALIZED_REPORTS.js +108 -0
- package/lib/constants/index.d.ts +1 -0
- package/lib/constants/index.js +1 -0
- package/lib/helpers/index.d.ts +1 -0
- package/lib/helpers/index.js +1 -0
- package/lib/helpers/materialized-reports/index.d.ts +5 -0
- package/lib/helpers/materialized-reports/index.js +21 -0
- package/lib/helpers/materialized-reports/key-helpers.d.ts +35 -0
- package/lib/helpers/materialized-reports/key-helpers.js +64 -0
- package/lib/helpers/materialized-reports/materialized-tenant-reports-iterations-helpers.d.ts +66 -0
- package/lib/helpers/materialized-reports/materialized-tenant-reports-iterations-helpers.js +63 -0
- package/lib/helpers/materialized-reports/scope-helpers.d.ts +57 -0
- package/lib/helpers/materialized-reports/scope-helpers.js +114 -0
- package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +125 -0
- package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +256 -0
- package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.d.ts +223 -0
- package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +875 -0
- package/lib/schemas/models/index.d.ts +2 -0
- package/lib/schemas/models/index.js +2 -0
- package/lib/schemas/models/materialized_tenant_reports_iterations.d.ts +80 -0
- package/lib/schemas/models/materialized_tenant_reports_iterations.js +85 -0
- package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +569 -0
- package/lib/schemas/models/materialized_tenant_sales_overview_reports.js +402 -0
- package/lib/schemas/models/orders.d.ts +24 -24
- package/lib/schemas/models/tenant_active_jobs.d.ts +3 -3
- package/lib/schemas/models/tenant_calendar.d.ts +3 -3
- package/lib/schemas/models/tenant_cash_drawer_sessions.d.ts +24 -24
- package/lib/schemas/models/tenant_cash_in_out.d.ts +24 -24
- package/lib/schemas/models/tenant_day_sessions.d.ts +24 -24
- package/lib/schemas/models/tenant_instore_shift_sessions.d.ts +24 -24
- package/lib/schemas/types/index.d.ts +2 -0
- package/lib/schemas/types/index.js +2 -0
- package/lib/schemas/types/materialized_tenant_reports_iterations.d.ts +62 -0
- package/lib/schemas/types/materialized_tenant_reports_iterations.js +2 -0
- package/lib/schemas/types/materialized_tenant_sales_overview_reports.d.ts +242 -0
- package/lib/schemas/types/materialized_tenant_sales_overview_reports.js +3 -0
- package/lib/tests/materialized-reports/fixtures.d.ts +81 -0
- package/lib/tests/materialized-reports/fixtures.js +87 -0
- package/lib/tests/materialized-reports/fixtures.test.d.ts +1 -0
- package/lib/tests/materialized-reports/fixtures.test.js +123 -0
- package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-helpers.test.d.ts +1 -0
- package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-helpers.test.js +75 -0
- package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-schema.test.d.ts +1 -0
- package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-schema.test.js +73 -0
- package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.d.ts +1 -0
- package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.js +207 -0
- package/lib/tests/materialized-reports/sales-overview-baseline.test.d.ts +1 -0
- package/lib/tests/materialized-reports/sales-overview-baseline.test.js +326 -0
- package/lib/tests/materialized-reports/sales-overview-reference.d.ts +63 -0
- package/lib/tests/materialized-reports/sales-overview-reference.js +131 -0
- package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.d.ts +1 -0
- package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +335 -0
- package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.d.ts +1 -0
- package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +885 -0
- package/package.json +5 -2
|
@@ -27,6 +27,8 @@ export * from './inventory_transactions';
|
|
|
27
27
|
export * from './item_transactions';
|
|
28
28
|
export * from './items';
|
|
29
29
|
export * from './marketing_fingerprints';
|
|
30
|
+
export * from './materialized_tenant_reports_iterations';
|
|
31
|
+
export * from './materialized_tenant_sales_overview_reports';
|
|
30
32
|
export * from './menus';
|
|
31
33
|
export * from './messaging_devices';
|
|
32
34
|
export * from './modifier_extras';
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import { Schema } from 'mongoose';
|
|
2
|
+
import { ALL_MATERIALIZED_REPORT_TYPES } from '../../constants/MATERIALIZED_REPORTS';
|
|
3
|
+
/**
|
|
4
|
+
* Mongoose schema for `materialized_tenant_reports_iterations` — the shared iteration
|
|
5
|
+
* history of every materialized report collection (see
|
|
6
|
+
* `MATERIALIZED_REPORTS.md`, "Iteration history").
|
|
7
|
+
*
|
|
8
|
+
* One append-only row per VERSIONED write of a report document; `snapshot`
|
|
9
|
+
* holds the full report document AFTER the write. `snapshot` is Mixed because
|
|
10
|
+
* the collection serves every report kind (`report_type` discriminates).
|
|
11
|
+
* Received-payment patches that change the ledger are versioned writes too
|
|
12
|
+
* (they bump `iteration` and append rows); no-op patches write nothing.
|
|
13
|
+
* Every row carries the backend-generated `reason` for the audit trail.
|
|
14
|
+
*/
|
|
15
|
+
export const MaterializedTenantReportIterationSchema = new Schema({
|
|
16
|
+
_id: {
|
|
17
|
+
type: Schema.Types.ObjectId,
|
|
18
|
+
required: true,
|
|
19
|
+
immutable: true,
|
|
20
|
+
},
|
|
21
|
+
report_type: {
|
|
22
|
+
type: String,
|
|
23
|
+
enum: ALL_MATERIALIZED_REPORT_TYPES,
|
|
24
|
+
required: true,
|
|
25
|
+
immutable: true,
|
|
26
|
+
},
|
|
27
|
+
report_id: {
|
|
28
|
+
type: Schema.Types.ObjectId,
|
|
29
|
+
required: true,
|
|
30
|
+
immutable: true,
|
|
31
|
+
},
|
|
32
|
+
iteration: {
|
|
33
|
+
type: Number,
|
|
34
|
+
required: true,
|
|
35
|
+
min: 1,
|
|
36
|
+
},
|
|
37
|
+
schema_version: {
|
|
38
|
+
type: Number,
|
|
39
|
+
required: true,
|
|
40
|
+
},
|
|
41
|
+
// Why the iteration happened — backend-generated free string, e.g.
|
|
42
|
+
// 'NEW_DAY' | 'RECLOSE' | 'RECONCILE' | 'CREDIT_BILL_COLLECTED'.
|
|
43
|
+
reason: {
|
|
44
|
+
type: String,
|
|
45
|
+
required: true,
|
|
46
|
+
},
|
|
47
|
+
// Full report document as written — polymorphic across report kinds, so
|
|
48
|
+
// untyped/Mixed; narrow by `report_type` (see the type file).
|
|
49
|
+
snapshot: {
|
|
50
|
+
type: Schema.Types.Mixed,
|
|
51
|
+
required: true,
|
|
52
|
+
},
|
|
53
|
+
createdAt: {
|
|
54
|
+
type: Schema.Types.Date,
|
|
55
|
+
required: true,
|
|
56
|
+
default: () => new Date(),
|
|
57
|
+
immutable: true,
|
|
58
|
+
},
|
|
59
|
+
updatedAt: {
|
|
60
|
+
type: Schema.Types.Date,
|
|
61
|
+
required: true,
|
|
62
|
+
default: () => new Date(),
|
|
63
|
+
},
|
|
64
|
+
}, {
|
|
65
|
+
timestamps: true,
|
|
66
|
+
versionKey: false,
|
|
67
|
+
minimize: false,
|
|
68
|
+
});
|
|
69
|
+
export const MATERIALIZED_TENANT_REPORTS_ITERATIONS_COLLECTION_NAME = 'materialized_tenant_reports_iterations';
|
|
70
|
+
/**
|
|
71
|
+
* Indexes for `materialized_tenant_reports_iterations` (values are Mongo key patterns that
|
|
72
|
+
* can be passed straight to `.hint()`):
|
|
73
|
+
* - `_id`: unique primary key.
|
|
74
|
+
* - `report_id__iteration`: UNIQUE — one row per (report, iteration); serves
|
|
75
|
+
* per-report history reads (`{ report_id }` + `.sort({ iteration: -1 })`;
|
|
76
|
+
* the head row mirrors the live document) and doubles as the idempotent
|
|
77
|
+
* upsert key (`replaceOne({ report_id, iteration }, row, { upsert: true })`).
|
|
78
|
+
*/
|
|
79
|
+
export const MATERIALIZED_TENANT_REPORTS_ITERATIONS_COLLECTION_INDEXES = {
|
|
80
|
+
_id: { _id: 1 }, // Unique Index
|
|
81
|
+
report_id__iteration: { report_id: 1, iteration: -1 }, // unique — one row per (report, iteration)
|
|
82
|
+
};
|
|
@@ -0,0 +1,399 @@
|
|
|
1
|
+
import { Schema } from 'mongoose';
|
|
2
|
+
import { REPORT_SALE_TYPE_ENUM } from '../../constants';
|
|
3
|
+
import { ALL_DAY_INDEX } from '../../constants/ENUMS';
|
|
4
|
+
import { ALL_MATERIALIZED_REPORT_KEY_FILTERS, ALL_MATERIALIZED_REPORT_SCOPES, SALES_OVERVIEW_KEY_FILTERS, } from '../../constants/MATERIALIZED_REPORTS';
|
|
5
|
+
/**
|
|
6
|
+
* Mongoose schema for `materialized_tenant_sales_overview_reports` — the
|
|
7
|
+
* materialized Reports > Overview data (one document per tenant × scope
|
|
8
|
+
* context × scope value), maintained by the day-end materialization job and
|
|
9
|
+
* read by the analytics API. Scope slices are stamped from the order's
|
|
10
|
+
* business day (`order.localDate`); hour buckets use the punch hour for sales
|
|
11
|
+
* and the settlement hour for credit-bill collections (see
|
|
12
|
+
* `MATERIALIZED_REPORTS.md`). The report's time-bias toggle (Punched At /
|
|
13
|
+
* `createdAt`) is out of scope. `scope_field` formats are documented on
|
|
14
|
+
* `MATERIALIZED_REPORT_SCOPE_ENUM` and in `MATERIALIZED_REPORTS.md`.
|
|
15
|
+
* Credit bills (`PAY_LATER`) live in each `sale_type_metrics` key's
|
|
16
|
+
* `CREDIT_BILLS` slot as a ledger (issued + settled tracking / received);
|
|
17
|
+
* gross stays sales-only and report views are derived by the frontend
|
|
18
|
+
* formatter. Iteration history (every structural write's full post-write
|
|
19
|
+
* snapshot) lives in the shared `materialized_tenant_reports_iterations` collection.
|
|
20
|
+
*/
|
|
21
|
+
/**
|
|
22
|
+
* Version of the key grammar + metric rules of this collection. Bump when
|
|
23
|
+
* `sale_type_key_filters`, their order, or metric semantics change —
|
|
24
|
+
* historical documents must then be re-materialized (readers may branch on
|
|
25
|
+
* this value during a rollout).
|
|
26
|
+
*/
|
|
27
|
+
export const MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_SCHEMA_VERSION = 1;
|
|
28
|
+
const ReportDiscountByTypeSchema = new Schema({
|
|
29
|
+
special_discount: {
|
|
30
|
+
type: Number, // cents — Σ order_discount_details.special_discount
|
|
31
|
+
required: true,
|
|
32
|
+
},
|
|
33
|
+
loyalty_discount: {
|
|
34
|
+
type: Number, // cents — Σ order_discount_details.loyalty_discount
|
|
35
|
+
required: true,
|
|
36
|
+
},
|
|
37
|
+
voucher_discount: {
|
|
38
|
+
type: Number, // cents — Σ order_discount_details.voucher_discount
|
|
39
|
+
required: true,
|
|
40
|
+
},
|
|
41
|
+
}, { _id: false, minimize: false });
|
|
42
|
+
const ReportOrderMetricSchema = new Schema({
|
|
43
|
+
count: {
|
|
44
|
+
type: Number,
|
|
45
|
+
required: true,
|
|
46
|
+
min: 0,
|
|
47
|
+
},
|
|
48
|
+
gross_amount: {
|
|
49
|
+
type: Number, // cents — Σ amount_earned of the bucket's orders
|
|
50
|
+
required: true,
|
|
51
|
+
},
|
|
52
|
+
discount_amount: {
|
|
53
|
+
type: Number, // cents — Σ total_discount_applied
|
|
54
|
+
required: true,
|
|
55
|
+
},
|
|
56
|
+
discount_by_type: {
|
|
57
|
+
type: ReportDiscountByTypeSchema,
|
|
58
|
+
required: true,
|
|
59
|
+
},
|
|
60
|
+
gst_amount: {
|
|
61
|
+
type: Number, // cents — Σ gst_amount
|
|
62
|
+
required: true,
|
|
63
|
+
},
|
|
64
|
+
tax_amount: {
|
|
65
|
+
type: Number, // cents — Σ tax_amount
|
|
66
|
+
required: true,
|
|
67
|
+
},
|
|
68
|
+
tip_amount: {
|
|
69
|
+
type: Number, // cents — Σ tip_amount
|
|
70
|
+
required: true,
|
|
71
|
+
},
|
|
72
|
+
tax_invoice_provider_charges: {
|
|
73
|
+
type: Number, // cents — Σ tax_invoice_provider_charges
|
|
74
|
+
required: true,
|
|
75
|
+
},
|
|
76
|
+
delivery_charges: {
|
|
77
|
+
type: Number, // cents — Σ delivery_details.delivery_cost
|
|
78
|
+
required: true,
|
|
79
|
+
},
|
|
80
|
+
}, { _id: false, minimize: false });
|
|
81
|
+
const ReportPaymentMetricSchema = new Schema({
|
|
82
|
+
payment_type: {
|
|
83
|
+
type: String,
|
|
84
|
+
// enum: ALL_PAYMENT_TYPE_NAMES, — intentionally NOT enforced: live stores
|
|
85
|
+
// contain legacy/aggregator values (CARD_PAYMENT, FOODPANDA, PLAZA, …)
|
|
86
|
+
// that must pass through reporting untouched.
|
|
87
|
+
required: true,
|
|
88
|
+
},
|
|
89
|
+
count: {
|
|
90
|
+
type: Number,
|
|
91
|
+
required: true,
|
|
92
|
+
min: 0,
|
|
93
|
+
},
|
|
94
|
+
gross_amount: {
|
|
95
|
+
type: Number, // cents — net of refunds & card charges; may be negative
|
|
96
|
+
required: true,
|
|
97
|
+
},
|
|
98
|
+
amount_due: {
|
|
99
|
+
type: Number,
|
|
100
|
+
required: true,
|
|
101
|
+
min: 0,
|
|
102
|
+
},
|
|
103
|
+
amount_paid: {
|
|
104
|
+
type: Number,
|
|
105
|
+
required: true,
|
|
106
|
+
min: 0,
|
|
107
|
+
},
|
|
108
|
+
amount_refunded: {
|
|
109
|
+
type: Number,
|
|
110
|
+
required: true,
|
|
111
|
+
min: 0,
|
|
112
|
+
},
|
|
113
|
+
card_charges: {
|
|
114
|
+
type: Number,
|
|
115
|
+
required: true,
|
|
116
|
+
min: 0,
|
|
117
|
+
},
|
|
118
|
+
}, { _id: false, minimize: false });
|
|
119
|
+
const ReportSaleTypeMetricSchema = new Schema({
|
|
120
|
+
orders: {
|
|
121
|
+
type: ReportOrderMetricSchema,
|
|
122
|
+
required: true,
|
|
123
|
+
},
|
|
124
|
+
payments: {
|
|
125
|
+
type: [ReportPaymentMetricSchema],
|
|
126
|
+
default: [],
|
|
127
|
+
},
|
|
128
|
+
}, { _id: false, minimize: false });
|
|
129
|
+
const ReportCreditBillSchema = new Schema({
|
|
130
|
+
order_id: {
|
|
131
|
+
type: String,
|
|
132
|
+
required: true,
|
|
133
|
+
},
|
|
134
|
+
payment_id: {
|
|
135
|
+
type: String,
|
|
136
|
+
required: true,
|
|
137
|
+
},
|
|
138
|
+
amount: {
|
|
139
|
+
type: Number, // cents — the bill's amount at issue
|
|
140
|
+
required: true,
|
|
141
|
+
},
|
|
142
|
+
// Cumulative amount received against this bill so far (0 while unpaid;
|
|
143
|
+
// less than `amount` while partially paid). Replaces the old `is_settled`
|
|
144
|
+
// flag: the bill is settled when `received_amount >= amount` (`settled_at`
|
|
145
|
+
// is stamped by the collection patch). Never an event delta, so patches
|
|
146
|
+
// stay idempotent.
|
|
147
|
+
received_amount: {
|
|
148
|
+
type: Number,
|
|
149
|
+
required: true,
|
|
150
|
+
default: 0,
|
|
151
|
+
},
|
|
152
|
+
credit_note: {
|
|
153
|
+
type: String, // optional note/reference recorded with the collection
|
|
154
|
+
default: null,
|
|
155
|
+
},
|
|
156
|
+
issued_at: {
|
|
157
|
+
type: Schema.Types.Date,
|
|
158
|
+
required: true,
|
|
159
|
+
},
|
|
160
|
+
// Stamped when the bill is fully collected (received_amount >= amount).
|
|
161
|
+
settled_at: {
|
|
162
|
+
type: Schema.Types.Date,
|
|
163
|
+
default: null,
|
|
164
|
+
},
|
|
165
|
+
}, { _id: false, minimize: false });
|
|
166
|
+
const ReportReceivedCreditBillSchema = new Schema({
|
|
167
|
+
order_id: {
|
|
168
|
+
type: String,
|
|
169
|
+
required: true,
|
|
170
|
+
},
|
|
171
|
+
payment_id: {
|
|
172
|
+
type: String,
|
|
173
|
+
required: true,
|
|
174
|
+
},
|
|
175
|
+
amount: {
|
|
176
|
+
type: Number, // cents — the bill's amount at issue
|
|
177
|
+
required: true,
|
|
178
|
+
},
|
|
179
|
+
// Cumulative amount received for this bill as of the collection compile
|
|
180
|
+
// (≤ `amount` while partially paid; reaches `amount` when fully collected).
|
|
181
|
+
received_amount: {
|
|
182
|
+
type: Number,
|
|
183
|
+
required: true,
|
|
184
|
+
},
|
|
185
|
+
credit_note: {
|
|
186
|
+
type: String, // optional note/reference recorded with the collection
|
|
187
|
+
default: null,
|
|
188
|
+
},
|
|
189
|
+
issued_local_date: {
|
|
190
|
+
type: String, // 'YYYY-MM-DD' — the sale's day (bill issue day)
|
|
191
|
+
required: true,
|
|
192
|
+
},
|
|
193
|
+
// Collection timestamp (`order_settled_at`) when known — stamped onto the
|
|
194
|
+
// issue-day bill's `settled_at` by the collection patch.
|
|
195
|
+
settled_at: {
|
|
196
|
+
type: Schema.Types.Date,
|
|
197
|
+
default: null,
|
|
198
|
+
},
|
|
199
|
+
}, { _id: false, minimize: false });
|
|
200
|
+
const ReportCreditBillsSchema = new Schema({
|
|
201
|
+
issued: {
|
|
202
|
+
count: {
|
|
203
|
+
type: Number,
|
|
204
|
+
required: true,
|
|
205
|
+
min: 0,
|
|
206
|
+
default: 0,
|
|
207
|
+
},
|
|
208
|
+
amount: {
|
|
209
|
+
type: Number,
|
|
210
|
+
required: true,
|
|
211
|
+
default: 0,
|
|
212
|
+
},
|
|
213
|
+
// How much of the issued bills has been collected since — patched on
|
|
214
|
+
// settlement (tracking only; the money is counted on the collection day).
|
|
215
|
+
settled_count: {
|
|
216
|
+
type: Number,
|
|
217
|
+
required: true,
|
|
218
|
+
min: 0,
|
|
219
|
+
default: 0,
|
|
220
|
+
},
|
|
221
|
+
settled_amount: {
|
|
222
|
+
type: Number,
|
|
223
|
+
required: true,
|
|
224
|
+
default: 0,
|
|
225
|
+
},
|
|
226
|
+
bills: {
|
|
227
|
+
type: [ReportCreditBillSchema],
|
|
228
|
+
default: [],
|
|
229
|
+
},
|
|
230
|
+
},
|
|
231
|
+
received: {
|
|
232
|
+
count: {
|
|
233
|
+
type: Number,
|
|
234
|
+
required: true,
|
|
235
|
+
min: 0,
|
|
236
|
+
default: 0,
|
|
237
|
+
},
|
|
238
|
+
amount: {
|
|
239
|
+
type: Number,
|
|
240
|
+
required: true,
|
|
241
|
+
default: 0,
|
|
242
|
+
},
|
|
243
|
+
bills: {
|
|
244
|
+
type: [ReportReceivedCreditBillSchema],
|
|
245
|
+
default: [],
|
|
246
|
+
},
|
|
247
|
+
},
|
|
248
|
+
}, { _id: false, minimize: false });
|
|
249
|
+
// Credit bills carry the PAY_LATER ledger (issued + settled tracking /
|
|
250
|
+
// received) — report views (including the Credit Bills sale-type numbers) are
|
|
251
|
+
// derived by the frontend formatter, not stored separately.
|
|
252
|
+
const ReportKeyMetricsSchema = new Schema({
|
|
253
|
+
[REPORT_SALE_TYPE_ENUM.TOTAL_SALES]: {
|
|
254
|
+
type: ReportSaleTypeMetricSchema,
|
|
255
|
+
required: true,
|
|
256
|
+
},
|
|
257
|
+
[REPORT_SALE_TYPE_ENUM.AMOUNT_COLLECTED]: {
|
|
258
|
+
type: ReportSaleTypeMetricSchema,
|
|
259
|
+
required: true,
|
|
260
|
+
},
|
|
261
|
+
[REPORT_SALE_TYPE_ENUM.CREDIT_BILLS]: {
|
|
262
|
+
type: ReportCreditBillsSchema,
|
|
263
|
+
required: true,
|
|
264
|
+
default: () => ({
|
|
265
|
+
issued: { count: 0, amount: 0, settled_count: 0, settled_amount: 0, bills: [] },
|
|
266
|
+
received: { count: 0, amount: 0, bills: [] },
|
|
267
|
+
}),
|
|
268
|
+
},
|
|
269
|
+
}, { _id: false, minimize: false });
|
|
270
|
+
export const MaterializedTenantSalesOverviewReportSchema = new Schema({
|
|
271
|
+
_id: {
|
|
272
|
+
type: Schema.Types.ObjectId,
|
|
273
|
+
required: true,
|
|
274
|
+
immutable: true,
|
|
275
|
+
},
|
|
276
|
+
tenant_id: {
|
|
277
|
+
type: String,
|
|
278
|
+
required: true,
|
|
279
|
+
immutable: true,
|
|
280
|
+
ref: 'tenants',
|
|
281
|
+
},
|
|
282
|
+
brand_id: {
|
|
283
|
+
type: String,
|
|
284
|
+
required: true,
|
|
285
|
+
},
|
|
286
|
+
scope_context: {
|
|
287
|
+
type: String,
|
|
288
|
+
enum: ALL_MATERIALIZED_REPORT_SCOPES,
|
|
289
|
+
required: true,
|
|
290
|
+
},
|
|
291
|
+
scope_field: {
|
|
292
|
+
type: String, // format depends on scope_context — see MATERIALIZED_REPORT_SCOPE_ENUM
|
|
293
|
+
required: true,
|
|
294
|
+
},
|
|
295
|
+
// Denormalized weekday of scope_field — set ONLY on LOCAL_HOUR /
|
|
296
|
+
// LOCAL_DATE documents (MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX);
|
|
297
|
+
// null elsewhere. Weekday analysis reads date/hour slices instead of an
|
|
298
|
+
// all-time accumulator document (see MATERIALIZED_REPORTS.md).
|
|
299
|
+
day_index: {
|
|
300
|
+
type: String,
|
|
301
|
+
enum: ALL_DAY_INDEX,
|
|
302
|
+
default: null,
|
|
303
|
+
},
|
|
304
|
+
sale_type_key_filters: {
|
|
305
|
+
type: [String],
|
|
306
|
+
enum: ALL_MATERIALIZED_REPORT_KEY_FILTERS,
|
|
307
|
+
required: true,
|
|
308
|
+
default: () => [...SALES_OVERVIEW_KEY_FILTERS],
|
|
309
|
+
},
|
|
310
|
+
// Map key = the ordered filter combination, e.g. "PLACED:POS_WALK-IN" —
|
|
311
|
+
// the grammar is declared by `sale_type_key_filters` and must be built /
|
|
312
|
+
// parsed through the shared key helper, never ad hoc.
|
|
313
|
+
sale_type_metrics: {
|
|
314
|
+
type: Map,
|
|
315
|
+
of: ReportKeyMetricsSchema,
|
|
316
|
+
required: true,
|
|
317
|
+
default: {},
|
|
318
|
+
},
|
|
319
|
+
// Versioned writes: bumped by `updateMaterializedTenantSalesOverviewReport`
|
|
320
|
+
// on metric changes (replacement / period deltas) AND on received-payment
|
|
321
|
+
// patches that change the ledger; 1 = first materialization. Every bump is
|
|
322
|
+
// recorded in the shared `materialized_tenant_reports_iterations` history
|
|
323
|
+
// (full post-write snapshot + reason) — this document carries no embedded
|
|
324
|
+
// snapshot.
|
|
325
|
+
iteration: {
|
|
326
|
+
type: Number,
|
|
327
|
+
required: true,
|
|
328
|
+
min: 1,
|
|
329
|
+
default: 1,
|
|
330
|
+
},
|
|
331
|
+
schema_version: {
|
|
332
|
+
type: Number,
|
|
333
|
+
required: true,
|
|
334
|
+
immutable: true,
|
|
335
|
+
default: MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_SCHEMA_VERSION,
|
|
336
|
+
},
|
|
337
|
+
source_watermark: {
|
|
338
|
+
type: Schema.Types.Date,
|
|
339
|
+
required: true,
|
|
340
|
+
},
|
|
341
|
+
computed_at: {
|
|
342
|
+
type: Schema.Types.Date,
|
|
343
|
+
required: true,
|
|
344
|
+
},
|
|
345
|
+
createdAt: {
|
|
346
|
+
type: Schema.Types.Date,
|
|
347
|
+
required: true,
|
|
348
|
+
default: () => new Date(),
|
|
349
|
+
immutable: true,
|
|
350
|
+
},
|
|
351
|
+
updatedAt: {
|
|
352
|
+
type: Schema.Types.Date,
|
|
353
|
+
required: true,
|
|
354
|
+
default: () => new Date(),
|
|
355
|
+
},
|
|
356
|
+
}, {
|
|
357
|
+
timestamps: true,
|
|
358
|
+
versionKey: false,
|
|
359
|
+
minimize: false,
|
|
360
|
+
});
|
|
361
|
+
export const MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_COLLECTION_NAME = 'materialized_tenant_sales_overview_reports';
|
|
362
|
+
/**
|
|
363
|
+
* Describes the indexes for `materialized_tenant_sales_overview_reports`.
|
|
364
|
+
* Values are Mongo key patterns that can be passed straight to `.hint()`.
|
|
365
|
+
* - `_id`: unique primary key.
|
|
366
|
+
* - `tenant_id__scope_context__scope_field`: UNIQUE index — one document per
|
|
367
|
+
* (tenant, scope context, scope value); also serves the standardized query
|
|
368
|
+
* (`tenant_id` + `scope_context` + `scope_field`).
|
|
369
|
+
* - `brand_id__scope_context__scope_field`: brand-level reads across the
|
|
370
|
+
* brand's tenants (sum across their tenant documents).
|
|
371
|
+
* - `tenant_id__scope_context__day_index__scope_field` (+ brand variant):
|
|
372
|
+
* weekday queries over LOCAL_HOUR / LOCAL_DATE slices
|
|
373
|
+
* (`day_index` + `scope_field` range).
|
|
374
|
+
*/
|
|
375
|
+
export const MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_COLLECTION_INDEXES = {
|
|
376
|
+
_id: { _id: 1 }, // Unique Index
|
|
377
|
+
tenant_id__scope_context__scope_field: {
|
|
378
|
+
tenant_id: 1,
|
|
379
|
+
scope_context: 1,
|
|
380
|
+
scope_field: 1,
|
|
381
|
+
}, // unique — one document per (tenant, scope context, scope value)
|
|
382
|
+
brand_id__scope_context__scope_field: {
|
|
383
|
+
brand_id: 1,
|
|
384
|
+
scope_context: 1,
|
|
385
|
+
scope_field: 1,
|
|
386
|
+
}, // brand-level reads across the brand's tenants
|
|
387
|
+
tenant_id__scope_context__scope_field__day_index: {
|
|
388
|
+
tenant_id: 1,
|
|
389
|
+
scope_context: 1,
|
|
390
|
+
scope_field: 1,
|
|
391
|
+
day_index: 1,
|
|
392
|
+
}, // weekday queries over LOCAL_HOUR / LOCAL_DATE slices
|
|
393
|
+
brand_id__scope_context__scope_field__day_index: {
|
|
394
|
+
brand_id: 1,
|
|
395
|
+
scope_context: 1,
|
|
396
|
+
scope_field: 1,
|
|
397
|
+
day_index: 1,
|
|
398
|
+
}, // brand-level weekday queries over LOCAL_HOUR / LOCAL_DATE slices
|
|
399
|
+
};
|
|
@@ -31,6 +31,8 @@ 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_tenant_reports_iterations';
|
|
35
|
+
export * from './materialized_tenant_sales_overview_reports';
|
|
34
36
|
export * from './menus';
|
|
35
37
|
export * from './messaging_devices';
|
|
36
38
|
export * from './modifier_extras';
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import { REPORT_SALE_TYPE_ENUM } from '../../constants';
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Constants for the `materialized_*` report collections (see
|
|
3
|
+
* `MATERIALIZED_REPORTS.md`).
|
|
4
|
+
*
|
|
5
|
+
* NOTE: during the current development phase the materialized-report files
|
|
6
|
+
* stay self-contained — this file is NOT (yet) re-exported from
|
|
7
|
+
* `src/constants/index.ts`; the report schema/type files import it via
|
|
8
|
+
* relative paths. Wiring re-exports into the barrels is a separate,
|
|
9
|
+
* explicitly-enabled step.
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* Time-scope of a materialized report document. Every document covers exactly
|
|
13
|
+
* one tenant × one scope context × one scope value (`scope_field`), and the
|
|
14
|
+
* same scope set is shared by every materialized report collection.
|
|
15
|
+
*
|
|
16
|
+
* `scope_field` formats (all strings), derived from the existing toolkit time
|
|
17
|
+
* helpers (`getLocalDocumentFields`, `getIsoWeekOfYear`, `getCalendarWeekStart`)
|
|
18
|
+
* for the order's business day (`order.localDate`) — hours use the PUNCH hour
|
|
19
|
+
* for sales and the SETTLEMENT hour for credit-bill collections:
|
|
20
|
+
* - `LOCAL_HOUR`: 'YYYY-MM-DD HH' — e.g. '2026-09-15 18' (one hour of one day)
|
|
21
|
+
* - `LOCAL_DATE`: 'YYYY-MM-DD' — e.g. '2026-09-15'
|
|
22
|
+
* - `LOCAL_WEEK`: 'YYYY-MM-DD' — week start (Sun–Sat, the calendar UI's
|
|
23
|
+
* convention: `getCalendarWeekStart(date, 0)`)
|
|
24
|
+
* - `LOCAL_WEEK_OF_YEAR`: 'YYYY-Wnn' — ISO week (`getIsoWeekOfYear`); `YYYY` is the
|
|
25
|
+
* ISO week-year for boundary weeks
|
|
26
|
+
* - `LOCAL_MONTH`: 'YYYY-MM' — e.g. '2026-09'
|
|
27
|
+
* - `LOCAL_QUARTER`: 'YYYY-Qn' — e.g. '2026-Q3'
|
|
28
|
+
* - `LOCAL_SEMESTER`: 'YYYY-Sn' — e.g. '2026-S2'
|
|
29
|
+
* - `LOCAL_YEAR`: 'YYYY' — e.g. '2026'
|
|
30
|
+
*
|
|
31
|
+
* `DAY_INDEX` is intentionally NOT a scope: a weekday accumulator has no time
|
|
32
|
+
* anchor — it cannot honor date-range filters and would grow forever. Instead,
|
|
33
|
+
* `LOCAL_HOUR` and `LOCAL_DATE` documents carry a denormalized `day_index`
|
|
34
|
+
* field (`DAY_INDEX_ENUM`) so weekday filtering/grouping is a plain query over
|
|
35
|
+
* the date/hour slices (see `MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX`).
|
|
36
|
+
*
|
|
37
|
+
* The day-end materialization job compiles the tenant's day into the report
|
|
38
|
+
* collections: up to 24 `LOCAL_HOUR` documents plus one document for each
|
|
39
|
+
* other scope (31 per tenant-day; the longer-period documents accumulate until
|
|
40
|
+
* their period ends). Changing scope values or their formats requires a
|
|
41
|
+
* `schema_version` bump and re-materialization of history.
|
|
42
|
+
*/
|
|
43
|
+
export declare enum MATERIALIZED_REPORT_SCOPE_ENUM {
|
|
44
|
+
LOCAL_HOUR = "localHour",
|
|
45
|
+
LOCAL_DATE = "localDate",
|
|
46
|
+
LOCAL_WEEK = "localWeek",
|
|
47
|
+
LOCAL_WEEK_OF_YEAR = "localWeekOfYear",
|
|
48
|
+
LOCAL_MONTH = "localMonth",
|
|
49
|
+
LOCAL_QUARTER = "localQuarter",
|
|
50
|
+
LOCAL_SEMESTER = "localSemester",
|
|
51
|
+
LOCAL_YEAR = "localYear"
|
|
52
|
+
}
|
|
53
|
+
export declare const ALL_MATERIALIZED_REPORT_SCOPES: MATERIALIZED_REPORT_SCOPE_ENUM[];
|
|
54
|
+
/**
|
|
55
|
+
* Scopes whose documents carry the denormalized `day_index` weekday field
|
|
56
|
+
* (derived from `scope_field` by the materializer, `DAY_INDEX_ENUM`). All
|
|
57
|
+
* other scopes must leave it `null` — weekday analysis reads date/hour slices
|
|
58
|
+
* (`LOCAL_HOUR` / `LOCAL_DATE`) instead of an all-time accumulator document.
|
|
59
|
+
*/
|
|
60
|
+
export declare const MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX: MATERIALIZED_REPORT_SCOPE_ENUM[];
|
|
61
|
+
/**
|
|
62
|
+
* Filter dimensions that can be encoded into the metric keys of a materialized
|
|
63
|
+
* report document (`sale_type_metrics`). The declaration order defines the key
|
|
64
|
+
* grammar: `<DIM_1>:<DIM_2>:...` built from raw enum/live string values
|
|
65
|
+
* (e.g. `PLACED:POS_WALK-IN`). Changing the dimensions or their order requires
|
|
66
|
+
* a `schema_version` bump and re-materialization of historical documents.
|
|
67
|
+
*/
|
|
68
|
+
export declare enum MATERIALIZED_REPORT_KEY_FILTER_ENUM {
|
|
69
|
+
ORDER_STATUS = "ORDER_STATUS",
|
|
70
|
+
PLATFORM = "PLATFORM"
|
|
71
|
+
}
|
|
72
|
+
export declare const ALL_MATERIALIZED_REPORT_KEY_FILTERS: MATERIALIZED_REPORT_KEY_FILTER_ENUM[];
|
|
73
|
+
/** Ordered key filters of the tenant sales overview report (`PLACED:POS_WALK-IN`). */
|
|
74
|
+
export declare const SALES_OVERVIEW_KEY_FILTERS: MATERIALIZED_REPORT_KEY_FILTER_ENUM[];
|
|
75
|
+
/**
|
|
76
|
+
* Payment-type label used by the frontend report formatter for the derived
|
|
77
|
+
* credit-settlement line in a collection day's payments breakdown (a
|
|
78
|
+
* `PAY_LATER` bill collected on a later day). NOT stored in materialized docs —
|
|
79
|
+
* the formatter composes the line from the `CREDIT_BILLS` ledger's `received`
|
|
80
|
+
* bucket. The line is excluded from method buckets (CASH/CARD/…) and never
|
|
81
|
+
* feeds gross: gross stays sales-only, so cross-day gross sums stay equal to
|
|
82
|
+
* total sales.
|
|
83
|
+
*/
|
|
84
|
+
export declare const MATERIALIZED_CREDIT_SETTLEMENT_PAYMENT_TYPE = "CREDIT_SETTLEMENT";
|
|
85
|
+
/**
|
|
86
|
+
* Materialized report kinds — the discriminator stored on
|
|
87
|
+
* `materialized_tenant_reports_iterations` rows. A single shared history collection records
|
|
88
|
+
* the structural iterations of EVERY materialized report, so each row must
|
|
89
|
+
* declare which report collection its `report_id` belongs to. Add one member
|
|
90
|
+
* per new report collection (Summary / X / Z / Riders / Items / Void Items …)
|
|
91
|
+
* as it lands.
|
|
92
|
+
*/
|
|
93
|
+
export declare enum MATERIALIZED_REPORT_TYPE_ENUM {
|
|
94
|
+
TENANT_SALES_OVERVIEW = "TENANT_SALES_OVERVIEW"
|
|
95
|
+
}
|
|
96
|
+
export declare const ALL_MATERIALIZED_REPORT_TYPES: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_SALES_OVERVIEW[];
|