5.3 KiB
5.3 KiB
Design: 套餐系列分配佣金系统重构
Context
当前系统使用简单的定价模式(pricing_mode/pricing_value)和一次性佣金(one_time_commission_*)来管理套餐系列分配。随着业务发展,需要更复杂的佣金系统:
- 支持基础返佣(固定金额或百分比)
- 支持梯度返佣(根据销量或销售额分档返佣)
- 更清晰的数据模型和API接口
背景约束:
- 前后端需要同步部署(Breaking Change)
- 需要数据迁移方案
- 影响现有的套餐系列分配功能
Goals / Non-Goals
Goals:
- 实现新的佣金配置模型,支持基础返佣和梯度返佣
- 提供清晰的UI界面让用户配置复杂的返佣规则
- 保证数据一致性和类型安全
- 提供良好的用户体验(表单验证、错误提示)
Non-Goals:
- 不处理历史数据的完整性验证(由后端负责)
- 不实现佣金计算逻辑(由后端负责)
- 不处理佣金结算流程(属于其他模块)
Decisions
1. Data Model Design
决策: 采用嵌套对象结构表示佣金配置
理由:
base_commission: { mode, value }- 清晰表达基础返佣的两个维度tier_config: { period_type, tier_type, tiers[] }- 梯度配置与基础配置分离,可选性强tiers: [{ threshold, mode, value }]- 每个档位都有独立的返佣模式和值
替代方案考虑:
- ❌ 平铺所有字段 - 会导致字段过多,语义不清晰
- ❌ 使用JSON字符串存储配置 - 失去类型安全,不利于表单编辑
2. UI Design Pattern
决策: 使用渐进式表单设计
表单结构:
1. 基础返佣配置 (必填)
- 返佣模式: 单选 (固定金额/百分比)
- 返佣值: 数字输入
2. 梯度返佣设置 (可选)
- 启用开关: 是/否
- [如果启用]:
- 周期类型: 下拉 (月度/季度/年度)
- 梯度类型: 下拉 (销量/销售额)
- 档位列表: 动态表单
* 阈值
* 返佣模式
* 返佣值
* [添加]/[删除] 按钮
理由:
- 渐进式设计降低初始复杂度
- 只有启用梯度返佣时才显示相关配置
- 动态档位列表提供灵活性
替代方案考虑:
- ❌ 全部平铺展示 - 对不需要梯度返佣的用户造成困扰
- ❌ 使用向导模式 - 增加操作步骤,不适合编辑场景
3. Form Validation Strategy
决策: 分层验证 + 条件验证
验证规则:
-
基础返佣配置:
- mode: 必选
- value: 必填,>= 0
-
梯度返佣配置(当启用时):
- period_type: 必选
- tier_type: 必选
- tiers: 至少一个档位
- 每个档位:
- threshold: 必填,> 0
- mode: 必选
- value: 必填,> 0
- 档位阈值必须递增
实现方式:
- 使用 Element Plus 的表单验证
- 自定义validator处理档位阈值递增验证
- 使用 computed 动态生成验证规则
4. API Response Handling
决策: 统一使用 list 字段名,添加适配层
理由:
- 后端统一规范使用
list而非items - 添加
total_pages字段提供更完整的分页信息 - 保持前端代码与后端规范一致
迁移策略:
// Before
const res = await getShopSeriesAllocations(params)
allocationList.value = res.data.items || []
// After
const res = await getShopSeriesAllocations(params)
allocationList.value = res.data.list || []
Risks / Trade-offs
Risk 1: Breaking Change导致部署协调困难
风险: 前后端必须同时部署,否则会出现接口不兼容
缓解措施:
- 与后端团队协调部署窗口
- 准备回退方案(前端代码分支)
- 在测试环境充分验证
Risk 2: 复杂表单导致用户体验问题
风险: 梯度返佣配置较复杂,用户可能不理解
缓解措施:
- 提供清晰的字段说明
- 添加示例或帮助文档链接
- 使用默认值简化初次配置
Risk 3: 数据迁移可能失败
风险: 旧数据无法完全转换为新模型
缓解措施:
- 要求后端提供数据迁移脚本和验证
- 在迁移后检查数据完整性
- 保留旧数据备份
Migration Plan
Phase 1: 准备阶段
- 与后端确认API变更细节和时间表
- 在开发环境实现前端变更
- 与后端在测试环境联调
Phase 2: 测试阶段
- 功能测试: 创建、编辑、删除、列表展示
- 集成测试: 与后端API集成
- 用户验收测试: 业务人员验证
Phase 3: 部署阶段
- 准备回退方案
- 与后端协调部署窗口
- 同步部署前后端
- 验证生产环境功能
Phase 4: 监控阶段
- 监控API错误率
- 收集用户反馈
- 修复遗留问题
Rollback Plan
如果部署后发现严重问题:
- 前端回退到上一版本
- 后端回退API(如果可能)
- 通知用户暂时不可用
- 修复问题后重新部署
Open Questions
-
Q: 梯度返佣的档位数量是否有上限?
- A: 待后端确认,前端可以先不限制或设置合理上限(如10个)
-
Q: 返佣值的单位和精度如何处理?
- A: 固定金额使用"分"为单位,百分比使用千分比(如200=20%),待后端确认
-
Q: 是否需要在列表页显示梯度返佣信息?
- A: 暂时只显示基础返佣,梯度信息在详情或编辑时查看
-
Q: 旧数据如何映射到新模型?
- A: 待后端提供迁移方案,前端需要能够正确显示迁移后的数据