junhong_cmp_fiber/openspec/changes/archive/2026-03-05-fix-tiered-commission-tier-fields/proposal.md at b52cb9a07890c2ad6aa5417ae96e49753e388249

csxj2026/junhong_cmp_fiber

Files

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

Details

- OneTimeCommissionTierDTO 补充 operator 字段映射
- GrantCommissionTierItem 补充 dimension/stat_scope 字段（从全局配置合并）
- 系列授权列表/详情补充强充锁定状态和强充金额的有效值计算
- 同步 OpenSpec 主规范并归档变更文档

2026-03-05 11:23:28 +08:00

4.1 KiB

Raw Blame History

Why

refactor-agent-series-grant 变更遗留了两处实现漏洞，加上前端对接时发现的第三处 Bug，共三个问题：

套餐系列管理 API 的梯度档位 DTO 缺少 operator 字段，导致无法通过接口设置/查看比较运算符。
代理系列授权的梯度响应缺少 dimension（销售量/销售额）和 stat_scope（统计范围）字段，前端完全无法理解阈值的业务含义。
系列授权列表和详情响应中，当套餐系列配置锁定了强充（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 字段，无需迁移）

4.1 KiB Raw Blame History Unescape Escape

Why