# 后续工作建议

基于当前已完成的工作，建议将剩余任务拆分为 4 个独立的 OpenSpec 变更，按优先级顺序执行。

---

## 提案 1：Service 层错误语义统一 - 核心业务模块

**优先级**：🔴 高

### Why
完成核心业务模块的错误语义统一，确保订单、套餐、分佣等关键流程的错误处理一致性。

### What Changes
统一以下 10 个核心模块的错误处理（约 70-80 处）：

**订单与套餐管理**：
- `package/service.go` (14 处)
- `package_series/service.go` (9 处)
- `order/service.go` (已完成)

**分佣系统**：
- `commission_withdrawal/service.go` (7 处)
- `commission_stats/service.go` (3 处)
- `my_commission/service.go` (9 处)

**店铺与企业**：
- `shop/service.go` (8 处)
- `enterprise/service.go` (7 处)
- `shop_account/service.go` (11 处)
- `customer_account/service.go` (6 处)

### Decisions
- 数据库/Redis/队列错误统一为 `errors.Wrap(CodeInternalError, err, msg)`
- 业务校验错误（如状态不允许、资源不存在）为 `errors.New(Code4xx, msg)`
- 每完成 2-3 个文件运行一次相关测试

### Impact
- **Breaking Changes**：部分接口错误码从 500 调整为 4xx
- **测试要求**：每个模块补充错误场景测试
- **文档更新**：更新 API 文档中的错误码说明

---

## 提案 2：Service 层错误语义统一 - 支持模块

**优先级**：🟡 中

### Why
完成剩余支持模块的错误语义统一，实现全局一致性。

### What Changes
统一以下 14 个支持模块的错误处理（约 140-150 处）：

**套餐分配系统**：
- `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 处)
- `iot_card_import/service.go` (2 处)
- `device_import/service.go` (已完成)

**其他支持服务**：
- `carrier/service.go` (9 处)
- `shop_commission/service.go` (7 处)
- `commission_withdrawal_setting/service.go` (4 处)
- `email/service.go` (6 处)
- `sync/service.go` (4 处)

### Decisions
- 同提案 1 的错误处理规则
- 可以分批次提交（如每 5 个文件一个 commit）

---

## 提案 3：Handler 层参数校验安全加固

**优先级**：🟡 中

### Why
防止参数校验错误泄露内部实现细节（validator 规则、字段名等），提升安全性。

### What Changes

**修复模式**：

```go
// ❌ 当前（泄露细节）
if err := c.BodyParser(&req); err != nil {
    return response.Error(c, 400, errors.CodeInvalidParam, "参数解析失败: "+err.Error())
}

if err := validate.Struct(&req); err != nil {
    return response.Error(c, 400, errors.CodeInvalidParam, "参数验证失败: "+err.Error())
}

// ✅ 修复后（安全）
if err := c.BodyParser(&req); err != nil {
    logger.GetAppLogger().Warn("参数解析失败", 
        zap.String("path", c.Path()),
        zap.Error(err),
    )
    return response.Error(c, 400, errors.CodeInvalidParam, "参数解析失败")
}

