AutoBOM/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

AutoBOM is an Excel-based Bill of Materials (BOM) management system for pressure product manufacturing. It uses VBA macros to parse conditional logic rules and generate categorized BOM configurations from Excel spreadsheets.

## Architecture

### Core VBA Modules (VBA/Modules/)

The system follows a modular architecture with clear separation of concerns:

- **M01_Main.bas** - Entry point and orchestration. Run `RunBOMConversion()` to execute the full workflow.
- **M02_DataIO.bas** - Data input/output operations. Reads source data from "平台配置清单" worksheet and generates categorized output workbooks.
- **M03_Logic.bas** - Core recursive parser for conditional expressions. Handles logical operators (AND/OR), nested parentheses, and key=value/key!=val conditions. Implements Cartesian products for set operations.
- **M04_Config.bas** - Column mapping and header priorities. Defines source data columns (CODE, NAME, QTY, CONDITION, CATEGORY) and standard ordering for output.
- **M05_PreProcessor.bas** - Preprocessing module for condition transformation. Handles category-specific preprocessing: "接头" (azxs+lcfw mapping, OR merging, parentheses simplification), "部件" (azxs mapping only, OR merging, parentheses simplification). Uses mapping data from "对照表" worksheet.
- **M99_TestRunner.bas** - Unit testing framework. Run `RunAllTests()` in VBA Immediate window to execute tests.

### Class Module

- **clsErrorLogger.cls** - Error handling and logging. Tracks conflicts, parsing failures, and provides detailed context without stopping execution.

### Data Flow

```
Excel "平台配置清单" → M01_Main → M02_DataIO.LoadSourceData() →
M05_PreProcessor.PreprocessCondition() → M03_Logic.ParseRule() →
Category Dictionary → M02_DataIO.CreateOutputWorkbook() →
New Excel Workbook + Error Report
```

## Key Concepts

### Preprocessing (M05_PreProcessor)

Before parsing conditions, the system applies category-specific preprocessing:

**Supported Categories**:

| Category | azxs Mapping | lcfw Mapping | OR Merging | Parentheses Simplification |
|----------|-------------|--------------|------------|----------------------------|
| 接头     | ✓           | ✓            | ✓          | ✓                          |
| 部件     | ✓           | ✗            | ✓          | ✓                          |
| Other    | ✗           | ✗            | ✗          | ✗                          |

**Value Mapping**:
- **azxs** (安装形式): Maps codes to descriptive values
  - A0, AT, AH → 径向
  - B0, BT, BZ, BH → 下轴向
  - Z0, ZT, ZZ, ZH → 中轴向
- **lcfw** (量程范围): Maps range codes to categories (接头 category only)
  - M01-M11 → 低压
  - M12-M16 → 高压

**OR Condition Merging**:
- Duplicate OR conditions are automatically merged
- Example: `azxs=径向 OR azxs=径向` → `azxs=径向`
- Different values preserve OR structure: `lcfw=低压 OR lcfw=高压`

**Parentheses Handling**:
- Simplified single-value expressions: `(azxs=A0 OR azxs=AT)` → `azxs=径向`
- Preserves parentheses when needed: `(lcfw=M01 OR lcfw=M15)` → `(lcfw=低压 OR lcfw=高压)`

Mapping data is loaded from "对照表" worksheet (columns A:B for lcfw, D:E for azxs).

### Conditional Logic Syntax

Conditions use a specific syntax for product selection:
- **Atoms**: `key=value` or `key!=value` (e.g., `gclj=M20`, `jycz=1`)
- **AND**: Cartesian product of sets (e.g., `gclj=M20 AND jycz=1`)
- **OR**: Union of sets (e.g., `azxs=A0 OR azxs=AT`)
- **Parentheses**: Nested grouping (e.g., `(azxs=A0 OR azxs=AT) AND jycz=1`)

Example: `gclj=M20 AND jycz=1 AND lcfw=M01 AND (azxs=A0 OR azxs=AT OR azxs=AH)`

### Column Mapping (M04_Config)

Source data must have columns in this order:
- Column C (3): CODE (代号)
- Column D (4): NAME (名称)
- Column E (5): QTY (数量)
- Column F (6): CONDITION (选择条件)
- Column H (8): CATEGORY (类别)

Data starts from row 4.

### Category-Based Output

Results are automatically organized by category (部件, 接头, 弹性元件, etc.). Each category gets a separate worksheet in the output workbook with columns dynamically ordered based on detected configuration keys.

## Development Commands

### Running the BOM Converter

1. Open `YTHN-100.xlsm` in Excel
2. Ensure "平台配置清单" worksheet exists with proper data
3. Run `M01_Main.RunBOMConversion()` or execute from the Excel interface

