首次提交: OnebotCatalog 项目代码与文档（含 NX 按需生成服务二期、后台、一键启动）

欧霓博_目录软件_M3设计文档.md

@@ -0,0 +1,99 @@
+# 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）——仅当有客户明确需要时启动。