From 157595a169f72d6354baedc1338dd45a612fad5c Mon Sep 17 00:00:00 2001 From: Misaka_Company Date: Thu, 12 Feb 2026 16:25:52 +0800 Subject: [PATCH] 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 --- CLAUDE.md | 257 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 244 insertions(+), 13 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index fa85a4b..1239be7 100644 --- 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