# ComponentInventoryCheckModule 流程图文档

## 模块概述

**模块名**: ComponentInventoryCheckModule
**功能**: 部件库存核对模块 - 自动核对产品订单中"部件"类物料的库存情况
**主入口**: CheckComponentInventory
**说明**: 当库存不足时,按订单顺序将超出部分的订单的"部件优先"字段标记为"否"

---

## 业务流程图（面向非技术人员）

```mermaid
flowchart TD
    Start([开始核对部件库存]) --> Step1["1. 读取数据<br/>读取产品订单表<br/>读取库存表<br/>读取物料配置表"]

    Step1 --> Step2["2. 分析订单<br/>查看每个订单需要哪些部件<br/>计算每个订单需要多少个部件"]

    Step2 --> Step3["3. 汇总需求<br/>统计所有订单总共需要多少个部件<br/>按部件种类分别统计"]

    Step3 --> Step4["4. 检查库存<br/>对比库存数量和需求数量<br/>找出库存不够的部件"]

    Step4 --> Step5["5. 分配库存<br/>按订单从上到下依次分配<br/>库存够的订单→保持不变<br/>库存不够的订单→标记为'否'"]

    Step5 --> Step6["6. 完成处理<br/>显示处理结果<br/>多少订单能发货<br/>多少订单缺部件"]

    Step6 --> End([完成])

    style Step1 fill:#e1f5e1
    style Step2 fill:#d1ecf1
    style Step3 fill:#fff3cd
    style Step4 fill:#ffe5b4
    style Step5 fill:#f8d7da
    style Step6 fill:#e1f5e1
```

### 业务流程说明

| 步骤 | 做什么 | 为什么 |
|------|--------|--------|
| **1. 读取数据** | 从Excel表格中读取订单、库存、配置信息 | 获取处理所需的所有数据 |
| **2. 分析订单** | 查看每个订单需要什么部件、多少个 | 了解每个订单的部件需求 |
| **3. 汇总需求** | 把所有订单的相同部件需求加在一起 | 算出总共需要多少部件 |
| **4. 检查库存** | 对比总需求和实际库存 | 判断库存是否够用 |
| **5. 分配库存** | 先来先得，库存不够的标记为"否" | 确定哪些订单能按时发货 |
| **6. 完成处理** | 显示统计结果 | 让用户了解处理情况 |

### 举例说明

假设有3个订单，都需要同一个部件A：

| 订单 | 需要部件A数量 | 库存分配过程 | 最终状态 |
|------|--------------|--------------|---------|
| 订单1 | 2个 | 库存剩5个，够用 | ✓ 保持原值 |
| 订单2 | 2个 | 库存剩3个，够用 | ✓ 保持原值 |
| 订单3 | 2个 | 库存剩1个，不够 | ✗ 标记为"否" |

> **技术说明**：标记为"否"的订单，在生成BIP上传数据时会跳过部件类物料，优先保证子部件供应。

---

## CheckComponentInventory 主流程图（技术版）

> 以下流程图面向技术人员，展示完整的错误处理和验证步骤。

---

## CheckComponentInventory 主流程图（详细版）

