# Project Context

## Purpose

物联网管理后台系统 (Internet of Things Admin)，用于运营平台和代理商管理。

主要目标：

- 提供运营人员和代理商的统一管理平台
- 管理物联网卡（号卡）的全生命周期
- 处理代理商体系的分佣和财务管理
- 提供设备和网卡的资产管理能力
- 支持批量操作和数据导入导出

## Tech Stack

- **前端框架**: Vue 3.5+ (Composition API)
- **编程语言**: TypeScript 5.6+
- **构建工具**: Vite 6.1+
- **UI 组件库**: Element Plus 2.8+
- **状态管理**: Pinia 3.0+ (with persistedstate plugin)
- **路由管理**: Vue Router 4.4+
- **HTTP 客户端**: Axios 1.7+
- **图表可视化**: ECharts 5.4+
- **富文本编辑器**: WangEditor 5.1+ / md-editor-v3
- **Excel 处理**: XLSX 0.18+
- **工具库**: VueUse 11.0+, crypto-js, file-saver, qrcode.vue

## Project Conventions

### Code Style

- **代码规范**: ESLint 9.x + Prettier 3.x
- **样式规范**: Stylelint 16.x (SCSS, Vue)
- **提交规范**: Commitizen + cz-git (conventional commits)
- **Git Hooks**: Husky + lint-staged (自动格式化和检查)
- **命名约定**:
  - 组件: PascalCase (如 `ArtBarChart.vue`)
  - 文件: camelCase 或 kebab-case
  - API 文件: 以 `Api` 结尾 (如 `menuApi.ts`, `usersApi.ts`)

### Architecture Patterns

- **组件架构**: 基于 Vue 3 Composition API
- **状态管理**: Pinia stores，支持持久化
- **路由守卫**: 基于角色的权限控制
- **API 模块化**: 按业务模块组织 API (modules 目录)
- **样式方案**: SCSS + CSS Variables (支持主题切换：light/dark/system)
- **布局模式**: 支持多种布局 (vertical/horizontal/mixed/dual_column)

### Testing Strategy

- **单元测试**: Vitest + @vue/test-utils
  - 优先测试：工具函数、复杂业务逻辑、状态管理
  - 覆盖率目标：核心模块 > 80%
- **E2E 测试**: Playwright (待引入)
  - 优先场景：登录流程、关键业务流程（充值、分配等）
- **代码检查**: pre-commit 时自动运行 ESLint 和 Stylelint
- **类型检查**: TypeScript strict mode，构建时进行类型检查

### Git Workflow

- **分支策略**: GitHub Flow (简化版)
  - `master`: 主分支，始终保持可部署状态
  - `feature/*`: 功能分支，从 master 创建
  - `fix/*`: 修复分支，从 master 创建
  - `hotfix/*`: 紧急修复，从 master 创建
- **提交规范**: Conventional Commits
  - `feat`: 新功能
  - `fix`: 修复 bug
  - `docs`: 文档更新
  - `style`: 代码格式调整
  - `refactor`: 重构
  - `perf`: 性能优化
  - `test`: 测试相关
  - `chore`: 构建/工具链更新
- **代码审查**: 建议 PR review 后合并

## Domain Context

### 业务领域

物联网卡管理系统，面向运营人员和代理商。

### 核心概念

- **平台角色**: 区分不同账号职责（运营/管理员等）
- **客户角色**: 决定客户的能力边界
- **代理商体系**: 多级代理商管理，支持分佣
- **企业客户**: 只能登录企业端的客户账号
- **号卡/网卡**: 物联网SIM卡，通过 ICCID 标识
- **套餐**: 流量套餐，可分配给代理商
- **设备**: 与网卡绑定的物联网设备
- **佣金模板**: 预设的分佣规则，方便分配产品时使用

### 主要业务模块

#### 1. 账号管理

- **平台角色**: 用以区分不同账号职责
- **平台账号**: 管理平台/运营账号
- **客户角色**: 决定客户能力边界
- **代理商管理**: 创建代理商及管理特定代理商账号
- **企业客户管理**: 创建企业管理账号（只能登录企业端，依赖客户角色）
- **客户账号管理**: 管理客户（代理商+企业客户）的账号，支持解绑手机等操作

