junhong_cmp_fiber/openspec/changes/archive/2026-01-30-code-cleanup-docs-update/tasks.md

Implementation Tasks

1. 移除任务模块占位代码

1.1 删除文件

• 删除 internal/routes/task.go

  rm internal/routes/task.go
  

• 删除 internal/handler/admin/task.go

  rm internal/handler/admin/task.go
  

1.2 移除引用

• 打开 internal/routes/routes.go
• 移除 registerTaskRoutes(...) 调用
• 移除相关 import（如果不再使用）

1.3 验证

• 编译检查：go build -o /tmp/test_api ./cmd/api
• 确认无 TaskHandler 引用：

  grep -r "TaskHandler" internal/ | grep -v "_test.go"
  # 应无结果
  

2. 清理注释一致性

2.1 扫描残留路径

• 查找所有 /api/v1 注释：

  grep -rn "/api/v1" internal/handler/ | grep -v "_test.go" > /tmp/path_comments.txt
  cat /tmp/path_comments.txt
  

2.2 批量修复注释

• 根据 /tmp/path_comments.txt 逐个修复：
  • /api/v1/users → /api/admin/users
  • /api/v1/shops → /api/admin/shops
  • /api/v1/orders → /api/admin/orders 或 /api/h5/orders
  • 等等

2.3 验证清理结果

• 再次扫描：

  grep -r "/api/v1" internal/handler/ | grep -v "_test.go"
  # 应无结果
  

3. 更新规范文档

3.1 更新错误处理规范

• 打开 openspec/specs/error-handling/spec.md

• 补充 Purpose 说明：

  ## Purpose
  
  统一项目的错误处理机制，确保：
  - 错误码一致性和可追踪性
  - 客户端能准确识别错误类型
  - 日志记录完整便于排查
  - 避免泄露内部实现细节
  

• 新增"错误报错规范"章节：

  ## 错误报错规范（必须遵守）
  
  ### Handler 层
  - ❌ 禁止直接返回/拼接底层错误信息给客户端
  - ✅ 参数校验失败统一返回 `errors.New(CodeInvalidParam)`
  - ✅ 详细校验错误写日志，对外返回通用消息
  
  ### Service 层
  - ❌ 禁止对外返回 `fmt.Errorf(...)`
  - ✅ 业务错误使用 `errors.New(code[, msg])`
  - ✅ 系统错误使用 `errors.Wrap(code, err[, msg])`
  
  ### 示例
  [补充实际代码示例]
  

3.2 更新 AGENTS.md

• 打开 AGENTS.md

• 在"错误处理"章节补充摘要：

  #### 错误报错规范（必须遵守）
  - Handler 层禁止直接返回/拼接底层错误信息（例如 `"参数验证失败: "+err.Error()`）
  - 参数校验失败：对外统一返回 `errors.New(CodeInvalidParam)`（详细错误写日志）
  - Service 层禁止对外返回 `fmt.Errorf(...)`，必须返回 `errors.New(...)` 或 `errors.Wrap(...)`
  

• 补充 Code Review 检查清单：

  ## Code Review 检查清单
  
  ### 错误处理
  - [ ] Service 层无 `fmt.Errorf` 对外返回
  - [ ] Handler 层参数校验不泄露细节
  - [ ] 错误码使用正确（4xx vs 5xx）
  - [ ] 错误日志完整（包含上下文）
  

3.3 更新使用指南

• 打开 docs/003-error-handling/使用指南.md

• 补充 Service 层错误处理实际案例：

  ## Service 层错误处理
  
  ### 业务校验错误（4xx）
  
  #### 示例 1：资源不存在
  [从实际代码中提取]
  
  #### 示例 2：状态不允许
  [从实际代码中提取]
  
  ### 系统依赖错误（5xx）
  
  #### 示例 3：数据库错误
  [从实际代码中提取]
  

• 补充 Handler 层参数校验案例：

  ## Handler 层参数校验
  
  ### 参数解析错误
  [补充安全加固后的代码示例]
  
  ### 参数验证错误
  [补充安全加固后的代码示例]
  

• 补充单元测试示例：

  ## 错误场景单元测试
  
  ### Service 层测试
  [补充测试代码示例]
  
  ### Handler 层测试
  [补充集成测试示例]
  

4. CI 检查增强

4.1 创建检查脚本

• 创建文件：scripts/check-service-errors.sh

  #!/bin/bash
  # 检查 Service 层是否使用 fmt.Errorf 对外返回
  
  echo "🔍 检查 Service 层错误处理规范..."
  
  FILES=$(find internal/service -name "*.go" -type f)
  VIOLATIONS=$(grep -n "fmt\.Errorf" $FILES | grep -v "// whitelist:")
  
  if [ -n "$VIOLATIONS" ]; then
      echo ""
      echo "❌ 发现 Service 层使用 fmt.Errorf："
      echo "$VIOLATIONS"
      echo ""
      echo "请使用以下方式替代："
      echo "  - 业务错误：errors.New(code, msg)"
      echo "  - 系统错误：errors.Wrap(code, err, msg)"
      echo ""
      echo "如果某处确实需要使用 fmt.Errorf（如内部调试），请添加注释：// whitelist:"
      exit 1
  fi
  
  echo "✅ Service 层错误处理检查通过"
  

