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 个主规范文件

破坏性变更：无
向后兼容：是

pkg/errors/codes.go

@@ -58,6 +58,8 @@ const (
 	CodeInsufficientBalance = 1051 // 余额不足
 	CodeWithdrawalNotFound  = 1052 // 提现申请不存在
 	CodeWalletNotFound      = 1053 // 钱包不存在
+	CodeInsufficientQuota   = 1054 // 额度不足
+	CodeExceedLimit         = 1055 // 超过限制
 
 	// IoT 卡相关错误 (1070-1089)
 	CodeIotCardNotFound                   = 1070 // IoT 卡不存在
@@ -145,6 +147,8 @@ var allErrorCodes = []int{
 	CodeInsufficientBalance,
 	CodeWithdrawalNotFound,
 	CodeWalletNotFound,
+	CodeInsufficientQuota,
+	CodeExceedLimit,
 	CodeIotCardNotFound,
 	CodeIotCardBoundToDevice,
 	CodeIotCardStatusNotAllowed,
@@ -227,6 +231,8 @@ var errorMessages = map[int]string{
 	CodeInsufficientBalance:               "余额不足",
 	CodeWithdrawalNotFound:                "提现申请不存在",
 	CodeWalletNotFound:                    "钱包不存在",
+	CodeInsufficientQuota:                 "额度不足",
+	CodeExceedLimit:                       "超过限制",
 	CodeIotCardNotFound:                   "IoT 卡不存在",
 	CodeIotCardBoundToDevice:              "IoT 卡已绑定设备，不能单独操作",
 	CodeIotCardStatusNotAllowed:           "卡状态不允许此操作",
@@ -290,7 +296,15 @@ func GetHTTPStatus(code int) int {
 		return 403 // Forbidden
 	case CodeNotFound:
 		return 404 // Not Found
-	case CodeConflict:
+	case CodeConflict,
+		CodeUsernameExists,
+		CodePhoneExists,
+		CodeRoleNameExists,
+		CodePermCodeExists,
+		CodeShopCodeExists,
+		CodeEnterpriseCodeExists,
+		CodeCustomerPhoneExists,
+		CodeCarrierCodeExists:
 		return 409 // Conflict
 	case CodeTooManyRequests:
 		return 429 // Too Many Requests

pkg/openapi/generator.go

@@ -57,6 +57,9 @@ func (g *Generator) addErrorResponseSchema() {
 	stringType := openapi3.SchemaType("string")
 	dateTimeFormat := "date-time"
 
+	var errorExample interface{} = "参数验证失败"
+	var codeExample interface{} = 1001
+
 	errorSchema := openapi3.SchemaOrRef{
 		Schema: &openapi3.Schema{
 			Type: &objectType,
@@ -65,12 +68,20 @@ func (g *Generator) addErrorResponseSchema() {
 					Schema: &openapi3.Schema{
 						Type:        &integerType,
 						Description: ptrString("错误码"),
+						Example:     &codeExample,
 					},
 				},
-				"message": {
+				"msg": {
 					Schema: &openapi3.Schema{
 						Type:        &stringType,
 						Description: ptrString("错误消息"),
+						Example:     &errorExample,
+					},
+				},
+				"data": {
+					Schema: &openapi3.Schema{
+						Type:        &objectType,
+						Description: ptrString("错误详情（可选）"),
 					},
 				},
 				"timestamp": {
@@ -81,7 +92,7 @@ func (g *Generator) addErrorResponseSchema() {
 					},
 				},
 			},
-			Required: []string{"code", "message", "timestamp"},
+			Required: []string{"code", "msg", "timestamp"},
 		},
 	}
 
@@ -129,9 +140,8 @@ func (g *Generator) AddOperation(method, path, summary, description string, inpu
 
 	// 反射输出 (响应 Body)
 	if output != nil {
-		if err := g.Reflector.SetJSONResponse(&op, output, 200); err != nil {
-			panic(err)
-		}
+		// 将输出包裹在 envelope 中
+		g.setEnvelopeResponse(&op, output, 200)
 	}
 
 	// 添加认证要求
@@ -225,9 +235,8 @@ func (g *Generator) AddMultipartOperation(method, path, summary, description str
 	}
 
 	if output != nil {
-		if err := g.Reflector.SetJSONResponse(&op, output, 200); err != nil {
-			panic(err)
-		}
+		// 将输出包裹在 envelope 中
+		g.setEnvelopeResponse(&op, output, 200)
 	}
 
 	if requiresAuth {
@@ -308,6 +317,75 @@ func parseFormFields(input interface{}) []formFieldInfo {
 	return fields
 }
 
+// setEnvelopeResponse 设置包裹在 envelope 中的响应
+func (g *Generator) setEnvelopeResponse(op *openapi3.Operation, output interface{}, statusCode int) {
+	// 首先调用 SetJSONResponse 让 Reflector 处理 DTO schema
+	tempOp := openapi3.Operation{}
+	if err := g.Reflector.SetJSONResponse(&tempOp, output, statusCode); err != nil {
+		panic(err)
+	}
+
+	// 获取生成的 DTO schema
+	dtoSchemaOrRef := tempOp.Responses.MapOfResponseOrRefValues[strconv.Itoa(statusCode)].Response.Content["application/json"].Schema
+
+	objectType := openapi3.SchemaType("object")
+	integerType := openapi3.SchemaType("integer")
+	stringType := openapi3.SchemaType("string")
+	dateTimeFormat := "date-time"
+
+	var successCodeExample interface{} = 0
+	var successMsgExample interface{} = "success"
+
+	// 构造 envelope schema
+	envelopeSchema := &openapi3.SchemaOrRef{
+		Schema: &openapi3.Schema{
+			Type: &objectType,
+			Properties: map[string]openapi3.SchemaOrRef{
+				"code": {
+					Schema: &openapi3.Schema{
+						Type:        &integerType,
+						Description: ptrString("响应码"),
+						Example:     &successCodeExample,
+					},
+				},
+				"msg": {
+					Schema: &openapi3.Schema{
+						Type:        &stringType,
+						Description: ptrString("响应消息"),
+						Example:     &successMsgExample,
+					},
+				},
+				"data": *dtoSchemaOrRef,
+				"timestamp": {
+					Schema: &openapi3.Schema{
+						Type:        &stringType,
+						Format:      &dateTimeFormat,
+						Description: ptrString("时间戳"),
+					},
+				},
+			},
+			Required: []string{"code", "msg", "data", "timestamp"},
+		},
+	}
+
+	// 设置响应
+	statusStr := strconv.Itoa(statusCode)
+	description := "成功"
+	if op.Responses.MapOfResponseOrRefValues == nil {
+		op.Responses.MapOfResponseOrRefValues = make(map[string]openapi3.ResponseOrRef)
+	}
+	op.Responses.MapOfResponseOrRefValues[statusStr] = openapi3.ResponseOrRef{
+		Response: &openapi3.Response{
+			Description: description,
+			Content: map[string]openapi3.MediaType{
+				"application/json": {
+					Schema: envelopeSchema,
+				},
+			},
+		},
+	}
+}
+
 // addSecurityRequirement 为操作添加认证要求
 func (g *Generator) addSecurityRequirement(op *openapi3.Operation) {
 	op.Security = []map[string][]string{

pkg/openapi/handlers.go

@@ -0,0 +1,49 @@
+package openapi
+
+import (
+	"github.com/break/junhong_cmp_fiber/internal/bootstrap"
+	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
+	"github.com/break/junhong_cmp_fiber/internal/handler/app"
+	"github.com/break/junhong_cmp_fiber/internal/handler/callback"
+	"github.com/break/junhong_cmp_fiber/internal/handler/h5"
+)
+
+// BuildDocHandlers 构造文档生成用的 handlers（所有依赖传 nil）
+func BuildDocHandlers() *bootstrap.Handlers {
+	return &bootstrap.Handlers{
+		AdminAuth:                   admin.NewAuthHandler(nil, nil),
+		H5Auth:                      h5.NewAuthHandler(nil, nil),
+		Account:                     admin.NewAccountHandler(nil),
+		Role:                        admin.NewRoleHandler(nil, nil),
+		Permission:                  admin.NewPermissionHandler(nil),
+		PersonalCustomer:            app.NewPersonalCustomerHandler(nil, nil),
+		Shop:                        admin.NewShopHandler(nil),
+		ShopAccount:                 admin.NewShopAccountHandler(nil),
+		ShopCommission:              admin.NewShopCommissionHandler(nil),
+		CommissionWithdrawal:        admin.NewCommissionWithdrawalHandler(nil),
+		CommissionWithdrawalSetting: admin.NewCommissionWithdrawalSettingHandler(nil),
+		Enterprise:                  admin.NewEnterpriseHandler(nil),
+		EnterpriseCard:              admin.NewEnterpriseCardHandler(nil),
+		EnterpriseDevice:            admin.NewEnterpriseDeviceHandler(nil),
+		EnterpriseDeviceH5:          h5.NewEnterpriseDeviceHandler(nil),
+		Authorization:               admin.NewAuthorizationHandler(nil),
+		CustomerAccount:             admin.NewCustomerAccountHandler(nil),
+		MyCommission:                admin.NewMyCommissionHandler(nil),
+		IotCard:                     admin.NewIotCardHandler(nil),
+		IotCardImport:               admin.NewIotCardImportHandler(nil),
+		Device:                      admin.NewDeviceHandler(nil),
+		DeviceImport:                admin.NewDeviceImportHandler(nil),
+		AssetAllocationRecord:       admin.NewAssetAllocationRecordHandler(nil),
+		Storage:                     admin.NewStorageHandler(nil),
+		Carrier:                     admin.NewCarrierHandler(nil),
+		PackageSeries:               admin.NewPackageSeriesHandler(nil),
+		Package:                     admin.NewPackageHandler(nil),
+		ShopSeriesAllocation:        admin.NewShopSeriesAllocationHandler(nil),
+		ShopPackageAllocation:       admin.NewShopPackageAllocationHandler(nil),
+		ShopPackageBatchAllocation:  admin.NewShopPackageBatchAllocationHandler(nil),
+		ShopPackageBatchPricing:     admin.NewShopPackageBatchPricingHandler(nil),
+		AdminOrder:                  admin.NewOrderHandler(nil),
+		H5Order:                     h5.NewOrderHandler(nil),
+		PaymentCallback:             callback.NewPaymentHandler(nil),
+	}
+}