enterprise-saa-s-dashboard-design/ARCHITECTURE.md

设备管理平台Demo — 系统架构文档

本文档描述【设备管理平台Demo】的整体架构，涵盖设备管理、APP获取授权文件、设备主机激活三大核心功能。

设计目标：轻量级、本地可运行、新手友好

---

一、整体架构图

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 获取授权文件

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 表，包含设备运行的技术参数：

{
  "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 最终授权文件结构

{
  "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