docs: expand AutoBOM architecture and implementation details
Refine project overview to include specific business context (Blaidy Company) and the main workbook file. Restructure the architecture section into a layered object-oriented design (Data, Processing, Application layers) and define the responsibilities of core VBA classes. Add new technical documentation sections covering: - Model number format parsing structure - Condition expression language syntax - Category hierarchy logic and picking strategies - Material matching pipeline flow Include VBA code examples for key methods such as CollectAllMaterials and GetMaterialsByCategoryAndModel to illustrate recursive traversal and material retrieval logic. Clarify the structure of key Excel configuration sheets.
This commit is contained in:
Misaka_Company
165
CLAUDE.md
165
CLAUDE.md
@@ -4,84 +4,135 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
|
||||
## Project Overview
|
||||
|
||||
AutoBOM is an Excel VBA-based Bill of Materials (BOM) Management System for manufacturing environments. It manages material hierarchies and procurement logic, supporting both assembled components and individual parts sourcing strategies.
|
||||
**AutoBOM** is an automated Bill of Materials (BOM) management system for industrial pressure gauge products at 布莱迪公司 (Blaidy Company). The system parses complex product model numbers, extracts material requirements based on specifications, and generates picking lists for manufacturing.
|
||||
|
||||
The main Excel file is `YTHN-100.A0.532-BOM-1.2版 Claude.xlsm` (macro-enabled workbook), which contains both the VBA code and the business data.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Classes (VBA/ClassModules/)
|
||||
### Core Components (Layered Object-Oriented Design)
|
||||
|
||||
- **clsBOMManager** - Central controller managing the entire BOM data structure
|
||||
- Loads data from two Excel worksheets: "领料配置" (Configuration) and "平台配置清单" (Platform Configuration)
|
||||
- Builds hierarchical category trees with parent-child relationships
|
||||
- Provides material querying interfaces
|
||||
- Key methods: `LoadData()`, `GetMaterialsForPicking()`, `GetCategory()`
|
||||
**Data Layer** (Class Modules)
|
||||
- `clsMaterialItem` - Individual material entity
|
||||
- `clsCategory` - Hierarchical category container with parent-child relationships
|
||||
- `clsBOMManager` - Central controller managing the entire BOM data structure
|
||||
|
||||
- **clsCategory** - Represents material categories with hierarchical relationships
|
||||
- Contains collections of materials and sub-categories
|
||||
- Tracks parent category for tree navigation
|
||||
- Properties: `categoryName`, `ParentCategoryName`, `Materials`, `SubCategories`, `IsLeafCategory`
|
||||
**Processing Layer** (Class Modules)
|
||||
- `clsModelParser` - Parses complex product model strings into structured components
|
||||
- `clsConditionExtractor` - Extracts selection conditions from parsed models
|
||||
- `clsConditionMatcher` - Evaluates logical expressions for material matching
|
||||
|
||||
- **clsMaterialItem** - Represents individual material items
|
||||
- Properties: `code` (物料代号), `Name` (物料名称), `Quantity`, `Condition` (选择条件), `Category`, `ParentCategory`
|
||||
**Application Layer** (Standard Modules)
|
||||
- `modBOMProcessor` - BOM operations and usage examples
|
||||
- `modModelParserTest` - Comprehensive test suite (6 test functions)
|
||||
- `modModelParserExamples` - Real-world usage examples
|
||||
|
||||
### Data Structure Design
|
||||
### Model Number Format
|
||||
|
||||
The system uses a dual-layer approach:
|
||||
1. **dictAllMaterials** - Complete material database loaded from platform configuration sheet
|
||||
2. **dictCategories** - Hierarchical category structure with materials filtered by configuration sheet
|
||||
Product models follow this structure:
|
||||
```
|
||||
[Model]-[Diameter].[Install].[Shell].[Connection].[Range].[Char]|[Dial]|[Accessory]|[Flange]
|
||||
```
|
||||
|
||||
Only materials appearing in the "领料配置" worksheet are marked for procurement. Materials in the platform database but not in configuration are ignored.
|
||||
Example: `YTHN-100.A0.532.M203.M16.Y3|BP-095.2312.M16.PA3`
|
||||
|
||||
### Business Logic
|
||||
The parser uses recursive descent parsing with structure validation.
|
||||
|
||||
**Dual-Sourcing Strategy** (via `GetMaterialsForPicking(categoryName, useParent)`):
|
||||
### Condition Expression Language
|
||||
|
||||
- **Parent Mode** (`useParent=True`): Retrieves parent category materials (assembled components)
|
||||
- Default procurement method
|
||||
- Example: "低压接头部件" (Low-pressure connector assembly)
|
||||
Materials are selected using logical expressions with variables:
|
||||
- `gclj` (过程连接 - process connection)
|
||||
- `jycz` (接液材质 - liquid contact material)
|
||||
- `lcfw` (量程范围 - range)
|
||||
|
||||
- **Child Mode** (`useParent=False`): Retrieves child category materials (individual parts)
|
||||
- Used when parent materials are insufficient
|
||||
- Recursively expands all sub-categories
|
||||
- Example: "径向低压接头" + "弹簧管" + "螺旋管" (individual components)
|
||||
Supported operators: `AND`, `OR`, `!=`, parentheses
|
||||
|
||||
## Running the Code
|
||||
Example: `lcfw=M16 AND gclj!=M20 OR (lcfw=M02 AND gclj=Z12)`
|
||||
|
||||
1. Open `YTHN-100.A0.532-BOM-1.2版 Claude.xlsm` in Microsoft Excel
|
||||
2. Enable macros when prompted
|
||||
3. Press Alt+F8 to open the Macro dialog
|
||||
4. Run procedures from modBOMProcessor.bas:
|
||||
- `TestBOMStructure` - Test data loading and verify structure
|
||||
- `GeneratePickingList` - Generate procurement lists to new worksheet
|
||||
- `GetCategoryMaterials` - Demo material retrieval logic
|
||||
- `QueryMaterialInfo` - Query specific category information
|
||||
### Category Hierarchy Logic
|
||||
|
||||
## Data Worksheet Format
|
||||
The system supports two picking strategies:
|
||||
1. **Parent Category Mode** (default): Pick assembled components
|
||||
2. **Child Category Mode** (fallback): Pick individual parts for assembly
|
||||
|
||||
**领料配置** (Configuration):
|
||||
- Column A: 物料代号 (Material Code)
|
||||
- Column C: 类别 (Category)
|
||||
- Column D: 上层类别 (Parent Category)
|
||||
- Row 1: Header, data starts from row 2
|
||||
Recursive tree traversal is used for material collection through the category hierarchy.
|
||||
|
||||
**平台配置清单** (Platform Configuration):
|
||||
- Column C: 代号 (Code)
|
||||
- Column D: 名称 (Name)
|
||||
- Column E: 数量 (Quantity)
|
||||
- Column F: 选择条件 (Selection Condition)
|
||||
- Rows 1-3: Headers, data starts from row 4
|
||||
### Material Matching Pipeline
|
||||
|
||||
## VBA Metadata
|
||||
```
|
||||
Model String → Parser → Extractor → Conditions Dictionary → Matcher → Filtered Materials
|
||||
```
|
||||
|
||||
The VBA module structure is tracked in `VBA/vba_metadata.json`. This file is automatically maintained and should not be manually edited.
|
||||
## Data Sheets Structure
|
||||
|
||||
## Code Style
|
||||
The Excel workbook contains two key sheets:
|
||||
|
||||
- All comments are in Chinese, explaining business logic and data structures
|
||||
- Extensive inline documentation for complex logic
|
||||
- Dictionary objects used for O(1) lookups by category name and material code
|
||||
- Collection objects used for ordered iteration of materials and categories
|
||||
**领料配置** (Picking Configuration)
|
||||
- Defines category hierarchy
|
||||
- Specifies which materials require picking
|
||||
- Columns: 物料代号, 类别名称, 上层类别名称
|
||||
|
||||
## Version Control
|
||||
**平台配置清单** (Platform Configuration)
|
||||
- Complete material database
|
||||
- Rows 1-3: Headers
|
||||
- Row 4+: Data
|
||||
|
||||
The `.gitignore` excludes `.xlsm` files from version control. Only VBA source code and metadata files are tracked in Git.
|
||||
## Testing
|
||||
|
||||
Run tests from the VBA editor or Excel macros:
|
||||
|
||||
- **All tests**: `RunAllTests()` in `modModelParserTest`
|
||||
- **Individual tests**: Test1-Test6 functions in `modModelParserTest`
|
||||
- Test1: Model parser basic functionality
|
||||
- Test2: Condition extractor
|
||||
- Test3: Condition matcher (14 test cases)
|
||||
- Test4: Full workflow test
|
||||
- Test5: All categories matching
|
||||
- Test6: Extraction rules display
|
||||
|
||||
## Development Workflow
|
||||
|
||||
1. Edit VBA code in Excel VBA Editor (Alt+F11)
|
||||
2. Export modules to `VBA/` directory
|
||||
3. Update `VBA/vba_metadata.json` when adding/removing modules
|
||||
4. Commit changes to git
|
||||
|
||||
**Note**: The main Excel workbook (*.xlsm) is excluded from git by .gitignore.
|
||||
|
||||
## Code Conventions
|
||||
|
||||
**Naming**
|
||||
- Classes: `cls` prefix (e.g., `clsBOMManager`)
|
||||
- Modules: `mod` prefix (e.g., `modBOMProcessor`)
|
||||
- Public properties: PascalCase
|
||||
- Local variables: camelCase
|
||||
|
||||
**Comments**
|
||||
- Section headers: `' ========================================`
|
||||
- Chinese comments for business logic (domain-specific)
|
||||
- English comments for technical implementation
|
||||
- Detailed parameter/return value documentation
|
||||
|
||||
**Error Handling**
|
||||
- `On Error GoTo ErrorHandler` pattern
|
||||
- Conservative: return `Nothing` or `False` on error
|
||||
|
||||
## Key Business Logic
|
||||
|
||||
- Materials have "selection conditions" expressed as logical formulas
|
||||
- Not all materials in platform config require picking (filtered by "领料配置" sheet)
|
||||
- Supports "部件" (component) vs "零件" (part) picking strategies
|
||||
- Condition extraction is data-driven (new variables can be added)
|
||||
- Category tree can have arbitrary depth
|
||||
|
||||
## Documentation
|
||||
|
||||
- `布莱迪公司压力表产品选型大表.md` - Complete product model numbering system (716 lines, Chinese)
|
||||
- `VBA/clsBOMManager使用说明.md` - API documentation and usage examples for clsBOMManager (546 lines, Chinese)
|
||||
|
||||
## Module Registry
|
||||
|
||||
`VBA/vba_metadata.json` maps VBA module names to their file locations in the repository. Update this file when:
|
||||
- Adding new class modules or standard modules
|
||||
- Renaming existing modules
|
||||
- Reorganizing the directory structure
|
||||
|
||||
Reference in New Issue
Block a user