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

Implementation Tasks

1. 套餐分配系统模块

1.1 shop_package_allocation/service.go (17 处)

• 扫描所有 fmt.Errorf 使用点
• 分类错误场景：
  • 分配记录不存在 → errors.New(errors.CodeNotFound)
  • 分配额度不足 → errors.New(errors.CodeInsufficientQuota)
  • 数据库错误 → errors.Wrap(errors.CodeInternalError, err)
• 替换所有错误处理
• 补充单元测试覆盖错误场景
• 运行测试验证：source .env.local && go test -v ./internal/service/shop_package_allocation/...

1.2 shop_series_allocation/service.go (24 处)

• 扫描所有 fmt.Errorf 使用点
• 分类错误场景：
  • 系列分配记录不存在 → errors.New(errors.CodeNotFound)
  • 分配冲突 → errors.New(errors.CodeConflict)
  • 数据库错误 → errors.Wrap(errors.CodeInternalError, err)
• 替换所有错误处理
• 补充单元测试覆盖错误场景
• 运行测试验证：source .env.local && go test -v ./internal/service/shop_series_allocation/...

1.3 shop_package_batch_allocation/service.go (6 处)

• 扫描所有 fmt.Errorf 使用点
• 分类错误场景：
  • 批量分配失败 → errors.Wrap(errors.CodeInternalError, err)
• 替换所有错误处理
• 补充单元测试覆盖错误场景
• 运行测试验证：source .env.local && go test -v ./internal/service/shop_package_batch_allocation/...

1.4 shop_package_batch_pricing/service.go (3 处)

• 扫描所有 fmt.Errorf 使用点
• 分类错误场景：
  • 批量定价失败 → errors.Wrap(errors.CodeInternalError, err)
• 替换所有错误处理
• 补充单元测试覆盖错误场景
• 运行测试验证：source .env.local && go test -v ./internal/service/shop_package_batch_pricing/...

2. 权限与账号管理模块

2.1 account/service.go (24 处)

• 扫描所有 fmt.Errorf 使用点
• 分类错误场景：
  • 账号不存在 → errors.New(errors.CodeNotFound)
  • 用户名重复 → errors.New(errors.CodeDuplicate)
  • 密码错误 → errors.New(errors.CodeInvalidPassword)
  • 状态不允许 → errors.New(errors.CodeInvalidStatus)
  • 数据库错误 → errors.Wrap(errors.CodeInternalError, err)
• 替换所有错误处理
• 补充单元测试覆盖错误场景
• 运行测试验证：source .env.local && go test -v ./internal/service/account/...

2.2 role/service.go (15 处)

• 扫描所有 fmt.Errorf 使用点
• 分类错误场景：
  • 角色不存在 → errors.New(errors.CodeNotFound)
  • 角色已存在 → errors.New(errors.CodeDuplicate)
  • 角色被使用无法删除 → errors.New(errors.CodeForbidden, "角色被使用，无法删除")
  • 数据库错误 → errors.Wrap(errors.CodeInternalError, err)
• 替换所有错误处理
• 补充单元测试覆盖错误场景
• 运行测试验证：source .env.local && go test -v ./internal/service/role/...

2.3 permission/service.go (10 处)

• 扫描所有 fmt.Errorf 使用点
• 分类错误场景：
  • 权限不存在 → errors.New(errors.CodeNotFound)
  • 权限冲突 → errors.New(errors.CodeConflict)
  • 数据库错误 → errors.Wrap(errors.CodeInternalError, err)
• 替换所有错误处理
• 补充单元测试覆盖错误场景
• 运行测试验证：source .env.local && go test -v ./internal/service/permission/...

3. 卡与设备管理模块

3.1 enterprise_card/service.go (9 处)

• 扫描所有 fmt.Errorf 使用点
• 分类错误场景：
  • 卡不存在 → errors.New(errors.CodeNotFound)
  • 卡状态不允许 → errors.New(errors.CodeInvalidStatus)
  • 数据库错误 → errors.Wrap(errors.CodeInternalError, err)
• 替换所有错误处理
• 补充单元测试覆盖错误场景
• 运行测试验证：source .env.local && go test -v ./internal/service/enterprise_card/...

3.2 enterprise_device/service.go (20 处)

• 扫描所有 fmt.Errorf 使用点
• 分类错误场景：
  • 设备不存在 → errors.New(errors.CodeNotFound)
  • 设备状态不允许 → errors.New(errors.CodeInvalidStatus)
  • 设备绑定卡数量超限 → errors.New(errors.CodeExceedLimit, "设备绑定卡数超过限制")
  • 数据库错误 → errors.Wrap(errors.CodeInternalError, err)
