docs: update CLAUDE.md to document both BOM systems as functional modules

- Clearly separate BOM Configuration System (M01-M05) and BOM Extraction System (M06-M09) - Update Project Overview to describe both functional modules - Update Architecture section to present both systems with their respective modules - Update Data Flow to show separate workflows for each system - Rewrite Key Concepts section with clear separation between systems - Update Development Commands for both BOM Converter and BOM Extractor - Update Configuration section with complete system constants for both systems - Update File Structure to accurately reflect VBA_BOMConverter/ directory layout - Update Important Notes to cover both systems' specific features Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-12 16:25:52 +08:00
parent 78241f2b8d
commit 157595a169
1 changed files with 244 additions and 13 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,13 +4,16 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

 ## Project Overview

-AutoBOM is an Excel-based Bill of Materials (BOM) management system for pressure product manufacturing. It uses VBA macros to parse conditional logic rules and generate categorized BOM configurations from Excel spreadsheets.
+AutoBOM is an Excel-based Bill of Materials (BOM) management system for pressure product manufacturing. The project includes TWO functional modules:
+
+1. **BOM Configuration System** (VBA/) - Parses conditional logic rules and generates categorized BOM configurations from Excel spreadsheets based on "平台配置清单" worksheet
+2. **BOM Extraction System** (VBA_BOMConverter/) - Parses product model strings and automatically extracts matching materials from BOM库.xlsx based on "产品型号" worksheet

 ## Architecture

-### Core VBA Modules (VBA/Modules/)
+### BOM Configuration System (VBA/Modules/)

-The system follows a modular architecture with clear separation of concerns:
+The BOM Configuration system follows a modular architecture with clear separation of concerns:

 - **M01_Main.bas** - Entry point and orchestration. Run `RunBOMConversion()` to execute the full workflow.
 - **M02_DataIO.bas** - Data input/output operations. Reads source data from "平台配置清单" worksheet and generates categorized output workbooks.
@@ -19,12 +22,23 @@ The system follows a modular architecture with clear separation of concerns:
 - **M05_PreProcessor.bas** - Preprocessing module for condition transformation. Handles category-specific preprocessing: "接头" (azxs+lcfw mapping, OR merging, parentheses simplification), "部件" (azxs mapping only, OR merging, parentheses simplification). Uses mapping data from "对照表" worksheet.
 - **M99_TestRunner.bas** - Unit testing framework. Run `RunAllTests()` in VBA Immediate window to execute tests.

+### BOM Extraction System (VBA_BOMConverter/Modules/)
+
+The BOM Extraction system follows a modular architecture with clear separation of concerns:
+
+- **M09_BOMExtractor.bas** - Main orchestration and entry point. Run `RunBOMExtraction()` to execute the full workflow. Implements two-phase validation (collect → validate) and generates output worksheets.
+- **M06_ModelParser.bas** - Product model string parsing. Extracts parameters from full model strings (e.g., `YTHN-100.A0.531.G123.M04.Y3|BP-088.2312.B09.0A3`).
+- **M07_BOMMatcher.bas** - BOM library matching. Matches extracted parameters against BOM库.xlsx worksheets using parameter-based rules (empty cells = wildcard, "!=" prefix = negative match, fjgn field = substring matching).
+- **M08_ComponentProcessor.bas** - Special handling for "部件" (component) materials. Handles component inventory logic (component vs sub-components selection).
+- **M06B_TestRunner.bas** - Unit testing framework for BOM Extraction system. Run tests in VBA Immediate window.
+
 ### Class Module

- **clsErrorLogger.cls** - Error handling and logging. Tracks conflicts, parsing failures, and provides detailed context without stopping execution.
+- **clsErrorLogger.cls** - Error and warning handling. Tracks conflicts, parsing failures, and provides detailed context. Supports both errors (blocking) and warnings (non-blocking) with color-coded reporting.

 ### Data Flow

+**BOM Configuration System Flow**:
 ```
 Excel "平台配置清单" → M01_Main → M02_DataIO.LoadSourceData() →
 M05_PreProcessor.PreprocessCondition() → M03_Logic.ParseRule() →
@@ -32,8 +46,22 @@ Category Dictionary → M02_DataIO.CreateOutputWorkbook() →
 New Excel Workbook + Error Report
 ```

