docs: add AGENTS.md documentation files

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>
2026-03-11 14:05:56 +08:00
parent 318d1c31f7
commit 787b3f56ab
4 changed files with 516 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,131 @@
+# 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)