# 授权码功能设计

## 1. 功能概述

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

## 2. 核心功能

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

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

### 2.3 激活验证
- 应用启动时自动验证授权状态
- 授权信息展示
- 授权失效处理

## 3. 数据模型

### 3.1 Authorization 表结构

```sql
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