222 lines
8.2 KiB
Markdown
222 lines
8.2 KiB
Markdown
# 设备管理平台Demo — 系统架构文档
|
||
|
||
> 本文档描述【设备管理平台Demo】的整体架构，涵盖设备管理、APP获取授权文件、设备主机激活三大核心功能。
|
||
>
|
||
> 设计目标：**轻量级、本地可运行、新手友好**
|
||
|
||
---
|
||
|
||
## 一、整体架构图
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph 客户端层 ["📱 客户端层"]
|
||
A[管理后台 Web端<br/>Next.js 14 + React + Tailwind CSS]
|
||
B[手机 APP<br/>HTTP 调用获取授权文件]
|
||
end
|
||
|
||
subgraph API层 ["🔗 API 层 (Next.js API Routes)"]
|
||
C1["设备 API<br/>/api/devices"]
|
||
C2["授权 API<br/>/api/licenses"]
|
||
C3["APP 授权下载<br/>/api/licenses/download"]
|
||
C4["配置 API<br/>/api/config-files"]
|
||
C5["维修/固件/报废 API"]
|
||
C6["物料/型号/BOM API"]
|
||
end
|
||
|
||
subgraph 核心业务层 ["⚙️ 核心业务层"]
|
||
D1["设备注册与生命周期管理"]
|
||
D2["授权文件生成引擎<br/>激活项 + 配置文件 → JSON + SHA256 数字签名"]
|
||
D3["双重授权匹配机制<br/>设备级优先 > 型号级"]
|
||
D4["设备技术参数配置管理"]
|
||
D5["维修工单 / 固件版本 / 报废流程"]
|
||
D6["物料管理 / BOM 清单 / 板卡类型"]
|
||
end
|
||
|
||
subgraph 数据层 ["🗄️ 数据层"]
|
||
E1[("SQLite<br/>本地文件数据库<br/>better-sqlite3")]
|
||
end
|
||
|
||
A -->|CRUD 操作| C1 & C2 & C4 & C5 & C6
|
||
B -->|GET ?sn=xxx| C3
|
||
|
||
C1 --> D1
|
||
C2 --> D2
|
||
C3 --> D3
|
||
C4 --> D4
|
||
C5 --> D5
|
||
C6 --> D6
|
||
|
||
D1 & D2 & D3 & D4 & D5 & D6 -->|SQL 读写| E1
|
||
```
|
||
|
||
---
|
||
|
||
## 二、各模块职责说明
|
||
|
||
### 1. 客户端层
|
||
|
||
| 模块 | 技术栈 | 职责 |
|
||
|------|--------|------|
|
||
| **管理后台 Web端** | Next.js 14 (App Router) + React + Tailwind CSS + lucide-react | 提供设备注册、授权配置、维修工单等全功能可视化管理界面。轻量级、单页应用体验，无需额外前端服务。 |
|
||
| **手机 APP** | 外部客户端（JavaScript 示例已提供） | 通过 `/api/licenses/download?sn=xxx` 接口，凭设备 SN 拉取授权文件 JSON，解析后启用对应功能模块。 |
|
||
|
||
### 2. API 层
|
||
|
||
| 接口路由 | 方法 | 核心职责 |
|
||
|----------|------|----------|
|
||
| `/api/devices` | GET / POST / PUT / DELETE | 设备全生命周期 CRUD：注册、列表、状态更新、删除。 |
|
||
| `/api/licenses` | GET / POST / PUT | 授权记录管理：创建授权时**自动生成带 SHA256 签名的 JSON 文件**，支持设备级/型号级双重模式。 |
|
||
| `/api/licenses/download` | GET | **APP 专用接口**：根据 SN 查询设备 → 优先匹配设备级授权 → fallback 型号级授权 → 返回 JSON 并记录下载日志。 |
|
||
| `/api/config-files` | GET / POST / PUT / DELETE | 设备技术参数模板管理，供授权文件关联引用。 |
|
||
| `/api/repair` `/firmware` `/scrap` | GET / POST / ... | 维修工单跟踪、固件版本发布、设备报废流程。 |
|
||
| `/api/models` `/materials` `/bom` | GET / POST / ... | 设备型号定义、物料入库/出库、BOM 清单与板卡版本兼容管理。 |
|
||
|
||
### 3. 核心业务层
|
||
|
||
| 模块 | 职责说明 |
|
||
|------|----------|
|
||
| **设备注册与生命周期** | 支持 SN 扫码/手动录入、生产批次选择、BOM 装配清单记录。状态流转：装配中 → 调试中 → 已激活 → 维修中 → 已报废。 |
|
||
| **授权文件生成引擎** | 保存授权时，将**激活项**（授权模块列表，如 1D/2D/3D/水上/跨孔/电流场法）与**配置文件**（发射参数、采集参数、网络参数）合并组装为 JSON，附加设备型号/SN/有效期后，计算 SHA256 数字签名防止篡改。 |
|
||
| **双重授权匹配机制** | APP 请求时先查 `device_sn` 精确匹配，无结果再按 `model` 匹配有效期内的型号级授权，确保灵活性。 |
|
||
| **配置管理** | 按设备型号维护技术参数配置，授权文件可关联具体配置 ID，实现不同批次设备的差异化参数下发。 |
|
||
| **维修/固件/报废** | 完整的售后支持流程：创建维修工单 → 记录故障与更换物料 → 固件升级 → 最终报废归档。 |
|
||
| **物料与 BOM** | 管理采集板、发射板、主板、电缆等物料的型号/版本/库存，BOM 支持多版本兼容（如两块采集板版本需一致）。 |
|
||
|
||
### 4. 数据层
|
||
|
||
| 组件 | 说明 |
|
||
|------|------|
|
||
| **SQLite (better-sqlite3)** | 轻量级本地文件数据库，零配置、开箱即用。数据库文件位于 `./data/app.db`，支持 WAL 模式提升并发性能。 |
|
||
| **自动迁移 (migrateDatabase)** | 启动时自动检测表结构变更，新增字段/新表无需手动执行 SQL。 |
|
||
| **Seed 数据 (seedIfEmpty)** | 首次运行时自动填充演示数据，新手可立即体验完整功能。 |
|
||
|
||
---
|
||
|
||
## 三、核心数据流：APP 获取授权文件
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
autonumber
|
||
participant APP as 手机APP
|
||
participant API as /api/licenses/download
|
||
participant DB as SQLite
|
||
participant LOG as 下载日志
|
||
|
||
APP->>API: GET ?sn=GD30-20260430-001
|
||
API->>DB: 查询 devices 表
|
||
DB-->>API: 返回设备信息
|
||
|
||
alt 存在设备级授权
|
||
API->>DB: SELECT * FROM licenses WHERE device_sn = ? AND status = '生效'
|
||
DB-->>API: 返回授权记录
|
||
else 无设备级授权
|
||
API->>DB: SELECT * FROM licenses WHERE model = ? AND status = '生效' AND expiry >= now
|
||
DB-->>API: 返回型号级授权
|
||
end
|
||
|
||
API->>API: 解析 license_file JSON<br/>更新 deviceSN 字段
|
||
API->>LOG: INSERT 下载日志<br/>(IP, UA, 时间)
|
||
API-->>APP: 返回授权 JSON
|
||
```
|
||
|
||
---
|
||
|
||
## 四、授权文件生成机制
|
||
|
||
授权文件由两大核心部分组合生成：
|
||
|
||
### 4.1 激活项（authModules）
|
||
|
||
来源于 `licenses.modules` 字段，表示该设备被授权启用的功能模块：
|
||
|
||
| 模块 ID | 模块名称 |
|
||
|---------|----------|
|
||
| `1D` | 一维自电/电阻率/激电测试模块 |
|
||
| `2D` | 二维自电/电阻率/激电测试模块 |
|
||
| `3D` | 三维自电/电阻率/激电测试模块 |
|
||
| `WATER` | 水上 |
|
||
| `CROSS` | 跨孔 |
|
||
| `CF` | 电流场法 |
|
||
|
||
每个模块在生成的 JSON 中以 `{ id, name, category, enabled: true }` 形式呈现。
|
||
|
||
### 4.2 配置文件（config）
|
||
|
||
来源于 `config_files` 表，包含设备运行的技术参数：
|
||
|
||
```json
|
||
{
|
||
"name": "GD30 标准配置",
|
||
"version": "v2.1",
|
||
"emissionParams": {
|
||
"maxVoltage": "1000V",
|
||
"maxCurrent": "5A",
|
||
"waveform": "50%",
|
||
"pulseWidth": "2s"
|
||
},
|
||
"acquisitionParams": {
|
||
"channels": 16,
|
||
"sampleRate": "1kHz",
|
||
"voltageRange": "±10V",
|
||
"fullWaveform": true
|
||
},
|
||
"networkParams": {
|
||
"wifiSSIDPrefix": "GD30-"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.3 最终授权文件结构
|
||
|
||
```json
|
||
{
|
||
"version": "1.0",
|
||
"generatedAt": "2026-05-07T10:00:00.000Z",
|
||
"deviceModel": "GD-30 Supreme",
|
||
"deviceSN": "GD30-20260430-001",
|
||
"validUntil": "2027-04-30",
|
||
"status": "active",
|
||
"authModules": [
|
||
{ "id": "1D", "name": "一维自电/电阻率/激电测试模块", "category": "一维", "enabled": true },
|
||
{ "id": "2D", "name": "二维自电/电阻率/激电测试模块", "category": "二维", "enabled": true }
|
||
],
|
||
"config": { ... },
|
||
"signature": {
|
||
"algorithm": "SHA256",
|
||
"value": "a1b2c3d4...",
|
||
"publicKey": "platform-public-key-placeholder"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、数据库核心表结构
|
||
|
||
| 表名 | 说明 |
|
||
|------|------|
|
||
| `devices` | 设备基本信息（SN、型号、状态、固件版本、生产批次等） |
|
||
| `licenses` | 授权记录（模块列表、有效期、状态、关联配置 ID、自动生成的 `license_file` JSON） |
|
||
| `config_files` | 设备技术参数配置模板 |
|
||
| `license_download_logs` | 授权下载审计日志 |
|
||
| `device_models` | 设备型号定义 |
|
||
| `repair_orders` | 维修工单 |
|
||
| `firmware` | 固件版本信息 |
|
||
| `scrap_records` | 报废记录 |
|
||
|
||
---
|
||
|
||
## 六、架构亮点
|
||
|
||
| 特性 | 说明 |
|
||
|------|------|
|
||
| **轻量本地运行** | 整个系统只需 `npm i && npm run dev`，SQLite 零配置，无需 Docker / 外接数据库。 |
|
||
| **新手友好** | 自动 Seed 数据 + 自动迁移，clone 下来即可看到完整功能的 Demo。 |
|
||
| **安全设计** | 授权文件含 SHA256 签名；下载日志完整审计（IP、UA、时间）。 |
|
||
| **APP 集成极简** | 一个 HTTP GET 请求即可获取授权 JSON，示例代码已在 README 中提供。 |
|
||
|
||
---
|
||
|
||
*文档生成时间：2026-05-07*
|