# Implementation Tasks

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

### 1.1 删除文件
- [x] 删除 `internal/routes/task.go`
  ```bash
  rm internal/routes/task.go
  ```
- [x] 删除 `internal/handler/admin/task.go`
  ```bash
  rm internal/handler/admin/task.go
  ```

### 1.2 移除引用
- [x] 打开 `internal/routes/routes.go`
- [x] 移除 `registerTaskRoutes(...)` 调用
- [x] 移除相关 import（如果不再使用）

### 1.3 验证
- [x] 编译检查：`go build -o /tmp/test_api ./cmd/api`
- [x] 确认无 TaskHandler 引用：
  ```bash
  grep -r "TaskHandler" internal/ | grep -v "_test.go"
  # 应无结果
  ```

## 2. 清理注释一致性

### 2.1 扫描残留路径
- [x] 查找所有 `/api/v1` 注释：
  ```bash
  grep -rn "/api/v1" internal/handler/ | grep -v "_test.go" > /tmp/path_comments.txt
  cat /tmp/path_comments.txt
  ```

### 2.2 批量修复注释
- [x] 根据 `/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 验证清理结果
- [x] 再次扫描：
  ```bash
  grep -r "/api/v1" internal/handler/ | grep -v "_test.go"
  # 应无结果
  ```

## 3. 更新规范文档

### 3.1 更新错误处理规范
- [x] 打开 `openspec/specs/error-handling/spec.md`
- [x] 补充 Purpose 说明：
  ```markdown
  ## Purpose
  
  统一项目的错误处理机制，确保：
  - 错误码一致性和可追踪性
  - 客户端能准确识别错误类型
  - 日志记录完整便于排查
  - 避免泄露内部实现细节
  ```

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

### 3.2 更新 AGENTS.md
- [x] 打开 `AGENTS.md`
- [x] 在"错误处理"章节补充摘要：
  ```markdown
  #### 错误报错规范（必须遵守）
  - Handler 层禁止直接返回/拼接底层错误信息（例如 `"参数验证失败: "+err.Error()`）
  - 参数校验失败：对外统一返回 `errors.New(CodeInvalidParam)`（详细错误写日志）
  - Service 层禁止对外返回 `fmt.Errorf(...)`，必须返回 `errors.New(...)` 或 `errors.Wrap(...)`
  ```

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

### 3.3 更新使用指南
- [x] 打开 `docs/003-error-handling/使用指南.md`
- [x] 补充 Service 层错误处理实际案例：
  ```markdown
  ## Service 层错误处理
  
  ### 业务校验错误（4xx）
  
  #### 示例 1：资源不存在
  [从实际代码中提取]
  
  #### 示例 2：状态不允许
  [从实际代码中提取]
  
  ### 系统依赖错误（5xx）
  
  #### 示例 3：数据库错误
  [从实际代码中提取]
  ```

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

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

## 4. CI 检查增强

### 4.1 创建检查脚本
- [x] 创建文件：`scripts/check-service-errors.sh`
  ```bash
  #!/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 层错误处理检查通过"
  ```

- [x] 添加执行权限：
  ```bash
  chmod +x scripts/check-service-errors.sh
  ```

### 4.2 创建注释检查脚本（可选）
- [x] 创建文件：`scripts/check-comment-paths.sh`
  ```bash
  #!/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 "✅ 注释路径检查通过"
  ```

- [x] 添加执行权限：
  ```bash
  chmod +x scripts/check-comment-paths.sh
  ```

### 4.3 创建统一检查脚本
- [x] 创建文件：`scripts/check-all.sh`
  ```bash
  #!/bin/bash
  # 运行所有代码规范检查
  
  set -e
  
  echo "🚀 运行代码规范检查..."
  echo ""
  
  bash scripts/check-service-errors.sh
  bash scripts/check-comment-paths.sh
  
  echo ""
  echo "✅ 所有检查通过"
  ```

- [x] 添加执行权限：
  ```bash
  chmod +x scripts/check-all.sh
  ```

### 4.4 测试检查脚本
- [x] 运行 Service 错误检查：
  ```bash
  bash scripts/check-service-errors.sh
  # 应返回 ✅（假设已完成提案 1 和 2）
  ```

- [x] 测试脚本能检测违规：
  ```bash
  echo 'return fmt.Errorf("test")' >> internal/service/test.go
  bash scripts/check-service-errors.sh  # 应返回 ❌
  rm internal/service/test.go
  ```

- [x] 运行注释路径检查：
  ```bash
  bash scripts/check-comment-paths.sh
  # 应返回 ✅
  ```

- [x] 运行全部检查：
  ```bash
  bash scripts/check-all.sh
  ```

### 4.5 集成到 CI（可选）
- [x] 创建/更新 `.github/workflows/lint.yml`：
  ```yaml
  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 代码清理验证
- [x] 确认文件已删除：
  ```bash
  ls internal/routes/task.go  # 应返回 No such file
  ls internal/handler/admin/task.go  # 应返回 No such file
  ```

- [x] 确认引用已移除：
  ```bash
  grep -r "registerTaskRoutes" internal/  # 应无结果
  grep -r "TaskHandler" internal/ | grep -v "_test.go"  # 应无结果
  ```

### 5.2 注释清理验证
- [x] 确认无残留 `/api/v1` 注释：
  ```bash
  grep -r "/api/v1" internal/handler/ | grep -v "_test.go"  # 应无结果
  ```

### 5.3 编译检查
- [x] `go build -o /tmp/test_api ./cmd/api`
- [x] `go build -o /tmp/test_worker ./cmd/worker`

### 5.4 CI 检查验证
- [x] 运行所有检查脚本：
  ```bash
  bash scripts/check-all.sh  # 应返回 ✅
  ```

### 5.5 文档完整性检查
- [x] 确认规范文档已更新：
  ```bash
  grep "错误报错规范" openspec/specs/error-handling/spec.md
  grep "错误报错规范" AGENTS.md
  grep "Service 层错误处理" docs/003-error-handling/使用指南.md
  ```

- [x] 确认文档包含实际案例（非空占位）

## 6. README 更新（可选）

### 6.1 补充 CI 检查说明
- [x] 在 `README.md` 中补充"代码规范检查"章节：
  ```markdown
  ## 代码规范检查
  
  运行代码规范检查：
  
  \`\`\`bash
  # 检查 Service 层错误处理
  bash scripts/check-service-errors.sh
  
  # 检查注释路径一致性
  bash scripts/check-comment-paths.sh
  
  # 运行所有检查
  bash scripts/check-all.sh
  \`\`\`
  
  这些检查会在 CI/CD 流程中自动执行。
  ```

## 验证清单

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

## 预估工作量

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

**总计**：约 3.5 小时