# item_tree_view

**Repository Path**: jeffery0573/item_tree_view

## Basic Information

- **Project Name**: item_tree_view
- **Description**: 在物料的列表页面，增加树显示物料的窗口。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-18
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Item Tree View

ERPNext 物料与制造相关的界面增强。名称来自最早实现的「Item 列表树形视图」，后续功能也统一维护在本 app 中。

## 功能一览

| # | 功能 | 影响页面 | 说明 |
|---|------|----------|------|
| 1 | Item 列表树形侧边栏 | Item 列表 | 左侧显示物料组树；点击分组筛选列表，点击物料叶子节点打开该物料 |
| 2 | Item 上一条 / 下一条 | Item 表单 | 工具栏 ◀ ▶ 按钮，按 `item_code` 顺序切换相邻物料（仅已保存单据） |
| 3 | BOM 上一条 / 下一条 | BOM 表单 | 工具栏 ◀ ▶ 按钮，按 BOM 编号顺序切换相邻 BOM（仅已保存单据） |
| 4 | Work Order 仓库自动带出 | Work Order 表单 | 选择 BOM 后，从 BOM 的 `Default Source Warehouse` / `Default Target Warehouse` 自动填入 `Source Warehouse` / `Target Warehouse`（含 Required Items 子表来源仓） |
| 5 | 半成品复制自动编号 | Item 表单 | 复制 `B-半成品` 及其子孙组内物料时，自动取同前缀组最大物料号 +1 并赋给新物料 |
| 6 | BOM 更新重量 | BOM 表单 | Actions → Update Weight：按子件重量汇总写入成品/半成品 `Weight Per Unit`；物料号第 3 位为 B（BAB）时禁用 |
| 7 | BOM 提交子件校验 | BOM 表单 | 提交时：每个子件须有 `BOM No`，或 Item 已勾选 Allow Purchase；否则提示并阻止提交 |

## 各功能详情

### 1. Item 列表树形侧边栏

- **入口**：Stock → Item → 列表视图
- **行为**：
  - 左侧按 Item Group 层级展示树
  - 点击分组：展开节点并筛选该组（含子组）下的物料
  - 点击物料名：打开对应 Item 表单
- **实现文件**：`public/js/item_list_tree.js`、`public/css/item_tree_sidebar.css`、`api.py`

### 2. Item 表单导航

- **入口**：打开任意已保存的 Item
- **行为**：表单顶部工具栏显示「上一条 / 下一条」，按编码顺序跳转
- **实现文件**：`public/js/item_form_nav.js`、`api.get_adjacent_items`

### 3. BOM 表单导航

- **入口**：打开任意已保存的 BOM
- **行为**：与 Item 导航相同，按 BOM 名称顺序切换
- **实现文件**：`public/js/bom_form_nav.js`、`api.get_adjacent_boms`

### 4. Work Order 仓库自动带出

- **入口**：Manufacturing → Work Order → 新建
- **前提**：BOM 上已维护 Default Source Warehouse / Default Target Warehouse
- **行为**：
  - 选择 `production_item` 或 `bom_no` 后自动带出仓库
  - 服务端在拉取 BOM 明细前写入仓库，Required Items 同步获得 Source Warehouse
  - API / 后台创建工单时，若仓库为空，保存前也会尝试从 BOM 补全
- **实现文件**：
  - 服务端：`overrides/work_order.py`
  - 客户端：`public/js/work_order_bom_warehouses.js`

### 5. 半成品复制自动编号

- **入口**：打开 `B-半成品` 及其子孙组内任意 Item，点击「Duplicate / 复制」
- **前提**：物料组在 `B-半成品` 子树内，且物料编码为「4 位前缀 + 数字后缀」（如 `BAP3`、`BAB1`、`BAW2`、`BAZ0` 等）
- **行为**：
  - 复制后打开的新 Item 表单会自动填入新物料号
  - 新号 = 同前缀组（如 `BAP3`、`BAB1`）现有最大物料号 + 1，数字后缀补零（通常共 10 位，例：`BAP3000027`）
  - 适用于工具栏 Duplicate 按钮与菜单 Duplicate（Shift+D）
- **实现文件**：`public/js/item_duplicate_code.js`、`api.get_next_item_code_for_copy`

### 6. BOM 更新重量

- **入口**：打开已保存的 BOM → Actions → **Update Weight**
- **计算规则**：`Σ(子件 Weight Per Unit × stock_qty) / BOM.quantity`，结果写入当前 BOM 成品/半成品 Item 的 `Weight Per Unit`；若 Item 尚无 Weight UOM，则尝试从子件带出
- **确认**：若当前物料 `Weight Per Unit` 已不为 0，弹窗确认是否继续覆盖更新
- **限制**：当前物料号第 3 个字符为 `B`（如 `BAB…`）时，按钮灰色不可用，服务端也会拒绝计算
- **提示**：子件重量为 0 时按 0 计入，并在结果中列出这些物料号
- **实现文件**：`public/js/bom_update_weight.js`、`api.get_bom_weight_preview`、`api.update_item_weight_from_bom`

### 7. BOM 提交子件校验

- **入口**：提交（Submit）任意 BOM
- **规则**：Items 表中每一个子件必须满足以下之一：
  1. `BOM No` 不为空，或
  2. 对应 Item 的 **Allow Purchase**（`is_purchase_item`）为勾选
- **行为**：若存在「BOM No 为空且 Allow Purchase = 0」的子件，弹出提示（列出行号与物料号）并**阻止提交**
- **实现文件**：`overrides/bom.py`（`ItemTreeViewBOM.before_submit`）

## 安装

```bash
cd $PATH_TO_YOUR_BENCH
bench get-app https://gitee.com/jeffery0573/item_tree_view
bench --site <site> install-app item_tree_view
bench --site <site> clear-cache
bench restart
```

安装成功后，终端会打印本 app 的功能清单。

在 ERPNext **应用列表**中也可看到简短描述（来自 `hooks.py` 的 `app_description`）。

## 依赖

- ERPNext（Manufacturing 模块，Work Order / BOM 功能）

## 维护说明

- 新增功能时：更新 `item_tree_view/install.py` 中的 `APP_FEATURES`、本 README 功能表，以及 `CHANGELOG.md`
- 版本号：`item_tree_view/__init__.py` 中的 `__version__`

## 其他脚本

| 文件 | 用途 |
|------|------|
| `migrate_baw_item_codes.py` | 一次性数据迁移：将 BAW 开头 9 位编码补齐为 10 位，非常规功能，按需手动执行 |

## Contributing

本仓库使用 `pre-commit` 做格式与 lint 检查：

```bash
cd apps/item_tree_view
pre-commit install
```

## License

MIT