feat: OpenAPI 契约对齐与框架优化

主要变更： 1. OpenAPI 文档契约对齐 - 统一错误响应字段名为 msg（非 message） - 规范 envelope 响应结构（code, msg, data, timestamp） - 个人客户路由纳入文档体系（使用 Register 机制） - 新增 BuildDocHandlers() 统一管理 handler 构造 - 确保文档生成的幂等性 2. Service 层错误处理统一 - 全面替换 fmt.Errorf 为 errors.New/Wrap - 统一错误码使用规范 - Handler 层参数校验不泄露底层细节 - 新增错误码验证集成测试 3. 代码质量提升 - 删除未使用的 Task handler 和路由 - 新增代码规范检查脚本（check-service-errors.sh） - 新增注释路径一致性检查（check-comment-paths.sh） - 更新 API 文档生成指南 4. OpenSpec 归档 - 归档 openapi-contract-alignment 变更（63 tasks） - 归档 service-error-unify-core 变更 - 归档 service-error-unify-support 变更 - 归档 code-cleanup-docs-update 变更 - 归档 handler-validation-security 变更 - 同步 delta specs 到主规范文件影响范围： - pkg/openapi: 新增 handlers.go，优化 generator.go - internal/service/*: 48 个 service 文件错误处理统一 - internal/handler/admin: 优化参数校验错误提示 - internal/routes: 个人客户路由改造，删除 task 路由 - scripts: 新增 3 个代码检查脚本 - docs: 更新 OpenAPI 文档（15750+ 行） - openspec/specs: 同步 3 个主规范文件破坏性变更：无向后兼容：是
2026-01-30 11:40:36 +08:00
parent 1290160728
commit 409a68d60b
88 changed files with 27358 additions and 990 deletions
--- a/docs/003-error-handling/使用指南.md
+++ b/docs/003-error-handling/使用指南.md
@@ -95,6 +95,17 @@ X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
 | 1008 | CodeTooManyRequests | 429 | 请求过多 | 触发限流 |
 | 1009 | CodeRequestEntityTooLarge | 413 | 请求体过大 | 文件上传超限 |

+#### 财务相关错误 (1050-1069)
+
+| 错误码 | 名称 | HTTP 状态 | 消息 | 使用场景 |
+|--------|------|-----------|------|----------|
+| 1050 | CodeInvalidStatus | 400 | 状态不允许此操作 | 资源状态不允许执行当前操作 |
+| 1051 | CodeInsufficientBalance | 400 | 余额不足 | 钱包余额不足以完成操作 |
+| 1052 | CodeWithdrawalNotFound | 404 | 提现申请不存在 | 提现记录未找到 |
+| 1053 | CodeWalletNotFound | 404 | 钱包不存在 | 钱包记录未找到 |
+| 1054 | CodeInsufficientQuota | 400 | 额度不足 | 套餐分配额度不足 |
+| 1055 | CodeExceedLimit | 400 | 超过限制 | 超过系统限制（如设备绑定卡数） |
+
 ### 服务端错误 (2000-2999)

 | 错误码 | 名称 | HTTP 状态 | 消息 | 使用场景 |
@@ -230,6 +241,137 @@ func (h *Handler) SpecialCase(c *fiber.Ctx) error {

 ---

+## Handler 层参数校验安全实践
+
+### ❌ 错误示例：泄露内部细节
+
+```go
+func (h *ShopHandler) Create(c *fiber.Ctx) error {
+    var req dto.CreateShopRequest
+    
+    // ❌ 错误：直接暴露解析错误
+    if err := c.BodyParser(&req); err != nil {
+        return errors.New(errors.CodeInvalidParam, "参数解析失败: "+err.Error())
+        // 可能泄露：json: cannot unmarshal number into Go struct field CreateShopRequest.ShopCode of type string
+    }
+    
+    // ❌ 错误：直接暴露 validator 错误
+    if err := h.validator.Struct(&req); err != nil {
+        return errors.New(errors.CodeInvalidParam, "参数验证失败: "+err.Error())
+        // 可能泄露：Key: 'CreateShopRequest.ShopName' Error:Field validation for 'ShopName' failed on the 'required' tag
+    }
+    
+    // ...
+}
+```
+
+**安全风险**：
+- 泄露内部字段名（ShopCode、ShopName）
+- 泄露数据类型（string、number）
+- 泄露验证规则（required、min、max 等）
+- 攻击者可根据错误消息推断 API 内部结构
+
+### ✅ 正确示例：安全的参数校验
+
+```go
+func (h *ShopHandler) Create(c *fiber.Ctx) error {
+    var req dto.CreateShopRequest
+    
+    // ✅ 正确：通用错误消息 + 结构化日志（WARN 级别）
+    if err := c.BodyParser(&req); err != nil {
+        logger.GetAppLogger().Warn("参数解析失败", 
+            zap.String("path", c.Path()),
+            zap.String("method", c.Method()),
+            zap.Error(err),
+        )
+        return errors.New(errors.CodeInvalidParam, "请求参数格式错误")
+    }
+    
+    // ✅ 正确：使用默认消息 + 结构化日志（WARN 级别）
+    if err := h.validator.Struct(&req); err != nil {
+        logger.GetAppLogger().Warn("参数验证失败",
+            zap.String("path", c.Path()),
+            zap.String("method", c.Method()),
+            zap.Error(err),
+        )
+        return errors.New(errors.CodeInvalidParam)  // 使用默认消息
+    }
+    
+    // 业务逻辑...
+    shop, err := h.service.Create(c.UserContext(), &req)
+    if err != nil {
+        return err
+    }
+    
+    return response.Success(c, shop)
+}
+```
+
+**安全优势**：
+- 对外：统一返回通用消息（"参数验证失败"）
+- 日志：记录详细错误信息用于排查
+- 包含 request_id：便于日志关联和问题追踪
+
+### 单元测试示例
+
+```go
+func TestShopHandler_Create_ParamValidation(t *testing.T) {
+    // 准备测试环境
+    app := fiber.New()
+    handler := NewShopHandler(mockService, mockValidator, logger)
+    app.Post("/shops", handler.Create)
+    
+    tests := []struct {
+        name           string
+        requestBody    string
+        expectedCode   int
+        expectedMsg    string
+    }{
+        {
+            name:        "参数解析失败",
+            requestBody: `{"shop_code": 123}`, // 类型错误
+            expectedCode: errors.CodeInvalidParam,
+            expectedMsg:  "请求参数格式错误",
+        },
+        {
+            name:        "必填字段缺失",
+            requestBody: `{"shop_code": ""}`, // ShopName 缺失
+            expectedCode: errors.CodeInvalidParam,
+            expectedMsg:  "参数验证失败",
+        },
+        {
+            name:        "正常请求",
+            requestBody: `{"shop_code": "SH001", "shop_name": "测试店铺"}`,
+            expectedCode: errors.CodeSuccess,
+            expectedMsg:  "操作成功",
+        },
+    }
+    
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            req := httptest.NewRequest("POST", "/shops", strings.NewReader(tt.requestBody))
+            req.Header.Set("Content-Type", "application/json")
+            
+            resp, _ := app.Test(req)
+            defer resp.Body.Close()
+            
+            var result map[string]interface{}
+            json.NewDecoder(resp.Body).Decode(&result)
+            
+            assert.Equal(t, tt.expectedCode, int(result["code"].(float64)))
+            assert.Equal(t, tt.expectedMsg, result["msg"])
+            
+            // ✅ 验证：错误消息不泄露内部细节
+            assert.NotContains(t, result["msg"], "ShopCode")
+            assert.NotContains(t, result["msg"], "ShopName")
+            assert.NotContains(t, result["msg"], "required")
+        })
+    }
+}
+```
+
+---
+
 ## 客户端错误处理

 ### JavaScript/TypeScript
@@ -412,14 +554,60 @@ return errors.New(errors.CodeDatabaseError, "用户名不能为空") // 应该
 return errors.New(errors.CodeNotFound, "") // 应该提供具体消息
 ```

-### 2. 错误消息编写
+### 2. 参数校验安全加固（重要）

 ✅ **正确示例**：
 ```go
-// 清晰、具体的错误消息
+// 参数解析失败
+if err := c.BodyParser(&req); err != nil {
+    logger.GetAppLogger().Warn("参数解析失败",
+        zap.String("path", c.Path()),
+        zap.String("method", c.Method()),
+        zap.Error(err),
+    )
+    return errors.New(errors.CodeInvalidParam, "请求参数格式错误")
+}
+
+// 参数验证失败
+if err := h.validator.Struct(&req); err != nil {
+    logger.GetAppLogger().Warn("参数验证失败",
+        zap.String("path", c.Path()),
+        zap.String("method", c.Method()),
+        zap.Error(err),
+    )
+    return errors.New(errors.CodeInvalidParam)  // 使用默认消息
+}
+```
+
+❌ **错误示例 - 泄露内部细节**：
+```go
+// ❌ 危险：泄露 validator 规则和字段名
+if err := h.validator.Struct(&req); err != nil {
+    return errors.New(errors.CodeInvalidParam, "参数验证失败: "+err.Error())
+}
+// 可能返回："Field validation for 'Username' failed on the 'required' tag"
+
+// ❌ 危险：泄露类型信息
+if err := c.BodyParser(&req); err != nil {
+    return errors.New(errors.CodeInvalidParam, "参数解析失败: "+err.Error())
+}
+// 可能返回："Unmarshal type error: expected=uint got=string field=shop_id"
+```
+
+**安全原则**：
+- 对外统一返回通用消息（"参数验证失败"）
+- 详细错误信息仅记录到日志
+- 使用 WARN 级别（客户端错误）
+- 必须包含请求上下文（path、method）
+
+### 3. 错误消息编写
+
+✅ **正确示例**：
+```go
+// 清晰、具体的错误消息（不泄露内部细节）
 errors.New(errors.CodeInvalidParam, "用户名长度必须在 3-20 个字符之间")
-errors.New(errors.CodeNotFound, "用户 ID 123 不存在")
-errors.New(errors.CodeConflict, "邮箱 test@example.com 已被注册")
+errors.New(errors.CodeNotFound, "用户不存在")
+errors.New(errors.CodeConflict, "邮箱已被注册")
 ```

 ❌ **错误示例**：
@@ -428,8 +616,9 @@ errors.New(errors.CodeConflict, "邮箱 test@example.com 已被注册")
 errors.New(errors.CodeInvalidParam, "错误")
 errors.New(errors.CodeNotFound, "not found")

-// 不要暴露敏感信息
+// 不要暴露敏感信息和内部细节
 errors.New(errors.CodeDatabaseError, "SQL error: SELECT * FROM users WHERE password = '...'")
+errors.New(errors.CodeInvalidParam, "Field 'Username' validation failed") // 泄露字段名
 ```

 ### 3. 错误包装
@@ -558,5 +747,140 @@ A: 堆栈跟踪仅在 panic 时记录，无法关闭。如需调整，修改 `in

 ---

+## Service 层错误处理实战案例
+
+### 案例 1：套餐服务 - 资源查询
+
+**场景**：获取套餐详情，需处理不存在和数据库错误
+
+```go
+// internal/service/package/service.go
+func (s *Service) Get(ctx context.Context, id uint) (*dto.PackageResponse, error) {
+    pkg, err := s.packageStore.GetByID(ctx, id)
+    if err != nil {
+        // ✅ 业务错误：资源不存在
+        if err == gorm.ErrRecordNotFound {
+            return nil, errors.New(errors.CodeNotFound, "套餐不存在")
+        }
+        // ✅ 系统错误：数据库查询失败
+        return nil, errors.Wrap(errors.CodeInternalError, err, "获取套餐失败")
+    }
+    
+    return s.toResponse(ctx, pkg), nil
+}
+```
+
+**错误返回示例**：
+- 套餐不存在（404）：
+  ```json
+  {"code": 1006, "msg": "套餐不存在", "data": null}
+  ```
+- 数据库错误（500）：
+  ```json
+  {"code": 2001, "msg": "内部服务器错误", "data": null}
+  ```
+  日志中记录详细错误：`获取套餐失败: connection refused`
+
+### 案例 2：分佣提现 - 复杂业务校验
+
+**场景**：提现审核，需验证余额、状态等
+
+```go
+// internal/service/commission_withdrawal/service.go
+func (s *Service) Approve(ctx context.Context, id uint, req *dto.ApproveWithdrawalReq) (*dto.WithdrawalApprovalResp, error) {
+    // ✅ 业务错误：资源不存在
+    withdrawal, err := s.commissionWithdrawalReqStore.GetByID(ctx, id)
+    if err != nil {
+        return nil, errors.New(errors.CodeNotFound, "提现申请不存在")
+    }
+    
+    // ✅ 业务错误：状态不允许
+    if withdrawal.Status != constants.WithdrawalStatusPending {
+        return nil, errors.New(errors.CodeInvalidStatus, "申请状态不允许此操作")
+    }
+    
+    // ✅ 业务错误：余额不足
+    wallet, err := s.walletStore.GetShopCommissionWallet(ctx, withdrawal.ShopID)
+    if err != nil {
+        return nil, errors.New(errors.CodeNotFound, "店铺佣金钱包不存在")
+    }
+    if wallet.FrozenBalance < amount {
+        return nil, errors.New(errors.CodeInsufficientBalance, "钱包冻结余额不足")
+    }
+    
+    // ✅ 系统错误：事务执行失败
+    err = s.db.Transaction(func(tx *gorm.DB) error {
+        if err := s.walletStore.DeductFrozenBalanceWithTx(ctx, tx, wallet.ID, amount); err != nil {
+            return errors.Wrap(errors.CodeInternalError, err, "扣除冻结余额失败")
+        }
+        // ...其他事务操作
+        return nil
+    })
+    
+    if err != nil {
+        return nil, err
+    }
+    
+    return &dto.WithdrawalApprovalResp{...}, nil
+}
+```
+
+### 案例 3：店铺管理 - 重复性检查
+
+**场景**：创建店铺，需检查代码重复和层级限制
+
+```go
+// internal/service/shop/service.go
+func (s *Service) Create(ctx context.Context, req *dto.CreateShopRequest) (*dto.ShopResponse, error) {
+    // ✅ 业务错误：重复检查
+    existing, _ := s.shopStore.GetByCode(ctx, req.ShopCode)
+    if existing != nil {
+        return nil, errors.New(errors.CodeDuplicate, "店铺代码已存在")
+    }
+    
+    // ✅ 业务错误：层级限制
+    level := 1
+    if req.ParentID != nil {
+        parent, err := s.shopStore.GetByID(ctx, *req.ParentID)
+        if err != nil {
+            return nil, errors.New(errors.CodeNotFound, "上级店铺不存在")
+        }
+        level = parent.Level + 1
+        if level > 7 {
+            return nil, errors.New(errors.CodeInvalidParam, "店铺层级超过限制")
+        }
+    }
+    
+    // ✅ 系统错误：数据库操作
+    shop := &model.Shop{...}
+    if err := s.shopStore.Create(ctx, shop); err != nil {
+        return nil, errors.Wrap(errors.CodeInternalError, err, "创建店铺失败")
+    }
+    
+    return s.toResponse(shop), nil
+}
+```
+
+### 错误处理原则总结
+
+| 场景类型 | 使用方式 | HTTP 状态码 | 示例 |
+|---------|---------|-----------|------|
+| 资源不存在 | `errors.New(CodeNotFound)` | 404 | 套餐、店铺、用户不存在 |
+| 状态不允许 | `errors.New(CodeInvalidStatus)` | 400 | 订单已取消、提现已审核 |
+| 参数错误 | `errors.New(CodeInvalidParam)` | 400 | 层级超限、金额无效 |
+| 重复操作 | `errors.New(CodeDuplicate)` | 409 | 代码重复、用户名已存在 |
+| 余额不足 | `errors.New(CodeInsufficientBalance)` | 400 | 钱包余额不足 |
+| 数据库错误 | `errors.Wrap(CodeInternalError, err)` | 500 | 查询失败、创建失败 |
+| 队列错误 | `errors.Wrap(CodeInternalError, err)` | 500 | 任务提交失败 |
+
+**核心原则**：
+1. 业务错误（4xx）：使用 `errors.New(Code4xx, msg)`
+2. 系统错误（5xx）：使用 `errors.Wrap(Code5xx, err, msg)`
+3. 错误消息保持中文，便于日志排查
+4. 禁止 `fmt.Errorf` 直接对外返回，避免泄露内部细节
+
+---
+
 **版本历史**:
+- v1.1.0 (2026-01-29): 补充 Service 层错误处理实战案例
 - v1.0.0 (2025-11-15): 初始版本