@pisell/private-materials 6.12.168 → 6.12.169

package/es/components/HDLKiosk/docs/09-Entry/350/256/276/345/244/207/344/272/213/344/273/266/351/207/215/346/236/204/344/277/256/345/244/215/346/212/245/345/221/212.md

@@ -0,0 +1,187 @@
+# Entry 设备事件重构修复报告
+
+## 1. 背景
+
+本次检查对照 `sc/260817/beta-HDLKiosk` 的 Entry/Flow 设备事件实现，复核无头
+Application Runtime 重构后的扫码与称重链路。目标行为为：
+
+- Entry 首码先创建并发布 Catalog Session，再执行 `barcode.consume`；
+- Session 启动期间的后续扫码归属于该 pending Session，不丢码、不另起流程；
+- Scanner 在 Entry、Session 启动中和 Flow 内由同一个无头路由持有；称重由 Entry
+  Trigger 与共享 Scale Runtime 分别负责边沿触发和连续状态；
+- inactive、支付完成和 reset 阶段不得由设备事件启动新 Session。
+
+## 2. 发现的问题
+
+### 2.1 Runtime 在 Kiosk inactive 时仍激活
+
+Session Controller 无条件激活 Application Runtime，导致隐藏状态仍订阅 Scanner/Scale。
+除了可能抢占其他页面的扫码焦点，设备事件还可能先执行 `session.ensure`，再被 UI 层销毁。
+
+### 2.2 Session 启动窗口内扫码丢失
+
+重构后 Entry Trigger 和 Flow Scanner Controller 分开。Session 尚未发布时，Flow
+Controller 因没有 `sessionRef` 忽略扫码；Application Runtime 又因已有 pending start
+拒绝新的自动入口，导致 Barcode 连扫以及 Quick/Scale 启动期间扫码丢失。
+
+### 2.3 finished Session 不再占用准入名额
+
+Runtime 原先只统计 `session.isActive()`。PaymentCompleted 会让 Actor 进入 `finished`，但
+UI 仍展示支付结果并持有该 Session。在自动 reset 前，扫码或称重可能启动新流程。
+
+### 2.4 finished Session 无法显式释放
+
+`disposeSession` 对 `isActive() === false` 直接返回，导致 PaymentCompleted reset 后 Actor
+和 Registry 记录没有按调用方预期释放。
+
+### 2.5 Entry 与 Flow 同时消费同一设备 Port
+
+Application Trigger Adapter 和 Flow Scanner Controller 使用两套 Ingress/支付策略接收
+同一事件。虽然 Operation Coordinator 能避免直接并发写购物车，但会产生重复准入、
+遥测缺口和后续策略漂移风险。
+
+### 2.6 Barcode-only 配置不激活 Scale Runtime
+
+Barcode Workflow 可以进入 Customization，但 BigSale Scale Runtime 只在 Quick/Scale
+入口启用。仅开启 Barcode 时，称重详情无法取得有效秤快照。
+
+## 3. 修复方案
+
+### 3.1 可逆 Runtime 生命周期
+
+Application Runtime 新增 `deactivate()`：释放 Trigger Adapter cleanup，但保留现有
+Session。Session Controller 根据 `isActive` 激活或停用 Runtime。每次 activate 同时推进
+`activationEpoch`；旧激活周期创建的 Session 即使在重新 active 后才完成，也会被识别为
+迟到结果并 dispose，不会跨生命周期发布。
+
+### 3.2 显式 Session 所有权准入
+
+Runtime 使用 owned Session 集合控制 `maxActiveSessions`。Session 即使自然 finished，
+在显式 `disposeSession` 前仍占用名额。`disposeSession` 现在允许释放 finished Session。
+
+### 3.3 单一 ScannerSessionRouter
+
+移除组合层 `PendingStartupScan` 和 React `useHDLKioskScannerController`。无头
+`ScannerSessionRouter` 唯一订阅 Scanner，并用一条 FIFO 覆盖三种阶段：
+
+- `idle`：首码入队后同步进入 `starting`，再发出 `onScan` 启动请求；
+- `starting`：Quick/Scale/Barcode 启动期间的扫码继续追加到同一队列；
+- `active`：Flow 新扫码仍追加到同一队列，并由当前 Session 串行消费。
+
+因此启动窗口的 B 码一定早于 Session 发布后到达的 C 码，不再存在两条队列交叉导致
+`A → C → B` 的可能。
+
+每次启动以 `cause.correlationId` 作为 `startId`。`begin/bind/fail` 必须携带相同 startId，
+旧启动的迟到 rejected 无权清理新启动队列。
+
+队列最多容纳 5 个未完成任务（running 也计入）；超限、启动失败、inactive、Session
+dispose 或前一任务结果不确定时，剩余任务都会收到结构化拒绝遥测，且不记录原始条码。
+当 Host 返回 `requiresSelection` 时，拒绝选择态建立前已经排队的旧任务并结束本轮
+drain。Router 不为尚不存在的 Host 完成协议维护永久冻结状态；选择弹层由 Scanner
+focus stack 临时接管物理扫码，关闭后新扫码重新按正常准入处理。
+
+### 3.4 `onStarted` 回归生命周期职责
+
+`onStarted` 只调用 `scannerRouter.bindSession(session)`。它不保存队列、不解释
+`barcode.consume`，也不直接执行业务。Router 只有在 Registry 已发布 `started` 后才开始
+drain，保留“先进入 Flow，再消费 code”的业务时序。Session 显式 dispose 后 Router
+release 并回到 `idle`。
+
+### 3.5 Router 与业务 Command 解耦
+
+Router 只依赖 `ScannerSessionPort`，不再 import `HDLKioskWorkflowSession`，也不包含
+`barcode.consume`、支付 Operation ID 或页面 Activity。具体可写策略、导航取消和
+Command 映射集中在 `scannerSessionPort.ts` 适配层，并增加架构边界测试防止回流。
+
+### 3.6 执行中任务的取消与代际隔离
+
+Session dispose 现在同时 dispose Operation Coordinator，触发其 AbortController，避免
+仍在执行的扫码 Command 泄漏到已销毁 Session。单纯 inactive 会保留 Session，因此不
+强杀可能已经写入 Host 的操作；Router 会推进 generation，并把迟到结果标为 stale，
+禁止它冻结、清理或继续驱动新激活周期的队列。
+
+### 3.7 选择态的最小处理
+
+`requiresSelection` 只承担当前已知事实：拒绝此前积压任务并停止本轮 drain。不新增
+无生产调用方的 resume API，也不维护无法被当前 Host 协议可靠解除的冻结状态。未来若
+Host 提供正式完成事件，再按实际契约补充等待语义。
+
+### 3.8 Barcode Scale Runtime
+
+BigSale Scale Runtime 的激活条件补充 Barcode 入口，确保 Barcode Flow 进入
+Customization 后仍能获得实时秤快照。
+
+BigSale Scanner focus 保持标准栈语义，不设置永久高优先级：HDLKiosk active 时位于全局
+扫码监听之上，后打开的选择或搜索弹层仍可临时接管，关闭后自然恢复。同步修正了遗留
+测试对 `priority: 100` 的错误预期。
+
+### 3.9 Scale 提交安全补强
+
+Scale Runtime 增加唯一的 `sampleSequence`，仅由 NativeScale 的真实 `onChange` 帧
+推进。断连、停止监听、读取错误、负重或超载会使当前采样失效；重连但未收到新帧时不
+恢复 Next。这里没有增加固定读数超时：顾客将商品放稳后长时间选择规格属于正常场景。
+
+Customization 的展示与提交复用同一个纯校验，提交回调不再信任上一次 React render，
+而是在点击 Next 时同步读取 Runtime 最新快照并冻结当下稳定重量。SkuDetailModal 的
+实时 Auto 模式同步收紧为只有 liveData、listening、connected、stable 且无错误时有效；
+员工 Manual 和编辑态尚未 re-read 的历史快照行为保持不变。
+
+## 4. 修复后的关键时序
+
+```text
+Entry 首码
+  → ScannerIngress
+  → ScannerSessionRouter FIFO
+  → onScan occurrence
+  → session.ensure
+  → Registry started（Catalog 已发布）
+  → onStarted.bindSession
+  → barcode.consume（同一 FIFO 串行 drain）
+
+Flow 内扫码
+  → 同一个 ScannerSessionRouter FIFO
+  → barcode.consume
+
+Entry 称重
+  → ScaleIngress
+  → onWeight occurrence
+  → Scale Session / Customization
+
+Flow 内称重
+  → BigSale Scale owner
+  → HDLScaleRuntime snapshot
+  → Customization measurement
+```
+
+## 5. 验证
+
+新增或补强以下回归覆盖：
+
+- Runtime deactivate/re-activate 与 Adapter cleanup；
+- 旧 activation epoch 的迟到 Session 不会在重新激活后发布；
+- 旧 startId 的迟到失败不会清理新启动队列；
+- finished Session 在 dispose 前继续阻止准入；
+- finished Session 可被显式 dispose；
+- Barcode 首码先发布 Catalog，再加购；
+- Barcode 启动期间连续扫码按顺序消费；
+- 启动窗口旧码与 Flow 新码严格保持单一 FIFO 顺序；
+- Quick 启动期间扫码绑定 Quick Session；
+- Quick-only 配置仍允许 Flow 内扫码，但不允许扫码作为 Entry；
+- `requiresSelection` 拒绝旧队列任务，但不会永久冻结 Session 的后续扫码；
+- inactive 前已执行的扫码结果按 generation 隔离，不影响重新激活后的队列；
+- Session dispose 会取消仍在执行的 Operation；
+- owned/finished Session 阶段扫码和称重不能启动新流程；
+- inactive Runtime 不持有设备订阅、不执行 `session.ensure`；
+- React Session Controller 随 `isActive` 激活/释放 Trigger。
+
+扩展轻量测试结果：HDLKiosk 50 个测试文件、271 项测试全部通过；BigSale HDLKiosk
+适配层 11 个测试文件、73 项测试全部通过。
+
+Scale 安全补强后再次合并运行 HDLKiosk、BigSale HDLKiosk Adapter 与
+`pro/skuDetailModal`：68 个测试文件、429 项测试全部通过。
+
+补充 `tsc --noEmit` 未能形成有效项目级结论：当前安装的
+`node_modules/@types/react/index.d.ts` 在 `HTMLAttributes` 附近存在结构损坏，且仓库内
+已有 `.ts` 测试文件包含 JSX，编译在进入本次修改源码前即失败。
+
+未运行 `pnpm`/`npm` webpack build，符合本工作区 Material 项目的验证约束。