```mermaid
flowchart TD
    Start(["开始 CheckComponentInventory"]) --> GetSheet1["获取[产品订单]工作表"]
    GetSheet1 --> CheckSheet1{工作表存在?}
    CheckSheet1 -->|否| ShowMsg1["显示错误消息"] --> End1(["结束"])
    CheckSheet1 -->|是| GetSheet2["获取[现存量]工作表"]

    GetSheet2 --> CheckSheet2{工作表存在?}
    CheckSheet2 -->|否| ShowMsg2["显示错误消息"] --> End2(["结束"])
    CheckSheet2 -->|是| GetSheet3["获取[平台配置清单]工作表"]

    GetSheet3 --> CheckSheet3{工作表存在?}
    CheckSheet3 -->|否| ShowMsg3["显示错误消息"] --> End3(["结束"])
    CheckSheet3 -->|是| CheckData{订单数据存在?}

    CheckData -->|否| ShowMsg4["显示无数据消息"] --> End4(["结束"])
    CheckData -->|是| InitBOM["初始化BOM提取器<br/>LoadBomData"]

    InitBOM --> CheckBOM{BOM加载成功?}
    CheckBOM -->|否| ShowMsg5["显示BOM错误"] --> End5(["结束"])
    CheckBOM -->|是| LoadInv["LoadInventoryData<br/>读取库存数据到字典"]

    LoadInv --> CheckInv{库存数据有效?}
    CheckInv -->|否| ShowMsg6["显示无库存消息"] --> End6(["结束"])
    CheckInv -->|是| LoadOrders["LoadOrderData<br/>读取订单数据"]

    LoadOrders --> CheckOrders{订单数据有效?}
    CheckOrders -->|否| ShowMsg7["显示无订单消息"] --> End7(["结束"])
    CheckOrders -->|是| ParseAll["ParseAllOrdersBOM<br/>解析所有订单的BOM"]

    ParseAll --> CalcDemand["CalculateComponentDemand<br/>统计部件总需求"]

    CalcDemand --> CheckDemand{有部件需求?}
    CheckDemand -->|否| ShowMsg8["显示无部件消息"] --> End8(["结束"])
    CheckDemand -->|是| Validate["ValidateInventory<br/>验证库存数据"]

    Validate --> Allocate["AllocateInventory<br/>按订单顺序分配库存"]

    Allocate --> ShowResult["显示结果统计<br/>总订单数、包含部件订单数<br/>库存充足/不足订单数"]

    ShowResult --> End9(["完成"])

    style InitBOM fill:#e1f5e1
    style LoadInv fill:#d1ecf1
    style LoadOrders fill:#d1ecf1
    style ParseAll fill:#fff3cd
    style CalcDemand fill:#fff3cd
    style Validate fill:#ffe5b4
    style Allocate fill:#f8d7da
    style End9 fill:#e1f5e1
```

---

## AllocateInventory 库存分配详细流程

```mermaid
flowchart TD
    AllocStart([开始 AllocateInventory]) --> InitStats[初始化统计信息<br/>TotalOrders, OrdersWithComponent<br/>OrdersSufficient, OrdersInsufficient, OrdersSkipped]

    InitStats --> LoopStart{遍历订单<br/>i = 1 to orders.Count}

    LoopStart -->|有订单| GetOrder[获取订单 order = orders i]
    GetOrder --> CheckParse{解析失败?}
    CheckParse -->|ORDER_PARSE_ERR <> ""| Skip1[跳过订单<br/>OrdersSkipped++]
    CheckParse -->|无错误| CheckHasComp{包含部件?}

    CheckHasComp -->|ORDER_HAS_COMP = False| Skip2[跳过订单<br/>OrdersSkipped++]
    CheckHasComp -->|HasComponent = True| CheckQty{数量为0?}

    CheckQty -->|ORDER_QUANTITY = 0| Skip3[跳过订单<br/>OrdersSkipped++]
    CheckQty -->|数量 > 0| UpdateComp[OrdersWithComponent++]

    UpdateComp --> GetComp[获取部件库存信息<br/>compInv = componentDemands compCode]
    GetComp --> CalcReq[计算需求量<br/>requiredQty = CompQty × OrderQty]

    CalcReq --> CheckStock{库存充足?<br/>compInv.STOCK >= requiredQty}

    CheckStock -->|是| DeductSufficient[扣减库存<br/>compInv.STOCK -= requiredQty<br/>OrdersSufficient++]
    CheckStock -->|否| MarkNo[标记E列为"否"<br/>orderSheet.Cells Row, 5 = "否"<br/>compInv.STOCK -= requiredQty<br/>OrdersInsufficient++]

    DeductSufficient --> NextOrder[继续下一个订单]
    MarkNo --> NextOrder
    Skip1 --> NextOrder
    Skip2 --> NextOrder
    Skip3 --> NextOrder

    NextOrder --> LoopStart

    style UpdateComp fill:#e1f5e1
    style DeductSufficient fill:#e1f5e1
    style MarkNo fill:#f8d7da
```

---

## ParseOrderBOM 解析详细流程

```mermaid
flowchart TD
    ParseStart([开始 ParseOrderBOM]) --> CreateParser[创建ProductModelParser]
    CreateParser --> ParseModel[解析型号<br/>parser.Parse model]

    ParseModel --> CheckParse{解析成功?}
    CheckParse -->|否| SetError[设置解析错误<br/>ORDER_PARSE_ERR = "解析失败: ..."]
    SetError --> ParseEnd([结束返回])

    CheckParse -->|是| ExtractBOM[提取BOM<br/>bomExtractor.ExtractBom conditions]

    ExtractBOM --> LoopComp{遍历BOM项目<br/>For Each item In matchedItems}

    LoopComp -->|有项目| CheckCat{item.category = "部件"?}

    CheckCat -->|否| NextItem[继续下一个项目]
    CheckCat -->|是| SetCompInfo[设置部件信息<br/>ORDER_COMP_CODE = item.Code66<br/>ORDER_COMP_QTY = item.quantity<br/>ORDER_HAS_COMP = True]

    SetCompInfo --> ParseEnd
    NextItem --> LoopComp

    style SetCompInfo fill:#d1ecf1
    style SetError fill:#f8d7da
```

