junhong_cmp_fiber/openspec/changes/archive/2026-01-28-add-shop-package-allocation/design.md

Context

Phase 1 完成了套餐系列和套餐的基础管理，但代理商还不能分销套餐。本期实现代理套餐分配机制，使上级代理能够：

1. 为下级店铺分配可销售的套餐系列
2. 通过加价模式设置下级的成本价
3. 配置梯度佣金（基于销量/销售额的阶梯奖励）

当前代理层级结构：

• 店铺通过 Shop.parent_id 维护层级关系
• 最多 7 级代理
• 数据权限通过 GetSubordinateShopIDs() 递归查询

Goals / Non-Goals

Goals:

• 实现套餐系列级别的分配机制
• 支持固定金额和百分比两种加价模式
• 支持梯度佣金配置（月度/季度/年度/自定义时间范围）
• 代理能查看自己被分配的套餐及成本价
• 可选的单套餐级别成本价覆盖

Non-Goals:

• 不实现卡/设备的套餐系列关联（Phase 3）
• 不实现订单支付流程（Phase 4）
• 不实现佣金计算逻辑（Phase 5）
• 不支持跨级分配（只能分配给直属下级）

Decisions

1. 分配模型设计

决策：三个独立模型

// ShopSeriesAllocation 店铺套餐系列分配
type ShopSeriesAllocation struct {
    gorm.Model
    BaseModel
    ShopID                      uint   // 被分配的店铺 ID
    SeriesID                    uint   // 套餐系列 ID
    AllocatorShopID             uint   // 分配者店铺 ID（上级）
    PricingMode                 string // 加价模式: fixed-固定金额 percent-百分比
    PricingValue                int64  // 加价值（分或千分比）
    OneTimeCommissionTrigger    string // 一次性佣金触发类型: one_time_recharge-单次充值 accumulated_recharge-累计充值
    OneTimeCommissionThreshold  int64  // 一次性佣金触发阈值（分）
    OneTimeCommissionAmount     int64  // 一次性佣金金额（分）
    Status                      int    // 状态 1-启用 2-禁用
}

// ShopSeriesCommissionTier 梯度佣金配置
type ShopSeriesCommissionTier struct {
    gorm.Model
    BaseModel
    AllocationID     uint      // 关联的分配 ID
    TierType         string    // 梯度类型: sales_count-销量 sales_amount-销售额
    PeriodType       string    // 周期类型: monthly-月度 quarterly-季度 yearly-年度 custom-自定义
    PeriodStartDate  *time.Time // 自定义周期开始日期
    PeriodEndDate    *time.Time // 自定义周期结束日期
    ThresholdValue   int64     // 阈值（销量或金额）
    CommissionAmount int64     // 佣金金额（分）
}

// ShopPackageAllocation 店铺单套餐分配（可选覆盖）
type ShopPackageAllocation struct {
    gorm.Model
    BaseModel
    ShopID          uint  // 被分配的店铺 ID
    PackageID       uint  // 套餐 ID
    AllocationID    uint  // 关联的系列分配 ID
    CostPrice       int64 // 覆盖的成本价（分）
    Status          int   // 状态 1-启用 2-禁用
}

理由：

• 系列级别分配是主要方式，减少配置工作量
• 单套餐分配用于特殊场景（如某个套餐给特定代理优惠价）
• 梯度佣金独立模型，支持多档配置

2. 加价模式与成本价计算

决策：成本价 = 上级成本价 + 加价值

# 固定金额加价
下级成本价 = 上级成本价 + pricing_value

# 百分比加价（pricing_value 为千分比，如 100 = 10%）
下级成本价 = 上级成本价 × (1 + pricing_value / 1000)

理由：

• 基于上级成本价加价，确保每级都有利润空间
• 千分比精度满足业务需求（0.1% 精度）
• 平台作为顶级，其成本价 = Package.suggested_cost_price

约束：

• 下级成本价 ≥ 上级成本价（禁止负加价）
• 验证时需递归获取上级成本价