package/es/components/HDLKiosk/docs/README.md

@@ -1,7 +1,7 @@
 # HDLKiosk 文档导航
 
 > 当前阶段：架构骨架已完成，后续重点是正式 Host 业务契约、真实设备/支付验收和 UI 还原。  
-> 更新日期：2026-08-20
+> 更新日期：2026-08-23
 
 ## 1. 从哪里开始
 
@@ -15,6 +15,8 @@
 6. [03-业务流程与交互规则.md](./03-业务流程与交互规则.md)：理解三入口和当前权威流程；
 7. [07-后续工作.md](./07-后续工作.md)：选择下一项业务或 UI 工作。
 
+理解或修改无头 Application Runtime 时，阅读 [08-无头 Application Runtime 重构设计.md](./08-无头Application运行时重构设计.md)。该文档同时记录已实现边界和剩余工作。
+
 按任务类型阅读：
 
 | 任务                                      | 必读文档                                               |
@@ -24,6 +26,7 @@
 | 修改扫码、称重或入口自动触发              | `04-设备与称重`、`03-业务流程与交互规则`               |
 | 还原 UI、文案和交互                       | `03-业务流程与交互规则`、原型 `kiosk/app/page.tsx`     |
 | 编写测试或准备实机验收                    | `06-测试与验收`、`07-后续工作`                         |
