one-pipe-system/PROJECT_TASKS.md

# 物联网管理后台 - 功能开发任务清单

## 项目概述

基于 Vue 3 + TypeScript + Element Plus 的物联网管理后台系统，管理代理商、网卡、套餐、设备等核心业务。

---

## 📦 模块划分

### 一、基础架构优化（必须先完成）

#### 1.1 API 层重构

**优先级：P0（最高）**

- [ ] 创建统一的 API 服务基类
- [ ] 创建类型定义文件
  - [ ] `src/types/api/auth.ts` - 认证相关类型
  - [ ] `src/types/api/role.ts` - 角色相关类型
  - [ ] `src/types/api/account.ts` - 账号相关类型
  - [ ] `src/types/api/card.ts` - 网卡相关类型
  - [ ] `src/types/api/package.ts` - 套餐相关类型
  - [ ] `src/types/api/device.ts` - 设备相关类型
  - [ ] `src/types/api/commission.ts` - 佣金相关类型
- [ ] 创建 API 服务类
  - [ ] `src/api/modules/auth.ts` - AuthService
  - [ ] `src/api/modules/role.ts` - RoleService
  - [ ] `src/api/modules/account.ts` - AccountService
  - [ ] `src/api/modules/agent.ts` - AgentService (代理商)
  - [ ] `src/api/modules/card.ts` - CardService
  - [ ] `src/api/modules/package.ts` - PackageService
  - [ ] `src/api/modules/device.ts` - DeviceService
  - [ ] `src/api/modules/commission.ts` - CommissionService
  - [ ] `src/api/modules/setting.ts` - SettingService

#### 1.2 公共配置和常量提取

**优先级：P0**

- [ ] 创建 `src/config/constants/` 目录
  - [ ] `operators.ts` - 运营商配置
  - [ ] `cardStatus.ts` - 网卡状态配置
  - [ ] `userRoles.ts` - 用户角色配置
  - [ ] `packageTypes.ts` - 套餐类型配置
  - [ ] `deviceStatus.ts` - 设备状态配置
  - [ ] `commissionStatus.ts` - 佣金状态配置
- [ ] 创建 `src/utils/business/` 目录
  - [ ] `card.ts` - 网卡相关工具函数
  - [ ] `package.ts` - 套餐相关工具函数
  - [ ] `commission.ts` - 佣金计算工具函数
  - [ ] `format.ts` - 格式化工具函数

#### 1.3 业务 Composables

**优先级：P0**

- [ ] `src/composables/useCardManagement.ts` - 网卡管理
- [ ] `src/composables/usePackageManagement.ts` - 套餐管理
- [ ] `src/composables/useDeviceManagement.ts` - 设备管理
- [ ] `src/composables/useAgentManagement.ts` - 代理商管理
- [ ] `src/composables/useCommission.ts` - 佣金管理
- [ ] `src/composables/usePagination.ts` - 分页管理
- [ ] `src/composables/useTableSelection.ts` - 表格选择

#### 1.4 公共业务组件

**优先级：P1**

- [ ] `src/components/business/CardStatusTag.vue` - 网卡状态标签
- [ ] `src/components/business/OperatorSelect.vue` - 运营商选择器
- [ ] `src/components/business/PackageSelector.vue` - 套餐选择器
- [ ] `src/components/business/AgentSelector.vue` - 代理商选择器
- [ ] `src/components/business/CommissionDisplay.vue` - 佣金展示组件
- [ ] `src/components/business/BatchOperationDialog.vue` - 批量操作对话框
- [ ] `src/components/business/ImportDialog.vue` - 导入对话框组件

---

## 🎯 功能模块开发

### 二、认证与权限模块

#### 2.1 登录模块

**优先级：P0** **依赖：1.1 API 层重构**

- [ ] 后端接口对接
  - [ ] 登录接口
  - [ ] 退出登录接口
  - [ ] 获取用户信息接口
  - [ ] 刷新 Token 接口
- [ ] 前端页面
  - [ ] 完善登录页面（`src/views/auth/login/index.vue`）
  - [ ] 添加多角色登录支持（平台账号、代理商、企业客户）
  - [ ] 添加验证码功能
  - [ ] 添加记住密码功能
- [ ] 权限守卫
  - [ ] 完善路由守卫逻辑
  - [ ] 实现基于角色的路由过滤
  - [ ] 实现按钮级权限控制
- [ ] Store 状态管理
  - [ ] 完善用户 Store（用户信息、权限列表）
  - [ ] 添加 Token 自动刷新逻辑

**Mock 数据：**

- 模拟不同角色的登录响应
- 模拟权限列表

---

### 三、账号管理模块

#### 3.1 平台角色管理

**优先级：P1** **依赖：1.1, 1.2, 1.3**

