csxj2026/junhong_cmp_fiber

Files

构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m45s

Details

主要变更：
1. OpenAPI 文档契约对齐
   - 统一错误响应字段名为 msg（非 message）
   - 规范 envelope 响应结构（code, msg, data, timestamp）
   - 个人客户路由纳入文档体系（使用 Register 机制）
   - 新增 BuildDocHandlers() 统一管理 handler 构造
   - 确保文档生成的幂等性

2. Service 层错误处理统一
   - 全面替换 fmt.Errorf 为 errors.New/Wrap
   - 统一错误码使用规范
   - Handler 层参数校验不泄露底层细节
   - 新增错误码验证集成测试

3. 代码质量提升
   - 删除未使用的 Task handler 和路由
   - 新增代码规范检查脚本（check-service-errors.sh）
   - 新增注释路径一致性检查（check-comment-paths.sh）
   - 更新 API 文档生成指南

4. OpenSpec 归档
   - 归档 openapi-contract-alignment 变更（63 tasks）
   - 归档 service-error-unify-core 变更
   - 归档 service-error-unify-support 变更
   - 归档 code-cleanup-docs-update 变更
   - 归档 handler-validation-security 变更
   - 同步 delta specs 到主规范文件

影响范围：
- pkg/openapi: 新增 handlers.go，优化 generator.go
- internal/service/*: 48 个 service 文件错误处理统一
- internal/handler/admin: 优化参数校验错误提示
- internal/routes: 个人客户路由改造，删除 task 路由
- scripts: 新增 3 个代码检查脚本
- docs: 更新 OpenAPI 文档（15750+ 行）
- openspec/specs: 同步 3 个主规范文件

破坏性变更：无
向后兼容：是

2026-01-30 11:40:36 +08:00

4.5 KiB

Raw Permalink Blame History

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

Why

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

当前问题：

任务模块占位代码：
- internal/routes/task.go 包含占位路由
- internal/handler/admin/task.go 未接入真实业务
- 存在鉴权不一致风险
注释路径不一致：
- Handler 层注释中残留 /api/v1/... 路径
- 真实路由为 /api/admin、/api/h5、/api/c/v1
规范文档缺失：
- openspec/specs/error-handling/spec.md 缺少"错误报错规范"
- AGENTS.md 未包含错误处理检查清单
- docs/003-error-handling/使用指南.md 缺少实际案例
CI 检查不完善：
- 无自动检查 Service 层禁止 fmt.Errorf
- 无自动检查注释路径一致性

What Changes

5.1 移除任务模块占位代码

删除以下文件和引用：

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

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

5.2 清理注释一致性

扫描并修复 Handler 层注释：

# 查找残留的 /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 检查增强

创建脚本检查规范遵守：

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

# .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

代码清理验证

# 确认文件已删除
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/  # 应无结果（除测试文件）

注释清理验证

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

CI 检查验证

# 运行检查脚本
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

文档完整性检查

# 确认文档已更新
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 小时

4.5 KiB Raw Permalink Blame History Unescape Escape