# M1 设计文档：核心闭环（浏览 + 选型 + 3D 预览 + STEP 下载）

> **历史设计文档（2026-06 拟定）**。实施后的最终状态、与设计的偏差、进度与踩坑以 **项目总览.md** 为准（同目录）。本文件仅作设计参考。

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

用户（欧霓博维护人员）打开维护版软件 → 加载一个 .opc 数据包 → 客户视角完成一个气缸系列"选型 → 下载 STEP"全流程。

**验收标准：**
- 打开示例数据包，目录树显示分类 → 系列 → 型号
- 选择缸径/行程/磁石等参数，过滤实时生效，参数表与 3D 预览联动
- 点击下载，得到命名正确的 STEP 文件（如 `ACQ32x50S.step`），在 SolidWorks/NX 中打开尺寸正确
- 中英界面切换可用
- `--admin` 启动 + 密码 → 维护页可加载/替换数据包、查看包信息

## 2. 三个关键架构决策

### 决策 1：数据包形态 —— SQLite 元数据 + 资源目录，zip 单文件分发

- `.opc` = zip 包，内含：`catalog.sqlite`（元数据/参数/规则/全文索引）+ `assets/`（STEP、预览网格、图片、PDF）+ `manifest.json`（schema 版本、目录名、语言列表）
- 客户版 exe 把 .opc 作为嵌入资源，首次运行时解压到 `%LOCALAPPDATA%\OuniboCatalog\`；维护版支持加载外部 .opc（便于替换/更新）
- 理由：SQLite 单文件利于嵌入 exe 与增量更新；资源外置避免把几百 MB 的 STEP 塞进数据库 blob

### 决策 2：参数化变体策略 —— M1 用"预生成变体"，schema 预留运行时建模

- M1：Builder/脚本按参数表**批量预生成**所有型号组合的 STEP（如缸径 8 种 × 行程 30 种 = 240 个文件），选型只是命中对应文件。简单、可靠、无运行时几何计算
- 预留扩展点：`variants.geometry_source ∈ {prebuilt, parametric}`；后续行程连续化时，`parametric` 模式在 Builder 端做参数化重建（气动元件形状规则，适合特征化建模），运行时仍只读成品 STEP
- 约束：M1 要求行程等参数为**离散枚举值**；连续行程列入后续里程碑

### 决策 3：3D 预览 —— 编译期转网格，运行时轻渲染

- Builder 打包时把每个 STEP 转成预览网格（glTF/自定义二进制网格，assimp 或 OCCT 完成转换），运行时用 **Helix Toolkit (WPF)** 渲染
- 理由：客户 exe 轻（不含 OCCT 运行时）、启动快、渲染流畅；STEP 原文件仅供下载，不进渲染管线
- 备选（后续增强）：运行时用 OCCT 直接读 STEP 渲染（精度高但增重）

## 3. .opc 数据包 schema（catalog.sqlite）

```sql
-- 元信息
catalog_meta(id, schema_version, catalog_name, catalog_version,
             default_lang, langs_json, build_time)

-- 目录树
categories(id PK, parent_id, sort, code)
series(id PK, category_id FK, code, sort, is_active)

-- 参数定义（每个系列一组参数）
parameters(id PK, series_id FK, code, type,   -- type: enum/number/text
           unit, sort, is_required, values_json)  -- enum 的取值/数值的范围

-- 变体（一个"型号组合"对应一行）
variants(id PK, series_id FK, model_code UNIQUE,   -- 如 ACQ32x50S
         param_values_json,                        -- {"bore":32,"stroke":50,...}
         step_path, mesh_path, preview_img_path,
         geometry_source DEFAULT 'prebuilt')

-- 选型规则（M1 支持简单约束，JSON 表达式）
rules(id PK, series_id FK, priority, expr_json)
-- expr_json 示例：{"if":{"param":"bore","op":"eq","value":32},
--                 "then":{"param":"stroke","op":"in","value":[25,50,75,100]}}

-- 附件（尺寸图/数据表/说明，按语言区分）
attachments(id PK, series_id, kind,   -- dim_drawing/datasheet/note
            lang, path, sort)

-- 翻译
translations(key PK, lang PK, text)

-- 型号编码与命名规则（series 级配置）
series_naming(id PK, series_id FK,
              code_template,     -- 如 "{SERIES}{bore}x{stroke}{MAG}"
              step_name_template -- 如 "{SERIES}{bore}x{stroke}{MAG}.step")
