# ProBom

**Repository Path**: pekua/pro-bom

## Basic Information

- **Project Name**: ProBom
- **Description**: 用于erpnext中bom创建
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 5
- **Created**: 2025-10-28
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Probom v2.0 — 工程项目型 BOM 智能创建与生产协同工具

> **目标平台**: Frappe Framework v16+ / ERPNext v16+（v15 不在支持范围）
> **文档编号**: PROBOM-2.0

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Frappe](https://img.shields.io/badge/Frappe-16+-green.svg)
![ERPNext](https://img.shields.io/badge/ERPNext-16+-green.svg)
![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)

## 概述

Probom 是面向**工程项目型制造企业**（以膜 / 水处理设备为代表）的 BOM 与生产协同工具。它不替代 ERPNext 的物料 / BOM / 库存 / 生产模块，而是**专攻 ERPNext 在"项目 BOM 录入"与"按工单集合作业"两个环节的体验缺口**。

## 核心模块

| 模块 | DocType | 功能 |
| --- | --- | --- |
| **Probom** | `probom` | 单级 BOM：Excel 导入 → 智能物料组匹配 → 批量建档 → 导出 |
| **MultiBOM** | `multibom` | 多级 BOM：半成品建档 → 关联子 Probom → 生成 ERPNext BOM |
| **TopBOM** | `topbom` | 项目级总 BOM：跨 Probom 去重汇总 → Excel 更新 → 生成 BOM |
| **Wanwork** | `wanwork` | 工单聚合：来料状态实时计算 → 一键完工（带回滚）→ 批量完工 |
| **配置中心** | `probom_settings` | Single DocType，运行时可调所有阈值 / 规则 / 仓库 |
| **匹配日志** | `probom_match_log` | 物料组匹配学习记录（手动覆盖追踪） |
| **活动日志** | `probom_activity_log` | 关键操作审计 |

## 架构亮点（v2 vs v1）

### 服务层拆分（SRS NFR-MAINT-1）

v1 的 `probom.py` 为 1500+ 行巨型文件。v2 拆分为：

```
probom/services/
├── matching_service.py   # 五级降级匹配引擎（纯函数，可单测）
├── excel_service.py      # Excel 解析/导出（openpyxl）
├── item_service.py       # 物料创建/映射
└── work_order_service.py # 来料状态计算 + 一键完工 state machine
```

### 五级降级匹配算法

1. **优先级规则** — `probom_settings.priority_rules_json` 热加载
2. **精确匹配** — 物料组名 == composite_name
3. **关键词 Jaccard** — `|A ∩ B| / |A ∪ B|`
4. **模糊匹配** — `0.7 × SequenceMatcher + 0.3 × Jaccard`
5. **同义词匹配** — 行业术语中英对照

### 一键完工 State Machine（带回滚）

严格顺序：Start → Material Transfer → Complete → Manufacture Receipt

任一步失败 → 自动回滚已提交的 Stock Entry（SRS [重做] v1 未做回滚的问题）。

## 安装

### 环境要求

- Frappe Framework v16+
- ERPNext v16+
- Python 3.11+
- MariaDB 10.6+ 或 PostgreSQL 14+

### 安装步骤

```bash
cd $PATH_TO_YOUR_BENCH

# 获取应用
bench get-app https://github.com/pekua/probom --branch main

# 安装应用
bench install-app probom

# 重启
bench restart
```

## v16 迁移指南

从 v1 (Frappe v15) 升级到 v2 (Frappe v16)：

```bash
# 1. 升级 ERPNext 到 v16
# 2. 先备份
bench --site <site> backup --with-files

# 3. 卸载 v1
bench --site <site> uninstall-app probom

# 4. 安装 v2
bench --site <site> install-app probom

# 5. 迁移
bench --site <site> migrate

# 6. 运行兼容性检查
./scripts/check_v16_api_compat.sh

# 7. 测试
bench --site <site> run-tests --app probom
```

## v16 关键适配项

| 适配项 | 影响 | 对策 |
| --- | --- | --- |
| Workspace 2.0 schema | v15 `cards[]` 不再解析 | 重写为 `links[]` + `shortcuts[]` |
| Work Order `expected_delivery_date` 必填 | 一键完工报错 | `probom_settings.default_lead_days` 兜底 |
| BOM `operating_cost_per_bom_quantity` 必填 | BOM 创建失败 | 从 Manufacturing Settings 拉默认 |
| Production Plan 两层结构 | PP → Work Order 失效 | 改走 Work Order Group 路径 |
| Item `is_sales_item` 默认值不固定 | 新 Item 误标可销售 | 创建时显式赋值 |
| `frappe.enqueue` 需显式 queue | 后台任务异常 | 指定 `queue="default"` |

## 开发指南

### 代码规范

```bash
# ruff 检查
ruff check probom

# v16 API 兼容性检查
./scripts/check_v16_api_compat.sh

# 单元测试（纯函数，不需要 frappe 环境）
python -m unittest probom.tests.test_matching_service -v

# bench 集成测试
bench --site <site> run-tests --app probom
```

### 设计原则（SRS §2.4）

1. **不修改标准 DocType** — 仅 Custom Field / Script
2. **DocType 命名小写下划线** — `[a-z][a-z0-9_]*`
3. **配置驱动** — 阈值集中在 `probom_settings`
4. **业务逻辑可单测** — 纯函数优先
5. **失败可恢复** — 批量操作支持部分成功
6. **可卸载** — 无脏数据残留

## 许可证

MIT License

## 作者

- **pekua** — [pekua](mailto:397014443@qq.com)