# 授权信息功能 — 完整方案设计

> 本文档覆盖「付费授权」功能的产品决策、数据模型、API 设计、安全方案、前端方案及分期实施计划。所有编码工作在本文档评审通过后按计划分批推进。

---

## 1. 背景与目标

酒库管理系统是按门店付费授权的 SaaS：许可证绑定设备、支持试用/月付/年付/买断。但当前实现是空壳：

- 虽有 `licenses` 表和 4 个接口（activate/verify/deactivate/info），但**激活时完全不验签**，许可证密钥仅做 DB 存在性查询，防伪能力为零。
- `GenerateKey` 把 HMAC 截断到 20 字符后无法反向验签，且无任何地方调用它，激活码只能靠人工写入 DB。
- 注册时不自动发试用许可，新门店开箱即「无授权」。
- license 路由未加 `AdminOnly`，普通员工可激活/解绑。
- 前端授权 Tab 仅只读展示；「续费」只弹邮箱；无过期拦截、无横幅、对应用行为零影响。
- 客户端无任何设备 ID 采集能力（未引入 device_info_plus）。

**目标**：建立完整的「签发 → 激活 → 校验 → 过期降级」闭环，兼顾安全（防伪造、防多机盗用）与用户体验（自助换机、清晰过期提示）。

---

## 2. 产品决策（已与产品方确认）

```yaml
试用期:
  触发: 注册成功自动签发
  时长: 30 天
  设备上限: 2 台

过期降级（宽限窗口）:
  day 0~+6:   宽限期（grace）  — 仍可读写，全局橙色横幅 + 启动弹窗提醒
  day +7~+14: 只读期（readonly）— 禁所有写操作，横幅+弹窗变红
  day +15~:   锁定期（locked） — 禁止登录，跳到激活/续费页
  配置项: LICENSE_GRACE_DAYS=7, LICENSE_LOCK_DAYS=15（在 config.go 中定义）

设备绑定:
  策略: 一证多设备（按套餐设上限）
  默认上限: trial=2, monthly/annual/lifetime=3（存 features.max_devices）
  换机: 用户可在授权 Tab 自助解绑旧设备后在新设备激活

防伪机制:
  算法: Ed25519 非对称签名
  私钥: 服务端持有（存 Bitwarden，rbw get license-ed25519-private）
  公钥: 客户端内置（编译期嵌入，无法通过 DB 泄露伪造新 key）
```

套餐类型（`licenses.type` 枚举不变）：`trial` / `monthly` / `annual` / `lifetime`

---

## 3. 数据模型

### 3.1 `licenses` 表改造

```sql
-- 新增字段（AutoMigrate 自动补）
ALTER TABLE licenses
  ADD COLUMN max_devices INT NOT NULL DEFAULT 3 AFTER is_active,
  ADD COLUMN license_token TEXT NOT NULL DEFAULT '' AFTER license_key;
  -- license_token: Ed25519 自包含 JWT 格式 token，激活时验签
  -- 原 device_id 列废弃：设备记录迁到 license_devices 表
  -- device_id / activated_at 列保留（向后兼容），新激活通过 license_devices
```

### 3.2 新表 `license_devices`

