chore: release server-v1.0.60

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.claude/commands/todo.md

@@ -1,158 +0,0 @@
----
-description: 项目 TODO 管理（list / add / status / done / reject / reopen / rm / sub）
-argument-hint: "list | add <描述> | status <id> <open|doing|done> | done <id> [version] | reject <id> <原因> | reopen <id> | rm <id> | sub add <parent_id> ... | sub status <sid> ..."
-model: claude-sonnet-4-6
-allowed-tools: Bash, Read
----
-
-管理项目 `todo/todo.json` 待办清单，所有写操作会自动重渲染 `todo/todo.html`。
-
-**重要规则**：所有待办项必须通过本命令管理，禁止使用其它 todo 工具（TaskCreate/TodoWrite 等）。
-
-**状态流转**：`open`（待开始）→ `doing`（开发中）→ `done`（待验收）→ `accepted`（已验收）
-- `done` 状态可被用户 `reject`（拒绝），退回 `open` 并升为最高优先级
-- Claude 可设：`open` / `doing` / `done`；用户专属：`accepted`（`/todo done`）、`reject`
-
-**子任务（subtask）**：复杂任务（tier-1/2）可拆出子任务，SID 格式为 `{parentId}{Letter}`（如 `21A`、`21B`）。
-- 父任务在子任务全部 `done` 前**不得**手动设为 `done`；全部完成时**自动**转为 `done`
-- 子任务状态与父任务独立，自身有 `open` / `doing` / `done` 三态
-- 子任务可声明依赖（`deps`），HTML 中以绿/红徽章展示依赖完成情况
-
----
-
-## 改动等级 (tier) 与开发流程
-
-每个 todo 有两个独立维度：**重要度 `level`**（优先级高低）和 **改动等级 `tier`**（复杂度/工作量）。
-
-| tier | 名称 | 判定标准 | 开发流程 |
-|------|------|---------|---------|
-| 1 | 一级 | 涉及接口设计 / 数据库 schema 变更，**或**改动跨越 **2 个以上模块** | **必须先进 plan 模式**，用户批准方案后才能编码；完成后同步更新 `docs/architecture/`、`docs/api/` 等设计文档 |
-| 2 | 二级 | 模块内较大改动，涉及 **5 个文件以上** | 可直接开发，完成后本地验证（build/test/analyze） |
-| 3 | 三级 | 小改动、局部优化、bugfix | 可直接开发，完成后本地验证 |
-
-**判定关键词指引：**
-- 一级：「新增接口」「改 schema」「新表」「跨模块」「涉及后端+前端」「新增 API」
-- 二级：「重构」「整页改版」「涉及多个 screen」「较大」
-- 三级：「修复」「bugfix」「优化」「调整文案」「小改」「单文件」
-
-**重要**：开发完成后只做本地验证（build / test / analyze），**不要**自动触发 `/release`。发版由用户决定。
-
----
-
-根据 `$ARGUMENTS` 分派，缺省等同 `list`：
-
-## list（或无参数）
-
-运行以下命令并将终端 summary 转述给用户，同时提示 HTML 路径便于浏览：
-
-```bash
-node todo/todo.mjs list
-```
-
-## add <描述>
-
-将 `$ARGUMENTS` 去掉首词 `add` 后的内容解析为待办描述，推断：
-- `--title`：核心一句话标题（简洁，去掉平台/类别信息）
-- `--level`：`high`（阻断/紧急）/ `mid`（重要，默认）/ `low`（一般/优化）
-  - 关键词「紧急」「阻断」「必须」「严重」→ high；「重要」「需要」→ mid；其余 → low
-- `--tier`：**必须推断**，见上方「改动等级」判定标准，取值 `1`/`2`/`3`
-- `--tags`：从描述推断平台/类别，可多个逗号分隔，常用值：`前端,后端,Web,mac,Windows,Android,iOS,数据库,CI/CD,文档`
-- `--desc`：补充说明（可选，如有具体文件/路径/上下文则填入）
-
-然后运行：
-```bash
-node todo/todo.mjs add --title "..." --level mid --tier 2 --tags "前端,Web" --desc "..."
-```
-
-转述：「已添加 #id [级别·等级] 标题  标签」，并显示 summary。
-
-## status <id> <open|doing|done>
-
-**Claude 在开发过程中主动调用**，更新条目的开发状态：
-- 开始处理某个 todo → `status <id> doing`（**先确认 tier**：一级须先 plan 模式，二/三级直接开发）
-- 开发完成提交验收 → `status <id> done`
-- 退回重做 → `status <id> open`
-
-```bash
-node todo/todo.mjs status <id> <open|doing|done>
-```
-
-转述：「#id 状态已更新为 xxx」，并显示 summary。
-注意：`accepted` 不可通过此命令设置，仅用户可标记。
-
-## done <id> [version]
-
-**用户调用**，标记条目已验收交付，记录版本号。从 `$ARGUMENTS` 提取 id 和可选 version（格式 vX.Y.Z）：
-
-- 有 version：`node todo/todo.mjs done <id> --version <version>`
-- 无 version：`node todo/todo.mjs done <id>`（脚本自动用 `git describe --tags --abbrev=0`）
-
-转述：「#id 已验收，记入版本 vX.Y.Z」，并显示 summary。
-
-## reject <id> <原因>
-
-**用户调用**，拒绝验收处于 `done` 状态的条目。拒绝后：
-- 状态退回 `open`
-- 优先级强制升为 `high`
-- 拒绝原因记录在条目上，HTML 卡片中可见
-
-从 `$ARGUMENTS` 提取 id 和原因文字：
-
-```bash
-node todo/todo.mjs reject <id> --reason "<原因>"
-```
-
-转述：「#id 已拒绝，优先级升为最高，原因：xxx」，并显示 summary。
-
-## reopen <id>
-
-重新开启条目（清空拒绝记录和验收信息），退回 `open` 状态：
-
-```bash
-node todo/todo.mjs reopen <id>
-```
-
-转述「#id 已重新开启」。
-
-## rm <id>
-
-```bash
-node todo/todo.mjs rm <id>
-```
-
-转述「#id 已删除」。
-
----
-
-## sub add <parent_id> --title "..." [--tier N] [--deps "21A,21B"]
-
-**Claude 在开发过程中主动调用**，为复杂任务（tier-1/2）添加子任务：
-- `parent_id`：父任务数字 id（如 `21`）
-- `--title`：子任务标题
-- `--tier`：改动等级（`1`/`2`/`3`，默认 `2`）
-- `--deps`：依赖的其他子任务 SID，逗号分隔（如 `"21A,21B"`）；被依赖项必须已存在
-
-SID 自动分配：第一个子任务为 `{parent_id}A`，依此类推（21A, 21B, 21C…）。
-父任务若为 `open` 状态，添加第一个子任务时自动升为 `doing`。
-
-```bash
-node todo/todo.mjs sub add <parent_id> --title "..." [--tier N] [--deps "21A,21B"]
-```
-
-转述：「已添加子任务 {SID} [等级]「{title}」→ #parent  依赖: ...」，并显示 summary。
-
-## sub status <sid> <open|doing|done>
-
-**Claude 在开发过程中主动调用**，更新子任务状态：
-- SID 格式：`21A`、`21B`（不区分大小写）
-- 当**最后一个子任务**标记为 `done` 时，父任务**自动**转为 `done`
-
-```bash
-node todo/todo.mjs sub status <sid> <open|doing|done>
-```
-
-转述：「{SID}「{title}」→ {状态}」，若触发父任务自动转换则一并提示。
-
----
-
-所有命令完成后，在终端显示来自脚本的完整 summary（按 open / doing / done / accepted 分组）。

.mcp.json

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "figma": {
-      "type": "http",
-      "url": "https://mcp.figma.com/mcp"
-    }
-  }
-}

CHANGELOG-server.md

@@ -5,7 +5,16 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.59] - 2026-06-19
+## [1.0.60] - 2026-06-19
+
+### 新功能
+- 激活码升级为「时长兑换券」：每张码代表一段时长（如 +1 年 / +6 个月），兑换后叠加到当前授权之后，可购买多张累计续期；过期后兑换则从兑换当天重新起算
+- 激活码改为简短易输入的形式（形如 JIUKU-XXXX-XXXX），告别此前需复制粘贴的超长字符串
+- 同一张激活码只能被成功兑换一次，重复或无效的码会明确提示
+
+### 改进
+- 续费/兑换成功后授权状态即时刷新，无需退出重新登录
+- 新门店首次使用仍自动获得 30 天试用，开箱即用
 
 ### 新功能
 - 会话安全加固：刷新令牌每次续期自动轮换并具备盗用检测，旧令牌一旦被重放即吊销整条会话；新增失败登录记录便于审计风控

CLAUDE.md

@@ -324,10 +324,11 @@ CI/CD（Forgejo）按 tag 前缀触发对应 workflow，自动：编译 → 测
 
 ### 项目 TODO 管理
 
-**本项目已停用 todo。** 即便全局 `~/.claude/CLAUDE.md` 要求用 `/todo` 记录待办，**本项目一律不记 todo、不调用 `/todo`、不创建 `todo/` 数据**（此项目规则覆盖全局规则）。需要追踪的事项直接在对话里说明即可。
+**统一使用全局 todo 工具**（`~/.claude/skills/todo/`，遵循全局 `~/.claude/CLAUDE.md` 的规则）。本项目**不再维护自己的 `/todo` slash command**（已删除），一律调用全局 todo skill。
 
-- **改动等级仍把控**：接口/schema/跨 2+ 模块的「大改」先进 plan 模式经用户批准，完成后同步更新设计文档；小 bugfix 直接做。
-- 仍**禁止**使用 TaskCreate/TodoWrite 等内置 todo 工具。
+- **数据落地**：全局 skill 把待办存到**当前项目**的 `todo/` 目录（`todo.json` + 看板 `todo/todo.html`，首次使用自动创建）；命令须在项目根目录运行，例如 `node ~/.claude/skills/todo/todo.mjs list`。
+- **禁止**使用 TaskCreate / TodoWrite 等任何内置 todo 工具，一律走全局 todo skill。
+- **改动等级把控**：接口/schema/跨 2+ 模块的「大改」先进 plan 模式经用户批准，完成后同步更新设计文档；小 bugfix 直接做。
 
 ---
 

backend/cmd/gencode/main.go

@@ -0,0 +1,90 @@
+// gencode — 平台方批量生成兑换券（激活码）并写入码池 license_codes。
+//
+// 用法（在 backend/ 目录下执行，读 config/env 取数据库 DSN）：
+//
+//	go run ./cmd/gencode -type annual -days 365 -count 100 -batch 2026-summer
+//	go run ./cmd/gencode -days 30 -count 10 -note "试用补偿"
+//	go run ./cmd/gencode -type lifetime -days 0 -count 1        # 永久授权码
+//
+// 生成的码以 JIUKU-XXXX-XXXX 格式打印（status=unused），分发给用户在 App 内兑换。
+package main
+
+import (
+	"flag"
+	"fmt"
+	stdlog "log"
+	"os"
+	"time"
+
+	"gorm.io/driver/mysql"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+
+	"github.com/wangjia/jiu/backend/config"
+	"github.com/wangjia/jiu/backend/internal/model"
+	"github.com/wangjia/jiu/backend/internal/util"
+)
+
+func main() {
+	licType := flag.String("type", "annual", "计费/时长标签：trial|monthly|annual|lifetime")
+	tier := flag.String("tier", "standard", "档位（当前仅 standard）")
+	days := flag.Int("days", 365, "授予时长（天）；0 = 永久")
+	devices := flag.Int("devices", 0, "授予设备上限；0 = 兑换时不改变门店现值")
+	count := flag.Int("count", 1, "生成数量")
+	batch := flag.String("batch", "", "发放批次/活动名（便于追踪）")
+	note := flag.String("note", "", "备注")
+	flag.Parse()
+
+	if *count < 1 {
+		fmt.Fprintln(os.Stderr, "error: -count 必须 >= 1")
+		os.Exit(1)
+	}
+
+	config.Load()
+	db, err := gorm.Open(mysql.Open(config.C.Database.DSN), &gorm.Config{
+		Logger: logger.New(
+			stdlog.New(os.Stdout, "\r\n", stdlog.LstdFlags),
+			logger.Config{LogLevel: logger.Warn, IgnoreRecordNotFoundError: true},
+		),
+	})
+	if err != nil {
+		stdlog.Fatalf("连接数据库失败: %v", err)
+	}
+	if err := db.AutoMigrate(&model.LicenseCode{}); err != nil {
+		stdlog.Fatalf("迁移 license_codes 失败: %v", err)
+	}
+
+	display := make([]string, 0, *count)
+	for i := 0; i < *count; i++ {
+		// 重试避免极小概率的唯一冲突
+		var shown string
+		for attempt := 0; attempt < 5; attempt++ {
+			shown = util.GenerateRedeemCode()
+			lc := model.LicenseCode{
+				Code:         util.NormalizeCode(shown),
+				Type:         *licType,
+				Tier:         *tier,
+				DurationDays: *days,
+				MaxDevices:   *devices,
+				Status:       "unused",
+				Batch:        *batch,
+				Note:         *note,
+			}
+			err := db.Create(&lc).Error
+			if err == nil {
+				break
+			}
+			if attempt == 4 {
+				stdlog.Fatalf("写入兑换码失败（连续冲突）: %v", err)
+			}
+		}
+		display = append(display, shown)
+	}
+
+	fmt.Printf("\n✅ 已生成 %d 个兑换码（type=%s tier=%s 时长=%d天 设备=%d batch=%q）于 %s：\n\n",
+		*count, *licType, *tier, *days, *devices, *batch, time.Now().Format("2006-01-02 15:04:05"))
+	for _, c := range display {
+		fmt.Println("   " + c)
+	}
+	fmt.Println()
+}

