787b3f56ab
Add comprehensive AGENTS.md documentation files across the project structure to document the agent architecture and capabilities. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
132 lines
5.2 KiB
Markdown
132 lines
5.2 KiB
Markdown
# AutoBOM Knowledge Base
|
||
|
||
**Generated:** 2026-03-11
|
||
**Stack:** VBA (Excel) + Python automation
|
||
|
||
## OVERVIEW
|
||
|
||
VBA-based BOM extraction system that parses product model strings and matches components from a platform configuration list. Core workflow: parse model → extract conditions → match BOM items → export results.
|
||
|
||
## STRUCTURE
|
||
|
||
```
|
||
AutoBOM/
|
||
├── VBA/ # Core VBA modules
|
||
│ ├── ClassModules/ # Data models + logic classes
|
||
│ ├── Modules/ # Entry points + workflows
|
||
│ └── DocumentModules/ # Sheet-specific code
|
||
├── docs/ # Flowcharts + execution plans
|
||
├── reference_docs/ # External product references
|
||
└── *.xlsm/*.xlsx # Excel workbooks with embedded macros
|
||
```
|
||
|
||
## WHERE TO LOOK
|
||
|
||
| Task | Location | Notes |
|
||
|------|----------|-------|
|
||
| Parse product model | `VBA/ClassModules/ProductModelParser.cls` | Extracts conditions from model string |
|
||
| Match BOM items | `VBA/ClassModules/BomExtractor.cls` | Core matching logic with assembly hierarchy |
|
||
| BOM data model | `VBA/ClassModules/BomItem.cls` | Row structure for platform configuration |
|
||
| Condition evaluation | `VBA/ClassModules/ConditionEvaluator.cls` | Evaluates selection conditions |
|
||
| Main workflow | `VBA/Modules/MainModule.bas` | `ProcessProductModels()` entry point |
|
||
| BIP upload | `VBA/Modules/BIPUploadModule.bas` | Upload results to BIP system |
|
||
| Component check | `VBA/Modules/ComponentInventoryCheckModule.bas` | Inventory verification |
|
||
| Excel→Markdown | `.claude/skills/excel-to-markdown/scripts/excel_to_markdown.py` | Python utility |
|
||
|
||
## CODE MAP
|
||
|
||
### Core Classes
|
||
|
||
| Symbol | Type | Location | Role |
|
||
|--------|------|----------|------|
|
||
| `BomExtractor` | Class | `ClassModules/BomExtractor.cls` | Extracts matching BOM items based on conditions |
|
||
| `BomItem` | Class | `ClassModules/BomItem.cls` | Data model for BOM row (11 fields) |
|
||
| `ProductModelParser` | Class | `ClassModules/ProductModelParser.cls` | Parses model string like `Y-100-M203.316SS` |
|
||
| `ConditionEvaluator` | Class | `ClassModules/ConditionEvaluator.cls` | Evaluates condition expressions |
|
||
| `MainModule` | Module | `Modules/MainModule.bas` | Orchestrates end-to-end workflow |
|
||
|
||
### Key Functions
|
||
|
||
| Function | Location | Description |
|
||
|----------|----------|-------------|
|
||
| `ProcessProductModels()` | `MainModule.bas` | Main entry point |
|
||
| `ExtractBom(conditions)` | `BomExtractor.cls` | Returns matched `Collection` of `BomItem` |
|
||
| `Parse(modelString)` | `ProductModelParser.cls` | Extracts `azxs`, `bkxs`, `gclj`, `jycz`, `lcfw`, `fjgn` |
|
||
| `Evaluate(condition, conditions)` | `ConditionEvaluator.cls` | Returns `Boolean` match result |
|
||
|
||
## CONVENTIONS
|
||
|
||
### VBA Structure
|
||
- **ClassModules**: Domain logic classes (`*.cls`)
|
||
- **Modules**: Procedural workflows (`*.bas`)
|
||
- **DocumentModules**: Sheet-specific event handlers (`Sheet9.cls`)
|
||
|
||
### Model String Format
|
||
```
|
||
[Header]-[Spec1].[Spec2].[Spec3].[Spec4].[Spec5]|[Detail1]|[Detail2]
|
||
Example: Y-100-M203.316SS.L100.N2
|
||
```
|
||
|
||
### Condition Config
|
||
```vba
|
||
Private Const CONDITION_CONFIG = "azxs，安装形式|bkxs，表壳形式|gclj，过程连接|jycz，接液材质|lcfw，量程范围|fjgn，附加功能"
|
||
```
|
||
|
||
## ANTI-PATTERNS (THIS PROJECT)
|
||
|
||
- **DO NOT** modify row indexing in `BomExtractor.LoadBomData()` — starts at row 4 (header is row 3)
|
||
- **DO NOT** change `BomItem` field order — hardcoded column mapping in `LoadFromRow()`
|
||
- **DO NOT** remove `On Error Resume Next` in `BomItem.LoadFromRow()` — handles type conversion failures
|
||
- **NEVER** skip assembly logic in `ApplyAssemblyLogic()` — handles parent/child component hierarchy
|
||
- **NEVER** hardcode workbook names — use `ThisWorkbook` reference
|
||
|
||
## UNIQUE STYLES
|
||
|
||
### Assembly Logic (Parent/Child Override)
|
||
If parent category matches (e.g., "部件") AND all children match (e.g., "接头", "弹性元件"), parent overrides children in output. Controlled by `ApplyAssemblyLogic()`.
|
||
|
||
### Batch Output Pattern
|
||
Results collected in `Collection` → converted to 2D array → single `Range.Value` write for performance.
|
||
|
||
### Condition Expression Syntax
|
||
```vba
|
||
' Format: "field=value" or "field1=value1|field2=value2"
|
||
' Example: "azxs=M|azxs=L" (vertical OR horizontal)
|
||
```
|
||
|
||
## COMMANDS
|
||
|
||
### Python Virtual Environment
|
||
```bash
|
||
# Activate (Windows)
|
||
.venv\Scripts\activate
|
||
|
||
# Run Excel→Markdown converter
|
||
python .claude/skills/excel-to-markdown/scripts/excel_to_markdown.py input.xlsx -o output.md
|
||
```
|
||
|
||
### Excel Macros
|
||
```
|
||
1. Open *.xlsm workbook
|
||
2. Press Alt+F11 to open VBA editor
|
||
3. Run: MainModule.ProcessProductModels
|
||
```
|
||
|
||
## NOTES
|
||
|
||
### Workbook Requirements
|
||
- Input sheet: `产品订单` (product orders)
|
||
- BOM sheet: `平台配置清单` (platform configuration)
|
||
- Output sheet: `BOM 提取结果` (auto-created)
|
||
|
||
### Git Configuration
|
||
`.gitignore` excludes `*.xlsm`, `*.xlsx`, `*.png`, `.venv/`, `build/`, `dist/`. Binary Excel files not tracked.
|
||
|
||
### ConditionEvaluator Dependencies
|
||
VBA `Scripting.Dictionary` required (Windows only). Not compatible with Mac Excel.
|
||
|
||
### Error Handling
|
||
- Parse failures → `extractNote = "解析失败：..."`
|
||
- No matches → `extractNote = "未匹配到任何物料"`
|
||
- Multi-match → logged but outputs all (data quality flag)
|