```sql
CREATE TABLE IF NOT EXISTS `license_devices` (
  `id`           BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  `license_id`   BIGINT UNSIGNED NOT NULL,
  `shop_id`      BIGINT UNSIGNED NOT NULL,
  `device_id`    VARCHAR(128)    NOT NULL COMMENT '设备唯一标识（客户端稳定 ID）',
  `device_name`  VARCHAR(200)    NOT NULL DEFAULT '' COMMENT '设备名称（主机名）',
  `platform`     VARCHAR(20)     NOT NULL DEFAULT '' COMMENT 'windows/macos/android/ios/web',
  `activated_at` DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `last_seen_at` DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_license_device` (`license_id`, `device_id`),
  KEY `idx_shop_id` (`shop_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='许可证设备绑定';
```

### 3.3 GORM Model 草案

```go
// backend/internal/model/license.go（改造）
type License struct {
    Base
    ShopID       uint64     `gorm:"not null;index"                        json:"shop_id"`
    LicenseKey   string     `gorm:"size:50;uniqueIndex"                   json:"license_key"`
    LicenseToken string     `gorm:"type:text"                             json:"-"` // Ed25519 token，不对外暴露
    Type         string     `gorm:"type:enum('trial','monthly','annual','lifetime');default:'trial'" json:"type"`
    ExpiresAt    *time.Time `                                              json:"expires_at"`
    IsActive     bool       `gorm:"default:true"                          json:"is_active"`
    MaxDevices   int        `gorm:"default:3"                             json:"max_devices"`
    Features     JSON       `gorm:"type:json"                             json:"features,omitempty"`
    ActivatedAt  *time.Time `                                              json:"activated_at"`
    // 废弃字段（保留列兼容旧数据）
    DeviceID     string     `gorm:"size:255"                              json:"-"`
    Devices      []LicenseDevice `gorm:"foreignKey:LicenseID"            json:"devices,omitempty"`
}

// backend/internal/model/license_device.go（新增）
type LicenseDevice struct {
    Base
    LicenseID   uint64    `gorm:"not null;index" json:"license_id"`
    ShopID      uint64    `gorm:"not null;index" json:"shop_id"`
    DeviceID    string    `gorm:"size:128;not null" json:"device_id"`
    DeviceName  string    `gorm:"size:200" json:"device_name"`
    Platform    string    `gorm:"size:20"  json:"platform"`
    ActivatedAt time.Time `                json:"activated_at"`
    LastSeenAt  time.Time `                json:"last_seen_at"`
}
```

---

## 4. License Token 格式（Ed25519 自包含）

License Token 采用 JWT 格式，算法字段 `"alg":"EdDSA"`：

```json
// header（base64url）
{ "alg": "EdDSA", "typ": "LIC" }

// payload（base64url）
{
  "shop_id":    12345,
  "lic_id":     67,
  "type":       "annual",
  "issued_at":  1748000000,
  "expires_at": 1779536000,   // unix；0 = 永久
  "max_devices": 3,
  "features":   { "finance": true }
}

// signature: Ed25519(header.payload, private_key)
```

激活时服务端用内置公钥验签；验签通过且 `shop_id` 与 JWT 一致后，将 license 记录与设备绑定。客户端可离线验证 token 格式与签名，防止任意字符串被当作有效 key。

---

## 5. 后端 API 设计

### 5.1 权限矩阵

| 接口 | 方法 | 路由 | JWT | AdminOnly | ReadOnly 拦截 |
|------|------|------|-----|-----------|--------------|
| 查询授权信息 | GET | `/license/info` | ✅ | ✗ | ✗ |
| 激活许可证 | POST | `/license/activate` | ✅ | **✅** | ✗（豁免） |
| 设备列表 | GET | `/license/devices` | ✅ | **✅** | ✗ |
| 解绑设备 | POST | `/license/devices/unbind` | ✅ | **✅** | ✗（豁免） |
| 解绑当前设备 | POST | `/license/deactivate` | ✅ | **✅** | ✗（豁免） |

> activate/deactivate/unbind 加 `AdminOnly`，防普通员工操作许可证。

### 5.2 GET /license/info

新增返回字段：

```json
{
  "data": {
    "type": "annual",
    "is_active": true,
    "expires_at": "2027-06-09T00:00:00Z",
    "activated_at": "2026-06-09T00:00:00Z",
    "max_devices": 3,
    "bound_devices": 2,
    "phase": "normal",          // normal | grace | readonly | locked
    "days_remaining": 365,       // null = 永久；负数 = 已过期 N 天
    "current_device_bound": true // 当前请求设备是否已绑定（query: device_id）
  }
}
```

### 5.3 POST /license/activate

```json
// 请求体
{
  "license_key":  "XXXXX-XXXXX-XXXXX-XXXXX",
  "device_id":    "win-{machine-guid}",
  "device_name":  "JiuPC-01",
  "platform":     "windows"
}

// 成功响应
{ "data": { ...License, "devices": [...] } }

// 错误码
// 400: missing fields
// 403: license 不属于当前门店 / is_active=false
// 409: 设备数已达上限（提示先解绑）
// 422: token 验签失败（伪造 key）
// 410: license 已过期
```

**处理流程**：
1. 验证 Ed25519 签名，失败→422
2. 按 `license_key` 查记录，校验 `shop_id` 匹配 JWT 中 shopID，`is_active=true`
3. 检查过期；`expires_at` 已过→410
4. 查 `license_devices WHERE license_id=?` 计数，`>= max_devices` 且设备不在列表中→409
5. Upsert `license_devices`（同设备重复激活更新 `last_seen_at`），更新 `licenses.activated_at`

### 5.4 GET /license/devices

返回当前许可证绑定的设备列表（`devices[]`），每条含 `device_id, device_name, platform, activated_at, last_seen_at`。

### 5.5 POST /license/devices/unbind

```json
{ "device_id": "win-{machine-guid}" }
```

删除 `license_devices` 对应记录。仅管理员可操作。

---

## 6. 注册自动发 trial

在 `AuthService.Register` 事务内（`auth.go:92-132`）注册末尾注入：

```go
// 注入点：创建 user 之后，return nil 之前
trial := model.License{
    ShopID:       shop.ID,
    LicenseKey:   generateTrialKey(shop.ID),  // 简单格式，仅内部标识
    LicenseToken: licSvc.GenerateTrial(shop.ID, 30),  // 签发 30 天 Ed25519 token
    Type:         "trial",
    ExpiresAt:    ptr(time.Now().AddDate(0, 0, 30)),
    IsActive:     true,
    MaxDevices:   2,
}
tx.Create(&trial)
```

`LicenseService.GenerateTrial` 用 Ed25519 私钥签发一个 trial token，写入 `licenses` 表。激活该 trial 无需用户输入 key（Web 和 trial 设备自动激活，桌面端首次启动提示激活）。

---

## 7. 授权状态机与拦截层

### 7.1 Phase 推算

```go
// service/license.go
type Phase string
const (
    PhaseNormal   Phase = "normal"
    PhaseGrace    Phase = "grace"
    PhaseReadOnly Phase = "readonly"
    PhaseLocked   Phase = "locked"
)

func CalcPhase(expiresAt *time.Time) Phase {
    if expiresAt == nil { return PhaseNormal } // 永久
    diff := time.Since(*expiresAt)
    if diff < 0 { return PhaseNormal }
    if diff < 7*24*time.Hour  { return PhaseGrace }
    if diff < 15*24*time.Hour { return PhaseReadOnly }
    return PhaseLocked
}
```

### 7.2 后端 LicenseGuard 中间件

**复用 `ReadOnly()`（auth.go:63）模式**，挂到全局 `api` 路由组（紧跟 JWT + ReadOnly 之后）：

```go
// middleware/license.go
func LicenseGuard(licSvc *service.LicenseService) gin.HandlerFunc {
    return func(c *gin.Context) {
        shopID := GetShopID(c)
        phase := licSvc.GetPhase(shopID) // 查库或读 JWT claim（见下方）

        if phase == PhaseLocked {
            c.AbortWithStatusJSON(http.StatusForbidden, gin.H{
                "error": "license_locked",
                "phase": phase,
            })
            return
        }
        if phase == PhaseReadOnly && c.Request.Method != "GET" {
            // 豁免：activate/deactivate/unbind（让用户能续费）
            if !isLicenseManagementRoute(c.FullPath()) {
                c.AbortWithStatusJSON(http.StatusForbidden, gin.H{
                    "error": "license_readonly",
                    "phase": phase,
                })
                return
            }
        }
        c.Set("license_phase", string(phase))
        c.Next()
    }
}
```

**性能**：将 `expires_at` 写入 JWT Claim（扩展 `middleware.Claims`），避免每请求查库——续费后 refresh token 自动刷新 claim。

```go
type Claims struct {
    UserID    uint64     `json:"user_id"`
    ShopID    uint64     `json:"shop_id"`
    Role      string     `json:"role"`
    LicExpiry *time.Time `json:"lic_exp,omitempty"` // 新增
    jwt.RegisteredClaims
}
```

### 7.3 登录拦截 locked

在 `AuthHandler.Login` 成功发 token 之前，判断 phase；若 `locked` 返回 `403 license_locked`，前端跳续费页。

---

## 8. 前端方案

### 8.1 文件改动清单

| 文件 | 类型 | 说明 |
|------|------|------|
| `client/lib/models/license.dart` | 新增 | LicenseInfo + LicenseDevice 模型（从 provider 抽出并扩展） |
| `client/lib/repositories/license_repository.dart` | 新增 | 封装所有 license API 调用 |
| `client/lib/providers/license_provider.dart` | 修改 | 改接 repository；新增 phase/deviceId/devices 状态 |
| `client/lib/core/platform/device_id.dart` | 新增 | 采集设备 ID（device_info_plus + shared_preferences 持久化） |
| `client/pubspec.yaml` | 修改 | 添加 `device_info_plus` 依赖 |
| `client/lib/screens/settings/settings_screen.dart` | 修改 | 授权 Tab 重构（激活码 + 设备列表 + 解绑） |
| `client/lib/screens/shell/app_shell.dart` | 修改 | 注入 license 横幅 + 到期弹窗 |

### 8.2 设备 ID 采集策略

```dart
// client/lib/core/platform/device_id.dart
// kIsWeb 先于 dart:io，遵守项目规则
Future<String> getDeviceId() async {
  // Web：无稳定 ID，用 localStorage 存 UUID（随清 cookies 失效，可接受）
  if (kIsWeb) return _webId();
  return switch (defaultTargetPlatform) {
    TargetPlatform.windows => _windowsMachineGuid(),   // reg HKLM\...\MachineGuid
    TargetPlatform.macOS   => _macosSystemGuid(),      // IOPlatformUUID
    TargetPlatform.android => DeviceInfoPlugin().androidInfo.then((i) => i.id),
    TargetPlatform.iOS     => DeviceInfoPlugin().iosInfo.then((i) => i.identifierForVendor ?? _uuid()),
    _                      => _uuid(),                  // fallback
  };
}
// 首次生成后持久化到 shared_preferences，避免二次采集差异
```

### 8.3 授权 Tab 重构

**激活区**（`is_active=false` 或设备未绑定时展示）：
- 激活码输入框（格式提示 XXXXX-XXXXX-XXXXX-XXXXX）
- 「激活」按钮 → `POST /license/activate`
- 设备自动填入（device_name = hostname，platform 自动推断）

**当前授权信息**（已激活时展示）：
- 类型标签 + 状态 Chip（正常/宽限/只读/已锁定）+ 到期时间 / 「永久有效」
- 已绑设备数 `n / max_devices`
- 设备列表卡片：设备名、平台图标、激活时间、「解绑」按钮（当前设备标记为「此设备」）
- 「续费 / 升级授权」入口（保留现有联系邮箱逻辑，后续可升为在线续费）

### 8.4 全局横幅与弹窗（app_shell.dart）

**复用更新横幅模式**（app_shell.dart:300-352）：

```dart
// grace 期：橙色横幅（可关闭）
if (licPhase == 'grace')
  Container(color: Color(0xFFFFF3E0), child: Row([
    Icon(Icons.warning_amber, color: Color(0xFFE65100)),
    Text('授权将在 $daysOverdue 天后进入只读模式，请及时续费'),
    TextButton('立即续费', onTap: _showRenewDialog),
    TextButton('稍后', onTap: _dismiss),
  ]))

// readonly 期：红色横幅（不可关闭）
if (licPhase == 'readonly')
  Container(color: Color(0xFFFFEBEE), child: Row([
    Icon(Icons.lock_outline, color: Colors.red),
    Text('授权已过期，当前为只读模式，无法写入数据'),
    TextButton('立即续费', onTap: _showRenewDialog),
  ]))
```

**启动弹窗**（`addPostFrameCallback`，类似强制更新弹窗）：
- grace/readonly 首次进入 shell 弹一次，当天不再重弹（`shared_preferences` 记录最后弹窗日期）

---

## 9. 安全与威胁模型

### 9.1 Ed25519 签发/验签流程

```
[运营工具] rbw get license-ed25519-private → go run tools/license-gen/main.go
    --shop-id 12345 --type annual --days 365 --max-devices 3
→ 生成 LicenseToken（Ed25519 签名） + LicenseKey（可读短码）
→ 写入 licenses 表（或导出给客户）

[激活时] POST /license/activate
    → 服务端读取内置公钥（config.C.License.Ed25519PublicKey，base64）
    → ed25519.Verify(publicKey, header.payload, signature)
    → 通过 → 绑设备
```

私钥**仅**存 Bitwarden，`rbw get license-ed25519-private`；服务端只存公钥（可公开）。即便服务端被拖库，攻击者也无法签发新许可证。

### 9.2 威胁模型与对策

| 威胁 | 对策 |
|------|------|
| 伪造 license key | Ed25519 验签，无私钥无法生成有效签名 → 激活返回 422 |
| 篡改 token 内容（改 expires_at）| 签名覆盖 payload，任何篡改导致验签失败 |
| 多机盗用（key 泄露） | `max_devices` 上限 + 按设备计数，超限拒绝 |
| 拖库后批量伪造 | 私钥不落库，公钥验签流程无私钥无用 |
| 修改本地系统时钟绕过过期 | `phase` 由**服务端**推算后写入 JWT，客户端无法单方面伪造 |
| 普通员工自行激活/解绑 | activate/deactivate/unbind 加 `AdminOnly` |
| 已吊销 license 继续使用 | `is_active=false` → `LicenseGuard` 拦截 + 联网校验时生效 |

---

## 10. 分期实施计划

以下每项作为独立 todo，按依赖顺序排列：

| # | 标题 | tier | 依赖 | 模块 |
|---|------|------|------|------|
| A | 后端：Ed25519 签发工具 + 替换 GenerateKey + 激活验签 | 1 | 无 | 后端/安全 |
| B | 后端：新增 license_devices 表 + 设备绑定/列表/解绑 API | 1 | A | 后端/数据库 |
| C | 后端：注册自动发 30 天 trial（事务内注入） | 2 | A B | 后端 |
| D | 后端：LicenseGuard 中间件 + JWT claim 扩展 + 登录 locked 拦截 | 1 | B C | 后端/安全 |
| E | 前端：device_info_plus + device_id 采集模块 | 2 | 无（可与 A 并行） | 前端 |
| F | 前端：License model/repository 重构 + provider 对接 | 2 | E | 前端 |
| G | 前端：授权 Tab 重构（激活码输入 + 设备列表 + 解绑） | 2 | D F | 前端 |
| H | 前端：全局横幅 + 到期弹窗（app_shell gating） | 2 | D F | 前端 |

**并行窗口**：A 与 E 可同时开始；D 依赖 B/C；G/H 依赖 D/F，但可并行。

---

## 11. 验证方式

```bash
# 后端
export PATH="/opt/homebrew/bin:$PATH"
cd backend && go build ./... && go test ./... && go vet ./...

# 前端
cd client && flutter analyze --no-fatal-infos --no-fatal-warnings

# 端到端场景
# 1. 注册 → 自动拥有 trial license（/license/info 返回 type=trial, expires_at=+30d）
# 2. 修改 expires_at = now()-1d → phase=grace → 横幅显示 / 操作可写
# 3. 修改 expires_at = now()-8d → phase=readonly → 写操作返回 403 / 横幅红色
# 4. 修改 expires_at = now()-16d → phase=locked → 登录返回 403 license_locked
# 5. POST /license/activate with 伪造 key → 422 验签失败
# 6. 绑定超 max_devices → 409 提示先解绑
# 7. 管理员解绑设备 → 设备列表减少 → 可重新激活
```

---

*文档版本：v1.0 | 2026-06-09*