junhong_cmp_fiber/openspec/changes/archive/2026-01-29-service-error-unify-support/proposal.md

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）

// ❌ 当前
if allocation == nil {
    return fmt.Errorf("分配记录不存在")
}

// ✅ 修复后
if allocation == nil {
    return errors.New(errors.CodeNotFound, "分配记录不存在")
}

系统依赖错误（5xx）

// ❌ 当前
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：

// 额度相关
CodeInsufficientQuota = 40010  // 额度不足
CodeExceedLimit       = 40011  // 超过限制

// 冲突相关
CodeConflict          = 40900  // 资源冲突

执行策略

1. 按模块分批：建议每完成 5 个文件提交一次
2. 优先级：权限管理 > 套餐分配 > 卡设备 > 其他
3. 测试覆盖：每个模块补充错误场景单元测试
4. 向后兼容：保持错误消息中文描述

Impact

Breaking Changes

• 部分接口错误码从 500 调整为 4xx
• 客户端需要处理新的错误码（如 CodeInsufficientQuota、CodeExceedLimit）

Testing Requirements

每个模块补充错误场景测试：

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

编译检查

go build -o /tmp/test_api ./cmd/api
go build -o /tmp/test_worker ./cmd/worker

单元测试（分模块）

# 套餐分配系统
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 小时