+**BOM Extraction System Flow**:
+```
+"产品型号" worksheet → M09_BOMExtractor.RunBOMExtraction()
+  → M06_ModelParser.ParseProductModel() (extract parameters: azxs, bkxs, gclj, jycz, lcfw, fjgn)
+  → M07_BOMMatcher.MatchBOMRecord() (match in BOM库.xlsx worksheets)
+  → M08_ComponentProcessor.ProcessComponentRecord() (special component handling if applicable)
+  → Two-phase validation (collect all matches → validate with cross-worksheet rules)
+  → "BOM提取结果" worksheet + "错误报告" worksheet
+```
+
 ## Key Concepts

+---
+
+## BOM Configuration System (VBA/)
+
 ### Preprocessing (M05_PreProcessor)

 Before parsing conditions, the system applies category-specific preprocessing:
@@ -66,7 +94,7 @@ Before parsing conditions, the system applies category-specific preprocessing:

 Mapping data is loaded from "对照表" worksheet (columns A:B for lcfw, D:E for azxs).

-### Conditional Logic Syntax
+### Conditional Logic Syntax (M03_Logic)

 Conditions use a specific syntax for product selection:
 - **Atoms**: `key=value` or `key!=value` (e.g., `gclj=M20`, `jycz=1`)
@@ -91,17 +119,121 @@ Data starts from row 4.

 Results are automatically organized by category (部件, 接头, 弹性元件, etc.). Each category gets a separate worksheet in the output workbook with columns dynamically ordered based on detected configuration keys.

+---
+
+## BOM Extraction System (VBA_BOMConverter/)
+
+### Model String Structure (M06_ModelParser)
+
+Product models follow a structured format that the parser can extract parameters from:
+
+**Full Model**: `[表头]|[表盘]|[附件]|[法兰隔膜]`
+
+**Table Header Format**: `[型号]-[公称外径].[安装形式].[壳体形式].[过程连接&接液材质].[量程范围].[仪表特性]`
+
+**Example**: `YTHN-100.A0.531.G123.M04.Y3|BP-088.2312.B09.0A3`
+- Table header: `YTHN-100.A0.531.G123.M04.Y3`
+- Parameters extracted:
+  - `xh` = YTHN (型号)
+  - `gcwj` = 100 (公称外径)
+  - `azxs` = A0 (安装形式)
+  - `bkxs` = 531 (表壳形式)
+  - `gclj` = G12 (过程连接)
+  - `jycz` = 3 (接液材质)
+  - `lcfw` = M04 (量程范围)
+  - `fjgn` = Y3 (附加功能)
+
+**Parsing Logic**:
+- Only processes table header portion (before first `|`)
+- Segments are split by `.` delimiter
+- `gclj` and `jycz` are extracted from single segment (last char is `jycz`)
+- `fjgn` combines all segments from position 5 onwards with comma separator
+
+### BOM Matching Rules (M07_BOMMatcher)
+
+The system matches extracted parameters against BOM库.xlsx worksheets using these rules:
+
+**Cell Matching Rules**:
+- **Empty cell**: Wildcard - matches all values
+- **"!=" prefix**: Negative match - matches when parameter ≠ value (e.g., `!=A0`)
+- **fjgn field**: Substring matching - matches when fjgn list contains cell value (InStr check)
+- **Normal values**: Exact match - parameter must equal cell value
+
+**Logic**: AND across all parameters - all conditions must be satisfied
+
+**Example**: BOM库 row has `azxs=A0`, `bkxs=`, `gclj=G12`, `fjgn=N1`
+- Matches: `azxs=A0`, `bkxs=531`, `gclj=G12`, `fjgn=N1,N2`
+- Reason: `azxs` matches exactly, `bkxs` is empty (wildcard), `gclj` matches exactly, `fjgn` contains "N1"
+
+### Component Special Handling (M08_ComponentProcessor)
+
+"部件" (component) materials contain three types of materials in one record:
+
+**Record Structure**:
+1. Component material itself (部件)
+2. Joint material (接头) - sub-component 1
+3. Elastic element material (弹性元件) - sub-component 2
+
+**Selection Strategy**:
+- **Inventory sufficient** → Return component material (1 item)
+- **Inventory insufficient** → Return sub-components (1 joint + 1 elastic element)
+
+**Validation Rules**:
+- Valid: 1 component OR 1 joint + 1 elastic element
+- Invalid: Any other combination (e.g., component + joint together, only joint, only element, multiple components)
+
+**Note**: Inventory checking interface is reserved for future ERP integration. Current version always returns inventory sufficient.
+
+### Two-Phase Validation (M09_BOMExtractor)
+
+The system uses two-phase validation to enable cross-worksheet validation:
+
+**Phase 1: Collection**
+- Iterate through all BOM库 worksheets
+- Collect match results WITHOUT recording errors
+- Store results for each worksheet: success, rowCount, rowNums, materials
+
+**Phase 2: Validation**
+- Validate all collected results together
+- Apply cross-worksheet rules (e.g., component/joint/element exclusivity)
+- Distinguish between **errors** (blocking) and **warnings** (non-blocking)
+
+**Cross-Worksheet Validation Rules**:
+1. **Component sheet returns component** → Ignore independent joint/element worksheets (warning)
+2. **Component sheet returns sub-components** → Ignore independent joint/element worksheets (warning)
+3. **Component sheet has no match** → Use independent joint/element worksheets
+4. **Non-special worksheets** → Must match exactly 1 record
+
+**Error vs Warning**:
+- **Error**: Blocking issues (0 matches, 2+ matches, invalid combinations)
+- **Warning**: Non-blocking issues (conflicting matches that were resolved)
+
 ## Development Commands