+| 实施无头 Application、Trigger 或 Runtime  | `08-无头 Application Runtime 重构设计`、`01-核心运行机制` |
 
 ## 2. 常驻文档
 
@@ -39,6 +42,7 @@
 | [06-测试与验收.md](./06-测试与验收.md)                  | 自动测试层级、异常矩阵、实机门禁                                               | 项目排期               |
 | [07-后续工作.md](./07-后续工作.md)                      | 未完成业务、UI 和生产化优先级                                                  | 已完成历史             |
 | [实施进度.md](./实施进度.md)                            | 当前事实快照、临时开关、最近关键变更                                           | 完整设计论证           |
+| [08-无头Application运行时重构设计.md](./08-无头Application运行时重构设计.md) | Application/Runtime/Session、Trigger Channel、Contract/Binding 的实现边界与状态 | 具体业务流程 |
 
 ## 3. 事实优先级
 
@@ -62,4 +66,4 @@
 - Workflow 节点顺序改变：先更新 `03-业务流程与交互规则.md`，再改代码；
 - 新增临时兼容策略：必须在 `实施进度.md` 登记开关、影响、退出条件和风险；
 - 已完成的分步清单、一次性论证和测试流水不再新建独立文档；
-- 文档不复制大段类型定义，详细字段以 `components/HDLKiosk/contracts` 为准。
+- 文档不复制大段类型定义，详细字段以 `components/HDLKiosk/app/contracts` 为准。

package/es/components/HDLKiosk/docs//345/256/236/346/226/275/350/277/233/345/272/246.md

@@ -32,7 +32,7 @@
 | Operation/Coordinator | 本地完成     | 冲突、去重、epoch、timeout、freeze                                                                                                                                                   | 真实 OS 时序验证                                               |
 | 表现层目录与边界      | 本地完成     | Screen/Dialog/Layout 独立目录与样式；Renderer/View Model 集中在 Presentation；Shell 通过 BottomBarHost 唯一挂载 FloatingBar/CartDrawer                                               | 后续逐 Screen 声明 BottomBar，不在 Screen 内重复挂载容器       |
 | Quick 主商品          | 待实机       | 模板临时商品 ID 通过 OS query 获取；Fulfillment 后进入 Customization，本地保留称重/options 草稿，Next 才交给 OS 加购，价格只消费 OS Projection                                      | 正式商品 ID 配置、真秤及真实折扣验收                           |
-| Barcode               | 待实机       | Session 级 Scanner Controller 在 active 生命周期常驻；Entry 首码等待 Session 激活，Quick/Scale 启动期间扫码归属 pending Session；可写页面使用 5 项 FIFO 串行加购且不导航 | 商品码专用 Host API、选择态闭环、稳定 eventId、全局反馈与实机 |
+| Barcode               | 待实机       | 无头 ScannerSessionRouter 在 active 生命周期常驻；Entry、启动中和 Flow 共用 5 项 FIFO，首码等待 Session 发布后串行加购且不导航 | 商品码专用 Host API、选择态闭环、稳定 eventId、全局反馈与实机 |
 | Scale                 | 待实机       | 顶层 Runtime、自动入口；有效重量先进入 Fulfillment，再进入与 Quick 共用的 Customization，本地草稿在 Next 时提交                                                                   | 真秤全矩阵、正式商品                                           |
 | Catalog               | 待实机       | HDLKiosk 模板驱动现有 retail Product Provider 正式 load 后读取快照；分类/搜索/商品卡、连续加购、订单悬浮栏及购物车 Drawer 已完成                                                     | 大目录虚拟化、复杂规格接管、实机视觉                           |
 | Cart Overlay          | 待业务/实机 | 已替代独立 Review/Voucher Slice；复用全局 BottomBar，展示 Host 商品、数量、卡券入口、小计和备注能力                                                                                | 称重/定制重新编辑、价格变化反馈、促销/税/节省明细              |
@@ -94,8 +94,8 @@
 - BigSale 公共边界收缩后，Adapter 纯逻辑定向回归 4 个测试文件、42 个用例通过；Hook 用例因工作区缺少 `@testing-library/react` 未能启动，完整 `tsc` 仍被本地 `node_modules/@types/react/index.d.ts` 的既有语法损坏阻断；本轮变更文件已通过 esbuild 语法转换检查；
 - Entry 首版复用了原型主视觉和 SVG 动效，在 1080×1920 画布与原型逐项对照：Quick 卡原型 `y=773.0`、当前 `y=769.8`，卡片宽高、三卡总高度与底部工具区位置一致；同时增加 1280×720 横屏降级布局；
 - Entry 的英文/简中切换与 Reach Mode 已在独立预览中验证；Reach Mode 将主操作区从约 `y=604` 下移到 `y=849`，不改变 Workflow/设备入口语义；Less 编译和 Entry esbuild bundle 通过，入口与共享展示投影 7 个用例通过；React 组件测试仍被工作区缺少 `@testing-library/react` 阻断；
