191 lines
5.3 KiB
Markdown
191 lines
5.3 KiB
Markdown
# 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
|
|
|
|
**决策**: 分层验证 + 条件验证
|
|
|
|
**验证规则**:
|
|
1. 基础返佣配置:
|
|
- mode: 必选
|
|
- value: 必填,>= 0
|
|
|
|
2. 梯度返佣配置(当启用时):
|
|
- period_type: 必选
|
|
- tier_type: 必选
|
|
- tiers: 至少一个档位
|
|
- 每个档位:
|
|
- threshold: 必填,> 0
|
|
- mode: 必选
|
|
- value: 必填,> 0
|
|
- 档位阈值必须递增
|
|
|
|
**实现方式**:
|
|
- 使用 Element Plus 的表单验证
|
|
- 自定义validator处理档位阈值递增验证
|
|
- 使用 computed 动态生成验证规则
|
|
|
|
### 4. API Response Handling
|
|
|
|
**决策**: 统一使用 `list` 字段名,添加适配层
|
|
|
|
**理由**:
|
|
- 后端统一规范使用 `list` 而非 `items`
|
|
- 添加 `total_pages` 字段提供更完整的分页信息
|
|
- 保持前端代码与后端规范一致
|
|
|
|
**迁移策略**:
|
|
```typescript
|
|
// 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: 准备阶段
|
|
1. 与后端确认API变更细节和时间表
|
|
2. 在开发环境实现前端变更
|
|
3. 与后端在测试环境联调
|
|
|
|
### Phase 2: 测试阶段
|
|
1. 功能测试: 创建、编辑、删除、列表展示
|
|
2. 集成测试: 与后端API集成
|
|
3. 用户验收测试: 业务人员验证
|
|
|
|
### Phase 3: 部署阶段
|
|
1. 准备回退方案
|
|
2. 与后端协调部署窗口
|
|
3. 同步部署前后端
|
|
4. 验证生产环境功能
|
|
|
|
### Phase 4: 监控阶段
|
|
1. 监控API错误率
|
|
2. 收集用户反馈
|
|
3. 修复遗留问题
|
|
|
|
### Rollback Plan
|
|
|
|
如果部署后发现严重问题:
|
|
1. 前端回退到上一版本
|
|
2. 后端回退API(如果可能)
|
|
3. 通知用户暂时不可用
|
|
4. 修复问题后重新部署
|
|
|
|
## Open Questions
|
|
|
|
1. **Q**: 梯度返佣的档位数量是否有上限?
|
|
- **A**: 待后端确认,前端可以先不限制或设置合理上限(如10个)
|
|
|
|
2. **Q**: 返佣值的单位和精度如何处理?
|
|
- **A**: 固定金额使用"分"为单位,百分比使用千分比(如200=20%),待后端确认
|
|
|
|
3. **Q**: 是否需要在列表页显示梯度返佣信息?
|
|
- **A**: 暂时只显示基础返佣,梯度信息在详情或编辑时查看
|
|
|
|
4. **Q**: 旧数据如何映射到新模型?
|
|
- **A**: 待后端提供迁移方案,前端需要能够正确显示迁移后的数据
|