# Implementation Tasks

## 1. 订单与套餐管理模块

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

### 1.2 package_series/service.go (9 处)
- [x] 扫描所有 `fmt.Errorf` 使用点
- [x] 分类错误场景：
  - 套餐系列不存在 → `errors.New(errors.CodeNotFound)`
  - 套餐系列已存在 → `errors.New(errors.CodeDuplicate)`
  - 数据库错误 → `errors.Wrap(errors.CodeInternalError, err)`
- [x] 替换所有错误处理
- [x] 补充单元测试覆盖错误场景
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/package_series/...`

## 2. 分佣系统模块

### 2.1 commission_withdrawal/service.go (7 处)
- [x] 扫描所有 `fmt.Errorf` 使用点
- [x] 分类错误场景：
  - 余额不足 → `errors.New(errors.CodeInsufficientBalance)`
  - 提现状态不允许 → `errors.New(errors.CodeInvalidStatus)`
  - 数据库错误 → `errors.Wrap(errors.CodeInternalError, err)`
  - 队列错误 → `errors.Wrap(errors.CodeInternalError, err)`
- [x] 替换所有错误处理
- [x] 补充单元测试覆盖错误场景
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/commission_withdrawal/...`

### 2.2 commission_stats/service.go (3 处)
- [x] 扫描所有 `fmt.Errorf` 使用点
- [x] 分类错误场景：
  - 统计计算失败 → `errors.Wrap(errors.CodeInternalError, err)`
- [x] 替换所有错误处理
- [x] 补充单元测试覆盖错误场景
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/commission_stats/...`

### 2.3 my_commission/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/my_commission/...`

## 3. 店铺与企业模块

### 3.1 shop/service.go (8 处)
- [x] 扫描所有 `fmt.Errorf` 使用点
- [x] 分类错误场景：
  - 店铺不存在 → `errors.New(errors.CodeNotFound)`
  - 店铺代码重复 → `errors.New(errors.CodeDuplicate)`
  - 层级超过限制 → `errors.New(errors.CodeInvalidParam, "店铺层级超过限制")`
  - 数据库错误 → `errors.Wrap(errors.CodeInternalError, err)`
- [x] 替换所有错误处理
- [x] 补充单元测试覆盖错误场景
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/shop/...`

### 3.2 enterprise/service.go (7 处)
- [x] 扫描所有 `fmt.Errorf` 使用点
- [x] 分类错误场景：
  - 企业不存在 → `errors.New(errors.CodeNotFound)`
  - 企业代码重复 → `errors.New(errors.CodeDuplicate)`
  - 数据库错误 → `errors.Wrap(errors.CodeInternalError, err)`
- [x] 替换所有错误处理
- [x] 补充单元测试覆盖错误场景
- [x] 运行测试验证：`source .env.local && go test -v ./internal/service/enterprise/...`

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

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

## 4. 全量验证

### 4.1 编译检查
- [x] `go build -o /tmp/test_api ./cmd/api`
- [x] `go build -o /tmp/test_worker ./cmd/worker`

### 4.2 全量单元测试
- [x] `source .env.local && go test -v ./internal/service/package/...`
- [x] `source .env.local && go test -v ./internal/service/package_series/...`
- [x] `source .env.local && go test -v ./internal/service/commission_withdrawal/...`
- [x] `source .env.local && go test -v ./internal/service/commission_stats/...`
- [x] `source .env.local && go test -v ./internal/service/my_commission/...`
- [x] `source .env.local && go test -v ./internal/service/shop/...`
- [x] `source .env.local && go test -v ./internal/service/enterprise/...`
- [x] `source .env.local && go test -v ./internal/service/shop_account/...`
- [x] `source .env.local && go test -v ./internal/service/customer_account/...`

### 4.3 集成测试
- [x] `source .env.local && go test -v ./tests/integration/...`

### 4.4 错误码手动验证

测试以下关键接口（通过 API 或单元测试）：

- [x] 套餐不存在返回 404（`GET /api/admin/packages/99999`）
- [x] 订单状态不允许返回 400（取消已取消的订单）
- [x] 余额不足返回 400（提现金额 > 余额）
- [x] 店铺代码重复返回 409（创建重复店铺代码）
- [x] 数据库错误返回 500（模拟数据库故障）

## 5. 文档更新

### 5.1 更新错误处理规范
- [x] 更新 `openspec/specs/error-handling/spec.md`
  - 补充 Service 层错误处理规范
  - 添加错误码映射表

### 5.2 补充使用指南
- [x] 更新 `docs/003-error-handling/使用指南.md`
  - 添加本次修改的实际案例
  - 补充错误场景单元测试示例

## 验证清单

- [x] 所有文件已移除 `fmt.Errorf` 对外返回
- [x] 业务错误使用 `errors.New(Code4xx)`
- [x] 系统错误使用 `errors.Wrap(Code5xx, err)`
- [x] 错误消息保持中文描述
- [x] 单元测试覆盖错误场景
- [x] 编译通过，无语法错误
- [x] 全量测试通过
- [x] 错误码手动验证通过
- [x] 日志验证：4xx 为 WARN，5xx 为 ERROR
- [x] 文档已更新

## 预估工作量

| 任务 | 预估时间 |
|-----|---------|
| 1. 订单与套餐模块（2 个文件） | 1h |
| 2. 分佣系统模块（3 个文件） | 1h |
| 3. 店铺与企业模块（4 个文件） | 1.5h |
| 4. 全量验证 | 0.5h |
| 5. 文档更新 | 0.5h |

**总计**：约 4.5 小时
