支持客户按套餐类型缩小可购范围

Constraint: 查询参数可选且仅接受 formal 或 addon
Rejected: 新增专用 Store 方法 | 现有 PackageStore.List 已支持 package_type 过滤
Confidence: high
Scope-risk: narrow
Directive: 套餐类型取值继续与 pkg/constants 保持一致
Tested: go run cmd/gendocs/main.go，确认 OpenAPI 生成 package_type 查询参数
Not-tested: 按用户要求未执行自动化测试

docs/admin-openapi.yaml

@@ -29405,6 +29405,13 @@ paths:
                     maxLength: 50
                     minLength: 1
                     type: string
+                - description: 套餐类型 (formal:正式套餐, addon:附加套餐)
+                  in: query
+                  name: package_type
+                  schema:
+                    description: 套餐类型 (formal:正式套餐, addon:附加套餐)
+                    nullable: true
+                    type: string
             responses:
                 "200":
                     content:

internal/handler/app/client_asset.go

@@ -22,11 +22,14 @@ import (
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 	pkgMiddleware "github.com/break/junhong_cmp_fiber/pkg/middleware"
 	"github.com/break/junhong_cmp_fiber/pkg/response"
+	"github.com/go-playground/validator/v10"
 	"github.com/gofiber/fiber/v2"
 	"go.uber.org/zap"
 	"gorm.io/gorm"
 )
 
+var clientAssetValidator = validator.New()
+
 // ClientAssetHandler C 端资产信息处理器
 // 提供 B1~B4 资产信息、可购套餐、套餐历史、手动刷新接口
 type ClientAssetHandler struct {
@@ -342,6 +345,9 @@ func (h *ClientAssetHandler) GetAvailablePackages(c *fiber.Ctx) error {
 	if err := c.QueryParser(&req); err != nil {
 		return errors.New(errors.CodeInvalidParam)
 	}
+	if err := clientAssetValidator.Struct(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
 
 	resolved, err := h.resolveAssetFromIdentifier(c, req.Identifier)
 	if err != nil {
@@ -369,15 +375,20 @@ func (h *ClientAssetHandler) GetAvailablePackages(c *fiber.Ctx) error {
 		listCtx = context.WithValue(listCtx, constants.ContextKeyShopID, resolved.SellerShopID)
 	}
 
+	filters := map[string]any{
+		"series_id":    *resolved.Asset.SeriesID,
+		"status":       constants.StatusEnabled,
+		"shelf_status": constants.ShelfStatusOn,
+	}
+	if req.PackageType != nil {
+		filters["package_type"] = *req.PackageType
+	}
+
 	pkgs, _, err := h.packageStore.List(listCtx, &store.QueryOptions{
 		Page:     1,
 		PageSize: constants.MaxPageSize,
 		OrderBy:  "id DESC",
-	}, map[string]any{
-		"series_id":    *resolved.Asset.SeriesID,
-		"status":       constants.StatusEnabled,
-		"shelf_status": constants.ShelfStatusOn,
-	})
+	}, filters)
 	if err != nil {
 		return errors.Wrap(errors.CodeDatabaseError, err, "查询可购套餐失败")
 	}

internal/model/dto/client_asset_dto.go

@@ -146,7 +146,8 @@ type DeviceRealtimeInfo struct {
 
 // AssetPackageListRequest B2 资产可购套餐列表请求
 type AssetPackageListRequest struct {
-	Identifier string `json:"identifier" query:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+	Identifier  string  `json:"identifier" query:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+	PackageType *string `json:"package_type" query:"package_type" validate:"omitempty,oneof=formal addon" description:"套餐类型 (formal:正式套餐, addon:附加套餐)"`
 }
 
 // ClientPackageItem B2 客户端套餐项