• 添加执行权限：

  chmod +x scripts/check-service-errors.sh
  

4.2 创建注释检查脚本（可选）

• 创建文件：scripts/check-comment-paths.sh

  #!/bin/bash
  # 检查注释中的 API 路径是否一致
  
  echo "🔍 检查注释中的 API 路径..."
  
  VIOLATIONS=$(grep -rn "/api/v1" internal/handler/ | grep -v "_test.go")
  
  if [ -n "$VIOLATIONS" ]; then
      echo ""
      echo "❌ 发现残留的 /api/v1 路径注释："
      echo "$VIOLATIONS"
      echo ""
      echo "请修复为真实路径（/api/admin、/api/h5、/api/c/v1）"
      exit 1
  fi
  
  echo "✅ 注释路径检查通过"
  

• 添加执行权限：

  chmod +x scripts/check-comment-paths.sh
  

4.3 创建统一检查脚本

• 创建文件：scripts/check-all.sh

  #!/bin/bash
  # 运行所有代码规范检查
  
  set -e
  
  echo "🚀 运行代码规范检查..."
  echo ""
  
  bash scripts/check-service-errors.sh
  bash scripts/check-comment-paths.sh
  
  echo ""
  echo "✅ 所有检查通过"
  

• 添加执行权限：

  chmod +x scripts/check-all.sh
  

4.4 测试检查脚本

• 运行 Service 错误检查：

  bash scripts/check-service-errors.sh
  # 应返回 ✅（假设已完成提案 1 和 2）
  

• 测试脚本能检测违规：

  echo 'return fmt.Errorf("test")' >> internal/service/test.go
  bash scripts/check-service-errors.sh  # 应返回 ❌
  rm internal/service/test.go
  

• 运行注释路径检查：

  bash scripts/check-comment-paths.sh
  # 应返回 ✅
  

• 运行全部检查：

  bash scripts/check-all.sh
  

4.5 集成到 CI（可选）

• 创建/更新 .github/workflows/lint.yml：

  name: Code Quality Check
  
  on:
    push:
      branches: [ main, develop ]
    pull_request:
      branches: [ main, develop ]
  
  jobs:
    lint:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v3
  
        - name: Set up Go
          uses: actions/setup-go@v4
          with:
            go-version: '1.25'
  
        - name: Run Code Quality Checks
          run: bash scripts/check-all.sh
  

5. 全量验证

5.1 代码清理验证

• 确认文件已删除：

  ls internal/routes/task.go  # 应返回 No such file
  ls internal/handler/admin/task.go  # 应返回 No such file
  

• 确认引用已移除：

  grep -r "registerTaskRoutes" internal/  # 应无结果
  grep -r "TaskHandler" internal/ | grep -v "_test.go"  # 应无结果
  

5.2 注释清理验证

• 确认无残留 /api/v1 注释：

  grep -r "/api/v1" internal/handler/ | grep -v "_test.go"  # 应无结果
  

5.3 编译检查

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

5.4 CI 检查验证

• 运行所有检查脚本：

  bash scripts/check-all.sh  # 应返回 ✅
  

5.5 文档完整性检查

• 确认规范文档已更新：

  grep "错误报错规范" openspec/specs/error-handling/spec.md
  grep "错误报错规范" AGENTS.md
  grep "Service 层错误处理" docs/003-error-handling/使用指南.md
  

• 确认文档包含实际案例（非空占位）

6. README 更新（可选）

6.1 补充 CI 检查说明

• 在 README.md 中补充"代码规范检查"章节：

  ## 代码规范检查
  
  运行代码规范检查：
  
  \`\`\`bash
  # 检查 Service 层错误处理
  bash scripts/check-service-errors.sh
  
  # 检查注释路径一致性
  bash scripts/check-comment-paths.sh
  
  # 运行所有检查
  bash scripts/check-all.sh
  \`\`\`
  
  这些检查会在 CI/CD 流程中自动执行。
  

验证清单

• 任务模块文件已删除
• 任务模块引用已移除
• 注释路径已统一
• 错误处理规范已更新（spec.md）
• 开发规范已更新（AGENTS.md）
• 使用指南已更新（包含实际案例）
• CI 检查脚本已创建
• CI 检查脚本测试通过
• 编译通过，无语法错误
• 全量检查脚本通过
• 文档完整性验证通过
• README 已更新（如需要）

预估工作量

任务	预估时间
1. 移除任务模块	0.5h
2. 清理注释一致性	0.5h
3. 更新规范文档	1h
4. CI 检查增强	0.5h
5. 全量验证	0.5h
6. README 更新（可选）	0.5h

总计：约 3.5 小时