feat: 添加硬件指纹功能并优化依赖管理

- 更新依赖管理文档，明确使用 Bun Catalog 统一管理版本并规范安装方式，新增已知问题与解决方案、依赖选择经验及 Git 工作流要求，强化团队协作与技术决策可追溯性。
- 添加硬件指纹页面，展示机器码、指纹质量等级及详细信息，并支持一键复制和缓存提示。
- 添加指纹路由配置并更新路由树类型定义以包含新路由路径和相关类型。
- 添加硬件指纹获取接口的契约定义，包含指纹字符串、质量等级、强标识符数量和时间戳的验证规则。
- 添加指纹合约到API合约导出中
- 添加硬件指纹获取接口，支持10分钟缓存并包含主硬盘序列号以提升指纹稳定性。
- 添加指纹路由到API路由器中
- 重构硬件指纹生成逻辑，引入缓存机制、质量等级评估和容错处理，提升稳定性与可维护性。

apps/server/src/routeTree.gen.ts

@@ -9,10 +9,16 @@
 // Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
 
 import { Route as rootRouteImport } from './routes/__root'
+import { Route as FingerprintRouteImport } from './routes/fingerprint'
 import { Route as IndexRouteImport } from './routes/index'
 import { Route as ApiSplatRouteImport } from './routes/api/$'
 import { Route as ApiRpcSplatRouteImport } from './routes/api/rpc.$'
 
