@pisell/private-materials 6.12.200 → 6.12.201

package/es/components/bigSale/templates/HDLKiosk/payment/HDLKioskPaymentRuntime.js

@@ -1,3 +1,4 @@
+import { _objectSpread2 } from "../../../../../_virtual/_@oxc-project_runtime@0.122.0/helpers/objectSpread2.js";
 import { _asyncToGenerator } from "../../../../../_virtual/_@oxc-project_runtime@0.122.0/helpers/asyncToGenerator.js";
 import useEngineContext from "../../../../../hooks/useEngineContext.js";
 import { CHECKOUT_VISIBLE_PAYMENT_CODES } from "../../../../checkout/constants.js";
@@ -9,12 +10,15 @@ import { executeEftposPayment } from "./eftposPayment.js";
 import { createStaffPaymentAuthorizationStore, isStaffPaymentAuthorizationCancelled, resolveStaffPaymentResult } from "./staffPaymentAuthorization.js";
 import { createHDLKioskPaymentResult } from "./paymentResult.js";
 import { completeBigSaleNoPaymentOrder } from "./noPaymentOrder.js";
-import React, { useEffect, useLayoutEffect, useMemo, useRef } from "react";
+import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from "react";
 //#region src/components/bigSale/templates/HDLKiosk/payment/HDLKioskPaymentRuntime.tsx
 /**
 * BigSale 模板内的 Kiosk 支付桥。它持有需要 React/设备 UI 的 PaymentMethodRuntime，
 * 再把窄命令交给独立 HDLKiosk Host；Core 不感知 BigSale、PiPayment 或 window.app。
 */
