# 设计文档：代码清理和规范文档更新

## 概述

本变更旨在清理项目中的临时代码和不一致的注释，完善规范文档，并增强 CI 检查，确保代码质量和规范一致性。

## 设计目标

1. **代码清理**：移除未使用的占位代码，避免潜在的安全风险
2. **注释一致性**：确保代码注释与实际路由路径一致
3. **规范完善**：补充缺失的规范文档和实际案例
4. **自动化检查**：通过 CI 脚本自动检测规范违规

## 架构设计

### 1. 任务模块清理

#### 现状分析

```
internal/
├── routes/
│   ├── routes.go
│   └── task.go              # 占位路由，未接入业务
└── handler/
    └── admin/
        └── task.go          # 占位 Handler，空实现
```

**问题**：
- 占位代码可能被误用，导致鉴权不一致
- 增加代码维护成本
- 没有实际业务价值

#### 解决方案

**完全移除策略**：
- 删除 `internal/routes/task.go`
- 删除 `internal/handler/admin/task.go`
- 从 `internal/routes/routes.go` 移除 `registerTaskRoutes()` 调用
- 清理相关 import

**不采用保留注释/TODO 的原因**：
- 如需任务功能，应重新设计实现
- 避免遗留代码污染代码库

### 2. 注释路径清理

#### 现状分析

Handler 层注释中存在已弃用的路径：

```go
// 错误示例
// @Summary 获取用户列表
// @Router /api/v1/users [get]    // ❌ 已不存在
func ListUsers(c *fiber.Ctx) error { ... }

// 正确示例
// @Summary 获取用户列表
// @Router /api/admin/users [get]  // ✅ 与真实路由一致
func ListUsers(c *fiber.Ctx) error { ... }
```

**真实路由体系**：
- `/api/admin/*`：后台管理接口
- `/api/h5/*`：H5 端接口
- `/api/c/v1/*`：个人客户接口

#### 解决方案

**扫描和修复流程**：

```bash
# 1. 扫描所有残留路径
grep -rn "/api/v1" internal/handler/ | grep -v "_test.go" > /tmp/path_comments.txt

# 2. 根据模块修复
# - internal/handler/admin/*.go → /api/admin/*
# - internal/handler/h5/*.go → /api/h5/*
# - internal/handler/personal/*.go → /api/c/v1/*

# 3. 验证清理结果
grep -r "/api/v1" internal/handler/ | grep -v "_test.go"  # 应无结果
```

### 3. 规范文档更新

#### 3.1 错误处理规范（openspec/specs/error-handling/spec.md）

**新增内容**：

##### Purpose 章节

```markdown
## Purpose

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

##### 错误报错规范章节

```markdown
## 错误报错规范（必须遵守）

### Handler 层

**禁止行为**：
- ❌ 直接返回/拼接底层错误信息给客户端
  ```go
  // 错误示例
  return response.Error(c, 400, errors.CodeInvalidParam, "参数验证失败: "+err.Error())
  ```

**正确做法**：
- ✅ 参数校验失败统一返回 `errors.New(CodeInvalidParam)`
- ✅ 详细校验错误写日志，对外返回通用消息
  ```go
  // 正确示例
  if err := c.BodyParser(&req); err != nil {
      logger.Error("参数解析失败", zap.Error(err))
      return errors.New(errors.CodeInvalidParam)
  }
  ```

### Service 层

**禁止行为**：
- ❌ 对外返回 `fmt.Errorf(...)`
  ```go
  // 错误示例
  return fmt.Errorf("用户不存在: %w", err)
  ```

**正确做法**：
- ✅ 业务错误使用 `errors.New(code[, msg])`
- ✅ 系统错误使用 `errors.Wrap(code, err[, msg])`
  ```go
  // 正确示例
  if user == nil {
      return errors.New(errors.CodeUserNotFound, "用户不存在")
  }
  if err := db.Save(&user).Error; err != nil {
      return errors.Wrap(errors.CodeInternalError, err, "保存用户失败")
  }
  ```
```

#### 3.2 开发规范（AGENTS.md）

**新增 Code Review 检查清单**：

```markdown
## Code Review 检查清单

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

