huang
b52cb9a078
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m27s
- OneTimeCommissionTierDTO 补充 operator 字段映射 - GrantCommissionTierItem 补充 dimension/stat_scope 字段（从全局配置合并） - 系列授权列表/详情补充强充锁定状态和强充金额的有效值计算 - 同步 OpenSpec 主规范并归档变更文档
48 lines
4.1 KiB
Markdown
48 lines
4.1 KiB
Markdown
## Why
|
||
|
||
`refactor-agent-series-grant` 变更遗留了两处实现漏洞，加上前端对接时发现的第三处 Bug，共三个问题：
|
||
|
||
1. 套餐系列管理 API 的梯度档位 DTO 缺少 `operator` 字段，导致无法通过接口设置/查看比较运算符。
|
||
2. 代理系列授权的梯度响应缺少 `dimension`（销售量/销售额）和 `stat_scope`（统计范围）字段，前端完全无法理解阈值的业务含义。
|
||
3. 系列授权列表和详情响应中，当套餐系列配置锁定了强充（`enable_force_recharge=true` 或 `trigger_type=first_recharge`）时，`force_recharge_enabled` 仍返回 `false`（分配记录自身的值），未反映有效状态；列表还缺少 `force_recharge_locked` 和 `force_recharge_amount` 字段。
|
||
|
||
## What Changes
|
||
|
||
- **修复** `OneTimeCommissionTierDTO`（`package_series_dto.go`）：新增 `Operator string` 字段，支持创建/更新套餐系列时传入并保存梯度阶梯的比较运算符（`>`、`>=`、`<`、`<=`）
|
||
- **修复** `package_series/service.go`：`dtoToModelConfig()` 新增 `Operator` 字段映射；`modelToDTO()` 新增 `Operator` 字段回填，使 `PackageSeriesResponse` 能正确返回 `operator`
|
||
- **修复** `GrantCommissionTierItem`（`shop_series_grant_dto.go`）：新增 `Dimension string` 和 `StatScope string` 字段
|
||
- **修复** `shop_series_grant/service.go`：`buildGrantResponse()` 合并全局 PackageSeries tiers 时，除 `Operator` 外同步合并 `Dimension` 和 `StatScope`
|
||
|
||
- **修复** `ShopSeriesGrantListItem`（`shop_series_grant_dto.go`）：新增 `ForceRechargeLocked bool` 和 `ForceRechargeAmount int64` 字段
|
||
- **修复** `shop_series_grant/service.go`：列表构建时计算 `forceRechargeLocked`，当锁定时 `ForceRechargeEnabled=true`、`ForceRechargeAmount=config.ForceAmount`；详情 `buildGrantResponse()` 同步修正 `ForceRechargeEnabled` 和 `ForceRechargeAmount` 有效状态逻辑
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
（无新增 Capability）
|
||
|
||
### Modified Capabilities
|
||
|
||
- `package-series-management`：梯度档位配置（`one_time_commission_config.tiers`）支持通过 API 读写 `operator` 字段（创建时传入、查询时返回）
|
||
- `agent-series-grant`：`commission_tiers` 响应中补充展示 `dimension`（`sales_count` / `sales_amount`）和 `stat_scope`（`self` / `self_and_sub`），这两个字段来自 PackageSeries 全局配置，对代理只读
|
||
- `agent-series-grant`：系列授权列表（`GET /api/admin/shop-series-grants`）新增 `force_recharge_locked` 和 `force_recharge_amount` 字段；列表和详情中 `force_recharge_enabled` 反映有效状态（锁定时为 `true`）
|
||
|
||
## Impact
|
||
|
||
**受影响的代码**
|
||
- `internal/model/dto/package_series_dto.go`：`OneTimeCommissionTierDTO` 新增 `Operator` 字段
|
||
- `internal/service/package_series/service.go`：`dtoToModelConfig()`、`modelToDTO()` 处理 `Operator`
|
||
- `internal/model/dto/shop_series_grant_dto.go`：`GrantCommissionTierItem` 新增 `Dimension`、`StatScope` 字段
|
||
- `internal/service/shop_series_grant/service.go`：`buildGrantResponse()` 合并 `Dimension`、`StatScope`
|
||
- `internal/model/dto/shop_series_grant_dto.go`：`ShopSeriesGrantListItem` 新增 `ForceRechargeLocked`、`ForceRechargeAmount` 字段
|
||
|
||
**受影响的 API**
|
||
- `POST/PUT /api/admin/package-series`：请求体中梯度档位可传 `operator`；响应中梯度档位包含 `operator`
|
||
- `GET /api/admin/package-series/:id`：同上
|
||
- `GET /api/admin/shop-series-grants/:id`：响应中 `commission_tiers` 新增 `dimension`、`stat_scope` 字段
|
||
- `POST /api/admin/shop-series-grants`：同上（Create 响应）
|
||
- `PUT /api/admin/shop-series-grants/:id`：同上（Update 响应）
|
||
- `GET /api/admin/shop-series-grants`（列表）：新增 `force_recharge_locked`、`force_recharge_amount` 字段；`force_recharge_enabled` 反映有效状态
|
||
|
||
**无数据库迁移**：仅涉及 DTO 和 Service 层代码，不改动数据库结构和 Model 层（`OneTimeCommissionTier` model 已在上次变更中添加 `Operator` 字段；`tb_shop_series_allocation` 表结构已有 `enable_force_recharge`/`force_recharge_amount` 字段，无需迁移）
|