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

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

概述

本变更旨在清理项目中的临时代码和不一致的注释，完善规范文档，并增强 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 层注释中存在已弃用的路径：

// 错误示例
// @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/*：个人客户接口

解决方案

扫描和修复流程：

# 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 章节

## Purpose

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

错误报错规范章节

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

### Handler 层

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

正确做法：

• ✅ 参数校验失败统一返回 errors.New(CodeInvalidParam)
• ✅ 详细校验错误写日志，对外返回通用消息

  // 正确示例
  if err := c.BodyParser(&req); err != nil {
      logger.Error("参数解析失败", zap.Error(err))
      return errors.New(errors.CodeInvalidParam)
  }
  

Service 层

禁止行为：

• ❌ 对外返回 fmt.Errorf(...)

  // 错误示例
  return fmt.Errorf("用户不存在: %w", err)
  

正确做法：

• ✅ 业务错误使用 errors.New(code[, msg])
• ✅ 系统错误使用 errors.Wrap(code, err[, msg])

  // 正确示例
  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

#!/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

#!/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

#!/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

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. 代码清理验证

# 确认文件已删除
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. 注释清理验证

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

3. CI 脚本验证

# 运行检查（应通过）
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. 文档完整性验证

# 确认规范文档已更新
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，对现有功能无影响。