```

manifest.json：

```json
{
  "schema_version": "1.0",
  "catalog_name": "欧霓博气动目录",
  "catalog_version": "2026.06",
  "langs": ["zh-CN", "en-US"],
  "builder_version": "0.1.0"
}
```

## 4. 模块与接口（C# .NET 8，MVVM）

| 模块 | 职责 | M1 关键接口 |
|---|---|---|
| CatalogCore | 数据包读写、查询 | `Load(string opcPath)`；`GetCategoryTree()`；`GetSeries(id)`；`GetVariants(seriesId, filter)`；`ResolveModelCode(code)`；`GetAttachments(seriesId, kind, lang)` |
| ConfiguratorEngine | 参数过滤 + 规则求值 | `GetAvailableOptions(seriesId, currentSelections)`；`Validate(selections) → 违反的规则列表`；`GetVariant(selections)` |
| Viewer3D | 网格加载与交互 | `LoadMesh(path)`；旋转/缩放/平移；`Clear()` |
| ExportService | STEP 下载 | `Export(variantId, destDir)` → 按命名模板复制 STEP 并返回路径 |
| Localization | 多语言 | `T(key, lang)`；资源文件 zh-CN/en-US |
| AdminService | 维护入口 | `IsAdminMode(args)`；`CheckPassword`；`LoadExternalPackage(path)`；`GetPackageInfo()` |
| AppShell (WPF) | 装配以上模块 | 客户模式 / 维护模式路由 |

依赖方向：AppShell → 各模块；CatalogCore 不依赖 UI；Viewer3D 只认网格文件路径。

## 5. UI 线框

```
┌─────────────────────────────────────────────────────────────┐
│ [语言:中/EN]        欧霓博气动目录            [下载 STEP]      │
├──────────────┬──────────────────────────┬───────────────────┤
│ 目录树        │ 参数选择面板              │ 数据表 (Tab)       │
│ ▼ 气动执行元件 │ 缸径: [6] [10] [16] [32]│ ┌────────────────┐│
│   ▼ ACQ 系列 │ 行程: [25][50][75][100] │ │ 2D 尺寸图       ││
│     ACQ 标准缸│ 磁石: [无][S]            │ │ 技术参数表      ││
│   ▼ 迷你气缸  │ 安装: [LB][FA][CB]       │ │ 选型说明        ││
│   ▼ 阀类      │ ── 已选: ACQ32x50S ──    │ └────────────────┘│
│              ├──────────────────────────┤                   │
│              │    3D 预览 (Tab)          │                   │
│              │      [旋转/缩放/平移]      │                   │
└──────────────┴──────────────────────────┴───────────────────┘

维护页（--admin 进入，密码保护）：
┌──────────────────────────────────────────┐
│ 当前数据包: ounibo_2026.06.opc (2026.06) │
│ [加载新数据包...] [校验] [查看日志]        │
│ （M2 起扩展：目录编辑 / 编译发布）          │
└──────────────────────────────────────────┘
```

## 6. 解决方案结构

```
OuniboCatalog/
├── src/
│   ├── Ounibo.Catalog.Core/      # CatalogCore + Configurator + Export + Localization
│   ├── Ounibo.Catalog.Viewer3D/  # Helix Toolkit 封装
│   ├── Ounibo.Catalog.App/       # WPF 壳（客户模式 + 维护页）
│   └── Ounibo.Tools/             # M1: 示例数据生成脚本(CLI)；M2 演化为 Builder
├── tests/Ounibo.Catalog.Core.Tests/   # xUnit：规则求值、命名模板、包加载
├── sample-data/                  # 1 个真实气缸系列的输入与生成物
└── OuniboCatalog.sln
```

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

1. CatalogCore：.opc 读写 + schema 建表 + 查询接口（含单测）
2. Ounibo.Tools 示例数据生成：读 Excel 参数表 + STEP 库 → 生成 .opc（含网格转换，assimp 命令行即可）
3. AppShell 客户模式：目录树 + 参数面板 + 过滤联动
4. Viewer3D 接入：选型变化 → 切换网格
5. ExportService：STEP 下载 + 命名模板
6. AdminService + 维护页：--admin、密码、加载/替换数据包
7. Localization：中/英资源接入全部文案
8. 集成测试：按验收标准走查全流程

## 8. 需要用户提供的输入（开工前）

- **1 个真实气缸系列的 STEP 模型**（如 ACQ 标准气缸各缸径/行程的模型，或 1 个基准模型 + 尺寸规律说明）
- **该系列的 Excel 参数表**（列：型号编码、缸径、行程、安装方式、磁石等）
- **型号编码规则**（如 ACQ32x50S 各段的含义与允许组合）
- **2D 尺寸图/数据表 PDF**（中/英）
- 客户常用 CAD 清单（用于 STEP 兼容性验证，通常无需适配）