# 架构说明 ARCHITECTURE.md

当前宿主：**v1.6.29**。配合 [FOR_AI.md](./FOR_AI.md)、[CODEMAP.md](./CODEMAP.md)。

## 技术选型

- .NET 8 / WPF（无 Electron / 无 Node 运行时依赖）
- 模块接口：`PrintComponent.Abstractions`
- 更新协议：HTTP JSON + zip（UpdateServer）
- 本机网页打印：`HttpListener`，默认端口 **17891**
- 标签渲染：GDI（`GdiTemplateRenderer`），JSON schemaVersion=1

## 运行时关系

```
[网页 / ERP / 在线设计器]
    |  HTTP  X-Print-Token
    v
[LocalPrintApiServer]  ←── 读 api-config.json / Profiles
    |  按 Channel.ApiPath 选打印机 + TemplateId
    v
[Printing 模块 · GDI] ----> [本机打印机]
    ^
[宿主 WPF]  UI / 托盘 / 一键自检 / 设计器
    |
    v 心跳 / 检查更新
[UpdateServer]  https://py99999.com/print-update
```

## 关键项目职责

| 项目 | 职责 |
|------|------|
| PrintComponent | 主窗口、API配置、Diagnostics、TemplateDesigner、托管 `/designer`、启动 API |
| Abstractions | IPrinterService、ITemplateRenderer、DTO、ModuleIds |
| Update | ModuleLoader、LocalModuleRegistry、ModularUpdateClient |
| UpdateServer | manifest、packages、多机心跳 |
| Modules.Printing | 打印机、队列、纸张 Profile、GDI 渲染 |
| Modules.LabelMatrix | QDF 字段探测、导入为 JSON 模版（不执行 QDF） |
| Modules.CustomArea | 客户自定义区 UI |

## 数据模型（真相源）

### api-config.json

| 字段 | 含义 |
|------|------|
| Enabled / Port / Token / AllowCorsAll | API 开关与鉴权 |
| Channels[] | ApiPath + PrinterName + TemplateId + Bound |
| Templates[] | Id/Name/Type/Content/Revision（text 或 json） |
| Sites[] | Origin / 默认通道（可选） |
| ErpPull | ERP 轮询 URL、间隔、目标通道 |

### app-printers.json（Profile）

按 **打印机设备名**：DPI、偏移、旋转、**纸张宽高 mm**。  
纸张应与 JSON 模版 `widthMm/heightMm` 一致（自检可「同步纸张」）。

### 路由优先级（打印）

URL 路径通道 → body `channel` → 站点默认 → 请求内 `printer` 覆盖。

## 多机 × 模版原则

1. **模版库全局共享**，通道各自 `TemplateId`
2. 多机布局不同 → 通道「另存专用」克隆后再改
3. 「挂到通道」必须确认：仅当前 / 全部；禁止静默全挂
4. 设计/预览/试打应带打印机上下文（通道机 Profile）

## 设计器双路径

| 路径 | 说明 |
|------|------|
| WPF `TemplateDesignerWindow` | 桌面拖拽、图层、字体；试打走通道机 |
| `www/designer.html` + `GET /designer` | 本机同源；亦可线上 `dev/designer.html`（需 CORS） |
| API | templates CRUD、preview（可带 printer/channel）、PATCH channel、channel test |

## UI 入口

- **API配置**：服务 / ERP拉取 / 网站 / 标签模版
- **一键自检**：BindingMatrix、纸张不一致、一键修复、同步纸张
- **模块与更新** / **帮助 → 检查更新**
- 关闭主窗 → 托盘；真退出走托盘或「工具→退出」

## 发版产物流向

```
pack-release.ps1  → publish/release/（Setup zip + packages + manifest）
deploy-release.ps1 → 官网下载 + /opt/print-component-update
deploy-dev-docs.ps1 → /www/wwwroot/py99999/print-component/dev/（文档+source.zip）
```