backend/cmd/genkey/main.go

@@ -1,59 +0,0 @@
-// genkey generates an Ed25519 keypair for license signing.
-// Run once; store the private key in Bitwarden and set the public key in config.
-//
-// Usage: go run ./cmd/genkey
-package main
-
-import (
-	"encoding/json"
-	"fmt"
-	"os"
-	"time"
-
-	"github.com/wangjia/jiu/backend/internal/util"
-)
-
-func main() {
-	priv, pub, err := util.GenerateEd25519KeyPair()
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "failed to generate keypair: %v\n", err)
-		os.Exit(1)
-	}
-
-	fmt.Println("=== Ed25519 License Keypair ===")
-	fmt.Println()
-	fmt.Println("[Bitwarden] Private key (keep secret, never commit):")
-	fmt.Println(priv)
-	fmt.Println()
-	fmt.Println("[Config / LICENSE_ED25519_PUBLIC_KEY] Public key:")
-	fmt.Println(pub)
-	fmt.Println()
-
-	// Demo: issue and verify a sample token to confirm the keypair works
-	now := time.Now()
-	exp := now.Add(30 * 24 * time.Hour).Unix()
-	sample := util.LicensePayload{
-		ShopID:     1,
-		LicenseID:  1,
-		Type:       "trial",
-		IssuedAt:   now.Unix(),
-		ExpiresAt:  &exp,
-		MaxDevices: 3,
-	}
-	token, err := util.IssueLicenseToken(sample, priv)
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "demo sign failed: %v\n", err)
-		os.Exit(1)
-	}
-	verified, err := util.VerifyLicenseToken(token, pub)
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "demo verify failed: %v\n", err)
-		os.Exit(1)
-	}
-	out, _ := json.MarshalIndent(verified, "", "  ")
-	fmt.Println("[Demo] Sample token (30-day trial, shop_id=1):")
-	fmt.Println(token)
-	fmt.Println()
-	fmt.Println("[Demo] Verified payload:")
-	fmt.Println(string(out))
-}

backend/cmd/issue/main.go

@@ -1,72 +0,0 @@
-// issue signs a license token for a specific shop.
-// Usage: go run ./cmd/issue -shop 1 -days 365 -type annual -key <base64-private-key>
-// Or use env var: LICENSE_ED25519_PRIVATE_KEY=<key> go run ./cmd/issue -shop 1 -days 365
-package main
-
-import (
-	"encoding/json"
-	"flag"
-	"fmt"
-	"os"
-	"time"
-
-	"github.com/wangjia/jiu/backend/internal/util"
-)
-
-func main() {
-	shopID := flag.Uint64("shop", 0, "shop ID (required)")
-	licenseID := flag.Uint64("license", 0, "license record ID (optional, 0 = omit)")
-	days := flag.Int("days", 365, "validity days; 0 = perpetual (no expiry)")
-	licType := flag.String("type", "annual", "license type: trial | annual | lifetime")
-	maxDevices := flag.Int("devices", 3, "max devices")
-	privKey := flag.String("key", "", "Ed25519 private key (base64); falls back to LICENSE_ED25519_PRIVATE_KEY env")
-	flag.Parse()
-
-	if *shopID == 0 {
-		fmt.Fprintln(os.Stderr, "error: -shop is required")
-		flag.Usage()
-		os.Exit(1)
-	}
-
-	key := *privKey
-	if key == "" {
-		key = os.Getenv("LICENSE_ED25519_PRIVATE_KEY")
-	}
-	if key == "" {
-		fmt.Fprintln(os.Stderr, "error: provide -key or set LICENSE_ED25519_PRIVATE_KEY")
-		os.Exit(1)
-	}
-
-	now := time.Now()
-	payload := util.LicensePayload{
-		ShopID:     *shopID,
-		Type:       *licType,
-		IssuedAt:   now.Unix(),
-		MaxDevices: *maxDevices,
-	}
-	if *licenseID > 0 {
-		payload.LicenseID = *licenseID
-	}
-	if *days > 0 {
-		exp := now.Add(time.Duration(*days) * 24 * time.Hour).Unix()
-		payload.ExpiresAt = &exp
-	}
-
-	token, err := util.IssueLicenseToken(payload, key)
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "sign failed: %v\n", err)
-		os.Exit(1)
-	}
-
-	out, _ := json.MarshalIndent(payload, "", "  ")
-	fmt.Println("=== License Token ===")
-	fmt.Println(token)
-	fmt.Println()
-	fmt.Println("=== Payload ===")
-	fmt.Println(string(out))
-	if payload.ExpiresAt != nil {
-		fmt.Printf("\nExpires: %s\n", time.Unix(*payload.ExpiresAt, 0).Format("2006-01-02 15:04:05"))
-	} else {
-		fmt.Println("\nExpires: never (perpetual)")
-	}
-}

backend/cmd/seed/main.go