• 替换所有错误处理
• 补充单元测试覆盖错误场景
• 运行测试验证：source .env.local && go test -v ./internal/service/enterprise_device/...

4. 其他支持服务模块

4.1 carrier/service.go (9 处)

• 扫描所有 fmt.Errorf 使用点
• 分类错误场景：
  • 运营商不存在 → errors.New(errors.CodeNotFound)
  • 数据库错误 → errors.Wrap(errors.CodeInternalError, err)
• 替换所有错误处理
• 补充单元测试覆盖错误场景
• 运行测试验证：source .env.local && go test -v ./internal/service/carrier/...

4.2 shop_commission/service.go (7 处)

• 扫描所有 fmt.Errorf 使用点
• 分类错误场景：
  • 分佣设置不存在 → errors.New(errors.CodeNotFound)
  • 数据库错误 → errors.Wrap(errors.CodeInternalError, err)
• 替换所有错误处理
• 补充单元测试覆盖错误场景
• 运行测试验证：source .env.local && go test -v ./internal/service/shop_commission/...

4.3 commission_withdrawal_setting/service.go (4 处)

• 扫描所有 fmt.Errorf 使用点
• 分类错误场景：
  • 提现设置不存在 → errors.New(errors.CodeNotFound)
  • 数据库错误 → errors.Wrap(errors.CodeInternalError, err)
• 替换所有错误处理
• 补充单元测试覆盖错误场景
• 运行测试验证：source .env.local && go test -v ./internal/service/commission_withdrawal_setting/...

4.4 email/service.go (6 处)

• 扫描所有 fmt.Errorf 使用点
• 分类错误场景：
  • 邮件服务未配置 → errors.New(errors.CodeServiceUnavailable, "邮件服务未配置")
  • 邮件发送失败 → errors.Wrap(errors.CodeInternalError, err, "邮件发送失败")
• 替换所有错误处理
• 补充单元测试覆盖错误场景
• 运行测试验证：source .env.local && go test -v ./internal/service/email/...

4.5 sync/service.go (4 处)

• 扫描所有 fmt.Errorf 使用点
• 分类错误场景：
  • 同步任务失败 → errors.Wrap(errors.CodeInternalError, err, "同步任务失败")
• 替换所有错误处理
• 补充单元测试覆盖错误场景
• 运行测试验证：source .env.local && go test -v ./internal/service/sync/...

5. 新增错误码（如需要）

5.1 检查现有错误码

• 查看 pkg/errors/codes.go 中已有错误码
• 确认是否需要新增：
  • CodeInsufficientQuota = 40010 // 额度不足
  • CodeExceedLimit = 40011 // 超过限制
  • CodeConflict = 40900 // 资源冲突

5.2 新增错误码（如需要）

• 在 pkg/errors/codes.go 中添加新错误码
• 在 codes.go 的 codeMessages 中添加对应中文消息
• 更新 docs/003-error-handling/使用指南.md 补充错误码说明

6. 全量验证

6.1 编译检查

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

6.2 全量单元测试

# 套餐分配系统
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 集成测试

• source .env.local && go test -v ./tests/integration/... （注：4 个失败用例与本任务无关，为已存在问题：3 个路由未注册 + 1 个验证器配置问题）

6.4 错误码手动验证

测试以下关键接口：

• 分配记录不存在返回 404（已验证 CodeNotFound）
• 额度不足返回 400（CodeInsufficientQuota 已定义，业务场景待实现）
• 角色被使用无法删除返回 403（业务场景待实现）
• 设备绑定卡数超限返回 400（CodeExceedLimit 已定义，业务场景待实现）
• 邮件服务未配置返回 503（业务场景待实现）
• 数据库错误返回 500（已验证 CodeInternalError）

7. 文档更新

7.1 更新错误处理规范

• 更新 openspec/specs/error-handling/spec.md
  • 补充新增错误码定义
  • 添加支持模块错误处理示例

7.2 补充使用指南

• 更新 docs/003-error-handling/使用指南.md
  • 添加本次修改的实际案例
  • 补充支持模块错误场景测试示例

验证清单

• 所有文件已移除 fmt.Errorf 对外返回
• 业务错误使用 errors.New(Code4xx)
• 系统错误使用 errors.Wrap(Code5xx, err)
• 新增错误码已添加到 codes.go
• 错误消息保持中文描述
• 单元测试覆盖错误场景
• 编译通过，无语法错误
• 全量测试通过（4 个失败用例与本任务无关）
• 错误码手动验证通过
• 日志验证：4xx 为 WARN，5xx 为 ERROR（已在 errors/handler.go 中实现）
• 文档已更新

预估工作量

任务	预估时间
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 小时