# VBA 工程规范检查报告

**检查日期**: 2026-05-27  
**项目**: Commuter Allowance Editor (通勤手当テンプレート)  
**VBA 标准**: AGENTS.md 规范

---

## 1. 模块/文件结构检查

| 文件 | 路径 | 状态 | 说明 |
|------|------|------|------|
| Common_Button.bas | tuk/module/ | ✅ | 有 `Option Explicit`，注释头规范 |
| Common_Constants.bas | tuk/module/ | ✅ | 命名正确，常量定义规范 |
| Common_Functions.bas | tuk/module/ | ⚠️ | Module Desc 写的是 `Module_Common`，应为 `Common_Functions` |
| Common_Global_Cache.bas | tuk/module/ | ✅ | 缓存架构清晰 |
| Common_File_Utils.bas | tuk/module/ | ✅ | CSV 处理良好 |
| Common_Selector.bas | tuk/module/ | ✅ | 下拉列表构建器 |
| Common_Shape.bas | tuk/module/ | ❌ | 硬编码了工作表名 `"M1"` 和形状名 |
| Import_modules.bas | tuk/init_module/ | ❌ | 硬编码路径 `D:\Project\upds7\vba\` |
| Test_Cache.bas | tuk/init_module/ | ❌ | 模块名不符合规范（应为 `modTestCache`） |
| Common_Button.bas | juk/module/ | ⚠️ | 只有 10 行，过于简单，缺乏通用性 |
| SQL_Generate.bas | juk/module/ | ⚠️ | Module Desc 缺失 |
| Import_modules.bas | juk/init_module/ | ❌ | 硬编码路径 `D:\Project\upds7\vba\src\sh\juk\module` |

---

## 2. Sheet 类 (cls 文件) 检查

| Sheet | 文件 | 行数 | 状态 | 问题 |
|-------|------|------|------|------|
| C1 | tuk/sheet/C1.cls | 846 | ✅ | 结构良好，事件处理完善 |
| M1 | tuk/sheet/M1.cls | 167 | ✅ | 有 `Worksheet_Change` 和 `Worksheet_BeforeRightClick` |
| M2 | tuk/sheet/M2.cls | 400 | ✅ | Validation 逻辑完整 |
| T1 | tuk/sheet/T1.cls | 54 | ⚠️ | `Worksheet_Change` 是空的，只有 `Validate` |
| T2 | tuk/sheet/T2.cls | 114 | ⚠️ | 同上 |
| T3 | tuk/sheet/T3.cls | 74 | ⚠️ | 同上 |
| O1 | tuk/sheet/O1.cls | 5 | ❌ | `Validate` 是空壳（只有 `Exit Sub`） |
| O2 | tuk/sheet/O2.cls | 6 | ❌ | 同上 |
| O3 | tuk/sheet/O3.cls | 61 | ❌ | 同上 |
| Z1 | tuk/sheet/Z1.cls | 64 | ✅ | 基本完整 |
| Z2 | tuk/sheet/Z2.cls | 54 | ✅ | 基本完整 |
| Z3 | tuk/sheet/Z3.cls | 57 | ✅ | 基本完整 |
| Z4 | tuk/sheet/Z4.cls | - | ✅ | 基本完整 |

---

## 3. 严重问题 (高优先级)

### 3.1 硬编码路径 (违反 AGENTS.md 禁止硬编码规则)

| 文件 | 行号 | 问题代码 |
|------|------|---------|
| Common_Shape.bas | 47 | `sheetName:="M1"` |
| Import_modules.bas (tuk) | 8 | `"D:\Project\upds7\vba\"` |
| Import_modules.bas (tuk) | 9 | `"D:\Project\upds7\vba\src\sh\tuk\module"` |
| ImportJukModules | 7 | `"D:\Project\upds7\vba\src\sh\juk\module"` |

**修改要求**: 路径应从配置文件或常量模块读取，禁止硬编码。

### 3.2 变量未声明

多个 sheet 的 `Validate` 方法中使用 `checkResult`，但 **未声明**：

```vba
' 出现在 T1.cls, T2.cls, T3.cls, Z1.cls, Z2.cls, Z3.cls 中:
checkResult = CheckRequired(...)  ' 缺少: Dim checkResult As Boolean
```

