huang
409a68d60b
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m45s
主要变更： 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 个主规范文件 破坏性变更：无 向后兼容：是
192 lines
4.5 KiB
Markdown
192 lines
4.5 KiB
Markdown
# 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 小时
|