@pisell/private-materials 6.12.168 → 6.12.170

package/lib/components/HDLKiosk/docs/04-/350/256/276/345/244/207/344/270/216/347/247/260/351/207/215.md

@@ -15,7 +15,7 @@
 - 仅允许商品码。现有通用扫码 API 会执行多种业务码，必须补充“先分类后执行”或商品专用 API；
 - 不记录、持久化或写入遥测原始条码。
 
-截至 2026-08-20，Session 级 Scanner Controller、5 项 FIFO、pending Session 归属、Session 激活后首码消费，以及支付 dispatch 前的版本化 `ensurePrepared` 已落地。商品码专用 Host 契约、`requiresSelection` 完成协议、全局扫码反馈和跨 SalesSDK 的 scan/payment activity bridge 仍待生产化补齐。
+截至 2026-08-24，无头 ScannerSessionRouter、5 项统一 FIFO、pending Session 归属、Session 发布后首码消费，以及支付 dispatch 前的版本化 `ensurePrepared` 已落地。商品码专用 Host 契约、`requiresSelection` 完成协议、全局扫码反馈和跨 SalesSDK 的 scan/payment activity bridge 仍待生产化补齐。
 
 ## 2. 当前实现审计
 
@@ -24,13 +24,12 @@
 ```text
 Native scanner / pubsub
 → BigSale scanner adapter
-→ useHDLKioskScannerController（HDLKiosk active 生命周期常驻）
 → ScannerIngress.accept
-→ bounded FIFO
-→ waitForReadySession
-  ├─ current/pending Session
-  └─ 无 Session 时 start({ entry: 'barcode' }) → ensure → setSession
-→ Session readyForCommands + cartWritable
+→ ScannerSessionRouter（Entry / starting / Flow 共用 bounded FIFO）
+  ├─ idle：首码触发 onScan → ensure → Registry started
+  ├─ starting：后续扫码追加到同一 FIFO
+  └─ active：Flow 扫码继续追加到同一 FIFO
+→ onStarted.bindSession(startId, ScannerSessionPort)
 → barcode.consume(eventId-scoped intent)
 ```
 
@@ -38,7 +37,7 @@ Native scanner / pubsub
 
 - Scanner adapter 优先申请 `hdl-kiosk` 扫码焦点，无法使用焦点栈时才回退 pubsub；
 - ScannerIngress 已有 eventId/LRU 去重、350ms 降级指纹去重和 payment freeze 门禁；
-- Session 级 Controller 使用真实队列长度做 5 项背压，Quick/Scale 启动期间的扫码会等待同一个 pending Session；
+- ScannerSessionRouter 使用真实未完成任务数做 5 项背压，Quick/Scale 启动期间的扫码会等待同一个 pending Session；
 - `barcode.consume` 使用 cart scope，且不设置 Operation 超时；`added` 才执行写后 cart consistency、Summary 和 receipt/fingerprint 验证，`requiresSelection` 等待 Host 选择流程；
 - Catalog transition 不再执行 prepare；支付 Operation 通过 Checkout freshness 检查复用或重建当前事实版本的 token；
 - 本地 cart/customer 写入会把 Prepared 状态标记为 `stale`，外部写入由 fingerprint/Summary/requirement 复验识别。
@@ -54,21 +53,24 @@ Native scanner / pubsub
 
 ## 3. 目标架构
 