### 代码质量
- [ ] 遵循 Handler → Service → Store → Model 分层
- [ ] 函数长度 ≤ 100 行（核心逻辑 ≤ 50 行）
- [ ] 常量定义在 `pkg/constants/`
- [ ] 使用 Go 惯用法（非 Java 风格）

### 测试覆盖
- [ ] 核心业务逻辑测试覆盖率 ≥ 90%
- [ ] 所有 API 端点有集成测试
- [ ] 测试验证真实功能（不绕过核心逻辑）

### 文档和注释
- [ ] 所有注释使用中文
- [ ] 导出函数/类型有文档注释
- [ ] API 路径注释与真实路由一致
```

#### 3.3 使用指南（docs/003-error-handling/使用指南.md）

**补充实际案例**：

从现有代码库中提取真实案例：
- Service 层业务校验错误示例
- Service 层系统依赖错误示例
- Handler 层参数校验示例
- 单元测试示例

### 4. CI 检查增强

#### 4.1 Service 层错误检查脚本

**文件**：`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 层错误处理检查通过"
```

**设计考虑**：
- 仅检查 `internal/service` 目录
- 跳过带有 `// whitelist:` 注释的行（特殊场景）
- 返回非零退出码以集成到 CI

#### 4.2 注释路径检查脚本

**文件**：`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 "✅ 注释路径检查通过"
```

#### 4.3 统一检查脚本

**文件**：`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 "✅ 所有检查通过"
```

**用途**：
- 本地开发：`bash scripts/check-all.sh`
- CI 集成：在 `.github/workflows/lint.yml` 中调用

#### 4.4 CI 集成（可选）

**文件**：`.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
```

## 数据流设计

### 注释清理流程

```
┌─────────────────────────────────────────────────────────────┐
│                     注释清理流程                             │
└────────────────────────────┬────────────────────────────────┘
                             │
                ┌────────────▼────────────┐
                │ 1. 扫描残留路径         │
                │ grep -rn "/api/v1"     │
                └────────────┬────────────┘
                             │
                ┌────────────▼────────────┐
                │ 2. 分析文件模块         │
                │ - admin/ → /api/admin  │
                │ - h5/ → /api/h5        │
                │ - personal/ → /api/c   │
                └────────────┬────────────┘
                             │
                ┌────────────▼────────────┐
                │ 3. 批量修复注释         │
                │ - 手动编辑文件          │
                │ - 或使用 sed 批量替换   │
                └────────────┬────────────┘
                             │
                ┌────────────▼────────────┐
                │ 4. 验证清理结果         │
                │ grep -r "/api/v1"      │
                │ 应无结果                │
                └─────────────────────────┘
```

### CI 检查流程

```
┌─────────────────────────────────────────────────────────────┐
│                      CI 检查流程                             │
└────────────────────────────┬────────────────────────────────┘
                             │
                ┌────────────▼────────────┐
                │ 1. 代码提交/PR          │
                └────────────┬────────────┘
                             │
                ┌────────────▼────────────┐
                │ 2. 触发 GitHub Actions  │
                └────────────┬────────────┘
                             │
                ┌────────────▼────────────┐
                │ 3. 运行 check-all.sh    │
                └────────────┬────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
┌───────▼────────┐  ┌────────▼────────┐  ┌───────▼────────┐
│ Service 错误检查│  │ 注释路径检查    │  │ 其他检查...    │
└───────┬────────┘  └────────┬────────┘  └───────┬────────┘
        │                    │                    │
        └────────────────────┼────────────────────┘
                             │
                    ┌────────▼────────┐
                    │ 4. 汇总结果      │
                    │ - ✅ 全部通过    │
                    │ - ❌ 有违规      │
                    └────────┬────────┘
                             │
                ┌────────────▼────────────┐
                │ 5. 反馈结果到 PR        │
                │ - 通过：允许合并        │
                │ - 失败：阻止合并        │
                └─────────────────────────┘
```

## 技术决策

### 1. 为什么完全删除任务模块而非保留注释？

**决策**：完全删除占位代码

**理由**：
- **避免误用**：占位代码可能被后续开发者误用
- **代码简洁**：减少维护成本和认知负担
- **版本控制**：Git 历史保留了代码，需要时可恢复
- **重新设计**：如需任务功能，应基于实际需求设计