**子任务：**

- [ ] 类型定义
  - [ ] 角色实体类型
  - [ ] 角色查询参数类型
  - [ ] 角色权限类型
- [ ] API 服务
  - [ ] 获取角色列表
  - [ ] 创建角色
  - [ ] 编辑角色
  - [ ] 删除角色
  - [ ] 分配权限
- [ ] 页面开发
  - [ ] `src/views/account-management/platform-role/index.vue`
  - [ ] 角色列表（表格）
  - [ ] 新增/编辑角色对话框
  - [ ] 权限分配对话框（树形结构）
- [ ] 组件开发
  - [ ] `PermissionTreeSelect.vue` - 权限树选择组件
- [ ] Mock 数据
  - [ ] 模拟角色列表
  - [ ] 模拟权限树

#### 3.2 平台账号管理

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取平台账号列表
  - [ ] 创建平台账号
  - [ ] 编辑平台账号
  - [ ] 删除/禁用平台账号
  - [ ] 重置密码
- [ ] 页面开发
  - [ ] `src/views/account-management/platform-account/index.vue`
  - [ ] 账号列表（支持搜索、筛选）
  - [ ] 新增/编辑账号对话框
  - [ ] 角色分配
- [ ] Mock 数据

#### 3.3 客户角色管理

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取客户角色列表
  - [ ] 创建客户角色
  - [ ] 编辑客户角色
  - [ ] 删除客户角色
  - [ ] 设置能力边界
- [ ] 页面开发
  - [ ] `src/views/account-management/customer-role/index.vue`
  - [ ] 角色列表
  - [ ] 能力边界配置（功能权限、资源限制）
- [ ] 组件开发
  - [ ] `AbilityBoundaryConfig.vue` - 能力边界配置组件
- [ ] Mock 数据

#### 3.4 代理商管理

**优先级：P1**

**子任务：**

- [ ] 类型定义
  - [ ] 代理商实体类型
  - [ ] 代理商层级关系类型
- [ ] API 服务
  - [ ] 获取代理商列表（树形结构）
  - [ ] 创建代理商
  - [ ] 编辑代理商信息
  - [ ] 禁用/启用代理商
  - [ ] 查看代理商详情
  - [ ] 获取代理商下级列表
- [ ] 页面开发
  - [ ] `src/views/account-management/agent-management/index.vue`
  - [ ] 代理商树形列表
  - [ ] 新增/编辑代理商对话框
  - [ ] 代理商详情页面
- [ ] 组件开发
  - [ ] `AgentTreeTable.vue` - 代理商树形表格组件
- [ ] Mock 数据
  - [ ] 模拟代理商层级数据

#### 3.5 企业客户管理

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取企业客户列表
  - [ ] 创建企业客户
  - [ ] 编辑企业客户
  - [ ] 禁用/启用企业客户
  - [ ] 分配客户角色
- [ ] 页面开发
  - [ ] `src/views/account-management/enterprise-customer/index.vue`
  - [ ] 企业客户列表
  - [ ] 新增/编辑企业客户对话框
- [ ] Mock 数据

#### 3.6 客户账号管理

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取客户账号列表（代理商+企业客户）
  - [ ] 解绑手机
  - [ ] 重置密码
  - [ ] 禁用/启用账号
- [ ] 页面开发
  - [ ] `src/views/account-management/customer-account/index.vue`
  - [ ] 账号列表（支持筛选）
  - [ ] 账号操作（解绑、重置密码等）
- [ ] Mock 数据

---

### 四、账户管理模块

#### 4.1 客户账户（佣金查看）

**优先级：P2**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取客户账户列表
  - [ ] 查看佣金详情
  - [ ] 查看提现记录
- [ ] 页面开发
  - [ ] `src/views/finance-management/customer-account/index.vue`
  - [ ] 客户账户列表
  - [ ] 佣金详情展示
  - [ ] 提现记录列表
- [ ] 组件开发
  - [ ] `CommissionDetailCard.vue` - 佣金详情卡片
- [ ] Mock 数据

#### 4.2 佣金提现管理

**优先级：P2**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取提现申请列表
  - [ ] 审核提现申请（通过/拒绝）
  - [ ] 查看提现详情
  - [ ] 批量审核
- [ ] 页面开发
  - [ ] `src/views/finance-management/commission-withdrawal/index.vue`
  - [ ] 提现申请列表
  - [ ] 审核对话框
  - [ ] 批量审核功能
- [ ] Mock 数据

#### 4.3 佣金提现设置

**优先级：P2**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取提现设置
  - [ ] 保存提现设置
  - [ ] 查看历史设置
- [ ] 页面开发
  - [ ] `src/views/finance-management/withdrawal-setting/index.vue`
  - [ ] 提现参数配置表单
  - [ ] 历史设置列表
