158 lines
8.9 KiB
Markdown
158 lines
8.9 KiB
Markdown
# 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 兼容性验证，通常无需适配）
|