# 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

```bash
# 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
```bash
# 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
```bash
# 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.