# HDLKiosk 文件导航

本文按当前代码事实说明所有权和依赖边界。详细运行模型见《01-核心运行机制》和《08-无头 Application 运行时设计》。

## 1. 固定依赖方向

```text
kernel ← app ← runtime ← ui
           ↑              ↑
         slices ───────────┘
```

- `kernel/` 是通用基础包，不认识 HDLKiosk、Host、商品、设备或 React。
- `app/` 是 HDLKiosk 业务 Application，只包含协议、流程和静态策略，可脱离 UI。
- `runtime/` 绑定 Host Port、Operation Handler 和 Trigger Adapter，产出可执行 Runtime。
- `slices/` 按 feature 并置协议定义和 React View；`app` 只允许读取其 `slice.ts` 协议出口。
- `ui/` 是 Runtime 的可选 React 适配层；`components/` 只保留跨 Slice 的共享视觉组件。

`architectureBoundary.test.ts` 会阻止 `app → runtime/UI` 和 `runtime → React/UI` 的反向依赖。

## 2. 顶层结构

```text
HDLKiosk/
├── kernel/          # 通用 Application、Workflow 和 Operation 原语
├── app/             # HDLKiosk Contracts、Manifest、Workflow、Operation Contract
├── slices/          # 各 Activity 的协议定义、View、Screen 和局部模型
├── runtime/         # Application Implementation、Host Binding、设备入口、Operation、Session
├── ui/              # React Entry、Controller、Renderer 和 Runtime hooks
├── components/      # 跨 Slice 共享的 common/shell/overlay UI
├── testing/         # FakeHost、fixture 和测试辅助
├── docs/
├── types.ts         # React 展示层公共类型
├── utils.ts         # 跨 View 纯方法
├── index.tsx
└── index.less
```

## 3. 各层所有权

### `kernel/`：通用基础包

| 位置           | 职责                                                                            |
| -------------- | ------------------------------------------------------------------------------- |
| `application/` | `defineSlice`、`defineApplication`、Trigger 路由、Admission 和 Session Registry |
| `workflow/`    | Compiler、Actor、Transition 原语                                                |
| `operations/`  | 排队、冲突域、timeout 和 epoch 原语                                             |

`kernel/application` 是可提取的通用 API，不是 HDLKiosk 业务 App。

### `app/`：HDLKiosk 业务 Application

| 位置            | 职责                                                   |
| --------------- | ------------------------------------------------------ |
| `manifest.ts`   | 产出 `hdlKioskApplication` Definition                  |
| `contracts/`    | Application 与 Host/Runtime 之间的稳定业务端口         |
| `operations.ts` | Operation ID、输入输出、冲突域和重试语义；不含 Handler |
| `workflow/`     | Quick、Barcode、Scale 拓扑与业务策略                   |

Activity、Command、Resolution、Surface 和 Acceptance 协议位于平级的
`slices/*/slice.ts`。协议与 UI 同 feature 并置，但 Application 不能导入其中的 React 文件。

`app/` 不可导入 Host 实现、设备订阅、Runtime Handler 或 React。

### `runtime/`：具体依赖与无头运行时

| 位置               | 职责                                                                       |
| ------------------ | -------------------------------------------------------------------------- |
| `application.ts`   | 固定 HDLKiosk Implementation，导出可通过 `bind()` 创建 Runtime 的 Application |
| `triggers.ts`      | 直接订阅 Scanner/Scale Port，提交 Trigger Occurrence                       |
| `devices/`         | Scanner/Scale Ingress、去重和无 UI Scale Store                             |
| `operations/`      | 购物车、支付、身份、履约和会话的 Host Handler                              |
| `session/`         | Workflow Session、Actor、Coordinator、Context、Projection 和 Lifecycle 组合 |

纯 JavaScript 可直接运行：

```ts
const runtime = hdlKioskApplication.bind({ host, config });
runtime.subscribe(() => consume(runtime.getSnapshot()));
runtime.activate();
const quick = await runtime.start('quick');
```

### `ui/` 与 `components/`：可选 React 消费层

| 位置                                             | 职责                                                           |
| ------------------------------------------------ | -------------------------------------------------------------- |
| `ui/controllers/useHDLKioskSessionController.ts` | 创建 Runtime、用 `useSyncExternalStore` 投影 snapshot          |
| `ui/controllers/useHDLKioskActionDispatcher.ts`  | 将 UI Resolution/Navigation/Command 适配到当前 Session             |
| `ui/controllers/useHDLKioskExitController.ts`    | 将 Runtime Exit Challenge 适配为确认与取消动作                 |
| `runtime/devices/scannerSessionRouter.ts`        | 唯一持有 Scanner；统一路由 Entry、启动中和 Flow 扫码           |
| `runtime/devices/scannerSessionPort.ts`          | 将当前 Workflow Session 的可写策略与扫码 Command 适配给 Router |
| `ui/controllers/useHDLKioskDeviceController.ts`  | 仅投影秤连接状态，不启动 Workflow                              |
| `ui/views.ts` / `ui/ScreenRenderer.tsx`          | Activity → View 注册和渲染                                     |
| `ui/entry/`                                      | Workflow 外手动入口 UI                                         |
| `slices/<name>/`                                 | 同一 feature 内的 `slice.ts` 协议与 View/Screen/Dialog         |
| `components/`                                    | 跨 feature 的 common、shell 和 overlays                        |

Slice 协议和 UI 分层，但保持相同 feature 名字和局部目录形状，降低定义与展示间的定位成本。

## 4. Trigger 所有权

```text
Host device event
  → runtime/triggers.ts
  → Kernel Runtime occurrence
  → trigger + channel 唯一匹配 Workflow
  → Admission / idempotency
  → Application Session lifecycle
  → Session Registry started event
  → React 或纯 JS 消费者
```

- Quick 未声明 `start`，因此默认 manual。
- Barcode/Scale 只能由 automatic Trigger 启动，手动调用 Workflow Handle 会被拒绝。
- 当前一个 automatic Trigger 只能绑定一个 Workflow，重复绑定 fail-closed。
- Channel 由 Runtime Adapter 赋予，不要求物理秤事件自带 Channel。
- 流程内扫码是 Session Command，不再进入 Workflow 启动 API。
- 当前不实现多 Workflow 广播和嵌套调用；`parentSessionId` 只保留因果关联字段。

## 5. 常见修改定位

| 需求                 | 首要位置                                                   |
| -------------------- | ---------------------------------------------------------- |
| 调整流程顺序         | `app/manifest.ts`                                          |
| 新增 Activity 协议   | `slices/<name>/slice.ts`                                   |
| 新增 Activity UI     | `slices/<name>/` + `ui/views.ts`                           |
| 新增 Operation 协议  | `app/operations.ts` + Slice perform/command                |
| 实现 Operation       | `runtime/operations/registry.ts` + 对应 Handler            |
| 新增自动入口         | `app/manifest.ts` + Workflow start + `runtime/triggers.ts` |
| 修改 React 消费方式  | `ui/`                                                      |
| 修改 BigSale/OS 对接 | `components/bigSale/templates/HDLKiosk/adapter/`           |

## 6. 文件头注释

业务、运行时和适配层文件应说明文件角色、运行机制和边界。注释记录当前设计事实，不记录迁移历史。