### Running Tests

In Excel VBA Immediate Window (Ctrl+G):
```
RunAllTests
```

This runs unit tests for:
- Simple atom parsing (`key=value`)
- AND operations with Cartesian products
- OR operations with union operations
- Nested parentheses handling
- Logic conflict detection
- **Preprocessing tests** (Test_PP_01 to Test_PP_12):
  - azxs mapping load (12 values)
  - lcfw mapping load (M01-M16)
  - Value replacement
  - OR condition merging
  - Full integration with M03_Logic
  - Non-"接头"/"部件" category handling
  - Unmapped value handling
  - "部件" category azxs mapping (PP_09)
  - "部件" category lcfw unchanged (PP_10)
  - "部件" category OR merging (PP_11)
  - "部件" category parentheses simplification (PP_12)

### Python Skills (Claude Code Integration)

The project includes custom skills in `.claude/skills/`:

- **excel-to-markdown**: Convert Excel files to Markdown tables
  ```bash
  python3 .claude/skills/excel-to-markdown/scripts/excel_to_markdown.py <file.xlsx>
  ```

- **mermaid-diagrams**: Generate architecture diagrams using Mermaid syntax

## Configuration

### Header Priority Ordering

Output columns are sorted according to priority defined in `M04_Config.GetHeaderPriority()`:
1. azxs (安装形式)
2. bkxs (表壳形式)
3. gclj (过程连接)
4. jycz (介质材质)
5. lcdw (量程单位)
6. lcfw (量程范围)
7. fjgn (非公/耐震)
8. btcy (表头尺寸)
9. bp (表盘)
10. dskd (度视宽度)
11. nqlc (耐震连接)
12. bptx (表盘图形)
13. jddj (精度等级)
14. cpdm (产品代码)
15. tsjz (特殊基准)
16. tsyq (特殊要求)
17. bpts (特殊表盘)
18. kdxh (壳体型号)

Unknown keys are assigned priority 999 and appear last.

## Git Workflow

### Branches

- **Main branch**: `DEV_YTHN-100`
- **Current branch**: `NEW_BOM`

### Claude Code Permissions

Configured in `.claude/settings.local.json`:
- Git operations: push, checkout, add
- Python execution
- Tree viewing and search utilities

### NTFY Notifications

The repository uses NTFY for git push notifications. Repository name is extracted dynamically from `github.repository` in workflow files.

## File Structure

```
AutoBOM/
├── VBA/
│   ├── Modules/          # Procedural modules (M01-M99)
│   └── ClassModules/     # OOP components (clsErrorLogger)
├── .claude/
│   └── skills/           # Claude Code integration skills
├── docs/                 # Code-related documentation
│   └── Test_PP_06_FullIntegration_流程详解.md
├── reference_docs/       # Business-related documentation and examples
└── YTHN-100.xlsm/.xlsx  # Main workbook files
```

## Error Handling

The system uses `clsErrorLogger` for comprehensive error tracking:
- Errors are logged but do not stop processing
- Final error report is generated in the output workbook
- Context is preserved for debugging (row number, expression, details)

## Important Notes

- **Late Binding**: VBA modules use late binding (CreateObject) to avoid external reference dependencies
- **Operator Precedence**: AND is processed before OR, parentheses override default precedence
- **Recursive Parsing**: Nested expressions are handled recursively in M03_Logic
- **Dynamic Columns**: Output workbooks detect and include only relevant configuration keys

## Documentation Guidelines

### Document Storage Policy

When creating documentation for this project, follow these guidelines:

**Code-Related Documentation** → Save in `docs/` directory:
- Technical specifications
- Algorithm explanations
- Code flow diagrams
- Test documentation
- API/reference documentation for code modules
- Implementation guides

Examples:
- `docs/Test_PP_06_FullIntegration_流程详解.md` ✓
- `docs/M03_Logic_Algorithm.md` ✓
- `docs/API_Reference.md` ✓

**Business-Related Documentation** → Save in `reference_docs/` directory:
- Business requirements
- User manuals
- Product specifications
- Industry standards
- Configuration examples
- Business process documentation

Examples:
- `reference_docs/BOM_Requirements.md` ✓
- `reference_docs/Product_Catalog.xlsx` ✓
- `reference_docs/User_Guide.pdf` ✓

**Decision Tree**:
```
Is it about code implementation or technical details?
├─ Yes → docs/
└─ No → Is it about business logic or user-facing content?
    ├─ Yes → reference_docs/
    └─ No → Ask for clarification
```

**Note**: When in doubt, prefer `docs/` for technical content and `reference_docs/` for business content.