+function diagnosticText(value, fallback = "unknown") {
+	return (String(value !== null && value !== void 0 ? value : "").trim() || fallback).slice(0, 200);
+}
 function asKioskMethod(method) {
 	var _raw$channel_applicat;
 	const raw = method;
@@ -35,7 +39,7 @@ function currentAmount(context) {
 	const amount = resolveBigSaleCurrentAmountDue(context);
 	return typeof amount === "number" && Number.isFinite(amount) && amount > 0 ? amount : 0;
 }
-function HDLKioskPaymentRuntime({ context, controllerRef, onPaymentResultChange }) {
+function HDLKioskPaymentRuntime({ active, context, controllerRef, onPaymentResultChange, telemetry }) {
 	var _context$sales$tempOr, _engineContext$appHel5;
 	const engineContext = useEngineContext();
 	const runtimeRef = useRef(null);
@@ -43,11 +47,31 @@ function HDLKioskPaymentRuntime({ context, controllerRef, onPaymentResultChange
 	const rawMethodsRef = useRef(/* @__PURE__ */ new Map());
 	const paymentResultContextRef = useRef(context);
 	const paymentResultChangeRef = useRef(onPaymentResultChange);
+	const activeRef = useRef(active);
+	const staffPaymentAttemptRef = useRef();
 	paymentResultContextRef.current = context;
 	paymentResultChangeRef.current = onPaymentResultChange;
+	activeRef.current = active;
 	const authorizationStore = useMemo(() => createStaffPaymentAuthorizationStore(), []);
 	const baseSales = context.sales.bookingTicket;
 	const currencySymbol = ((_context$sales$tempOr = context.sales.tempOrder) === null || _context$sales$tempOr === void 0 ? void 0 : _context$sales$tempOr.currency_symbol) || "$";
+	const emitDiagnostic = useCallback((name, traceId, attributes) => {
+		try {
+			telemetry.emit({
+				name,
+				traceId,
+				occurredAt: Date.now(),
+				attributes
+			});
+		} catch (_unused) {}
+	}, [telemetry]);
+	useEffect(() => {
+		var _window$location;
+		emitDiagnostic("hdlKiosk.runtime.lifecycle", `hdl-payment-runtime:${Date.now()}:${active ? "active" : "inactive"}`, {
+			phase: active ? "activated" : "deactivated",
+			pathname: diagnosticText((_window$location = window.location) === null || _window$location === void 0 ? void 0 : _window$location.pathname, "/")
+		});
+	}, [active, emitDiagnostic]);
 	const controller = useMemo(() => ({
 		loadPaymentMethods: function() {
 			var _ref = _asyncToGenerator(function* () {
@@ -126,6 +150,19 @@ function HDLKioskPaymentRuntime({ context, controllerRef, onPaymentResultChange
 				if (typeof (globalApp === null || globalApp === void 0 ? void 0 : globalApp.runFunction) !== "function") return failed("staffPaymentAuthorizationUnavailable", "staff");
 				const authorization = authorizationStore.begin();
 				if (!authorization) return failed("staffPaymentAuthorizationInProgress", "retry");
+				const startedAt = Date.now();
+				const attempt = {
+					attemptId: `hdl-staff-payment:${startedAt}:${authorization.token}`,
+					authorization,
+					methodCode: method.code,
+					startedAt
+				};
+				staffPaymentAttemptRef.current = attempt;
+				emitDiagnostic("hdlKiosk.staffPayment.authorization", attempt.attemptId, {
+					phase: "started",
+					authorizationToken: authorization.token,
+					methodCode: method.code
+				});
 				try {
 					var _baseSales$getOtherPa;
 					const otherParams = (yield baseSales === null || baseSales === void 0 || (_baseSales$getOtherPa = baseSales.getOtherParams) === null || _baseSales$getOtherPa === void 0 ? void 0 : _baseSales$getOtherPa.call(baseSales)) || (baseSales === null || baseSales === void 0 ? void 0 : baseSales.otherParams) || {};
@@ -137,30 +174,82 @@ function HDLKioskPaymentRuntime({ context, controllerRef, onPaymentResultChange
 							paymentMethodType: method.type,
 							amount
 						},
-						onClose: () => authorizationStore.cancel(authorization)
+						onClose: () => {
+							var _staffPaymentAttemptR;
+							const cancelled = authorizationStore.cancel(authorization);
+							emitDiagnostic("hdlKiosk.staffPayment.authorization", attempt.attemptId, {
+								phase: cancelled ? "closed" : "closeIgnored",
+								authorizationToken: authorization.token,
+								elapsedMs: Date.now() - attempt.startedAt
+							});
+							if (cancelled && ((_staffPaymentAttemptR = staffPaymentAttemptRef.current) === null || _staffPaymentAttemptR === void 0 ? void 0 : _staffPaymentAttemptR.authorization) === authorization) staffPaymentAttemptRef.current = void 0;
+						}
 					});
-					if (authorizationStore.isSettling(authorization)) return {
-						status: "succeeded",
-						data: void 0
-					};
+					if (authorizationStore.isSettling(authorization)) {
+						emitDiagnostic("hdlKiosk.staffPayment.authorization", attempt.attemptId, {
+							phase: "dispatchSucceededDuringSettlement",
+							authorizationToken: authorization.token,
+							elapsedMs: Date.now() - attempt.startedAt
+						});
+						return {
+							status: "succeeded",
+							data: void 0
+						};
+					}
 					if (isStaffPaymentAuthorizationCancelled(result)) {
+						var _staffPaymentAttemptR2;
 						authorizationStore.cancel(authorization);
+						emitDiagnostic("hdlKiosk.staffPayment.authorization", attempt.attemptId, {
+							phase: "dispatchCancelled",
+							authorizationToken: authorization.token,
+							elapsedMs: Date.now() - attempt.startedAt
+						});
+						if (((_staffPaymentAttemptR2 = staffPaymentAttemptRef.current) === null || _staffPaymentAttemptR2 === void 0 ? void 0 : _staffPaymentAttemptR2.authorization) === authorization) staffPaymentAttemptRef.current = void 0;
 						return failed("staffPaymentAuthorizationCancelled", "retry");
 					}
 					if ((result === null || result === void 0 ? void 0 : result.status) !== "success") {
+						var _staffPaymentAttemptR3;
 						authorizationStore.fail(authorization);
+						emitDiagnostic("hdlKiosk.staffPayment.authorization", attempt.attemptId, {
+							phase: "dispatchFailed",
+							authorizationToken: authorization.token,
+							resultStatus: diagnosticText(result === null || result === void 0 ? void 0 : result.status),
+							elapsedMs: Date.now() - attempt.startedAt
+						});
+						if (((_staffPaymentAttemptR3 = staffPaymentAttemptRef.current) === null || _staffPaymentAttemptR3 === void 0 ? void 0 : _staffPaymentAttemptR3.authorization) === authorization) staffPaymentAttemptRef.current = void 0;
 						return failed("staffPaymentAuthorizationDispatchFailed", "retry", result.msg);
 					}
+					emitDiagnostic("hdlKiosk.staffPayment.authorization", attempt.attemptId, {
+						phase: "dispatchSucceeded",
+						authorizationToken: authorization.token,
+						elapsedMs: Date.now() - attempt.startedAt
+					});
 					return {
 						status: "succeeded",
 						data: void 0
 					};
 				} catch (error) {
-					if (authorizationStore.isSettling(authorization)) return {
-						status: "succeeded",
-						data: void 0
-					};
+					var _staffPaymentAttemptR4;
+					if (authorizationStore.isSettling(authorization)) {
+						emitDiagnostic("hdlKiosk.staffPayment.authorization", attempt.attemptId, {
+							phase: "dispatchErroredDuringSettlement",
+							authorizationToken: authorization.token,
+							message: diagnosticText(error instanceof Error ? error.message : error),
+							elapsedMs: Date.now() - attempt.startedAt
+						});
+						return {
+							status: "succeeded",
+							data: void 0
+						};
+					}
 					authorizationStore.fail(authorization);
+					emitDiagnostic("hdlKiosk.staffPayment.authorization", attempt.attemptId, {
+						phase: "dispatchFailed",
+						authorizationToken: authorization.token,
+						message: diagnosticText(error instanceof Error ? error.message : error),
+						elapsedMs: Date.now() - attempt.startedAt
+					});
+					if (((_staffPaymentAttemptR4 = staffPaymentAttemptRef.current) === null || _staffPaymentAttemptR4 === void 0 ? void 0 : _staffPaymentAttemptR4.authorization) === authorization) staffPaymentAttemptRef.current = void 0;
 					return failed("staffPaymentAuthorizationDispatchFailed", "retry", error);
 				}
 			});
@@ -175,26 +264,48 @@ function HDLKioskPaymentRuntime({ context, controllerRef, onPaymentResultChange
 		context,
 		currencySymbol,
 		(_engineContext$appHel5 = engineContext.appHelper) === null || _engineContext$appHel5 === void 0 ? void 0 : _engineContext$appHel5.utils,
+		emitDiagnostic,
 		onPaymentResultChange
 	]);
 	useEffect(() => {
 		let cleanup;
 		let globalApp;
 		try {
-			var _window2, _app$applicationManag, _globalApp$runFunctio;
+			var _window2, _app$applicationManag;
 			const app = (_window2 = window) === null || _window2 === void 0 ? void 0 : _window2.app;
 			globalApp = app === null || app === void 0 || (_app$applicationManag = app.applicationManager) === null || _app$applicationManag === void 0 ? void 0 : _app$applicationManag.get("global");
-			cleanup = globalApp === null || globalApp === void 0 || (_globalApp$runFunctio = globalApp.runFunction) === null || _globalApp$runFunctio === void 0 ? void 0 : _globalApp$runFunctio.call(globalApp, "listenExternalCommand", {
+			if (typeof (globalApp === null || globalApp === void 0 ? void 0 : globalApp.runFunction) !== "function") throw new Error("global application is unavailable");
+			cleanup = globalApp.runFunction("listenExternalCommand", {
 				app,
 				handler: (command) => {
+					var _staffPaymentAttemptR5;
 					if (command.command !== "payment_result") return;
+					const params = command.params || {};
+					const currentAttempt = staffPaymentAttemptRef.current;
+					const hostRequestId = diagnosticText(params.requestId, "missing");
+					const traceId = (currentAttempt === null || currentAttempt === void 0 ? void 0 : currentAttempt.attemptId) || `hdl-staff-payment:orphan:${hostRequestId}:${Date.now()}`;
+					emitDiagnostic("hdlKiosk.staffPayment.result", traceId, _objectSpread2({
+						phase: "received",
+						hostRequestId,
+						resultStatus: diagnosticText(params.status),
+						ok: params.ok === true,
+						hasActiveAttempt: Boolean(currentAttempt)
+					}, currentAttempt ? { methodCode: currentAttempt.methodCode } : {}));
 					const authorization = authorizationStore.beginSettlement();
-					if (!authorization) return;
+					if (!authorization) {
+						emitDiagnostic("hdlKiosk.staffPayment.result", traceId, {
+							phase: "ignored",
+							reason: "no-active-authorization",
+							hostRequestId,
+							resultStatus: diagnosticText(params.status)
+						});
+						return;
+					}
 					try {
-						var _globalApp$runFunctio2;
-						globalApp === null || globalApp === void 0 || (_globalApp$runFunctio2 = globalApp.runFunction) === null || _globalApp$runFunctio2 === void 0 || _globalApp$runFunctio2.call(globalApp, "closeAuthorization");
-					} catch (_unused) {}
-					const result = resolveStaffPaymentResult(command.params || {});
+						var _globalApp$runFunctio;
+						globalApp === null || globalApp === void 0 || (_globalApp$runFunctio = globalApp.runFunction) === null || _globalApp$runFunctio === void 0 || _globalApp$runFunctio.call(globalApp, "closeAuthorization");
+					} catch (_unused2) {}
+					const result = resolveStaffPaymentResult(params);
 					if (result.status === "succeeded") {
 						var _currentContext$sales;
 						const currentContext = paymentResultContextRef.current;
@@ -202,21 +313,48 @@ function HDLKioskPaymentRuntime({ context, controllerRef, onPaymentResultChange
 							source: "staff",
 							fallbackAmount: currentAmount(currentContext),
 							currencySymbol: (_currentContext$sales = currentContext.sales.tempOrder) === null || _currentContext$sales === void 0 ? void 0 : _currentContext$sales.currency_symbol,
-							rawResult: command.params
+							rawResult: params
 						}));
+						emitDiagnostic("hdlKiosk.staffPayment.result", traceId, {
+							phase: "projected",
+							hostRequestId,
+							resultStatus: result.status
+						});
 					}
-					authorizationStore.complete(authorization, result);
+					const published = authorizationStore.complete(authorization, result);
+					emitDiagnostic("hdlKiosk.staffPayment.result", traceId, {
+						phase: published ? "published" : "publishIgnored",
+						hostRequestId,
+						resultStatus: result.status
+					});
+					if (published && ((_staffPaymentAttemptR5 = staffPaymentAttemptRef.current) === null || _staffPaymentAttemptR5 === void 0 ? void 0 : _staffPaymentAttemptR5.authorization) === authorization) staffPaymentAttemptRef.current = void 0;
 				}
 			});
-		} catch (_unused2) {}
+			emitDiagnostic("hdlKiosk.staffPayment.result", `hdl-staff-payment-listener:${Date.now()}`, { phase: "listenerRegistered" });
+		} catch (error) {
+			emitDiagnostic("hdlKiosk.staffPayment.result", `hdl-staff-payment-listener:${Date.now()}`, {
+				phase: "listenerRegistrationFailed",
+				message: diagnosticText(error instanceof Error ? error.message : error)
+			});
+		}
 		return () => {
+			var _window$location2;
 			if (typeof cleanup === "function") cleanup();
-			if (authorizationStore.dispose()) try {
-				var _globalApp$runFunctio3;
-				globalApp === null || globalApp === void 0 || (_globalApp$runFunctio3 = globalApp.runFunction) === null || _globalApp$runFunctio3 === void 0 || _globalApp$runFunctio3.call(globalApp, "closeAuthorization");
+			const hadActiveAuthorization = authorizationStore.dispose();
+			const currentAttempt = staffPaymentAttemptRef.current;
+			emitDiagnostic("hdlKiosk.runtime.lifecycle", (currentAttempt === null || currentAttempt === void 0 ? void 0 : currentAttempt.attemptId) || `hdl-payment-runtime:${Date.now()}:unmounted`, {
+				phase: "unmounted",
+				active: activeRef.current,
+				hadActiveAuthorization,
+				pathname: diagnosticText((_window$location2 = window.location) === null || _window$location2 === void 0 ? void 0 : _window$location2.pathname, "/")
+			});
+			staffPaymentAttemptRef.current = void 0;
+			if (hadActiveAuthorization) try {
+				var _globalApp$runFunctio2;
+				globalApp === null || globalApp === void 0 || (_globalApp$runFunctio2 = globalApp.runFunction) === null || _globalApp$runFunctio2 === void 0 || _globalApp$runFunctio2.call(globalApp, "closeAuthorization");
 			} catch (_unused3) {}
 		};
-	}, [authorizationStore]);
+	}, [authorizationStore, emitDiagnostic]);
 	useLayoutEffect(() => {
 		controllerRef.current = controller;
 		return () => {

package/lib/components/HDLKiosk/index.js

@@ -59,10 +59,11 @@ function HDLKioskContent({ host, config, isActive = true, entryDataPreparing = f
 		setActiveLocale(nextLocale);
 		onLocaleChange === null || onLocaleChange === void 0 || onLocaleChange(nextLocale);
 	}, [onLocaleChange]);
-	const { session, starting, startErrorReference, exiting, exitError, pendingExit, start, back, requestExit, resolveExit, completeOrder, recover } = require_useHDLKioskSessionController.useHDLKioskSessionController({
+	const { session, starting, preparingEntry, entryPreparationErrorReference, startErrorReference, exiting, exitError, pendingExit, start, back, requestExit, resolveExit, completeOrder, recover, retryEntryPreparation } = require_useHDLKioskSessionController.useHDLKioskSessionController({
 		host,
 		config,
-		isActive
+		isActive,
+		entryPreparationBlocked: entryDataPreparing || sales.hostStatus === "loading"
 	});
 	const observeExit = (0, react.useCallback)((result) => {
 		if (result.status === "exited") onPaymentResultReset === null || onPaymentResultReset === void 0 || onPaymentResultReset();
@@ -169,10 +170,12 @@ function HDLKioskContent({ host, config, isActive = true, entryDataPreparing = f
 				start({ entry });
 			}
 		},
-		busy: starting,
-		errorReference: startErrorReference,
-		errorMessage: _pisell_utils.locales.getText("pisell2.hdl-kiosk.session-start-failed")
-	}), starting ? /* @__PURE__ */ react.default.createElement("div", {
+		busy: starting || preparingEntry || Boolean(entryPreparationErrorReference),
+		errorReference: entryPreparationErrorReference || startErrorReference,
+		errorMessage: _pisell_utils.locales.getText(entryPreparationErrorReference ? "pisell2.hdl-kiosk.reset-failed-description" : "pisell2.hdl-kiosk.session-start-failed"),
+		retryLabel: entryPreparationErrorReference ? _pisell_utils.locales.getText("pisell2.hdl-kiosk.retry-entry-preparation") : void 0,
+		onRetry: entryPreparationErrorReference ? retryEntryPreparation : void 0
+	}), starting || preparingEntry ? /* @__PURE__ */ react.default.createElement("div", {
 		className: "hdl-operation-overlay",
 		role: "status"
 	}, /* @__PURE__ */ react.default.createElement("span", { className: "hdl-operation-overlay__spinner" }), /* @__PURE__ */ react.default.createElement("strong", null, _pisell_utils.locales.getText("pisell2.hdl-kiosk.working"))) : null));

package/lib/components/HDLKiosk/locales.js

@@ -45,6 +45,7 @@ const localeTexts = {
 		"pisell2.hdl-kiosk.payment-conflict-title": "Payment needs attention",
 		"pisell2.hdl-kiosk.payment-conflict-description": "Please do not pay again. Ask a staff member to check your payment.",
 		"pisell2.hdl-kiosk.resetting-order": "Preparing next order…",
+		"pisell2.hdl-kiosk.retry-entry-preparation": "Retry preparation",
 		"pisell2.hdl-kiosk.order-needs-attention": "The previous action did not complete. Review the order before continuing.",
 		"pisell2.hdl-kiosk.fulfillment-unavailable": "This device cannot save the dining option yet. Please ask a staff member for help.",
 		"pisell2.hdl-kiosk.keep-ordering": "Keep ordering",
@@ -86,6 +87,8 @@ const localeTexts = {
 		"pisell2.hdl-kiosk.customization-unit-price": "Unit price",
 		"pisell2.hdl-kiosk.customization-per100g": "/100g",
 		"pisell2.hdl-kiosk.customization-next": "Next",
+		"pisell2.hdl-kiosk.customization-required-options": "Please select an option for every required group.",
+		"pisell2.hdl-kiosk.customization-required-group": (groupName) => `Please select an option in “${groupName}”.`,
 		"pisell2.hdl-kiosk.primary-product-prompt-eyebrow": "Before Checkout",
 		"pisell2.hdl-kiosk.primary-product-prompt-title": "Would you like to add a Malatang bowl?",
 		"pisell2.hdl-kiosk.primary-product-prompt-accept": "Yes",
@@ -202,6 +205,7 @@ const localeTexts = {
 		"pisell2.hdl-kiosk.payment-conflict-title": "请确认支付状态",
 		"pisell2.hdl-kiosk.payment-conflict-description": "请勿重复付款，并联系工作人员确认。",
 		"pisell2.hdl-kiosk.resetting-order": "正在准备下一单…",
+		"pisell2.hdl-kiosk.retry-entry-preparation": "重新准备",
 		"pisell2.hdl-kiosk.order-needs-attention": "上一步未完成，请核对订单后再继续。",
 		"pisell2.hdl-kiosk.fulfillment-unavailable": "当前设备尚未接入用餐方式写入能力，请联系工作人员处理。",
 		"pisell2.hdl-kiosk.keep-ordering": "继续点餐",
@@ -243,6 +247,8 @@ const localeTexts = {
 		"pisell2.hdl-kiosk.customization-unit-price": "单价",
 		"pisell2.hdl-kiosk.customization-per100g": "/100克",
 		"pisell2.hdl-kiosk.customization-next": "下一步",
+		"pisell2.hdl-kiosk.customization-required-options": "请完成所有必选规格的选择。",
+		"pisell2.hdl-kiosk.customization-required-group": (groupName) => `请选择「${groupName}」中的必选项。`,
 		"pisell2.hdl-kiosk.primary-product-prompt-eyebrow": "结账前确认",
 		"pisell2.hdl-kiosk.primary-product-prompt-title": "需要添加一份麻辣烫吗？",
 		"pisell2.hdl-kiosk.primary-product-prompt-accept": "需要",
@@ -359,6 +365,7 @@ const localeTexts = {
 		"pisell2.hdl-kiosk.payment-conflict-title": "請確認付款狀態",
 		"pisell2.hdl-kiosk.payment-conflict-description": "請勿重複付款，並聯絡工作人員確認。",
 		"pisell2.hdl-kiosk.resetting-order": "正在準備下一單…",
+		"pisell2.hdl-kiosk.retry-entry-preparation": "重新準備",
 		"pisell2.hdl-kiosk.order-needs-attention": "上一步未完成，請核對訂單後再繼續。",
 		"pisell2.hdl-kiosk.fulfillment-unavailable": "當前設備尚未接入用餐方式寫入能力，請聯絡工作人員處理。",
 		"pisell2.hdl-kiosk.keep-ordering": "繼續點餐",
@@ -400,6 +407,8 @@ const localeTexts = {
 		"pisell2.hdl-kiosk.customization-unit-price": "單價",
 		"pisell2.hdl-kiosk.customization-per100g": "/100克",
 		"pisell2.hdl-kiosk.customization-next": "下一步",
+		"pisell2.hdl-kiosk.customization-required-options": "請完成所有必選規格的選擇。",
+		"pisell2.hdl-kiosk.customization-required-group": (groupName) => `請選擇「${groupName}」中的必選項。`,
 		"pisell2.hdl-kiosk.primary-product-prompt-eyebrow": "結帳前確認",
 		"pisell2.hdl-kiosk.primary-product-prompt-title": "需要加入一份麻辣燙嗎？",
 		"pisell2.hdl-kiosk.primary-product-prompt-accept": "需要",
@@ -516,6 +525,7 @@ const localeTexts = {
 		"pisell2.hdl-kiosk.payment-conflict-title": "お支払い状況をご確認ください",
 		"pisell2.hdl-kiosk.payment-conflict-description": "再度支払わず、スタッフにお声がけください。",
 		"pisell2.hdl-kiosk.resetting-order": "次の注文を準備中…",
+		"pisell2.hdl-kiosk.retry-entry-preparation": "もう一度準備する",
 		"pisell2.hdl-kiosk.order-needs-attention": "前の操作が完了していません。注文を確認してから続けてください。",
 		"pisell2.hdl-kiosk.fulfillment-unavailable": "この端末では現在、飲食方法を保存できません。スタッフにお声がけください。",
 		"pisell2.hdl-kiosk.keep-ordering": "注文を続ける",
@@ -557,6 +567,8 @@ const localeTexts = {
 		"pisell2.hdl-kiosk.customization-unit-price": "単価",
 		"pisell2.hdl-kiosk.customization-per100g": "/100g",
 		"pisell2.hdl-kiosk.customization-next": "次へ",
+		"pisell2.hdl-kiosk.customization-required-options": "必須項目をすべて選択してください。",
+		"pisell2.hdl-kiosk.customization-required-group": (groupName) => `「${groupName}」の必須項目を選択してください。`,
 		"pisell2.hdl-kiosk.primary-product-prompt-eyebrow": "お会計前の確認",
 		"pisell2.hdl-kiosk.primary-product-prompt-title": "麻辣湯を1杯追加しますか？",
 		"pisell2.hdl-kiosk.primary-product-prompt-accept": "はい",
@@ -673,6 +685,7 @@ const localeTexts = {
 		"pisell2.hdl-kiosk.payment-conflict-title": "Confirme o estado do pagamento",
 		"pisell2.hdl-kiosk.payment-conflict-description": "Não pague novamente. Peça ajuda a um funcionário.",
 		"pisell2.hdl-kiosk.resetting-order": "A preparar o próximo pedido…",
+		"pisell2.hdl-kiosk.retry-entry-preparation": "Tentar preparar novamente",
 		"pisell2.hdl-kiosk.order-needs-attention": "A ação anterior não foi concluída. Verifique o pedido antes de continuar.",
 		"pisell2.hdl-kiosk.fulfillment-unavailable": "Este dispositivo ainda não consegue guardar a opção de consumo. Peça ajuda a um funcionário.",
 		"pisell2.hdl-kiosk.keep-ordering": "Continuar a pedir",
@@ -714,6 +727,8 @@ const localeTexts = {
 		"pisell2.hdl-kiosk.customization-unit-price": "Preço unitário",
 		"pisell2.hdl-kiosk.customization-per100g": "/100 g",
 		"pisell2.hdl-kiosk.customization-next": "Seguinte",
+		"pisell2.hdl-kiosk.customization-required-options": "Selecione uma opção em cada grupo obrigatório.",
+		"pisell2.hdl-kiosk.customization-required-group": (groupName) => `Selecione uma opção obrigatória em “${groupName}”.`,
 		"pisell2.hdl-kiosk.primary-product-prompt-eyebrow": "Antes de finalizar",
 		"pisell2.hdl-kiosk.primary-product-prompt-title": "Deseja adicionar uma tigela de Malatang?",
 		"pisell2.hdl-kiosk.primary-product-prompt-accept": "Sim",

package/lib/components/HDLKiosk/runtime/entryPreparation.js

@@ -0,0 +1,48 @@
+const require_asyncToGenerator = require("../../../_virtual/_@oxc-project_runtime@0.122.0/helpers/asyncToGenerator.js");
+const require_errors = require("./operations/errors.js");
+//#region src/components/HDLKiosk/runtime/entryPreparation.ts
+function forwardFailure(result) {
+	return result;
+}
+/** Entry 首次展示或重新激活时，必须先证明 Host 已不存在上一笔购物车。 */
+function prepareHDLKioskEntry(_x, _x2) {
+	return _prepareHDLKioskEntry.apply(this, arguments);
+}
+function _prepareHDLKioskEntry() {
+	_prepareHDLKioskEntry = require_asyncToGenerator._asyncToGenerator(function* (host, signal) {
+		let result;
+		try {
+			const payment = host.sales.readTransactionState().payment;
+			if (payment.status === "pending" || payment.status === "unknown") result = require_errors.operationUnknown("entryPreparationBlockedByPaymentState");
+			else if (signal.aborted) result = {
+				status: "cancelled",
+				reason: "entryPreparationAborted"
+			};
+			else {
+				const reset = yield host.sales.clearAndReset(signal);
+				if (reset.status !== "succeeded") result = forwardFailure(reset);
+				else if (!reset.data.cartEmpty) result = require_errors.operationUnknown("entryPreparationHostResultNotEmpty");
+				else if (signal.aborted) result = {
+					status: "cancelled",
+					reason: "entryPreparationAborted"
+				};
+				else {
+					const consistency = yield host.sales.waitForCartConsistency(signal);
+					result = consistency.status === "succeeded" ? {
+						status: "succeeded",
+						data: void 0
+					} : forwardFailure(consistency);
+				}
+			}
+		} catch (cause) {
+			result = {
+				status: "failed",
+				error: require_errors.createOperationError("entryPreparationUnhandled", "staff", cause)
+			};
+		}
+		return result;
+	});
+	return _prepareHDLKioskEntry.apply(this, arguments);
+}
+//#endregion
+exports.prepareHDLKioskEntry = prepareHDLKioskEntry;

package/lib/components/HDLKiosk/runtime/session/createSession.js

@@ -62,9 +62,30 @@ function createHDLKioskWorkflowSession(entry, host, options = {}) {
 	let staffPaymentPending = false;
 	let staffPaymentConfirmed = false;
 	let staffPaymentRejected = false;
+	let staffPaymentObserved = false;
+	let staffPaymentAdvanceDispatched = false;
+	let lastStaffPaymentAdvanceDiagnostic = "";
 	let completedOrderFinalized = false;
 	let completedOrderFinalizePromise;
 	const staffPaymentReceipt = Object.freeze({ paymentConfirmed: true });
+	const emitStaffPaymentWorkflow = (phase, authorizationStatus, reason) => {
+		const snapshot = workflowActor.getSnapshot();
+		try {
+			host.telemetry.emit({
+				name: "hdlKiosk.staffPayment.workflow",
+				traceId: `${snapshot.workflowId}:${snapshot.sessionEpoch}:staff-payment`,
+				occurredAt: Date.now(),
+				attributes: require_objectSpread2._objectSpread2({
+					phase,
+					authorizationStatus,
+					workflowId: snapshot.workflowId,
+					sessionEpoch: snapshot.sessionEpoch,
+					nodeId: snapshot.nodeId,
+					workflowStatus: snapshot.status
+				}, reason ? { reason } : {})
+			});
+		} catch (_unused) {}
+	};
 	const dispatchConfirmedPayment = (receipt, intentId) => {
 		var _definition$nodes$sna;
 		const snapshot = workflowActor.getSnapshot();
@@ -80,8 +101,26 @@ function createHDLKioskWorkflowSession(entry, host, options = {}) {
 	};
 	const advanceConfirmedStaffPayment = () => {
 		var _definition$nodes$sna2;
+		if (!staffPaymentObserved || staffPaymentPending || staffPaymentAdvanceDispatched) return;
 		const snapshot = workflowActor.getSnapshot();
-		if (snapshot.status !== "idle" || ((_definition$nodes$sna2 = definition.nodes[snapshot.nodeId]) === null || _definition$nodes$sna2 === void 0 ? void 0 : _definition$nodes$sna2.activity) !== "paymentMethod" || staffPaymentRejected || staffPaymentPending && !staffPaymentConfirmed || !staffPaymentConfirmed) return;
+		if (staffPaymentRejected || !staffPaymentConfirmed) return;
+		const skipReason = snapshot.status !== "idle" ? "workflow-not-idle" : ((_definition$nodes$sna2 = definition.nodes[snapshot.nodeId]) === null || _definition$nodes$sna2 === void 0 ? void 0 : _definition$nodes$sna2.activity) !== "paymentMethod" ? "not-payment-method" : void 0;
+		if (skipReason) {
+			const diagnostic = [
+				snapshot.sessionEpoch,
+				snapshot.nodeId,
+				snapshot.status,
+				skipReason
+			].join(":");
+			if (diagnostic !== lastStaffPaymentAdvanceDiagnostic) {
+				lastStaffPaymentAdvanceDiagnostic = diagnostic;
+				emitStaffPaymentWorkflow("advanceSkipped", "succeeded", skipReason);
+			}
+			return;
+		}
+		staffPaymentAdvanceDispatched = true;
+		lastStaffPaymentAdvanceDiagnostic = `${snapshot.sessionEpoch}:advanced`;
+		emitStaffPaymentWorkflow("advanced", "succeeded");
 		dispatchConfirmedPayment(staffPaymentReceipt, `staff-payment:${snapshot.sessionEpoch}`);
 	};
 	const finalizeCompletedOrder = (intentId) => {
@@ -116,15 +155,20 @@ function createHDLKioskWorkflowSession(entry, host, options = {}) {
 	try {
 		unsubscribePaymentWorkflow = workflowActor.subscribe(handleWorkflowUpdate);
 		unsubscribeStaffPayment = host.sales.subscribeStaffPaymentAuthorizationResult((result) => {
+			staffPaymentObserved = true;
 			if (result.status === "pending") {
 				staffPaymentPending = true;
 				staffPaymentConfirmed = false;
 				staffPaymentRejected = false;
+				staffPaymentAdvanceDispatched = false;
+				lastStaffPaymentAdvanceDiagnostic = "";
+				emitStaffPaymentWorkflow("pending", result.status);
 				return;
 			}
 			staffPaymentPending = false;
 			staffPaymentConfirmed = result.status === "succeeded";
 			staffPaymentRejected = !staffPaymentConfirmed;
+			emitStaffPaymentWorkflow(staffPaymentConfirmed ? "confirmed" : "rejected", result.status);
 			if (staffPaymentConfirmed) coordinator.confirmPaymentSucceeded();
 			advanceConfirmedStaffPayment();
 		});
@@ -154,7 +198,7 @@ function createHDLKioskWorkflowSession(entry, host, options = {}) {
 				sessionEpoch: snapshot.sessionEpoch
 			}
 		});
-	} catch (_unused) {}
+	} catch (_unused2) {}
 	const disposeSession = () => {
 		if (disposed) return;
 		disposed = true;

package/lib/components/HDLKiosk/slices/customization/Screen/index.js

@@ -1,6 +1,7 @@
 const require_runtime = require("../../../../../_virtual/_rolldown/runtime.js");
 const require_objectSpread2 = require("../../../../../_virtual/_@oxc-project_runtime@0.122.0/helpers/objectSpread2.js");
 const require_asyncToGenerator = require("../../../../../_virtual/_@oxc-project_runtime@0.122.0/helpers/asyncToGenerator.js");
+const require_resolveLocalizedText = require("../../../../../plus/salesSdk/utils/resolveLocalizedText.js");
 const require_index = require("../../../components/shell/HDLKioskBottomBarHost/index.js");
 const require_index$1 = require("../../../components/shell/HDLKioskOrderSummary/index.js");
 const require_model = require("../../../components/common/HDLKioskSkuOptionsSelection/model.js");
@@ -12,6 +13,7 @@ react = require_runtime.__toESM(react);
 let _pisell_utils = require("@pisell/utils");
 let decimal_js = require("decimal.js");
 decimal_js = require_runtime.__toESM(decimal_js);
+let _pisell_materials = require("@pisell/materials");
 //#region src/components/HDLKiosk/slices/customization/Screen/index.tsx
 /**
 * 文件角色：呈现主称重商品的本地重量与标准 SkuValue 草稿。
@@ -50,6 +52,22 @@ function formatMoney(value, currencySymbol) {
 	const amount = value.toDecimalPlaces(2).toNumber();
 	return String((0, _pisell_utils.formatAmount)(amount, 2, currencySymbol || ""));
 }
+function resolveInvalidSkuGroupName(error, product) {
+	var _group$name;
+	if (!error || typeof error !== "object" || Array.isArray(error) || !product) return;
+	const firstInvalidGroupId = Object.keys(error)[0];
+	if (!firstInvalidGroupId) return void 0;
+	const source = product;
+	const group = [
+		"variant_group",
+		"option_group",
+		"bundle_group"
+	].flatMap((key) => Array.isArray(source[key]) ? source[key] : []).find((candidate) => {
+		var _candidate$id;
+		return String((_candidate$id = candidate === null || candidate === void 0 ? void 0 : candidate.id) !== null && _candidate$id !== void 0 ? _candidate$id : "") === firstInvalidGroupId;
+	});
+	return require_resolveLocalizedText.resolveLocalizedText((_group$name = group === null || group === void 0 ? void 0 : group.name) !== null && _group$name !== void 0 ? _group$name : group === null || group === void 0 ? void 0 : group.title) || void 0;
+}
 function resolveScaleMeasurement(scale, productFacts, minimumWeightKg) {
 	var _scale$grossWeightKg, _productFacts$fixedTa, _productFacts$fixedTa2;
 	const gross = new decimal_js.default((_scale$grossWeightKg = scale.grossWeightKg) !== null && _scale$grossWeightKg !== void 0 ? _scale$grossWeightKg : NaN);
@@ -151,6 +169,7 @@ function ProductFallback() {
 }
 function CustomizationScreen({ product, loading, errorReference, errorMessage, busy, syncing, canGoBack, minimumWeightKg, orderBar, send }) {
 	var _productFacts$product, _orderBar$primaryLine, _orderBar$primaryLine2, _orderBar$primaryLine3, _orderBar$primaryLine4, _orderBar$primaryLine7, _productFacts$unitPri, _orderBar$primaryLine9, _orderBar$primaryLine11;
+	const Toast = (0, _pisell_materials.useToast)();
 	const scaleRuntime = require_scale.useHDLScaleRuntime();
 	const scale = require_scale.useHDLScaleSnapshot();
 	const skuOptionsRef = (0, react.useRef)(null);
@@ -190,7 +209,9 @@ function CustomizationScreen({ product, loading, errorReference, errorMessage, b
 		try {
 			var _skuOptionsRef$curren;
 			yield (_skuOptionsRef$curren = skuOptionsRef.current) === null || _skuOptionsRef$curren === void 0 ? void 0 : _skuOptionsRef$curren.validate();
-		} catch (_unused) {
+		} catch (error) {
+			const invalidGroupName = resolveInvalidSkuGroupName(error, product);
+			Toast.fail(invalidGroupName ? _pisell_utils.locales.getText("pisell2.hdl-kiosk.customization-required-group")(invalidGroupName) : _pisell_utils.locales.getText("pisell2.hdl-kiosk.customization-required-options"));
 			return;
 		}
 		const submittedSkuValue = (_skuOptionsRef$curren2 = (_skuOptionsRef$curren3 = skuOptionsRef.current) === null || _skuOptionsRef$curren3 === void 0 ? void 0 : _skuOptionsRef$curren3.getTransformValues()) !== null && _skuOptionsRef$curren2 !== void 0 ? _skuOptionsRef$curren2 : skuValue;
@@ -216,11 +237,13 @@ function CustomizationScreen({ product, loading, errorReference, errorMessage, b
 		busy,
 		minimumWeightKg,
 		(_orderBar$primaryLine9 = orderBar.primaryLine) === null || _orderBar$primaryLine9 === void 0 ? void 0 : _orderBar$primaryLine9.lineId,
+		product,
 		productFacts,
 		scaleRuntime,
 		skuValue,
 		send,
-		syncing
+		syncing,
+		Toast
 	]);
 	const omitPrimaryProduct = (0, react.useCallback)(() => {
 		var _orderBar$primaryLine10;