# M3 设计文档：一键编译发布（客户版 exe + 光盘结构）+ 正式版

> **历史设计文档（2026-06 拟定）**。实施后的最终状态（2026.08 发布管线/三份产物/站点删除重试等）、与设计的偏差、进度与踩坑以 **项目总览.md** 为准（同目录）。本文件仅作设计参考。

## 1. M3 目标与验收标准

维护入口中点击"编译发布"→ 生成客户版单文件 exe（目录数据内置、无维护入口），可选生成光盘/USB 目录结构；多语言完整；交付两份手册——正式版。

**验收标准：**
- 编译发布产出的客户版 exe 在**纯净 Win10/11 虚拟机**（无 .NET 运行时、断网）上双击即用，完成选型 → 下载 STEP 全流程
- 客户版 exe 中不存在维护入口（无 --admin 响应、无维护页、无 Builder 代码路径）
- 光盘/USB 目录结构生成正确（autorun.inf + exe + 外置 .opc），增量更新包（仅换 .opc）验证可用
- 中/英全量文案无缺失 key；用户手册 + 维护手册交付
- 数据包版本校验：客户端对过旧/过新的 .opc 给出明确提示

## 2. 发布流水线

```
Builder 生成 .opc ──→ 校验器（通过才可发布）
        │
        ├─ 路径 A：单文件客户版（默认）
        │     .opc 作为嵌入资源 → dotnet publish（self-contained, single-file,
        │     Release, trimmed, CUSTOMER_BUILD 编译符号）→ OuniboCatalog.exe
        │
        └─ 路径 B：目录版（光盘/USB 用）
              exe（同 CUSTOMER_BUILD 编译，不含资源）+ 外置 catalog.opc
              → 生成发布目录结构（见 §3）
```

### 2.1 单文件实现方案

- 一份代码同时支持 A/B：启动时 `先找 exe 旁 catalog.opc（B）→ 找不到读嵌入资源（A）→ 都没有则提示"数据包缺失"`；A 由 Packager 把 .opc 写入资源后重新编译
- 实现细节：Packager 维护一个预置的"客户版 csproj"，把 .opc 复制为 EmbeddedResource，调用 `dotnet publish` 自动编译；发布机需装 .NET SDK
- `CUSTOMER_BUILD` 编译符号：剔除 AdminService、维护页、Builder、校验器、Packager 自身（`#if !CUSTOMER_BUILD`），确保客户版干净且更小
- self-contained + single-file + trimmed：客户机无需装 .NET；注意 Helix Toolkit 与 WPF 的 trimming 兼容性，若有反射问题则关 trim 或用 RDXml 声明
- exe 图标（欧霓博 logo）、版本资源（FileVersion = 目录版本）、产品名

### 2.2 代码签名（可选但建议）

- 购买代码签名证书（OV 级足够），发布机集成签名步骤；未签名 exe 会被 SmartScreen 拦截，客户体验差——**正式发布前建议完成**

## 3. 光盘/USB 发布目录结构（对标 Airtac 包形态）

```
OuniboCatalog_2026.06/
├── autorun.inf                 # 指向 OuniboCatalog.exe
├── OuniboCatalog.exe           # 客户版（CUSTOMER_BUILD，无嵌入数据）
├── catalog.opc                 # 数据包（外置，增量更新只换此文件）
├── icon.ico
└── README_zh.txt / README_en.txt   # 使用说明（含各 CAD 导入 STEP 的简略指引）
```

- 增量更新包 = 新版 `catalog.opc`（校验器通过后由发布流水线产出），客户覆盖即升级；单文件版客户升级 = 重新下发 exe
- autorun.inf 在 Win10/11 默认禁用自动播放——README 中说明"双击 exe 运行"，不依赖 autorun

## 4. 版本与兼容

- `catalog_meta`：`catalog_version`（目录内容版本）+ `schema_version`（格式版本）
- 客户端加载 .opc 时校验：schema_version 高于软件支持 → 提示"请升级软件"；低于已知最低版本 → 提示"数据包过旧"；均拒绝加载
- 版本号规则：`年.月`（如 2026.06）+ 补丁位（2026.06.1），显示在关于页

## 5. 多语言完善

- 全部文案入资源文件（zh-CN / en-US），含错误提示、规则解释、校验报告
- 构建期脚本扫描缺失 key（界面启动时兜底显示 key 本身，测试阶段开警告）
- 语言选择：首次启动跟随系统 → 设置可切换（沿用 M1 设计）

## 6. 文档（交付物）

- **用户手册**：安装/运行、选型流程、STEP 下载与各主流 CAD 导入指引、批量下载、FAQ
- **维护手册**：数据准备规范（Excel 模板格式、STEP 文件要求、命名约定）、Builder 五步操作、校验与常见错误处理、发布流程（编译发布操作步骤、增量更新流程）
- 两份手册中/英双语

## 7. 验收测试清单

| 场景 | 预期 |
|---|---|
| 纯净 Win10/11 虚拟机，双击客户版 exe | 无需安装 .NET，直接运行 |
| 断网运行 | 全流程可用 |
| 客户版 --admin 启动 | 无维护入口响应 |
| 搜索/选型（5 万变体规模抽测） | 启动 <5s，过滤/搜索 <1s |
| 光盘目录版：仅替换 catalog.opc 升级 | 新版数据生效，版本号正确显示 |
| 把 schema_version 改大后加载 | 明确提示"请升级软件"，不崩溃 |
| 校验器存在 ERROR 时点编译发布 | 被拦截并给出报告 |
| STEP 下载后在 SolidWorks/NX 打开 | 尺寸正确 |

## 8. 任务清单（建议实现顺序）

1. Packager：路径 B（目录版）+ 增量更新包产出
2. `CUSTOMER_BUILD` 编译符号改造 + 单文件 self-contained 发布（路径 A）
3. 版本校验与关于页
4. 多语言补齐 + 缺失 key 检查
5. 图标/版本资源/签名流程
6. 两份手册编写
7. 虚拟机验收测试全项走查

## 9. 后续（M4 可选扩展，不在本次范围）

Teamcenter 集成（SOA 检入、映射 JSON）——仅当有客户明确需要时启动。