@@ -26,6 +26,7 @@ var allModels = []any{
 	&model.Shop{},
 	&model.User{},
 	&model.License{},
+	&model.LicenseCode{},
 	&model.ProductCategory{},
 	&model.Product{},
 	&model.ProductNameOption{},

backend/config/config.go

@@ -11,7 +11,6 @@ type Config struct {
 	Server   ServerConfig
 	Database DatabaseConfig
 	JWT      JWTConfig
-	License  LicenseConfig
 	Storage  StorageConfig
 	Session  SessionConfig
 }
@@ -34,12 +33,6 @@ type JWTConfig struct {
 	RefreshExpireH  int    `mapstructure:"refresh_expire_h"`  // Refresh Token 有效小时数
 }
 
-type LicenseConfig struct {
-	HMACSecret       string `mapstructure:"hmac_secret"`        // legacy, kept for backward compat
-	Ed25519PublicKey  string `mapstructure:"ed25519_public_key"`  // base64 Ed25519 public key for token verification
-	Ed25519PrivateKey string `mapstructure:"ed25519_private_key"` // base64 Ed25519 private key for token signing (keep in Bitwarden)
-}
-
 // SessionConfig 登录会话与并发限制（全局默认，可被每店 session_policy 覆盖）。
 type SessionConfig struct {
 	LimitDesktop int `mapstructure:"limit_desktop"` // 桌面端(win/mac/linux)最大并发会话，0=禁止
@@ -72,9 +65,6 @@ func Load() {
 	// 显式绑定没有默认值的 key，确保 AutomaticEnv 能找到对应 env var
 	_ = viper.BindEnv("database.dsn", "DATABASE_DSN")
 	_ = viper.BindEnv("jwt.secret", "JWT_SECRET")
-	_ = viper.BindEnv("license.hmac_secret", "LICENSE_HMAC_SECRET")
-	_ = viper.BindEnv("license.ed25519_public_key", "LICENSE_ED25519_PUBLIC_KEY")
-	_ = viper.BindEnv("license.ed25519_private_key", "LICENSE_ED25519_PRIVATE_KEY")
 	_ = viper.BindEnv("storage.upload_dir", "STORAGE_UPLOAD_DIR")
 	_ = viper.BindEnv("storage.base_url", "STORAGE_BASE_URL")
 	_ = viper.BindEnv("storage.public_url", "STORAGE_PUBLIC_URL")

backend/internal/handler/auth_test.go

@@ -11,10 +11,8 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
-	"github.com/wangjia/jiu/backend/config"
 	"github.com/wangjia/jiu/backend/internal/middleware"
 	"github.com/wangjia/jiu/backend/internal/service"
-	"github.com/wangjia/jiu/backend/internal/util"
 	"github.com/wangjia/jiu/backend/testutil"
 )
 
@@ -301,16 +299,13 @@ func TestAuthHandler_Login_ResponseContainsUserInfo(t *testing.T) {
 // #8 心跳 /auth/ping 回带授权概况，客户端据此免去单独轮询 /license/info。
 func TestAuthHandler_Ping_ReturnsLicense(t *testing.T) {
 	db := testutil.SetupTestDB()
-	priv, _, err := util.GenerateEd25519KeyPair()
-	require.NoError(t, err)
-	config.C.License.Ed25519PrivateKey = priv
 
 	shop := testutil.CreateTestShop(db, "AHPING")
 	testutil.CreateTestUser(db, shop.ID, "admin", "password123", "admin")
 
 	authSvc := service.NewAuthService(db)
 	// 登录触发首登自动 trial。
-	_, _, err = authSvc.Login("AHPING", "admin", "password123", service.DeviceInfo{Platform: "windows"})
+	_, _, err := authSvc.Login("AHPING", "admin", "password123", service.DeviceInfo{Platform: "windows"})
 	require.NoError(t, err)
 
 	licSvc := service.NewLicenseService(db)

backend/internal/handler/license.go

@@ -17,11 +17,12 @@ func NewLicenseHandler(svc *service.LicenseService) *LicenseHandler {
 	return &LicenseHandler{svc: svc}
 }
 
-// Activate POST /api/v1/license/activate
+// Activate POST /api/v1/license/activate — 兑换激活码（时长券），把时长叠加到门店授权。
+// 路由名保留 activate 以兼容客户端；内部走 Redeem 逻辑。
 func (h *LicenseHandler) Activate(c *gin.Context) {
 	shopID := middleware.GetShopID(c)
 	var req struct {
-		LicenseKey string `json:"license_key" binding:"required"`
+		LicenseKey string `json:"license_key" binding:"required"` // 承载激活码（短码）
 		DeviceID   string `json:"device_id" binding:"required"`
 		DeviceName string `json:"device_name"`
 		Platform   string `json:"platform"`
@@ -31,7 +32,7 @@ func (h *LicenseHandler) Activate(c *gin.Context) {
 		return
 	}
 
-	lic, err := h.svc.Activate(shopID, req.LicenseKey, req.DeviceID, req.DeviceName, req.Platform)
+	lic, err := h.svc.Redeem(shopID, req.LicenseKey, req.DeviceID, req.DeviceName, req.Platform)
 	if err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return

backend/internal/handler/license_test.go

@@ -19,28 +19,32 @@ func TestLicenseHandler_Activate_Success(t *testing.T) {
 	token := getAuthToken(user.ID, shop.ID, "admin")
 	r := setupProtectedRouter(db)
 
-	expiry := time.Now().Add(30 * 24 * time.Hour)
-	lic := &model.License{
-		ShopID:     shop.ID,
-		LicenseKey: "LHACT-BBBBB-CCCCC-DDDDD",
-		IsActive:   true,
-		ExpiresAt:  &expiry,
-		MaxDevices: 3,
-	}
-	require.NoError(t, db.Create(lic).Error)
+	// 码池里放一张未用兑换码（30 天）
+	require.NoError(t, db.Create(&model.LicenseCode{
+		Code: "JIUKUTEST0001", Type: "annual", Tier: "standard",
+		DurationDays: 30, MaxDevices: 3, Status: "unused",
+	}).Error)
 
+	// 请求带连字符/会被归一化为 JIUKUTEST0001
 	w := makeRequest(r, "POST", "/api/v1/license/activate", token, map[string]interface{}{
-		"license_key": "LHACT-BBBBB-CCCCC-DDDDD",
+		"license_key": "JIUKU-TEST-0001",
 		"device_id":   "device-123",
 		"device_name": "Test Machine",
 		"platform":    "windows",
 	})
 	assert.Equal(t, http.StatusOK, w.Code)
 
-	// Verify device was recorded in license_devices
+	// 兑换后门店生成授权行 + 设备绑定
+	var lic model.License
+	require.NoError(t, db.Where("shop_id = ?", shop.ID).First(&lic).Error)
 	var dev model.LicenseDevice
 	require.NoError(t, db.Where("license_id = ? AND device_id = ?", lic.ID, "device-123").First(&dev).Error)
 	assert.Equal(t, "Test Machine", dev.DeviceName)
+
+	// 码被标记已用
+	var lc model.LicenseCode
+	require.NoError(t, db.Where("code = ?", "JIUKUTEST0001").First(&lc).Error)
+	assert.Equal(t, "redeemed", lc.Status)
 }
 
 func TestLicenseHandler_Activate_MissingFields(t *testing.T) {
@@ -84,40 +88,31 @@ func TestLicenseHandler_Activate_DeviceLimitExceeded(t *testing.T) {
 	token := getAuthToken(user.ID, shop.ID, "admin")
 	r := setupProtectedRouter(db)
 
+	// 既有授权：1 个设备名额已占满
+	future := time.Now().Add(30 * 24 * time.Hour)
 	lic := &model.License{
-		ShopID: shop.ID, LicenseKey: "LHBND-BBBBB-CCCCC-DDDDD", IsActive: true, MaxDevices: 1,
+		ShopID: shop.ID, LicenseKey: "TRIAL-LH004", IsActive: true, MaxDevices: 1, ExpiresAt: &future,
 	}
 	require.NoError(t, db.Create(lic).Error)
-	// Fill the single allowed slot
 	require.NoError(t, db.Create(&model.LicenseDevice{
 		LicenseID: lic.ID, ShopID: shop.ID, DeviceID: "existing-device",
 	}).Error)
+	// 码不提升设备上限（max_devices=0）
+	require.NoError(t, db.Create(&model.LicenseCode{
+		Code: "JIUKUDEVLIMIT1", Type: "annual", Tier: "standard",
+		DurationDays: 365, MaxDevices: 0, Status: "unused",
+	}).Error)
 
 	w := makeRequest(r, "POST", "/api/v1/license/activate", token, map[string]interface{}{
-		"license_key": "LHBND-BBBBB-CCCCC-DDDDD",
+		"license_key": "JIUKU-DEVL-IMIT1",
 		"device_id":   "different-device",
 	})
 	assert.Equal(t, http.StatusBadRequest, w.Code)
-}
 
-func TestLicenseHandler_Activate_Expired(t *testing.T) {
-	db := testutil.SetupTestDB()
-	shop := testutil.CreateTestShop(db, "LH005")
-	user := testutil.CreateTestUser(db, shop.ID, "admin", "pass", "admin")
-	token := getAuthToken(user.ID, shop.ID, "admin")
-	r := setupProtectedRouter(db)
-
-	expiry := time.Now().Add(-24 * time.Hour)
-	lic := &model.License{
-		ShopID: shop.ID, LicenseKey: "LHEXP-BBBBB-CCCCC-DDDDD", IsActive: true, ExpiresAt: &expiry, MaxDevices: 3,
-	}
-	require.NoError(t, db.Create(lic).Error)
-
-	w := makeRequest(r, "POST", "/api/v1/license/activate", token, map[string]interface{}{
-		"license_key": "LHEXP-BBBBB-CCCCC-DDDDD",
-		"device_id":   "device-123",
-	})
-	assert.Equal(t, http.StatusBadRequest, w.Code)
+	// 设备超限 → 整笔回滚：码仍未使用
+	var lc model.LicenseCode
+	require.NoError(t, db.Where("code = ?", "JIUKUDEVLIMIT1").First(&lc).Error)
+	assert.Equal(t, "unused", lc.Status)
 }
 
 func TestLicenseHandler_Activate_NoAuth(t *testing.T) {

backend/internal/middleware/license_guard_test.go

@@ -60,7 +60,7 @@ func TestLicenseGuardUsesLiveDBPhase(t *testing.T) {
 		id INTEGER PRIMARY KEY AUTOINCREMENT,
 		created_at DATETIME, updated_at DATETIME, deleted_at DATETIME,
 		shop_id INTEGER NOT NULL,
-		license_key TEXT, type TEXT, expires_at DATETIME,
+		license_key TEXT, type TEXT, tier TEXT DEFAULT 'standard', expires_at DATETIME,
 		is_active INTEGER DEFAULT 1, max_devices INTEGER DEFAULT 3,
 		features TEXT, device_id TEXT, activated_at DATETIME
 	)`).Error)
@@ -125,7 +125,7 @@ func TestLicenseGuardRevokedAndInvalidation(t *testing.T) {
 		id INTEGER PRIMARY KEY AUTOINCREMENT,
 		created_at DATETIME, updated_at DATETIME, deleted_at DATETIME,
 		shop_id INTEGER NOT NULL,
-		license_key TEXT, type TEXT, expires_at DATETIME,
+		license_key TEXT, type TEXT, tier TEXT DEFAULT 'standard', expires_at DATETIME,
 		is_active INTEGER DEFAULT 1, max_devices INTEGER DEFAULT 3,
 		features TEXT, device_id TEXT, activated_at DATETIME
 	)`).Error)

backend/internal/model/license.go

@@ -7,7 +7,9 @@ type License struct {
 	ShopID     uint64     `gorm:"not null;index" json:"shop_id"`
 	LicenseKey string     `gorm:"size:768;uniqueIndex" json:"license_key"`
 	Type       string     `gorm:"type:enum('trial','monthly','annual','lifetime');default:'trial'" json:"type"`
-	ExpiresAt  *time.Time `json:"expires_at"`
+	// Tier 当前权益档位（标准/pro/max…），随兑换码写入；当前默认 'standard'，暂不据此做能力差异。
+	Tier      string     `gorm:"size:32;not null;default:'standard'" json:"tier"`
+	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"`

backend/internal/model/license_code.go

@@ -0,0 +1,27 @@
+package model
+
+import "time"
+
+// LicenseCode 兑换券（激活码）。由平台方批量生成，用户购买/活动获得后在自己门店兑换。
+// 每张码代表一段时长（duration_days），兑换时叠加到门店当前到期时间上；一码一次（status 控制）。
+type LicenseCode struct {
+	ID   uint64 `gorm:"primaryKey;autoIncrement" json:"id"`
+	Code string `gorm:"size:32;uniqueIndex;not null" json:"code"` // 归一化大写无连字符存储
+
+	Type string `gorm:"type:enum('trial','monthly','annual','lifetime');default:'annual'" json:"type"` // 计费/时长标签
+	// Tier 档位钩子（类似 pro/max）。当前只用 'standard' 一种，分档能力/消费模式后续设计。
+	Tier         string `gorm:"size:32;not null;default:'standard'" json:"tier"`
+	DurationDays int    `gorm:"not null;default:0" json:"duration_days"` // 授予时长；0 = 永久（lifetime）
+	MaxDevices   int    `gorm:"not null;default:0" json:"max_devices"`   // 授予设备上限；0 = 不改变现值
+
+	Status           string     `gorm:"type:enum('unused','redeemed','void');default:'unused';index" json:"status"`
+	RedeemedShopID   *uint64    `gorm:"index" json:"redeemed_shop_id,omitempty"`
+	RedeemedAt       *time.Time `json:"redeemed_at,omitempty"`
+	RedeemedDeviceID string     `gorm:"size:255" json:"redeemed_device_id,omitempty"`
+
+	Batch string `gorm:"size:64" json:"batch,omitempty"` // 发放批次/活动名
+	Note  string `gorm:"size:255" json:"note,omitempty"`
+
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+}

backend/internal/service/auth_test.go

@@ -7,9 +7,7 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
-	"github.com/wangjia/jiu/backend/config"
 	"github.com/wangjia/jiu/backend/internal/model"
-	"github.com/wangjia/jiu/backend/internal/util"
 	"github.com/wangjia/jiu/backend/testutil"
 )
 
@@ -31,9 +29,6 @@ func TestAuthService_Login_Success(t *testing.T) {
 
 func TestAuthService_Login_AutoTrialOnFirstUse(t *testing.T) {
 	db := testutil.SetupTestDB()
-	priv, _, err := util.GenerateEd25519KeyPair()
-	require.NoError(t, err)
-	config.C.License.Ed25519PrivateKey = priv
 
 	shop := testutil.CreateTestShop(db, "TRIAL001")
 	testutil.CreateTestUser(db, shop.ID, "admin", "password123", "admin")
@@ -46,7 +41,7 @@ func TestAuthService_Login_AutoTrialOnFirstUse(t *testing.T) {
 	svc := NewAuthService(db)
 
 	// 首次登录 → 自动签发 30 天 trial
-	_, _, err = svc.Login("TRIAL001", "admin", "password123", DeviceInfo{Platform: "windows"})
+	_, _, err := svc.Login("TRIAL001", "admin", "password123", DeviceInfo{Platform: "windows"})
 	require.NoError(t, err)
 
 	var lic model.License

backend/internal/service/license.go

@@ -1,18 +1,13 @@
 package service
 
 import (
-	"crypto/hmac"
-	"crypto/sha256"
-	"encoding/base32"
 	"errors"
-	"fmt"
 	"log"
-	"strings"
 	"time"
 
+	"github.com/google/uuid"
 	"gorm.io/gorm"
 
-	"github.com/wangjia/jiu/backend/config"
 	"github.com/wangjia/jiu/backend/internal/middleware"
 	"github.com/wangjia/jiu/backend/internal/model"
 	"github.com/wangjia/jiu/backend/internal/util"
@@ -22,7 +17,12 @@ var (
 	ErrLicenseNotFound   = errors.New("license not found")
 	ErrLicenseInactive   = errors.New("license is inactive")
 	ErrLicenseExpired    = errors.New("license has expired")
-	ErrDeviceLimitExceed = errors.New("device limit reached — deactivate another device first")
+	ErrDeviceLimitExceed = errors.New("设备数已达上限，请先在其它设备上解绑后再试")
+
+	// 兑换券（激活码）相关错误，消息直接面向用户。
+	ErrCodeNotFound = errors.New("无效激活码")
+	ErrCodeUsed     = errors.New("该激活码已被使用")
+	ErrCodeVoid     = errors.New("该激活码已失效")
 )
 
 type LicenseService struct {
@@ -33,69 +33,150 @@ func NewLicenseService(db *gorm.DB) *LicenseService {
 	return &LicenseService{db: db}
 }
 
-// GenerateKey 生成许可证激活码
-// 格式：HMAC-SHA256(shopID+licenseType+expiry, secret) → base32, 每5字符加'-'
-func GenerateKey(shopID uint64, licenseType string, expiresAt *time.Time) string {
-	payload := fmt.Sprintf("%d:%s", shopID, licenseType)
-	if expiresAt != nil {
-		payload += ":" + expiresAt.Format("20060102")
-	}
-	mac := hmac.New(sha256.New, []byte(config.C.License.HMACSecret))
-	mac.Write([]byte(payload))
-	raw := base32.StdEncoding.WithPadding(base32.NoPadding).EncodeToString(mac.Sum(nil))
-	// 截取前20字符，分4段，每段5字符
-	raw = strings.ToUpper(raw)[:20]
-	return fmt.Sprintf("%s-%s-%s-%s", raw[0:5], raw[5:10], raw[10:15], raw[15:20])
-}
-
-// Activate 激活许可证并绑定设备到 license_devices 表。
-// 若该设备已绑定，则更新 last_seen_at（幂等）。
-// 若是新设备，则校验是否超出 max_devices 上限。
-func (s *LicenseService) Activate(shopID uint64, licenseKey, deviceID, deviceName, platform string) (*model.License, error) {
-	var lic model.License
-	if err := s.db.Where("license_key = ? AND shop_id = ?", licenseKey, shopID).First(&lic).Error; err != nil {
-		return nil, ErrLicenseNotFound
-	}
-	if !lic.IsActive {
-		return nil, ErrLicenseInactive
-	}
-	if lic.ExpiresAt != nil && time.Now().After(*lic.ExpiresAt) {
-		return nil, ErrLicenseExpired
+// Redeem 兑换一张激活码（时长券）：校验码有效且未使用 → 把时长叠加到门店当前授权的到期时间
+// → 标记码已用 → 绑定本设备。整个过程在单事务内，check-then-act 用 FOR UPDATE 锁行，
+// 保证一码只能被成功兑换一次（并发下恰一个成功）。
+//
+// 时长叠加规则：新到期 = max(今天, 当前到期) + duration_days；duration_days=0 视为永久（到期置 NULL）。
+func (s *LicenseService) Redeem(shopID uint64, rawCode, deviceID, deviceName, platform string) (*model.License, error) {
+	code := util.NormalizeCode(rawCode)
+	if code == "" {
+		return nil, ErrCodeNotFound
 	}
 
-	// 激活成功即清除该店 phase 缓存：续费/换新授权码后写权限即时恢复，不必等 30s TTL。
-	defer middleware.InvalidateLicensePhase(shopID)
-
-	var existing model.LicenseDevice
-	err := s.db.Where("license_id = ? AND device_id = ?", lic.ID, deviceID).First(&existing).Error
-	if err == nil {
-		// Device already bound — just touch last_seen_at (handled by autoUpdateTime)
-		if err := s.db.Model(&existing).Update("device_name", deviceName).Error; err != nil {
-			return nil, err
+	var result model.License
+	err := s.db.Transaction(func(tx *gorm.DB) error {
+		// 1) 锁定并校验兑换码
+		var lc model.LicenseCode
+		if err := tx.Set("gorm:query_option", "FOR UPDATE").
+			Where("code = ?", code).First(&lc).Error; err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return ErrCodeNotFound
+			}
+			return err
+		}
+		switch lc.Status {
+		case "redeemed":
+			return ErrCodeUsed
+		case "void":
+			return ErrCodeVoid
 		}
-		return &lic, nil
-	}
 
-	// New device — enforce max_devices
-	var count int64
-	if err := s.db.Model(&model.LicenseDevice{}).Where("license_id = ?", lic.ID).Count(&count).Error; err != nil {
+		now := time.Now()
+
+		// 2) 取本店最新有效授权行（锁行）；无则新建一行
+		var lic model.License
+		err := tx.Set("gorm:query_option", "FOR UPDATE").
+			Where("shop_id = ? AND is_active = ?", shopID, true).
+			Order("id DESC").First(&lic).Error
+		creating := errors.Is(err, gorm.ErrRecordNotFound)
+		if err != nil && !creating {
+			return err
+		}
+
+		// 3) 计算叠加后的到期时间
+		var newExpires *time.Time
+		if lc.DurationDays > 0 {
+			base := now
+			if lic.ExpiresAt != nil && lic.ExpiresAt.After(now) {
+				base = *lic.ExpiresAt
+			}
+			t := base.Add(time.Duration(lc.DurationDays) * 24 * time.Hour)
+			newExpires = &t
+		} // duration_days==0 → 永久授权，newExpires 保持 nil
+
+		maxDevices := lic.MaxDevices
+		if lc.MaxDevices > maxDevices {
+			maxDevices = lc.MaxDevices
+		}
+		if maxDevices == 0 {
+			maxDevices = 1
+		}
+
+		if creating {
+			lic = model.License{
+				ShopID:     shopID,
+				LicenseKey: "REDEEM-" + uuid.New().String(),
+				Type:       lc.Type,
+				Tier:       lc.Tier,
+				ExpiresAt:  newExpires,
+				IsActive:   true,
+				MaxDevices: maxDevices,
+			}
+			if err := tx.Create(&lic).Error; err != nil {
+				return err
+			}
+		} else {
+			// 不动 license_key（保留原值，licenses 行只表示"当前权益"）
+			if err := tx.Model(&lic).Updates(map[string]any{
+				"type":        lc.Type,
+				"tier":        lc.Tier,
+				"expires_at":  newExpires,
+				"is_active":   true,
+				"max_devices": maxDevices,
+			}).Error; err != nil {
+				return err
+			}
+			lic.ExpiresAt = newExpires
+			lic.Type = lc.Type
+			lic.Tier = lc.Tier
+			lic.MaxDevices = maxDevices
+		}
+
+		// 4) 绑定本设备（幂等 + max_devices 上限校验）
+		if err := bindDevice(tx, &lic, deviceID, deviceName, platform); err != nil {
+			return err
+		}
+
+		// 5) 标记码已用
+		if err := tx.Model(&model.LicenseCode{}).Where("id = ?", lc.ID).Updates(map[string]any{
+			"status":             "redeemed",
+			"redeemed_shop_id":   shopID,
+			"redeemed_at":        now,
+			"redeemed_device_id": deviceID,
+		}).Error; err != nil {
+			return err
+		}
+
+		result = lic
+		return nil
+	})
+	if err != nil {
 		return nil, err
 	}
-	if int(count) >= lic.MaxDevices {
-		return nil, ErrDeviceLimitExceed
-	}
 
-	dev := model.LicenseDevice{
+	// 事务提交后再失效 phase 缓存：此刻新到期对其它连接已可见，写权限即时恢复，不必等 30s TTL。
+	middleware.InvalidateLicensePhase(shopID)
+	return &result, nil
+}
+
+// bindDevice 把设备绑定到许可证（幂等：已绑则更新名称；新设备则校验 max_devices 上限）。
+func bindDevice(tx *gorm.DB, lic *model.License, deviceID, deviceName, platform string) error {
+	if deviceID == "" {
+		return nil // 无设备信息（如服务端工具调用）则跳过绑定
+	}
+	var existing model.LicenseDevice
+	err := tx.Where("license_id = ? AND device_id = ?", lic.ID, deviceID).First(&existing).Error
+	if err == nil {
+		return tx.Model(&existing).Update("device_name", deviceName).Error
+	}
+	if !errors.Is(err, gorm.ErrRecordNotFound) {
+		return err
+	}
+	var count int64
+	if err := tx.Model(&model.LicenseDevice{}).Where("license_id = ?", lic.ID).Count(&count).Error; err != nil {
+		return err
+	}
+	if int(count) >= lic.MaxDevices {
+		return ErrDeviceLimitExceed
+	}
+	return tx.Create(&model.LicenseDevice{
 		LicenseID:  lic.ID,
-		ShopID:     shopID,
+		ShopID:     lic.ShopID,
 		DeviceID:   deviceID,
 		DeviceName: deviceName,
 		Platform:   platform,
-	}
-	if err := s.db.Create(&dev).Error; err != nil {
-		return nil, err
-	}
-	return &lic, nil
+	}).Error
 }
 
 // Verify 验证设备许可证（客户端启动时调用）。
@@ -188,33 +269,15 @@ func (s *LicenseService) Deactivate(shopID uint64, deviceID string) error {
 		Delete(&model.LicenseDevice{}).Error
 }
 
-// issueTrialLicense 为门店签发并写入一条 30 天 trial license。
-// 私钥未配置或签发/落库失败时返回 error，由调用方决定如何处理（注册路径 Fatal、
-// 登录路径仅记日志）。
+// issueTrialLicense 为门店写入一条 30 天 trial license。直接建行（无需签名/私钥），
+// license_key 用合成唯一值占位以满足 NOT NULL/UNIQUE。落库失败返回 error。
 func issueTrialLicense(db *gorm.DB, shopID uint64) error {
-	privKey := config.C.License.Ed25519PrivateKey
-	if privKey == "" {
-		return fmt.Errorf("ed25519 private key not configured")
-	}
-
 	expiresAt := time.Now().Add(30 * 24 * time.Hour)
-	expiresUnix := expiresAt.Unix()
-	payload := util.LicensePayload{
-		ShopID:     shopID,
-		Type:       "trial",
-		IssuedAt:   time.Now().Unix(),
-		ExpiresAt:  &expiresUnix,
-		MaxDevices: 1,
-	}
-	token, err := util.IssueLicenseToken(payload, privKey)
-	if err != nil {
-		return err
-	}
-
 	lic := model.License{
 		ShopID:     shopID,
-		LicenseKey: token,
+		LicenseKey: "TRIAL-" + uuid.New().String(),
 		Type:       "trial",
+		Tier:       "standard",
 		ExpiresAt:  &expiresAt,
 		IsActive:   true,
 		MaxDevices: 1,
@@ -228,12 +291,8 @@ func issueTrialLicense(db *gorm.DB, shopID uint64) error {
 	return nil
 }
 
-// createTrialLicense 在注册事务中为新门店签发 30 天 trial license。
-// 私钥未配置时 Fatal，防止生产环境静默跳过导致新注册门店无 license。
+// createTrialLicense 在注册事务中为新门店写入 30 天 trial license。失败仅记日志、不阻断注册。
 func createTrialLicense(tx *gorm.DB, shopID uint64) {
-	if config.C.License.Ed25519PrivateKey == "" {
-		log.Fatalf("[license] Ed25519 private key not configured — cannot issue trial for shop %d; set License.Ed25519PrivateKey in config", shopID)
-	}
 	if err := issueTrialLicense(tx, shopID); err != nil {
 		log.Printf("[license] failed to create trial license for shop %d: %v", shopID, err)
 	}

backend/internal/service/license_test.go

@@ -6,155 +6,185 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"gorm.io/gorm"
 
 	"github.com/wangjia/jiu/backend/internal/model"
+	"github.com/wangjia/jiu/backend/internal/util"
 	"github.com/wangjia/jiu/backend/testutil"
 )
 
-func TestLicenseService_Activate_Success(t *testing.T) {
-	db := testutil.SetupTestDB()
-	shop := testutil.CreateTestShop(db, "LIC001")
-
-	expiry := time.Now().Add(30 * 24 * time.Hour)
-	lic := &model.License{
-		ShopID:     shop.ID,
-		LicenseKey: "AAAAA-BBBBB-CCCCC-DDDDD",
-		IsActive:   true,
-		ExpiresAt:  &expiry,
-		MaxDevices: 3,
-	}
-	require.NoError(t, db.Create(lic).Error)
-
-	svc := NewLicenseService(db)
-	result, err := svc.Activate(shop.ID, "AAAAA-BBBBB-CCCCC-DDDDD", "device-001", "Test PC", "windows")
-
-	require.NoError(t, err)
-	require.NotNil(t, result)
-
-	// Verify device record was created
-	var dev model.LicenseDevice
-	require.NoError(t, db.Where("license_id = ? AND device_id = ?", lic.ID, "device-001").First(&dev).Error)
-	assert.Equal(t, "Test PC", dev.DeviceName)
-	assert.Equal(t, "windows", dev.Platform)
+// createCode 在码池写入一张 unused 兑换码（默认 type=annual / tier=standard）。
+func createCode(t *testing.T, db *gorm.DB, code string, durationDays, maxDevices int) {
+	t.Helper()
+	require.NoError(t, db.Create(&model.LicenseCode{
+		Code:         util.NormalizeCode(code),
+		Type:         "annual",
+		Tier:         "standard",
+		DurationDays: durationDays,
+		MaxDevices:   maxDevices,
+		Status:       "unused",
+	}).Error)
 }
 
-func TestLicenseService_Activate_SameDeviceIdempotent(t *testing.T) {
-	db := testutil.SetupTestDB()
-	shop := testutil.CreateTestShop(db, "LIC002")
-
-	lic := &model.License{
-		ShopID:     shop.ID,
-		LicenseKey: "EEEEE-FFFFF-GGGGG-HHHHH",
-		IsActive:   true,
-		MaxDevices: 3,
+func daysFromNow(t *time.Time) float64 {
+	if t == nil {
+		return 0
 	}
-	require.NoError(t, db.Create(lic).Error)
-	// Pre-bind the device
-	require.NoError(t, db.Create(&model.LicenseDevice{
-		LicenseID: lic.ID, ShopID: shop.ID, DeviceID: "same-device",
+	return time.Until(*t).Hours() / 24
+}
+
+// 首次兑换（门店尚无授权行）：新建一行，到期 = 今天 + 时长，码标记已用并绑定设备。
+func TestLicenseService_Redeem_NewShop(t *testing.T) {
+	db := testutil.SetupTestDB()
+	shop := testutil.CreateTestShop(db, "RDM001")
+	createCode(t, db, "JIUKU-AAAA-BBBB", 365, 3)
+
+	svc := NewLicenseService(db)
+	// 传小写 + 连字符，验证归一化
+	lic, err := svc.Redeem(shop.ID, "jiuku-aaaa-bbbb", "dev-1", "Test PC", "windows")
+	require.NoError(t, err)
+	require.NotNil(t, lic)
+	assert.InDelta(t, 365, daysFromNow(lic.ExpiresAt), 1)
+	assert.Equal(t, 3, lic.MaxDevices)
+	assert.Equal(t, "standard", lic.Tier)
+	assert.Equal(t, "annual", lic.Type)
+
+	var lc model.LicenseCode
+	require.NoError(t, db.Where("code = ?", "JIUKUAAAABBBB").First(&lc).Error)
+	assert.Equal(t, "redeemed", lc.Status)
+	require.NotNil(t, lc.RedeemedShopID)
+	assert.Equal(t, shop.ID, *lc.RedeemedShopID)
+
+	var dev model.LicenseDevice
+	require.NoError(t, db.Where("license_id = ? AND device_id = ?", lic.ID, "dev-1").First(&dev).Error)
+	assert.Equal(t, "Test PC", dev.DeviceName)
+}
+
+// 在既有未过期授权上兑换：到期时间叠加在原到期之后。
+func TestLicenseService_Redeem_ExtendsExisting(t *testing.T) {
+	db := testutil.SetupTestDB()
+	shop := testutil.CreateTestShop(db, "RDM002")
+	expiry := time.Now().Add(10 * 24 * time.Hour)
+	require.NoError(t, db.Create(&model.License{
+		ShopID: shop.ID, LicenseKey: "TRIAL-RDM002", Type: "trial", Tier: "standard",
+		ExpiresAt: &expiry, IsActive: true, MaxDevices: 3,
+	}).Error)
+	createCode(t, db, "JIUKU-CCCC-DDDD", 365, 0)
+
+	svc := NewLicenseService(db)
+	lic, err := svc.Redeem(shop.ID, "JIUKU-CCCC-DDDD", "dev-1", "PC", "windows")
+	require.NoError(t, err)
+	// 原剩 10 天 + 365 ≈ 375
+	assert.InDelta(t, 375, daysFromNow(lic.ExpiresAt), 1)
+}
+
+// 叠加：连兑两张码，时长累加。
+func TestLicenseService_Redeem_Stacks(t *testing.T) {
+	db := testutil.SetupTestDB()
+	shop := testutil.CreateTestShop(db, "RDM003")
+	createCode(t, db, "JIUKU-1111-1111", 365, 1)
+	createCode(t, db, "JIUKU-2222-2222", 365, 1)
+
+	svc := NewLicenseService(db)
+	_, err := svc.Redeem(shop.ID, "JIUKU-1111-1111", "dev-1", "PC", "windows")
+	require.NoError(t, err)
+	lic, err := svc.Redeem(shop.ID, "JIUKU-2222-2222", "dev-1", "PC", "windows")
+	require.NoError(t, err)
+	assert.InDelta(t, 730, daysFromNow(lic.ExpiresAt), 1)
+}
+
+// 已过期门店兑换：从今天起算，不在过去叠加。
+func TestLicenseService_Redeem_ExpiredBase(t *testing.T) {
+	db := testutil.SetupTestDB()
+	shop := testutil.CreateTestShop(db, "RDM004")
+	past := time.Now().Add(-5 * 24 * time.Hour)
+	require.NoError(t, db.Create(&model.License{
+		ShopID: shop.ID, LicenseKey: "TRIAL-RDM004", Type: "trial", Tier: "standard",
+		ExpiresAt: &past, IsActive: true, MaxDevices: 1,
+	}).Error)
+	createCode(t, db, "JIUKU-EEEE-FFFF", 30, 0)
+
+	svc := NewLicenseService(db)
+	lic, err := svc.Redeem(shop.ID, "JIUKU-EEEE-FFFF", "dev-1", "PC", "windows")
+	require.NoError(t, err)
+	assert.InDelta(t, 30, daysFromNow(lic.ExpiresAt), 1)
+}
+
+// 永久码（duration=0）：到期置 NULL。
+func TestLicenseService_Redeem_Lifetime(t *testing.T) {
+	db := testutil.SetupTestDB()
+	shop := testutil.CreateTestShop(db, "RDM005")
+	createCode(t, db, "JIUKU-LIFE-TIME", 0, 1)
+
+	svc := NewLicenseService(db)
+	lic, err := svc.Redeem(shop.ID, "JIUKU-LIFE-TIME", "dev-1", "PC", "windows")
+	require.NoError(t, err)
+	assert.Nil(t, lic.ExpiresAt)
+}
+
+// 一码一次：同码兑换两次，第二次失败。
+func TestLicenseService_Redeem_AlreadyUsed(t *testing.T) {
+	db := testutil.SetupTestDB()
+	shop := testutil.CreateTestShop(db, "RDM006")
+	createCode(t, db, "JIUKU-USED-ONCE", 365, 1)
+
+	svc := NewLicenseService(db)
+	_, err := svc.Redeem(shop.ID, "JIUKU-USED-ONCE", "dev-1", "PC", "windows")
+	require.NoError(t, err)
+	_, err = svc.Redeem(shop.ID, "JIUKU-USED-ONCE", "dev-1", "PC", "windows")
+	assert.Equal(t, ErrCodeUsed, err)
+}
+
+func TestLicenseService_Redeem_NotFound(t *testing.T) {
+	db := testutil.SetupTestDB()
+	shop := testutil.CreateTestShop(db, "RDM007")
+
+	svc := NewLicenseService(db)
+	_, err := svc.Redeem(shop.ID, "JIUKU-NONE-XXXX", "dev-1", "", "")
+	assert.Equal(t, ErrCodeNotFound, err)
+}
+
+func TestLicenseService_Redeem_Void(t *testing.T) {
+	db := testutil.SetupTestDB()
+	shop := testutil.CreateTestShop(db, "RDM008")
+	require.NoError(t, db.Create(&model.LicenseCode{
+		Code: "JIUKUVOIDCODE0", Type: "annual", Tier: "standard",
+		DurationDays: 365, Status: "void",
 	}).Error)
 
 	svc := NewLicenseService(db)
-	// Re-activating same device should succeed (idempotent)
-	result, err := svc.Activate(shop.ID, "EEEEE-FFFFF-GGGGG-HHHHH", "same-device", "Updated Name", "windows")
-
-	require.NoError(t, err)
-	require.NotNil(t, result)
-
-	// Still only one device record
-	var count int64
-	db.Model(&model.LicenseDevice{}).Where("license_id = ?", lic.ID).Count(&count)
-	assert.Equal(t, int64(1), count)
+	_, err := svc.Redeem(shop.ID, "JIUKU-VOID-CODE0", "dev-1", "", "")
+	assert.Equal(t, ErrCodeVoid, err)
 }
 
-func TestLicenseService_Activate_DeviceLimitExceeded(t *testing.T) {
+// 设备超上限：兑换整体回滚——码保持 unused、到期不变。
+func TestLicenseService_Redeem_DeviceLimitRollsBack(t *testing.T) {
 	db := testutil.SetupTestDB()
-	shop := testutil.CreateTestShop(db, "LIC003")
-
+	shop := testutil.CreateTestShop(db, "RDM009")
+	expiry := time.Now().Add(10 * 24 * time.Hour)
 	lic := &model.License{
-		ShopID:     shop.ID,
-		LicenseKey: "IIIII-JJJJJ-KKKKK-LLLLL",
-		IsActive:   true,
-		MaxDevices: 2,
+		ShopID: shop.ID, LicenseKey: "TRIAL-RDM009", Type: "trial", Tier: "standard",
+		ExpiresAt: &expiry, IsActive: true, MaxDevices: 1,
 	}
 	require.NoError(t, db.Create(lic).Error)
-	// Fill up the device limit
-	require.NoError(t, db.Create(&model.LicenseDevice{LicenseID: lic.ID, ShopID: shop.ID, DeviceID: "dev-1"}).Error)
-	require.NoError(t, db.Create(&model.LicenseDevice{LicenseID: lic.ID, ShopID: shop.ID, DeviceID: "dev-2"}).Error)
+	// 已占满 1 个设备名额
+	require.NoError(t, db.Create(&model.LicenseDevice{
+		LicenseID: lic.ID, ShopID: shop.ID, DeviceID: "old-dev",
+	}).Error)
+	createCode(t, db, "JIUKU-DEVL-IMIT", 365, 0) // 不提升设备上限
 
 	svc := NewLicenseService(db)
-	result, err := svc.Activate(shop.ID, "IIIII-JJJJJ-KKKKK-LLLLL", "dev-3", "", "")
-
-	assert.Error(t, err)
+	_, err := svc.Redeem(shop.ID, "JIUKU-DEVL-IMIT", "new-dev", "New PC", "windows")
 	assert.Equal(t, ErrDeviceLimitExceed, err)
-	assert.Nil(t, result)
-}
 
-func TestLicenseService_Activate_NotFound(t *testing.T) {
-	db := testutil.SetupTestDB()
-	shop := testutil.CreateTestShop(db, "LIC004")
-
-	svc := NewLicenseService(db)
-	result, err := svc.Activate(shop.ID, "NONEX-ISTEN-TTTTT-LICCC", "device-001", "", "")
-
-	assert.Error(t, err)
-	assert.Equal(t, ErrLicenseNotFound, err)
-	assert.Nil(t, result)
-}
-
-func TestLicenseService_Activate_WrongShop(t *testing.T) {
-	db := testutil.SetupTestDB()
-	shop := testutil.CreateTestShop(db, "LIC004B")
-	otherShop := testutil.CreateTestShop(db, "LIC004C")
-
-	lic := &model.License{
-		ShopID: shop.ID, LicenseKey: "OTHSH-BBBBB-CCCCC-DDDDD", IsActive: true, MaxDevices: 3,
-	}
-	require.NoError(t, db.Create(lic).Error)
-
-	svc := NewLicenseService(db)
-	// otherShop cannot activate a license belonging to shop
-	result, err := svc.Activate(otherShop.ID, "OTHSH-BBBBB-CCCCC-DDDDD", "device-001", "", "")
-
-	assert.Error(t, err)
-	assert.Equal(t, ErrLicenseNotFound, err)
-	assert.Nil(t, result)
-}
-
-func TestLicenseService_Activate_Inactive(t *testing.T) {
-	db := testutil.SetupTestDB()
-	shop := testutil.CreateTestShop(db, "LIC005")
-
-	lic := &model.License{
-		ShopID: shop.ID, LicenseKey: "MMMMM-NNNNN-OOOOO-PPPPP", IsActive: true, MaxDevices: 3,
-	}
-	require.NoError(t, db.Create(lic).Error)
-	require.NoError(t, db.Model(lic).Update("is_active", false).Error)
-
-	svc := NewLicenseService(db)
-	result, err := svc.Activate(shop.ID, "MMMMM-NNNNN-OOOOO-PPPPP", "device-001", "", "")
-
-	assert.Error(t, err)
-	assert.Equal(t, ErrLicenseInactive, err)
-	assert.Nil(t, result)
-}
-
-func TestLicenseService_Activate_Expired(t *testing.T) {
-	db := testutil.SetupTestDB()
-	shop := testutil.CreateTestShop(db, "LIC006")
-
-	expiry := time.Now().Add(-24 * time.Hour)
-	lic := &model.License{
-		ShopID: shop.ID, LicenseKey: "QQQQQ-RRRRR-SSSSS-TTTTT", IsActive: true, ExpiresAt: &expiry, MaxDevices: 3,
-	}
-	require.NoError(t, db.Create(lic).Error)
-
-	svc := NewLicenseService(db)
-	result, err := svc.Activate(shop.ID, "QQQQQ-RRRRR-SSSSS-TTTTT", "device-001", "", "")
-
-	assert.Error(t, err)
-	assert.Equal(t, ErrLicenseExpired, err)
-	assert.Nil(t, result)
+	// 码仍未使用（回滚）
+	var lc model.LicenseCode
+	require.NoError(t, db.Where("code = ?", "JIUKUDEVLIMIT").First(&lc).Error)
+	assert.Equal(t, "unused", lc.Status)
+	// 到期不变
+	var after model.License
+	require.NoError(t, db.First(&after, lic.ID).Error)
+	assert.InDelta(t, 10, daysFromNow(after.ExpiresAt), 1)
 }
 
 func TestLicenseService_Verify_Success(t *testing.T) {
@@ -229,17 +259,3 @@ func TestLicenseService_Verify_NoExpiry(t *testing.T) {
 	require.NoError(t, err)
 	require.NotNil(t, result)
 }
-
-func TestGenerateKey(t *testing.T) {
-	testutil.InitConfig()
-
-	expiry := time.Now().Add(30 * 24 * time.Hour)
-	key := GenerateKey(1, "annual", &expiry)
-
-	assert.NotEmpty(t, key)
-	// 格式：XXXXX-XXXXX-XXXXX-XXXXX
-	assert.Equal(t, 23, len(key)) // 4*5 + 3 dashes = 23
-	assert.Equal(t, '-', rune(key[5]))
-	assert.Equal(t, '-', rune(key[11]))
-	assert.Equal(t, '-', rune(key[17]))
-}

backend/internal/util/license_key.go

@@ -1,106 +0,0 @@
-package util
-
-import (
-	"crypto/ed25519"
-	"crypto/rand"
-	"encoding/base64"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"strings"
-)
-
-var (
-	ErrInvalidLicenseToken     = errors.New("invalid license token")
-	ErrInvalidLicenseSignature = errors.New("invalid license token signature")
-)
-
-// LicensePayload is the verified content extracted from a signed license token.
-type LicensePayload struct {
-	ShopID     uint64         `json:"shop_id"`
-	LicenseID  uint64         `json:"license_id,omitempty"`
-	Type       string         `json:"type"` // trial | monthly | annual | lifetime
-	IssuedAt   int64          `json:"issued_at"`
-	ExpiresAt  *int64         `json:"expires_at,omitempty"` // unix seconds; nil = perpetual
-	MaxDevices int            `json:"max_devices"`
-	Features   map[string]any `json:"features,omitempty"`
-}
-
-// GenerateEd25519KeyPair generates a new Ed25519 keypair.
-// Returns standard base64-encoded private key (64 bytes) and public key (32 bytes).
-// The private key must be stored securely (Bitwarden); the public key goes in config.
-func GenerateEd25519KeyPair() (privKeyB64, pubKeyB64 string, err error) {
-	pub, priv, err := ed25519.GenerateKey(rand.Reader)
-	if err != nil {
-		return "", "", err
-	}
-	return base64.StdEncoding.EncodeToString(priv),
-		base64.StdEncoding.EncodeToString(pub),
-		nil
-}
-
-// IssueLicenseToken signs a LicensePayload with the Ed25519 private key and returns
-// a compact token: base64url(header).base64url(payload).base64url(signature).
-// privKeyB64 is the standard base64-encoded 64-byte Ed25519 private key.
-func IssueLicenseToken(payload LicensePayload, privKeyB64 string) (string, error) {
-	privKeyBytes, err := base64.StdEncoding.DecodeString(privKeyB64)
-	if err != nil {
-		return "", fmt.Errorf("decode private key: %w", err)
-	}
-	if len(privKeyBytes) != ed25519.PrivateKeySize {
-		return "", fmt.Errorf("private key must be %d bytes, got %d", ed25519.PrivateKeySize, len(privKeyBytes))
-	}
-	privKey := ed25519.PrivateKey(privKeyBytes)
-
-	header := rawB64([]byte(`{"alg":"EdDSA","typ":"LIC"}`))
-	payloadJSON, err := json.Marshal(payload)
-	if err != nil {
-		return "", err
-	}
-	body := rawB64(payloadJSON)
-	signingInput := header + "." + body
-	sig := ed25519.Sign(privKey, []byte(signingInput))
-	return signingInput + "." + rawB64(sig), nil
-}
-
-// VerifyLicenseToken verifies the Ed25519 signature of a license token and returns
-// the decoded payload. Does NOT check expiry — callers must check ExpiresAt themselves.
-// pubKeyB64 is the standard base64-encoded 32-byte Ed25519 public key.
-func VerifyLicenseToken(token, pubKeyB64 string) (*LicensePayload, error) {
-	parts := strings.Split(token, ".")
-	if len(parts) != 3 {
-		return nil, ErrInvalidLicenseToken
-	}
-
-	pubKeyBytes, err := base64.StdEncoding.DecodeString(pubKeyB64)
-	if err != nil {
-		return nil, fmt.Errorf("decode public key: %w", err)
-	}
-	if len(pubKeyBytes) != ed25519.PublicKeySize {
-		return nil, fmt.Errorf("public key must be %d bytes, got %d", ed25519.PublicKeySize, len(pubKeyBytes))
-	}
-	pubKey := ed25519.PublicKey(pubKeyBytes)
-
-	signingInput := parts[0] + "." + parts[1]
-	sigBytes, err := base64.RawURLEncoding.DecodeString(parts[2])
-	if err != nil {
-		return nil, ErrInvalidLicenseToken
-	}
-	if !ed25519.Verify(pubKey, []byte(signingInput), sigBytes) {
-		return nil, ErrInvalidLicenseSignature
-	}
-
-	payloadJSON, err := base64.RawURLEncoding.DecodeString(parts[1])
-	if err != nil {
-		return nil, ErrInvalidLicenseToken
-	}
-	var p LicensePayload
-	if err := json.Unmarshal(payloadJSON, &p); err != nil {
-		return nil, ErrInvalidLicenseToken
-	}
-	return &p, nil
-}
-
-func rawB64(data []byte) string {
-	return base64.RawURLEncoding.EncodeToString(data)
-}

backend/internal/util/license_key_test.go

@@ -1,110 +0,0 @@
-package util
-
-import (
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-func TestLicenseKeyRoundTrip(t *testing.T) {
-	priv, pub, err := GenerateEd25519KeyPair()
-	require.NoError(t, err)
-
-	exp := time.Now().Add(30 * 24 * time.Hour).Unix()
-	payload := LicensePayload{
-		ShopID:     42,
-		LicenseID:  7,
-		Type:       "annual",
-		IssuedAt:   time.Now().Unix(),
-		ExpiresAt:  &exp,
-		MaxDevices: 3,
-	}
-
-	token, err := IssueLicenseToken(payload, priv)
-	require.NoError(t, err)
-	assert.NotEmpty(t, token)
-
-	got, err := VerifyLicenseToken(token, pub)
-	require.NoError(t, err)
-	assert.Equal(t, payload.ShopID, got.ShopID)
-	assert.Equal(t, payload.Type, got.Type)
-	assert.Equal(t, payload.MaxDevices, got.MaxDevices)
-	assert.Equal(t, *payload.ExpiresAt, *got.ExpiresAt)
-}
-
-func TestVerifyLicenseToken_TamperedPayload(t *testing.T) {
-	priv, pub, err := GenerateEd25519KeyPair()
-	require.NoError(t, err)
-
-	exp := time.Now().Add(30 * 24 * time.Hour).Unix()
-	token, err := IssueLicenseToken(LicensePayload{
-		ShopID: 1, Type: "trial", IssuedAt: time.Now().Unix(), ExpiresAt: &exp, MaxDevices: 1,
-	}, priv)
-	require.NoError(t, err)
-
-	// Flip the last byte of the signature to simulate tampering
-	tampered := token[:len(token)-2] + "XX"
-	_, err = VerifyLicenseToken(tampered, pub)
-	assert.Error(t, err, "tampered token must be rejected")
-}
-
-func TestVerifyLicenseToken_WrongKey(t *testing.T) {
-	priv, _, err := GenerateEd25519KeyPair()
-	require.NoError(t, err)
-	_, otherPub, err := GenerateEd25519KeyPair()
-	require.NoError(t, err)
-
-	exp := time.Now().Add(30 * 24 * time.Hour).Unix()
-	token, err := IssueLicenseToken(LicensePayload{
-		ShopID: 1, Type: "trial", IssuedAt: time.Now().Unix(), ExpiresAt: &exp, MaxDevices: 1,
-	}, priv)
-	require.NoError(t, err)
-
-	_, err = VerifyLicenseToken(token, otherPub)
-	assert.ErrorIs(t, err, ErrInvalidLicenseSignature)
-}
-
-func TestVerifyLicenseToken_InvalidFormat(t *testing.T) {
-	_, pub, err := GenerateEd25519KeyPair()
-	require.NoError(t, err)
-
-	_, err = VerifyLicenseToken("not-a-valid-token", pub)
-	assert.ErrorIs(t, err, ErrInvalidLicenseToken)
-}
-
-// TestLicenseTokenFitsColumnLimit verifies that a realistic (even worst-case)
-// license token fits within the VARCHAR(768) column limit imposed by the
-// InnoDB index constraint (768 chars × 4 bytes/char = 3072 bytes max).
-func TestLicenseTokenFitsColumnLimit(t *testing.T) {
-	const columnLimit = 768
-
-	priv, _, err := GenerateEd25519KeyPair()
-	require.NoError(t, err)
-
-	// Use a large features map to simulate a worst-case payload.
-	exp := time.Now().Add(365 * 24 * time.Hour).Unix()
-	payload := LicensePayload{
-		ShopID:    999999999,
-		LicenseID: 999999999,
-		Type:      "lifetime",
-		IssuedAt:  time.Now().Unix(),
-		ExpiresAt: &exp,
-		MaxDevices: 99,
-		Features: map[string]any{
-			"finance":    true,
-			"inventory":  true,
-			"reports":    true,
-			"export":     true,
-			"multi_shop": true,
-			"api_access": true,
-		},
-	}
-
-	token, err := IssueLicenseToken(payload, priv)
-	require.NoError(t, err)
-
-	assert.LessOrEqual(t, len(token), columnLimit,
-		"license token length %d exceeds VARCHAR(%d) column limit", len(token), columnLimit)
-}

backend/internal/util/redeem_code.go

@@ -0,0 +1,40 @@
+package util
+
+import (
+	"crypto/rand"
+	"strings"
+)
+
+// codeAlphabet 兑换码字母表：剔除易混字符 0/O/1/I/L，避免人工抄录歧义。
+const codeAlphabet = "23456789ABCDEFGHJKMNPQRSTUVWXYZ"
+
+// codePrefix 兑换码固定前缀，便于一眼识别归属。
+const codePrefix = "JIUKU"
+
+// GenerateRedeemCode 生成一个随机兑换码，展示格式 JIUKU-XXXX-XXXX（8 位随机段）。
+// 使用 crypto/rand + 无歧义字母表；归一化（NormalizeCode）后入库与比对。
+func GenerateRedeemCode() string {
+	const n = 8
+	buf := make([]byte, n)
+	if _, err := rand.Read(buf); err != nil {
+		// crypto/rand 失败属系统级异常，调用方（CLI 生码）应直接失败而非产出弱码。
+		panic("crypto/rand failed: " + err.Error())
+	}
+	out := make([]byte, n)
+	for i, b := range buf {
+		out[i] = codeAlphabet[int(b)%len(codeAlphabet)]
+	}
+	return codePrefix + "-" + string(out[:4]) + "-" + string(out[4:])
+}
+
+// NormalizeCode 归一化兑换码：转大写、去掉连字符/空格，得到入库与查表用的规范形式。
+func NormalizeCode(code string) string {
+	var b strings.Builder
+	for _, r := range strings.ToUpper(code) {
+		if r == '-' || r == ' ' || r == '\t' || r == '\n' || r == '\r' {
+			continue
+		}
+		b.WriteRune(r)
+	}
+	return b.String()
+}

backend/main.go

@@ -24,9 +24,6 @@ func main() {
 		if config.C.Server.CORSOrigin == "*" {
 			log.Fatal("server.cors_origin must not be '*' in production — set it to the actual frontend origin")
 		}
-		if config.C.License.Ed25519PrivateKey == "" {
-			log.Fatal("license.ed25519_private_key is required in production — store the key in Bitwarden and inject via env LICENSE_ED25519PRIVATEKEY")
-		}
 	}
 
 	// 初始化数据库
@@ -101,6 +98,7 @@ func autoMigrate(db *gorm.DB) {
 		&model.User{},
 		&model.License{},
 		&model.LicenseDevice{},
+		&model.LicenseCode{},
 		&model.UserSession{},
 		&model.LoginAttempt{},
 		&model.ProductCategory{},

backend/schema/schema.sql

@@ -107,6 +107,7 @@ CREATE TABLE IF NOT EXISTS `licenses` (
   `license_key`  VARCHAR(768)    NOT NULL COMMENT 'Ed25519 signed token',
   `device_id`    VARCHAR(255)    DEFAULT NULL COMMENT 'deprecated: use license_devices',
   `type`         ENUM('trial','monthly','annual','lifetime') NOT NULL DEFAULT 'trial',
+  `tier`         VARCHAR(32)     NOT NULL DEFAULT 'standard' COMMENT '权益档位钩子(pro/max-like)，当前默认 standard',
   `expires_at`   DATETIME        DEFAULT NULL COMMENT 'NULL=永久',
   `is_active`    TINYINT(1)      NOT NULL DEFAULT 1,
   `max_devices`  INT             NOT NULL DEFAULT 3 COMMENT '最大绑定设备数',
@@ -134,6 +135,28 @@ CREATE TABLE IF NOT EXISTS `license_devices` (
   KEY `idx_license_id` (`license_id`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='许可证设备绑定';
 
+-- 兑换券（激活码）码池：平台方批量生成，用户兑换后叠加时长到门店授权
+CREATE TABLE IF NOT EXISTS `license_codes` (
+  `id`                 BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+  `code`               VARCHAR(32)     NOT NULL COMMENT '归一化大写无连字符',
+  `type`               ENUM('trial','monthly','annual','lifetime') NOT NULL DEFAULT 'annual' COMMENT '计费/时长标签',
+  `tier`               VARCHAR(32)     NOT NULL DEFAULT 'standard' COMMENT '档位钩子(pro/max-like)，当前默认 standard',
+  `duration_days`      INT             NOT NULL DEFAULT 0 COMMENT '授予时长；0=永久(lifetime)',
+  `max_devices`        INT             NOT NULL DEFAULT 0 COMMENT '授予设备上限；0=不改变现值',
+  `status`             ENUM('unused','redeemed','void') NOT NULL DEFAULT 'unused',
+  `redeemed_shop_id`   BIGINT UNSIGNED DEFAULT NULL COMMENT '被哪个门店兑换',
+  `redeemed_at`        DATETIME        DEFAULT NULL,
+  `redeemed_device_id` VARCHAR(255)    DEFAULT NULL COMMENT '兑换设备(审计)',
+  `batch`              VARCHAR(64)     DEFAULT NULL COMMENT '发放批次/活动名',
+  `note`               VARCHAR(255)    DEFAULT NULL,
+  `created_at`         DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `updated_at`         DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_code` (`code`),
+  KEY `idx_status` (`status`),
+  KEY `idx_redeemed_shop` (`redeemed_shop_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='兑换券码池';
+
 -- ------------------------------------------------------------
 -- 商品分类
 -- ------------------------------------------------------------

backend/testutil/setup.go

@@ -27,9 +27,6 @@ func InitConfig() {
 			AccessExpireMin: 60,
 			RefreshExpireH:  168,
 		},
-		License: config.LicenseConfig{
-			HMACSecret: "test-license-hmac-secret",
-		},
 		Session: config.SessionConfig{
 			LimitDesktop: 2,
 			LimitMobile:  2,
@@ -125,12 +122,29 @@ func SetupTestDB() *gorm.DB {
 			license_key TEXT UNIQUE,
 			device_id TEXT,
 			type TEXT DEFAULT 'trial',
+			tier TEXT DEFAULT 'standard',
 			expires_at DATETIME,
 			is_active INTEGER DEFAULT 1,
 			max_devices INTEGER DEFAULT 3,
 			features TEXT,
 			activated_at DATETIME
 		)`,
+		`CREATE TABLE IF NOT EXISTS license_codes (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			code TEXT UNIQUE NOT NULL,
+			type TEXT DEFAULT 'annual',
+			tier TEXT DEFAULT 'standard',
+			duration_days INTEGER NOT NULL DEFAULT 0,
+			max_devices INTEGER NOT NULL DEFAULT 0,
+			status TEXT NOT NULL DEFAULT 'unused',
+			redeemed_shop_id INTEGER,
+			redeemed_at DATETIME,
+			redeemed_device_id TEXT,
+			batch TEXT,
+			note TEXT,
+			created_at DATETIME,
+			updated_at DATETIME
+		)`,
 		`CREATE TABLE IF NOT EXISTS license_devices (
 			id INTEGER PRIMARY KEY AUTOINCREMENT,
 			license_id INTEGER NOT NULL,

client/lib/screens/auth/login_screen.dart

@@ -1,6 +1,7 @@
 import 'dart:async';
 
 import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
 import '../../core/responsive/responsive.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
@@ -34,6 +35,16 @@ class _LoginScreenState extends ConsumerState<LoginScreen> {
   bool _obscure = true;
   String? _errorMessage;
 
+  // 客服邮箱（授权续费 / 锁定协助）。与官网 web/_data/site.json 的 support.email 保持一致。
+  static const _supportEmail = 'yammy2023@163.com';
+
+  /// 当前错误是否为「授权锁定」——后端返回固定文案
+  /// `license locked, please renew or contact support`（见 service.ErrLicenseLocked）。
+  bool get _isLicenseLocked {
+    final m = _errorMessage?.toLowerCase() ?? '';
+    return m.contains('license') && (m.contains('lock') || m.contains('expire'));
+  }
+
   List<String> _hotelCodeHistory = [];
   List<String> _usernameHistory = [];
 
@@ -242,6 +253,94 @@ class _LoginScreenState extends ConsumerState<LoginScreen> {
     }
   }
 
+  Future<void> _openRenewSite() async {
+    await launchUrl(
+      Uri.parse(AppConfig.publicBaseUrl),
+      mode: LaunchMode.externalApplication,
+    );
+  }
+
+  Future<void> _copySupportEmail() async {
+    await Clipboard.setData(const ClipboardData(text: _supportEmail));
+    if (!mounted) return;
+    ScaffoldMessenger.of(context).showSnackBar(
+      const SnackBar(content: Text('已复制客服邮箱：$_supportEmail')),
+    );
+  }
+
+  /// 授权锁定时的可操作提示：告诉用户「去哪里解决」——前往官网续费 / 联系客服。
+  Widget _buildLicenseLockedNotice() {
+    return Container(
+      width: double.infinity,
+      padding: const EdgeInsets.all(14),
+      decoration: BoxDecoration(
+        color: AppTheme.danger.withAlpha(15),
+        borderRadius: BorderRadius.circular(6),
+        border: Border.all(color: AppTheme.danger.withAlpha(80)),
+      ),
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: [
+          const Row(
+            children: [
+              Icon(Icons.lock_clock_outlined,
+                  color: AppTheme.danger, size: 18),
+              SizedBox(width: 8),
+              Expanded(
+                child: Text(
+                  '授权已过期，账号已锁定',
+                  style: TextStyle(
+                      color: AppTheme.danger,
+                      fontSize: 14,
+                      fontWeight: FontWeight.w600),
+                ),
+              ),
+            ],
+          ),
+          const SizedBox(height: 6),
+          const Text(
+            '当前门店授权已到期，暂时无法登录。请续费授权后重试，或联系客服协助开通。',
+            style: TextStyle(
+                color: AppTheme.textSecondary, fontSize: 13, height: 1.4),
+          ),
+          const SizedBox(height: 12),
+          Wrap(
+            spacing: 8,
+            runSpacing: 8,
+            children: [
+              ElevatedButton.icon(
+                onPressed: _openRenewSite,
+                icon: const Icon(Icons.open_in_new, size: 16),
+                label: const Text('前往官网续费'),
+                style: ElevatedButton.styleFrom(
+                  backgroundColor: AppTheme.danger,
+                  foregroundColor: Colors.white,
+                  padding: const EdgeInsets.symmetric(
+                      horizontal: 14, vertical: 10),
+                  shape: RoundedRectangleBorder(
+                      borderRadius: BorderRadius.circular(4)),
+                ),
+              ),
+              OutlinedButton.icon(
+                onPressed: _copySupportEmail,
+                icon: const Icon(Icons.support_agent_outlined, size: 16),
+                label: const Text('复制客服邮箱'),
+                style: OutlinedButton.styleFrom(
+                  foregroundColor: AppTheme.danger,
+                  side: BorderSide(color: AppTheme.danger.withAlpha(120)),
+                  padding: const EdgeInsets.symmetric(
+                      horizontal: 14, vertical: 10),
+                  shape: RoundedRectangleBorder(
+                      borderRadius: BorderRadius.circular(4)),
+                ),
+              ),
+            ],
+          ),
+        ],
+      ),
+    );
+  }
+
   @override
   Widget build(BuildContext context) {
     // 被踢下线 / 会话失效：登出后跳回登录页，弹一次提示并清空
@@ -283,20 +382,12 @@ class _LoginScreenState extends ConsumerState<LoginScreen> {
                         child: Column(
                           mainAxisSize: MainAxisSize.min,
                           children: [
-                            // Logo
+                            // Logo（岩美酒库品牌 mark，与 App 图标一致）
                             Container(
                               width: 80,
                               height: 80,
                               decoration: BoxDecoration(
-                                gradient: const LinearGradient(
-                                  colors: [
-                                    AppTheme.primaryLight,
-                                    AppTheme.primaryDark
-                                  ],
-                                  begin: Alignment.topLeft,
-                                  end: Alignment.bottomRight,
-                                ),
-                                borderRadius: BorderRadius.circular(12),
+                                borderRadius: BorderRadius.circular(15),
                                 boxShadow: [
                                   BoxShadow(
                                     color: AppTheme.primary.withAlpha(102),
@@ -305,12 +396,19 @@ class _LoginScreenState extends ConsumerState<LoginScreen> {
                                   ),
                                 ],
                               ),
-                              child: const Icon(Icons.wine_bar,
-                                  color: Colors.white, size: 44),
+                              child: ClipRRect(
+                                borderRadius: BorderRadius.circular(15),
+                                child: Image.asset(
+                                  'assets/brand/logo_mark.png',
+                                  width: 80,
+                                  height: 80,
+                                  fit: BoxFit.cover,
+                                ),
+                              ),
                             ),
                             const SizedBox(height: 20),
                             const Text(
-                              '酒库管理系统',
+                              '岩美酒库',
                               style: TextStyle(
                                 fontSize: 24,
                                 fontWeight: FontWeight.w700,
@@ -320,7 +418,7 @@ class _LoginScreenState extends ConsumerState<LoginScreen> {
                             ),
                             const SizedBox(height: 6),
                             const Text(
-                              '酒店仓库管理解决方案',
+                              '专业酒水仓储 · 进销存一体化管理',
                               style: TextStyle(
                                   fontSize: 13,
                                   color: AppTheme.textSecondary),
@@ -448,32 +546,35 @@ class _LoginScreenState extends ConsumerState<LoginScreen> {
                             // Inline error
                             if (_errorMessage != null) ...[
                               const SizedBox(height: 12),
-                              Container(
-                                width: double.infinity,
-                                padding: const EdgeInsets.symmetric(
-                                    horizontal: 12, vertical: 10),
-                                decoration: BoxDecoration(
-                                  color: AppTheme.danger.withAlpha(15),
-                                  borderRadius: BorderRadius.circular(4),
-                                  border: Border.all(
-                                      color: AppTheme.danger.withAlpha(80)),
-                                ),
-                                child: Row(
-                                  children: [
-                                    const Icon(Icons.error_outline,
-                                        color: AppTheme.danger, size: 16),
-                                    const SizedBox(width: 8),
-                                    Expanded(
-                                      child: Text(
-                                        _errorMessage!,
-                                        style: const TextStyle(
-                                            color: AppTheme.danger,
-                                            fontSize: 13),
+                              if (_isLicenseLocked)
+                                _buildLicenseLockedNotice()
+                              else
+                                Container(
+                                  width: double.infinity,
+                                  padding: const EdgeInsets.symmetric(
+                                      horizontal: 12, vertical: 10),
+                                  decoration: BoxDecoration(
+                                    color: AppTheme.danger.withAlpha(15),
+                                    borderRadius: BorderRadius.circular(4),
+                                    border: Border.all(
+                                        color: AppTheme.danger.withAlpha(80)),
+                                  ),
+                                  child: Row(
+                                    children: [
+                                      const Icon(Icons.error_outline,
+                                          color: AppTheme.danger, size: 16),
+                                      const SizedBox(width: 8),
+                                      Expanded(
+                                        child: Text(
+                                          _errorMessage!,
+                                          style: const TextStyle(
+                                              color: AppTheme.danger,
+                                              fontSize: 13),
+                                        ),
                                       ),
-                                    ),
-                                  ],
+                                    ],
+                                  ),
                                 ),
-                              ),
                             ],
 
                             const SizedBox(height: 24),
@@ -530,7 +631,7 @@ class _LoginScreenState extends ConsumerState<LoginScreen> {
             right: 0,
             child: Center(
               child: Text(
-                '© 2026 酒库管理系统 v1.0.0',
+                '© 2026 岩美酒库 v1.0.0',
                 style: TextStyle(
                     color: Colors.white.withAlpha(102), fontSize: 12),
               ),

client/lib/screens/settings/settings_screen.dart

@@ -455,11 +455,11 @@ class _SettingsScreenState extends ConsumerState<SettingsScreen> {
         child: Column(
           crossAxisAlignment: CrossAxisAlignment.start,
           children: [
-            const Text('激活授权码',
+            const Text('兑换激活码',
                 style:
                     TextStyle(fontSize: 14, fontWeight: FontWeight.w600)),
             const SizedBox(height: 8),
-            const Text('输入从官方渠道获得的授权码以激活或续期',
+            const Text('输入购买或活动获得的激活码，时长将叠加到当前授权之后',
                 style: TextStyle(
                     fontSize: 13, color: AppTheme.textSecondary)),
             const SizedBox(height: 12),
@@ -469,7 +469,7 @@ class _SettingsScreenState extends ConsumerState<SettingsScreen> {
                   child: TextField(
                     controller: _licenseKeyCtrl,
                     decoration: const InputDecoration(
-                      hintText: 'ey... 授权码',
+                      hintText: 'JIUKU-XXXX-XXXX',
                       isDense: true,
                       border: OutlineInputBorder(),
                       contentPadding:
@@ -487,7 +487,7 @@ class _SettingsScreenState extends ConsumerState<SettingsScreen> {
                             width: 16,
                             height: 16,
                             child: CircularProgressIndicator(strokeWidth: 2))
-                        : const Text('激活'),
+                        : const Text('兑换'),
                   ),
                 ],
               ],
@@ -514,7 +514,7 @@ class _SettingsScreenState extends ConsumerState<SettingsScreen> {
       if (mounted) {
         ScaffoldMessenger.of(context).showSnackBar(
           const SnackBar(
-              content: Text('授权激活成功'), backgroundColor: AppTheme.success),
+              content: Text('兑换成功，授权已更新'), backgroundColor: AppTheme.success),
         );
       }
     } catch (e) {

client/pubspec.yaml

@@ -44,3 +44,4 @@ flutter:
   assets:
     - assets/fonts/NotoSansSC-Regular.ttf
     - assets/config/app_info.json
+    - assets/brand/logo_mark.png

docs/architecture/license-design.md

@@ -1,6 +1,45 @@
 # 授权信息功能 — 完整方案设计
 
-> 本文档覆盖「付费授权」功能的产品决策、数据模型、API 设计、安全方案、前端方案及分期实施计划。所有编码工作在本文档评审通过后按计划分批推进。
+> ⚠️ **本文档第 1–11 节为 v1（Ed25519 自包含签名 token 方案），已被 v2「时长兑换券」模型取代。**
+> 实际线上实现以下方「## v2」为准；下方 v1 各节仅作历史保留，其中「激活时验签」「license_token 列」「AdminOnly 激活」等已不再适用。
+
+---
+
+## v2 实际实现（时长兑换券模型，2026-06 起）
+
+### 为什么改
+
+v1 把许可证做成「一个 Ed25519 签名 token = 一张完整授权」，但运行时从不验签（签名形同虚设），且 token 内 `expires_at` 是**绝对日期**、不可叠加，不符合「买一张码续 1 年、可买多张累加」的消费直觉。经产品方确认改为**时长兑换券**。
+
+### 模型要点
+
+- **时长券**：每张码代表一段**时长**（`duration_days`），兑换 = `新到期 = max(今天, 当前到期) + 时长`，**可叠加**；`duration_days=0` 表示永久（到期置 NULL）。
+- **短码 + 服务端码表**：码形如 `JIUKU-7F3A-9K2D`（`util.GenerateRedeemCode`，crypto/rand + 无歧义字母表），归一化（`util.NormalizeCode`）后存 `license_codes` 表。**一码一次**由服务端码表 `status` 强制（签名无法防重放，故 v2 退役 ed25519）。
+- **档位钩子**：`license_codes.tier` / `licenses.tier`（默认 `standard`），为将来 pro/max-like 分档预留；当前不据此做能力差异，分档消费模式后续设计。
+- **签发归平台方**：码由 CLI `go run ./cmd/gencode -type annual -days 365 -count N` 批量生成落库，用户购买/活动获得后在 App「设置 → 授权」兑换。**不开放 App 内自助签发**（防店铺管理员自签终身授权）。
+
+### 数据模型
+
+- 新表 `license_codes`（码池）：`code`(uniq) / `type` / `tier` / `duration_days` / `max_devices` / `status`(unused/redeemed/void) / `redeemed_shop_id` / `redeemed_at` / `redeemed_device_id` / `batch` / `note`。见 `model.LicenseCode` + `schema.sql` + `testutil`。
+- `licenses` 表新增 `tier` 列（additive）。`license_key` 列降级为「当前权益占位」：trial 用 `TRIAL-<uuid>`、无既有行兜底用 `REDEEM-<uuid>`，兑换扩展时不改原值。**v1 的 `license_token` 列未实现，已废弃。**
+
+### 兑换流程（`LicenseService.Redeem`，路由仍 `POST /license/activate` 以兼容客户端）
+
+单事务 + `FOR UPDATE`（check-then-act 并发安全）：① 锁码校验 unused（否则 `无效激活码/已被使用/已失效`）→ ② 锁本店最新 `is_active` 授权行（无则新建）→ ③ 叠加到期、写 `type/tier/max_devices=max(现值,码值)` → ④ 绑定本设备（幂等 + `max_devices` 上限，超限整笔回滚）→ ⑤ 标记码 `redeemed` → ⑥ 提交后 `InvalidateLicensePhase` 即时生效。
+
+### 与 v1 的差异（务必注意）
+
+| 维度 | v1（已废弃） | v2（现状） |
+|------|------|------|
+| 码形态 | Ed25519 246 字符 token | 短码 `JIUKU-XXXX-XXXX` + 服务端码表 |
+| 到期语义 | token 内绝对日期 | 时长券叠加，DB `expires_at` 为准 |
+| 验签 | 计划激活时验签（实际从未生效） | 退役 ed25519，改服务端码表查验 |
+| 签发 | `cmd/issue` 打印 token（需手动 INSERT） | `cmd/gencode` 批量生成并落库 |
+| 激活权限 | 计划加 `AdminOnly` | 维持 `ReadOnly` 豁免、不加 AdminOnly（兑换是店主自助行为） |
+| trial | Ed25519 签发 | 直接建行（无需私钥），`createTrialLicense` 去除 Fatal |
+| 运行时降级 | 同 v2（`LicenseGuard` 读 DB `expires_at` 实时算 phase，30s 缓存） | **不变，沿用** |
+
+> v1 第 7 节「授权状态机与拦截层」（`CalcLicensePhase` / `LicenseGuard` / grace/readonly/locked）**已落地且 v2 沿用**，是两版共同的运行时基础。
 
 ---
 

scripts/set-license-expiry.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# set-license-expiry.sh <门店编号> <带符号天数>
+#
+# 测试工具：把某门店「当前有效授权」(licenses.is_active=1) 的到期时间改成
+# 「相对现在 N 天」，方便快速切换授权阶段验证客户端表现。
+#
+# 带符号天数 DAYS：
+#    30  -> 30 天后到期      → normal   正常（未过期）
+#    0   -> 今天到期
+#   -6   -> 已过期 6 天      → grace    宽限期（仍可登录，有横幅）
+#   -10  -> 已过期 10 天     → readonly 只读（可登录，禁写）
+#   -20  -> 已过期 20 天     → locked   锁定（无法登录）
+#
+# 默认改「线上 prod」EC2 上 jiu_mysql 容器里的 jiu_db.licenses。
+# 连接参数可用环境变量覆盖：
+#   EC2_HOST  (默认 18.136.60.128)
+#   EC2_USER  (默认 ec2-user)
+#   SSH_KEY   (默认 ~/.ssh/wangjia.pem)
+#
+# 用法示例：
+#   sh scripts/set-license-expiry.sh S003 -6    # S003 → 已过期 6 天（grace）
+#   sh scripts/set-license-expiry.sh S003 30    # S003 → 恢复，30 天后到期
+set -euo pipefail
+
+SHOP="${1:-}"
+DAYS="${2:-}"
+if [ -z "$SHOP" ] || [ -z "$DAYS" ]; then
+  echo "用法: $0 <门店编号> <带符号天数>" >&2
+  echo "示例: $0 S003 -6     # S003 授权改为已过期 6 天（grace 宽限期）" >&2
+  echo "      $0 S003 30     # S003 授权恢复，30 天后到期" >&2
+  exit 1
+fi
+case "$DAYS" in
+  ''|*[!0-9-]*) echo "错误: 天数必须是整数（可带负号），收到: '$DAYS'" >&2; exit 1;;
+esac
+
+EC2_HOST="${EC2_HOST:-18.136.60.128}"
+EC2_USER="${EC2_USER:-ec2-user}"
+SSH_KEY="${SSH_KEY:-$HOME/.ssh/wangjia.pem}"
+
+echo "==> 目标(线上 prod): ${EC2_USER}@${EC2_HOST}   门店=${SHOP}   到期=现在 ${DAYS} 天"
+
+# 全部在远端单次 ssh 内完成；DB 密码只在远端从 production.env 读取，绝不打印/外传。
+ssh -o ConnectTimeout=10 -o StrictHostKeyChecking=accept-new -i "$SSH_KEY" \
+  "${EC2_USER}@${EC2_HOST}" bash -s -- "$SHOP" "$DAYS" <<'ENDSSH'
+set -euo pipefail
+SHOP="$1"; DAYS="$2"
+
+sudo grep '^DB_PASSWORD=' /opt/jiu/config/production.env | cut -d= -f2- | {
+  read -r PW
+  MYSQL() { sudo docker exec -i jiu_mysql mysql --default-character-set=utf8mb4 -uroot -p"$PW" jiu_db "$@"; }
+
+  echo "--- 改前 ---"
+  MYSQL -e "SELECT s.code, s.name, l.id, l.type, l.is_active, l.expires_at,
+      TIMESTAMPDIFF(DAY, l.expires_at, NOW()) AS days_expired
+    FROM licenses l JOIN shops s ON s.id = l.shop_id
+    WHERE s.code = '${SHOP}' AND l.is_active = 1 ORDER BY l.id DESC;"
+
+  MYSQL -e "UPDATE licenses SET expires_at = DATE_ADD(NOW(), INTERVAL ${DAYS} DAY)
+    WHERE shop_id = (SELECT id FROM shops WHERE code = '${SHOP}' LIMIT 1)
+      AND is_active = 1;"
+
+  echo "--- 改后 ---"
+  MYSQL -e "SELECT s.code, l.id, l.expires_at,
+      TIMESTAMPDIFF(DAY, l.expires_at, NOW()) AS days_expired
+    FROM licenses l JOIN shops s ON s.id = l.shop_id
+    WHERE s.code = '${SHOP}' AND l.is_active = 1 ORDER BY l.id DESC;"
+}
+ENDSSH
+
+# 阶段提示（与后端 middleware.CalcLicensePhase 边界一致：grace<=7天, readonly<=15天, locked>15天）
+if [ "$DAYS" -ge 0 ]; then
+  PHASE="normal   正常（未过期）"
+else
+  EXP=$(( -DAYS ))
+  if   [ "$EXP" -le 7 ];  then PHASE="grace    宽限期（仍可登录，有横幅提醒）"
+  elif [ "$EXP" -le 15 ]; then PHASE="readonly 只读（可登录，所有写操作被禁）"
+  else                         PHASE="locked   锁定（无法登录，登录页给出续费入口）"
+  fi
+fi
+echo "==> 完成。预计阶段: ${PHASE}"
+echo "==> 提示: 后端 phase 有约 30s 的每店缓存；已登录的客户端会话需等 ~30s 或重新登录后生效。"