---

## 数据处理序列图

```mermaid
sequenceDiagram
    participant Main as CheckComponentInventory
    participant Loader as 数据加载器
    participant Parser as BOM解析器
    participant Calc as 需求计算器
    participant Validator as 库存验证器
    participant Allocator as 库存分配器

    Main->>Loader: LoadInventoryData(ws)
    Loader-->>Main: 库存字典 Dictionary(编码 -> 数量)

    Main->>Loader: LoadOrderData(ws)
    Loader-->>Main: 订单集合 Collection(Of Dictionary)

    loop 每个订单
        Main->>Parser: ParseOrderBOM(order, bomExtractor)
        Parser->>Parser: ProductModelParser.Parse(model)
        Parser->>Parser: BomExtractor.ExtractBom(conditions)
        Parser->>Parser: 查找 category="部件" 的物料
        Parser-->>Main: 设置订单部件信息
    end

    Main->>Calc: CalculateComponentDemand(orders)
    Calc->>Calc: 累加每个订单的部件需求
    Note over Calc: 需求 = CompQty × OrderQty
    Calc-->>Main: 部件需求字典 Dictionary(编码 -> 库存信息)

    Main->>Validator: ValidateInventory(demands, inventoryData)
    Validator->>Validator: 检查每个部件是否存在
    Validator->>Validator: 计算是否短缺
    Validator-->>Main: 警告集合 Collection

    Main->>Allocator: AllocateInventory(orders, demands, sheet)
    loop 按订单顺序遍历
        Allocator->>Allocator: 获取订单部件需求
        Allocator->>Allocator: 检查库存是否充足
        alt 库存充足
            Allocator->>Allocator: 扣减库存，保持原值
            Note over Allocator: OrdersSufficient++
        else 库存不足
            Allocator->>Allocator: 标记 E5 = "否"
            Note over Allocator: OrdersInsufficient++
        end
    end
    Allocator-->>Main: 统计信息 Statistics

    Main-->>Main: 显示结果消息框
```

---

## 数据结构说明

### 订单字典结构 (Dictionary Object)

| 键名 | 常量 | 类型 | 说明 |
|------|------|------|------|
| RowNumber | ORDER_ROW | Long | 订单所在行号 |
| ProductModel | ORDER_MODEL | String | 产品型号 |
| Quantity | ORDER_QUANTITY | Double | 产品数量 |
| ComponentCode | ORDER_COMP_CODE | String | 部件66编码 |
| ComponentQty | ORDER_COMP_QTY | Double | 部件BOM数量 |
| HasComponent | ORDER_HAS_COMP | Boolean | 是否包含部件 |
| ParseError | ORDER_PARSE_ERR | String | 解析错误信息 |

### 部件库存字典结构 (Dictionary Object)

| 键名 | 常量 | 类型 | 说明 |
|------|------|------|------|
| ComponentCode | INV_CODE | String | 部件66编码 |
| TotalDemand | INV_DEMAND | Double | 总需求量 |
| AvailableStock | INV_STOCK | Double | 可用库存（动态扣减） |
| IsShortage | INV_SHORTAGE | Boolean | 是否短缺 |

### 统计信息结构 (Statistics Type)

| 字段 | 类型 | 说明 |
|------|------|------|
| TotalOrders | Long | 总订单数 |
| OrdersWithComponent | Long | 包含部件的订单数 |
| OrdersSufficient | Long | 库存充足订单数 |
| OrdersInsufficient | Long | 库存不足订单数 |
| OrdersSkipped | Long | 跳过订单数 |

---

## 关键特性

### 1. 库存分配策略
- **按订单顺序分配**: 从上到下遍历订单，先到先得
- **动态库存扣减**: 库存充足时扣减，不足时标记为负数
- **只标记不跳过**: 即使库存不足也继续处理后续订单