-- 表现层按所有权组织：业务私有 Screen/Dialog、ViewModel 与 `slice.ts`、`view.tsx` 同置于 `slices/<name>/`；跨 Slice 的 Shell、Overlay 和公共控件位于 `components/`，公共类型与纯方法分别位于根 `types.ts`、`utils.ts`；活跃会话 UI 编排位于 `runtime/HDLKioskWorkflowView.tsx`；
-- 组件依赖门禁递归覆盖 `slices/`、`components/` 与 `app/entry`；Slice 业务定义不依赖 React，Workflow/Operation 纯逻辑测试不会加载物料 UI；
+- 表现层按所有权组织：业务私有 Screen/Dialog、ViewModel 与 `slice.ts`、`view.tsx` 同置于 `slices/<name>/`；跨 Slice 的 Shell、Overlay 和公共控件位于 `components/`，公共类型与纯方法分别位于根 `types.ts`、`utils.ts`；活跃会话 UI 编排位于 `ui/HDLKioskWorkflowView.tsx`；
+- 组件依赖门禁递归覆盖 `slices/`、`components/` 与 `ui/entry`；Slice 业务定义不依赖 React，Workflow/Operation 纯逻辑测试不会加载物料 UI；
 - Identity 已从通用 Step 拆成独立 Screen，并按原型还原沉浸式品牌区、会员利益标题、App QR、SMS 和 Skip；Shell 使用显式 `identityGate` 变体隐藏常规页头/页脚。SMS 无业务 handler，Skip 复用既有 Guest `identity.sync`；109 个纯逻辑用例、Less 编译和根入口 esbuild bundle 继续通过；
 - Fulfillment 已从通用 Step 拆成独立 Screen，完成堂食/外带卡片及自动前进；BottomBar 不再假定该节点位于空订单阶段，实时购物车有商品时组合通用 `HDLKioskOrderSummary` 和可编辑 CartDrawer，显示 OS 确认的数量/金额；空车时仅保留 Back。Drawer 在此节点不伪造 Next，用户仍需在页面选择堂食或外带；
 - Customization 已完成称重主商品详情首版并按原型校准：Hero 固定，只有 options 区滚动；称重栏保留状态标识与 Unit Price/Weight/Tare；规格分组 Tab 在 HDLKiosk 作用域隐藏，不修改共享 `SKUOptionsSelection`。重量/options 只保留页面本地草稿，Next 才交给 OS `addProductWithFlow`，成功后前进；底栏和 Drawer 只使用 OS `summary.due`，不自行估算折扣；
@@ -112,17 +112,18 @@
 - Barcode 当前使用“激活 Session → 消费首码 → Catalog → 缺主商品时询问 → Yes 时 Fulfillment → 称重详情 → Next/OS 加购成功 → Catalog”的路径；No 保持在 Catalog 且不要求 Fulfillment，Cart Overlay 完成订单复核与卡券操作；
 - 移除遗留 `hdl-shell__footer` 与 `resolveScreenBottomBar`：Fulfillment、Customization、Catalog 改为声明实时 BottomBar，由 Shell 内唯一 `HDLKioskBottomBarHost` 渲染。BottomBar 当前区分 `visible / masked / hidden`：退出确认及 Catalog 主商品询问等普通 Modal 保留底栏并由遮罩阻止交互，同时自动收起 CartDrawer；只有等待员工、支付未决和 blocked 等不可导航状态才隐藏。购物车图标已接入基于 `CompensatedPisellContainer` 的底部 Drawer，展示 Host 已确认的商品、定制摘要、数量和金额，并在三个 Catalog workflow 中复用既有改数量/删除 Operation；
 - Workflow 使用线性优先的 Slice 数组：数组表达主路径，Slice Intent 通过 `next()` 或 `navigate: 'next'` 补齐默认前进，`on` 只描述分支、合流和跳跃；Back 是独立 Navigation，并按实际页面历史解析。同一 Slice 可用 `slice:用途` 多次出现，回路必须声明有限 repeat，Actor 超限即阻塞；Intent 同时携带 `stepId/activityId`，避免同类 Activity 的迟到实例误触发当前 Step。支付不确定是 Actor blocked 状态，不作为业务节点；
-- `slices/<name>/slice.ts` 是各业务能力唯一导出的 `defineSlice` 结果：Slice `id` 标识业务 Activity，`screen.id` 标识页面类别；`view.tsx` 就地完成该 Slice 的 ViewModel 派生和组件装配，`app/views.ts` 单独维护完整的 Activity → View 本地注册表，`ScreenRenderer` 进行同步解析。Kernel、Slice 和 Workflow 不依赖 React View；公共类型与跨 Slice 纯方法分别集中在根 `types.ts`、`utils.ts`；
-- Kernel 已不依赖 HDLKiosk contracts：结构 Compiler、Actor 和通用 Coordinator 位于 `kernel/`；`app/operations.ts` 是共享业务副作用的公共入口，私有实现位于 `app/operations/`，其中 Coordinator 注入 HDLKioskHost、冲突矩阵、支付冻结、错误分类和遥测。Slice 专属 Operation 与对应 Slice 同置；
+- `slices/<name>/slice.ts` 是各业务能力唯一导出的 `defineSlice` 结果：Slice `id` 标识业务 Activity，`surface.id` 标识页面类别；`view.tsx` 就地完成该 Slice 的 ViewModel 派生和组件装配，`ui/views.ts` 单独维护完整的 Activity → View 本地注册表，`ScreenRenderer` 进行同步解析。Kernel、Slice 和 Workflow 不依赖 React View；公共类型与跨 Slice 纯方法分别集中在根 `types.ts`、`utils.ts`；
+- Kernel 已不依赖 HDLKiosk contracts：结构 Compiler、Actor 和通用 Coordinator 位于 `kernel/`；Application 契约位于 `app/contracts`，具体 Host Handler 与 Coordinator 位于 `runtime/operations/`，其中注入 HDLKioskHost、冲突矩阵、支付冻结、错误分类和遥测；
 - HDLKiosk 阻断式 Dialog 已统一到 `HDLKioskModal → PisellModal`，默认层级高于 CartDrawer；BottomBar 的三态解析、组件依赖边界、Checkout 安全及现有 Dialog/Screen 定向用例通过，HDLKiosk 汇总 Less 编译、变更组件 esbuild 语法转换和 `git diff --check` 通过；
 - Shell 中途登录统一走 `executeCommand(identity.sync)`；明确失败可在原页重试，客户写入/重报价 `partial/unknown` 会阻塞 Actor。物料不维护 idle 警告或倒计时 UI；Session Controller 提供验证式 `returnToEntry` 接口，未来由应用级策略决定是否和何时触发；
 - Checkout 前置业务要求由 Activity Contract 声明 ID，Compiler 按当前流程汇总，Requirement Registry 结合 Workflow Context 和 Host Projection 判断适用性与满足状态。当前默认 Registry 为空；
 - 称重页的 Next 携带点击当下的商品/重量/options 草稿；点击前不同步 Host。详情页与 Scale 入口共用最小有效重量，稳定的微小残留不会启用 Next；
