feat(beta): 客户端付费体系——设备指纹/付费状态/AI 用量卡

- 主进程 machineId 设备指纹（激活码一码多设备绑定，首次调用后恒定）
- LicenseActivation 接入设备指纹，到期前 3 天续费提醒
- betaStore 新增 paidStatus（服务端 user_metadata.paid 快照跨设备同步）
- 新增 AiQuotaCard 与 useQuota：服务端权威配额展示（次数/费用双进度）
- 设置页 BetaProfile 展示服务端确认的付费状态与到期日

Author: Aparencia

client/electron/machineId.ts

@@ -0,0 +1,48 @@
+/**
+ * 设备指纹（machineId）— 主进程生成与持久化
+ *
+ * @ai-context: 激活码一码多设备绑定依赖稳定且不可被渲染进程改写的设备标识。
+ * 生成规则：sha256(hostname + platform + arch + 随机盐)，持久化到 userData/machine-id；
+ * 首次调用生成后固定不变（重装系统/换机 = 新指纹，触发服务端设备上限判定）。
+ * @ai-context: 仅主进程可读写（渲染进程经 IPC 白名单只读获取），防止伪造/篡改。
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { arch, hostname, platform } from 'node:os';
+import { app } from 'electron';
+
+/** machine-id 持久化文件名（userData 目录） */
+const MACHINE_ID_FILE = 'machine-id';
+
+/**
+ * 获取设备指纹（首次调用生成并持久化，此后恒定）。
+ *
+ * @returns 32 位十六进制字符串（sha256 截断前 32 字符）
+ */
+export function getMachineId(): string {
+  const filePath = join(app.getPath('userData'), MACHINE_ID_FILE);
+
+  // 已存在则直接返回（稳定优先）
+  if (existsSync(filePath)) {
+    try {
+      const cached = readFileSync(filePath, 'utf-8').trim();
+      if (cached) return cached;
+    } catch (err) {
+      console.warn('[machineId] 读取失败，重新生成:', err);
+    }
+  }
+
+  // 生成：hostname+platform+arch 混合 + 128 位随机盐（防同配置机器指纹碰撞）
+  const salt = randomBytes(16).toString('hex');
+  const raw = `${hostname()}|${platform()}|${arch()}|${salt}`;
+  const machineId = createHash('sha256').update(raw).digest('hex').slice(0, 32);
+
+  try {
+    writeFileSync(filePath, machineId, 'utf-8');
+  } catch (err) {
+    console.warn('[machineId] 持久化失败（本次会话内仍可用）:', err);
+  }
+  return machineId;
+}

client/src/env.d.ts

