luo/one-pipe-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
099e3ec78bbec91e56064e939e7e720b0e53b0a2
one-pipe-system/openspec/project.md
sexygoat 222e5bb11a Initial commit: One Pipe System 
完整的管理系统，包含账户管理、卡片管理、套餐管理、财务管理等功能模块。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-22 16:35:33 +08:00

7.4 KiB
Raw Blame History

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 图表库
Reference in New Issue View Git Blame Copy Permalink