+- Scale Runtime 以 NativeScale `onChange` 的递增采样序号区分真实新帧：断连、停止监听、读取错误、负重或超载后必须收到新帧才恢复；稳定读数不使用固定超时。Next 点击时同步复核 Runtime 最新快照，SkuDetailModal 实时 Auto 同步要求 live/stable/connected/listening；
 - Barcode/Scale 已收敛为会话外部入口，不再伪装成可前进/后退的 Workflow Activity。Barcode 首码在 Session `readyForCommands && cartWritable` 后消费，不依赖首屏类型；Scale Workflow 当前从 Fulfillment 开始。两者的首页 Back 因无 Workflow 前驱而自然落入会话级清单并回 Entry，无需“入口节点不可回访”特例；
-- Scanner 订阅已从 Entry Device Controller 移到 Session 级 `useHDLKioskScannerController`；已有 Session、pending Quick/Scale 和 Entry 新建 Barcode Session 三种归属路径均有定向测试。Catalog transition 不再绑定 `checkout.prepare`，EFTPOS、店员授权和通用 checkout 在 dispatch 前统一检查 Prepared freshness；相关 12 个测试文件、88 个用例通过；
+- Scanner 订阅已收敛到无头 `ScannerSessionRouter`；Entry、pending Quick/Scale 和 Flow 扫码共享同一有限 FIFO，`onStarted` 只绑定已发布 Session，React 不再持有扫码硬件。Catalog transition 不再绑定 `checkout.prepare`，EFTPOS、店员授权和通用 checkout 在 dispatch 前统一检查 Prepared freshness；
 - 临时 live-debug reporter、密钥、日志和 Collector 已清理；
 - 日常验证遵守工作区规则，未使用 pnpm/npm 运行 material webpack build。
-- 当前目录职责为 `app / slices / components / runtime / contracts / devices / kernel / testing`；共享阻断表面使用 `BlockingNotice`，履约写入由 Checkout Prepare 统一完成。核心 25 个测试文件、135 个用例通过，根入口 esbuild bundle 通过。
+- 当前目录职责为 `kernel / app / slices / runtime / ui / components / testing`；共享阻断表面使用 `BlockingNotice`，履约写入由 Checkout Prepare 统一完成。
 
 本地 `468867` 参考文件不再参与运行时 import；无需恢复或维护为可执行 mock。
 

package/es/components/HDLKiosk/docs//346/236/266/346/236/204/350/256/276/350/256/241.md

@@ -60,11 +60,11 @@ flowchart TB
     POLICY["HDLKiosk Workflow Policy"]
     RUNNER["HDLKiosk Transition Runner"]
     LIFECYCLE["Workflow Lifecycle"]
-    OPS["app/operations.ts<br/>Shared Operation Facade"]
+    OPS["runtime/operations<br/>Host Operation Handlers"]
     OP_POLICY["HDLKiosk Operation Policy<br/>Host Context / Conflict / Telemetry"]
     SAFETY["Checkout Safety"]
     REQUIREMENT["Checkout Requirement Registry"]
-    VIEW["app/views Registry<br/>ScreenRenderer"]
+    VIEW["ui/views Registry<br/>ScreenRenderer"]
     UI["Slice Screens / Shared Components"]
 
     HOST --> PROJ
@@ -107,17 +107,18 @@ Kernel ✕ HDLKiosk contracts / BigSale / SalesSDK / merchant workflows / Screen
 | Contracts/Ports         | HDLKiosk 自有 DTO、能力和结果语义                                    | BigSale 字段兼容                              |
 | Projection              | 标准化 Host 可观察事实                                               | 发业务命令                                    |
 | Slice                 | 将 Screen、合法 Intent、局部 Command、退出 Effect 和 Requirement 收敛为业务能力 | 前后节点和 Host 实现              |
-| Application Manifest    | 汇总 Slice、Workflow 和 Operation 引用并生成可信注册表              | React 生命周期和订单事实                       |
+| Application Definition  | 汇总 Activity、Workflow、Trigger 与 Operation Contract              | Handler、React 生命周期和订单事实              |
+| Application Runtime     | Trigger 路由、Admission、Session Registry 和无头启动                | 业务方法实现和 React Presentation              |
 | Structural Compiler     | Step ID、相邻导航、可达性、终点、Modal 和有界循环                    | 支付和购物车策略                              |
 | HDLKiosk Policy         | 编译后检查支付来源和 Checkout Prepare 等交易约束                     | 修改节点结构                                  |
 | Workflow Actor          | mailbox、step/activity 防迟到、running/blocked、节点提交和循环计数   | Host、Predicate、Operation、支付解释和持久化   |
 | Transition Runner       | 求值 Predicate/执行 Exit Command，将结果归一为 advance/stay/blocked  | React、节点数组位置                           |
