# bom-workbench

**Repository Path**: Debugman/bom-workbench

## Basic Information

- **Project Name**: bom-workbench
- **Description**: BOM 转换工作台
SolidWorks PDM（EBOM）↔ 金蝶 ERP（MBOM）转换中间件
- **Primary Language**: C#
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-14
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BOM 转换工作台

> 对应需求文档 [02-MRD.md](../02-MRD.md) · [03-PRD.md](../03-PRD.md) · [04-API接口清单.md](../04-API接口清单.md)  
> 技术栈：.NET 10 + EF Core + Vue3 / Vite / Element Plus / vxe-table（虚拟滚动树表）
> **生产模式**：PDM/金蝶 API、数据库、认证、定时同步均通过 `appsettings` 配置

## 7 项清单对照

| # | 模块 | 实现说明 |
|---|------|----------|
| ① | SolidWorks PDM API | Mock / HTTP 双模式；BOM 抽取含版本/状态；**PDM Add-in**（`addin/`）+ `POST /api/pdm/sync-trigger` |
| ② | 金蝶 ERP 读写 | 推送 MBOM、物料校验、变更通知、只读查询 `GET /api/bom/erp/mbom`；失败重试 `retry-push` |
| ③ | 规则引擎 | 映射/条件/默认值/结构变换/预处理/校验；CRUD + 激活 + 测试运行 API；前端规则录入页 |
| ④ | 设计 BOM 管理 | 快照列表、版本历史、详情、全树展示、PDM 同步状态、转 MBOM |
| ⑤ | 工艺 BOM 管理 | 草稿列表、树展示、审核/推送/重试、EBOM↔MBOM 一键对比 |
| ⑥ | 用户/运维手册 | `docs/用户操作手册.md`、`docs/运维手册.md` |
| ⑦ | 培训与交付 | 精简版操作培训材料（手册 + 内置演示数据）；完整培训体系需另行安排 |

## 功能范围（M1～M7）

| 模块 | 说明 |
|------|------|
| M1 EBOM 同步 | 手动 / 后台定时，Mock 或 HTTP PDM |
| M2 规则引擎 | 字段映射、条件匹配、lookup、结构变换、预处理、校验；JSON 配置 + 测试 API |
| M3 MBOM 转换 | EBOM 快照 → MBOM 草稿 |
| M4 差异对比 | EBOM vs MBOM、版本 vs 版本 |
| M5 审核流程 | 草稿 → 审核中 → 已批准 |
| M6 推送金蝶 | Mock 或 HTTP ERP |
| M7 料号对照 | 预置 PDM ↔ 金蝶编码映射 |

## 规则引擎能力

| 类型 | 说明 |
|------|------|
| `fieldMapping` | 字段映射，支持 `direct` / `toNumber` / `concat` / `substring` 等变换 |
| `lookup` | 料号对照表 lookup，`onNotFound`: error / warn / skip / keepSource |
| `conditional` | 条件分支（`when.all` / `when.any` + `then` / `else`） |
| `defaultValue` | 节点级默认值 |
| `structureTransform` | 结构变换：`skipNode` / `mergePhantom` / `flattenOneLevel` / `promoteChild` |
| `preprocess` | 转换前预处理：`trim` / `uppercase` / `normalizePartNo` / `unitConvert` |
| `validation` | 必填字段、最大层级、`failOnWarn` |
| `scope` | 规则集作用域：件号前缀、PDM 状态 |

规则 JSON Schema 见 [schema/rule-engine.schema.json](../schema/rule-engine.schema.json)，示例见 [schema/rule-set-example.json](../schema/rule-set-example.json)。

**测试 API**（不写库）：

```powershell
Invoke-RestMethod -Uri http://localhost:5180/api/rules/sets/1/test `
  -Method Post -Body '{"snapshotId":1}' -ContentType "application/json"