if err := validate.Struct(&req); err != nil {
    logger.GetAppLogger().Warn("参数验证失败",
        zap.String("path", c.Path()),
        zap.Error(err),
    )
    return errors.New(errors.CodeInvalidParam)  // 使用默认 msg
}
```

**影响范围**：
- `internal/handler/admin/**` (约 20-25 个文件)
- `internal/handler/h5/**` (约 5-8 个文件)
- `internal/handler/personal/**` (约 3-5 个文件)

### Decisions
- 详细校验错误只写日志，不返回给客户端
- 统一返回 `CodeInvalidParam` + 通用消息
- 为关键 Handler 补充参数校验测试

### Testing
```go
func TestHandler_InvalidParam(t *testing.T) {
    // 测试参数缺失
    resp := testRequest(t, "POST", "/api/admin/users", `{}`)
    assert.Equal(t, 400, resp.StatusCode)
    
    var result map[string]interface{}
    json.Unmarshal(resp.Body, &result)
    
    // 验证不包含 validator 内部细节
    assert.NotContains(t, result["msg"], "Field validation")
    assert.NotContains(t, result["msg"], "required")
}
```

---

## 提案 4：OpenAPI 文档契约对齐

**优先级**：🟡 中

### Why
确保 OpenAPI 文档描述的响应结构与真实运行时一致，避免 SDK 生成和接口对接问题。

### What Changes

#### 4.1 响应字段名对齐
```yaml
# ❌ 当前
components:
  schemas:
    ErrorResponse:
      properties:
        code: integer
        message: string  # 错误：应为 msg
        data: object
        timestamp: string

# ✅ 修复后
components:
  schemas:
    ErrorResponse:
      properties:
        code: integer
        msg: string      # 对齐真实字段名
        data: object
        timestamp: string
```

#### 4.2 成功响应体现 envelope
```yaml
# ❌ 当前（直接返回 DTO）
/api/admin/users:
  get:
    responses:
      200:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserDTO'

# ✅ 修复后（包裹 envelope）
/api/admin/users:
  get:
    responses:
      200:
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: integer
                  example: 0
                msg:
                  type: string
                  example: "success"
                data:
                  $ref: '#/components/schemas/UserDTO'
                timestamp:
                  type: string
                  format: date-time
```

#### 4.3 补齐 handlers 清单
在 `cmd/api/docs.go` 和 `cmd/gendocs/main.go` 中补充：
- `PersonalCustomer` handler
- `ShopPackageBatchAllocation` handler
- `ShopPackageBatchPricing` handler

#### 4.4 个人客户路由纳入文档
修改 `internal/routes/personal.go` 使用 `Register(...)` 并添加 RouteSpec。

### Impact
- OpenAPI 文档结构变化（需通知 SDK 使用方）
- 文档生成后需要对比差异确认

### Testing
```bash
# 1. 重新生成文档
go run cmd/gendocs/main.go

# 2. 对比差异
diff logs/openapi.yaml logs/openapi.yaml.old

# 3. 验证关键接口
# - 检查响应是否包含 envelope
# - 检查字段名是否为 msg（非 message）
# - 检查 /api/c/v1 路由是否出现
```

---

## 提案 5：代码清理和规范文档更新

**优先级**：🟢 低

### Why
清理临时代码和不一致的注释，更新项目规范文档，完善 CI 检查。

### What Changes

#### 5.1 移除任务模块占位代码
- 删除 `internal/routes/task.go`
- 删除 `internal/handler/admin/task.go`
- 更新 `internal/routes/routes.go` 移除 `registerTaskRoutes` 调用

#### 5.2 清理注释一致性
扫描 `internal/handler/**` 中残留的 `/api/v1` 注释，统一为真实路径。

#### 5.3 更新规范文档
- 更新 `openspec/specs/error-handling/spec.md` 补充"错误报错规范"
- 更新 `AGENTS.md` 增加错误处理检查清单
- 更新 `docs/003-error-handling/使用指南.md` 补充实际案例

#### 5.4 CI 检查增强
```bash
# 添加脚本检查 Service 层禁止 fmt.Errorf
#!/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 层错误处理检查通过"
```

---

## 执行顺序建议

```
提案 1 (核心业务) → 提案 2 (支持模块) → 提案 3 (Handler 层) → 提案 4 (OpenAPI) → 提案 5 (清理)
```

**原因**：
1. 优先修复核心业务错误语义（影响用户体验）
2. 完成全量 Service 层统一后再处理 Handler 层
3. OpenAPI 文档对齐可以独立进行
4. 代码清理和规范更新最后进行

---

## 每个提案的验证清单

### 编译检查
```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/[模块名]/...
```

### 集成测试
```bash
source .env.local && go test -v ./tests/integration/...
```

### 错误码验证
手动测试关键接口，确认：
- 业务错误返回 4xx（如参数错误、状态不允许）
- 系统错误返回 5xx（如数据库连接失败）
- 错误消息不泄露内部细节

---

## 预估工作量

| 提案 | 文件数 | 错误点数 | 预估时间 | 优先级 |
|-----|-------|---------|---------|-------|
| 提案 1 | 10 | 70-80 | 2-3 小时 | 高 |
| 提案 2 | 14 | 140-150 | 3-4 小时 | 中 |
| 提案 3 | 30-40 | N/A | 2-3 小时 | 中 |
| 提案 4 | 5-6 | N/A | 1-2 小时 | 中 |
| 提案 5 | 3-4 | N/A | 1 小时 | 低 |

**总计**：约 9-13 小时（分 5 次完成）

---

## 风险提示

1. **Breaking Changes**：错误码变更可能影响现有客户端
2. **测试覆盖**：每个模块需要补充错误场景测试
3. **文档同步**：OpenAPI 文档变更需通知 SDK 使用方
4. **Code Review**：每个提案需要充分的代码审查

建议每个提案完成后：
- 运行全量测试
- 在测试环境验证
- 通过 Code Review 后再合并