-| Operations              | 封装业务 Command 和写后验证                                          | Screen 导航                                   |
+| Operation Bindings      | 为 Contract 注入 Host Command 和写后验证                             | Screen 导航、Workflow 拓扑                     |
 | Requirement Registry    | 判断支付前业务要求对当前订单是否适用，并校验 Host Projection         | Workflow 节点编排和 UI                        |
 | Kernel Coordinator      | 用应用注入的 Context/Scope/Policy 处理冲突、去重、timeout 和 epoch    | 支付含义、Host、业务错误和节点目标             |
 | HDLKiosk Operation Policy | 注入 Host Context、冲突矩阵、支付 freeze、错误分类和遥测            | Screen 导航                                   |
 | Workflow                | 用有序 Slice 数组表达主路径，以 `on` 描述分支、合流和受限回路      | Screen 内部动作和订单事实                      |
-| Controllers             | session/device/customer 生命周期；提供验证式 `returnToEntry`         | OS 字段转换、决定自动返回时机                  |
+| Controllers             | React/设备输入适配和验证式 `returnToEntry`                            | 创建 Actor、拥有 Runtime Session Registry      |
 | View assembly           | 把 Activity 节点和 Projection 转换为组件输入，并路由 Intent/Navigation/Command | 决定目标节点                           |
 | Screens/Dialogs/Layouts | 展示、局部输入、Screen Command、Activity Intent 和 Back Navigation           | 直接调用 Host、Actor 或 Controller     |
 | BigSale Adapter         | DTO 转换、callback、插件、capability                                 | 决定流程节点                                  |
@@ -158,7 +159,7 @@ Screen：输入和展示状态
 1. Core 不 import BigSale、SalesSDK、Engine plugin 或 raw tempOrder。
 2. Adapter 不决定 Workflow 目标节点。
 3. Screen 不直接调用 Host；内部写操作发送 Command，离开步骤发送 Activity Intent，返回发送 Navigation。
-4. Slice 是 Screen、Intent、Command 和退出策略的唯一业务定义；Activity Registry 和 Operation Registry 从 Application Manifest 派生，不维护平行清单。
+4. Activity/Slice 是 Intent、Command 和退出策略的业务定义；Screen 可选，Operation 只引用 Contract，Handler Registry 位于 Runtime Binding。
 5. Workflow 作者只排列已注册 Slice；规范化后的运行结构不得包含 Screen、Predicate、Operation 或 failureTarget。重复 Slice 必须使用 `slice:用途` 标识每次出现。
 6. 只有可被业务编排者独立排序或分支的里程碑才成为节点；Dialog 内部询问、选择和等待阶段留在 Activity 内。
 7. Operation 不渲染 UI，不直接切 Screen。
