fetch(modify):修改原来的bug

openspec/changes/add-package-management-system/design.md

@@ -5,12 +5,14 @@
 实现完整的套餐管理系统，包括4个核心模块。该系统需要支持多级代理商体系的套餐分配和定价管理。
 
 **背景**：
+
 - 项目已有类型定义（src/types/api/package.ts），但使用不同的字段命名和枚举值
 - 后端 API 已实现，使用下划线命名（如 `series_name`）
 - 前端项目统一使用 CommonStatus 枚举（0:禁用, 1:启用）
 - 参考实现：`/system/role` 页面使用了组件化架构
 
 **约束**：
+
 - 必须保留现有类型定义文件，不能破坏现有代码
 - 需要兼容后端 API 的字段命名规范
 - 需要适配项目的状态枚举规范
@@ -18,6 +20,7 @@
 ## Goals / Non-Goals
 
 ### Goals
+
 1. 实现4个核心模块的完整 CRUD 功能
 2. 建立统一的 API 服务层，封装后端接口
 3. 实现组件化的页面结构，参考 `/system/role`
@@ -25,6 +28,7 @@
 5. 确保数据隔离和权限控制
 
 ### Non-Goals
+
 1. 不重构现有的 package.ts 类型定义
 2. 不实现套餐的实时统计和报表功能（后续迭代）
 3. 不实现套餐批量导入功能（后续迭代）
@@ -37,20 +41,23 @@
 **问题**：后端使用下划线命名（snake_case），前端类型通常使用驼峰命名（camelCase）。
 
 **决策**：
+
 - API 请求/响应保持下划线命名，与后端保持一致
 - 创建新的类型文件 `packageManagement.ts`，使用下划线命名
 - 在表单提交和响应处理时不做转换，直接使用下划线字段
 
 **理由**：
+
 - 减少转换层的复杂性和错误风险
 - 与后端 API 文档保持一致，便于对照
 - TypeScript 支持下划线字段名，不影响类型安全
 
 **示例**：
+
 ```typescript
 export interface PackageSeriesResponse {
   id: number
-  series_code: string  // 下划线命名
+  series_code: string // 下划线命名
   series_name: string
   status: number
   created_at: string
@@ -63,11 +70,13 @@ export interface PackageSeriesResponse {
 **问题**：文档中状态是 `1:启用, 2:禁用`，但项目 CommonStatus 是 `0:禁用, 1:启用`。
 
 **决策**：
+
 - **在常量配置中定义套餐专用的状态枚举**
 - **前端页面使用项目统一的 CommonStatus（0/1）**
 - **在 API 服务层进行状态值映射转换**
 
 **映射规则**：
+
 ```typescript
 // 前端 -> 后端
 CommonStatus.ENABLED (1) -> API Status (1)
@@ -79,6 +88,7 @@ API Status (2) -> CommonStatus.DISABLED (0)
 ```
 
 **理由**：
+
 - 保持前端 UI 的一致性
 - 避免混淆项目开发者
 - 集中在 API 服务层处理差异
@@ -88,18 +98,21 @@ API Status (2) -> CommonStatus.DISABLED (0)
 **问题**：是创建单个 package.ts 服务，还是拆分为多个服务文件？
 
 **决策**：拆分为4个独立的服务文件：
+
 1. `packageSeries.ts` - 套餐系列管理
 2. `package.ts` - 套餐管理
 3. `myPackage.ts` - 代理可售套餐
 4. `shopPackageAllocation.ts` - 单套餐分配
 
 **理由**：
+
 - 每个模块功能独立，职责清晰
 - 便于维护和扩展
 - 符合单一职责原则
 - 便于团队协作（不同开发者负责不同模块）
 
 **替代方案**：
+
 - 单个 package.ts 文件 - **拒绝**，文件过大，难以维护
 
 ### Decision 4: 定价规则实现
@@ -107,11 +120,13 @@ API Status (2) -> CommonStatus.DISABLED (0)
 **问题**：代理商的套餐成本价有两种计算方式：系列加价和单套餐覆盖。
 
 **决策**：
+
 - **后端负责成本价计算**，前端只展示结果
 - 前端接收 `price_source` 字段，标识价格来源
 - 单套餐分配创建时，保存 `calculated_cost_price`（系列规则计算的价格）供参考
 
 **数据流**：
+
 ```
 1. 系列分配：pricing_mode + pricing_value -> 后端计算 -> cost_price
 2. 单套餐分配：直接设置 cost_price（覆盖系列规则）
