# HDLKiosk 业务流程与交互规则

> 本文是三入口、Workflow 节点顺序和跨页面业务规则的唯一文档。

## 1. 边界

HDLKiosk 不定义、展示或校验过敏流程。顾客在 OS 加购中可能看到的业务弹窗由 OS 自行判断和完成，HDLKiosk 只消费最终加购结果。

Customization 中的称重、规格和必选项在点击 Next 前都是页面本地草稿：

- 重量或 options 变化不调用 Host/OS；
- 不维护本地订单副本，已确认购物车和金额仍只来自 Host Projection；
- Next 将点击当下的完整草稿作为 Resolution Acceptance Operation 提交给 OS；
- OS 加购成功并通过 writer receipt/Projection 验证后，Actor 才进入下一步；
- `failed`/`cancelled` 留在 Customization 允许重试，`partial`/`unknown` 按交易安全规则阻断；
- 返回编辑已有主商品时携带 `existingLineId`，Host 必须更新原行，不得重复新增。

## 2. Entry

Entry 同时展示 Quick Order、Scan Product Barcode 和 Place Item on Scale。Entry 只负责能力状态和入口仲裁，一次只有一个入口可以 claim session。

## 3. Quick Order

```text
Entry → Identity → Customization → Catalog → Fulfillment
      → Payment Method / Payment Completed → Entry
```

- Quick 的 Identity occurrence 将 `complete | omit` 配置为 `bypass`。登录或 Omit 成功后，该 Step 在本会话不再进入，也不写入 Back 页面历史。当没有更早的已访问页面时，Actor 返回 Flow Boundary，Runtime 使用当前 Workflow 的 `exitPolicy` 创建 `discardActiveOrder` Challenge。确认后验证式清理订单并返回 Entry，取消则留在当前页。
- Fulfillment 统一位于 Payment 之前确认堂食/外带。
- Customization 只在稳定正净重且必选 options 完整时启用 Next。
- “I don't need Malatang” 移除已有主商品并进入 Catalog；Customization 的 `omit` 使用 `reenter`，因此 Back 和主商品编辑入口仍可返回。
- Next 调用 `product.syncPrimaryWeightedProduct`；成功后进入 Catalog，失败不跳转。
- Catalog Back 返回 Customization。
- Cart Overlay 中的卡券和中途登录可能改变金额，Checkout Prepare 必须在这些写入稳定后执行。
- EFTPOS 或店员付款只有在 Host 确认 `payment.succeeded` 后才切换为 Checkout Screen 内的支付成功展示。
- 成功展示复用 `PaymentResultToastV2`，优先显示 OS 本地订单的 `shop_full_order_number`；本地为空时异步查询只读订单详情，查询期间显示生成中，不得从 payment result 或内部 `orderId` 推断。
- Host 明确确认支付成功并进入 Payment Completed 后立即清空购物车、客户和履约工作区，同时保留支付结果与已完成订单快照供成功页展示；成功页沿用旧 Kiosk 的 10 秒返回首页能力，本地缺少取餐码时，订单详情异步加载的时间不计入倒计时，请求结束后才从完整 10 秒开始。明确取消或失败留在支付页并给出可重试反馈，unknown 继续阻断重复支付和订单写入，但阻断页允许显式 reset 返回入口。
- Payment Method 提供“重新开始订单”，仅在 payment idle/failed 时可用；二次确认后复用 `session.reset` 安全清空。pending 时继续等待外部终态，unknown 则进入带恢复入口的安全阻断页。

## 4. Barcode

```text
Entry -- ensure session --> CatalogWithPrimaryProductPrompt
Session readyForCommands -- barcode.consume --> current activity
Catalog Checkout 且缺主商品
  ├─ No  → Payment Method（不展示 Fulfillment）
  └─ Yes → Fulfillment → Customization -- Next/OS add succeeded --> Catalog
Catalog / Cart Overlay → Fulfillment → Payment Method / Payment Completed
```

入口扫码先建立并激活 Barcode Session，在 Session Runtime 进入 `readyForCommands` 且购物车可写后消费首码；当前 Barcode 首屏为 Catalog 只是 Workflow 配置，不是扫码控制器依赖。Prompt 是 Catalog Activity 内部 Dialog，不是 Workflow 节点。Yes 先确认堂食/外带，再复用同一 Customization；主商品加购成功后返回 Catalog。No 将本单标记为不要求 Fulfillment，Cart Overlay/Checkout 也不得把顾客补送到堂食/外带页。

Barcode 首次扫码只依赖 scanner 和 session 能力；秤、主商品查询或 Customization 能力未就绪时，仍应允许已成功扫码的普通商品进入 Catalog。

Quick、Barcode 和 Scale Session 中，只要购物车仍可写，Identity、Fulfillment、Customization、Catalog 和 Cart Overlay 都允许扫码加购且不改变当前节点。支付尚未 dispatch 时也允许扫码，并使旧 Checkout Prepared 状态失效；真正发起任意支付方式前由 Checkout Coordinator 对当前订单版本统一执行 `ensurePrepared`。EFTPOS 执行中、店员支付授权 Command 执行中、支付 pending/unknown/succeeded、Payment Completed、blocked 和 resetting 阶段拒绝扫码写入。完整策略见 [04-设备与称重.md](./04-设备与称重.md)。

## 5. Scale

```text
Entry -- valid scale edge --> Fulfillment → Customization
Customization -- Next/OS add succeeded --> Catalog
Catalog → Fulfillment → Payment Method / Payment Completed
```

Entry 消费第一个有效重量边沿后启动以 Fulfillment 为首节点的 session。页面持续读取顶层 Scale Runtime，但不因后续重量变化自动写购物车。称重行不能使用普通 `+1` 表示加 1kg。

## 6. 会员中途插入

Identity 的 Omit 只表示当前以 Guest 继续。Shell 可在本地策略允许的页面执行 `identity.sync`。登录、Customer 写入、重报价和 Projection 验证成功后仍留在原节点；`partial`/`unknown` 不得带着未确认价格继续。

## 7. UI 和修改规则

- HDLKiosk 以 1080×1920 为固定设计坐标；设备适配由主应用对完整模板统一缩放，组件内部不得使用 `vw`、`vh`、`clamp()` 或尺寸型媒体查询二次适配。
- 视觉尺寸先以生产中的 Login2、SaleDetail 商品卡、优惠卡券和小计模块为锚点，综合字体、行高、控件高度、间距和组件尺寸反推；HDLKiosk 只控制外部模块的承载容器，不覆盖其内部尺寸标准。
- 尺寸校准以上线环境的实际渲染值反推：当 72px 在目标倍率下实测为 100px，而原型目标为 108px 时，当前自有视觉值统一乘以 `108 / 100 = 1.08`；外部生产组件不参与这一次修正。
- Screen 不得直接 import BigSale/SalesSDK，也不本地计算最终金额。
- Screen 内部写操作使用 Screen Command；Resolution 成立所需的写操作使用 Acceptance Operation。
- `product.syncPrimaryWeightedProduct` 属于 Customization `complete` 的 Acceptance Operation，不是输入变化时的 Screen Command。
- Shell 的购物车、金额和 Drawer 只消费 Host 已确认 Projection。
- 调整节点顺序时同步更新 Workflow Definition、compiler/definition/actor/Screen 测试和实施进度。