@@ -221,23 +222,20 @@ HDLKiosk 无法独立保证：
 
 ```text
 components/HDLKiosk/
-├── app/              # 应用清单、三入口流程、共享 Operation 入口和节点渲染装配
-│   ├── workflow/     # Quick / Barcode / Scale + registry / predicates / navigation guards / policy
-│   ├── operations.ts # 跨 Slice Operation 的唯一公共导入面
-│   ├── operations/   # 公共入口背后的私有实现与测试
-│   └── entry/        # Workflow 外三入口页面
+├── kernel/           # Application / Workflow / Operation 通用执行原语
+├── app/              # HDLKiosk Contracts、Manifest、Workflow 与 Operation Contract
+│   ├── contracts/    # DTO / Ports / Config / Result / Error
+│   └── workflow/     # Quick / Barcode / Scale + registry / guards / policy
+├── runtime/          # 可脱离 React 的 Host Handler、Trigger、Devices 与 Session
+│   ├── operations/   # HDLKiosk 业务 Operation 与安全策略
+│   ├── devices/      # Scanner/Scale ingress、去重与 Scale Store
+│   └── session/      # Session / Actor / Context / Lifecycle 组合
+├── ui/               # React View Registry、Entry、Controller 与订阅 hooks
 ├── slices/           # 业务纵向切片：slice + operation + view + Screen/Dialog
 ├── components/       # 只承载跨 Slice 共享 UI 与样式
 │   ├── shell/        # Shell / Header / BottomBarHost / FloatingBar
 │   ├── overlays/     # CartDrawer / 会话 Dialog / PisellModal 统一壳
 │   └── common/       # 跨 Slice 视觉控件与 BlockingNotice
-├── runtime/          # Controllers / Projection subscriptions / active workflow view
-├── contracts/        # DTO / Ports / Config / Result / Error
-├── devices/          # Ingress / Arbiter / Dedupe / shared scale runtime
-├── kernel/           # 不依赖 HDLKiosk contracts 的通用执行原语
-│   ├── application/  # Slice / Workflow / Application 作者 API
-│   ├── workflow/     # Structural compiler / Actor / transition primitives
-│   └── operations/   # Generic coordinator / registry / epoch
 ├── testing/         # Fake Host / Fixtures
 ├── types.ts         # 公共 Props、Action、ViewModel 与 Slice View Context
 ├── utils.ts         # 跨 Slice 共享的纯方法和错误呈现

package/es/components/HDLKiosk/index.js

@@ -1,14 +1,15 @@
 import { _objectWithoutProperties } from "../../_virtual/_@oxc-project_runtime@0.122.0/helpers/objectWithoutProperties.js";
 import { HDLKioskErrorBoundary } from "./components/shell/HDLKioskErrorBoundary/index.js";
 import localeTexts from "./locales.js";
-import { useHDLKioskDeviceController } from "./runtime/controllers/useHDLKioskDeviceController.js";
-import { HDLScaleRuntimeProvider, createHDLScaleRuntime } from "./devices/scale/runtime.js";
-import { useHDLKioskSessionController } from "./runtime/controllers/useHDLKioskSessionController.js";
-import { useHDLKioskScannerController } from "./runtime/controllers/useHDLKioskScannerController.js";
-import { HDLKioskWorkflowView } from "./runtime/HDLKioskWorkflowView.js";
-import { useHostSnapshot } from "./runtime/useHostSnapshot.js";
-import { EntryScreen } from "./app/entry/Screen/index.js";
-import { createEntryScreenModel } from "./app/entry/model.js";
+import { useHDLKioskDeviceController } from "./ui/controllers/useHDLKioskDeviceController.js";
+import { useHDLKioskSessionController } from "./ui/controllers/useHDLKioskSessionController.js";
+import { createHDLScaleRuntime } from "./runtime/devices/scaleStore.js";
+import { HDLScaleRuntimeProvider } from "./ui/scale.js";
+import { useHostSnapshot } from "./ui/snapshots.js";
+import { HDLKioskWorkflowView } from "./ui/HDLKioskWorkflowView.js";
+import { EntryScreen } from "./ui/entry/Screen/index.js";
+import { createEntryScreenModel } from "./ui/entry/model.js";
+import ScaleSimulatorConsole, { isScaleSimulatorApiAvailable } from "./ui/ScaleSimulatorConsole/index.js";
 import React, { useCallback, useEffect, useMemo, useState } from "react";
 import { locales } from "@pisell/utils";
 import "./index.less";
@@ -32,6 +33,7 @@ function HDLKiosk(_ref) {
 }
 function HDLKioskContent({ host, config, isActive = true, entryDataPreparing = false, locale, onLocaleChange, onTechnicalSupportClick, renderIdentityAuth, renderCartContent, cartOverlayActions }) {
 	const [activeLocale, setActiveLocale] = useState(locale || "en");
+	const [scaleSimulatorAuthOpen, setScaleSimulatorAuthOpen] = useState(false);
 	const sales = useHostSnapshot(host);
 	locales.init(localeTexts, activeLocale);
 	useEffect(() => {
@@ -41,31 +43,17 @@ function HDLKioskContent({ host, config, isActive = true, entryDataPreparing = f
 		setActiveLocale(nextLocale);
 		onLocaleChange === null || onLocaleChange === void 0 || onLocaleChange(nextLocale);
 	}, [onLocaleChange]);
-	const { session, starting, startErrorReference, sessionRef, activeRef, scannerIngress, scaleIngress, start, waitForReadySession, returnToEntry } = useHDLKioskSessionController({
+	const handleScaleSimulatorRequest = useCallback(() => {
+		if (isScaleSimulatorApiAvailable()) setScaleSimulatorAuthOpen(true);
+	}, []);
+	const { session, starting, startErrorReference, returning, returnError, start, returnToEntry } = useHDLKioskSessionController({
 		host,
 		config,
 		isActive
 	});
 	const { scaleConnectionState } = useHDLKioskDeviceController({
 		host,
-		config,
-		isActive,
-		starting,
-		sessionRef,
-		activeRef,
-		scaleIngress,
-		start
-	});
-	useHDLKioskScannerController({
-		host,
-		config,
-		isActive,
-		starting,
-		sessionRef,
-		activeRef,
-		scannerIngress,
-		start,
-		waitForReadySession
+		isActive
 	});
 	return /* @__PURE__ */ React.createElement("div", {
 		className: "pisell-hdl-kiosk",
@@ -80,6 +68,8 @@ function HDLKioskContent({ host, config, isActive = true, entryDataPreparing = f
 		sales,
 		config,
 		isActive,
+		returning,
+		returnError,
 		returnToEntry,
 		renderIdentityAuth,
 		renderCartContent,
@@ -89,6 +79,7 @@ function HDLKioskContent({ host, config, isActive = true, entryDataPreparing = f
 		model: createEntryScreenModel(config, host.capabilities, scaleConnectionState, sales.hostStatus, entryDataPreparing),
 		onLocaleChange: handleLocaleChange,
 		onTechnicalSupportClick,
+		onScaleSimulatorRequest: handleScaleSimulatorRequest,
 		onSelect: (entry) => {
 			if (entry === "quick") start({ entry });
 		},
@@ -98,7 +89,10 @@ function HDLKioskContent({ host, config, isActive = true, entryDataPreparing = f
 	}), starting ? /* @__PURE__ */ React.createElement("div", {
 		className: "hdl-operation-overlay",
 		role: "status"
-	}, /* @__PURE__ */ React.createElement("span", { className: "hdl-operation-overlay__spinner" }), /* @__PURE__ */ React.createElement("strong", null, locales.getText("pisell2.hdl-kiosk.working"))) : null)));
+	}, /* @__PURE__ */ React.createElement("span", { className: "hdl-operation-overlay__spinner" }), /* @__PURE__ */ React.createElement("strong", null, locales.getText("pisell2.hdl-kiosk.working"))) : null)), /* @__PURE__ */ React.createElement(ScaleSimulatorConsole, {
+		authOpen: scaleSimulatorAuthOpen,
+		onAuthClose: () => setScaleSimulatorAuthOpen(false)
+	}));
 }
 //#endregion
 export { HDLKiosk as default };

package/es/components/HDLKiosk/index.less

@@ -88,4 +88,4 @@
 @import './slices/fulfillment/Screen/index.less';
 @import './slices/identity/Screen/index.less';
 @import './components/common/BlockingNotice/index.less';
-@import './app/entry/Screen/index.less';
+@import './ui/entry/Screen/index.less';

package/es/components/HDLKiosk/kernel/README.md

@@ -1,15 +1,15 @@
-# Kiosk Kernel
+# Workflow Kernel
 
 `kernel/` 是放在 HDLKiosk 目录内的无 UI 运行内核。它不依赖 `HDLKioskHost`、海底捞流程、支付模型、React、BigSale 或 SalesSDK，`dependencyBoundary.test.ts` 会检查这个约束。
 
 ## 开发一套 kiosk 时使用什么
 
-业务开发者主要使用 `application/` 的四类 API：
+业务开发者主要使用相邻 `../app/` 层的四类 API：
 
 ```ts
 const identity = defineSlice({
   id: 'identity',
-  screen: { id: 'identity' },
+  surface: { id: 'identity' },
   intents: {
     complete: effect(identifyCustomer, { navigate: 'next' }),
     omit: next(),
@@ -21,10 +21,10 @@ const identity = defineSlice({
 
 const order = defineWorkflow({
   id: 'merchant.order',
-  steps: [identity, catalog, { slice: result, end: 'success' }],
+  steps: [identity, catalog, { slice: result, isTerminal: true }],
 });
 
-const application = defineKioskApplication({
+const application = defineApplication({
   id: 'merchant-kiosk',
   slices: [identity, catalog, result],
   workflows: { order },
@@ -41,30 +41,31 @@ const views = {
 - `defineSlice`：把业务 Activity、Screen 描述、语义出口、Screen 内 Command 和离开时 Effect 放在一起；
 - `next()`：声明默认前进；Back 由独立 Navigation 和页面历史处理；
 - `defineWorkflow`：数组只表达 Slice 顺序，`on` 只处理跳跃、分支、合流和有界回路；
-- `defineKioskApplication`：汇总 Slice、Workflow 与应用级 Operation，并自动生成 Activity/Operation Manifest。
+- `defineApplication`：汇总 Slice、Workflow 与应用级 Operation，并自动生成 Activity/Operation Manifest。
 
 Slice 的 `intents` 是“业务活动请求流程执行的意图”，不是按钮或 DOM 事件。Back 使用独立 Navigation；不会离开 Screen 的动作放进 `commands`。支付门禁、设备监听、购物车写入验证等商家规则不进入 Kernel。
 
-三个标识的职责固定如下：Slice `id` 是 Workflow 引用的业务 Activity；`screen.id` 是 Shell、数据加载和展示策略使用的页面类别；React View 由应用层按 Activity 单独注册。不导航的业务操作声明为当前 Slice 的 Command，例如 `paymentMethod` 内的店员支付授权。
+Slice `id` 是 Workflow 引用的业务 Activity；可选 `surface.id` 是由外层解释的稳定展示键；React View 由具体 Presentation 按 Activity 单独注册。Kernel 只复制 `surfaceId`，不理解页面类别。
 
-Compiler 只把 `screen.id` 复制为节点的 `screenId`。Renderer 再按节点的 Activity 查询应用层 View 注册表。因此远端 Workflow 只能编排 Slice，不能替换本地页面实现；Kernel 也不依赖 React。
+Compiler 只把 `surface.id` 复制为节点的 `surfaceId`。Renderer 再按节点的 Activity 查询 Presentation View 注册表。因此远端 Workflow 只能编排 Slice，不能替换本地页面实现；Kernel 也不依赖 React。
 
 ## 目录职责
 
 | 目录 | 负责 | 由应用注入 |
 | --- | --- | --- |
-| `application/` | Slice/Workflow/Application 作者 API、Manifest 生成 | Screen 描述、Intent、Operation 引用 |
 | `workflow/` | 结构编译、Actor mailbox、节点提交、有界循环 | Activity Registry、Predicate Registry、Navigation Guard Registry、Transition Runner、Context Reducer |
 | `operations/` | 排队、冲突仲裁、intent 去重、timeout、Abort、session epoch | Context factory、错误分类、冲突规则、业务 Policy、观察器 |
 | `lifecycle.ts` | 组合 Actor 提交后的只读观察器 | telemetry、审计或持久化观察器 |
 
-Kernel Operation 只认识泛型 `Context / Error / Scope`。HDLKiosk 在外层 `app/operations/types.ts` 与 `app/operations/coordinator.ts` 注入 `HDLKioskHost`、冲突矩阵、支付冻结和遥测；另一个商家可以注入自己的 Host Context 与交易策略。
+Kernel Operation 只认识泛型 `Context / Error / Scope`。通用 Application 定义与运行时位于
+`../app/`；HDLKiosk 再在外层 `domain/operations/types.ts` 与
+`domain/operations/coordinator.ts` 注入 `HDLKioskHost`、冲突矩阵、支付冻结和遥测。
 
 ## 从定义到运行
 
 ```text
 Slice ─┐
-         ├─ defineKioskApplication ─ Manifest ─ Activity/Operation Registry
+         ├─ defineApplication ─ Manifest ─ Activity/Operation Registry
 Workflow ┘                                      │
                                                 ▼
                                     Structural Compiler ─ Actor
@@ -83,4 +84,4 @@ Activity Intent ─ Transition Runner ────────────┘
 - BigSale Adapter、插件检测、兼容开关；
 - UI 文案、错误展示和远端配置拉取。
 
-最小独立定义见 `application/application.test.ts`。该测试不导入任何 HDLKiosk 业务模块，并完成 Slice 收集、Operation 自动注册和 Workflow 编译。
+最小独立定义见 `../app/application.test.ts`。该测试不导入任何 HDLKiosk 业务模块，并完成 Slice 收集、Operation 自动注册和 Workflow 编译。