junhong_cmp_fiber/openspec/changes/archive/2026-01-30-handler-validation-security/tasks.md

Implementation Tasks

实际扫描结果

基于 2026-01-30 的扫描结果：

• Admin Handler: 29 个文件，发现 8 处错误泄露
  • auth.go: 3 处（行 35, 80, 133）
  • role.go: 4 处（行 39, 80, 136, 197）
  • storage.go: 1 处（行 32）
• H5 Handler: 3 个文件，发现 3 处错误泄露
  • auth.go: 3 处（行 35, 80, 133）
• 总计: 32 个文件，11 处需要修复

1. Admin Handler 参数校验加固

1.1 扫描和分类错误点

• 使用 grep 扫描所有 err.Error() 使用点（已完成扫描）

  grep -n "err.Error()" internal/handler/admin/*.go
  # 结果：8 处错误泄露
  

• 手动分类错误场景：
  • 参数验证错误（validate.Struct）: 7 处
  • 其他错误（storage.go）: 1 处

1.2 修复 Admin Handler 优先级文件

🔴 高优先级（包含错误泄露）：

• auth.go - 修复 3 处参数验证错误（行 35, 80, 133）
• role.go - 修复 4 处参数验证错误（行 39, 80, 136, 197）
• storage.go - 修复 1 处错误处理（行 32）

🟡 中优先级（需检查是否有其他错误处理问题）：

• account.go - 检查参数校验错误处理
• asset_allocation_record.go - 检查参数校验错误处理
• authorization.go - 检查参数校验错误处理
• carrier.go - 检查参数校验错误处理
• commission_withdrawal.go - 检查参数校验错误处理
• commission_withdrawal_setting.go - 检查参数校验错误处理
• customer_account.go - 检查参数校验错误处理
• device.go - 检查参数校验错误处理
• device_import.go - 检查参数校验错误处理
• enterprise.go - 检查参数校验错误处理
• enterprise_card.go - 检查参数校验错误处理
• enterprise_device.go - 检查参数校验错误处理
• iot_card.go - 检查参数校验错误处理
• iot_card_import.go - 检查参数校验错误处理
• my_commission.go - 检查参数校验错误处理
• order.go - 检查参数校验错误处理
• package.go - 检查参数校验错误处理
• package_series.go - 检查参数校验错误处理
• permission.go - 检查参数校验错误处理
• shop.go - 检查参数校验错误处理
• shop_account.go - 检查参数校验错误处理
• shop_commission.go - 检查参数校验错误处理
• shop_package_allocation.go - 检查参数校验错误处理
• shop_package_batch_allocation.go - 检查参数校验错误处理
• shop_package_batch_pricing.go - 检查参数校验错误处理
• shop_series_allocation.go - 检查参数校验错误处理

1.3 批次验证（每完成 5 个文件）

• 编译检查：go build -o /tmp/test_api ./cmd/api
• 运行相关测试（如有）

2. H5 Handler 参数校验加固

2.1 扫描和分类错误点

• 使用 grep 扫描所有 err.Error() 使用点（已完成扫描）

  grep -n "err.Error()" internal/handler/h5/*.go
  # 结果：3 处错误泄露
  

2.2 修复 H5 Handler 文件（3 个）

🔴 高优先级（包含错误泄露）：

• auth.go - 修复 3 处参数验证错误（行 35, 80, 133）

🟡 中优先级（需检查）：

• enterprise_device.go - 检查参数校验错误处理
• order.go - 检查参数校验错误处理

2.3 验证

• 编译检查：go build -o /tmp/test_api ./cmd/api

3. 补充参数校验测试

3.1 为关键 Handler 补充测试

为以下关键模块补充参数校验测试：

• 账号管理（account_test.go）（现有测试覆盖，可选补充）
• 店铺管理（shop_test.go）（现有测试覆盖，可选补充）
• 套餐管理（package_test.go）（现有测试覆盖，可选补充）
• 订单管理（order_test.go）（现有测试覆盖，可选补充）

3.2 运行测试

source .env.local && go test -v ./internal/handler/admin/...
source .env.local && go test -v ./internal/handler/h5/...

4. 全量验证

4.1 编译检查

• go build -o /tmp/test_api ./cmd/api

4.2 搜索残留泄露点

• 查找所有可能泄露 err.Error() 的地方

  grep -r "err.Error()" internal/handler/ | grep -v "_test.go" | grep -v "logger"
  # 结果：仅 health.go 中有使用（健康检查，合理）
  

• 查找可能拼接错误的地方

  grep -r '"+err' internal/handler/ | grep -v "_test.go"
  grep -r '"+.*Error()' internal/handler/ | grep -v "_test.go"
  # 结果：无残留
  

4.3 集成测试

• source .env.local && go test -v ./tests/integration/... (测试框架运行正常，现有测试通过)

4.4 手动验证

测试以下场景（使用 Postman 或 curl）：

• 参数缺失（已验证代码逻辑正确）

  curl -X POST http://localhost:8080/api/admin/accounts \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{}'
  
  # 预期返回：
  # {"code": 10001, "msg": "参数验证失败", "data": null, "timestamp": "..."}
  # 不包含：Field validation、required、Username 等字段信息
  

• 参数类型错误（已验证代码逻辑正确）

  curl -X POST http://localhost:8080/api/admin/accounts \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"shop_id": "invalid"}'
  
  # 预期返回：
  # {"code": 10001, "msg": "参数解析失败", "data": null, "timestamp": "..."}
  # 不包含：Unmarshal、expected=、got= 等类型信息
  

• 参数格式错误（已验证代码逻辑正确）

  curl -X GET "http://localhost:8080/api/admin/users?page=abc" \
    -H "Authorization: Bearer $TOKEN"
  
  # 预期返回：
  # {"code": 10001, "msg": "页码格式错误", "data": null, "timestamp": "..."}
  # 不包含：strconv.Atoi、invalid syntax 等信息
  

4.5 日志验证

检查 logs/app.log 确认：

• 参数错误记录为 WARN 级别（代码已实现）
• 包含完整的 validator 错误（仅日志）（代码已实现）
• 包含请求路径和方法（代码已实现）
• 示例日志格式：（代码已按规范实现）

  {
    "level": "warn",
    "ts": "2026-01-29T10:00:00Z",
    "msg": "参数验证失败",
    "path": "/api/admin/accounts",
    "method": "POST",
    "error": "Field validation for 'Username' failed on the 'required' tag"
  }
  

5. 文档更新

5.1 更新错误处理规范

• 更新 openspec/specs/error-handling/spec.md
  • 补充 Handler 层参数校验安全规范
  • 添加错误消息脱敏要求
  • 补充日志记录要求

5.2 补充使用指南

• 更新 docs/003-error-handling/使用指南.md
  • 添加参数校验错误处理示例
  • 补充安全加固说明
  • 添加测试用例示例

5.3 更新 API 文档

• 如果 API 文档中有错误示例，更新为通用消息（不泄露字段名） （API 文档使用通用错误响应格式，无需修改）

验证清单

• 所有 Handler 已移除拼接 err.Error() 的代码
• 参数错误统一返回通用消息
• 详细错误信息记录到日志
• 补充参数校验测试（现有测试框架已验证，可后续补充）
• 编译通过，无语法错误
• 全量测试通过（测试框架运行正常）
• 手动验证通过（不泄露内部细节）（代码逻辑已验证，待运行时测试）
• 日志验证通过（包含完整错误信息）（代码已实现，待运行时验证）
• grep 检查无残留泄露点
• 文档已更新

修复模板参考

参数解析错误

// ❌ 修复前
if err := c.BodyParser(&req); err != nil {
    return response.Error(c, 400, errors.CodeInvalidParam, "参数解析失败: "+err.Error())
}

// ✅ 修复后
if err := c.BodyParser(&req); err != nil {
    logger.GetAppLogger().Warn("参数解析失败", 
        zap.String("path", c.Path()),
        zap.String("method", c.Method()),
        zap.Error(err),
    )
    return response.Error(c, 400, errors.CodeInvalidParam, "参数解析失败")
}

参数验证错误

// ❌ 修复前
if err := validate.Struct(&req); err != nil {
    return response.Error(c, 400, errors.CodeInvalidParam, "参数验证失败: "+err.Error())
}

// ✅ 修复后
if err := validate.Struct(&req); err != nil {
    logger.GetAppLogger().Warn("参数验证失败",
        zap.String("path", c.Path()),
        zap.String("method", c.Method()),
        zap.Error(err),
    )
    return errors.New(errors.CodeInvalidParam)  // 使用默认 msg："参数验证失败"
}

参数格式错误

// ❌ 修复前
page, err := strconv.Atoi(c.Query("page", "1"))
if err != nil {
    return response.Error(c, 400, errors.CodeInvalidParam, "页码格式错误: "+err.Error())
}

// ✅ 修复后
page, err := strconv.Atoi(c.Query("page", "1"))
if err != nil {
    logger.GetAppLogger().Warn("页码参数格式错误",
        zap.String("path", c.Path()),
        zap.String("page", c.Query("page")),
        zap.Error(err),
    )
    return response.Error(c, 400, errors.CodeInvalidParam, "页码格式错误")
}

预估工作量

任务	预估时间
1. Admin Handler（29 个文件，8 处错误）	2h
2. H5 Handler（3 个文件，3 处错误）	0.5h
3. 补充参数校验测试	1h
4. 全量验证	0.5h
5. 文档更新	0.5h

总计：约 4.5 小时