VBAExtractor/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Auto_BOM is a VBA code extraction and management toolkit for Excel-based Bill of Materials (BOM) processing. The project provides Python tools to extract VBA code from .xlsm files, manage it externally, and import it back into Excel.

The VBA code implements a hierarchical BOM management system with:

• clsBOMManager: Main class managing BOM data structure and category relationships
• clsCategory: Represents material categories with hierarchical parent-child relationships
• clsMaterialItem: Represents individual materials with code, name, quantity, and selection conditions

Directory Structure

Auto_BOM/
├── Excel/              # Source Excel files (.xlsm) - gitignored
├── VBA/                # Extracted VBA code - gitignored
│   ├── Modules/        # Standard modules (.bas)
│   ├── ClassModules/   # Class modules (.cls)
│   ├── DocumentModules/# Sheet/workbook modules (.cls)
│   ├── Forms/          # User forms
│   └── vba_metadata.json # Module metadata for import
├── extract_vba.py      # Extract VBA from Excel files
├── import_vba.py      # Import VBA back to Excel files
├── main.py            # Empty placeholder
└── requirements.txt   # Python dependencies

Development Setup

# Create and activate virtual environment
python -m venv .venv
.venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

Dependencies:

• pywin32>=306 - Windows COM interface for Excel automation (Windows only)
• oletools>=0.60 - Alternative VBA extraction without Excel dependency

Common Commands

Extract VBA Code

# Interactive extraction - will prompt for file and method
python extract_vba.py

Two extraction methods available:

1. COM Interface (recommended) - Requires Microsoft Excel, more reliable
2. olevba Library - No Excel required, uses oletools

For COM method, ensure Excel trusts VBA access:

• Excel > Options > Trust Center > Trust Center Settings
• Check "Trust access to the VBA project object model"

Import VBA Code

# Import from VBA/ directory back to Excel
python import_vba.py VBA/vba_metadata.json

VBA Code Architecture

BOM Data Model

The VBA system implements a hierarchical category-based material management:

1. Two-source loading pattern:

   • [平台配置清单] sheet: Contains all material info (code, name, quantity, condition)
   • [领料配置] sheet: Defines categories and which materials require picking

2. Category hierarchy:

   • Materials organized in parent-child category relationships
   • useParent=True: Pick assembled components from parent category (default)
   • useParent=False: Pick individual parts from child categories (fallback when stock insufficient)

3. Data structures:

   • dictCategories: Dictionary for fast category lookup by name
   • dictAllMaterials: Dictionary for fast material lookup by code
   • rootCategories: Collection of top-level categories for tree traversal

Module Types

• Modules: Standard VBA modules (.bas files)
• ClassModules: Class definitions (.cls files) - clsBOMManager, clsCategory, clsMaterialItem
• DocumentModules: Sheet and workbook code-behind (.cls files)
• Forms: UserForm definitions

Important Implementation Details

VBA Extraction (extract_vba.py)

• Cleans Attribute statements from exported code for readability
• Automatically categorizes modules by type (Standard/Class/Document/Form)
• Generates vba_metadata.json tracking source file, module names, types, and file mappings
• Module type detection based on naming conventions (mod_=Standard, cls=Class, sheet=Document)

VBA Import (import_vba.py)

• Uses Windows COM to interact with Excel
• Critical fix for ClassModules: Reconstructs VERSION 1.0 CLASS header before import
• Encoding handling: Uses GB18030 for temp files to prevent Chinese character corruption
• Path recognition logic handles relative/absolute paths in metadata
• Two import strategies:
  • Modules/ClassModules: Remove and re-import via file
  • DocumentModules/Forms: Update code in-place via string injection

Module Naming Convention

The code determines module type by naming prefix:

• mod_* or mod* → Standard Modules
• cls* or class* → Class Modules
• sheet* or thisworkbook → Document Modules

VS Code Configuration

The .vscode/settings.json associates .cls files with Visual Basic syntax highlighting for better editing experience.

Platform Requirements

• Windows required for import functionality (COM interface)
• Microsoft Excel required for COM-based extraction/import
• Cross-platform extraction possible with oletools (no Excel needed)

Git Workflow

The .gitignore excludes:

• Virtual environment (.venv/)
• Build artifacts (build/, dist/)
• Project data (Excel/, VBA/)
• Claude temporary files (.claude/, tmpclaude-*)

Only commit code changes, not extracted VBA or Excel files.