146 lines
5.5 KiB
Markdown
146 lines
5.5 KiB
Markdown
# 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.
|