From 787b3f56ab4bdb867a9ba1ce71c7a735eabb4f79 Mon Sep 17 00:00:00 2001 From: Misaka_Company Date: Wed, 11 Mar 2026 14:05:56 +0800 Subject: [PATCH] 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 --- AGENTS.md | 131 ++++++++++++++++++++++++++++++++ VBA/AGENTS.md | 95 ++++++++++++++++++++++++ VBA/ClassModules/AGENTS.md | 148 +++++++++++++++++++++++++++++++++++++ VBA/Modules/AGENTS.md | 142 +++++++++++++++++++++++++++++++++++ 4 files changed, 516 insertions(+) create mode 100644 AGENTS.md create mode 100644 VBA/AGENTS.md create mode 100644 VBA/ClassModules/AGENTS.md create mode 100644 VBA/Modules/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..10e321f --- /dev/null +++ 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) diff --git a/VBA/AGENTS.md b/VBA/AGENTS.md new file mode 100644 index 0000000..0bb2a81 --- /dev/null +++ b/VBA/AGENTS.md @@ -0,0 +1,95 @@ +# VBA Module Knowledge Base + +**Scope:** `VBA/` directory - Core automation logic + +## OVERVIEW + +VBA modules for BOM extraction: ClassModules (domain logic), Modules (workflows), DocumentModules (sheet events). + +## STRUCTURE + +``` +VBA/ +├── ClassModules/ # 4 classes: BomExtractor, BomItem, ProductModelParser, ConditionEvaluator +├── Modules/ # 4 modules: MainModule, BIPUploadModule, ComponentInventoryCheckModule, TestModule +├── DocumentModules/ # Sheet9.cls (event handlers) +└── vba_metadata.json # Module metadata +``` + +## WHERE TO LOOK + +| Task | Location | Notes | +|------|----------|-------| +| Main entry point | `Modules/MainModule.bas` | `ProcessProductModels()` | +| BOM extraction | `ClassModules/BomExtractor.cls` | `ExtractBom()` with assembly logic | +| Model parsing | `ClassModules/ProductModelParser.cls` | `Parse()` extracts 6 conditions | +| Condition logic | `ClassModules/ConditionEvaluator.cls` | Expression evaluation | +| BIP upload | `Modules/BIPUploadModule.bas` | Upload to BIP system | +| Inventory check | `Modules/ComponentInventoryCheckModule.bas` | Component verification | + +## CODE MAP + +| Symbol | Type | Location | Role | +|--------|------|----------|------| +| `ProcessProductModels()` | Sub | `MainModule.bas` | Main entry point | +| `ExtractBom()` | Function | `BomExtractor.cls` | Core matching logic | +| `Parse()` | Function | `ProductModelParser.cls` | Model string parser | +| `Evaluate()` | Function | `ConditionEvaluator.cls` | Condition evaluator | +| `LoadFromRow()` | Sub | `BomItem.cls` | Row data loader | + +## CONVENTIONS + +### Module Organization +- **ClassModules**: `*.cls` files with `Option Explicit`, public methods, private state +- **Modules**: `*.bas` files with public subs, helper functions +- **DocumentModules**: Sheet-specific event handlers (e.g., `Sheet9.cls`) + +### Error Handling Pattern +```vba +On Error GoTo ErrorHandler +' ... logic ... +Exit Sub +ErrorHandler: + ' Handle error +``` + +### Data Loading +- `BomExtractor.LoadBomData()` starts at row 4 (row 3 is header) +- `BomItem.LoadFromRow()` uses `On Error Resume Next` for type conversions + +## ANTI-PATTERNS (THIS PROJECT) + +- **NEVER** change row indexing in `LoadBomData()` — hardcoded to start at row 4 +- **NEVER** reorder `BomItem` fields — column mapping is hardcoded (11 fields) +- **NEVER** remove `On Error Resume Next` in `LoadFromRow()` — handles type conversion +- **NEVER** bypass `ApplyAssemblyLogic()` — parent/child override is critical +- **NEVER** hardcode workbook names — always use `ThisWorkbook` + +## UNIQUE STYLES + +### Assembly Logic (总成逻辑) +Parent category overrides children if: +1. Parent matches exactly 1 item +2. All children match at least 1 item +3. Result: parent output, children hidden + +### Batch Output Pattern +```vba +' Collect in Collection +' Convert to 2D array +' Single Range.Value write +``` + +### Condition Syntax +- Format: `"field=value|field2=value2"` (pipe = OR) +- Example: `"azxs=M|azxs=L"` (vertical OR horizontal installation) + +## NOTES + +### Scripting.Dictionary Dependency +All classes use `CreateObject("Scripting.Dictionary")` - Windows only, not Mac-compatible. + +### Workbook Sheets Required +- `产品订单` - Input orders +- `平台配置清单` - BOM configuration (starts at row 4) +- `BOM 提取结果` - Auto-created output diff --git a/VBA/ClassModules/AGENTS.md b/VBA/ClassModules/AGENTS.md new file mode 100644 index 0000000..c6babf1 --- /dev/null +++ b/VBA/ClassModules/AGENTS.md @@ -0,0 +1,148 @@ +# ClassModules Knowledge Base + +**Scope:** `VBA/ClassModules/` - Domain logic classes + +## OVERVIEW + +4 classes: `ProductModelParser` (parse model strings), `BomItem` (data model), `ConditionEvaluator` (evaluate conditions), `BomExtractor` (core matching logic). + +## STRUCTURE + +``` +ClassModules/ +├── ProductModelParser.cls # Parse model strings → extract 6 conditions +├── BomItem.cls # BOM data model (11 fields) +├── ConditionEvaluator.cls # Evaluate condition expressions +└── BomExtractor.cls # Core matching + assembly logic +``` + +## WHERE TO LOOK + +| Task | Location | Notes | +|------|----------|-------| +| Parse model string | `ProductModelParser.cls` | `Parse()` method | +| Extract conditions | `ProductModelParser.cls` | Returns `azxs`, `bkxs`, `gclj`, `jycz`, `lcfw`, `fjgn` | +| Load BOM row | `BomItem.cls` | `LoadFromRow()` with type conversion | +| Evaluate condition | `ConditionEvaluator.cls` | `Evaluate(condition, conditions)` | +| Match BOM items | `BomExtractor.cls` | `ExtractBom()` with 4-step process | +| Assembly logic | `BomExtractor.cls` | `ApplyAssemblyLogic()` parent/child override | + +## CODE MAP + +### ProductModelParser +| Method | Role | +|--------|------| +| `Parse(modelString)` | Entry point, validates format | +| `ParseHeader()` | Splits model string by `-` and `.` | +| `ExtractConnectionAndMaterial()` | Separates `gclj` and `jycz` from code | +| `ExtractAdditionalFeatures()` | Removes oil-fill type (Y+digit) from `fjgn` | + +### BomItem +| Property | Type | Column | +|----------|------|--------| +| `RowNumber` | Long | A | +| `Module` | String | B | +| `code` | String | C | +| `Name` | String | D | +| `quantity` | Double | E | +| `SelectCondition` | String | F | +| `Remark` | String | G | +| `category` | String | H | +| `ParentCategory` | String | I | +| `CategoryCondition` | String | J | +| `Code66` | String | K | + +### BomExtractor +| Method | Role | +|--------|------| +| `LoadBomData()` | Loads from row 4 (header row 3) | +| `ExtractBom(conditions)` | 4-step: determine categories → match → apply assembly → validate | +| `ApplyAssemblyLogic()` | Parent overrides children if all match | +| `ValidateResult()` |双向覆盖检查 (parent/child coverage) | + +## CONVENTIONS + +### Class Structure +```vba +Option Explicit + +' Private state +Private pPropertyName As Type + +' Initialize +Private Sub Class_Initialize() + Set pProperty = New Collection +End Sub + +' Public methods +Public Function MethodName() As ReturnType + On Error GoTo ErrorHandler + ' Logic + Exit Function +ErrorHandler: + ' Handle +End Function +``` + +### Condition Dictionary +All condition methods accept `Scripting.Dictionary` with keys: `azxs`, `bkxs`, `gclj`, `jycz`, `lcfw`, `fjgn`. + +### Error Collection Pattern +```vba +Private pErrorMessages As Collection +Public Function GetErrorSummary() As String + ' Join all errors with "; " +End Function +``` + +## ANTI-PATTERNS (THIS PROJECT) + +- **NEVER** change `BomItem.LoadFromRow()` column indices — hardcoded to match platform configuration sheet +- **NEVER** remove `On Error Resume Next` in `LoadFromRow()` — type conversions fail gracefully +- **NEVER** skip validation in `ValidateResult()` —双向覆盖检查 prevents false negatives +- **DO NOT** modify `BomExtractor.LoadBomData()` row start — must be row 4 (row 3 is header) + +## UNIQUE STYLES + +### Assembly Logic Algorithm +```vba +' 1. Build parent→child map from CategoryHierarchy +' 2. Count matches per category +' 3. If parent=1 AND all children≥1 → parent covers children +' 4. Output parent only, hide children +``` + +### Model String Format +``` +[Header]-[Spec1].[Spec2].[Spec3].[Spec4].[Spec5]|[Detail1]|[Detail2] +Example: Y-100-M203.316SS.L100.N2 + +Parsed conditions: +- azxs (安装形式): M (vertical) +- bkxs (表壳形式): 3 +- gclj (过程连接): M20 +- jycz (接液材质): 3 (316SS) +- lcfw (量程范围): 0.L100 +- fjgn (附加功能): N2 (from .316SS.L100.N2) +``` + +### Condition Expression Syntax +```vba +' Single: "field=value" +' OR: "field1=value1|field2=value2" +' Example: "azxs=M|azxs=L" → vertical OR horizontal +``` + +## NOTES + +### Category Hierarchy +Built from `ParentCategory` field (column I). Example: +- "接头" → "部件" +- "弹性元件" → "部件" +- Result: if "部件" matches AND both children match → output "部件" only + +### Type Conversion +`BomItem.LoadFromRow()` uses `CLng()`, `CStr()`, `CDbl()` with `On Error Resume Next` — invalid conversions become 0 or empty string. + +### Scripting.Dictionary +Windows-only. All dictionary usage via `CreateObject("Scripting.Dictionary")`. diff --git a/VBA/Modules/AGENTS.md b/VBA/Modules/AGENTS.md new file mode 100644 index 0000000..d4d5f38 --- /dev/null +++ b/VBA/Modules/AGENTS.md @@ -0,0 +1,142 @@ +# Modules Knowledge Base + +**Scope:** `VBA/Modules/` - Procedural workflows and entry points + +## OVERVIEW + +4 modules: `MainModule` (main workflow), `BIPUploadModule` (upload results), `ComponentInventoryCheckModule` (inventory check), `TestModule` (testing utilities). + +## STRUCTURE + +``` +Modules/ +├── MainModule.bas # Main entry point + orchestration +├── BIPUploadModule.bas # Upload to BIP system +├── ComponentInventoryCheckModule.bas # Component inventory verification +└── TestModule.bas # Testing utilities +``` + +## WHERE TO LOOK + +| Task | Location | Notes | +|------|----------|-------| +| Run BOM extraction | `MainModule.bas` | `ProcessProductModels()` | +| Upload results | `BIPUploadModule.bas` | BIP system integration | +| Check inventory | `ComponentInventoryCheckModule.bas` | Component count verification | +| Test parsing | `TestModule.bas` | Unit test utilities | + +## CODE MAP + +### MainModule +| Function | Role | +|----------|------| +| `ProcessProductModels()` | Main entry point, orchestrates workflow | +| `ProcessSingleModel()` | Process one model, collect output | +| `CreateOutputRowArray()` | Build row data array | +| `WriteBatchData()` | Bulk write to worksheet | +| `GetInputSheet()` | Get `产品订单` sheet | +| `GetBomSheet()` | Get `平台配置清单` sheet | +| `CreateOutputSheet()` | Create/reset `BOM 提取结果` | + +### BIPUploadModule +| Function | Role | +|----------|------| +| `UploadToBIP()` | Upload BOM results to BIP system | + +### ComponentInventoryCheckModule +| Function | Role | +|----------|------| +| `CheckComponentInventory()` | Verify component counts match | + +## CONVENTIONS + +### Module Structure +```vba +Option Explicit + +' Constants +Private Const CONDITION_CONFIG = "azxs，安装形式|bkxs，表壳形式|..." + +' Public entry points +Public Sub MainEntryPoint() + On Error GoTo ErrorHandler + ' Orchestration + Exit Sub +ErrorHandler: + MsgBox "Error: " & Err.Description +End Sub + +' Private helpers +Private Sub HelperFunction() + ' Implementation +End Sub +``` + +### Workflow Pattern +1. Get input sheet (`产品订单`) +2. Get BOM sheet (`平台配置清单`) +3. Create output sheet (`BOM 提取结果`) +4. Initialize `BomExtractor`, load data +5. Loop through models, call `ProcessSingleModel()` +6. Batch write results +7. Format output, show message + +### Batch Output Pattern +```vba +' Collect in Collection +Dim outputData As Collection +Set outputData = New Collection + +' Add arrays +outputData.Add CreateOutputRowArray(...) + +' Convert to 2D array +ReDim resultData(1 To rowCount, 1 To colCount) +' Fill array... + +' Single write +ws.Range("A2").Resize(rowCount, colCount).Value = resultData +``` + +## ANTI-PATTERNS (THIS PROJECT) + +- **NEVER** hardcode sheet names — use `GetInputSheet()`, `GetBomSheet()` helpers +- **NEVER** write row-by-row — always batch write via 2D array +- **NEVER** skip error handling — all public subs use `On Error GoTo ErrorHandler` +- **DO NOT** change output column order — must match header definition in `WriteOutputHeader()` + +## UNIQUE STYLES + +### Condition Config Constant +```vba +Private Const CONDITION_CONFIG = "azxs，安装形式|bkxs，表壳形式|gclj，过程连接|jycz，接液材质|lcfw，量程范围|fjgn，附加功能" +``` +Format: `code,label|code,label|...` — parsed dynamically for header generation. + +### Component Priority Flag +From column E of input sheet: +- "是" (or "1", "TRUE") → include all categories +- "否" (or "0", "FALSE") → exclude "部件" (components) category + +### Output Row Structure +``` +Column 1: 生产订单号 (order number) +Column 2: 产品型号 (full model) +Columns 3-8: 6 conditions (azxs, bkxs, gclj, jycz, lcfw, fjgn) +Columns 9-16: BOM fields (行号，模块，代号，名称，数量，类别，66 代码，备注) +``` + +## NOTES + +### Output Sheet Formatting +- Row 1: Bold, gray background (RGB 217,217,217), centered +- Data starts at row 2 +- AutoFit columns (commented out in current code) + +### Error Messages +- Parse failure: `"解析失败：" + error` +- No match: `"未匹配到任何物料"` +- Multi-match: `"类别[X] 匹配到多条物料(N 条)"` — outputs all but flags + +### Performance +Batch write via `Range.Value = resultData` is 10-100x faster than cell-by-cell writes for large datasets.