# FOR_AI.md — 给后续 AI 的操作手册

你正在维护 **莆阳打印组件（PrintComponent）**，当前宿主约 **v1.6.29**。  
**先读本文件 + [manifest.json](./manifest.json)，再改代码或发版。**

线上权威目录：https://py99999.com/print-component/dev/  
源码快照：https://py99999.com/print-component/dev/source.zip （解压树 `source/`）

## 0. 阅读顺序（必遵）

1. 本文件（边界与禁令）
2. [ARCHITECTURE.md](./ARCHITECTURE.md)（运行时与数据模型）
3. [CODEMAP.md](./CODEMAP.md)（改哪里）
4. 按任务再读 [API.md](./API.md) / [DESIGN.md](./DESIGN.md) / [UPDATE.md](./UPDATE.md)
5. 需要落地实现时打开 `source/` 或本机仓库对应文件

## 1. 产品是什么

Windows 本地打印宿主（.NET 8 WPF）：

- UI 对标菜鸟打印组件风格
- 兼容 LABEL MATRIX（探测/导入 QDF 字段，**不内嵌** LM 商业 EXE）
- 模块化多机在线更新
- 本机 HTTP API：网页 / ERP → 按 **通道** 绑定不同打印机与模版
- 双设计器：WPF 可视化 + 本机/线上 `designer.html`

官网下载：https://py99999.com/print-component/

## 2. 代码在哪

| 环境 | 路径 |
|------|------|
| 开发机（主） | `D:\源码\LABEL MATRIX 条形码标签软件\` |
| 线上源码快照 | `/www/wwwroot/py99999/print-component/dev/source/` 或 `source.zip` |
| AI/开发文档源 | 仓库 `web/print-component/dev/`（编辑后 `deploy-dev-docs.ps1`） |
| 官网静态站 | `/www/wwwroot/py99999/` |
| 更新服务 | `/opt/print-component-update` |

相关但独立：`D:\源码\官网\`（官网 HTML，非本解决方案）。

## 3. 解决方案结构

```
PrintComponent.sln
src/
  PrintComponent/                 # WPF 宿主：主窗、API配置、设计器、本机 API
  PrintComponent.Abstractions/     # 契约、DTO
  PrintComponent.Update/          # 模块加载、更新客户端
  PrintComponent.UpdateServer/     # 更新中心（Linux）
  Modules/
    PrintComponent.Modules.Printing/     # GDI 渲染、打印机、纸张
    PrintComponent.Modules.LabelMatrix/  # QDF 探测与导入
    PrintComponent.Modules.CustomArea/
tools/  pack-release / deploy-release / deploy-dev-docs
web/print-component/              # 下载页 + 本目录文档源
```

模块 ID：`host` / `printing` / `labelmatrix` / `customarea`

## 4. 核心心智模型（勿回退）

```
共享模版库 Templates[]  ←——  通道 Channels[] 绑定 TemplateId
                              ↓
                         PrinterName + ApiPath
                              ↓
                         Profile（DPI/偏移/纸张，按设备名）
```

- **正式打印只认 `api-config.json` 的 Templates（JSON/text）**，不执行 QDF。
- **不推荐每机独立模版库**；多机差异 =「另存专用副本再绑本通道」。
- **禁止** `SaveAndRestart` / 设默认模版时静默把所有通道全挂同一模版。
- **禁止**内嵌 Label Matrix `lmw.exe` / HASP 保护 DLL。
- 占位符：`{{字段名}}`（支持中文），渲染见 `GdiTemplateRenderer`。

## 5. 本机运行时数据

```
%LocalAppData%\PrintComponent\
  api-config.json        # 端口/Token/Channels/Templates/Sites/ErpPull
  app-printers.json      # Profile：DPI/偏移/纸张
  update-config.json     # 默认 https://py99999.com/print-update
  erp-dedup.json         # ERP 去重
  modules\  logs\  preview\  templates\assets\
```

本地 API 默认：`http://127.0.0.1:17891/`（见 API.md）  
本机设计器（同源免 CORS）：`GET /designer` → `www/designer.html`

## 6. 怎么发版 / 同步知识

| 目标 | 命令 |
|------|------|
| 客户端功能 | 改代码 → `pack-release.ps1` → `deploy-release.ps1` |
| 模块热更 | 升模块 Version → pack → deploy |
| 下载页文案 | 改 `web/print-component/` → deploy-release 或 deploy-print-component-web |
| **AI 文档 + 源码快照** | 改 `web/print-component/dev/*` → **`deploy-dev-docs.ps1`** |

密码只用环境变量 `PY_DEPLOY_PASS`，**禁止写入仓库/文档**。

版本锚点：`App.HostVersion`、`PrintComponent.csproj`、`PrintingModule.Version`、`packaging/PrintComponent.iss`、`web/print-component/latest.json` 保持一致。

## 7. 服务器约定

| 项 | 值 |
|----|-----|
| 主机 | `42.193.144.48`（py99999.com） |
| SSH | root + `PY_DEPLOY_PASS` |
| 知识库 | `/www/wwwroot/py99999/print-component/dev/` |
| 更新反代 | `https://py99999.com/print-update` → `127.0.0.1:17890` |
| systemd | `print-update` |

## 8. 禁止事项

- 不把服务器密码、Token 默认值写进公开 Markdown/HTML
- 不 force push；不破坏生产未备份的 `index.html`
- 不假设 Node（本项目 .NET 8）
- 不内嵌 LABEL MATRIX 商业二进制
- 不静默全挂通道模版

## 9. UI 入口速查

- **API配置 → 服务**：通道行（打印机 / 绑定 / 模版下拉 / 测试 / 编辑 / 在线设计 / 另存专用）
- **API配置 → 标签模版**：模版库、挂到通道（会确认范围）
- **一键自检**：机→模版→Profile 矩阵、纸张不一致、同步纸张
- **帮助 → 检查更新**

## 10. 任务检查清单

```
[ ] 读 FOR_AI + ARCHITECTURE + CODEMAP + manifest
[ ] 确认改宿主 / 模块 / 更新中心 / 文档哪一类
[ ] 本地 dotnet build 通过
[ ] 需要上线：pack + deploy-release
[ ] 同步知识：deploy-dev-docs，更新 CHANGELOG
```