ssq-desk/docs/04-功能迭代/授权码功能/授权码功能设计.md

授权码功能设计

1. 功能概述

授权码功能用于设备激活和授权验证，确保应用在授权设备上使用。

2. 核心功能

2.1 设备标识

• 基于主机名、用户目录、操作系统生成设备ID
• 使用 MD5 哈希确保唯一性和稳定性
• 设备ID与授权码绑定

2.2 授权码验证

• 授权码输入和格式验证
• 设备绑定（授权码与设备ID关联）
• 授权状态存储（SQLite 本地数据库）

2.3 激活验证

• 应用启动时自动验证授权状态
• 授权信息展示
• 授权失效处理

3. 数据模型

3.1 Authorization 表结构

CREATE TABLE IF NOT EXISTS `sys_authorization_code` (
  `id` INTEGER PRIMARY KEY AUTOINCREMENT,                    -- 主键ID
  `license_code` VARCHAR(100) NOT NULL,                       -- 授权码（唯一）
  `device_id` VARCHAR(100) NOT NULL,                          -- 设备ID（MD5哈希）
  `activated_at` DATETIME NOT NULL,                          -- 激活时间
  `expires_at` DATETIME NULL,                                 -- 过期时间（可选，NULL表示永不过期）
  `status` TINYINT NOT NULL DEFAULT 1,                        -- 状态（1:有效 0:无效）
  `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,  -- 创建时间
  `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,  -- 更新时间
  UNIQUE (`license_code`)                                     -- 授权码唯一索引
);

3.2 字段说明

• id: 主键ID，自增
• license_code: 授权码，唯一索引（UNIQUE约束）
• device_id: 设备ID（基于主机名、用户目录、操作系统生成的MD5哈希），通过 GORM 标签定义索引
• activated_at: 激活时间，必填
• expires_at: 过期时间，可选，NULL表示永不过期
• status: 状态（1:有效 0:无效），默认值为1
• created_at: 创建时间，自动设置为当前时间
• updated_at: 更新时间，自动更新为当前时间

3.3 索引说明

• license_code: 唯一索引（UNIQUE约束），用于快速查找和验证授权码
• 其他字段的索引通过 GORM 标签在模型定义中声明，由 GORM AutoMigrate 自动创建

4. API 接口

4.1 ActivateLicense

• 功能: 激活授权码
• 参数: licenseCode string
• 返回: 激活结果和授权状态

4.2 GetAuthStatus

• 功能: 获取当前授权状态
• 返回: 授权状态信息

4.3 GetDeviceID

• 功能: 获取设备ID
• 返回: 设备ID字符串

5. 实现架构

5.1 分层结构

API 层 (auth_api.go)
    ↓
Service 层 (auth_service.go)
    ↓
Repository 层 (auth_repository.go)
    ↓
Model 层 (authorization.go)
    ↓
SQLite 数据库

5.2 启动验证流程

应用启动
    ↓
初始化 SQLite
    ↓
初始化 AuthAPI
    ↓
检查授权状态
    ↓
未激活 → 提示用户激活
已激活 → 继续运行

6. 使用说明

6.1 激活授权

前端调用 ActivateLicense(licenseCode) 方法激活授权码。

6.2 检查状态

前端调用 GetAuthStatus() 方法获取授权状态，根据状态决定是否显示激活界面。

6.3 设备ID

调用 GetDeviceID() 获取设备ID，可用于授权码生成或问题排查。

---

文档维护者：JueChen
创建时间：2026-01-07