# ADR-0004：桌面端与本地能力边界

- **状态**：已接受
- **日期**：2026-09-22
- **决策人**：技术负责人
- **相关**：任务表 A0.5（决策 D4）；设计文档《架构设计》第 7 节

## 背景

工厂现场用的是 Windows PC，部分机器离线。桌面端要承载界面，还要做打印、扫码、文件访问这类本地能力。平台服务可以集中部署在内网，也可以与客户端同机部署。

## 选项

| 选项 | 做法 | 代价 | 不选的理由 |
| --- | --- | --- | --- |
| A Electron | 自带 Node 与 Chromium | 体积 150MB 起 | 选定 |
| B Tauri v2 | 系统 WebView，体积 10–20MB | 无 Node 运行时，主进程逻辑要用 Rust 重写；依赖系统 WebView2 | 老机器可能缺 WebView2；重写 sidecar 与离线升级成本高 |
| C 纯浏览器 / PWA | 不装客户端 | 最省 | 没有本地设备能力与离线能力 |

## 结论

首版选 Electron，不投入 Tauri 评估。理由是工厂离线 PC 不必赌系统里有 WebView2，且离线升级、进程守护、单实例这些事都有成熟做法。等包体或内存成为硬指标时再评估 Tauri。

桌面端边界：

| 边界 | 说明 |
| --- | --- |
| 不直连 Provider | 所有业务调用走平台 API，桌面端只是入口 |
| 不持有业务凭据 | 凭据只存在平台凭据代理，本地不落长期密钥 |
| 本地 runner 只做本地事 | 打印、扫码、文件、设备采集可以本地做；业务写操作仍要过 Core |
| 离线只缓存不越权 | 断网时排队与重试，恢复后仍要过策略与确认 |
| 授权沿用现有方式 | 授权码 + 设备绑定。这是既定的商务与运维约定，不在技术选型范围内 |

## 影响

- **对代码**：`client/desktop/`（main / preload / sidecar / updater）；sidecar 的语义从"拉 Python 服务"改为"拉起引擎中立的平台服务"
- **对任务**：A10.5 Electron 壳与本地守护、A10.6 离线升级与回滚
- **对文档**：设计文档《架构设计》第 7 节
- **不这么做的后果**：选 Tauri 会把 sidecar 编排与离线升级重写成 Rust，工期显著增加，而离线机缺少 WebView2 的风险仍要靠额外方案兜

## 遗留

设备身份的签发方式（自签证书还是接入现有 PKI）待 A4 身份模块设计时定。