From 4b8ba2d14498672b483b9aafd0765f1f021ae64e Mon Sep 17 00:00:00 2001
From: Misaka_Company <pengqiangqiang0@gmail.com>
Date: Mon, 19 Jan 2026 17:39:00 +0800
Subject: [PATCH] add: create CLAUDE.md for project documentation and guidance
 on VBA code extraction and management

---
 CLAUDE.md | 139 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 139 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..74da38c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,139 @@
+# 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.