278 lines
7.0 KiB
Markdown
278 lines
7.0 KiB
Markdown
# PQS-9100 Tool Client
|
||
|
||
## 项目简介
|
||
|
||
这是一个基于 Electron 的桌面端小工具，用于离线生成和管理设备激活码。
|
||
|
||
项目定位：
|
||
|
||
- 面向 C 端桌面使用场景
|
||
- 不依赖后端服务
|
||
- 数据保存在本地内置 SQLite 数据库
|
||
- 当前核心业务为设备激活记录管理
|
||
|
||
该项目是在 `electron-egg` 模板基础上裁剪和扩展得到，现阶段实际业务代码集中在“设备激活”模块。
|
||
|
||
## 技术栈
|
||
|
||
- 桌面框架：Electron 31
|
||
- Electron 应用框架：electron-egg / ee-core
|
||
- 前端框架：Vue 3
|
||
- UI 组件库：Ant Design Vue
|
||
- 构建工具：Vite 6
|
||
- 本地数据库：better-sqlite3
|
||
- 日期处理：dayjs
|
||
- 加解密：jsencrypt
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
.
|
||
├─electron/ Electron 主进程代码
|
||
│ ├─config/ 应用配置
|
||
│ ├─controller/ IPC 控制器
|
||
│ ├─preload/ 应用启动与 preload 逻辑
|
||
│ ├─service/ 主进程服务
|
||
│ │ ├─database/ 本地数据库封装
|
||
│ │ └─os/ 托盘、窗口、安全、更新等系统能力
|
||
│ └─main.ts Electron 入口
|
||
├─frontend/ Vue 前端应用
|
||
│ ├─src/
|
||
│ │ ├─api/ IPC 路由定义
|
||
│ │ ├─assets/ 静态资源与样式
|
||
│ │ ├─layouts/ 页面布局
|
||
│ │ ├─router/ 路由配置
|
||
│ │ ├─utils/ 工具函数
|
||
│ │ └─views/activate/ 激活业务页面
|
||
│ ├─.env.development 开发环境变量
|
||
│ ├─.env.production 生产环境变量
|
||
│ └─vite.config.ts 前端构建配置
|
||
├─build/ 打包资源
|
||
├─cmd/ electron-builder 配置
|
||
├─public/ Electron 公共资源
|
||
├─package.json 根脚本与 Electron 依赖
|
||
└─README.md 项目说明
|
||
```
|
||
|
||
## 核心功能
|
||
|
||
### 1. 设备激活码生成
|
||
|
||
前端页面提供以下能力：
|
||
|
||
- 录入设备申请码
|
||
- 选择需要激活的模块
|
||
- 生成设备激活码
|
||
- 复制激活码
|
||
- 填写备注
|
||
|
||
当前支持的模块有：
|
||
|
||
- `simulate`
|
||
- `digital`
|
||
- `contrast`
|
||
|
||
### 2. 激活记录管理
|
||
|
||
激活记录页面支持：
|
||
|
||
- 按 `macAddress` 查询
|
||
- 按模块组合查询
|
||
- 查看历史激活记录
|
||
- 复制历史记录中的激活码
|
||
- 将新生成的激活记录保存到本地数据库
|
||
|
||
### 3. 本地数据库存储
|
||
|
||
项目不依赖后端，激活记录直接写入本地 SQLite。
|
||
|
||
当前数据库文件名：
|
||
|
||
- `pqs9100-tool.db`
|
||
|
||
当前表：
|
||
|
||
- `activate_record`
|
||
|
||
主要字段：
|
||
|
||
- `id`
|
||
- `macAddress`
|
||
- `applicationCode`
|
||
- `module`
|
||
- `activationCode`
|
||
- `createTime`
|
||
- `remark`
|
||
|
||
## 业务流程
|
||
|
||
整体流程如下：
|
||
|
||
1. 用户在前端输入设备申请码。
|
||
2. 前端使用 RSA 私钥解密申请码，解析出设备信息。
|
||
3. 用户选择需要激活的模块。
|
||
4. 前端组装激活码明文后，再用 RSA 公钥加密生成激活码。
|
||
5. 用户点击保存后，前端通过 IPC 调用主进程。
|
||
6. 主进程将记录写入本地 SQLite 数据库。
|
||
7. 列表页面通过 IPC 查询本地数据库并展示历史记录。
|
||
|
||
## 核心代码说明
|
||
|
||
### Electron 主进程
|
||
|
||
- `electron/main.ts`
|
||
- 应用启动入口
|
||
- 注册生命周期与 preload
|
||
|
||
- `electron/preload/index.ts`
|
||
- 启动时初始化托盘
|
||
- 初始化安全服务
|
||
- 初始化自动更新服务
|
||
- 初始化本地数据库
|
||
|
||
- `electron/preload/lifecycle.ts`
|
||
- 控制应用 ready、窗口 ready、关闭前等生命周期行为
|
||
- 启动后自动设置主窗口大小和位置
|
||
|
||
### 数据库相关
|
||
|
||
- `electron/service/database/basedb.ts`
|
||
- SQLite 基础封装
|
||
- 负责数据库文件路径和连接初始化
|
||
|
||
- `electron/service/database/activateRecord.ts`
|
||
- `activate_record` 表初始化
|
||
- 保存激活记录
|
||
- 查询激活记录
|
||
- 删除记录等数据库操作
|
||
|
||
- `electron/controller/activateRecord.ts`
|
||
- 暴露激活记录相关 IPC 接口
|
||
|
||
### 前端相关
|
||
|
||
- `frontend/src/main.ts`
|
||
- Vue 应用入口
|
||
- 注册 Ant Design Vue 和全局组件
|
||
|
||
- `frontend/src/router/routerMap.ts`
|
||
- 当前仅注册一个业务页面：`/activate`
|
||
|
||
- `frontend/src/layouts/AppSider.vue`
|
||
- 左侧菜单布局
|
||
- 当前只包含“设备激活”菜单
|
||
|
||
- `frontend/src/views/activate/index.vue`
|
||
- 激活记录查询页面
|
||
- 激活记录展示、查询、复制、保存入口
|
||
|
||
- `frontend/src/views/activate/ActiveForm.vue`
|
||
- 激活码生成表单
|
||
- 处理申请码解析、模块选择、激活码生成
|
||
|
||
- `frontend/src/utils/rsa.ts`
|
||
- RSA 加解密封装
|
||
|
||
- `frontend/src/utils/ipcRenderer.ts`
|
||
- 渲染进程 IPC 调用封装
|
||
|
||
## 路由与界面
|
||
|
||
当前前端只有一条实际业务路由：
|
||
|
||
- `/activate` 设备激活页面
|
||
|
||
左侧菜单当前也只有一个入口：
|
||
|
||
- 设备激活
|
||
|
||
因此，整个系统目前可以理解为“单页面桌面工具”，所有主要功能都集中在这一个界面中完成。
|
||
|
||
当前页面的详细说明已单独整理到：
|
||
|
||
- `docs/current-page.md`
|
||
|
||
## 配置说明
|
||
|
||
### 根目录脚本
|
||
|
||
常用命令：
|
||
|
||
- `npm run dev` 启动 Electron + 前端开发环境
|
||
- `npm run dev-frontend` 仅启动前端
|
||
- `npm run dev-electron` 仅启动 Electron
|
||
- `npm run build` 构建前端、Electron 并执行加密
|
||
- `npm run build-w` 构建 Windows 安装包
|
||
|
||
### 前端环境变量
|
||
|
||
位于：
|
||
|
||
- `frontend/.env.development`
|
||
- `frontend/.env.production`
|
||
|
||
当前已使用的变量主要有：
|
||
|
||
- `VITE_TITLE`
|
||
- `VITE_RSA_PUBLIC_KEY`
|
||
- `VITE_RSA_PRIVATE_KEY`
|
||
- `VITE_RSA_CAN_EDIT`
|
||
|
||
## 数据存储说明
|
||
|
||
数据库由主进程在应用启动时初始化。
|
||
|
||
数据库初始化入口：
|
||
|
||
- `electron/preload/index.ts`
|
||
|
||
数据库基础路径由 `ee-core` 提供的数据目录决定，实际数据库文件保存在应用数据目录下的 `db` 子目录中。
|
||
|
||
## 当前项目特征总结
|
||
|
||
从当前代码看，项目有以下特点：
|
||
|
||
- 业务功能集中，当前只有激活工具这一个主要模块
|
||
- 没有后端依赖，所有数据均在本地处理和存储
|
||
- 前端负责激活码的生成逻辑
|
||
- 主进程负责数据库初始化与数据持久化
|
||
- 项目仍保留部分 `electron-egg` 模板能力和示例代码
|
||
- 现有目录中存在一些当前业务未直接使用的模板模块，可在后续按需要继续裁剪
|
||
|
||
## 适合后续演进的方向
|
||
|
||
结合当前项目现状，后续工作更适合围绕以下方向展开：
|
||
|
||
- 梳理并精简模板残留代码
|
||
- 完善激活记录管理能力
|
||
- 增加导入、导出、删除、编辑等本地数据操作
|
||
- 统一页面文案、编码和可维护性
|
||
- 补充更明确的项目文档与交付说明
|
||
|
||
## 运行说明
|
||
|
||
### 开发环境
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
### 构建
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
Windows 安装包构建：
|
||
|
||
```bash
|
||
npm run build-w
|
||
```
|
||
|
||
## 补充说明
|
||
|
||
- 原仓库中的 `README.zh-CN.md` 更偏向上游模板说明
|
||
- 当前 `README.md` 旨在描述本项目自身，而不是 `electron-egg` 模板本身
|
||
- 如果后续继续迭代业务，建议优先维护本文件，保证项目文档与实际实现一致
|