通勤認定エクセルツール対応12 表示しない対応

documents/checklist-2026-05-27.md

@@ -0,0 +1,194 @@
+# 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 过程的注释头
+- [ ] 考虑分离配置管理到独立模块