@@ -58,6 +58,8 @@ declare global {
       safeStorageDecrypt: (encoded: string) => Promise<string>;
       backupSave: (data: string, defaultName?: string) => Promise<unknown>;
       backupOpen: () => Promise<unknown>;
+      /** 设备指纹（激活码一码多设备绑定；主进程生成，首次调用后恒定） */
+      getMachineId?: () => Promise<string>;
       db: {
         query: <T = unknown>(table: string, method: string, args?: unknown[]) => Promise<T>;
         insert: (table: string, item: unknown) => Promise<string>;

client/src/features/beta/AiQuotaCard.tsx

@@ -0,0 +1,83 @@
+/**
+ * AI 用量卡 — 设置页展示当日配额使用情况
+ *
+ * @ai-context: 数据来自服务端权威计数（GET /api/v1/license/quota），
+ * 展示今日调用次数与费用双进度条；网关不可达时静默隐藏（增强信息不阻塞）。
+ */
+import { Gauge, Coins } from 'lucide-react';
+import { useQuota } from '@/features/beta/hooks/useQuota';
+import { TIER_LABELS } from '@/types/beta';
+import { cn } from '@/lib/utils';
+
+/** 用量条（百分比钳制 0-100） */
+function UsageBar({ used, total, tone }: { used: number; total: number; tone: 'brand' | 'warning' }) {
+  const pct = total > 0 ? Math.min(100, Math.round((used / total) * 100)) : 0;
+  return (
+    <div className="h-1.5 rounded-kb-full bg-bg-tertiary overflow-hidden">
+      <div
+        className={cn(
+          'h-full rounded-kb-full transition-all duration-kb-fast',
+          tone === 'brand' ? 'bg-brand-500' : 'bg-semantic-warning',
+        )}
+        style={{ width: `${pct}%` }}
+      />
+    </div>
+  );
+}
+
+/** AI 用量卡（设置页内嵌） */
+export function AiQuotaCard() {
+  const { quota } = useQuota();
+
+  // 网关不可达或未登录时不展示（增强信息）
+  if (!quota || quota.totalCalls <= 0) return null;
+
+  const callPct = quota.totalCalls > 0 ? quota.usedCalls / quota.totalCalls : 0;
+  const costPct = quota.costLimit > 0 ? quota.usedCost / quota.costLimit : 0;
+  const callsNearlyDone = callPct >= 0.8;
+
+  return (
+    <div className="flex flex-col gap-3 p-3 rounded-kb-md bg-bg-elevated border border-border-default">
+      {/* 标题行 */}
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-2">
+          <Gauge className="w-4 h-4 text-brand-500" strokeWidth={1.5} />
+          <span className="text-b3 font-medium text-text-primary">今日 AI 用量</span>
+        </div>
+        <span className="text-c1 text-text-tertiary">{TIER_LABELS[quota.tier]}</span>
+      </div>
+
+      {/* 调用次数 */}
+      <div className="space-y-1">
+        <div className="flex items-center justify-between text-c1">
+          <span className="text-text-tertiary">AI 调用</span>
+          <span className={cn('font-medium', callsNearlyDone ? 'text-semantic-warning' : 'text-text-secondary')}>
+            {quota.usedCalls}/{quota.totalCalls} 次
+          </span>
+        </div>
+        <UsageBar used={quota.usedCalls} total={quota.totalCalls} tone={callsNearlyDone ? 'warning' : 'brand'} />
+      </div>
+
+      {/* 费用 */}
+      <div className="space-y-1">
+        <div className="flex items-center justify-between text-c1">
+          <span className="inline-flex items-center gap-1 text-text-tertiary">
+            <Coins className="w-3 h-3" strokeWidth={1.5} />
+            今日费用
+          </span>
+          <span className="font-medium text-text-secondary">
+            ¥{quota.usedCost.toFixed(2)}/¥{quota.costLimit.toFixed(1)}
+          </span>
+        </div>
+        <UsageBar used={quota.usedCost} total={quota.costLimit} tone={costPct >= 0.8 ? 'warning' : 'brand'} />
+      </div>
+
+      {/* 到期时间（订阅用户） */}
+      {quota.expiresAt && quota.tier !== 'free' && (
+        <p className="text-c1 text-text-tertiary">
+          订阅至 {new Date(quota.expiresAt).toLocaleDateString('zh-CN')}
+        </p>
+      )}
+    </div>
+  );
+}

client/src/features/beta/BetaProfile.tsx

@@ -6,7 +6,7 @@
  * 所有用户可在此输入激活码升级 Pro。
  */
 import { useState } from 'react';
-import { Shield, Check, Gift, Key, Users, ChevronDown, ChevronUp } from 'lucide-react';
+import { Shield, Gift, Key, ChevronDown, ChevronUp } from 'lucide-react';
 import { Card, Button, Input, useToast } from '@/components/ui';
 import { cn } from '@/lib/utils';
 import { useAuth } from '@/lib/auth/AuthContext';
@@ -17,11 +17,11 @@ import { LicenseActivation } from './LicenseActivation';
 
 export function BetaProfile() {
   const { user } = useAuth();
-  const { toast } = useToast();
   const {
     betaProfile,
     effectiveTier,
     activeLicenses,
+    paidStatus,
   } = useBetaStore();
 
   const [expanded, setExpanded] = useState(false);
@@ -114,6 +114,20 @@ export function BetaProfile() {
       {/* 展开面板 */}
       {expanded && (
         <div className="space-y-4">
+          {/* 付费状态（服务端 user_metadata.paid 快照，跨设备同步） */}
+          {paidStatus && (
+            <div className="flex items-center justify-between p-2 rounded-kb-sm bg-brand-50/50 dark:bg-brand-900/10">
+              <span className="text-b3 font-medium text-brand-500">
+                {paidStatus.tier === 'lifetime' ? '✨ 终身 Pro（服务端确认）' : '✨ Pro 订阅（服务端确认）'}
+              </span>
+              {paidStatus.expiresAt && (
+                <span className="text-c1 text-text-tertiary">
+                  至 {new Date(paidStatus.expiresAt).toLocaleDateString('zh-CN')}
+                </span>
+              )}
+            </div>
+          )}
+
           {/* 权益摘要 */}
           <div className="grid grid-cols-2 gap-2">
             <PerkBadge

client/src/features/beta/LicenseActivation.tsx

@@ -4,6 +4,8 @@
  * @ai-context: 用户输入激活码（ENTROPY-{TYPE}-{XXXX}-{XXXX}）升级付费 tier。
  * 本地优先：首次验证需联网，成功后本地缓存 7 天宽限期。
  * 激活码格式：ENTROPY-PRO-XXXX-XXXX（订阅）/ ENTROPY-LIFE-XXXX-XXXX（终身）
+ * @ai-context: machine_id 取主进程设备指纹（electronAPI.getMachineId），
+ * 服务端据此做一码多设备绑定（防分享）；到期前 3 天展示续费提醒。
  */
 import { useState } from 'react';
 import { Key, Check, AlertTriangle, Sparkles, ExternalLink } from 'lucide-react';
@@ -24,6 +26,22 @@ const LICENSE_TYPE_TO_TIER: Record<string, UserTier> = {
   THM1: 'free',    // 主题包不升级 tier
 };
 
+/** 剩余天数（不足 1 天按 0 处理） */
+function daysRemaining(expiresAt: string): number {
+  return Math.ceil((new Date(expiresAt).getTime() - Date.now()) / 86_400_000);
+}
+
+/** 获取设备指纹（Electron 主进程；Web 环境降级为固定占位符） */
+async function getDeviceMachineId(): Promise<string> {
+  try {
+    const mid = await window.electronAPI?.getMachineId?.();
+    if (mid) return mid;
+  } catch {
+    // 主进程不可用（Web 预览等）时降级，服务端按单设备兼容处理
+  }
+  return 'web';
+}
+
 export function LicenseActivation() {
   const { toast } = useToast();
   const { getAccessToken } = useAuth();
@@ -62,6 +80,9 @@ export function LicenseActivation() {
       // 提取类型（trimmed 已 toUpperCase，type 为大写字符串如 'PRO'/'LIFE'）
       const type = trimmed.split('-')[1];
 
+      // 设备指纹（一码多设备绑定；Web 环境降级 'web'）
+      const machineId = await getDeviceMachineId();
+
       // 调服务端验证激活码
       const token = await getAccessToken();
       const resp = await fetch('/api/v1/license/activate', {
@@ -72,7 +93,7 @@ export function LicenseActivation() {
         },
         body: JSON.stringify({
           code: trimmed,
-          machine_id: 'local',
+          machine_id: machineId,
         }),
       });
 
@@ -84,18 +105,19 @@ export function LicenseActivation() {
       const data = await resp.json();
       const tier = LICENSE_TYPE_TO_TIER[type] ?? 'free';
 
+      // 服务端返回的到期时间优先（池记录 duration_days 为准，客户端不再自行 30 天）
+      const serverExpiresAt = typeof data.expires_at === 'string' ? data.expires_at : undefined;
+
       // 创建本地激活码记录
       const license: License = {
         id: crypto.randomUUID(),
         code: trimmed,
         type: type.toLowerCase() as LicenseType,
         tier,
         status: 'active',
-        machineId: 'local',
+        machineId,
         activatedAt: new Date().toISOString(),
-        expiresAt: type === 'PRO'  // 使用大写常量比较
-          ? new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString()
-          : data.expires_at || undefined,
+        expiresAt: serverExpiresAt,
         syncedAt: new Date().toISOString(),
       };
 
@@ -121,20 +143,34 @@ export function LicenseActivation() {
     const activeLicense = activeLicenses.find(
       (l) => (l.tier === 'pro' || l.tier === 'lifetime') && l.status === 'active',
     );
+    const expiresAt = activeLicense?.expiresAt;
+    const remainingDays = expiresAt ? daysRemaining(expiresAt) : 0;
+    const isAnnual = !!expiresAt && remainingDays >= 300;  // 年付方案识别（服务端时长为准）
+    const expiringSoon = !!expiresAt && remainingDays > 0 && remainingDays <= 3;
     return (
-      <div className="flex items-center gap-2 p-3 rounded-kb-md bg-semantic-success/5 border border-semantic-success/20">
-        <Sparkles className="w-4 h-4 text-semantic-success flex-shrink-0" strokeWidth={1.5} />
-        <div className="flex-1 min-w-0">
-          <p className="text-b3 font-medium text-semantic-success">
-            {activeLicense?.tier === 'lifetime' ? '终身 Pro 已激活' : 'Pro 已激活'}
-          </p>
-          {activeLicense?.expiresAt && (
-            <p className="text-c1 text-text-tertiary">
-              有效期至 {new Date(activeLicense.expiresAt).toLocaleDateString('zh-CN')}
+      <div className="flex flex-col gap-2 p-3 rounded-kb-md bg-semantic-success/5 border border-semantic-success/20">
+        <div className="flex items-center gap-2">
+          <Sparkles className="w-4 h-4 text-semantic-success flex-shrink-0" strokeWidth={1.5} />
+          <div className="flex-1 min-w-0">
+            <p className="text-b3 font-medium text-semantic-success">
+              {activeLicense?.tier === 'lifetime' ? '终身 Pro 已激活' : `Pro 已激活${isAnnual ? '（年付方案）' : ''}`}
             </p>
-          )}
+            {expiresAt && (
+              <p className="text-c1 text-text-tertiary">
+                有效期至 {new Date(expiresAt).toLocaleDateString('zh-CN')}
+                {activeLicense?.tier !== 'lifetime' && `（剩余 ${remainingDays} 天）`}
+              </p>
+            )}
+          </div>
+          <span className="text-c1 text-semantic-success">已激活</span>
         </div>
-        <span className="text-c1 text-semantic-success">已激活</span>
+        {/* 到期前 3 天温和提醒（非阻断） */}
+        {expiringSoon && (
+          <div className="flex items-center gap-1.5 text-c1 text-semantic-warning">
+            <AlertTriangle className="w-3.5 h-3.5 flex-shrink-0" strokeWidth={1.5} />
+            订阅将于 {remainingDays} 天后到期，续费保持 Pro 权益
+          </div>
+        )}
       </div>
     );
   }

client/src/features/beta/betaStore.test.ts

@@ -0,0 +1,93 @@
+/**
+ * betaStore — effectiveTier 计算测试
+ *
+ * @ai-context: 覆盖 paidStatus（服务端 user_metadata.paid 快照）纳入
+ * effectiveTier 计算的行为：跨设备订阅同步、过期降级、与本地激活码/内测身份取最高者。
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+import { useBetaStore } from './betaStore';
+import type { License, PaidStatus } from '@/types/beta';
+
+/** 构造一条本地激活码记录 */
+function makeLicense(tier: License['tier'], status: License['status'] = 'active'): License {
+  return {
+    id: `lic-${tier}-${status}`,
+    code: `ENTROPY-${tier.toUpperCase()}-AAAA-BBBB`,
+    type: tier === 'lifetime' ? 'lifetime' : tier === 'pro' ? 'pro' : 'snd1',
+    tier,
+    status,
+    machineId: 'm1',
+    activatedAt: new Date().toISOString(),
+    expiresAt: new Date(Date.now() + 30 * 86_400_000).toISOString(),
+    syncedAt: new Date().toISOString(),
+  };
+}
+
+/** 构造服务端付费快照 */
+function makePaidStatus(tier: 'pro' | 'lifetime', expiresInDays?: number): PaidStatus {
+  return {
+    tier,
+    ...(expiresInDays !== undefined
+      ? { expiresAt: new Date(Date.now() + expiresInDays * 86_400_000).toISOString() }
+      : {}),
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+beforeEach(() => {
+  useBetaStore.getState().reset();
+});
+
+describe('betaStore.recalcEffectiveTier', () => {
+  it('服务端 paid 快照（lifetime）无本地激活码时提升 tier', () => {
+    // Arrange：仅登录快照（跨设备场景，本机无激活记录）
+    useBetaStore.getState().setPaidStatus(makePaidStatus('lifetime'));
+
+    // Act
+    const tier = useBetaStore.getState().effectiveTier;
+
+    // Assert
+    expect(tier).toBe('lifetime');
+  });
+
+  it('服务端 paid 快照（pro 未过期）生效', () => {
+    useBetaStore.getState().setPaidStatus(makePaidStatus('pro', 30));
+    expect(useBetaStore.getState().effectiveTier).toBe('pro');
+  });
+
+  it('服务端 paid 快照过期后不提升 tier', () => {
+    // Arrange：已过期的 pro 快照
+    useBetaStore.getState().setPaidStatus(makePaidStatus('pro', -1));
+    expect(useBetaStore.getState().effectiveTier).toBe('free');
+  });
+
+  it('本地激活码 pro 优先于 paid 快照（两者同等级取本地）', () => {
+    useBetaStore.getState().addLicense(makeLicense('pro'));
+    expect(useBetaStore.getState().effectiveTier).toBe('pro');
+  });
+
+  it('内测 core + 本地 pro → 取 core（rank 最高者）', () => {
+    useBetaStore.getState().setBetaProfile({
+      id: 'p1', userId: 'u1', tier: 'core', cohort: 1,
+      joinedAt: new Date().toISOString(), lifetimePro: false,
+      badges: [], perksConfig: '{}',
+    });
+    useBetaStore.getState().addLicense(makeLicense('pro'));
+    expect(useBetaStore.getState().effectiveTier).toBe('core');
+  });
+
+  it('内测 observer + 服务端 lifetime → 取 lifetime', () => {
+    useBetaStore.getState().setBetaProfile({
+      id: 'p2', userId: 'u1', tier: 'observer', cohort: 1,
+      joinedAt: new Date().toISOString(), lifetimePro: false,
+      badges: [], perksConfig: '{}',
+    });
+    useBetaStore.getState().setPaidStatus(makePaidStatus('lifetime'));
+    expect(useBetaStore.getState().effectiveTier).toBe('lifetime');
+  });
+
+  it('失效激活码（expired）不计入付费 tier', () => {
+    useBetaStore.getState().addLicense(makeLicense('pro', 'expired'));
+    expect(useBetaStore.getState().effectiveTier).toBe('free');
+  });
+});