# 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

```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/Access automation (Windows only)
- `oletools>=0.60` - Alternative VBA extraction without Excel dependency (Excel only)

## Common Commands

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