@@ -119,6 +134,7 @@ API Status (2) -> CommonStatus.DISABLED (0)
 ```
 
 **理由**：
+
 - 计算逻辑复杂，集中在后端便于维护
 - 前端只负责展示，降低复杂度
 - 保留 calculated_cost_price 便于调试和审计
@@ -128,16 +144,19 @@ API Status (2) -> CommonStatus.DISABLED (0)
 **问题**：客户端验证 vs 服务端验证。
 
 **决策**：**双重验证**
+
 - 客户端：使用 Element Plus 的 FormRules 进行基础验证
 - 服务端：后端 API 进行完整验证并返回详细错误
 
 **客户端验证规则**：
+
 - 必填字段检查
 - 长度限制（如系列名称 1-255 字符）
 - 数值范围（如套餐时长 1-120 月）
 - 格式验证（如价格必须为正整数）
 
 **理由**：
+
 - 客户端验证提升用户体验，即时反馈
 - 服务端验证保证数据安全性和完整性
 - 符合 Web 应用最佳实践
@@ -147,20 +166,26 @@ API Status (2) -> CommonStatus.DISABLED (0)
 **问题**：页面结构如何组织？
 
 **决策**：参考 `/system/role` 页面，使用组件化结构：
+
 ```vue
 <template>
   <ArtTableFullScreen>
-    <ArtSearchBar /> <!-- 搜索栏 -->
+    <ArtSearchBar />
+    <!-- 搜索栏 -->
     <ElCard>
-      <ArtTableHeader /> <!-- 表格头部：刷新、列设置、操作按钮 -->
-      <ArtTable /> <!-- 数据表格 -->
-      <ElDialog /> <!-- 新增/编辑对话框 -->
+      <ArtTableHeader />
+      <!-- 表格头部：刷新、列设置、操作按钮 -->
+      <ArtTable />
+      <!-- 数据表格 -->
+      <ElDialog />
+      <!-- 新增/编辑对话框 -->
     </ElCard>
   </ArtTableFullScreen>
 </template>
 ```
 
 **理由**：
+
 - 与项目现有页面风格一致
 - 复用成熟的组件，减少开发工作量
 - 便于维护和扩展
@@ -172,6 +197,7 @@ API Status (2) -> CommonStatus.DISABLED (0)
 **风险**：后端接口可能尚未实现或与文档不一致。
 
 **缓解措施**：
+
 1. 先实现 API 服务层，使用 TypeScript 类型约束
 2. 使用 Mock 数据进行前端开发（已有示例）
 3. 与后端团队确认 API 规范和联调时间
@@ -182,6 +208,7 @@ API Status (2) -> CommonStatus.DISABLED (0)
 **风险**：在某些地方忘记转换状态值，导致显示错误。
 
 **缓解措施**：
+
 1. 在 API 服务层统一处理转换
 2. 创建工具函数封装映射逻辑
 3. 编写单元测试覆盖映射函数
@@ -192,6 +219,7 @@ API Status (2) -> CommonStatus.DISABLED (0)
 **风险**：对定价规则的理解与实际业务需求有偏差。
 
 **缓解措施**：
+
 1. 在实现前与产品确认定价规则
 2. 编写测试用例覆盖各种定价场景
 3. 在 UI 上清晰展示价格来源和计算方式
@@ -202,10 +230,12 @@ API Status (2) -> CommonStatus.DISABLED (0)
 **取舍**：保留旧的 package.ts 类型定义，新增 packageManagement.ts。
 
 **代价**：
+
 - 存在两套类型定义，可能造成混淆
 - 占用额外的代码空间
 
 **收益**：
+
 - 不影响现有代码，向后兼容
 - 新旧系统可以并存，降低迁移风险
 - 未来可以逐步迁移到新类型
@@ -215,10 +245,12 @@ API Status (2) -> CommonStatus.DISABLED (0)
 **取舍**：在 API 服务层进行状态值转换。
 
 **代价**：
+
 - 增加一层转换逻辑
 - 可能影响性能（微小）
 
 **收益**：
+
 - 前端 UI 保持一致性
 - 业务逻辑更清晰
 - 便于后续维护
@@ -226,27 +258,32 @@ API Status (2) -> CommonStatus.DISABLED (0)
 ## Migration Plan
 
 ### Phase 1: 基础设施（1-2天）
+
 1. 创建类型定义文件
 2. 创建常量配置文件
 3. 设置状态映射工具函数
 
 ### Phase 2: API 服务层（2-3天）
+
 1. 实现4个 API 服务模块
 2. 编写单元测试（可选）
 3. 使用 Mock 数据测试
 
 ### Phase 3: 页面实现（4-5天）
+
 1. 套餐系列管理页面（1天）
 2. 套餐管理页面（1.5天）
 3. 代理可售套餐页面（1天）
 4. 单套餐分配页面（1.5天）
 
 ### Phase 4: 集成测试（1-2天）
+
 1. 与后端 API 联调
 2. 端到端功能测试
 3. 修复 Bug 和优化
 
 ### Phase 5: 上线（1天）
+
 1. Code Review
 2. 合并代码
 3. 部署到测试环境
@@ -257,6 +294,7 @@ API Status (2) -> CommonStatus.DISABLED (0)
 ### Rollback Plan
 
 如果出现严重问题，回滚步骤：
+
 1. 从 Git 回滚到上一个稳定版本
 2. 移除新增的路由配置
 3. 移除新增的 API 服务导出
@@ -267,6 +305,7 @@ API Status (2) -> CommonStatus.DISABLED (0)
 **问题**：如何统一处理各类错误和异常？
 
 **决策**：分层错误处理机制
+
 - **网络错误**：axios 拦截器统一捕获，显示通用错误提示
 - **401 未认证**：自动跳转到登录页面
 - **403 无权限**：显示权限不足提示，不跳转
@@ -274,6 +313,7 @@ API Status (2) -> CommonStatus.DISABLED (0)
 - **表单验证错误**：在表单字段下显示错误提示
 
 **错误提示方式**：
+
 ```typescript
 // 网络错误或服务器错误
 ElMessage.error('网络错误，请稍后重试')
