vba/documents/checklist-2026-05-27.md

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，但 未声明：

' 出现在 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 是空壳：

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 未使用的参数

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

4.3 错误处理简陋

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

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 与实际不符

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

---

5. 低优先级问题

5.1 Public 过程缺少注释头

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

' 当前:
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 中大量使用魔法数字，虽然有常量定义，但注释可更清晰：

' 当前:
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 过程的注释头
• 考虑分离配置管理到独立模块