junhong_cmp_fiber/openspec/changes/archive/2026-01-27-add-package-module/proposal.md at 79c061b6fa35db35b78311113251cd10d280a448

csxj2026/junhong_cmp_fiber

Files

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

Details

- 新增套餐系列管理 (CRUD + 状态切换)
- 新增套餐管理 (CRUD + 启用/禁用 + 上架/下架双状态)
- 清理 8 个废弃分佣模型及对应数据库表
- Package 模型新增建议成本价、建议售价、上架状态字段
- 完整的 Store/Service/Handler 三层实现
- 包含单元测试和集成测试
- 归档 add-package-module change
- 新增多个 OpenSpec changes (订单支付、店铺套餐分配、一次性分佣、卡设备系列绑定)

2026-01-27 19:55:47 +08:00

3.1 KiB

Raw Blame History

Why

当前分佣模型过于复杂（包含冻结/解冻审批、组合分佣、号卡结算等），而流量卡业务只需要简单的一次性佣金。现有的 AgentPackageAllocation 模型也不支持套餐系列级别的分配和梯度佣金配置。需要清理废弃模型，调整 Package 模型支持建议价格和上架状态，并提供完整的套餐/套餐系列 CRUD API。

What Changes

模型清理（commission.go）：

BREAKING 删除 AgentHierarchy - 代理层级通过 Shop.parent_id 维护
BREAKING 删除 CommissionRule - 过于复杂，后续用新模型替代
BREAKING 删除 CommissionLadder - 后续用 ShopSeriesCommissionTier 替代
BREAKING 删除 CommissionCombinedCondition - 流量卡不需要组合分佣
BREAKING 删除 CommissionApproval - 不需要冻结/解冻审批流程
BREAKING 删除 CommissionTemplate - 简化后不需要模板
BREAKING 删除 CarrierSettlement - 号卡专用，本期不做

模型清理（package.go）：

BREAKING 删除 AgentPackageAllocation - 用新的分配模型替代

Package 模型调整：

新增 suggested_cost_price 字段（建议成本价，分为单位）
新增 suggested_retail_price 字段（建议售价，分为单位）
新增 shelf_status 字段（上架状态：1-上架 2-下架）

新增 API：

套餐系列 CRUD（创建、更新、删除、列表、详情、启用/禁用）
套餐 CRUD（创建、更新、删除、列表、详情、启用/禁用、上架/下架）

Capabilities

New Capabilities

package-series-management: 套餐系列管理 - 创建/更新/删除/列表/详情，支持启用/禁用状态切换
package-management: 套餐管理 - 创建/更新/删除/列表/详情，支持启用/禁用和上架/下架双状态管理

Modified Capabilities

Impact

代码影响：

internal/model/commission.go - 删除 7 个模型
internal/model/package.go - 删除 1 个模型，修改 Package 模型
migrations/ - 需要创建迁移文件删除废弃表、修改 package 表
internal/handler/admin/ - 新增套餐系列和套餐管理 Handler
internal/service/ - 新增套餐系列和套餐管理 Service
internal/store/postgres/ - 新增套餐系列和套餐 Store
internal/model/dto/ - 新增请求/响应 DTO
internal/bootstrap/ - 注册新的 Store/Service/Handler
internal/router/ - 注册新的 API 路由
cmd/api/docs.go 和 cmd/gendocs/main.go - 更新文档生成器

API 影响：

新增 /api/admin/package-series/* 路由组
新增 /api/admin/packages/* 路由组

数据库影响：

删除表：tb_agent_hierarchy, tb_commission_rule, tb_commission_ladder, tb_commission_combined_condition, tb_commission_approval, tb_commission_template, tb_carrier_settlement, tb_agent_package_allocation
修改表：tb_package 新增 3 个字段

依赖关系：

本期不涉及外部依赖变更
后续 Phase 2（代理套餐分配）依赖本期完成

3.1 KiB Raw Blame History Unescape Escape

Why