feat: 实现套餐管理模块，包含套餐系列、双状态管理、废弃模型清理

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

openspec/changes/archive/2026-01-27-add-package-module/tasks.md

@@ -0,0 +1,128 @@
+## 1. 模型清理
+
+- [x] 1.1 删除 `internal/model/commission.go` 中的废弃模型（AgentHierarchy, CommissionRule, CommissionLadder, CommissionCombinedCondition, CommissionApproval, CommissionTemplate, CarrierSettlement）
+- [x] 1.2 删除 `internal/model/package.go` 中的 `AgentPackageAllocation` 模型
+- [x] 1.3 执行 `go build ./...` 确认无编译错误，如有引用则同步清理
+
+## 2. Package 模型调整
+
+- [x] 2.1 在 `internal/model/package.go` 的 Package 结构体中新增 `suggested_cost_price` 字段（bigint, 默认 0, 注释：建议成本价）
+- [x] 2.2 在 Package 结构体中新增 `suggested_retail_price` 字段（bigint, 默认 0, 注释：建议售价）
+- [x] 2.3 在 Package 结构体中新增 `shelf_status` 字段（int, 默认 2, 注释：上架状态 1-上架 2-下架）
+
+## 3. 数据库迁移
+
+- [x] 3.1 创建迁移文件，UP 脚本删除 8 个废弃表：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
+- [x] 3.2 在迁移 UP 脚本中添加 tb_package 表的 3 个新字段
+- [x] 3.3 编写迁移 DOWN 脚本（重建表结构、删除新字段）
+- [x] 3.4 本地执行迁移验证
+
+## 4. 套餐系列 DTO
+
+- [x] 4.1 创建 `internal/model/dto/package_series.go`，定义 CreatePackageSeriesRequest（series_code 必填, series_name 必填, description 可选）
+- [x] 4.2 定义 UpdatePackageSeriesRequest（series_name, description）
+- [x] 4.3 定义 PackageSeriesListRequest（page, page_size, series_name 模糊, status 筛选）
+- [x] 4.4 定义 UpdatePackageSeriesStatusRequest（status 必填）
+- [x] 4.5 定义 PackageSeriesResponse 响应结构
+
+## 5. 套餐系列 Store
+
+- [x] 5.1 创建 `internal/store/postgres/package_series_store.go`，实现 Create 方法
+- [x] 5.2 实现 GetByID 方法
+- [x] 5.3 实现 GetByCode 方法（用于编码唯一性检查）
+- [x] 5.4 实现 Update 方法
+- [x] 5.5 实现 Delete 方法（软删除）
+- [x] 5.6 实现 List 方法（支持分页、名称模糊搜索、状态筛选）
+- [x] 5.7 实现 UpdateStatus 方法
+
+## 6. 套餐系列 Service
+
+- [x] 6.1 创建 `internal/service/package_series/service.go`，实现 Create 方法（检查编码唯一性）
+- [x] 6.2 实现 Get 方法
+- [x] 6.3 实现 Update 方法（忽略编码修改）
+- [x] 6.4 实现 Delete 方法
+- [x] 6.5 实现 List 方法
+- [x] 6.6 实现 UpdateStatus 方法
+
+## 7. 套餐系列 Handler
+
+- [x] 7.1 创建 `internal/handler/admin/package_series.go`，实现 Create 接口
+- [x] 7.2 实现 Get 接口
+- [x] 7.3 实现 Update 接口
+- [x] 7.4 实现 Delete 接口
+- [x] 7.5 实现 List 接口
+- [x] 7.6 实现 UpdateStatus 接口
+
+## 8. 套餐 DTO
+
+- [x] 8.1 创建 `internal/model/dto/package.go`，定义 CreatePackageRequest（package_code 必填, package_name 必填, series_id, package_type 必填, duration_months 必填, data_type, real_data_mb, virtual_data_mb, data_amount_mb, price 必填, suggested_cost_price, suggested_retail_price）
+- [x] 8.2 定义 UpdatePackageRequest（除 package_code 外的字段）
+- [x] 8.3 定义 PackageListRequest（page, page_size, package_name 模糊, series_id, status, shelf_status, package_type）
+- [x] 8.4 定义 UpdatePackageStatusRequest（status 必填）
+- [x] 8.5 定义 UpdatePackageShelfStatusRequest（shelf_status 必填）
+- [x] 8.6 定义 PackageResponse 响应结构（包含新增的 3 个字段）
+
+## 9. 套餐 Store
+
+- [x] 9.1 创建 `internal/store/postgres/package_store.go`，实现 Create 方法
+- [x] 9.2 实现 GetByID 方法
+- [x] 9.3 实现 GetByCode 方法
+- [x] 9.4 实现 Update 方法
+- [x] 9.5 实现 Delete 方法
+- [x] 9.6 实现 List 方法（支持分页、名称模糊、系列筛选、状态筛选、上架状态筛选、类型筛选）
+- [x] 9.7 实现 UpdateStatus 方法
+- [x] 9.8 实现 UpdateShelfStatus 方法
+
+## 10. 套餐 Service
+
+- [x] 10.1 创建 `internal/service/package/service.go`，实现 Create 方法（检查编码唯一性、验证系列存在）
+- [x] 10.2 实现 Get 方法
+- [x] 10.3 实现 Update 方法（忽略编码修改、验证系列存在）
+- [x] 10.4 实现 Delete 方法
+- [x] 10.5 实现 List 方法
+- [x] 10.6 实现 UpdateStatus 方法（禁用时强制下架）
+- [x] 10.7 实现 UpdateShelfStatus 方法（检查启用状态才能上架）
+
+## 11. 套餐 Handler
+
+- [x] 11.1 创建 `internal/handler/admin/package.go`，实现 Create 接口
+- [x] 11.2 实现 Get 接口
+- [x] 11.3 实现 Update 接口
+- [x] 11.4 实现 Delete 接口
+- [x] 11.5 实现 List 接口
+- [x] 11.6 实现 UpdateStatus 接口
+- [x] 11.7 实现 UpdateShelfStatus 接口
+
+## 12. Bootstrap 注册
+
+- [x] 12.1 在 `internal/bootstrap/stores.go` 中注册 PackageSeriesStore 和 PackageStore
+- [x] 12.2 在 `internal/bootstrap/services.go` 中注册 PackageSeriesService 和 PackageService
+- [x] 12.3 在 `internal/bootstrap/handlers.go` 中注册 PackageSeriesHandler 和 PackageHandler
+
+## 13. 路由注册
+
+- [x] 13.1 在 `internal/router/` 中注册套餐系列路由组 `/api/admin/package-series`（POST, GET, GET/:id, PUT/:id, DELETE/:id, PATCH/:id/status）
+- [x] 13.2 注册套餐路由组 `/api/admin/packages`（POST, GET, GET/:id, PUT/:id, DELETE/:id, PATCH/:id/status, PATCH/:id/shelf）
+
+## 14. 文档生成器更新
+
+- [x] 14.1 在 `cmd/api/docs.go` 中添加 PackageSeriesHandler 和 PackageHandler
+- [x] 14.2 在 `cmd/gendocs/main.go` 中添加 PackageSeriesHandler 和 PackageHandler
+- [x] 14.3 执行 `go run cmd/gendocs/main.go` 生成 OpenAPI 文档
+
+## 15. 测试
+
+- [x] 15.1 为 PackageSeriesStore 编写单元测试
+- [x] 15.2 为 PackageStore 编写单元测试
+- [x] 15.3 为 PackageSeriesService 编写单元测试（覆盖编码唯一性检查）
+- [x] 15.4 为 PackageService 编写单元测试（覆盖双状态逻辑）
+- [x] 15.5 编写套餐系列 API 集成测试
+- [x] 15.6 编写套餐 API 集成测试（覆盖禁用强制下架、禁用不能上架场景）
+- [x] 15.7 执行 `go test ./...` 确认所有测试通过
+
+## 16. 最终验证
+
+- [x] 16.1 执行 `go build ./...` 确认编译通过
+- [x] 16.2 执行 `go vet ./...` 检查代码质量
+- [x] 16.3 启动服务，手动测试 API 接口
+- [x] 16.4 确认 OpenAPI 文档正确生成