+const FingerprintRoute = FingerprintRouteImport.update({
+  id: '/fingerprint',
+  path: '/fingerprint',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const IndexRoute = IndexRouteImport.update({
   id: '/',
   path: '/',
@@ -31,36 +37,47 @@ const ApiRpcSplatRoute = ApiRpcSplatRouteImport.update({
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
+  '/fingerprint': typeof FingerprintRoute
   '/api/$': typeof ApiSplatRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
+  '/fingerprint': typeof FingerprintRoute
   '/api/$': typeof ApiSplatRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
+  '/fingerprint': typeof FingerprintRoute
   '/api/$': typeof ApiSplatRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
-  fullPaths: '/' | '/api/$' | '/api/rpc/$'
+  fullPaths: '/' | '/fingerprint' | '/api/$' | '/api/rpc/$'
   fileRoutesByTo: FileRoutesByTo
-  to: '/' | '/api/$' | '/api/rpc/$'
-  id: '__root__' | '/' | '/api/$' | '/api/rpc/$'
+  to: '/' | '/fingerprint' | '/api/$' | '/api/rpc/$'
+  id: '__root__' | '/' | '/fingerprint' | '/api/$' | '/api/rpc/$'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
+  FingerprintRoute: typeof FingerprintRoute
   ApiSplatRoute: typeof ApiSplatRoute
   ApiRpcSplatRoute: typeof ApiRpcSplatRoute
 }
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
+    '/fingerprint': {
+      id: '/fingerprint'
+      path: '/fingerprint'
+      fullPath: '/fingerprint'
+      preLoaderRoute: typeof FingerprintRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/': {
       id: '/'
       path: '/'
@@ -87,6 +104,7 @@ declare module '@tanstack/react-router' {
 
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
+  FingerprintRoute: FingerprintRoute,
   ApiSplatRoute: ApiSplatRoute,
   ApiRpcSplatRoute: ApiRpcSplatRoute,
 }

apps/server/src/routes/fingerprint.tsx

@@ -0,0 +1,301 @@
+import { useSuspenseQuery } from '@tanstack/react-query'
+import { createFileRoute } from '@tanstack/react-router'
+import { useEffect, useState } from 'react'
+import { orpc } from '@/client/query-client'
+
+export const Route = createFileRoute('/fingerprint')({
+  component: FingerprintPage,
+  loader: async ({ context }) => {
+    await context.queryClient.ensureQueryData(
+      orpc.fingerprint.get.queryOptions(),
+    )
+  },
+})
+
+function FingerprintPage() {
+  const query = useSuspenseQuery(orpc.fingerprint.get.queryOptions())
+  const [copied, setCopied] = useState(false)
+
+  const data = query.data
+
+  useEffect(() => {
+    if (copied) {
+      const timer = setTimeout(() => setCopied(false), 2000)
+      return () => clearTimeout(timer)
+    }
+  }, [copied])
+
+  const handleCopy = async () => {
+    await navigator.clipboard.writeText(data.fingerprint)
+    setCopied(true)
+  }
+
+  const qualityConfig = {
+    strong: {
+      label: '强',
+      color: 'text-green-600',
+      bg: 'bg-green-50',
+      border: 'border-green-200',
+      icon: '✓',
+      description: '推荐用于生产授权',
+    },
+    medium: {
+      label: '中',
+      color: 'text-yellow-600',
+      bg: 'bg-yellow-50',
+      border: 'border-yellow-200',
+      icon: '!',
+      description: '可用但不理想',
+    },
+    weak: {
+      label: '弱',
+      color: 'text-red-600',
+      bg: 'bg-red-50',
+      border: 'border-red-200',
+      icon: '×',
+      description: '仅适合开发/测试',
+    },
+  }
+
+  const config = qualityConfig[data.quality]
+
+  return (
+    <div className="min-h-screen bg-gradient-to-br from-slate-50 via-blue-50 to-slate-50 py-12 px-4 sm:px-6 font-sans">
+      <div className="max-w-4xl mx-auto space-y-8">
+        {/* Header */}
+        <div className="text-center space-y-3">
+          <h1 className="text-4xl font-bold text-slate-900 tracking-tight">
+            硬件指纹
+          </h1>
+          <p className="text-slate-500 text-lg">用于软件授权和机器码识别</p>
+        </div>
+
+        {/* Main Card */}
+        <div className="bg-white rounded-3xl shadow-xl border border-slate-100 overflow-hidden">
+          {/* Quality Badge */}
+          <div className={`px-8 py-6 border-b ${config.bg} ${config.border}`}>
+            <div className="flex items-center justify-between">
+              <div className="flex items-center gap-3">
+                <div
+                  className={`w-12 h-12 rounded-full ${config.bg} border-2 ${config.border} flex items-center justify-center text-2xl font-bold ${config.color}`}
+                >
+                  {config.icon}
+                </div>
+                <div>
+                  <div className="flex items-center gap-2">
+                    <span className="text-sm font-medium text-slate-600">
+                      指纹质量
+                    </span>
+                    <span
+                      className={`px-3 py-1 rounded-full text-sm font-semibold ${config.bg} ${config.color} border ${config.border}`}
+                    >
+                      {config.label}
+                    </span>
+                  </div>
+                  <p className="text-xs text-slate-500 mt-1">
+                    {config.description}
+                  </p>
+                </div>
+              </div>
+              <div className="text-right">
+                <div className="text-3xl font-bold text-slate-900">
+                  {data.strongIdentifiersCount}
+                </div>
+                <div className="text-xs font-medium text-slate-400 uppercase tracking-wider">
+                  强标识符
+                </div>
+              </div>
+            </div>
+          </div>
+
+          {/* Fingerprint Display */}
+          <div className="px-8 py-8">
+            <div className="space-y-4">
+              <div className="flex items-center justify-between">
+                <div className="text-sm font-semibold text-slate-700 uppercase tracking-wider">
+                  机器码
+                </div>
+                <button
+                  type="button"
+                  onClick={handleCopy}
+                  className={`px-4 py-2 rounded-lg font-medium text-sm transition-all ${
+                    copied
+                      ? 'bg-green-100 text-green-700 border-2 border-green-300'
+                      : 'bg-slate-100 text-slate-700 hover:bg-slate-200 border-2 border-slate-200'
+                  }`}
+                >
+                  {copied ? '已复制 ✓' : '复制'}
+                </button>
+              </div>
+
+              <div className="relative group">
+                <div className="absolute inset-0 bg-gradient-to-r from-blue-500 to-purple-500 rounded-xl blur-sm opacity-0 group-hover:opacity-20 transition-opacity" />
+                <div className="relative bg-slate-900 rounded-xl p-6 font-mono text-sm break-all leading-relaxed text-slate-100 shadow-inner border-2 border-slate-800">
+                  {data.fingerprint}
+                </div>
+              </div>
+
+              <div className="flex items-center gap-2 text-xs text-slate-500">
+                <svg
+                  className="w-4 h-4"
+                  fill="none"
+                  viewBox="0 0 24 24"
+                  stroke="currentColor"
+                  aria-hidden="true"
+                >
+                  <title>信息</title>
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    strokeWidth={2}
+                    d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
+                  />
+                </svg>
+                <span>SHA-256 哈希，43 字符 Base64URL 编码</span>
+              </div>
+            </div>
+          </div>
+
+          {/* Metadata */}
+          <div className="px-8 py-6 bg-slate-50 border-t border-slate-100">
+            <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+              <div className="space-y-2">
+                <div className="text-xs font-semibold text-slate-500 uppercase tracking-wider">
+                  生成时间
+                </div>
+                <div className="text-lg font-medium text-slate-900">
+                  {new Date(data.timestamp).toLocaleString('zh-CN', {
+                    year: 'numeric',
+                    month: '2-digit',
+                    day: '2-digit',
+                    hour: '2-digit',
+                    minute: '2-digit',
+                    second: '2-digit',
+                  })}
+                </div>
+              </div>
+
+              <div className="space-y-2">
+                <div className="text-xs font-semibold text-slate-500 uppercase tracking-wider">
+                  缓存状态
+                </div>
+                <div className="flex items-center gap-2">
+                  <div className="w-2 h-2 rounded-full bg-green-500 animate-pulse" />
+                  <span className="text-lg font-medium text-slate-900">
+                    已缓存 10 分钟
+                  </span>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        {/* Info Cards */}
+        <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+          <div className="bg-white rounded-2xl shadow-md border border-slate-100 p-6 space-y-3">
+            <div className="w-10 h-10 rounded-lg bg-blue-100 flex items-center justify-center">
+              <svg
+                className="w-6 h-6 text-blue-600"
+                fill="none"
+                viewBox="0 0 24 24"
+                stroke="currentColor"
+                aria-hidden="true"
+              >
+                <title>安全</title>
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                  d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"
+                />
+              </svg>
+            </div>
+            <h3 className="font-semibold text-slate-900">安全性</h3>
+            <p className="text-sm text-slate-600 leading-relaxed">
+              使用 HMAC-SHA256 加密，无法反推原始硬件信息
+            </p>
+          </div>
+
+          <div className="bg-white rounded-2xl shadow-md border border-slate-100 p-6 space-y-3">
+            <div className="w-10 h-10 rounded-lg bg-purple-100 flex items-center justify-center">
+              <svg
+                className="w-6 h-6 text-purple-600"
+                fill="none"
+                viewBox="0 0 24 24"
+                stroke="currentColor"
+                aria-hidden="true"
+              >
+                <title>稳定性</title>
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                  d="M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z"
+                />
+              </svg>
+            </div>
+            <h3 className="font-semibold text-slate-900">稳定性</h3>
+            <p className="text-sm text-slate-600 leading-relaxed">
+              基于系统 UUID、序列号等不易变更的标识符
+            </p>
+          </div>
+
+          <div className="bg-white rounded-2xl shadow-md border border-slate-100 p-6 space-y-3">
+            <div className="w-10 h-10 rounded-lg bg-green-100 flex items-center justify-center">
+              <svg
+                className="w-6 h-6 text-green-600"
+                fill="none"
+                viewBox="0 0 24 24"
+                stroke="currentColor"
+                aria-hidden="true"
+              >
+                <title>性能</title>
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                  d="M13 10V3L4 14h7v7l9-11h-7z"
+                />
+              </svg>
+            </div>
+            <h3 className="font-semibold text-slate-900">高性能</h3>
+            <p className="text-sm text-slate-600 leading-relaxed">
+              自动缓存，减少系统调用开销
+            </p>
+          </div>
+        </div>
+
+        {/* Usage Hint */}
+        <div className="bg-blue-50 border-2 border-blue-200 rounded-2xl p-6">
+          <div className="flex gap-4">
+            <div className="flex-shrink-0">
+              <svg
+                className="w-6 h-6 text-blue-600"
+                fill="none"
+                viewBox="0 0 24 24"
+                stroke="currentColor"
+                aria-hidden="true"
+              >
+                <title>提示</title>
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                  d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
+                />
+              </svg>
+            </div>
+            <div className="space-y-2">
+              <h4 className="font-semibold text-blue-900">使用建议</h4>
+              <ul className="text-sm text-blue-800 space-y-1 list-disc list-inside">
+                <li>将机器码存储在授权服务器进行验证</li>
+                <li>建议配合用户账号进行双因素认证</li>
+                <li>同一台机器的指纹保持稳定，便于授权管理</li>
+              </ul>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}

apps/server/src/server/api/contracts/fingerprint.contract.ts

@@ -0,0 +1,26 @@
+import { oc } from '@orpc/contract'
+import { z } from 'zod'
+
+/**
+ * 硬件指纹质量等级
+ */
+const fingerprintQualitySchema = z.enum(['strong', 'medium', 'weak'])
+
+/**
+ * 硬件指纹响应 Schema
+ */
+const fingerprintResultSchema = z.object({
+  /** 机器码（HMAC-SHA256 哈希） */
+  fingerprint: z.string(),
+  /** 指纹质量等级 */
+  quality: fingerprintQualitySchema,
+  /** 可用的强标识符数量 */
+  strongIdentifiersCount: z.number(),
+  /** 生成时间戳 */
+  timestamp: z.number(),
+})
+
+/**
+ * 获取硬件指纹契约
+ */
+export const get = oc.input(z.void()).output(fingerprintResultSchema)

apps/server/src/server/api/contracts/index.ts

@@ -1,6 +1,8 @@
+import * as fingerprint from './fingerprint.contract'
 import * as todo from './todo.contract'
 
 export const contract = {
+  fingerprint,
   todo,
 }
 

apps/server/src/server/api/routers/fingerprint.router.ts

@@ -0,0 +1,11 @@
+import { getHardwareFingerprint } from '@furtherverse/utils/fingerprint'
+import { os } from '../server'
+
+export const get = os.fingerprint.get.handler(async () => {
+  const result = await getHardwareFingerprint({
+    cacheTtlMs: 10 * 60 * 1000, // 10 分钟缓存
+    includePrimaryDisk: true, // 包含主硬盘序列号以提高稳定性
+  })
+
+  return result
+})

apps/server/src/server/api/routers/index.ts

@@ -1,6 +1,8 @@
 import { os } from '../server'
+import * as fingerprint from './fingerprint.router'
 import * as todo from './todo.router'
 
 export const router = os.router({
+  fingerprint,
   todo,
 })