# Change: 套餐管理系统实现

## Why

根据业务需求文档（docs/套餐.md），需要实现完整的套餐管理系统，包括4个核心模块：

1. **套餐系列管理** - 管理套餐的分类和组织
2. **套餐管理** - 管理具体的套餐产品（流量、价格、时长等）
3. **代理可售套餐** - 代理商查看被分配的可售套餐及定价
4. **单套餐分配** - 为代理商分配特定套餐并设置成本价

当前系统虽然有套餐相关的类型定义（src/types/api/package.ts）和部分页面骨架，但缺少完整的 API 对接和业务逻辑实现。此变更将实现完整的套餐管理能力。

## What Changes

### 1. API 层实现

采用模块化设计，拆分为 4 个独立的 API 服务文件：

- **新增**: `src/api/modules/packageSeries.ts` - 套餐系列 API 服务
  - 套餐系列列表查询（分页、筛选）
  - 创建套餐系列
  - 获取套餐系列详情
  - 更新套餐系列
  - 删除套餐系列
  - 更新套餐系列状态

- **新增**: `src/api/modules/package.ts` - 套餐管理 API 服务
  - 套餐列表查询（分页、多条件筛选）
  - 创建套餐
  - 获取套餐详情
  - 更新套餐
  - 删除套餐
  - 更新套餐状态
  - 更新套餐上架状态
  - 获取系列下拉选项（用于表单选择）

- **新增**: `src/api/modules/myPackage.ts` - 代理可售套餐 API 服务
  - 我的可售套餐列表查询
  - 获取可售套餐详情
  - 我的被分配系列列表

- **新增**: `src/api/modules/shopPackageAllocation.ts` - 单套餐分配 API 服务
  - 单套餐分配列表查询
  - 创建单套餐分配
  - 获取单套餐分配详情
  - 更新单套餐分配
  - 删除单套餐分配
  - 更新单套餐分配状态

- **修改**: `src/api/modules/index.ts` - 导出新增的服务模块
  - 导出 PackageSeriesService
  - 导出 PackageService
  - 导出 MyPackageService
  - 导出 ShopPackageAllocationService

### 2. 类型定义增强

- **新增**: `src/types/api/packageManagement.ts` - 完整的套餐管理类型定义
  - 匹配文档的 API 字段（下划线命名）
  - 包含所有请求/响应类型
  - 包含分页结果类型

### 3. 页面实现

**套餐系列管理** (`src/views/package-management/package-series/index.vue`)
- 列表展示（支持名称搜索、状态筛选）
- 新增/编辑套餐系列
- 删除套餐系列
- 状态开关（启用/禁用）

**套餐管理** (`src/views/package-management/package-list/index.vue`)
- 列表展示（支持多条件筛选：名称、系列、状态、上架状态、套餐类型）
- 新增/编辑套餐
- 删除套餐
- 状态开关（启用/禁用）
- 上架状态开关（上架/下架）

**代理可售套餐** (`src/views/package-management/my-packages/index.vue`)
- 查看被分配的套餐列表（支持系列、类型筛选）
- 查看套餐详情（成本价、建议售价、利润空间等）
- 查看被分配系列列表

**单套餐分配** (`src/views/package-management/package-assign/index.vue`)
- 分配列表（支持店铺、套餐、状态筛选）
- 创建分配（选择套餐、店铺、设置成本价）
- 编辑分配（修改成本价）
- 删除分配
- 状态管理（启用/禁用）

### 4. 常量配置

- **新增**: `src/config/constants/package.ts` - 套餐相关常量
  - 套餐类型枚举（formal/addon）
  - 流量类型枚举（real/virtual）
  - 上架状态枚举（1:上架, 2:下架）
  - 定价模式枚举（fixed/percent）
  - 价格来源枚举（series_pricing/package_override）

### 5. 路由配置

已存在的路由（无需修改）：
- `/package-management/package-series` - 套餐系列管理
- `/package-management/package-list` - 套餐管理
- `/package-management/package-assign` - 单套餐分配

需要新增的路由：
- **新增**: `src/router/routesAlias.ts` - 添加路由别名
  - `MyPackages = '/package-management/my-packages'` - 代理可售套餐

- **新增**: `src/router/routes/asyncRoutes.ts` - 添加路由配置
  - `/package-management/my-packages` - 代理可售套餐页面路由

## Impact

### 受影响的规范
- `package-series-management` - 新增能力
- `package-management` - 新增能力
- `my-packages` - 新增能力
- `shop-package-allocation` - 新增能力

### 受影响的代码
- `src/api/modules/*` - 新增 4 个 API 服务模块
- `src/types/api/*` - 新增类型定义文件
- `src/views/package-management/*` - 4 个页面完整实现
- `src/config/constants/*` - 新增常量配置
- `src/router/routes/asyncRoutes.ts` - 路由配置

### 依赖关系
- 依赖现有的组件库（ArtTable、ArtSearchBar、ArtTableHeader 等）
- 依赖现有的 HTTP 请求工具（request.ts）
- 依赖现有的权限控制和路由守卫
- 依赖 ShopService（用于单套餐分配页面的店铺选择器）
- 后端 API 需已实现（docs/套餐.md 中定义的接口）

**注意事项**：
- ShopService 应该已经存在于 src/api/modules/shop.ts
- 如果不存在，需要先实现或使用 Mock 数据

### 风险评估
- **低风险**: 独立模块，不影响现有功能
- **API 依赖**: 需确保后端接口已实现并联调
- **权限控制**: 需配置对应的菜单和按钮权限