# Change: 代码清理和规范文档更新

## Why

清理临时代码和不一致的注释，更新项目规范文档，完善 CI 检查，确保代码质量和规范一致性。

**当前问题**：

1. **任务模块占位代码**：
   - `internal/routes/task.go` 包含占位路由
   - `internal/handler/admin/task.go` 未接入真实业务
   - 存在鉴权不一致风险

2. **注释路径不一致**：
   - Handler 层注释中残留 `/api/v1/...` 路径
   - 真实路由为 `/api/admin`、`/api/h5`、`/api/c/v1`

3. **规范文档缺失**：
   - `openspec/specs/error-handling/spec.md` 缺少"错误报错规范"
   - `AGENTS.md` 未包含错误处理检查清单
   - `docs/003-error-handling/使用指南.md` 缺少实际案例

4. **CI 检查不完善**：
   - 无自动检查 Service 层禁止 `fmt.Errorf`
   - 无自动检查注释路径一致性

## What Changes

### 5.1 移除任务模块占位代码

删除以下文件和引用：

```bash
# 删除文件
rm internal/routes/task.go
rm internal/handler/admin/task.go

# 更新 routes.go
# 移除 registerTaskRoutes(...) 调用
```

### 5.2 清理注释一致性

扫描并修复 Handler 层注释：

```bash
# 查找残留的 /api/v1 注释
grep -r "/api/v1" internal/handler/ | grep -v "_test.go"

# 修复为真实路径
/api/v1/users → /api/admin/users
/api/v1/shops → /api/admin/shops
```

### 5.3 更新规范文档

#### 错误处理规范
- 更新 `openspec/specs/error-handling/spec.md`
- 补充 Purpose 说明
- 新增"错误报错规范"条款：
  - Handler 层禁止直接返回底层错误
  - Service 层禁止使用 `fmt.Errorf` 对外返回
  - 参数校验失败统一返回 `CodeInvalidParam`

#### 开发规范
- 更新 `AGENTS.md`
- 增加"错误报错规范"摘要
- 补充 Code Review 检查清单

#### 使用指南
- 更新 `docs/003-error-handling/使用指南.md`
- 补充 Service 层错误处理实际案例
- 补充 Handler 层参数校验案例
- 补充单元测试示例

### 5.4 CI 检查增强

创建脚本检查规范遵守：

```bash
#!/bin/bash
# scripts/check-service-errors.sh

FILES=$(find internal/service -name "*.go" -type f)
VIOLATIONS=$(grep -n "fmt\.Errorf" $FILES | grep -v "// whitelist:")

if [ -n "$VIOLATIONS" ]; then
    echo "❌ 发现 Service 层使用 fmt.Errorf："
    echo "$VIOLATIONS"
    exit 1
fi

echo "✅ Service 层错误处理检查通过"
```

## Decisions

### 任务模块处理

- 完全移除占位代码（不保留注释或 TODO）
- 如需任务功能，后续单独设计实现

### 注释清理规则

- 注释路径必须与真实路由一致
- 不使用已弃用的路径（如 `/api/v1`）
- API 文档路径以 OpenAPI 生成为准

### CI 检查范围

- Service 层：禁止 `fmt.Errorf` 对外返回
- Handler 层：建议检查但不强制（可选）
- 测试文件：跳过检查

## Impact

### Breaking Changes

无（仅清理未使用代码）

### Documentation Updates

- 错误处理规范文档完善
- 开发规范检查清单更新
- 使用指南补充实际案例

### CI Integration

可选集成到 GitHub Actions：

```yaml
# .github/workflows/lint.yml
- name: Check Service Layer Errors
  run: bash scripts/check-service-errors.sh
```

## Affected Specs

- **UPDATE**: `openspec/specs/error-handling/spec.md`
- **UPDATE**: `AGENTS.md`
- **UPDATE**: `docs/003-error-handling/使用指南.md`

## Verification Checklist

### 代码清理验证
```bash
# 确认文件已删除
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/  # 应无结果（除测试文件）
```

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

### CI 检查验证
```bash
# 运行检查脚本
bash scripts/check-service-errors.sh  # 应返回 ✅

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

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

## Estimated Effort

| 任务 | 预估时间 |
|-----|---------|
| 5.1 移除任务模块 | 0.5h |
| 5.2 清理注释一致性 | 0.5h |
| 5.3 更新规范文档 | 1h |
| 5.4 CI 检查增强 | 0.5h |
| 验证 | 0.5h |

**总计**：约 3 小时