pqs-9100_tool_client/README.md

# 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` 模板本身
- 如果后续继续迭代业务，建议优先维护本文件，保证项目文档与实际实现一致