# 梯度佣金独立 CRUD 接口清理总结

## 清理时间
2026-01-28

## 清理原因
在新的设计模型中，梯度佣金应该作为**系列分配的配置项**，在创建/更新分配时一起配置，而不是独立的 CRUD 资源。

## 已删除的接口

### 1. 路由层（已删除）
**文件**: `internal/routes/shop_series_allocation.go`

| 方法 | 路径 | Handler 方法 | 功能 |
|------|------|-------------|------|
| POST | `/:id/tiers` | `AddTier` | 创建梯度佣金 |
| PUT | `/:id/tiers/:tid` | `UpdateTier` | 更新梯度佣金 |
| DELETE | `/:id/tiers/:tid` | `DeleteTier` | 删除梯度佣金 |
| GET | `/:id/tiers` | `ListTiers` | 查询梯度佣金列表 |

### 2. Handler 层（已删除）
**文件**: `internal/handler/admin/shop_series_allocation.go`

- `AddTier(c *fiber.Ctx) error`
- `UpdateTier(c *fiber.Ctx) error`
- `DeleteTier(c *fiber.Ctx) error`
- `ListTiers(c *fiber.Ctx) error`

**原位置**: 第 114-187 行（共 74 行代码）

### 3. Service 层（已删除）
**文件**: `internal/service/shop_series_allocation/service.go`

- `AddTier(ctx, allocationID, req) (*dto.CommissionTierResponse, error)`
- `UpdateTier(ctx, allocationID, tierID, req) (*dto.CommissionTierResponse, error)`
- `DeleteTier(ctx, allocationID, tierID) error`
- `ListTiers(ctx, allocationID) ([]*dto.CommissionTierResponse, error)`
- `buildTierResponse(t *model.ShopSeriesCommissionTier) *dto.CommissionTierResponse`

**原位置**: 第 319-516 行（共 198 行代码）

### 4. DTO 层（已删除）
**文件**: `internal/model/dto/shop_series_allocation.go`

以下 DTO 仅用于独立 Tier CRUD，已全部删除：

- `CreateCommissionTierRequest` - 创建梯度佣金请求
- `UpdateCommissionTierRequest` - 更新梯度佣金请求
- `CommissionTierResponse` - 梯度佣金响应
- `CreateCommissionTierParams` - 创建梯度佣金聚合参数
- `UpdateCommissionTierParams` - 更新梯度佣金聚合参数
- `DeleteCommissionTierParams` - 删除梯度佣金聚合参数
- `AllocationIDReq` - 分配ID路径参数
- `TierIDReq` - 梯度ID路径参数
- `CommissionTierListResult` - 梯度佣金列表结果
- `TierIDParams` - 梯度ID路径参数组合

**原位置**: 第 90-165 行（共 76 行代码）

**保留的 DTO**: `TierEntry` - 梯度档位条目（仍然用于 `TierCommissionConfig.Tiers` 字段）

## 正确的使用方式

### 创建分配时配置梯度佣金
```json
POST /api/admin/shop-series-allocations
{
  "shop_id": 1,
  "series_id": 1,
  "base_commission": {"mode": "fixed", "value": 1000},
  "enable_tier_commission": true,
  "tier_config": {
    "period_type": "monthly",
    "tier_type": "sales_count",
    "tiers": [
      {"threshold": 100, "mode": "fixed", "value": 1500},
      {"threshold": 200, "mode": "fixed", "value": 2000}
    ]
  }
}
```

### 更新分配时修改梯度佣金
```json
PUT /api/admin/shop-series-allocations/:id
{
  "enable_tier_commission": true,
  "tier_config": {
    "period_type": "quarterly",
    "tier_type": "sales_amount",
    "tiers": [
      {"threshold": 10000, "mode": "percent", "value": 100},
      {"threshold": 50000, "mode": "percent", "value": 150}
    ]
  }
}
```

## 验证结果

### 1. 编译验证
```bash
go build ./...
```
✅ 编译通过

### 2. OpenAPI 文档验证
```bash
go run cmd/gendocs/main.go
grep -A5 "/api/admin/shop-series-allocations/{id}/tiers" docs/admin-openapi.yaml
```
✅ 已移除 4 个接口（POST/PUT/DELETE/GET）

### 3. 代码清理统计
- **删除的方法数**: 9 个（4 Handler + 4 Service + 1 辅助方法）
- **删除的 DTO 数**: 10 个
- **删除的代码行数**: 约 348 行

## 影响范围

### ✅ 无影响区域
1. **分配主接口**: Create/Update/Delete/List/Get 完全正常
2. **配置版本管理**: 历史配置版本功能不受影响
3. **Store 层**: `ShopSeriesCommissionTierStore` 保留（用于分佣计算时查询）
4. **Model 层**: `ShopSeriesCommissionTier` 模型保留（数据库表继续使用）
5. **测试**: 现有测试通过（无任何测试依赖这些接口）

### 🔍 需要注意的地方
1. **前端**: 如果前端有使用这 4 个接口，需要迁移到新的嵌套配置方式
2. **API 文档**: 需要更新 API 使用文档，说明正确的梯度佣金配置方式

## 设计优势

### 旧设计（已移除）
```
1. POST /allocations → 创建分配
2. POST /allocations/:id/tiers → 添加梯度1
3. POST /allocations/:id/tiers → 添加梯度2
4. PUT /allocations/:id/tiers/:tid → 修改梯度1
```
❌ 多次请求、配置分散、难以原子操作

### 新设计（当前）
```
1. POST /allocations → 创建分配 + 配置梯度（一次请求）
2. PUT /allocations/:id → 更新分配 + 修改梯度（原子操作）
```
✅ 单次请求、配置集中、原子更新、符合业务逻辑

## 后续建议

1. **更新 API 文档**: 在 `docs/` 目录添加梯度佣金配置示例
2. **前端迁移**: 如果前端有使用旧接口，需要修改为新的嵌套配置方式
3. **测试覆盖**: 为新的嵌套配置方式编写集成测试
4. **代码审查**: 确认没有其他地方引用已删除的方法

## 清理完成时间
2026-01-28 19:16:00

---

**变更记录**:
- 2026-01-28: 完成梯度佣金独立 CRUD 接口清理
- 相关项目: `refactor-shop-package-allocation`
- 完成度: 88% → 89%（新增一项清理任务完成）