-在 `HDLKioskContent` 层新增一个 Session 级的 `HDLKioskScannerController`，与 Entry/Workflow View 平级：
+Scanner 属于无头 Runtime 设备层，与 React Entry/Workflow View 解耦：
 
 ```text
-HDLKioskContent
-├─ Device Runtime
-├─ Session Controller
-├─ HDLKioskScannerController
+Application Runtime
+├─ Trigger / Admission / Session Registry
+├─ ScannerSessionRouter
 │  ├─ scanner focus / subscription
 │  ├─ ingress validation + dedupe
 │  ├─ bounded task queue
-│  ├─ scan policy
-│  ├─ barcode.consume dispatcher
-│  └─ result/recovery presentation state
-├─ Entry View
-└─ Workflow View
+│  ├─ startId / activation generation
+│  └─ bind/release ScannerSessionPort
+├─ ScannerSessionPort
+│  ├─ cart/payment policy
+│  ├─ navigation policy
+│  └─ barcode.consume dispatcher
+└─ React Session Controller（只订阅 Registry）
+   ├─ Entry View
+   └─ Workflow View
    ├─ Header
    ├─ current Slice
    ├─ Cart Overlay
@@ -99,7 +101,7 @@ ScanPolicyDecision
 
 ## 4. 设备所有权与生命周期
 
-- HDLKiosk active 时由 Scanner Controller 申请焦点；KeepAlive 隐藏、unmount 或 capability 消失时释放。
+- HDLKiosk active 时由 ScannerSessionRouter 申请焦点；KeepAlive 隐藏、unmount 或 capability 消失时释放。
 - 页面切换不重建订阅，Session 切换只更新扫码策略和任务归属。
 - Scanner adapter 必须成为 HDLKiosk 生命周期内唯一的物理消费者。
 - 有焦点栈时，HDLKiosk 持有焦点，会员登录等更高优先级的本地交互可暂时抢占。
@@ -116,11 +118,11 @@ Entry 收到合法商品扫码事件时：
 4. 创建 Barcode Session，并把首码任务绑定到该 `sessionEpoch`；
 5. `setSession`，由 Session Controller 完成 Actor、Operation Coordinator、Host binding 和 Projection subscription 的安装；
 6. Session Runtime 进入 `active` 并发布与 Screen 无关的 `sessionReadyForCommands`，同时由交易策略给出独立的 `sessionCartWritable`；
-7. Scanner Controller 把首码交给该 Session，串行执行 `barcode.consume`；
+7. ScannerSessionRouter 把首码交给该 Session，串行执行 `barcode.consume`；
 8. 成功后刷新 Projection/Summary；失败则留在该 Session 的当前页面展示可恢复错误，不回退到 Entry；
 9. 只有无法建立安全 Session 时才释放 claim 并返回 Entry。
 
-`sessionReadyForCommands` 是 Session Runtime 的生命周期状态，不由 Catalog 或任意 Screen 的 mount/commit 事件驱动。未来某类 Workflow 即使以 Identity、Fulfillment 或其他页面作为首屏，也不需要改 Scanner Controller。
+`sessionReadyForCommands` 是 Session Runtime 的生命周期状态，不由 Catalog 或任意 Screen 的 mount/commit 事件驱动。未来某类 Workflow 即使以 Identity、Fulfillment 或其他页面作为首屏，也不需要改 ScannerSessionRouter。
 
 这里应区分三个概念：
 
@@ -161,15 +163,17 @@ Customization 需额外识别当前主称重商品：扫描同一主商品不能
 
 ## 7. 队列、去重与背压
 
-Scanner Controller 维护真实的有限 FIFO 队列：
+ScannerSessionRouter 维护真实的有限 FIFO 队列：
 
 - 同一 Session 内最多保留建议 5 个待处理任务，running/waitingSelection 也计入占用；
 - 队列满时立即拒绝，并提示等待当前商品处理完成；
-- 不同 Session 的任务不得串用，Session epoch 变化时清空旧队列；
+- 不同 Session 的任务不得串用；启动以 startId 绑定，激活和 Session generation
+  变化时隔离旧结果；
 - 同 eventId 只接受一次；无稳定 eventId 的设备继续使用非明文 350ms fingerprint 作为降级方案；
 - cart mutation scope 串行执行，不在多个 Screen 中并行调用 `barcode.consume`；
 - 将真实 `pendingEventCount` 传入 ScannerIngress，删除固定 `0`；
-- `requiresSelection` 占用队首，完成或取消前不执行下一任务，避免选择弹层与后续扫码交叉。
+- `requiresSelection` 拒绝在选择态建立前已经排队的旧任务并结束本轮 drain；选择弹层
+  通过 Scanner focus stack 临时接管物理扫码，关闭后新扫码按正常准入重新进入队列。
 
 ## 8. 只消费商品码
 
@@ -285,7 +289,7 @@ checkoutCoordinator.ensurePrepared(currentVersion)
 
 ### Phase 1：移动所有权并支持页面内扫码（已完成）
 
-- 新建 Session 级 Scanner Controller；
+- 新建无头 ScannerSessionRouter；
 - 订阅生命周期从“仅 Entry 无 Session”改为“HDLKiosk active”；
 - 建立 scan policy、真实队列和 session epoch；
 - Quick/Scale/Barcode 的可写页面共用 `barcode.consume`；
@@ -341,6 +345,19 @@ useNativeScale（一次）
 └─ CustomizationScreen：持续读取毛重/皮重/净重/稳定态
 ```
 
-Runtime 负责连接/重连、单位与精度、measurementId、时效、阈值、边沿解锁以及毛重/皮重/净重/稳定态。Scanner 与 Scale 共用 Entry Arbiter，但进入 Session 后互不抢占业务消费权。
+Runtime 只保存 owner 发布的最新快照和递增 `sampleSequence`。断连、停止监听、读取错误、
+负重或超载会立即使当前采样失效；重连后必须收到新的 native `onChange` 帧才能重新
+启用提交。稳定读数不会因为顾客花时间选择规格而按固定秒数过期。
+
+Entry 仍允许有效正重边沿（包括正在趋稳的读数）启动 Flow；这一步不写购物车。
+Customization 必须同时满足当前连接周期已有新采样、连接并监听、状态 stable、无错误和
+正净重阈值。点击 Next 时同步读取 Runtime 最新快照并冻结点击当下重量，避免 React 旧
+render 与断连/抖动同批发生时提交旧值；捕获成功后顾客可以正常取走商品。
+
+`SkuDetailModal` 属于有员工操作的通用商品场景，继续保留 Manual 和编辑态冻结快照；
+但启动实时 Auto 后同样只有 `liveData + listening + connected + stable` 才输出
+`is_valid=true`。两处共享安全原则，不强行共享不同的业务交互策略。
+
+Scanner 与 Scale 共用 Entry Arbiter，但进入 Session 后互不抢占业务消费权。
 
 `CustomizationScreen` 只维护称重和 options 草稿；点击 Next 后才由 `product.syncPrimaryWeightedProduct` 交给 OS 加购。最终金额、订单行和 Summary 始终以 Host Projection 为准。

package/lib/components/HDLKiosk/docs/05-/344/272/244/346/230/223/345/256/211/345/205/250.md

@@ -77,6 +77,8 @@ Prepare 检查：
 
 “We are checking your order” 表示支付或副作用最终结果无法确认，不是普通 loading。页面必须展示 trace reference，不能提供再次支付按钮。
 
+硬阻断只保留给 P0 副作用：支付可能已派发/扣款、支付最终化无法确认，或 reset 可能部分完成。购物车、会员、履约、定制和 checkout 派发前的短暂不稳定停留当前页、显示 reference 并允许重试，不再将整个 Workflow 转为 blocked。
+
 ## 6. 会话边界与未来扩展
 
 当前 Session、Coordinator Epoch、Prepare Token 和 Checkout Safety 都是页面生命周期内状态。刷新页面不会恢复原 Workflow 节点，也不会用浏览器存储推断支付结果。