# HDLKiosk 文档导航

> 当前阶段：架构骨架已完成，后续重点是正式 Host 业务契约、真实设备/支付验收和 UI 还原。  
> 更新日期：2026-08-23

## 1. 从哪里开始

首次通览按以下顺序阅读：

1. [架构设计.md](./架构设计.md)：理解独立物料边界、依赖方向和全局不变量；
2. [00-文件导航.md](./00-文件导航.md)：快速查找每个目录和关键文件的角色、调用方与修改落点；
3. [01-核心运行机制.md](./01-核心运行机制.md)：沿 Activity Contract、Resolution/Navigation Actor、Command Coordinator、Controller 和 Screen 的真实调用链理解 Core；
4. [02-Host 适配与业务数据.md](./02-Host适配与业务数据.md)：理解 BigSale 兼容层每个文件解决的问题、字段映射和当前缺口；
5. [实施进度.md](./实施进度.md)：确认当前已完成能力、临时策略和已知风险；
6. [03-业务流程与交互规则.md](./03-业务流程与交互规则.md)：理解三入口和当前权威流程；
7. [07-后续工作.md](./07-后续工作.md)：选择下一项业务或 UI 工作。

理解或修改无头 Application Runtime 时，阅读 [08-无头 Application 运行时设计.md](./08-无头Application运行时重构设计.md)。该文档定义 Application、Runtime、Session、Trigger 和 Presentation 的稳定边界。

HDLKiosk 的具体类型、文件职责和验收矩阵见 [10-Application Runtime 自顶向下设计.md](./10-ApplicationRuntime自顶向下设计.md)。

按任务类型阅读：

| 任务                                      | 必读文档                                               |
| ----------------------------------------- | ------------------------------------------------------ |
| 修改 Activity、Workflow、Command、运行时  | `架构设计`、`01-核心运行机制`、`03-业务流程与交互规则` |
| 接 BigSale/OS API、商品、会员、优惠或支付 | `02-Host适配与业务数据`、`05-交易安全`                 |
| 修改扫码、称重或入口自动触发              | `04-设备与称重`、`03-业务流程与交互规则`               |
| 还原 UI、文案和交互                       | `03-业务流程与交互规则`、原型 `kiosk/app/page.tsx`     |
| 编写测试或准备实机验收                    | `06-测试与验收`、`07-后续工作`                         |
| 实现无头 Application、Trigger 或 Runtime  | `08-无头 Application 运行时设计`、`01-核心运行机制` |
| 设计 Runtime 创建与绑定                   | `10-Application Runtime 自顶向下设计`、`08-无头 Application 运行时设计` |

## 2. 常驻文档

| 文档                                                    | 维护内容                                                                       | 不维护的内容           |
| ------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------- |
| [00-文件导航.md](./00-文件导航.md)                      | 目录职责、关键文件角色、调用关系和常见修改落点                                 | 详细业务顺序和字段定义 |
| [架构设计.md](./架构设计.md)                            | 边界、总图、状态所有权、不变量                                                 | 实施流水账             |
| [01-核心运行机制.md](./01-核心运行机制.md)              | Core 代码地图、Activity/Resolution/Navigation/Command/Actor/Controller 调用链、修改落点 | BigSale 原始字段 |
| [02-Host 适配与业务数据.md](./02-Host适配与业务数据.md) | BigSale 兼容层代码地图、痛点与形式、Projection/Command/商品/设备映射、真实缺口 | Screen 导航            |
| [03-业务流程与交互规则.md](./03-业务流程与交互规则.md)  | 三入口、会员、主商品提交、页面行为、UI 基线                                | OS 内部实现            |
| [04-设备与称重.md](./04-设备与称重.md)                  | Scanner、任意页面扫码方案、Scale、事件仲裁和称重商品                           | 支付实现细节           |
| [05-交易安全.md](./05-交易安全.md)                      | Cart 一致性、Checkout、Payment、Reset、错误处理                                | 视觉细节               |
| [06-测试与验收.md](./06-测试与验收.md)                  | 自动测试层级、异常矩阵、实机门禁                                               | 项目排期               |
| [07-后续工作.md](./07-后续工作.md)                      | 未完成业务、UI 和生产化优先级                                                  | 已完成历史             |
| [实施进度.md](./实施进度.md)                            | 当前事实快照、临时开关、最近关键变更                                           | 完整设计论证           |
| [08-无头Application运行时重构设计.md](./08-无头Application运行时重构设计.md) | Application/Runtime/Session、Trigger Channel、Contract/Binding 的稳定边界 | 具体业务流程 |
| [10-ApplicationRuntime自顶向下设计.md](./10-ApplicationRuntime自顶向下设计.md) | Application define/implement/bind/start、启动事务、设备协作与验收标准 | 业务页面与视觉实现 |
| [11-二期抽象准备实施计划.md](./11-二期抽象准备实施计划.md) | 不提前通用化 Sales Port 前提下的 Runtime 拆分、Host 契约、数据边界、Operation 门禁、流程快照和跨业务依赖规则 | Kernel 物理迁移与跨业务 Commerce DTO 设计 |

## 3. 事实优先级

发生冲突时按以下顺序处理：

```text
当前代码与测试
> 架构设计和对应主题文档
> 实施进度
> 原型交互意图
> 历史聊天或旧设计稿
```

原型只定义业务意图和视觉参考，不能作为商品、金额、会员、优惠、重量、订单或支付事实源。

## 4. 文档维护规则

- 架构边界或全局不变量改变：更新 `架构设计.md`；
- 某主题契约改变：只更新对应主题文档；
- 完成一项业务切片：更新 `实施进度.md` 和 `07-后续工作.md`；
- Workflow 节点顺序改变：先更新 `03-业务流程与交互规则.md`，再改代码；
- 新增临时兼容策略：必须在 `实施进度.md` 登记开关、影响、退出条件和风险；
- 已完成的分步清单、一次性论证和测试流水不再新建独立文档；
- 文档不复制大段类型定义，详细字段以 `components/HDLKiosk/app/contracts` 为准。