194 lines
6.4 KiB
Markdown
194 lines
6.4 KiB
Markdown
# 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 过程的注释头
|
||
- [ ] 考虑分离配置管理到独立模块 |