feat: 新增代理分配套餐上架状态（shelf_status）功能
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m56s
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m56s
- 新增数据库迁移：为 shop_package_allocation 表添加 shelf_status 字段 - 更新模型/DTO：ShopPackageAllocation 增加 ShelfStatus 字段及相关枚举 - 更新套餐分配 Service：支持上架/下架状态管理逻辑 - 更新套餐 Store/Service：根据 shelf_status 过滤可售套餐 - 更新购买验证 Service：引入上架状态校验逻辑 - 归档 OpenSpec 变更：2026-03-02-agent-allocation-shelf-status - 同步更新主规范文档：allocation-shelf-status、package-management、purchase-validation Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -82,7 +82,7 @@ type services struct {
|
||||
}
|
||||
|
||||
func initServices(s *stores, deps *Dependencies) *services {
|
||||
purchaseValidation := purchaseValidationSvc.New(deps.DB, s.IotCard, s.Device, s.Package)
|
||||
purchaseValidation := purchaseValidationSvc.New(deps.DB, s.IotCard, s.Device, s.Package, s.ShopPackageAllocation)
|
||||
accountAudit := accountAuditSvc.NewService(s.AccountOperationLog)
|
||||
account := accountSvc.New(s.Account, s.Role, s.AccountRole, s.ShopRole, s.Shop, s.Enterprise, accountAudit)
|
||||
|
||||
|
||||
@@ -39,6 +39,7 @@ type ShopPackageAllocationResponse struct {
|
||||
AllocatorShopName string `json:"allocator_shop_name" description:"分配者店铺名称"`
|
||||
CostPrice int64 `json:"cost_price" description:"该代理的成本价（分）"`
|
||||
Status int `json:"status" description:"状态 (1:启用, 2:禁用)"`
|
||||
ShelfStatus int `json:"shelf_status" description:"上架状态 (1:上架, 2:下架)"`
|
||||
CreatedAt string `json:"created_at" description:"创建时间"`
|
||||
UpdatedAt string `json:"updated_at" description:"更新时间"`
|
||||
}
|
||||
|
||||
@@ -13,6 +13,7 @@ type ShopPackageAllocation struct {
|
||||
CostPrice int64 `gorm:"column:cost_price;type:bigint;not null;comment:该代理的成本价（分）" json:"cost_price"`
|
||||
SeriesAllocationID *uint `gorm:"column:series_allocation_id;index;comment:关联的系列分配ID" json:"series_allocation_id"`
|
||||
Status int `gorm:"column:status;type:int;default:1;not null;comment:状态 1-启用 2-禁用" json:"status"`
|
||||
ShelfStatus int `gorm:"column:shelf_status;type:int;default:1;not null;comment:上架状态 1-上架 2-下架" json:"shelf_status"`
|
||||
}
|
||||
|
||||
// TableName 指定表名
|
||||
|
||||
@@ -425,6 +425,14 @@ func (s *Service) UpdateShelfStatus(ctx context.Context, id uint, shelfStatus in
|
||||
return errors.New(errors.CodeUnauthorized, "未授权访问")
|
||||
}
|
||||
|
||||
userType := middleware.GetUserTypeFromContext(ctx)
|
||||
|
||||
// 代理用户：修改自己分配记录的 shelf_status，不影响平台全局套餐状态
|
||||
if userType == constants.UserTypeAgent {
|
||||
return s.updateAgentShelfStatus(ctx, id, shelfStatus, currentUserID)
|
||||
}
|
||||
|
||||
// 平台/超管：修改套餐全局 shelf_status
|
||||
pkg, err := s.packageStore.GetByID(ctx, id)
|
||||
if err != nil {
|
||||
if err == gorm.ErrRecordNotFound {
|
||||
@@ -433,7 +441,7 @@ func (s *Service) UpdateShelfStatus(ctx context.Context, id uint, shelfStatus in
|
||||
return errors.Wrap(errors.CodeInternalError, err, "获取套餐失败")
|
||||
}
|
||||
|
||||
if shelfStatus == 1 && pkg.Status == constants.StatusDisabled {
|
||||
if shelfStatus == constants.ShelfStatusOn && pkg.Status == constants.StatusDisabled {
|
||||
return errors.New(errors.CodeInvalidStatus, "禁用的套餐不能上架，请先启用")
|
||||
}
|
||||
|
||||
@@ -447,6 +455,43 @@ func (s *Service) UpdateShelfStatus(ctx context.Context, id uint, shelfStatus in
|
||||
return nil
|
||||
}
|
||||
|
||||
// updateAgentShelfStatus 代理上下架路径：更新分配记录的 shelf_status
|
||||
func (s *Service) updateAgentShelfStatus(ctx context.Context, packageID uint, shelfStatus int, updaterID uint) error {
|
||||
shopID := middleware.GetShopIDFromContext(ctx)
|
||||
if shopID == 0 {
|
||||
return errors.New(errors.CodeUnauthorized, "当前用户不属于任何店铺")
|
||||
}
|
||||
|
||||
// 查找代理对该套餐的分配记录
|
||||
allocation, err := s.packageAllocationStore.GetByShopAndPackage(ctx, shopID, packageID)
|
||||
if err != nil {
|
||||
if err == gorm.ErrRecordNotFound {
|
||||
return errors.New(errors.CodeNotFound, "该套餐未分配给您，无法操作上下架")
|
||||
}
|
||||
return errors.Wrap(errors.CodeInternalError, err, "获取分配记录失败")
|
||||
}
|
||||
|
||||
// 上架时检查套餐全局禁用状态
|
||||
if shelfStatus == constants.ShelfStatusOn {
|
||||
pkg, err := s.packageStore.GetByID(ctx, packageID)
|
||||
if err != nil {
|
||||
if err == gorm.ErrRecordNotFound {
|
||||
return errors.New(errors.CodeNotFound, "套餐不存在")
|
||||
}
|
||||
return errors.Wrap(errors.CodeInternalError, err, "获取套餐失败")
|
||||
}
|
||||
if pkg.Status == constants.StatusDisabled {
|
||||
return errors.New(errors.CodeInvalidStatus, "套餐已禁用，无法上架")
|
||||
}
|
||||
}
|
||||
|
||||
if err := s.packageAllocationStore.UpdateShelfStatus(ctx, allocation.ID, shelfStatus, updaterID); err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "更新上下架状态失败")
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
func (s *Service) toResponse(ctx context.Context, pkg *model.Package) *dto.PackageResponse {
|
||||
var seriesID *uint
|
||||
if pkg.SeriesID > 0 {
|
||||
@@ -488,6 +533,8 @@ func (s *Service) toResponse(ctx context.Context, pkg *model.Package) *dto.Packa
|
||||
resp.CostPrice = allocation.CostPrice
|
||||
profitMargin := pkg.SuggestedRetailPrice - allocation.CostPrice
|
||||
resp.ProfitMargin = &profitMargin
|
||||
// 代理查询时，shelf_status 返回自己分配记录的值，而非平台全局值
|
||||
resp.ShelfStatus = allocation.ShelfStatus
|
||||
}
|
||||
}
|
||||
|
||||
@@ -547,6 +594,8 @@ func (s *Service) toResponseWithAllocation(_ context.Context, pkg *model.Package
|
||||
resp.CostPrice = allocation.CostPrice
|
||||
profitMargin := pkg.SuggestedRetailPrice - allocation.CostPrice
|
||||
resp.ProfitMargin = &profitMargin
|
||||
// 代理查询时，shelf_status 返回自己分配记录的值，而非平台全局值
|
||||
resp.ShelfStatus = allocation.ShelfStatus
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -15,6 +15,7 @@ type Service struct {
|
||||
iotCardStore *postgres.IotCardStore
|
||||
deviceStore *postgres.DeviceStore
|
||||
packageStore *postgres.PackageStore
|
||||
packageAllocationStore *postgres.ShopPackageAllocationStore
|
||||
}
|
||||
|
||||
func New(
|
||||
@@ -22,12 +23,14 @@ func New(
|
||||
iotCardStore *postgres.IotCardStore,
|
||||
deviceStore *postgres.DeviceStore,
|
||||
packageStore *postgres.PackageStore,
|
||||
packageAllocationStore *postgres.ShopPackageAllocationStore,
|
||||
) *Service {
|
||||
return &Service{
|
||||
db: db,
|
||||
iotCardStore: iotCardStore,
|
||||
deviceStore: deviceStore,
|
||||
packageStore: packageStore,
|
||||
packageAllocationStore: packageAllocationStore,
|
||||
}
|
||||
}
|
||||
|
||||
@@ -51,7 +54,13 @@ func (s *Service) ValidateCardPurchase(ctx context.Context, cardID uint, package
|
||||
return nil, errors.New(errors.CodeInvalidParam, "该卡未关联套餐系列，无法购买套餐")
|
||||
}
|
||||
|
||||
packages, totalPrice, err := s.validatePackages(ctx, packageIDs, *card.SeriesID)
|
||||
// 确定卖家店铺ID：卡所属店铺即为卖家（代理渠道），平台自营时为0
|
||||
var sellerShopID uint
|
||||
if card.ShopID != nil {
|
||||
sellerShopID = *card.ShopID
|
||||
}
|
||||
|
||||
packages, totalPrice, err := s.validatePackages(ctx, packageIDs, *card.SeriesID, sellerShopID)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
@@ -76,7 +85,13 @@ func (s *Service) ValidateDevicePurchase(ctx context.Context, deviceID uint, pac
|
||||
return nil, errors.New(errors.CodeInvalidParam, "该设备未关联套餐系列，无法购买套餐")
|
||||
}
|
||||
|
||||
packages, totalPrice, err := s.validatePackages(ctx, packageIDs, *device.SeriesID)
|
||||
// 确定卖家店铺ID：设备所属店铺即为卖家（代理渠道），平台自营时为0
|
||||
var sellerShopID uint
|
||||
if device.ShopID != nil {
|
||||
sellerShopID = *device.ShopID
|
||||
}
|
||||
|
||||
packages, totalPrice, err := s.validatePackages(ctx, packageIDs, *device.SeriesID, sellerShopID)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
@@ -88,7 +103,10 @@ func (s *Service) ValidateDevicePurchase(ctx context.Context, deviceID uint, pac
|
||||
}, nil
|
||||
}
|
||||
|
||||
func (s *Service) validatePackages(ctx context.Context, packageIDs []uint, seriesID uint) ([]*model.Package, int64, error) {
|
||||
// validatePackages 验证套餐列表是否可购买
|
||||
// sellerShopID > 0 表示代理渠道，校验该代理的 allocation.shelf_status；
|
||||
// sellerShopID == 0 表示平台自营渠道，校验 package.shelf_status
|
||||
func (s *Service) validatePackages(ctx context.Context, packageIDs []uint, seriesID uint, sellerShopID uint) ([]*model.Package, int64, error) {
|
||||
if len(packageIDs) == 0 {
|
||||
return nil, 0, errors.New(errors.CodeInvalidParam, "请选择至少一个套餐")
|
||||
}
|
||||
@@ -109,13 +127,22 @@ func (s *Service) validatePackages(ctx context.Context, packageIDs []uint, serie
|
||||
return nil, 0, errors.New(errors.CodeInvalidParam, "套餐不在可购买范围内")
|
||||
}
|
||||
|
||||
// Package.status 为全局开关，任何渠道都必须检查
|
||||
if pkg.Status != constants.StatusEnabled {
|
||||
return nil, 0, errors.New(errors.CodeInvalidParam, "套餐已禁用")
|
||||
}
|
||||
|
||||
if sellerShopID > 0 {
|
||||
// 代理渠道：检查卖家代理的 allocation.shelf_status，不检查 package.shelf_status
|
||||
if err := s.validateAgentShelfStatus(ctx, sellerShopID, pkgID); err != nil {
|
||||
return nil, 0, err
|
||||
}
|
||||
} else {
|
||||
// 平台自营渠道：检查 package.shelf_status
|
||||
if pkg.ShelfStatus != constants.ShelfStatusOn {
|
||||
return nil, 0, errors.New(errors.CodeInvalidParam, "套餐已下架")
|
||||
}
|
||||
}
|
||||
|
||||
packages = append(packages, pkg)
|
||||
totalPrice += pkg.SuggestedRetailPrice
|
||||
@@ -124,6 +151,25 @@ func (s *Service) validatePackages(ctx context.Context, packageIDs []uint, serie
|
||||
return packages, totalPrice, nil
|
||||
}
|
||||
|
||||
// validateAgentShelfStatus 校验卖家代理的分配记录上架状态
|
||||
func (s *Service) validateAgentShelfStatus(ctx context.Context, sellerShopID, packageID uint) error {
|
||||
// 使用不带数据权限过滤的查询，避免 buyer ctx 的权限限制干扰系统级校验
|
||||
allocation, err := s.packageAllocationStore.GetByShopAndPackageForSystem(ctx, sellerShopID, packageID)
|
||||
if err != nil {
|
||||
if err == gorm.ErrRecordNotFound {
|
||||
return errors.New(errors.CodeInvalidParam, "套餐已下架")
|
||||
}
|
||||
return errors.Wrap(errors.CodeInternalError, err, "查询套餐分配记录失败")
|
||||
}
|
||||
|
||||
if allocation.ShelfStatus != constants.ShelfStatusOn {
|
||||
return errors.New(errors.CodeInvalidParam, "套餐已下架")
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
func (s *Service) GetPurchasePrice(ctx context.Context, pkg *model.Package, buyerType string) int64 {
|
||||
return pkg.SuggestedRetailPrice
|
||||
}
|
||||
|
||||
|
||||
@@ -252,7 +252,9 @@ func (s *Service) UpdateStatus(ctx context.Context, id uint, status int) error {
|
||||
return errors.New(errors.CodeUnauthorized, "未授权访问")
|
||||
}
|
||||
|
||||
_, err := s.packageAllocationStore.GetByID(ctx, id)
|
||||
// 任务 3.2：所有者校验 —— 代理只能修改自己创建的分配记录的 status
|
||||
// 使用系统级查询（不带数据权限过滤），再做业务层权限判断以返回正确的 403
|
||||
allocation, err := s.packageAllocationStore.GetByIDForSystem(ctx, id)
|
||||
if err != nil {
|
||||
if err == gorm.ErrRecordNotFound {
|
||||
return errors.New(errors.CodeNotFound, "分配记录不存在")
|
||||
@@ -260,6 +262,15 @@ func (s *Service) UpdateStatus(ctx context.Context, id uint, status int) error {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "获取分配记录失败")
|
||||
}
|
||||
|
||||
userType := middleware.GetUserTypeFromContext(ctx)
|
||||
if userType == constants.UserTypeAgent {
|
||||
callerShopID := middleware.GetShopIDFromContext(ctx)
|
||||
// 代理用户只能修改自己作为 allocator 的记录
|
||||
if allocation.AllocatorShopID != callerShopID {
|
||||
return errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")
|
||||
}
|
||||
}
|
||||
|
||||
if err := s.packageAllocationStore.UpdateStatus(ctx, id, status, currentUserID); err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "更新状态失败")
|
||||
}
|
||||
@@ -267,6 +278,43 @@ func (s *Service) UpdateStatus(ctx context.Context, id uint, status int) error {
|
||||
return nil
|
||||
}
|
||||
|
||||
// UpdateShelfStatus 更新分配记录的上下架状态
|
||||
// 代理独立控制自己客户侧套餐可见性，不影响平台全局状态
|
||||
func (s *Service) UpdateShelfStatus(ctx context.Context, allocationID uint, shelfStatus int) error {
|
||||
currentUserID := middleware.GetUserIDFromContext(ctx)
|
||||
if currentUserID == 0 {
|
||||
return errors.New(errors.CodeUnauthorized, "未授权访问")
|
||||
}
|
||||
|
||||
allocation, err := s.packageAllocationStore.GetByID(ctx, allocationID)
|
||||
if err != nil {
|
||||
if err == gorm.ErrRecordNotFound {
|
||||
return errors.New(errors.CodeNotFound, "分配记录不存在")
|
||||
}
|
||||
return errors.Wrap(errors.CodeInternalError, err, "获取分配记录失败")
|
||||
}
|
||||
|
||||
// 上架时检查套餐全局状态：禁用的套餐不允许上架
|
||||
if shelfStatus == constants.ShelfStatusOn {
|
||||
pkg, err := s.packageStore.GetByID(ctx, allocation.PackageID)
|
||||
if err != nil {
|
||||
if err == gorm.ErrRecordNotFound {
|
||||
return errors.New(errors.CodeNotFound, "套餐不存在")
|
||||
}
|
||||
return errors.Wrap(errors.CodeInternalError, err, "获取套餐失败")
|
||||
}
|
||||
if pkg.Status == constants.StatusDisabled {
|
||||
return errors.New(errors.CodeInvalidStatus, "套餐已禁用，无法上架")
|
||||
}
|
||||
}
|
||||
|
||||
if err := s.packageAllocationStore.UpdateShelfStatus(ctx, allocationID, shelfStatus, currentUserID); err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "更新上下架状态失败")
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
func (s *Service) buildResponse(ctx context.Context, a *model.ShopPackageAllocation, shopName, packageName, packageCode string) (*dto.ShopPackageAllocationResponse, error) {
|
||||
var seriesID uint
|
||||
seriesName := ""
|
||||
@@ -304,6 +352,7 @@ func (s *Service) buildResponse(ctx context.Context, a *model.ShopPackageAllocat
|
||||
AllocatorShopName: allocatorShopName,
|
||||
CostPrice: a.CostPrice,
|
||||
Status: a.Status,
|
||||
ShelfStatus: a.ShelfStatus,
|
||||
CreatedAt: a.CreatedAt.Format(time.RFC3339),
|
||||
UpdatedAt: a.UpdatedAt.Format(time.RFC3339),
|
||||
}, nil
|
||||
|
||||
@@ -58,11 +58,13 @@ func (s *PackageStore) List(ctx context.Context, opts *store.QueryOptions, filte
|
||||
|
||||
query := s.db.WithContext(ctx).Model(&model.Package{})
|
||||
|
||||
// 代理用户额外过滤：只能看到已分配的套餐
|
||||
// 代理用户额外过滤：只能看到已分配（allocation.status=启用）的套餐
|
||||
// 不按 tb_package.shelf_status 过滤，代理套餐可见性由 allocation.shelf_status 决定
|
||||
userType := middleware.GetUserTypeFromContext(ctx)
|
||||
shopID := middleware.GetShopIDFromContext(ctx)
|
||||
if userType == constants.UserTypeAgent && shopID > 0 {
|
||||
query = query.Joins("INNER JOIN tb_shop_package_allocation ON tb_shop_package_allocation.package_id = tb_package.id").
|
||||
isAgent := userType == constants.UserTypeAgent && shopID > 0
|
||||
if isAgent {
|
||||
query = query.Joins("INNER JOIN tb_shop_package_allocation ON tb_shop_package_allocation.package_id = tb_package.id AND tb_shop_package_allocation.deleted_at IS NULL").
|
||||
Where("tb_shop_package_allocation.shop_id = ? AND tb_shop_package_allocation.status = ?",
|
||||
shopID, constants.StatusEnabled)
|
||||
}
|
||||
@@ -77,8 +79,13 @@ func (s *PackageStore) List(ctx context.Context, opts *store.QueryOptions, filte
|
||||
query = query.Where("tb_package.status = ?", status)
|
||||
}
|
||||
if shelfStatus, ok := filters["shelf_status"]; ok {
|
||||
if isAgent {
|
||||
// 代理用户按自己的 allocation.shelf_status 过滤，不使用平台全局值
|
||||
query = query.Where("tb_shop_package_allocation.shelf_status = ?", shelfStatus)
|
||||
} else {
|
||||
query = query.Where("tb_package.shelf_status = ?", shelfStatus)
|
||||
}
|
||||
}
|
||||
if packageType, ok := filters["package_type"].(string); ok && packageType != "" {
|
||||
query = query.Where("tb_package.package_type = ?", packageType)
|
||||
}
|
||||
|
||||
@@ -32,6 +32,16 @@ func (s *ShopPackageAllocationStore) GetByID(ctx context.Context, id uint) (*mod
|
||||
return &allocation, nil
|
||||
}
|
||||
|
||||
// GetByIDForSystem 根据ID获取分配记录（不应用数据权限过滤）
|
||||
// 用于 Service 层需要先查到记录再做业务权限校验的场景
|
||||
func (s *ShopPackageAllocationStore) GetByIDForSystem(ctx context.Context, id uint) (*model.ShopPackageAllocation, error) {
|
||||
var allocation model.ShopPackageAllocation
|
||||
if err := s.db.WithContext(ctx).First(&allocation, id).Error; err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &allocation, nil
|
||||
}
|
||||
|
||||
func (s *ShopPackageAllocationStore) GetByShopAndPackage(ctx context.Context, shopID, packageID uint) (*model.ShopPackageAllocation, error) {
|
||||
var allocation model.ShopPackageAllocation
|
||||
query := s.db.WithContext(ctx).Where("shop_id = ? AND package_id = ?", shopID, packageID)
|
||||
@@ -43,6 +53,18 @@ func (s *ShopPackageAllocationStore) GetByShopAndPackage(ctx context.Context, sh
|
||||
return &allocation, nil
|
||||
}
|
||||
|
||||
// GetByShopAndPackageForSystem 根据店铺和套餐查询分配记录（不应用数据权限过滤）
|
||||
// 用于系统内部查询场景（如购买校验），避免因 ctx 权限限制导致无法查到目标记录
|
||||
func (s *ShopPackageAllocationStore) GetByShopAndPackageForSystem(ctx context.Context, shopID, packageID uint) (*model.ShopPackageAllocation, error) {
|
||||
var allocation model.ShopPackageAllocation
|
||||
if err := s.db.WithContext(ctx).
|
||||
Where("shop_id = ? AND package_id = ?", shopID, packageID).
|
||||
First(&allocation).Error; err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &allocation, nil
|
||||
}
|
||||
|
||||
func (s *ShopPackageAllocationStore) Update(ctx context.Context, allocation *model.ShopPackageAllocation) error {
|
||||
return s.db.WithContext(ctx).Save(allocation).Error
|
||||
}
|
||||
@@ -106,6 +128,17 @@ func (s *ShopPackageAllocationStore) UpdateStatus(ctx context.Context, id uint,
|
||||
}).Error
|
||||
}
|
||||
|
||||
// UpdateShelfStatus 更新分配记录的上下架状态
|
||||
func (s *ShopPackageAllocationStore) UpdateShelfStatus(ctx context.Context, id uint, shelfStatus int, updater uint) error {
|
||||
return s.db.WithContext(ctx).
|
||||
Model(&model.ShopPackageAllocation{}).
|
||||
Where("id = ?", id).
|
||||
Updates(map[string]interface{}{
|
||||
"shelf_status": shelfStatus,
|
||||
"updater": updater,
|
||||
}).Error
|
||||
}
|
||||
|
||||
func (s *ShopPackageAllocationStore) GetByShopID(ctx context.Context, shopID uint) ([]*model.ShopPackageAllocation, error) {
|
||||
var allocations []*model.ShopPackageAllocation
|
||||
query := s.db.WithContext(ctx).Where("shop_id = ? AND status = 1", shopID)
|
||||
|
||||
@@ -0,0 +1,3 @@
|
||||
-- 回滚：移除 tb_shop_package_allocation 表的 shelf_status 字段
|
||||
ALTER TABLE tb_shop_package_allocation
|
||||
DROP COLUMN IF EXISTS shelf_status;
|
||||
@@ -0,0 +1,6 @@
|
||||
-- 为 tb_shop_package_allocation 表新增代理独立上下架状态字段
|
||||
-- 背景：代理调用上下架接口时应只修改自己的分配记录，不影响平台全局套餐状态
|
||||
ALTER TABLE tb_shop_package_allocation
|
||||
ADD COLUMN shelf_status INT NOT NULL DEFAULT 1;
|
||||
|
||||
COMMENT ON COLUMN tb_shop_package_allocation.shelf_status IS '上架状态 1-上架 2-下架';
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-03-02
|
||||
@@ -0,0 +1,85 @@
|
||||
## Context
|
||||
|
||||
### 当前状态
|
||||
|
||||
`tb_package` 有 `shelf_status` 字段（1-上架, 2-下架），由平台控制套餐的全局可见性。`tb_shop_package_allocation` 只有 `status` 字段（1-启用, 2-禁用），没有代理独立的上下架字段。
|
||||
|
||||
当代理调用 `PATCH /api/admin/packages/:id/shelf` 时，service 层直接修改 `tb_package.shelf_status`，导致该操作影响全平台——所有代理和平台的该套餐都被下架。
|
||||
|
||||
### 核心矛盾
|
||||
|
||||
"上下架"在业务上有两个层次：
|
||||
- **平台层**：控制平台自营店面的客户侧可见性，与代理无关
|
||||
- **代理层**：每个代理独立控制自己客户侧的可见性，互不影响
|
||||
|
||||
目前两个层次合并成一个字段，是 Bug 的根源。
|
||||
|
||||
### 约束
|
||||
|
||||
- `tb_shop_package_allocation.status`（启用/禁用）语义为"分配者临时暂停该分配"，不等同于上下架
|
||||
- 平台若要停止某套餐全网销售，应回收分配而非修改 shelf_status
|
||||
- `Package.status`（全局禁用）是唯一影响全平台购买的开关
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 为 `tb_shop_package_allocation` 新增 `shelf_status` 字段，默认上架
|
||||
- `PATCH /packages/:id/shelf` 接口按调用者角色路由到不同数据层（平台→package，代理→allocation）
|
||||
- 代理查看套餐列表/详情时，`shelf_status` 返回自己分配记录的值
|
||||
- 购买校验按购买场景分流：代理场景检查 `allocation.shelf_status`，平台场景检查 `package.shelf_status`
|
||||
- 修复 `UpdateAllocationStatus` 接口缺少所有者校验的安全 Bug
|
||||
|
||||
**Non-Goals:**
|
||||
- 不引入级联上下架（代理A下架不影响代理B）
|
||||
- 不修改 `Package.status`（全局禁用）的语义和操作权限
|
||||
- 不在代理层增加"启用/禁用套餐"能力（status 仍只有分配者可改）
|
||||
- 不变更 URL 路径（同一接口服务不同角色）
|
||||
|
||||
## Decisions
|
||||
|
||||
### 决策 1：角色上下文路由在 Service 层实现
|
||||
|
||||
**选择**：在 `PackageService.UpdateShelfStatus()` 中通过 `middleware.GetUserTypeFromContext(ctx)` 判断角色，路由到不同的 store 操作。
|
||||
|
||||
**理由**：Handler 层保持薄，不含业务逻辑。角色判断属于业务规则，放 Service 层符合分层原则。URL 不变对前端友好，无需区分调用地址。
|
||||
|
||||
**备选方案**：为代理新增单独的 API 路由（如 `PATCH /shop-package-allocations/:id/shelf`）。问题是代理需要知道 allocation ID 而非 package ID，增加前端复杂度，且未来其他类似接口都要新增一套路由。
|
||||
|
||||
### 决策 2：默认上架
|
||||
|
||||
**选择**：分配给代理时，`allocation.shelf_status` 默认为 1（上架）。
|
||||
|
||||
**理由**：分配行为本身代表分配者希望下级销售此套餐，默认上架减少操作步骤。代理可主动下架。
|
||||
|
||||
### 决策 3：购买校验按场景分流
|
||||
|
||||
**选择**：
|
||||
- 客户直接从平台购买 → 检查 `Package.status == enabled AND Package.shelf_status == on`
|
||||
- 客户通过代理购买 → 检查 `Package.status == enabled AND allocation(seller).shelf_status == on`
|
||||
|
||||
**理由**：平台 shelf_status 仅代表平台自营店面状态，与代理销售解耦。代理链路只检查最终销售代理的 allocation，不向上追溯（上级若不想让下级卖，应回收分配）。
|
||||
|
||||
### 决策 4：分配 status 修改加所有者校验
|
||||
|
||||
**选择**：`UpdateAllocationStatus` 检查调用者是否为该 allocation 的 `allocator_shop_id`（平台用户则通过，代理用户需 allocator_shop_id == 调用者 shop_id）。
|
||||
|
||||
**理由**：当前无校验，任意代理可修改任意分配记录的 status，是安全漏洞。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
**[风险] 存量数据的 shelf_status 默认值** → 迁移时 `ALTER TABLE` 设 `DEFAULT 1 NOT NULL`，存量记录全部视为上架，符合业务现状（原来没有这个字段时代理就是在卖）。
|
||||
|
||||
**[风险] 购买校验需要额外查询 allocation** → 校验路径需增加一次 `GetByShopAndPackage` 查询。订单创建场景已有多个查询，增加一次影响可接受；可加索引 `(shop_id, package_id)` 优化（已存在）。
|
||||
|
||||
**[风险] 前端展示的 shelf_status 语义变化** → 代理端看到的 shelf_status 从 package 级变为 allocation 级，前端无需改动（字段名相同，值含义不变），但平台管理员在查看"代理管理的套餐"时无法直接看到各代理的 shelf_status，这属于 Non-Goal。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. 生成数据库迁移文件：`tb_shop_package_allocation` 增加 `shelf_status INT NOT NULL DEFAULT 1`
|
||||
2. 执行迁移（无停机，仅 ADD COLUMN）
|
||||
3. 部署新代码（接口行为自动分流）
|
||||
4. 无回滚风险：新增字段，原有字段语义不变
|
||||
|
||||
## Open Questions
|
||||
|
||||
无。所有设计决策已在探索阶段与业务确认。
|
||||
@@ -0,0 +1,31 @@
|
||||
## Why
|
||||
|
||||
套餐分配给代理后，代理无法独立控制自己的客户侧上下架状态：代理调用上下架接口会直接修改平台级字段 `tb_package.shelf_status`，导致整个平台的该套餐都被下架。需要在分配记录层引入独立的上下架字段，并确立角色上下文决定操作目标的设计原则，为未来 SaaS 化奠定基础。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **新增** `tb_shop_package_allocation.shelf_status` 字段（1-上架, 2-下架），分配时默认上架
|
||||
- **修改** `PATCH /api/admin/packages/:id/shelf` 接口行为：平台/超管修改 `tb_package.shelf_status`，代理修改自己的 `tb_shop_package_allocation.shelf_status`
|
||||
- **修改** 代理查询套餐列表/详情时，`shelf_status` 字段返回各自分配记录的值（而非平台级值）
|
||||
- **修改** 购买校验逻辑：代理场景下检查卖家代理的 `allocation.shelf_status`，不再检查 `package.shelf_status`
|
||||
- **修复** `PUT /api/admin/shop-package-allocations/:id/status` 接口：加入所有者校验（只有分配者才能修改该条记录的 status）
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `allocation-shelf-status`：代理分配记录的独立上下架能力，包括字段定义、API 行为分流（按角色路由到不同数据层）、读取时的展示逻辑
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `package-management`：`shelf_status` 上下架操作的角色分流行为变更（平台→改套餐本身，代理→改分配记录）
|
||||
- `agent-available-packages`：代理查询套餐时 `shelf_status` 字段语义变更（返回各自分配记录的值）
|
||||
- `package-purchase-validation`：购买校验逻辑变更（代理场景改为检查 `allocation.shelf_status`，平台场景保持检查 `package.shelf_status`）
|
||||
|
||||
## Impact
|
||||
|
||||
- **数据库迁移**：`tb_shop_package_allocation` 新增 `shelf_status` 字段
|
||||
- **API 行为变更**：`PATCH /packages/:id/shelf` 同一接口因角色不同操作不同数据层
|
||||
- **购买链路**：`purchase_validation` 服务逻辑调整，需结合购买场景判断检查哪一层的 shelf_status
|
||||
- **列表查询**：`PackageStore.List()` 和响应构建逻辑需感知代理角色并返回正确的 shelf_status
|
||||
- **权限修复**：`ShopPackageAllocationService.UpdateStatus()` 需加 allocator 归属校验
|
||||
@@ -0,0 +1,49 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 代理查询可售套餐列表
|
||||
|
||||
系统 SHALL 通过统一的套餐列表接口（`/api/admin/packages`）为代理用户自动过滤可售套餐。代理用户查询时，系统 MUST 只返回被分配的套餐，响应 MUST 包含成本价、利润空间、返佣信息等代理专属字段。**响应中的 `shelf_status` 字段 MUST 返回代理自己分配记录的值（`allocation.shelf_status`），而非套餐的全局值（`package.shelf_status`）。**
|
||||
|
||||
#### Scenario: 代理查询自动过滤为已分配套餐
|
||||
- **WHEN** 代理用户调用 `GET /api/admin/packages`
|
||||
- **THEN** 系统通过 JOIN `tb_shop_package_allocation` 自动过滤，只返回该代理被分配的套餐
|
||||
|
||||
#### Scenario: 平台用户查询返回所有套餐
|
||||
- **WHEN** 平台用户调用 `GET /api/admin/packages`
|
||||
- **THEN** 系统返回所有套餐（不应用代理权限过滤），shelf_status 返回 `tb_package.shelf_status`
|
||||
|
||||
#### Scenario: 响应包含代理专属字段
|
||||
- **WHEN** 代理用户查询套餐列表
|
||||
- **THEN** 每个套餐包含：cost_price（成本价）、profit_margin（利润空间）、current_commission_rate（当前返佣比例）
|
||||
|
||||
#### Scenario: 响应包含梯度返佣信息
|
||||
- **WHEN** 代理用户查询套餐列表，且该系列启用了梯度返佣
|
||||
- **THEN** 响应包含 tier_info：enabled、current_sales（本周期销量）、current_tier_id（当前档位）、next_threshold（下一档阈值）、next_rate（下一档返佣比例）
|
||||
|
||||
#### Scenario: 按系列筛选
|
||||
- **WHEN** 代理指定套餐系列 ID 筛选
|
||||
- **THEN** 系统只返回该系列下已分配的套餐
|
||||
|
||||
#### Scenario: 代理查询时 shelf_status 返回分配记录的值
|
||||
- **GIVEN** `tb_package.shelf_status=1`（平台上架），代理自己的 `allocation.shelf_status=2`（代理下架）
|
||||
- **WHEN** 代理调用 `GET /api/admin/packages`
|
||||
- **THEN** 响应中该套餐的 `shelf_status=2`（返回代理自己的状态）
|
||||
|
||||
#### Scenario: 代理查询时不按 package.shelf_status 过滤
|
||||
- **GIVEN** `tb_package.shelf_status=2`（平台下架），但代理的 `allocation.shelf_status=1`（代理上架）
|
||||
- **WHEN** 代理调用 `GET /api/admin/packages`
|
||||
- **THEN** 该套餐仍出现在结果中（代理侧状态独立），shelf_status 返回 1
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 代理查询可售套餐详情
|
||||
|
||||
系统 SHALL 通过统一的套餐详情接口（`/api/admin/packages/:id`）为代理用户返回套餐详细信息，包含完整的价格信息。**响应中的 `shelf_status` MUST 返回代理自己分配记录的值。**
|
||||
|
||||
#### Scenario: 代理查询已分配套餐详情
|
||||
- **WHEN** 代理查询一个已被分配的套餐详情
|
||||
- **THEN** 系统返回套餐完整信息，包含：cost_price（成本价）、建议售价、利润空间、价格来源，以及代理自己的 shelf_status
|
||||
|
||||
#### Scenario: 代理查询未分配的套餐
|
||||
- **WHEN** 代理查询一个未被分配的套餐详情
|
||||
- **THEN** 系统返回 404 或权限错误（数据权限过滤生效）
|
||||
@@ -0,0 +1,52 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 分配记录独立上下架
|
||||
|
||||
系统 SHALL 在 `tb_shop_package_allocation` 表新增 `shelf_status` 字段（1-上架, 2-下架），允许代理独立控制自己分配到的套餐在客户侧的可见性，不影响其他代理和平台的同一套餐状态。
|
||||
|
||||
#### Scenario: 新建分配记录默认上架
|
||||
- **WHEN** 平台或上级代理为某店铺创建套餐分配记录
|
||||
- **THEN** `allocation.shelf_status` 默认为 1（上架）
|
||||
|
||||
#### Scenario: 代理下架自己的套餐
|
||||
- **GIVEN** 代理A拥有套餐P的分配记录，shelf_status=1
|
||||
- **WHEN** 代理A调用 `PATCH /api/admin/packages/:id/shelf`，传入 shelf_status=2
|
||||
- **THEN** 系统更新代理A的 `allocation.shelf_status=2`，套餐P在代理A的客户侧不可见
|
||||
- **AND** 代理B的同一套餐分配记录 shelf_status 不受影响
|
||||
- **AND** `tb_package.shelf_status` 不受影响
|
||||
|
||||
#### Scenario: 代理上架自己的套餐
|
||||
- **GIVEN** 代理A的分配记录 shelf_status=2
|
||||
- **WHEN** 代理A调用 `PATCH /api/admin/packages/:id/shelf`，传入 shelf_status=1
|
||||
- **THEN** 系统更新代理A的 `allocation.shelf_status=1`
|
||||
|
||||
#### Scenario: 代理上架已被全局禁用的套餐
|
||||
- **GIVEN** `tb_package.status=2`（套餐全局禁用），代理A的 allocation.shelf_status=2
|
||||
- **WHEN** 代理A尝试将 shelf_status 设置为1（上架）
|
||||
- **THEN** 系统返回错误 "套餐已禁用，无法上架"
|
||||
|
||||
#### Scenario: 调用者无分配记录时无法操作
|
||||
- **GIVEN** 代理A没有套餐P的分配记录
|
||||
- **WHEN** 代理A调用 `PATCH /api/admin/packages/:id/shelf`（套餐ID为P）
|
||||
- **THEN** 系统返回错误 "该套餐未分配给您，无法操作上下架"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 分配记录 status 修改需所有者校验
|
||||
|
||||
系统 MUST 验证调用者是分配记录的创建者（allocator），才允许修改该记录的 `status`（启用/禁用）。
|
||||
|
||||
#### Scenario: 平台用户修改任意分配记录的 status
|
||||
- **GIVEN** 平台用户调用 `PUT /api/admin/shop-package-allocations/:id/status`
|
||||
- **WHEN** 分配记录存在
|
||||
- **THEN** 允许修改，不限制 allocator
|
||||
|
||||
#### Scenario: 代理修改自己创建的分配记录的 status
|
||||
- **GIVEN** 代理A创建了"代理A→代理B"的分配记录（allocator_shop_id = A的shop_id）
|
||||
- **WHEN** 代理A调用修改该记录的 status
|
||||
- **THEN** 允许修改
|
||||
|
||||
#### Scenario: 代理修改别人分配给自己的记录的 status
|
||||
- **GIVEN** 平台或代理A创建了"→代理B"的分配记录（allocator_shop_id != B的shop_id）
|
||||
- **WHEN** 代理B调用修改该记录的 status
|
||||
- **THEN** 系统返回错误 "无权限操作该资源或资源不存在"
|
||||
@@ -0,0 +1,37 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 上架/下架套餐
|
||||
|
||||
系统 SHALL 通过 `PATCH /api/admin/packages/:id/shelf` 接口允许不同角色切换套餐上下架状态。**操作目标因调用者角色而不同**：平台/超管修改 `tb_package.shelf_status`（全局状态），代理修改自己的 `tb_shop_package_allocation.shelf_status`（代理独立状态）。只有启用状态的套餐才能上架。
|
||||
|
||||
#### Scenario: 平台管理员上架启用的套餐
|
||||
- **WHEN** 平台/超管将启用且下架的套餐设置为上架
|
||||
- **THEN** 系统更新 `tb_package.shelf_status=1`
|
||||
|
||||
#### Scenario: 平台管理员尝试上架禁用的套餐
|
||||
- **WHEN** 平台/超管尝试上架一个 status=2（禁用）的套餐
|
||||
- **THEN** 系统返回错误 "禁用的套餐不能上架，请先启用"
|
||||
|
||||
#### Scenario: 平台管理员下架套餐
|
||||
- **WHEN** 平台/超管将上架的套餐设置为下架
|
||||
- **THEN** 系统更新 `tb_package.shelf_status=2`，只影响平台自营渠道
|
||||
|
||||
#### Scenario: 代理上架自己分配的套餐
|
||||
- **GIVEN** 代理拥有该套餐的分配记录，且 `tb_package.status=1`（启用）
|
||||
- **WHEN** 代理调用接口设置 shelf_status=1
|
||||
- **THEN** 系统更新该代理的 `allocation.shelf_status=1`，不修改 `tb_package.shelf_status`
|
||||
|
||||
#### Scenario: 代理下架自己分配的套餐
|
||||
- **GIVEN** 代理拥有该套餐的分配记录，allocation.shelf_status=1
|
||||
- **WHEN** 代理调用接口设置 shelf_status=2
|
||||
- **THEN** 系统更新该代理的 `allocation.shelf_status=2`，不影响其他代理
|
||||
|
||||
#### Scenario: 代理尝试上架全局禁用的套餐
|
||||
- **GIVEN** `tb_package.status=2`（禁用）
|
||||
- **WHEN** 代理尝试将 shelf_status 设置为1
|
||||
- **THEN** 系统返回错误 "套餐已禁用，无法上架"
|
||||
|
||||
#### Scenario: 代理操作未分配的套餐
|
||||
- **GIVEN** 代理没有该套餐的分配记录
|
||||
- **WHEN** 代理调用接口操作该套餐的上下架
|
||||
- **THEN** 系统返回错误 "该套餐未分配给您，无法操作上下架"
|
||||
@@ -0,0 +1,35 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 验证套餐状态
|
||||
|
||||
创建订单前系统 MUST 验证套餐处于可购买状态。**校验逻辑因购买场景而不同**：通过代理渠道购买时检查代理分配记录的 shelf_status，通过平台自营渠道购买时检查套餐全局 shelf_status。`Package.status`（启用/禁用）为全局开关，任何场景下都必须检查。
|
||||
|
||||
#### Scenario: 代理渠道 - 套餐启用且代理上架
|
||||
- **GIVEN** `Package.status=1`（启用），卖家代理的 `allocation.shelf_status=1`（上架）
|
||||
- **WHEN** 客户通过该代理下单购买套餐
|
||||
- **THEN** 套餐状态校验通过
|
||||
|
||||
#### Scenario: 代理渠道 - 套餐已禁用
|
||||
- **GIVEN** `Package.status=2`（禁用）
|
||||
- **WHEN** 客户通过任意代理下单购买套餐
|
||||
- **THEN** 验证失败，返回 "套餐已禁用"
|
||||
|
||||
#### Scenario: 代理渠道 - 代理已下架套餐
|
||||
- **GIVEN** `Package.status=1`（启用），卖家代理的 `allocation.shelf_status=2`（代理下架）
|
||||
- **WHEN** 客户通过该代理下单购买套餐
|
||||
- **THEN** 验证失败，返回 "套餐已下架"
|
||||
|
||||
#### Scenario: 代理渠道 - 平台下架不影响代理销售
|
||||
- **GIVEN** `Package.status=1`（启用），`Package.shelf_status=2`（平台下架），卖家代理的 `allocation.shelf_status=1`（代理上架）
|
||||
- **WHEN** 客户通过该代理下单购买套餐
|
||||
- **THEN** 套餐状态校验通过（平台 shelf_status 不参与代理渠道校验）
|
||||
|
||||
#### Scenario: 平台自营渠道 - 套餐启用且平台上架
|
||||
- **GIVEN** `Package.status=1`（启用），`Package.shelf_status=1`（平台上架）
|
||||
- **WHEN** 客户通过平台自营渠道下单购买套餐
|
||||
- **THEN** 套餐状态校验通过
|
||||
|
||||
#### Scenario: 平台自营渠道 - 套餐已下架
|
||||
- **GIVEN** `Package.status=1`（启用），`Package.shelf_status=2`（平台下架）
|
||||
- **WHEN** 客户通过平台自营渠道下单购买套餐
|
||||
- **THEN** 验证失败，返回 "套餐已下架"
|
||||
@@ -0,0 +1,45 @@
|
||||
## 1. 数据库迁移
|
||||
|
||||
- [x] 1.1 创建迁移文件，为 `tb_shop_package_allocation` 新增 `shelf_status INT NOT NULL DEFAULT 1` 字段，添加字段注释"上架状态 1-上架 2-下架"
|
||||
- [x] 1.2 执行迁移，确认字段已添加，存量记录 shelf_status 均为 1
|
||||
|
||||
## 2. Model 和 Store 层
|
||||
|
||||
- [x] 2.1 在 `internal/model/shop_package_allocation.go` 中为 `ShopPackageAllocation` 结构体新增 `ShelfStatus` 字段（gorm tag + json tag）
|
||||
- [x] 2.2 在 `internal/store/postgres/shop_package_allocation_store.go` 中新增 `UpdateShelfStatus(ctx, id, shelfStatus, updaterID)` 方法
|
||||
- [x] 2.3 在 `internal/store/postgres/package_allocation_store_interface.go`（或对应接口文件）中更新接口定义，添加 `UpdateShelfStatus` 方法签名
|
||||
|
||||
## 3. 分配上下架能力（allocation-shelf-status）
|
||||
|
||||
- [x] 3.1 在 `internal/service/shop_package_allocation/service.go` 中新增 `UpdateShelfStatus(ctx, allocationID, shelfStatus)` 方法，实现：套餐禁用时拒绝上架（查 Package.status）、成功则调用 Store 更新
|
||||
- [x] 3.2 在 `internal/service/shop_package_allocation/service.go` 的 `UpdateStatus()` 方法中加入所有者校验：代理用户需验证 `allocation.allocator_shop_id == caller.shopID`，不匹配则返回 `errors.CodeForbidden`
|
||||
|
||||
## 4. 套餐上下架接口角色分流（package-management）
|
||||
|
||||
- [x] 4.1 在 `internal/service/package/service.go` 的 `UpdateShelfStatus()` 方法中，增加角色判断：代理用户走分配记录路径（查找并更新 `allocation.shelf_status`），平台/超管走原有套餐路径（更新 `package.shelf_status`）
|
||||
- [x] 4.2 代理路径需处理：分配记录不存在时返回 "该套餐未分配给您，无法操作上下架"；Package.status=禁用时拒绝上架
|
||||
|
||||
## 5. 代理查询套餐响应（agent-available-packages）
|
||||
|
||||
- [x] 5.1 在 `internal/service/package/service.go` 的 `toResponse()` 和 `toResponseWithAllocation()` 方法中，代理角色时将响应的 `ShelfStatus` 替换为 `allocation.ShelfStatus`（而非 `package.ShelfStatus`）
|
||||
- [x] 5.2 确认 `PackageStore.List()` 对代理用户的过滤逻辑：不再按 `package.shelf_status` 过滤（代理看到的套餐不因平台下架而消失），改为代理能看到自己所有已分配（allocation.status=启用）的套餐
|
||||
|
||||
## 6. 购买校验逻辑（package-purchase-validation）
|
||||
|
||||
- [x] 6.1 在 `internal/service/purchase_validation/service.go` 的套餐状态校验中，增加购买场景判断：代理渠道购买时获取卖家代理的 `allocation.shelf_status` 进行校验，不检查 `package.shelf_status`；平台自营渠道保持检查 `package.shelf_status`
|
||||
- [x] 6.2 确认 `PurchaseValidationService` 能获取到卖家代理的 shop_id（通过 ctx 或参数传入），并调用 `ShopPackageAllocationStore.GetByShopAndPackage()` 获取 allocation 记录
|
||||
|
||||
## 7. DTO 更新
|
||||
|
||||
- [x] 7.1 在 `internal/model/dto/shop_package_allocation_dto.go` 中为 `ShopPackageAllocationResponse` 新增 `ShelfStatus` 字段（含 description 标签）
|
||||
- [x] 7.2 新增 `UpdateShopPackageAllocationShelfStatusRequest` DTO 和对应 Params（包含路由 ID + body），用于 handler 绑定（如未来需要独立路由时备用，当前复用 package 接口的分流即可，此 DTO 可仅用于 service 内部）
|
||||
|
||||
## 8. 验证
|
||||
|
||||
- [x] 8.1 使用 PostgreSQL MCP 工具确认 `tb_shop_package_allocation` 表含 `shelf_status` 字段，存量数据默认值为 1
|
||||
- [x] 8.2 调用 `PATCH /api/admin/packages/:id/shelf`（代理身份），验证只更新了 `allocation.shelf_status`，`tb_package.shelf_status` 不变
|
||||
- [x] 8.3 调用 `PATCH /api/admin/packages/:id/shelf`（平台身份），验证更新了 `tb_package.shelf_status`，allocation 不变
|
||||
- [x] 8.4 代理下架套餐后，验证另一代理的同一套餐 shelf_status 不受影响
|
||||
- [x] 8.5 代理下架套餐后，验证其客户下单时购买校验报错"套餐已下架"
|
||||
- [x] 8.6 平台下架套餐后，验证代理仍可在其列表中看到该套餐（shelf_status 显示代理自己的状态）
|
||||
- [x] 8.7 验证代理无法修改别人分配给自己的 allocation.status（调用 `PUT /shop-package-allocations/:id/status` 应返回 403）
|
||||
@@ -8,7 +8,7 @@
|
||||
|
||||
### Requirement: 代理查询可售套餐列表
|
||||
|
||||
系统 SHALL 通过统一的套餐列表接口（`/api/admin/packages`）为代理用户自动过滤可售套餐。代理用户查询时，系统 MUST 只返回被分配的套餐，响应 MUST 包含成本价、利润空间、返佣信息等代理专属字段。
|
||||
系统 SHALL 通过统一的套餐列表接口（`/api/admin/packages`）为代理用户自动过滤可售套餐。代理用户查询时，系统 MUST 只返回被分配的套餐，响应 MUST 包含成本价、利润空间、返佣信息等代理专属字段。**响应中的 `shelf_status` 字段 MUST 返回代理自己分配记录的值（`allocation.shelf_status`），而非套餐的全局值（`package.shelf_status`）。**
|
||||
|
||||
#### Scenario: 代理查询自动过滤为已分配套餐
|
||||
- **WHEN** 代理用户调用 `GET /api/admin/packages`
|
||||
@@ -16,7 +16,7 @@
|
||||
|
||||
#### Scenario: 平台用户查询返回所有套餐
|
||||
- **WHEN** 平台用户调用 `GET /api/admin/packages`
|
||||
- **THEN** 系统返回所有套餐（不应用代理权限过滤）
|
||||
- **THEN** 系统返回所有套餐（不应用代理权限过滤），shelf_status 返回 `tb_package.shelf_status`
|
||||
|
||||
#### Scenario: 响应包含代理专属字段
|
||||
- **WHEN** 代理用户查询套餐列表
|
||||
@@ -30,19 +30,25 @@
|
||||
- **WHEN** 代理指定套餐系列 ID 筛选
|
||||
- **THEN** 系统只返回该系列下已分配的套餐
|
||||
|
||||
#### Scenario: 只返回启用且上架的套餐
|
||||
- **WHEN** 代理查询可售套餐
|
||||
- **THEN** 系统只返回 status=1（启用）且 shelf_status=1（上架）的套餐
|
||||
#### Scenario: 代理查询时 shelf_status 返回分配记录的值
|
||||
- **GIVEN** `tb_package.shelf_status=1`（平台上架），代理自己的 `allocation.shelf_status=2`（代理下架）
|
||||
- **WHEN** 代理调用 `GET /api/admin/packages`
|
||||
- **THEN** 响应中该套餐的 `shelf_status=2`（返回代理自己的状态）
|
||||
|
||||
#### Scenario: 代理查询时不按 package.shelf_status 过滤
|
||||
- **GIVEN** `tb_package.shelf_status=2`（平台下架），但代理的 `allocation.shelf_status=1`（代理上架）
|
||||
- **WHEN** 代理调用 `GET /api/admin/packages`
|
||||
- **THEN** 该套餐仍出现在结果中（代理侧状态独立），shelf_status 返回 1
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 代理查询可售套餐详情
|
||||
|
||||
系统 SHALL 通过统一的套餐详情接口（`/api/admin/packages/:id`）为代理用户返回套餐详细信息，包含完整的价格信息。
|
||||
系统 SHALL 通过统一的套餐详情接口（`/api/admin/packages/:id`）为代理用户返回套餐详细信息，包含完整的价格信息。**响应中的 `shelf_status` MUST 返回代理自己分配记录的值。**
|
||||
|
||||
#### Scenario: 代理查询已分配套餐详情
|
||||
- **WHEN** 代理查询一个已被分配的套餐详情
|
||||
- **THEN** 系统返回套餐完整信息，包含：成本价、建议售价、利润空间、价格来源（系列分配）
|
||||
- **THEN** 系统返回套餐完整信息，包含：cost_price（成本价）、建议售价、利润空间、价格来源，以及代理自己的 shelf_status
|
||||
|
||||
#### Scenario: 代理查询未分配的套餐
|
||||
- **WHEN** 代理查询一个未被分配的套餐详情
|
||||
|
||||
58
openspec/specs/allocation-shelf-status/spec.md
Normal file
58
openspec/specs/allocation-shelf-status/spec.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# Capability: 分配记录独立上下架
|
||||
|
||||
## Purpose
|
||||
|
||||
本 capability 定义代理对自己分配到的套餐的独立上下架能力。代理可以独立控制自己客户侧的套餐可见性，互不影响。同时约束分配记录 status 修改的所有者校验规则。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 分配记录独立上下架
|
||||
|
||||
系统 SHALL 在 `tb_shop_package_allocation` 表维护 `shelf_status` 字段（1-上架, 2-下架），允许代理独立控制自己分配到的套餐在客户侧的可见性，不影响其他代理和平台的同一套餐状态。
|
||||
|
||||
#### Scenario: 新建分配记录默认上架
|
||||
- **WHEN** 平台或上级代理为某店铺创建套餐分配记录
|
||||
- **THEN** `allocation.shelf_status` 默认为 1（上架）
|
||||
|
||||
#### Scenario: 代理下架自己的套餐
|
||||
- **GIVEN** 代理A拥有套餐P的分配记录，shelf_status=1
|
||||
- **WHEN** 代理A调用 `PATCH /api/admin/packages/:id/shelf`，传入 shelf_status=2
|
||||
- **THEN** 系统更新代理A的 `allocation.shelf_status=2`，套餐P在代理A的客户侧不可见
|
||||
- **AND** 代理B的同一套餐分配记录 shelf_status 不受影响
|
||||
- **AND** `tb_package.shelf_status` 不受影响
|
||||
|
||||
#### Scenario: 代理上架自己的套餐
|
||||
- **GIVEN** 代理A的分配记录 shelf_status=2
|
||||
- **WHEN** 代理A调用 `PATCH /api/admin/packages/:id/shelf`，传入 shelf_status=1
|
||||
- **THEN** 系统更新代理A的 `allocation.shelf_status=1`
|
||||
|
||||
#### Scenario: 代理上架已被全局禁用的套餐
|
||||
- **GIVEN** `tb_package.status=2`（套餐全局禁用），代理A的 allocation.shelf_status=2
|
||||
- **WHEN** 代理A尝试将 shelf_status 设置为1（上架）
|
||||
- **THEN** 系统返回错误 "套餐已禁用，无法上架"
|
||||
|
||||
#### Scenario: 调用者无分配记录时无法操作
|
||||
- **GIVEN** 代理A没有套餐P的分配记录
|
||||
- **WHEN** 代理A调用 `PATCH /api/admin/packages/:id/shelf`（套餐ID为P）
|
||||
- **THEN** 系统返回错误 "该套餐未分配给您，无法操作上下架"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 分配记录 status 修改需所有者校验
|
||||
|
||||
系统 MUST 验证调用者是分配记录的创建者（allocator），才允许修改该记录的 `status`（启用/禁用）。
|
||||
|
||||
#### Scenario: 平台用户修改任意分配记录的 status
|
||||
- **GIVEN** 平台用户调用 `PUT /api/admin/shop-package-allocations/:id/status`
|
||||
- **WHEN** 分配记录存在
|
||||
- **THEN** 允许修改，不限制 allocator
|
||||
|
||||
#### Scenario: 代理修改自己创建的分配记录的 status
|
||||
- **GIVEN** 代理A创建了"代理A→代理B"的分配记录（allocator_shop_id = A的shop_id）
|
||||
- **WHEN** 代理A调用修改该记录的 status
|
||||
- **THEN** 允许修改
|
||||
|
||||
#### Scenario: 代理修改别人分配给自己的记录的 status
|
||||
- **GIVEN** 平台或代理A创建了"→代理B"的分配记录（allocator_shop_id != B的shop_id）
|
||||
- **WHEN** 代理B调用修改该记录的 status
|
||||
- **THEN** 系统返回错误 "无权限操作该资源或资源不存在"
|
||||
@@ -197,19 +197,39 @@
|
||||
|
||||
### Requirement: 上架/下架套餐
|
||||
|
||||
系统 SHALL 允许管理员切换套餐的上架状态。只有启用状态的套餐才能上架。
|
||||
系统 SHALL 通过 `PATCH /api/admin/packages/:id/shelf` 接口允许不同角色切换套餐上下架状态。**操作目标因调用者角色而不同**：平台/超管修改 `tb_package.shelf_status`（全局状态），代理修改自己的 `tb_shop_package_allocation.shelf_status`（代理独立状态）。只有启用状态的套餐才能上架。
|
||||
|
||||
#### Scenario: 上架启用的套餐
|
||||
- **WHEN** 管理员将启用且下架的套餐设置为上架
|
||||
- **THEN** 系统更新上架状态为上架(1)
|
||||
#### Scenario: 平台管理员上架启用的套餐
|
||||
- **WHEN** 平台/超管将启用且下架的套餐设置为上架
|
||||
- **THEN** 系统更新 `tb_package.shelf_status=1`
|
||||
|
||||
#### Scenario: 尝试上架禁用的套餐
|
||||
- **WHEN** 管理员尝试上架一个禁用的套餐
|
||||
#### Scenario: 平台管理员尝试上架禁用的套餐
|
||||
- **WHEN** 平台/超管尝试上架一个 status=2（禁用）的套餐
|
||||
- **THEN** 系统返回错误 "禁用的套餐不能上架，请先启用"
|
||||
|
||||
#### Scenario: 下架套餐
|
||||
- **WHEN** 管理员将上架的套餐设置为下架
|
||||
- **THEN** 系统更新上架状态为下架(2)
|
||||
#### Scenario: 平台管理员下架套餐
|
||||
- **WHEN** 平台/超管将上架的套餐设置为下架
|
||||
- **THEN** 系统更新 `tb_package.shelf_status=2`，只影响平台自营渠道
|
||||
|
||||
#### Scenario: 代理上架自己分配的套餐
|
||||
- **GIVEN** 代理拥有该套餐的分配记录，且 `tb_package.status=1`（启用）
|
||||
- **WHEN** 代理调用接口设置 shelf_status=1
|
||||
- **THEN** 系统更新该代理的 `allocation.shelf_status=1`，不修改 `tb_package.shelf_status`
|
||||
|
||||
#### Scenario: 代理下架自己分配的套餐
|
||||
- **GIVEN** 代理拥有该套餐的分配记录，allocation.shelf_status=1
|
||||
- **WHEN** 代理调用接口设置 shelf_status=2
|
||||
- **THEN** 系统更新该代理的 `allocation.shelf_status=2`，不影响其他代理
|
||||
|
||||
#### Scenario: 代理尝试上架全局禁用的套餐
|
||||
- **GIVEN** `tb_package.status=2`（禁用）
|
||||
- **WHEN** 代理尝试将 shelf_status 设置为1
|
||||
- **THEN** 系统返回错误 "套餐已禁用，无法上架"
|
||||
|
||||
#### Scenario: 代理操作未分配的套餐
|
||||
- **GIVEN** 代理没有该套餐的分配记录
|
||||
- **WHEN** 代理调用接口操作该套餐的上下架
|
||||
- **THEN** 系统返回错误 "该套餐未分配给您，无法操作上下架"
|
||||
|
||||
#### Scenario: 状态未变化
|
||||
- **WHEN** 管理员设置的上架状态与当前状态相同
|
||||
|
||||
@@ -24,18 +24,36 @@
|
||||
|
||||
### Requirement: 验证套餐状态
|
||||
|
||||
创建订单前系统 MUST 验证套餐处于可购买状态。
|
||||
创建订单前系统 MUST 验证套餐处于可购买状态。**校验逻辑因购买场景而不同**：通过代理渠道购买时检查代理分配记录的 shelf_status，通过平台自营渠道购买时检查套餐全局 shelf_status。`Package.status`（启用/禁用）为全局开关，任何场景下都必须检查。
|
||||
|
||||
#### Scenario: 套餐启用且上架
|
||||
- **WHEN** 套餐 status=1 且 shelf_status=1
|
||||
- **THEN** 验证通过
|
||||
#### Scenario: 代理渠道 - 套餐启用且代理上架
|
||||
- **GIVEN** `Package.status=1`（启用），卖家代理的 `allocation.shelf_status=1`（上架）
|
||||
- **WHEN** 客户通过该代理下单购买套餐
|
||||
- **THEN** 套餐状态校验通过
|
||||
|
||||
#### Scenario: 套餐已禁用
|
||||
- **WHEN** 套餐 status=2
|
||||
#### Scenario: 代理渠道 - 套餐已禁用
|
||||
- **GIVEN** `Package.status=2`（禁用）
|
||||
- **WHEN** 客户通过任意代理下单购买套餐
|
||||
- **THEN** 验证失败，返回 "套餐已禁用"
|
||||
|
||||
#### Scenario: 套餐已下架
|
||||
- **WHEN** 套餐 shelf_status=2
|
||||
#### Scenario: 代理渠道 - 代理已下架套餐
|
||||
- **GIVEN** `Package.status=1`（启用），卖家代理的 `allocation.shelf_status=2`（代理下架）
|
||||
- **WHEN** 客户通过该代理下单购买套餐
|
||||
- **THEN** 验证失败，返回 "套餐已下架"
|
||||
|
||||
#### Scenario: 代理渠道 - 平台下架不影响代理销售
|
||||
- **GIVEN** `Package.status=1`（启用），`Package.shelf_status=2`（平台下架），卖家代理的 `allocation.shelf_status=1`（代理上架）
|
||||
- **WHEN** 客户通过该代理下单购买套餐
|
||||
- **THEN** 套餐状态校验通过（平台 shelf_status 不参与代理渠道校验）
|
||||
|
||||
#### Scenario: 平台自营渠道 - 套餐启用且平台上架
|
||||
- **GIVEN** `Package.status=1`（启用），`Package.shelf_status=1`（平台上架）
|
||||
- **WHEN** 客户通过平台自营渠道下单购买套餐
|
||||
- **THEN** 套餐状态校验通过
|
||||
|
||||
#### Scenario: 平台自营渠道 - 套餐已下架
|
||||
- **GIVEN** `Package.status=1`（启用），`Package.shelf_status=2`（平台下架）
|
||||
- **WHEN** 客户通过平台自营渠道下单购买套餐
|
||||
- **THEN** 验证失败，返回 "套餐已下架"
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user