@@ -286,6 +326,7 @@ ElMessage.success('操作成功')
 ```
 
 **理由**：
+
 - 统一的错误处理提升用户体验
 - 分层处理避免重复代码
 - 清晰的错误提示帮助用户理解问题
@@ -297,36 +338,34 @@ ElMessage.success('操作成功')
 **决策**：细粒度的 loading 状态管理
 
 **Loading 状态分类**：
+
 ```typescript
-const loading = ref(false)           // 表格数据加载
-const submitLoading = ref(false)     // 表单提交
+const loading = ref(false) // 表格数据加载
+const submitLoading = ref(false) // 表单提交
 const deleteLoading = ref<Record<number, boolean>>({}) // 删除操作（可选）
 ```
 
 **状态管理规则**：
+
 - **列表查询**：表格显示 loading 遮罩
 - **新增/编辑提交**：提交按钮显示 loading，禁用表单
 - **删除操作**：可选择在按钮上显示 loading 或全局 loading
 - **状态切换**：ElSwitch 自带 loading 效果，先更新 UI 再调用 API
 
 **理由**：
+
 - 细粒度控制提供更好的交互反馈
 - 防止重复提交
 - 清晰标识正在进行的操作
 
 ## Open Questions
 
-1. **Q**: 套餐被删除后，历史订单如何处理？
-   **A**: 待产品确认，可能需要软删除机制
+1. **Q**: 套餐被删除后，历史订单如何处理？ **A**: 待产品确认，可能需要软删除机制
 
-2. **Q**: 代理商可以自行调整套餐售价吗？
-   **A**: 待产品确认，当前设计只展示建议售价
+2. **Q**: 代理商可以自行调整套餐售价吗？ **A**: 待产品确认，当前设计只展示建议售价
 
-3. **Q**: 套餐系列和套餐是否支持批量操作（批量启用/禁用）？
-   **A**: 当前不支持，后续迭代考虑
+3. **Q**: 套餐系列和套餐是否支持批量操作（批量启用/禁用）？ **A**: 当前不支持，后续迭代考虑
 
-4. **Q**: 是否需要套餐变更历史记录？
-   **A**: 后端可能有审计日志，前端暂不展示
+4. **Q**: 是否需要套餐变更历史记录？ **A**: 后端可能有审计日志，前端暂不展示
 
-5. **Q**: 单套餐分配的"原计算成本价"是否需要实时更新？
-   **A**: 待确认，当前设计是创建时计算一次，不自动更新
+5. **Q**: 单套餐分配的"原计算成本价"是否需要实时更新？ **A**: 待确认，当前设计是创建时计算一次，不自动更新