205 lines
7.4 KiB
Markdown
205 lines
7.4 KiB
Markdown
# 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 图表库
|