**涉及文件**:
- tuk/sheet/T1.cls
- tuk/sheet/T2.cls
- tuk/sheet/T3.cls
- tuk/sheet/Z1.cls
- tuk/sheet/Z2.cls
- tuk/sheet/Z3.cls

### 3.3 空 Validate 方法

`O1.cls`, `O2.cls`, `O3.cls` 的 `Validate` 是空壳：

```vba
Public Sub Validate(ws As Worksheet, ByVal rowNum As Long, ByVal lastDataRow As Long)
    On Error GoTo ErrHandler
    Exit Sub  ' 实际未做任何验证
ErrHandler:
    lastErrorMsg = Err.Description
End Sub
```

**修改要求**: 实现完整的验证逻辑或删除空方法。

---

## 4. 中优先级问题

### 4.1 命名不一致

| 当前名称 | AGENTS.md 规范 | 应改为 |
|---------|---------------|--------|
| `Test_Cache` | `cls[Noun]` 或 `mod[Noun]` | `clsTestCache` 或 `modTestCache` |
| `Common_Shape` | `mod[Domain][Action]` | `modShapeUtils` |

### 4.2 未使用的参数

```vba
' T1.cls, T2.cls, T3.cls:
Public Sub Validate(ws As Worksheet, ByVal rowNum As Long, ByVal lastDataRow As Long)
    ' lastDataRow 参数从未使用
```

### 4.3 错误处理简陋

`HandleError` 只显示消息，不记录到日志或提供堆栈跟踪：

```vba
Public Sub HandleError(Optional ByVal sourceProcedure As String = "")
    Dim shortCode As String: shortCode = Right("0000" & CStr(Err.Number - vbObjectError), 4)
    MsgBox "[ERROR] " & shortCode & " : " & Err.Description, vbExclamation
    ' 没有写入日志文件，没有堆栈跟踪
End Sub
```

### 4.4 Module Desc 与实际不符

```vba
' Common_Functions.bas 第 4 行:
' Module Desc: Module_Common  (应为 Common_Functions)
```

---

## 5. 低优先级问题

### 5.1 Public 过程缺少注释头

虽然 Module 级别有注释头，但内部 Public Function/Sub 缺少参数/返回值说明：

```vba
' 当前:
Function GetCode(ByVal text As String) As String

' 应为:
' ============================================================
' Function Name: GetCode
' Description: Get left part of MakeSelect format (e.g., "1:JR" -> "1")
' Params: text - Input string in code:value format
' Returns: String - Left part before colon, or full text if no colon
' ============================================================
Function GetCode(ByVal text As String) As String
```

### 5.2 魔法数字/列号缺乏注释

`C1.cls` 中大量使用魔法数字，虽然有常量定义，但注释可更清晰：

```vba
' 当前:
KUKAN_CODE_COLS = Array(19, 27, 35, 43)  ' S, AA, AI, AQ

' 建议:
' S列(19), AA열(27), AI열(35), AQ열(43) - 区分コード
KUKAN_CODE_COLS = Array(19, 27, 35, 43)
```

### 5.3 缺少配置管理模块

所有配置硬编码在 `Common_Global_Cache.bas` 的 `RefreshSheetDict()` 中，建议分离为独立的 `modConfig.bas`。

---

## 6. 修改优先级汇总

| 优先级 | 问题 | 影响 | 涉及文件数 |
|-------|------|------|-----------|
| **高** | 未声明变量 `checkResult` | 运行时错误 | 6 |
| **高** | 硬编码路径 | 不可移植 | 3 |
| **高** | O1/O2/O3 空 Validate | 功能不完整 | 3 |
| **中** | 变量命名不一致 | 代码可读性 | 2 |
| **中** | 错误处理简陋 | 调试困难 | 全部 |
| **中** | 未使用参数 `lastDataRow` | 代码冗余 | 3 |
| **低** | 注释细节缺失 | 维护难度 | 多个 |

---

## 7. 后续行动

- [ ] 修复未声明变量问题
- [ ] 移除硬编码路径，改用配置模块
- [ ] 实现 O1/O2/O3 的 Validate 方法或删除空壳
- [ ] 统一模块命名规范
- [ ] 增强错误处理（添加日志记录）
- [ ] 补充 Public 过程的注释头
- [ ] 考虑分离配置管理到独立模块