### 2. 为什么只检查 Service 层的 fmt.Errorf？

**决策**：只强制检查 Service 层

**理由**：
- **影响范围**：Service 层错误直接影响客户端体验
- **降低噪音**：Handler 层有时需要拼接调试信息（不对外返回）
- **测试文件**：测试代码可以使用 `fmt.Errorf` 构造错误

**特殊场景处理**：
- 内部调试需要 `fmt.Errorf`：添加 `// whitelist:` 注释跳过检查

### 3. 为什么文档案例从实际代码提取？

**决策**：使用真实代码案例而非虚构示例

**理由**：
- **实用性**：开发者可直接参考实际实现
- **一致性**：确保文档与代码同步
- **可信度**：真实案例更有说服力

### 4. CI 集成为什么设为可选？

**决策**：CI 集成为可选任务

**理由**：
- **灵活性**：本地开发可直接运行脚本
- **渐进式**：项目可选择何时启用 CI
- **成本考虑**：小型项目可能不需要 CI

## 非功能性需求

### 性能考虑

- **脚本性能**：检查脚本应在 10 秒内完成
- **CI 耗时**：代码检查不应显著增加 CI 时间（< 30 秒）

### 可维护性

- **脚本可读性**：使用清晰的错误消息和帮助文本
- **规则扩展**：易于添加新的检查规则
- **白名单机制**：支持特殊场景豁免

### 兼容性

- **Shell 兼容性**：脚本使用 Bash 标准语法（兼容 Linux/macOS）
- **工具依赖**：仅依赖标准工具（grep、find），无需额外安装

## 验证策略

### 1. 代码清理验证

```bash
# 确认文件已删除
test ! -f internal/routes/task.go
test ! -f internal/handler/admin/task.go

# 确认引用已移除
! grep -r "registerTaskRoutes" internal/
! grep -r "TaskHandler" internal/ | grep -v "_test.go"

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

### 2. 注释清理验证

```bash
# 确认无残留 /api/v1 注释
! grep -r "/api/v1" internal/handler/ | grep -v "_test.go"
```

### 3. CI 脚本验证

```bash
# 运行检查（应通过）
bash scripts/check-all.sh

# 测试能检测违规（应失败）
echo 'return fmt.Errorf("test")' >> internal/service/test_violation.go
bash scripts/check-service-errors.sh  # 应返回退出码 1
rm internal/service/test_violation.go

# 测试白名单机制（应通过）
echo 'return fmt.Errorf("debug") // whitelist:' >> internal/service/test.go
bash scripts/check-service-errors.sh  # 应返回退出码 0
rm internal/service/test.go
```

### 4. 文档完整性验证

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

# 确认文档包含实际案例（非空占位）
test $(wc -l < docs/003-error-handling/使用指南.md) -gt 100
```

## 实施计划

### 阶段 1：代码清理（0.5h）

1. 删除任务模块文件
2. 移除路由注册调用
3. 编译验证

### 阶段 2：注释清理（0.5h）

1. 扫描残留路径
2. 批量修复注释
3. 验证清理结果

### 阶段 3：文档更新（1h）

1. 更新错误处理规范
2. 更新开发规范
3. 补充使用指南案例

### 阶段 4：CI 增强（0.5h）

1. 创建检查脚本
2. 测试脚本功能
3. 更新 README

### 阶段 5：全量验证（0.5h）

1. 运行所有验证命令
2. 确认文档完整性
3. 更新 README

## 风险和缓解

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 误删有用代码 | 高 | 仔细审查 Git 历史，确认代码未被引用 |
| 注释修复遗漏 | 中 | 使用自动化脚本扫描，手动验证结果 |
| CI 脚本误报 | 中 | 提供白名单机制，允许特殊场景豁免 |
| 文档案例过时 | 低 | 从当前代码库提取，确保时效性 |

## 总结

本设计通过系统化的方法清理代码、完善文档、增强 CI 检查，确保项目代码质量和规范一致性。关键设计决策包括：

1. **完全删除**占位代码而非保留注释
2. **自动化检查** Service 层错误处理规范
3. **真实案例**补充文档使用指南
4. **渐进式集成** CI 检查（可选）

预计总工作量约 3 小时，无 Breaking Changes，对现有功能无影响。