# 设备管理平台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*