### 2. 部件识别机制
- 通过 `BomExtractor` 提取完整BOM
- 遍历BOM项目，查找 `category = "部件"` 的物料
- 只记录第一个匹配到的部件（假设每个产品只有一个主部件）

### 3. 错误处理
- **工作表缺失**: 提前验证，友好提示
- **BOM加载失败**: 显示错误摘要，终止处理
- **型号解析失败**: 记录错误，跳过该订单
- **部件找不到库存**: 添加警告，继续处理（库存设为0）

### 4. 数据完整性
- 使用 `Dictionary` 实现库存的引用更新
- 使用 `Collection` 保持订单顺序
- 统计跳过的订单（解析失败、无部件、数量为0）

---

## 执行示例

### 正常流程示例

```
输入数据:
  [产品订单]
    第2行: MD-100, 数量2, 部件A(编码661001, 用量1)
    第3行: MD-200, 数量2, 部件A(编码661001, 用量1)
    第4行: MD-300, 数量2, 部件A(编码661001, 用量1)

  [现存量]
    661001: 5

处理流程:
  1. 读取3个订单
  2. 解析BOM，识别部件661001
  3. 统计需求: 1×2 + 1×2 + 1×2 = 6
  4. 验证库存: 6 > 5，短缺
  5. 分配库存:
     - 订单2: 需求2，库存5→3，充足
     - 订单3: 需求2，库存3→1，充足
     - 订单4: 需求2，库存1→-1，不足，标记E4="否"

输出结果:
  [产品订单]
    第2行: E列保持原值
    第3行: E列保持原值
    第4行: E列 = "否"

  统计信息:
    处理订单数: 3
    包含部件订单: 3
    库存充足订单: 2
    库存不足订单: 1
```

### 异常处理示例

```
输入数据:
  [产品订单]
    第2行: INVALID-MODEL, 数量5  ← 型号解析失败
    第3行: MD-100, 数量0        ← 数量为0
    第4行: MD-200, 数量2, 部件669999 (库存中不存在)

  [现存量]
    661001: 10

输出结果:
  第2行: 跳过（解析失败）
  第3行: 跳过（数量为0）
  第4行: 标记E4="否"，但添加警告 "部件 '669999' 在[现存量]中未找到"

  统计信息:
    处理订单数: 3
    包含部件订单: 1
    库存充足订单: 0
    库存不足订单: 1
    跳过订单数: 2

  警告信息:
    部件 '669999' 在[现存量]中未找到
```

---

## 工作表结构要求

### [产品订单] 工作表

| 列号 | 字段名 | 说明 | 必填 |
|------|--------|------|------|
| A | 生产订单号 | 订单唯一标识 | 否 |
| B | 产品型号 | 产品完整型号 | 是 |
| C | 数量 | 生产数量 | 是 |
| D | 产品编码 | 产品代码 | 否 |
| E | 部件优先 | 是否优先提取部件类别（输出字段） | - |

- **表头**: 第1行
- **数据起始**: 第2行
- **输出位置**: E列（第5列）

### [现存量] 工作表

| 列号 | 字段名 | 说明 |
|------|--------|------|
| B | 物料编码 | 对应BOM中的66代码 |
| J | 结存主数量 | 库存数量 |

- **表头**: 第3行
- **数据起始**: 第4行

### [平台配置清单] 工作表

标准的BOM配置清单，用于提取物料信息。

---

## 相关模块

### 依赖的类模块
- **BomExtractor**: BOM提取器，负责从平台配置清单中提取匹配的物料
- **ProductModelParser**: 产品型号解析器，解析型号字符串为结构化条件
- **BomItem**: BOM物料项数据模型

### 相关模块
- **BIPUploadModule**: 生成BIP上传模板
  - 读取"部件优先"字段
  - 当值为"否"时排除"部件"类别物料
  - 与本模块功能互补

---

## 算法复杂度

| 操作 | 时间复杂度 | 说明 |
|------|-----------|------|
| LoadInventoryData | O(n) | n = 库存行数 |
| LoadOrderData | O(m) | m = 订单行数 |
| ParseAllOrdersBOM | O(m × p) | p = 平均BOM物料数 |
| CalculateComponentDemand | O(m) | 遍历订单统计需求 |
| ValidateInventory | O(k) | k = 不同部件数 |
| AllocateInventory | O(m) | 遍历订单分配库存 |

**总体复杂度**: O(m × p)，主要由BOM解析决定

---

## 版本历史

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0 | 2026-02-03 | 初始版本，实现部件库存核对功能 |