#### 2. 账户管理

- **客户账户**: 查看账号下全部客户账号的佣金情况及提现情况
- **佣金提现**: 管理全部的提现申请
- **佣金提现设置**: 设置提现参数（生效最新一条）
- **我的账户**: 获取当前登录账号的佣金相关数据

#### 3. 我的设置

- **收款商户设置**: 设置支付参数
- **开发能力管理**: 获取开发能力对接参数及管理
- **分佣模板**: 创建及管理分佣模板，方便给代理分配产品时设置分佣规则

#### 4. 商品管理

- **号卡管理**: 新增管理号卡商品，管理基础信息
- **号卡分配**: 为特定代理分配号卡商品，同时设置佣金模式
- **套餐系列管理**: 新增及管理套餐系列
- **套餐管理**: 新增及管理套餐（只能看到自己的/管理员可以看到全部）
- **套餐分配**: 为直级代理分配套餐同时设置佣金模式

#### 5. 资产管理

- **单卡信息**:
  - 通过 ICCID 查询单卡相关信息
  - 支持操作：套餐充值、停复机、流量详情、更改过期时间、转新卡、停复机记录、往期订单、增减流量、变更钱包余额、充值支付密码、续充、设备操作
- **网卡管理**: 查询网卡信息，提供相关批量操作入口
- **设备管理**: 查看设备信息，提供相关操作入口，查看/修改设备卡信息，设备相关操作
- **资产分配**:
  - 为特定代理分配网卡，只支持批量操作
  - 批量分配分为两种：设备批量分配、网卡批量分配
  - 网卡批量分配时，若网卡有设备信息，会把该卡所属设备及网卡都分配过去
- **换卡申请**: 管理客户提交的换卡申请，处理换卡申请，填充新的 ICCID

#### 6. 批量操作

- **网卡导入**: 批量导入 ICCID，查看导入任务情况
- **设备导入**: 批量导入设备及 ICCID 关系，查看导入任务情况
- **线下批量充值**: 查看批量充值记录，提供批量充值 Excel 导入
- **换卡通知**: 可单独/批量新建换卡通知，查看换卡通知记录

#### 7. 登录模块

- 用以登录平台（根据账号属性做权限控制）

## Important Constraints

### 技术约束

- Node.js 版本要求: >= 20.19.0
- 浏览器兼容性: 现代浏览器（Chrome、Firefox、Safari、Edge）
- 构建输出: ES Module

### 业务约束

- **权限控制**: 严格的基于角色的访问控制 (RBAC)
- **数据隔离**: 代理商只能查看自己及下级的数据
- **佣金计算**: 需要准确的佣金计算和分配逻辑
- **批量操作**: 需要异步任务处理机制，防止超时
- **ICCID 唯一性**: 物联网卡的 ICCID 必须唯一

### 安全约束

- 敏感操作需要二次确认
- 财务相关操作需要审计日志
- 密码需要加密存储和传输

## External Dependencies

### 后端 API

- 主要通过 Axios 与后端 RESTful API 交互
- API 基础路径配置在环境变量中
- API 文档托管在 Apifox (详见 `docs/部分API.md`)
- **API 模块划分**:
  - `账号相关`: 账号 CRUD、角色分配
  - `权限`: 权限 CRUD、权限树
  - `平台账号`: 平台账号管理、密码修改、启用/禁用
  - `角色`: 角色 CRUD、权限分配、状态管理
  - `认证`: 登录、登出、Token 刷新、用户信息
- **请求/响应约定**:
  - 统一使用 RESTful 风格
  - 分页列表返回: `ModelXxxPageResult`
  - 详情返回: `ModelXxxResponse`
  - 创建请求: `ModelCreateXxxRequest`
  - 更新请求: `ModelUpdateXxxParams`

### 第三方服务

- **支付服务**: 收款商户设置中配置
- **短信服务**: 用于手机验证码
- **物联网卡供应商 API**: 用于卡片操作（停复机、充值等）

### UI 依赖

- Element Plus Icons
- 自定义图标字体 (iconfont)
- ECharts 图表库