junhong_cmp_fiber/openspec/changes/archive/fix-global-business-consistency-emergency-fixes/NEXT_STEPS.md

后续工作建议

基于当前已完成的工作，建议将剩余任务拆分为 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

修复模式：

// ❌ 当前（泄露细节）
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

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 响应字段名对齐

# ❌ 当前
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

# ❌ 当前（直接返回 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

# 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 检查增强

# 添加脚本检查 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. 代码清理和规范更新最后进行

---

每个提案的验证清单

编译检查

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

单元测试

source .env.local && go test -v ./internal/service/[模块名]/...

集成测试

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 后再合并