junhong_cmp_fiber/openspec/changes/archive/2026-01-28-add-shop-package-allocation/proposal.md at c5bf85c8de920e71adb2d18ae2dc7ca6bfb3d3d9

csxj2026/junhong_cmp_fiber

Files

构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m18s

Details

主要变更：
- 重构分配模型：从加价模式（pricing_mode/pricing_value）改为返佣模式（base_commission + tier_commission）
- 删除独立的 my_package 接口，统一到 /api/admin/packages（通过数据权限自动过滤）
- 新增批量分配和批量调价功能，支持事务和性能优化
- 新增配置版本管理，订单创建时锁定返佣配置
- 新增成本价历史记录，支持审计和纠纷处理
- 新增统计缓存系统（Redis + 异步任务），优化梯度返佣计算性能
- 删除冗余的梯度佣金独立 CRUD 接口（合并到分配配置中）
- 归档 3 个已完成的 OpenSpec changes 并同步 8 个新 capabilities 到 main specs

技术细节：
- 数据库迁移：000026_refactor_shop_package_allocation
- 新增 Store：AllocationConfigStore, PriceHistoryStore, CommissionStatsStore
- 新增 Service：BatchAllocationService, BatchPricingService, CommissionStatsService
- 新增异步任务：统计更新、定时同步、周期归档
- 测试覆盖：批量操作集成测试、梯度佣金 CRUD 清理验证

影响：
- API 变更：删除 4 个梯度 CRUD 接口（POST/GET/PUT/DELETE /:id/tiers）
- API 新增：批量分配、批量调价接口
- 数据模型：重构 shop_series_allocation 表结构
- 性能优化：批量操作使用 CreateInBatches，统计使用 Redis 缓存

相关文档：
- openspec/changes/archive/2026-01-28-refactor-shop-package-allocation/
- openspec/specs/agent-available-packages/
- openspec/specs/allocation-config-versioning/
- 等 8 个新 capability specs

2026-01-28 17:11:55 +08:00

2.6 KiB

Raw Blame History

Why

Phase 1 完成了套餐基础模块，但代理商还不能分销套餐。需要实现代理套餐分配机制：上级代理为下级分配套餐系列，设置成本价（通过加价模式计算），并支持梯度佣金配置。代理只能看到和销售被分配的套餐。

What Changes

新增模型：

ShopSeriesAllocation：店铺套餐系列分配，记录哪个店铺被分配了哪个套餐系列、成本价加价模式、一次性佣金触发配置
ShopSeriesCommissionTier：梯度佣金配置，基于销量/销售额设置不同的阶梯奖励金额
ShopPackageAllocation：店铺单套餐分配（可选），用于覆盖系列级别的成本价设置

新增 API：

为下级店铺分配套餐系列（设置加价模式）
查询店铺的套餐系列分配列表
更新/删除套餐系列分配
配置梯度佣金（按系列）
为下级店铺分配单个套餐（覆盖成本价）
代理查看自己可销售的套餐列表（含成本价）

业务规则：

加价模式：固定金额加价或百分比加价（基于上级成本价）
代理给下级设置的成本价 ≥ 自己的成本价（不可亏本）
梯度佣金支持时间范围配置（月度/季度/年度/自定义）
套餐系列分配是主要方式，单套餐分配用于特殊覆盖

Capabilities

New Capabilities

shop-series-allocation: 店铺套餐系列分配 - 为下级店铺分配套餐系列，设置加价模式计算成本价
shop-commission-tier: 梯度佣金配置 - 基于销量/销售额配置不同档位的一次性佣金
shop-package-allocation: 店铺单套餐分配 - 可选的单套餐级别成本价覆盖
agent-available-packages: 代理可售套餐查询 - 代理查看自己被分配的套餐及成本价

Modified Capabilities

Impact

代码影响：

internal/model/ - 新增 3 个模型文件
migrations/ - 创建 3 个新表
internal/handler/admin/ - 新增分配管理 Handler
internal/service/ - 新增分配管理 Service
internal/store/postgres/ - 新增 3 个 Store
internal/model/dto/ - 新增请求/响应 DTO
internal/bootstrap/ - 注册新组件
internal/router/ - 注册新路由

API 影响：

新增 /api/admin/shop-series-allocations/* 路由组
新增 /api/admin/shop-package-allocations/* 路由组
新增 /api/admin/my-packages 代理可售套餐查询

数据库影响：

新增表：tb_shop_series_allocation, tb_shop_series_commission_tier, tb_shop_package_allocation

依赖关系：

依赖 Phase 1（add-package-module）完成
Phase 3（卡/设备关联）依赖本期

2.6 KiB Raw Blame History Unescape Escape

Why