- [ ] Mock 数据

#### 4.4 我的账户（佣金）

**优先级：P2**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取当前账号佣金数据
  - [ ] 获取佣金明细
  - [ ] 申请提现
- [ ] 页面开发
  - [ ] `src/views/finance-management/my-account/index.vue`
  - [ ] 佣金概览（卡片展示，非列表）
  - [ ] 佣金明细列表
  - [ ] 提现申请对话框
- [ ] 组件开发
  - [ ] `CommissionOverviewCard.vue` - 佣金概览卡片
- [ ] Mock 数据

---

### 五、我的设置模块

#### 5.1 收款商户设置

**优先级：P2**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取支付配置
  - [ ] 保存支付配置
- [ ] 页面开发
  - [ ] `src/views/my-settings/payment-merchant/index.vue`
  - [ ] 支付参数配置表单
- [ ] Mock 数据

#### 5.2 开发能力管理

**优先级：P2**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取开发能力参数
  - [ ] 生成 API Key
  - [ ] 刷新 Secret
- [ ] 页面开发
  - [ ] `src/views/my-settings/dev-capability/index.vue`
  - [ ] API Key 展示和管理
  - [ ] 接口文档链接
- [ ] Mock 数据

#### 5.3 分佣模板管理

**优先级：P2**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取分佣模板列表
  - [ ] 创建分佣模板
  - [ ] 编辑分佣模板
  - [ ] 删除分佣模板
- [ ] 页面开发
  - [ ] `src/views/my-settings/commission-template/index.vue`
  - [ ] 模板列表
  - [ ] 新增/编辑模板对话框
  - [ ] 分佣规则配置
- [ ] 组件开发
  - [ ] `CommissionRuleConfig.vue` - 分佣规则配置组件
- [ ] Mock 数据

---

### 六、商品管理模块

#### 6.1 号卡管理

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取号卡商品列表
  - [ ] 新增号卡商品
  - [ ] 编辑号卡商品
  - [ ] 删除号卡商品
- [ ] 页面开发
  - [ ] `src/views/product-management/simcard/index.vue`
  - [ ] 号卡列表
  - [ ] 新增/编辑号卡对话框
- [ ] Mock 数据

#### 6.2 号卡分配

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取可分配号卡列表
  - [ ] 分配号卡给代理
  - [ ] 设置佣金模式
- [ ] 页面开发
  - [ ] `src/views/product-management/simcard-assign/index.vue`
  - [ ] 号卡选择
  - [ ] 代理商选择
  - [ ] 佣金模式配置
- [ ] 组件开发
  - [ ] `CommissionModeSelector.vue` - 佣金模式选择组件
- [ ] Mock 数据

#### 6.3 套餐系列管理

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取套餐系列列表
  - [ ] 新增套餐系列
  - [ ] 编辑套餐系列
  - [ ] 删除套餐系列
- [ ] 页面开发
  - [ ] `src/views/product-management/package-series/index.vue` (重命名 package-series)
  - [ ] 系列列表
  - [ ] 新增/编辑系列对话框
- [ ] Mock 数据

#### 6.4 套餐管理

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取套餐列表（根据角色过滤）
  - [ ] 创建套餐
  - [ ] 编辑套餐
  - [ ] 删除套餐
- [ ] 页面开发
  - [ ] 重构 `src/views/package-management/package-create/index.vue`
  - [ ] 套餐列表（支持角色过滤）
  - [ ] 新增/编辑套餐对话框
- [ ] Mock 数据

#### 6.5 套餐分配

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取可分配套餐列表
  - [ ] 分配套餐给直级代理
  - [ ] 设置佣金模式
- [ ] 页面开发
  - [ ] 重构 `src/views/package-management/package-assign/index.vue`
  - [ ] 套餐选择
  - [ ] 直级代理选择
  - [ ] 佣金模式配置
- [ ] Mock 数据

---

### 七、资产管理模块

#### 7.1 单卡信息查询

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 根据 ICCID 查询单卡信息
  - [ ] 套餐充值
  - [ ] 停复机操作
  - [ ] 流量详情查询
  - [ ] 更改过期时间
  - [ ] 转新卡
  - [ ] 停复机记录
  - [ ] 往期订单
  - [ ] 增减流量
  - [ ] 变更钱包余额
  - [ ] 充值支付密码
  - [ ] 续充
  - [ ] 设备操作
- [ ] 页面开发
  - [ ] 重构 `src/views/card-management/single-card/index.vue`
  - [ ] 单卡信息展示（描述列表）
  - [ ] 操作按钮组
  - [ ] 各类操作对话框
- [ ] 组件开发
  - [ ] 复用 `CardOperationDialog.vue` 并扩展功能