```


```powershell
cd E:\design\bom-workbench
dotnet restore --configfile NuGet.Config
.\deploy\build-web.ps1    # 构建 Vue 前端（含 2000+ 行虚拟滚动树表）
dotnet build
dotnet run --project src/BomWorkbench.Api --urls http://localhost:5180
```

## 前端（虚拟滚动树表）

- 源码：`web/`（Vue3 + Element Plus + **vxe-table** 虚拟滚动）
- 构建：`.\deploy\build-web.ps1` 或 `cd web && npm run build`
- EBOM / MBOM 树表支持 **2000+ 行**流畅滚动（`scroll-y.gt=20` 启用虚拟渲染）

## PDM Add-in 安装

```powershell
cd E:\design\bom-workbench
.\addin\install-addin.ps1 -WorkbenchUrl "http://localhost:5180"
```

| 组件 | 说明 |
|------|------|
| `BomWorkbench.PdmAddIn.dll` | PDM 客户端插件，菜单「同步到 BOM 工作台」 |
| `BomWorkbench.PdmSyncLauncher.exe` | 独立同步助手（手动输入件号） |
| `AddIn.config.json` | 工作台 URL、API Key |

详见 [addin/README.md](./addin/README.md)。注册：PDM 管理工具 → 插件 → 添加 DLL。

浏览器打开 **http://localhost:5180**

## 一键部署

**双击运行**（Windows）：

| 文件 | 说明 |
|------|------|
| `一键部署.bat` | 发布 + 启动 + 健康检查 + 打开浏览器 |
| `停止服务.bat` | 停止运行中的实例 |

或 PowerShell：

```powershell
cd E:\design\bom-workbench
.\deploy\deploy.ps1                    # 开发模式（默认）
.\deploy\deploy.ps1 -Profile prod        # 生产模式（ASPNETCORE_ENVIRONMENT=Production）
.\deploy\deploy.ps1 -PublishOnly         # 只 publish 不启动
.\deploy\deploy.ps1 -Restart             # 不重新编译，仅重启
.\deploy\deploy.ps1 -Stop                # 停止
```

首次运行会自动生成 `deploy/config.json`（可复制 `deploy/config.example.json` 修改）：

| 配置项 | 说明 | 默认 |
|--------|------|------|
| `profile` | `dev` / `prod` | dev |
| `port` | 监听端口 | 5180 |
| `publishDir` | 发布目录 | publish |
| `openBrowser` | 部署后打开浏览器 | true |

**说明**：重新部署时会自动备份/恢复 `publish` 目录下的 `appsettings*.json` 和 `bom-workbench.db`，避免覆盖生产配置与数据。日志见 `deploy/deploy.log`。

---

## 安装包（交付客户）

双击 **`打包安装包.bat`** 或：

```powershell
.\deploy\build-package.ps1 -Version 1.0.0
```

生成 **`dist/BomWorkbench-1.0.0-win-x64.zip`**（自包含 .NET，目标机无需安装 Runtime）。

客户侧步骤：
1. 解压 ZIP  
2. 编辑 `app\appsettings.Production.json`  
3. 双击 **`安装.bat`**  
4. 访问 http://localhost:5180  

---

## 生产部署（手动）

```powershell
$env:ASPNETCORE_ENVIRONMENT = "Production"
dotnet run --project src/BomWorkbench.Api
```

使用 `appsettings.Production.json`，并通过**环境变量**覆盖敏感项（推荐）：

```powershell
$env:BomWorkbench__Database__ConnectionString = "Server=...;Database=BomWorkbench;..."
$env:BomWorkbench__Pdm__BaseUrl = "https://pdm.customer.com"
$env:BomWorkbench__Pdm__Authentication__ClientSecret = "secret"
$env:BomWorkbench__Erp__BaseUrl = "https://erp.customer.com"
$env:BomWorkbench__Erp__Authentication__ClientSecret = "secret"
$env:BomWorkbench__Security__ApiKey = "your-api-key"
```

## 配置说明（`BomWorkbench` 节）

| 配置块 | 关键项 | 说明 |
|--------|--------|------|
| `Application` | `SeedDemoData` | 生产设为 `false` |
| `Database` | `Provider`, `ConnectionString` | `Sqlite` 或 `SqlServer` |
| `Pdm` | `Provider` | `Mock`（开发）或 `Http`（生产） |
| `Pdm` | `BaseUrl`, `Endpoints.FetchBom` | PDM API 根地址与路径模板 |
| `Pdm` | `Authentication.Scheme` | `None` / `ApiKey` / `Bearer` / `Basic` / `OAuth2ClientCredentials` |
| `Pdm` | `ResponseNodesPath` | 响应 JSON 中节点数组路径，如 `nodes` 或 `data.nodes` |
| `Erp` | `Provider`, `BaseUrl`, `Endpoints.*` | 金蝶物料校验、BOM 推送、变更通知 |
| `Erp` | `PushBillNoPath` | 推送响应中的单号字段，如 `data.billNo` |
| `Sync` | `EnableBackgroundSync`, `PartNumbers` | 后台定时同步件号列表 |
| `Security` | `EnableApiKeyAuth`, `ApiKey` | 生产 API 鉴权 |

### PDM HTTP 端点占位符

路径模板支持：`{partNo}`、`{version}`、`{itemCode}`、`{draftId}`

```json
"Endpoints": {
  "FetchBom": "/api/v1/vault/bom/{partNo}?revision={version}"
}
```

PDM 期望响应格式（字段名可映射）：

```json
{
  "nodes": [
    {
      "nodeUid": "root-001",
      "parentUid": null,
      "partNo": "ASM-001",
      "partName": "主装配",
      "qty": 1,
      "uom": "PCS",
      "levelNo": 0,
      "isPhantom": false,
      "attrs": { "Configuration": "自制" }
    }
  ]
}
```

### 金蝶 HTTP 端点

| 端点键 | 默认路径 | 方法 |
|--------|----------|------|
| `ItemExists` | `/api/v1/material/{itemCode}` | GET |
| `PushMbom` | `/api/v1/bom/push` | POST |
| `FetchMbom` | `/api/v1/bom/{itemCode}` | GET |
| `ChangeNotification` | `/api/v1/message/send` | POST |

## 新增 API（7 项清单）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/bom/ebom/versions?partNo=` | EBOM 版本历史 |
| GET | `/api/bom/ebom/{id}` | EBOM 快照详情 |
| GET | `/api/bom/ebom/{id}/tree-all` | EBOM 全树 |
| GET | `/api/bom/mbom/{id}` | MBOM 草稿详情 |
| POST | `/api/bom/mbom/{id}/retry-push` | 推送失败重试 |
| GET | `/api/bom/erp/mbom?itemCode=` | 金蝶 MBOM 只读 |
| POST | `/api/pdm/sync-trigger` | PDM Add-in 触发同步 |
| GET | `/api/integration/status` | 集成配置状态 |
| POST/PUT/DELETE | `/api/material-mapping` | 料号对照 CRUD |
| POST | `/api/rules/test-run` | 规则测试（不写库） |