3. 成本价获取逻辑

决策：递归查询 + 缓存

func GetCostPrice(shopID, packageID uint) int64 {
    // 1. 检查是否有单套餐覆盖
    if override := GetPackageAllocation(shopID, packageID); override != nil {
        return override.CostPrice
    }
    
    // 2. 获取系列分配
    allocation := GetSeriesAllocation(shopID, package.SeriesID)
    if allocation == nil {
        return 0 // 未分配，不可购买
    }
    
    // 3. 获取上级成本价
    parentCostPrice := GetParentCostPrice(allocation.AllocatorShopID, packageID)
    
    // 4. 计算当前成本价
    return CalculatePrice(parentCostPrice, allocation.PricingMode, allocation.PricingValue)
}

理由：

• 单套餐覆盖优先级最高
• 递归到平台级别时，使用 Package.suggested_cost_price
• 可考虑缓存热点套餐的成本价（后续优化）

4. 梯度佣金周期计算

决策：支持固定周期和自定义周期

PeriodType	计算方式
monthly	当月 1 日 00:00 至月末 23:59:59
quarterly	当季度第一天至最后一天
yearly	当年 1 月 1 日至 12 月 31 日
custom	PeriodStartDate 至 PeriodEndDate

理由：

• 固定周期覆盖常见场景
• 自定义周期支持促销活动等特殊需求

5. API 设计

决策：RESTful + 嵌套资源

# 套餐系列分配
POST   /api/admin/shop-series-allocations              为下级分配系列
GET    /api/admin/shop-series-allocations              查询分配列表
GET    /api/admin/shop-series-allocations/:id          分配详情
PUT    /api/admin/shop-series-allocations/:id          更新分配
DELETE /api/admin/shop-series-allocations/:id          删除分配
PATCH  /api/admin/shop-series-allocations/:id/status   启用/禁用

# 梯度佣金（嵌套在分配下）
POST   /api/admin/shop-series-allocations/:id/tiers    添加梯度
GET    /api/admin/shop-series-allocations/:id/tiers    梯度列表
PUT    /api/admin/shop-series-allocations/:id/tiers/:tierId  更新梯度
DELETE /api/admin/shop-series-allocations/:id/tiers/:tierId  删除梯度

# 单套餐分配
POST   /api/admin/shop-package-allocations             分配单套餐
GET    /api/admin/shop-package-allocations             查询列表
PUT    /api/admin/shop-package-allocations/:id         更新
DELETE /api/admin/shop-package-allocations/:id         删除

# 代理可售套餐
GET    /api/admin/my-packages                          查询我的可售套餐
GET    /api/admin/my-packages/:id                      套餐详情（含成本价）

Risks / Trade-offs

风险 1：递归成本价计算性能

风险：多级代理场景下，递归查询成本价可能较慢

缓解：

• 首期不做缓存，观察实际性能
• 如有问题，后续增加 Redis 缓存（按 shop_id + package_id 缓存）
• 缓存失效策略：分配变更时清除相关缓存

风险 2：分配一致性

风险：上级删除分配后，下级的分配关系如何处理

缓解：

• 删除分配时检查是否有下级依赖
• 如有下级依赖，禁止删除或级联禁用
• 本期采用禁止删除策略，要求先清理下级分配

风险 3：梯度佣金统计复杂度

风险：统计周期内的销量/销售额可能涉及大量数据

缓解：

• 佣金计算在 Phase 5 实现
• 可考虑定时任务预计算周期统计数据
• 本期只做配置，不做实际统计

Open Questions

1. 是否支持批量分配？

   • 当前设计：单个分配
   • 待确认：是否需要批量为多个下级分配同一系列？

2. 分配删除策略？

   • 当前设计：有下级依赖时禁止删除
   • 待确认：是否需要级联删除或级联禁用？

3. 梯度佣金是否可叠加？

   • 当前设计：达到最高档位只拿最高档佣金
   • 待确认：是否需要累加所有达标档位的佣金？