-### Running the BOM Converter
+### Running BOM Configuration System

 1. Open `YTHN-100.xlsm` in Excel
 2. Ensure "平台配置清单" worksheet exists with proper data
 3. Run `M01_Main.RunBOMConversion()` or execute from the Excel interface

+**Output**: New Excel workbook with categorized BOM data + error report
+
+### Running BOM Extraction System
+
+1. Open the main Excel workbook (e.g., `YTHN-100.xlsm`)
+2. Ensure "产品型号" worksheet exists with product model data
+3. Ensure `BOM库.xlsx` is in the same directory as the main workbook
+4. Run `M09_BOMExtractor.RunBOMExtraction()` or execute from the Excel interface
+
+**Output**:
+- "BOM提取结果" worksheet - Contains extracted materials with parameters
+- "错误报告_[timestamp]" worksheet - Generated only if errors/warnings exist
+
 ### Running Tests

 In Excel VBA Immediate Window (Ctrl+G):
+
+**For BOM Configuration System (M99_TestRunner)**:
 ```
 RunAllTests
 ```
@@ -125,6 +257,17 @@ This runs unit tests for:
  - "部件" category OR merging (PP_11)
  - "部件" category parentheses simplification (PP_12)

+**For BOM Extraction System (M06B_TestRunner)**:
+```
+RunAllTests
+```
+
+This runs unit tests for:
+- M06_ModelParser tests (model string parsing)
+- M07_BOMMatcher tests (BOM library matching)
+- M08_ComponentProcessor tests (component handling)
+- M09_BOMExtractor tests (full extraction workflow)
+
 ### Python Skills (Claude Code Integration)

 The project includes custom skills in `.claude/skills/`:
@@ -138,6 +281,40 @@ The project includes custom skills in `.claude/skills/`:

 ## Configuration

+### System Constants (M04_Config)
+
+**File Configuration**:
+- `BOMLIB_FILENAME` = "BOM库.xlsx" - BOM library file name
+- `OUTPUT_SHEET_NAME` = "BOM提取结果" - Output worksheet name
+- `BOMLIB_START_ROW` = 2 - BOM库 data starts from row 2 (row 1 is header)
+
+**Input Column Configuration**:
+- `INPUT_COL_MODEL` = "型号"
+- `INPUT_COL_PRODUCT_MODEL` = "产品型号"
+
+**BOM库 Worksheet Names**:
+- `BOMLIB_SHEET_JOINT` = "接头"
+- `BOMLIB_SHEET_ELEMENT` = "弹性元件"
+- `BOMLIB_SHEET_MOVEMENT` = "机芯"
+- `BOMLIB_SHEET_COMPONENT` = "部件"
+- `BOMLIB_SHEET_EDGE` = "边"
+
+**BOM库 Column Names**:
+- `BOMLIB_COL_NAME` = "名称"
+- `BOMLIB_COL_CODE` = "编码"
+- `BOMLIB_COL_QTY` = "数量"
+- `BOMLIB_COL_JOINT_NAME` = "接头名称"
+- `BOMLIB_COL_JOINT_CODE` = "接头编码"
+- `BOMLIB_COL_JOINT_QTY` = "接头数量"
+- `BOMLIB_COL_ELEMENT_NAME` = "弹性元件名称"
+- `BOMLIB_COL_ELEMENT_CODE` = "弹性元件编码"
+- `BOMLIB_COL_ELEMENT_QTY` = "弹性元件数量"
+
+**Model Parsing Constants**:
+- `MODEL_SEPARATOR_PIPELINE` = "|"
+- `MODEL_SEPARATOR_DOT` = "."
+- `MODEL_HEADER_MIN_SEGMENTS` = 6
+
 ### Header Priority Ordering

 Output columns are sorted according to priority defined in `M04_Config.GetHeaderPriority()`:
@@ -184,9 +361,21 @@ The repository uses NTFY for git push notifications. Repository name is extracte

 ```
 AutoBOM/
-├── VBA/
-│   ├── Modules/          # Procedural modules (M01-M99)
-│   └── ClassModules/     # OOP components (clsErrorLogger)
+├── VBA_BOMConverter/
+│   ├── Modules/
+│   │   ├── M01_Main.bas              # BOM Configuration System - Entry point
+│   │   ├── M02_DataIO.bas            # BOM Configuration System - Data I/O
+│   │   ├── M03_Logic.bas             # BOM Configuration System - Conditional logic parser
+│   │   ├── M04_Config.bas            # Shared - Constants and configuration
+│   │   ├── M05_PreProcessor.bas       # BOM Configuration System - Preprocessing
+│   │   ├── M06_ModelParser.bas       # BOM Extraction System - Model parsing
+│   │   ├── M06B_TestRunner.bas      # BOM Extraction System - Unit tests
+│   │   ├── M07_BOMMatcher.bas       # BOM Extraction System - BOM matching
+│   │   ├── M08_ComponentProcessor.bas # BOM Extraction System - Component handling
+│   │   ├── M09_BOMExtractor.bas      # BOM Extraction System - Main orchestration
+│   │   └── M99_TestRunner.bas       # BOM Configuration System - Unit tests
+│   └── ClassModules/
+│       └── clsErrorLogger.cls        # Shared - Error/warning logging
 ├── .claude/
 │   └── skills/           # Claude Code integration skills
 ├── docs/                 # Code-related documentation
@@ -197,18 +386,60 @@ AutoBOM/

 ## Error Handling

-The system uses `clsErrorLogger` for comprehensive error tracking:
- Errors are logged but do not stop processing
- Final error report is generated in the output workbook
- Context is preserved for debugging (row number, expression, details)
+The system uses `clsErrorLogger` for comprehensive error and warning tracking:
+
+**Error vs Warning Distinction**:
+- **Errors**: Blocking issues that indicate failure (red highlighting in report)
+  - Examples: No match found, multiple matches, invalid combinations
+  - Properties: `HasErrors`, `pErrors.Count`
+- **Warnings**: Non-blocking issues (yellow highlighting in report)
+  - Examples: Conflicting matches that were resolved, fallback scenarios
+  - Properties: `HasWarnings`, `pWarnings.Count`
+- **HasIssues**: True if either errors or warnings exist
+
+**Error Recording**:
+```vba
+' Record error
+logger.Record rowIndex, sourceFunction, errorType, description, context
+
+' Record warning
+logger.RecordWarning rowIndex, sourceFunction, warningType, description, context
+```
+
+**Error Report Output**:
+- Creates "错误报告_[timestamp]" worksheet
+- Color-coded rows: red for errors, yellow for warnings
+- Columns: Type, Row Number, Source Module, Error Type, Description, Context
+- Only generated if issues exist

 ## Important Notes

+### BOM Configuration System
+
 - **Late Binding**: VBA modules use late binding (CreateObject) to avoid external reference dependencies
 - **Operator Precedence**: AND is processed before OR, parentheses override default precedence
 - **Recursive Parsing**: Nested expressions are handled recursively in M03_Logic
 - **Dynamic Columns**: Output workbooks detect and include only relevant configuration keys

+### BOM Extraction System
+
+- **rowCount vs materials.count**: Critical distinction in BOM matching
+  - `rowCount` = Number of worksheet rows matched in BOM库
+  - `materials.count` = Number of actual materials returned
+  - These can differ when components fall back to sub-components (1 row → 2 materials)
+
+- **Performance Optimizations**:
+  - Array-based processing instead of cell-by-cell operations
+  - Header mapping cached for each worksheet
+  - Progress updates every 10 models
+  - Screen updating and calculation disabled during execution
+
+- **Two-Phase Matching**: Separates collection from validation to enable cross-worksheet validation rules that would be impossible with immediate error reporting
+
+- **Late Binding**: VBA modules use late binding (CreateObject) to avoid external reference dependencies
+
+- **Dynamic Columns**: Output workbooks detect and include only relevant configuration keys based on extracted parameters
+
 ## Documentation Guidelines

 ### Document Storage Policy