.

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

@@ -0,0 +1,114 @@
+# 授权码功能设计
+
+## 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