## 项目结构

```
src/
├── BomWorkbench.Core/           实体、DTO、接口、Configuration
├── BomWorkbench.Infrastructure/ EF、Mock/Http 集成、规则引擎、后台同步
└── BomWorkbench.Api/            Web API + 中间件 + wwwroot
```

## 健康检查

```powershell
Invoke-RestMethod http://localhost:5180/health
```

返回当前 `pdmProvider`、`erpProvider`、`database`、`backgroundSync` 等运行模式（不含密钥）。

## 接真实 PDM / 金蝶

1. 将 `Pdm.Provider` / `Erp.Provider` 改为 `Http`
2. 填写 `BaseUrl` 与各 `Endpoints`
3. 配置 `Authentication`（OAuth2 等）
4. 重启服务；`/health` 确认 Provider 已切换

集成规格参考 [07-PDM集成规格-模板.md](../07-PDM集成规格-模板.md)、[08-金蝶集成规格-模板.md](../08-金蝶集成规格-模板.md)。

## 数据库

| 环境 | Provider | 连接串示例 |
|------|----------|------------|
| 开发 | Sqlite | `Data Source=bom-workbench.db` |
| 生产 | SqlServer | 见 `appsettings.Production.json` |

生产 DDL 见 [ddl/init.sql](../ddl/init.sql)。

## 已知限制

- HTTP 集成按约定 JSON 结构解析，若客户 API 差异大需扩展映射配置
- 规则引擎 conditional 仍为演示级
- 前端为 CDN Vue 单页