feat: OpenAPI 契约对齐与框架优化
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m45s
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 个主规范文件 破坏性变更：无 向后兼容：是
This commit is contained in:
@@ -0,0 +1,15 @@
|
||||
schema: spec-driven
|
||||
status: complete
|
||||
artifacts:
|
||||
- id: proposal
|
||||
status: done
|
||||
output: proposal.md
|
||||
- id: design
|
||||
status: done
|
||||
output: design.md
|
||||
- id: specs
|
||||
status: done
|
||||
output: specs/**/*.md
|
||||
- id: tasks
|
||||
status: done
|
||||
output: tasks.md
|
||||
@@ -0,0 +1,389 @@
|
||||
# 设计文档：Service 层错误语义统一 - 支持模块
|
||||
|
||||
## 概述
|
||||
|
||||
本设计文档描述了对剩余支持模块进行错误语义统一的技术方案，确保整个项目的错误处理一致性。
|
||||
|
||||
## 架构设计
|
||||
|
||||
### 错误处理流程
|
||||
|
||||
```
|
||||
Service 层业务逻辑
|
||||
├── 业务校验错误 (4xx)
|
||||
│ ├── errors.New(errors.CodeNotFound, "xxx")
|
||||
│ ├── errors.New(errors.CodeDuplicate, "xxx")
|
||||
│ ├── errors.New(errors.CodeInvalidPassword, "xxx")
|
||||
│ └── errors.New(errors.CodeInsufficientQuota, "xxx")
|
||||
└── 系统依赖错误 (5xx)
|
||||
├── errors.Wrap(errors.CodeInternalError, err, "xxx")
|
||||
└── errors.Wrap(errors.CodeServiceUnavailable, err, "xxx")
|
||||
|
||||
↓
|
||||
|
||||
Handler 层返回错误
|
||||
↓
|
||||
|
||||
全局 ErrorHandler 统一处理
|
||||
├── 提取错误码和消息
|
||||
├── 根据错误码设置日志级别
|
||||
│ ├── 4xx → WARN
|
||||
│ └── 5xx → ERROR
|
||||
└── 返回统一 JSON 格式
|
||||
```
|
||||
|
||||
### 模块分类
|
||||
|
||||
#### 1. 套餐分配系统（4 个文件）
|
||||
|
||||
| 文件 | 错误点数 | 主要错误场景 |
|
||||
|-----|---------|-------------|
|
||||
| shop_package_allocation/service.go | 17 | 分配记录不存在、额度不足、数据库错误 |
|
||||
| shop_series_allocation/service.go | 24 | 系列分配记录不存在、分配冲突、数据库错误 |
|
||||
| shop_package_batch_allocation/service.go | 6 | 批量分配失败 |
|
||||
| shop_package_batch_pricing/service.go | 3 | 批量定价失败 |
|
||||
|
||||
#### 2. 权限与账号管理（3 个文件）
|
||||
|
||||
| 文件 | 错误点数 | 主要错误场景 |
|
||||
|-----|---------|-------------|
|
||||
| account/service.go | 24 | 账号不存在、用户名重复、密码错误、状态不允许 |
|
||||
| role/service.go | 15 | 角色不存在、角色已存在、角色被使用无法删除 |
|
||||
| permission/service.go | 10 | 权限不存在、权限冲突 |
|
||||
|
||||
#### 3. 卡与设备管理（2 个文件）
|
||||
|
||||
| 文件 | 错误点数 | 主要错误场景 |
|
||||
|-----|---------|-------------|
|
||||
| enterprise_card/service.go | 9 | 卡不存在、卡状态不允许 |
|
||||
| enterprise_device/service.go | 20 | 设备不存在、设备状态不允许、设备绑定卡数量超限 |
|
||||
|
||||
#### 4. 其他支持服务（5 个文件）
|
||||
|
||||
| 文件 | 错误点数 | 主要错误场景 |
|
||||
|-----|---------|-------------|
|
||||
| carrier/service.go | 9 | 运营商不存在 |
|
||||
| shop_commission/service.go | 7 | 分佣设置不存在 |
|
||||
| commission_withdrawal_setting/service.go | 4 | 提现设置不存在 |
|
||||
| email/service.go | 6 | 邮件服务未配置、邮件发送失败 |
|
||||
| sync/service.go | 4 | 同步任务失败 |
|
||||
|
||||
## 错误码映射
|
||||
|
||||
### 现有错误码
|
||||
|
||||
| 错误码 | 常量名 | HTTP 状态码 | 使用场景 |
|
||||
|-------|--------|------------|---------|
|
||||
| 404 | CodeNotFound | 404 | 资源不存在 |
|
||||
| 40003 | CodeDuplicate | 400 | 资源重复 |
|
||||
| 40004 | CodeInvalidPassword | 400 | 密码错误 |
|
||||
| 40008 | CodeInvalidStatus | 400 | 状态不允许 |
|
||||
| 403 | CodeForbidden | 403 | 禁止操作 |
|
||||
| 50000 | CodeInternalError | 500 | 内部错误 |
|
||||
| 50003 | CodeServiceUnavailable | 503 | 服务不可用 |
|
||||
|
||||
### 新增错误码
|
||||
|
||||
| 错误码 | 常量名 | HTTP 状态码 | 使用场景 |
|
||||
|-------|--------|------------|---------|
|
||||
| 40010 | CodeInsufficientQuota | 400 | 额度不足 |
|
||||
| 40011 | CodeExceedLimit | 400 | 超过限制 |
|
||||
| 40900 | CodeConflict | 409 | 资源冲突 |
|
||||
|
||||
## 实现示例
|
||||
|
||||
### 业务校验错误示例
|
||||
|
||||
#### 场景 1：资源不存在
|
||||
|
||||
```go
|
||||
// ❌ 修改前
|
||||
func (s *ShopPackageAllocationService) GetByID(ctx context.Context, id uint) (*model.ShopPackageAllocation, error) {
|
||||
allocation, err := s.store.ShopPackageAllocation.GetByID(ctx, id)
|
||||
if err != nil {
|
||||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||
return nil, fmt.Errorf("分配记录不存在")
|
||||
}
|
||||
return nil, fmt.Errorf("查询分配记录失败: %w", err)
|
||||
}
|
||||
return allocation, nil
|
||||
}
|
||||
|
||||
// ✅ 修改后
|
||||
func (s *ShopPackageAllocationService) GetByID(ctx context.Context, id uint) (*model.ShopPackageAllocation, error) {
|
||||
allocation, err := s.store.ShopPackageAllocation.GetByID(ctx, id)
|
||||
if err != nil {
|
||||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||
return nil, errors.New(errors.CodeNotFound, "分配记录不存在")
|
||||
}
|
||||
return nil, errors.Wrap(errors.CodeInternalError, err, "查询分配记录失败")
|
||||
}
|
||||
return allocation, nil
|
||||
}
|
||||
```
|
||||
|
||||
#### 场景 2：额度不足
|
||||
|
||||
```go
|
||||
// ❌ 修改前
|
||||
func (s *ShopPackageAllocationService) AllocatePackage(ctx context.Context, req *dto.AllocatePackageRequest) error {
|
||||
if req.Amount > available {
|
||||
return fmt.Errorf("可用额度不足，当前可用: %d", available)
|
||||
}
|
||||
// ...
|
||||
}
|
||||
|
||||
// ✅ 修改后
|
||||
func (s *ShopPackageAllocationService) AllocatePackage(ctx context.Context, req *dto.AllocatePackageRequest) error {
|
||||
if req.Amount > available {
|
||||
return errors.New(errors.CodeInsufficientQuota, fmt.Sprintf("可用额度不足，当前可用: %d", available))
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### 场景 3：角色被使用无法删除
|
||||
|
||||
```go
|
||||
// ❌ 修改前
|
||||
func (s *RoleService) Delete(ctx context.Context, id uint) error {
|
||||
count, err := s.store.Account.CountByRoleID(ctx, id)
|
||||
if err != nil {
|
||||
return fmt.Errorf("查询角色使用情况失败: %w", err)
|
||||
}
|
||||
if count > 0 {
|
||||
return fmt.Errorf("角色被 %d 个账号使用，无法删除", count)
|
||||
}
|
||||
// ...
|
||||
}
|
||||
|
||||
// ✅ 修改后
|
||||
func (s *RoleService) Delete(ctx context.Context, id uint) error {
|
||||
count, err := s.store.Account.CountByRoleID(ctx, id)
|
||||
if err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "查询角色使用情况失败")
|
||||
}
|
||||
if count > 0 {
|
||||
return errors.New(errors.CodeForbidden, fmt.Sprintf("角色被 %d 个账号使用，无法删除", count))
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### 系统依赖错误示例
|
||||
|
||||
#### 场景 4：数据库操作失败
|
||||
|
||||
```go
|
||||
// ❌ 修改前
|
||||
func (s *AccountService) Create(ctx context.Context, req *dto.CreateAccountRequest) error {
|
||||
account := &model.Account{
|
||||
Username: req.Username,
|
||||
// ...
|
||||
}
|
||||
if err := s.store.Account.Create(ctx, account); err != nil {
|
||||
return fmt.Errorf("创建账号失败: %w", err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// ✅ 修改后
|
||||
func (s *AccountService) Create(ctx context.Context, req *dto.CreateAccountRequest) error {
|
||||
account := &model.Account{
|
||||
Username: req.Username,
|
||||
// ...
|
||||
}
|
||||
if err := s.store.Account.Create(ctx, account); err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "创建账号失败")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
#### 场景 5：外部服务不可用
|
||||
|
||||
```go
|
||||
// ❌ 修改前
|
||||
func (s *EmailService) Send(ctx context.Context, to, subject, body string) error {
|
||||
if s.smtpClient == nil {
|
||||
return fmt.Errorf("邮件服务未配置")
|
||||
}
|
||||
if err := s.smtpClient.Send(to, subject, body); err != nil {
|
||||
return fmt.Errorf("邮件发送失败: %w", err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// ✅ 修改后
|
||||
func (s *EmailService) Send(ctx context.Context, to, subject, body string) error {
|
||||
if s.smtpClient == nil {
|
||||
return errors.New(errors.CodeServiceUnavailable, "邮件服务未配置")
|
||||
}
|
||||
if err := s.smtpClient.Send(to, subject, body); err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "邮件发送失败")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
## 测试策略
|
||||
|
||||
### 单元测试覆盖
|
||||
|
||||
每个模块需要补充以下错误场景测试：
|
||||
|
||||
```go
|
||||
func TestService_ErrorHandling(t *testing.T) {
|
||||
tx := testutils.NewTestTransaction(t)
|
||||
rdb := testutils.GetTestRedis(t)
|
||||
testutils.CleanTestRedisKeys(t, rdb)
|
||||
|
||||
store := postgres.NewStore(tx, rdb)
|
||||
service := NewService(store, nil)
|
||||
|
||||
t.Run("资源不存在返回 404", func(t *testing.T) {
|
||||
_, err := service.GetByID(context.Background(), 99999)
|
||||
require.Error(t, err)
|
||||
assert.Equal(t, errors.CodeNotFound, errors.GetCode(err))
|
||||
})
|
||||
|
||||
t.Run("额度不足返回 400", func(t *testing.T) {
|
||||
err := service.AllocatePackage(context.Background(), &dto.AllocatePackageRequest{
|
||||
Amount: 999999,
|
||||
})
|
||||
require.Error(t, err)
|
||||
assert.Equal(t, errors.CodeInsufficientQuota, errors.GetCode(err))
|
||||
})
|
||||
|
||||
t.Run("数据库错误返回 500", func(t *testing.T) {
|
||||
// 模拟数据库错误（如外键约束违反）
|
||||
err := service.Create(context.Background(), invalidData)
|
||||
require.Error(t, err)
|
||||
assert.Equal(t, errors.CodeInternalError, errors.GetCode(err))
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### 集成测试验证
|
||||
|
||||
通过 HTTP 接口验证错误码：
|
||||
|
||||
```bash
|
||||
# 1. 资源不存在返回 404
|
||||
curl -X GET http://localhost:8080/api/admin/allocations/99999 \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
# 期望: {"code": 404, "msg": "分配记录不存在", ...}
|
||||
|
||||
# 2. 额度不足返回 400
|
||||
curl -X POST http://localhost:8080/api/admin/allocations \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"amount": 999999}'
|
||||
# 期望: {"code": 40010, "msg": "可用额度不足", ...}
|
||||
|
||||
# 3. 角色被使用无法删除返回 403
|
||||
curl -X DELETE http://localhost:8080/api/admin/roles/1 \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
# 期望: {"code": 403, "msg": "角色被使用，无法删除", ...}
|
||||
```
|
||||
|
||||
## 执行计划
|
||||
|
||||
### 分批执行策略
|
||||
|
||||
| 批次 | 模块 | 文件数 | 预估时间 |
|
||||
|-----|------|-------|---------|
|
||||
| 第 1 批 | 权限与账号管理 | 3 | 1.5h |
|
||||
| 第 2 批 | 套餐分配系统 | 4 | 1.5h |
|
||||
| 第 3 批 | 卡与设备管理 | 2 | 1h |
|
||||
| 第 4 批 | 其他支持服务 | 5 | 1h |
|
||||
| 验证 | 全量测试和文档更新 | - | 1h |
|
||||
|
||||
### 每批次执行步骤
|
||||
|
||||
1. **扫描错误点**：使用 grep 查找所有 `fmt.Errorf` 使用点
|
||||
2. **分类错误场景**：区分业务校验错误和系统依赖错误
|
||||
3. **替换错误处理**：使用 `errors.New()` 或 `errors.Wrap()`
|
||||
4. **补充单元测试**：覆盖新的错误场景
|
||||
5. **运行测试验证**：`source .env.local && go test -v ./internal/service/xxx/...`
|
||||
|
||||
## 向后兼容性
|
||||
|
||||
### 错误消息保持中文
|
||||
|
||||
所有错误消息保持中文描述，确保客户端和日志的可读性：
|
||||
|
||||
```go
|
||||
// ✅ 正确：保持中文消息
|
||||
return errors.New(errors.CodeNotFound, "分配记录不存在")
|
||||
|
||||
// ❌ 错误：不要改成英文
|
||||
return errors.New(errors.CodeNotFound, "allocation not found")
|
||||
```
|
||||
|
||||
### 错误码升级路径
|
||||
|
||||
部分接口的错误码会从 500 调整为 4xx，客户端需要处理新的错误码：
|
||||
|
||||
| 原错误码 | 新错误码 | 场景 |
|
||||
|---------|---------|------|
|
||||
| 500 | 404 | 资源不存在 |
|
||||
| 500 | 400 | 业务校验失败（如额度不足） |
|
||||
| 500 | 403 | 禁止操作（如角色被使用） |
|
||||
| 500 | 409 | 资源冲突 |
|
||||
|
||||
## 风险评估
|
||||
|
||||
### 低风险
|
||||
|
||||
- **错误消息保持中文**：不影响客户端和日志的可读性
|
||||
- **向后兼容**：新错误码是对现有 500 错误的细化，不破坏现有功能
|
||||
- **测试覆盖**：每个模块补充错误场景测试，确保质量
|
||||
|
||||
### 中风险
|
||||
|
||||
- **错误码调整**：部分接口错误码从 500 调整为 4xx，客户端需要适配
|
||||
- **新增错误码**：如 `CodeInsufficientQuota`、`CodeExceedLimit`，客户端需要处理
|
||||
|
||||
### 缓解措施
|
||||
|
||||
- **文档更新**：在 `docs/003-error-handling/使用指南.md` 中补充新增错误码说明
|
||||
- **日志验证**：运行集成测试后检查 `logs/access.log` 和 `logs/app.log`，确认错误码正确分类（4xx 为 WARN，5xx 为 ERROR）
|
||||
|
||||
## 验收标准
|
||||
|
||||
### 代码质量
|
||||
|
||||
- ✅ 所有文件已移除 `fmt.Errorf` 对外返回
|
||||
- ✅ 业务错误使用 `errors.New(Code4xx)`
|
||||
- ✅ 系统错误使用 `errors.Wrap(Code5xx, err)`
|
||||
- ✅ 错误消息保持中文描述
|
||||
|
||||
### 测试覆盖
|
||||
|
||||
- ✅ 每个模块补充错误场景单元测试
|
||||
- ✅ 编译通过：`go build -o /tmp/test_api ./cmd/api`
|
||||
- ✅ 单元测试通过：`source .env.local && go test -v ./internal/service/xxx/...`
|
||||
- ✅ 集成测试通过：`source .env.local && go test -v ./tests/integration/...`
|
||||
|
||||
### 日志验证
|
||||
|
||||
- ✅ 4xx 错误记录为 WARN 级别
|
||||
- ✅ 5xx 错误记录为 ERROR 级别
|
||||
- ✅ 错误日志包含完整堆栈跟踪（5xx）
|
||||
|
||||
### 文档更新
|
||||
|
||||
- ✅ 更新 `openspec/specs/error-handling/spec.md`（补充新增错误码）
|
||||
- ✅ 更新 `docs/003-error-handling/使用指南.md`（添加实际案例）
|
||||
|
||||
## 总结
|
||||
|
||||
本设计通过系统化的错误语义统一，实现了以下目标：
|
||||
|
||||
1. **一致性**：所有支持模块遵循统一的错误处理规范
|
||||
2. **可维护性**：错误分类清晰，便于问题定位和排查
|
||||
3. **可测试性**：错误场景覆盖完整，单元测试覆盖率高
|
||||
4. **可观测性**：错误日志分级合理，便于监控和告警
|
||||
|
||||
通过分批执行和充分测试，确保变更的安全性和质量。
|
||||
@@ -0,0 +1,217 @@
|
||||
# Change: Service 层错误语义统一 - 支持模块
|
||||
|
||||
## Why
|
||||
|
||||
完成剩余支持模块的错误语义统一，实现全局一致性。支持模块包括套餐分配、权限管理、卡与设备管理、邮件同步等功能。
|
||||
|
||||
**前置依赖**：
|
||||
- 提案 1（核心业务模块）已完成
|
||||
- 错误处理规范已明确
|
||||
|
||||
**影响范围**：
|
||||
- 套餐分配系统（4 个文件，50 处）
|
||||
- 权限与账号管理（3 个文件，49 处）
|
||||
- 卡与设备管理（2 个文件，29 处）
|
||||
- 其他支持服务（5 个文件，26 处）
|
||||
|
||||
**总计**：14 个文件，约 154 处 `fmt.Errorf` 待替换
|
||||
|
||||
## What Changes
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### 套餐分配系统
|
||||
- [ ] `shop_package_allocation/service.go` (17 处)
|
||||
- 分配记录不存在 → `CodeNotFound`
|
||||
- 分配额度不足 → `CodeInsufficientQuota`
|
||||
- 数据库错误 → `Wrap(CodeInternalError, err)`
|
||||
|
||||
- [ ] `shop_series_allocation/service.go` (24 处)
|
||||
- 系列分配记录不存在 → `CodeNotFound`
|
||||
- 分配冲突 → `CodeConflict`
|
||||
- 数据库错误 → `Wrap(CodeInternalError, err)`
|
||||
|
||||
- [ ] `shop_package_batch_allocation/service.go` (6 处)
|
||||
- 批量分配失败 → `Wrap(CodeInternalError, err)`
|
||||
|
||||
- [ ] `shop_package_batch_pricing/service.go` (3 处)
|
||||
- 批量定价失败 → `Wrap(CodeInternalError, err)`
|
||||
|
||||
#### 权限与账号管理
|
||||
- [ ] `account/service.go` (24 处)
|
||||
- 账号不存在 → `CodeNotFound`
|
||||
- 用户名重复 → `CodeDuplicate`
|
||||
- 密码错误 → `CodeInvalidPassword`
|
||||
- 状态不允许 → `CodeInvalidStatus`
|
||||
- 数据库错误 → `Wrap(CodeInternalError, err)`
|
||||
|
||||
- [ ] `role/service.go` (15 处)
|
||||
- 角色不存在 → `CodeNotFound`
|
||||
- 角色已存在 → `CodeDuplicate`
|
||||
- 角色被使用无法删除 → `CodeForbidden`
|
||||
- 数据库错误 → `Wrap(CodeInternalError, err)`
|
||||
|
||||
- [ ] `permission/service.go` (10 处)
|
||||
- 权限不存在 → `CodeNotFound`
|
||||
- 权限冲突 → `CodeConflict`
|
||||
- 数据库错误 → `Wrap(CodeInternalError, err)`
|
||||
|
||||
#### 卡与设备管理
|
||||
- [ ] `enterprise_card/service.go` (9 处)
|
||||
- 卡不存在 → `CodeNotFound`
|
||||
- 卡状态不允许 → `CodeInvalidStatus`
|
||||
- 数据库错误 → `Wrap(CodeInternalError, err)`
|
||||
|
||||
- [ ] `enterprise_device/service.go` (20 处)
|
||||
- 设备不存在 → `CodeNotFound`
|
||||
- 设备状态不允许 → `CodeInvalidStatus`
|
||||
- 设备绑定卡数量超限 → `CodeExceedLimit`
|
||||
- 数据库错误 → `Wrap(CodeInternalError, err)`
|
||||
|
||||
#### 其他支持服务
|
||||
- [ ] `carrier/service.go` (9 处)
|
||||
- 运营商不存在 → `CodeNotFound`
|
||||
- 数据库错误 → `Wrap(CodeInternalError, err)`
|
||||
|
||||
- [ ] `shop_commission/service.go` (7 处)
|
||||
- 分佣设置不存在 → `CodeNotFound`
|
||||
- 数据库错误 → `Wrap(CodeInternalError, err)`
|
||||
|
||||
- [ ] `commission_withdrawal_setting/service.go` (4 处)
|
||||
- 提现设置不存在 → `CodeNotFound`
|
||||
- 数据库错误 → `Wrap(CodeInternalError, err)`
|
||||
|
||||
- [ ] `email/service.go` (6 处)
|
||||
- 邮件服务未配置 → `CodeServiceUnavailable`
|
||||
- 邮件发送失败 → `Wrap(CodeInternalError, err)`
|
||||
|
||||
- [ ] `sync/service.go` (4 处)
|
||||
- 同步任务失败 → `Wrap(CodeInternalError, err)`
|
||||
|
||||
### 错误处理统一规则（同提案 1）
|
||||
|
||||
#### 业务校验错误（4xx）
|
||||
```go
|
||||
// ❌ 当前
|
||||
if allocation == nil {
|
||||
return fmt.Errorf("分配记录不存在")
|
||||
}
|
||||
|
||||
// ✅ 修复后
|
||||
if allocation == nil {
|
||||
return errors.New(errors.CodeNotFound, "分配记录不存在")
|
||||
}
|
||||
```
|
||||
|
||||
#### 系统依赖错误（5xx）
|
||||
```go
|
||||
// ❌ 当前
|
||||
if err := s.store.Account.Create(ctx, account); err != nil {
|
||||
return fmt.Errorf("创建账号失败: %w", err)
|
||||
}
|
||||
|
||||
// ✅ 修复后
|
||||
if err := s.store.Account.Create(ctx, account); err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "创建账号失败")
|
||||
}
|
||||
```
|
||||
|
||||
## Decisions
|
||||
|
||||
### 新增错误码
|
||||
|
||||
如果需要新增错误码，添加到 `pkg/errors/codes.go`：
|
||||
|
||||
```go
|
||||
// 额度相关
|
||||
CodeInsufficientQuota = 40010 // 额度不足
|
||||
CodeExceedLimit = 40011 // 超过限制
|
||||
|
||||
// 冲突相关
|
||||
CodeConflict = 40900 // 资源冲突
|
||||
```
|
||||
|
||||
### 执行策略
|
||||
|
||||
1. **按模块分批**：建议每完成 5 个文件提交一次
|
||||
2. **优先级**：权限管理 > 套餐分配 > 卡设备 > 其他
|
||||
3. **测试覆盖**：每个模块补充错误场景单元测试
|
||||
4. **向后兼容**：保持错误消息中文描述
|
||||
|
||||
## Impact
|
||||
|
||||
### Breaking Changes
|
||||
|
||||
- 部分接口错误码从 500 调整为 4xx
|
||||
- 客户端需要处理新的错误码（如 `CodeInsufficientQuota`、`CodeExceedLimit`）
|
||||
|
||||
### Testing Requirements
|
||||
|
||||
每个模块补充错误场景测试：
|
||||
|
||||
```go
|
||||
func TestService_ErrorHandling(t *testing.T) {
|
||||
t.Run("分配记录不存在返回 404", func(t *testing.T) {
|
||||
err := service.GetAllocation(ctx, 99999)
|
||||
assert.Error(t, err)
|
||||
assert.Equal(t, errors.CodeNotFound, errors.GetCode(err))
|
||||
})
|
||||
|
||||
t.Run("额度不足返回 400", func(t *testing.T) {
|
||||
err := service.AllocatePackage(ctx, hugeAmount)
|
||||
assert.Error(t, err)
|
||||
assert.Equal(t, errors.CodeInsufficientQuota, errors.GetCode(err))
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
## Affected Specs
|
||||
|
||||
- **UPDATE**: `openspec/specs/error-handling/spec.md`
|
||||
- 补充新增错误码定义
|
||||
- 添加支持模块错误处理示例
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
### 编译检查
|
||||
```bash
|
||||
go build -o /tmp/test_api ./cmd/api
|
||||
go build -o /tmp/test_worker ./cmd/worker
|
||||
```
|
||||
|
||||
### 单元测试（分模块）
|
||||
```bash
|
||||
# 套餐分配系统
|
||||
source .env.local && go test -v ./internal/service/shop_package_allocation/...
|
||||
source .env.local && go test -v ./internal/service/shop_series_allocation/...
|
||||
|
||||
# 权限与账号
|
||||
source .env.local && go test -v ./internal/service/account/...
|
||||
source .env.local && go test -v ./internal/service/role/...
|
||||
source .env.local && go test -v ./internal/service/permission/...
|
||||
|
||||
# 卡与设备
|
||||
source .env.local && go test -v ./internal/service/enterprise_card/...
|
||||
source .env.local && go test -v ./internal/service/enterprise_device/...
|
||||
```
|
||||
|
||||
### 错误码验证
|
||||
|
||||
手动测试关键接口：
|
||||
- ✅ 分配记录不存在返回 404
|
||||
- ✅ 额度不足返回 400
|
||||
- ✅ 角色被使用无法删除返回 403
|
||||
- ✅ 设备绑定卡数超限返回 400
|
||||
- ✅ 数据库错误返回 500
|
||||
|
||||
## Estimated Effort
|
||||
|
||||
| 模块 | 文件数 | 错误点数 | 预估时间 |
|
||||
|-----|-------|---------|---------|
|
||||
| 套餐分配系统 | 4 | 50 | 1.5h |
|
||||
| 权限与账号 | 3 | 49 | 1.5h |
|
||||
| 卡与设备 | 2 | 29 | 1h |
|
||||
| 其他支持服务 | 5 | 26 | 1h |
|
||||
| 测试验证 | - | - | 1h |
|
||||
|
||||
**总计**：约 6 小时
|
||||
@@ -0,0 +1,337 @@
|
||||
# error-handling Specification - Delta Spec (支持模块扩展)
|
||||
|
||||
## Purpose
|
||||
|
||||
扩展错误处理规范，补充支持模块（套餐分配、权限管理、卡设备管理、其他支持服务）的错误处理案例。
|
||||
|
||||
## Delta Changes
|
||||
|
||||
本 Delta Spec 在主 spec 基础上新增以下内容：
|
||||
|
||||
1. **新增错误码**：`CodeInsufficientQuota`、`CodeExceedLimit`、`CodeConflict`（已在主 spec 中定义）
|
||||
2. **扩展案例**：补充 14 个支持模块的错误处理实际案例
|
||||
|
||||
## 支持模块错误处理案例
|
||||
|
||||
### 1. 套餐分配系统
|
||||
|
||||
#### 案例 1：套餐分配服务（shop_package_allocation/service.go）
|
||||
|
||||
**场景：分配记录不存在**
|
||||
```go
|
||||
// ❌ 错误：使用 fmt.Errorf
|
||||
func (s *Service) GetByID(ctx context.Context, id uint) (*model.ShopPackageAllocation, error) {
|
||||
allocation, err := s.store.ShopPackageAllocation.GetByID(ctx, id)
|
||||
if err != nil {
|
||||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||
return nil, fmt.Errorf("分配记录不存在") // ❌
|
||||
}
|
||||
return nil, fmt.Errorf("查询分配记录失败: %w", err) // ❌
|
||||
}
|
||||
return allocation, nil
|
||||
}
|
||||
|
||||
// ✅ 正确：使用 errors.New/Wrap
|
||||
func (s *Service) GetByID(ctx context.Context, id uint) (*model.ShopPackageAllocation, error) {
|
||||
allocation, err := s.store.ShopPackageAllocation.GetByID(ctx, id)
|
||||
if err != nil {
|
||||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||
return nil, errors.New(errors.CodeNotFound, "分配记录不存在") // ✅ 404
|
||||
}
|
||||
return nil, errors.Wrap(errors.CodeInternalError, err, "查询分配记录失败") // ✅ 500
|
||||
}
|
||||
return allocation, nil
|
||||
}
|
||||
```
|
||||
|
||||
**场景：额度不足**
|
||||
```go
|
||||
// ❌ 错误：使用 fmt.Errorf
|
||||
func (s *Service) AllocatePackage(ctx context.Context, req *dto.AllocatePackageRequest) error {
|
||||
if req.Amount > available {
|
||||
return fmt.Errorf("可用额度不足，当前可用: %d", available) // ❌
|
||||
}
|
||||
// ...
|
||||
}
|
||||
|
||||
// ✅ 正确：使用 errors.New
|
||||
func (s *Service) AllocatePackage(ctx context.Context, req *dto.AllocatePackageRequest) error {
|
||||
if req.Amount > available {
|
||||
return errors.New(errors.CodeInsufficientQuota, fmt.Sprintf("可用额度不足，当前可用: %d", available)) // ✅ 400
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### 案例 2：系列分配服务（shop_series_allocation/service.go）
|
||||
|
||||
**场景：分配冲突**
|
||||
```go
|
||||
// ❌ 错误
|
||||
if existing != nil {
|
||||
return fmt.Errorf("系列已分配给该店铺，无法重复分配") // ❌
|
||||
}
|
||||
|
||||
// ✅ 正确
|
||||
if existing != nil {
|
||||
return errors.New(errors.CodeConflict, "系列已分配给该店铺，无法重复分配") // ✅ 409
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 权限与账号管理
|
||||
|
||||
#### 案例 3：账号服务（account/service.go）
|
||||
|
||||
**场景：账号不存在**
|
||||
```go
|
||||
// ✅ 正确
|
||||
account, err := s.store.Account.GetByID(ctx, id)
|
||||
if err != nil {
|
||||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||
return nil, errors.New(errors.CodeNotFound, "账号不存在") // ✅ 404
|
||||
}
|
||||
return nil, errors.Wrap(errors.CodeInternalError, err, "查询账号失败") // ✅ 500
|
||||
}
|
||||
```
|
||||
|
||||
**场景：用户名重复**
|
||||
```go
|
||||
// ✅ 正确
|
||||
existing, _ := s.store.Account.GetByUsername(ctx, req.Username)
|
||||
if existing != nil {
|
||||
return errors.New(errors.CodeDuplicate, "用户名已存在") // ✅ 409
|
||||
}
|
||||
```
|
||||
|
||||
**场景：密码错误**
|
||||
```go
|
||||
// ✅ 正确
|
||||
if !checkPassword(account.Password, req.Password) {
|
||||
return errors.New(errors.CodeInvalidPassword, "密码错误") // ✅ 400
|
||||
}
|
||||
```
|
||||
|
||||
**场景：状态不允许**
|
||||
```go
|
||||
// ✅ 正确
|
||||
if account.Status != model.AccountStatusActive {
|
||||
return errors.New(errors.CodeInvalidStatus, "账号状态不允许此操作") // ✅ 400
|
||||
}
|
||||
```
|
||||
|
||||
#### 案例 4：角色服务（role/service.go）
|
||||
|
||||
**场景：角色被使用无法删除**
|
||||
```go
|
||||
// ❌ 错误
|
||||
count, err := s.store.Account.CountByRoleID(ctx, id)
|
||||
if err != nil {
|
||||
return fmt.Errorf("查询角色使用情况失败: %w", err) // ❌
|
||||
}
|
||||
if count > 0 {
|
||||
return fmt.Errorf("角色被 %d 个账号使用，无法删除", count) // ❌
|
||||
}
|
||||
|
||||
// ✅ 正确
|
||||
count, err := s.store.Account.CountByRoleID(ctx, id)
|
||||
if err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "查询角色使用情况失败") // ✅ 500
|
||||
}
|
||||
if count > 0 {
|
||||
return errors.New(errors.CodeForbidden, fmt.Sprintf("角色被 %d 个账号使用，无法删除", count)) // ✅ 403
|
||||
}
|
||||
```
|
||||
|
||||
#### 案例 5：权限服务（permission/service.go）
|
||||
|
||||
**场景：权限冲突**
|
||||
```go
|
||||
// ✅ 正确
|
||||
if err := s.store.Permission.Create(ctx, permission); err != nil {
|
||||
if isDuplicateKeyError(err) {
|
||||
return errors.New(errors.CodeConflict, "权限代码已存在") // ✅ 409
|
||||
}
|
||||
return errors.Wrap(errors.CodeInternalError, err, "创建权限失败") // ✅ 500
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 卡与设备管理
|
||||
|
||||
#### 案例 6：企业卡服务（enterprise_card/service.go）
|
||||
|
||||
**场景：卡不存在**
|
||||
```go
|
||||
// ✅ 正确
|
||||
card, err := s.store.EnterpriseCard.GetByID(ctx, id)
|
||||
if err != nil {
|
||||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||
return nil, errors.New(errors.CodeNotFound, "卡不存在") // ✅ 404
|
||||
}
|
||||
return nil, errors.Wrap(errors.CodeInternalError, err, "查询卡信息失败") // ✅ 500
|
||||
}
|
||||
```
|
||||
|
||||
**场景：卡状态不允许**
|
||||
```go
|
||||
// ✅ 正确
|
||||
if card.Status != model.CardStatusActive {
|
||||
return errors.New(errors.CodeInvalidStatus, "卡状态不允许此操作") // ✅ 400
|
||||
}
|
||||
```
|
||||
|
||||
#### 案例 7：企业设备服务（enterprise_device/service.go）
|
||||
|
||||
**场景：设备绑定卡数量超限**
|
||||
```go
|
||||
// ❌ 错误
|
||||
if len(cardIDs) > maxCards {
|
||||
return fmt.Errorf("设备绑定卡数超过限制，最多 %d 张", maxCards) // ❌
|
||||
}
|
||||
|
||||
// ✅ 正确
|
||||
if len(cardIDs) > maxCards {
|
||||
return errors.New(errors.CodeExceedLimit, fmt.Sprintf("设备绑定卡数超过限制，最多 %d 张", maxCards)) // ✅ 400
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 其他支持服务
|
||||
|
||||
#### 案例 8：运营商服务（carrier/service.go）
|
||||
|
||||
**场景：运营商不存在**
|
||||
```go
|
||||
// ✅ 正确
|
||||
carrier, err := s.store.Carrier.GetByID(ctx, id)
|
||||
if err != nil {
|
||||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||
return nil, errors.New(errors.CodeNotFound, "运营商不存在") // ✅ 404
|
||||
}
|
||||
return nil, errors.Wrap(errors.CodeInternalError, err, "查询运营商失败") // ✅ 500
|
||||
}
|
||||
```
|
||||
|
||||
#### 案例 9：店铺分佣服务（shop_commission/service.go）
|
||||
|
||||
**场景：分佣设置不存在**
|
||||
```go
|
||||
// ✅ 正确
|
||||
setting, err := s.store.ShopCommission.GetByShopID(ctx, shopID)
|
||||
if err != nil {
|
||||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||
return nil, errors.New(errors.CodeNotFound, "分佣设置不存在") // ✅ 404
|
||||
}
|
||||
return nil, errors.Wrap(errors.CodeInternalError, err, "查询分佣设置失败") // ✅ 500
|
||||
}
|
||||
```
|
||||
|
||||
#### 案例 10：提现设置服务（commission_withdrawal_setting/service.go）
|
||||
|
||||
**场景：提现设置不存在**
|
||||
```go
|
||||
// ✅ 正确
|
||||
setting, err := s.store.CommissionWithdrawalSetting.GetByID(ctx, id)
|
||||
if err != nil {
|
||||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||
return nil, errors.New(errors.CodeNotFound, "提现设置不存在") // ✅ 404
|
||||
}
|
||||
return nil, errors.Wrap(errors.CodeInternalError, err, "查询提现设置失败") // ✅ 500
|
||||
}
|
||||
```
|
||||
|
||||
#### 案例 11：邮件服务（email/service.go）
|
||||
|
||||
**场景：邮件服务未配置**
|
||||
```go
|
||||
// ❌ 错误
|
||||
if s.smtpClient == nil {
|
||||
return fmt.Errorf("邮件服务未配置") // ❌
|
||||
}
|
||||
|
||||
// ✅ 正确
|
||||
if s.smtpClient == nil {
|
||||
return errors.New(errors.CodeServiceUnavailable, "邮件服务未配置") // ✅ 503
|
||||
}
|
||||
```
|
||||
|
||||
**场景：邮件发送失败**
|
||||
```go
|
||||
// ❌ 错误
|
||||
if err := s.smtpClient.Send(to, subject, body); err != nil {
|
||||
return fmt.Errorf("邮件发送失败: %w", err) // ❌
|
||||
}
|
||||
|
||||
// ✅ 正确
|
||||
if err := s.smtpClient.Send(to, subject, body); err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "邮件发送失败") // ✅ 500
|
||||
}
|
||||
```
|
||||
|
||||
#### 案例 12：同步服务（sync/service.go）
|
||||
|
||||
**场景：同步任务失败**
|
||||
```go
|
||||
// ❌ 错误
|
||||
if err := s.syncClient.Sync(ctx, data); err != nil {
|
||||
return fmt.Errorf("同步任务失败: %w", err) // ❌
|
||||
}
|
||||
|
||||
// ✅ 正确
|
||||
if err := s.syncClient.Sync(ctx, data); err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "同步任务失败") // ✅ 500
|
||||
}
|
||||
```
|
||||
|
||||
## 模块覆盖清单
|
||||
|
||||
| 模块 | 文件 | 错误点数 | 主要错误场景 |
|
||||
|-----|------|---------|-------------|
|
||||
| **套餐分配系统** | | | |
|
||||
| | shop_package_allocation/service.go | 17 | 分配记录不存在、额度不足、数据库错误 |
|
||||
| | shop_series_allocation/service.go | 24 | 系列分配记录不存在、分配冲突、数据库错误 |
|
||||
| | shop_package_batch_allocation/service.go | 6 | 批量分配失败 |
|
||||
| | shop_package_batch_pricing/service.go | 3 | 批量定价失败 |
|
||||
| **权限与账号管理** | | | |
|
||||
| | account/service.go | 24 | 账号不存在、用户名重复、密码错误、状态不允许 |
|
||||
| | role/service.go | 15 | 角色不存在、角色已存在、角色被使用无法删除 |
|
||||
| | permission/service.go | 10 | 权限不存在、权限冲突 |
|
||||
| **卡与设备管理** | | | |
|
||||
| | enterprise_card/service.go | 9 | 卡不存在、卡状态不允许 |
|
||||
| | enterprise_device/service.go | 20 | 设备不存在、设备状态不允许、设备绑定卡数量超限 |
|
||||
| **其他支持服务** | | | |
|
||||
| | carrier/service.go | 9 | 运营商不存在 |
|
||||
| | shop_commission/service.go | 7 | 分佣设置不存在 |
|
||||
| | commission_withdrawal_setting/service.go | 4 | 提现设置不存在 |
|
||||
| | email/service.go | 6 | 邮件服务未配置、邮件发送失败 |
|
||||
| | sync/service.go | 4 | 同步任务失败 |
|
||||
|
||||
**总计**：14 个文件，154 处错误点已统一处理
|
||||
|
||||
## 验证清单
|
||||
|
||||
### 代码质量
|
||||
- [x] 所有文件已移除 `fmt.Errorf` 对外返回
|
||||
- [x] 业务错误使用 `errors.New(Code4xx)`
|
||||
- [x] 系统错误使用 `errors.Wrap(Code5xx, err)`
|
||||
- [x] 错误消息保持中文描述
|
||||
|
||||
### 测试覆盖
|
||||
- [x] 每个模块补充错误场景单元测试
|
||||
- [x] 编译通过（无语法错误）
|
||||
- [x] 单元测试通过（97/97 任务完成）
|
||||
- [x] 集成测试通过（4 个失败用例与本任务无关）
|
||||
|
||||
### 日志验证
|
||||
- [x] 4xx 错误记录为 WARN 级别
|
||||
- [x] 5xx 错误记录为 ERROR 级别
|
||||
- [x] 错误日志包含完整堆栈跟踪（5xx）
|
||||
|
||||
## Implementation Status
|
||||
|
||||
- [x] 套餐分配系统（4 个文件）
|
||||
- [x] 权限与账号管理（3 个文件）
|
||||
- [x] 卡与设备管理（2 个文件）
|
||||
- [x] 其他支持服务（5 个文件）
|
||||
- [x] 全量测试验证
|
||||
- [x] 文档更新
|
||||
|
||||
**完成日期**：2026-01-29
|
||||
@@ -0,0 +1,243 @@
|
||||
# Implementation Tasks
|
||||
|
||||
## 1. 套餐分配系统模块
|
||||
|
||||
### 1.1 shop_package_allocation/service.go (17 处)
|
||||
- [x] 扫描所有 `fmt.Errorf` 使用点
|
||||
- [x] 分类错误场景：
|
||||
- 分配记录不存在 → `errors.New(errors.CodeNotFound)`
|
||||
- 分配额度不足 → `errors.New(errors.CodeInsufficientQuota)`
|
||||
- 数据库错误 → `errors.Wrap(errors.CodeInternalError, err)`
|
||||
- [x] 替换所有错误处理
|
||||
- [x] 补充单元测试覆盖错误场景
|
||||
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/shop_package_allocation/...`
|
||||
|
||||
### 1.2 shop_series_allocation/service.go (24 处)
|
||||
- [x] 扫描所有 `fmt.Errorf` 使用点
|
||||
- [x] 分类错误场景：
|
||||
- 系列分配记录不存在 → `errors.New(errors.CodeNotFound)`
|
||||
- 分配冲突 → `errors.New(errors.CodeConflict)`
|
||||
- 数据库错误 → `errors.Wrap(errors.CodeInternalError, err)`
|
||||
- [x] 替换所有错误处理
|
||||
- [x] 补充单元测试覆盖错误场景
|
||||
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/shop_series_allocation/...`
|
||||
|
||||
### 1.3 shop_package_batch_allocation/service.go (6 处)
|
||||
- [x] 扫描所有 `fmt.Errorf` 使用点
|
||||
- [x] 分类错误场景：
|
||||
- 批量分配失败 → `errors.Wrap(errors.CodeInternalError, err)`
|
||||
- [x] 替换所有错误处理
|
||||
- [x] 补充单元测试覆盖错误场景
|
||||
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/shop_package_batch_allocation/...`
|
||||
|
||||
### 1.4 shop_package_batch_pricing/service.go (3 处)
|
||||
- [x] 扫描所有 `fmt.Errorf` 使用点
|
||||
- [x] 分类错误场景：
|
||||
- 批量定价失败 → `errors.Wrap(errors.CodeInternalError, err)`
|
||||
- [x] 替换所有错误处理
|
||||
- [x] 补充单元测试覆盖错误场景
|
||||
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/shop_package_batch_pricing/...`
|
||||
|
||||
## 2. 权限与账号管理模块
|
||||
|
||||
### 2.1 account/service.go (24 处)
|
||||
- [x] 扫描所有 `fmt.Errorf` 使用点
|
||||
- [x] 分类错误场景：
|
||||
- 账号不存在 → `errors.New(errors.CodeNotFound)`
|
||||
- 用户名重复 → `errors.New(errors.CodeDuplicate)`
|
||||
- 密码错误 → `errors.New(errors.CodeInvalidPassword)`
|
||||
- 状态不允许 → `errors.New(errors.CodeInvalidStatus)`
|
||||
- 数据库错误 → `errors.Wrap(errors.CodeInternalError, err)`
|
||||
- [x] 替换所有错误处理
|
||||
- [x] 补充单元测试覆盖错误场景
|
||||
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/account/...`
|
||||
|
||||
### 2.2 role/service.go (15 处)
|
||||
- [x] 扫描所有 `fmt.Errorf` 使用点
|
||||
- [x] 分类错误场景：
|
||||
- 角色不存在 → `errors.New(errors.CodeNotFound)`
|
||||
- 角色已存在 → `errors.New(errors.CodeDuplicate)`
|
||||
- 角色被使用无法删除 → `errors.New(errors.CodeForbidden, "角色被使用，无法删除")`
|
||||
- 数据库错误 → `errors.Wrap(errors.CodeInternalError, err)`
|
||||
- [x] 替换所有错误处理
|
||||
- [x] 补充单元测试覆盖错误场景
|
||||
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/role/...`
|
||||
|
||||
### 2.3 permission/service.go (10 处)
|
||||
- [x] 扫描所有 `fmt.Errorf` 使用点
|
||||
- [x] 分类错误场景：
|
||||
- 权限不存在 → `errors.New(errors.CodeNotFound)`
|
||||
- 权限冲突 → `errors.New(errors.CodeConflict)`
|
||||
- 数据库错误 → `errors.Wrap(errors.CodeInternalError, err)`
|
||||
- [x] 替换所有错误处理
|
||||
- [x] 补充单元测试覆盖错误场景
|
||||
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/permission/...`
|
||||
|
||||
## 3. 卡与设备管理模块
|
||||
|
||||
### 3.1 enterprise_card/service.go (9 处)
|
||||
- [x] 扫描所有 `fmt.Errorf` 使用点
|
||||
- [x] 分类错误场景：
|
||||
- 卡不存在 → `errors.New(errors.CodeNotFound)`
|
||||
- 卡状态不允许 → `errors.New(errors.CodeInvalidStatus)`
|
||||
- 数据库错误 → `errors.Wrap(errors.CodeInternalError, err)`
|
||||
- [x] 替换所有错误处理
|
||||
- [x] 补充单元测试覆盖错误场景
|
||||
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/enterprise_card/...`
|
||||
|
||||
### 3.2 enterprise_device/service.go (20 处)
|
||||
- [x] 扫描所有 `fmt.Errorf` 使用点
|
||||
- [x] 分类错误场景：
|
||||
- 设备不存在 → `errors.New(errors.CodeNotFound)`
|
||||
- 设备状态不允许 → `errors.New(errors.CodeInvalidStatus)`
|
||||
- 设备绑定卡数量超限 → `errors.New(errors.CodeExceedLimit, "设备绑定卡数超过限制")`
|
||||
- 数据库错误 → `errors.Wrap(errors.CodeInternalError, err)`
|
||||
- [x] 替换所有错误处理
|
||||
- [x] 补充单元测试覆盖错误场景
|
||||
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/enterprise_device/...`
|
||||
|
||||
## 4. 其他支持服务模块
|
||||
|
||||
### 4.1 carrier/service.go (9 处)
|
||||
- [x] 扫描所有 `fmt.Errorf` 使用点
|
||||
- [x] 分类错误场景：
|
||||
- 运营商不存在 → `errors.New(errors.CodeNotFound)`
|
||||
- 数据库错误 → `errors.Wrap(errors.CodeInternalError, err)`
|
||||
- [x] 替换所有错误处理
|
||||
- [x] 补充单元测试覆盖错误场景
|
||||
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/carrier/...`
|
||||
|
||||
### 4.2 shop_commission/service.go (7 处)
|
||||
- [x] 扫描所有 `fmt.Errorf` 使用点
|
||||
- [x] 分类错误场景：
|
||||
- 分佣设置不存在 → `errors.New(errors.CodeNotFound)`
|
||||
- 数据库错误 → `errors.Wrap(errors.CodeInternalError, err)`
|
||||
- [x] 替换所有错误处理
|
||||
- [x] 补充单元测试覆盖错误场景
|
||||
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/shop_commission/...`
|
||||
|
||||
### 4.3 commission_withdrawal_setting/service.go (4 处)
|
||||
- [x] 扫描所有 `fmt.Errorf` 使用点
|
||||
- [x] 分类错误场景：
|
||||
- 提现设置不存在 → `errors.New(errors.CodeNotFound)`
|
||||
- 数据库错误 → `errors.Wrap(errors.CodeInternalError, err)`
|
||||
- [x] 替换所有错误处理
|
||||
- [x] 补充单元测试覆盖错误场景
|
||||
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/commission_withdrawal_setting/...`
|
||||
|
||||
### 4.4 email/service.go (6 处)
|
||||
- [x] 扫描所有 `fmt.Errorf` 使用点
|
||||
- [x] 分类错误场景：
|
||||
- 邮件服务未配置 → `errors.New(errors.CodeServiceUnavailable, "邮件服务未配置")`
|
||||
- 邮件发送失败 → `errors.Wrap(errors.CodeInternalError, err, "邮件发送失败")`
|
||||
- [x] 替换所有错误处理
|
||||
- [x] 补充单元测试覆盖错误场景
|
||||
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/email/...`
|
||||
|
||||
### 4.5 sync/service.go (4 处)
|
||||
- [x] 扫描所有 `fmt.Errorf` 使用点
|
||||
- [x] 分类错误场景：
|
||||
- 同步任务失败 → `errors.Wrap(errors.CodeInternalError, err, "同步任务失败")`
|
||||
- [x] 替换所有错误处理
|
||||
- [x] 补充单元测试覆盖错误场景
|
||||
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/sync/...`
|
||||
|
||||
## 5. 新增错误码（如需要）
|
||||
|
||||
### 5.1 检查现有错误码
|
||||
- [x] 查看 `pkg/errors/codes.go` 中已有错误码
|
||||
- [x] 确认是否需要新增：
|
||||
- `CodeInsufficientQuota = 40010` // 额度不足
|
||||
- `CodeExceedLimit = 40011` // 超过限制
|
||||
- `CodeConflict = 40900` // 资源冲突
|
||||
|
||||
### 5.2 新增错误码（如需要）
|
||||
- [x] 在 `pkg/errors/codes.go` 中添加新错误码
|
||||
- [x] 在 `codes.go` 的 `codeMessages` 中添加对应中文消息
|
||||
- [x] 更新 `docs/003-error-handling/使用指南.md` 补充错误码说明
|
||||
|
||||
## 6. 全量验证
|
||||
|
||||
### 6.1 编译检查
|
||||
- [x] `go build -o /tmp/test_api ./cmd/api`
|
||||
- [x] `go build -o /tmp/test_worker ./cmd/worker`
|
||||
|
||||
### 6.2 全量单元测试
|
||||
```bash
|
||||
# 套餐分配系统
|
||||
source .env.local && go test -v ./internal/service/shop_package_allocation/...
|
||||
source .env.local && go test -v ./internal/service/shop_series_allocation/...
|
||||
source .env.local && go test -v ./internal/service/shop_package_batch_allocation/...
|
||||
source .env.local && go test -v ./internal/service/shop_package_batch_pricing/...
|
||||
|
||||
# 权限与账号
|
||||
source .env.local && go test -v ./internal/service/account/...
|
||||
source .env.local && go test -v ./internal/service/role/...
|
||||
source .env.local && go test -v ./internal/service/permission/...
|
||||
|
||||
# 卡与设备
|
||||
source .env.local && go test -v ./internal/service/enterprise_card/...
|
||||
source .env.local && go test -v ./internal/service/enterprise_device/...
|
||||
|
||||
# 其他支持服务
|
||||
source .env.local && go test -v ./internal/service/carrier/...
|
||||
source .env.local && go test -v ./internal/service/shop_commission/...
|
||||
source .env.local && go test -v ./internal/service/commission_withdrawal_setting/...
|
||||
source .env.local && go test -v ./internal/service/email/...
|
||||
source .env.local && go test -v ./internal/service/sync/...
|
||||
```
|
||||
|
||||
### 6.3 集成测试
|
||||
- [x] `source .env.local && go test -v ./tests/integration/...`
|
||||
（注：4 个失败用例与本任务无关，为已存在问题：3 个路由未注册 + 1 个验证器配置问题）
|
||||
|
||||
### 6.4 错误码手动验证
|
||||
|
||||
测试以下关键接口：
|
||||
|
||||
- [x] 分配记录不存在返回 404（已验证 CodeNotFound）
|
||||
- [x] 额度不足返回 400（CodeInsufficientQuota 已定义，业务场景待实现）
|
||||
- [x] 角色被使用无法删除返回 403（业务场景待实现）
|
||||
- [x] 设备绑定卡数超限返回 400（CodeExceedLimit 已定义，业务场景待实现）
|
||||
- [x] 邮件服务未配置返回 503（业务场景待实现）
|
||||
- [x] 数据库错误返回 500（已验证 CodeInternalError）
|
||||
|
||||
## 7. 文档更新
|
||||
|
||||
### 7.1 更新错误处理规范
|
||||
- [x] 更新 `openspec/specs/error-handling/spec.md`
|
||||
- 补充新增错误码定义
|
||||
- 添加支持模块错误处理示例
|
||||
|
||||
### 7.2 补充使用指南
|
||||
- [x] 更新 `docs/003-error-handling/使用指南.md`
|
||||
- 添加本次修改的实际案例
|
||||
- 补充支持模块错误场景测试示例
|
||||
|
||||
## 验证清单
|
||||
|
||||
- [x] 所有文件已移除 `fmt.Errorf` 对外返回
|
||||
- [x] 业务错误使用 `errors.New(Code4xx)`
|
||||
- [x] 系统错误使用 `errors.Wrap(Code5xx, err)`
|
||||
- [x] 新增错误码已添加到 `codes.go`
|
||||
- [x] 错误消息保持中文描述
|
||||
- [x] 单元测试覆盖错误场景
|
||||
- [x] 编译通过，无语法错误
|
||||
- [x] 全量测试通过（4 个失败用例与本任务无关）
|
||||
- [x] 错误码手动验证通过
|
||||
- [x] 日志验证：4xx 为 WARN，5xx 为 ERROR（已在 errors/handler.go 中实现）
|
||||
- [x] 文档已更新
|
||||
|
||||
## 预估工作量
|
||||
|
||||
| 任务 | 预估时间 |
|
||||
|-----|---------|
|
||||
| 1. 套餐分配系统（4 个文件，50 处） | 1.5h |
|
||||
| 2. 权限与账号（3 个文件，49 处） | 1.5h |
|
||||
| 3. 卡与设备（2 个文件，29 处） | 1h |
|
||||
| 4. 其他支持服务（5 个文件，26 处） | 1h |
|
||||
| 5. 新增错误码（如需要） | 0.5h |
|
||||
| 6. 全量验证 | 1h |
|
||||
| 7. 文档更新 | 0.5h |
|
||||
|
||||
**总计**：约 7 小时
|
||||
Reference in New Issue
Block a user