wangruiguo/OnebotCatalog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
OnebotCatalog/欧霓博_目录软件_M1设计文档.md

8.9 KiB
Raw Permalink Blame History

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）

-- 元信息
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：

{
  "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 兼容性验证，通常无需适配）