- [ ] Mock 数据

#### 7.2 网卡管理

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取网卡列表
  - [ ] 批量操作入口
- [ ] 页面开发
  - [ ] 重构 `src/views/card-management/card-list/index.vue`
  - [ ] 网卡列表
  - [ ] 批量操作按钮
- [ ] Mock 数据

#### 7.3 设备管理

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取设备列表
  - [ ] 查看设备卡信息
  - [ ] 修改设备卡信息
  - [ ] 设备相关操作
- [ ] 页面开发
  - [ ] 拆分 `src/views/device-management/devices/index.vue` (2022行，需拆分)
    - [ ] 主页面 `index.vue`
    - [ ] 设备详情组件 `DeviceDetail.vue`
    - [ ] 设备操作组件 `DeviceOperation.vue`
  - [ ] 设备列表
  - [ ] 设备详情对话框
  - [ ] 设备操作对话框
- [ ] Composables
  - [ ] `useDeviceManagement.ts` - 设备管理逻辑
- [ ] Mock 数据

#### 7.4 资产分配

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 设备批量分配
  - [ ] 网卡批量分配
- [ ] 页面开发
  - [ ] `src/views/asset-management/asset-assign/index.vue`
  - [ ] 分配方式选择（设备/网卡）
  - [ ] 批量导入 ICCID
  - [ ] 目标代理选择
- [ ] 组件开发
  - [ ] 复用 `ImportDialog.vue`
- [ ] Mock 数据

#### 7.5 换卡申请

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 获取换卡申请列表
  - [ ] 处理换卡申请
  - [ ] 填充新 ICCID
- [ ] 页面开发
  - [ ] 重构 `src/views/card-management/card-replacement/index.vue`
  - [ ] 申请列表
  - [ ] 处理对话框
- [ ] Mock 数据

---

### 八、批量操作模块

#### 8.1 网卡导入

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 批量导入 ICCID
  - [ ] 查看导入任务状态
  - [ ] 查看导入失败记录
- [ ] 页面开发
  - [ ] `src/views/batch-operation/card-import/index.vue`
  - [ ] Excel 导入
  - [ ] 任务列表
  - [ ] 失败记录查看
- [ ] 组件开发
  - [ ] 复用 `ImportDialog.vue`
- [ ] Mock 数据

#### 8.2 设备导入

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 批量导入设备及 ICCID 关系
  - [ ] 查看导入任务状态
- [ ] 页面开发
  - [ ] `src/views/batch-operation/device-import/index.vue`
  - [ ] Excel 导入
  - [ ] 任务列表
- [ ] Mock 数据

#### 8.3 线下批量充值

**优先级：P1**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 查看批量充值记录
  - [ ] Excel 批量充值导入
- [ ] 页面开发
  - [ ] 重构 `src/views/card-management/offline-batch-recharge/index.vue`
  - [ ] 充值记录列表
  - [ ] 批量充值 Excel 导入
- [ ] Mock 数据

#### 8.4 换卡通知

**优先级：P2**

**子任务：**

- [ ] 类型定义
- [ ] API 服务
  - [ ] 单独新建换卡通知
  - [ ] 批量新建换卡通知
  - [ ] 查看换卡通知记录
- [ ] 页面开发
  - [ ] `src/views/batch-operation/card-change-notice/index.vue`
  - [ ] 通知记录列表
  - [ ] 新建通知对话框（单个/批量）
- [ ] Mock 数据

---

## 📅 开发计划建议

### 第一阶段（1-2 周）：基础架构

- 完成所有 1.x 任务（API 层、配置、Composables、公共组件）
- 完成登录模块（2.1）

### 第二阶段（2-3 周）：账号管理

- 完成账号管理模块所有功能（3.1-3.6）

### 第三阶段（2 周）：商品管理

- 完成商品管理模块（6.1-6.5）

### 第四阶段（2-3 周）：资产管理

- 完成资产管理模块（7.1-7.5）

### 第五阶段（1-2 周）：账户管理 + 我的设置

- 完成账户管理模块（4.1-4.4）
- 完成我的设置模块（5.1-5.3）

### 第六阶段（1-2 周）：批量操作 + 优化

- 完成批量操作模块（8.1-8.4）
- 性能优化、测试、Bug 修复

---

## 📌 注意事项

1. **所有模块先用 Mock 数据开发，便于前后端并行开发**
2. **严格遵循组件化原则，提高代码复用率**
3. **使用 TypeScript 严格类型，减少运行时错误**
4. **每个模块完成后进行代码审查**
5. **关键功能需要编写单元测试**

---

## 🔗 相关文档

- [项目架构文档](./openspec/project.md)
- [API 规范文档](待创建)
- [组件使用文档](待创建)