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 (Excel) and .accdb (Access) files, manage it externally, and import it back.

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
├── Access/             # Source Access files (.accdb) - 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/Access files
├── import_vba.py      # Import VBA back to Excel/Access 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/Access automation (Windows only)
• oletools>=0.60 - Alternative VBA extraction without Excel dependency (Excel only)

Common Commands

Extract VBA Code

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

Excel (.xlsm) - Two extraction methods available:

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

Access (.accdb) - Only COM Interface supported (requires Microsoft Access)

For COM method, ensure the application 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 or Access
python import_vba.py

Set TARGET_FILE in .env to the target .xlsm or .accdb file path.

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)
• Module type detection based on naming conventions (mod_=Standard, cls=Class, sheet=Document)
• Auto-detects file type by extension (.xlsm → Excel, .accdb → Access)

VBA Import (import_vba.py)

• Uses Windows COM to interact with Excel or Access
• 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 Excel COM-based extraction/import
• Microsoft Access required for Access COM-based extraction/import
• Cross-platform extraction possible with oletools (Excel only, no Office needed)

Git Workflow

The .gitignore excludes:

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

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