docs: 简化依赖管理文档，聚焦 Bun Catalog 版本控制

- 简化依赖管理文档，聚焦使用 Bun Catalog 统一版本控制，并提供清晰的安装与查询命令参考。

.env.example

@@ -1 +0,0 @@
-DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres

.gitignore

@@ -6,6 +6,12 @@
 # Nitro
 .output/
 
+# Bun build
+*.bun-build
+
+# Turborepo
+.turbo/
+
 ### Node ###
 
 # Logs

.sisyphus/notepads/fingerprint-migration/decisions.md

@@ -0,0 +1,8 @@
+## Migration Decisions
+
+- **Library**: `@isaacs/ttlcache` v2.1.4
+- **Rationale**: Minimal, zero-dependency, specialized for TTL, well-maintained.
+- **Cache Key**: Fixed string `'fingerprint'` since we only cache one result.
+- **Max Items**: 1 (singleton fingerprint).
+- **Default TTL**: 10 minutes (compatible with previous implementation).
+

.sisyphus/notepads/fingerprint-migration/learnings.md

@@ -0,0 +1,8 @@
+## @isaacs/ttlcache Migration Learnings
+
+- Successfully replaced manual TTL cache with `@isaacs/ttlcache` in `fingerprint.ts`.
+- Use `catalog:` for dependency management in the Bun monorepo.
+- `TTLCache` does not handle in-flight request deduplication, so the `inFlight` Promise pattern was preserved.
+- Alphabetical sorting in `package.json` catalog is important for consistency.
+- Biome handles import organization and formatting; `bun fix` should be run after manual edits.
+

.sisyphus/notepads/license-activation/decisions.md

@@ -0,0 +1,3 @@
+## Decisions
+
+- Renamed `db` middleware to `dbProvider` as requested, while keeping `db` as an alias to avoid breaking existing routers.

.sisyphus/notepads/license-activation/issues.md

@@ -0,0 +1,4 @@
+## Issues encountered
+
+- `db:migrate` failed due to `device_info` table already existing in the local SQLite database. Resolved by using `db:push` which is suitable for dev environments.
+- `lsp_diagnostics` was not available, used `bun typecheck` (`tsc --noEmit`) instead.

.sisyphus/notepads/license-activation/learnings.md

@@ -0,0 +1,7 @@
+## License Activation Implementation
+
+- Created `license_activation` table for better semantic clarity.
+- Implemented `ensureLicenseActivationInitialized` with UPSERT logic and singleton pattern.
+- Added ORPC endpoints `license.getActivation` and `license.activate`.
+- Used `db:push` to handle migration in dev environment when conflicts occur.
+- Fixed type mismatch in `device.router.ts` where `Date` was returned instead of `number` for timestamp fields.

.vscode/settings.json

@@ -37,7 +37,8 @@
   "files.associations": {
     ".env": "dotenv",
     ".env.*": "dotenv",
-    "**/tsconfig*.json": "jsonc",
+    "**/tsconfig.json": "jsonc",
+    "**/tsconfig.*.json": "jsonc",
     "**/biome.json": "jsonc",
     "**/opencode.json": "jsonc"
   },

AGENTS.md

@@ -1,323 +0,0 @@
-# AGENTS.md - AI Coding Agent Guidelines
-
-This document provides comprehensive guidelines for AI coding agents working in this TanStack Start fullstack starter codebase.
-
-## Project Overview
-
-- **Framework**: TanStack Start (React SSR framework with file-based routing)
-- **Runtime**: Bun
-- **Language**: TypeScript (strict mode, ESNext)
-- **Styling**: Tailwind CSS v4
-- **Database**: PostgreSQL with Drizzle ORM
-- **State Management**: TanStack Query
-- **Routing**: TanStack Router (file-based)
-- **RPC**: ORPC (type-safe RPC with contract-first design)
-- **Build Tool**: Vite
-- **Linter/Formatter**: Biome
-
-## Build, Lint, and Test Commands
-
-### Development
-```bash
-bun dev                    # Start development server
-bun db:studio              # Open Drizzle Studio for database management
-```
-
-### Building
-```bash
-bun build                  # Build for production (outputs to .output/)
-bun compile                # Compile to standalone executable (out/server)
-bun serve                  # Preview production build
-```
-
-### Code Quality
-```bash
-bun typecheck              # Run TypeScript compiler (tsc -b)
-bun fix                    # Run Biome linter and formatter (auto-fix issues)
-biome check .              # Check without auto-fix
-biome format --write .     # Format code only
-```
-
-### Database
-```bash
-bun db:generate            # Generate migration files from schema
-bun db:migrate             # Run migrations
-bun db:push                # Push schema changes directly (dev only)
-```
-
-### Testing
-**Note**: No test framework is currently configured. When adding tests:
-- Use Vitest or Bun's built-in test runner
-- Run single test file: `bun test path/to/test.ts`
-- Run specific test: `bun test -t "test name pattern"`
-
-## Code Style Guidelines
-
-### Formatting (Biome)
-
-**Indentation**: 2 spaces (not tabs)
-**Line Endings**: LF (Unix-style)
-**Quotes**: Single quotes for strings
-**Semicolons**: As needed (ASI - automatic semicolon insertion)
-**Arrow Parens**: Always use parentheses `(x) => x`
-
-Example:
-```typescript
-const myFunc = (value: string) => {
-  return value.toUpperCase()
-}
-```
-
-### Import Organization
-
-Imports are auto-organized by Biome. Order:
-1. External dependencies
-2. Internal imports using `@/*` alias
-3. Type imports (use `type` keyword when importing only types)
-
-Example:
-```typescript
-import { createFileRoute } from '@tanstack/react-router'
-import { createServerFn } from '@tanstack/react-start'
-import { db } from '@/db'
-import type { ReactNode } from 'react'
-```
-
-### TypeScript
-
-**Strict Mode**: Enabled with additional strictness flags
-- `strict: true`
-- `noUncheckedIndexedAccess: true` - Array/object indexing returns `T | undefined`
-- `noImplicitOverride: true`
-- `noFallthroughCasesInSwitch: true`
-
-**Module Resolution**: `bundler` mode with `verbatimModuleSyntax`
-- Always use `.ts`/`.tsx` extensions in imports
-- Use `@/*` path alias for `src/*`
-
-**Type Annotations**:
-- Always annotate function parameters and return types for public APIs
-- Prefer explicit types over `any`
-- Use `type` for object shapes, `interface` for extendable contracts
-- Use `Readonly<T>` for immutable props
-
-Example:
-```typescript
-function getTodos(): Promise<Todo[]> {
-  return db.query.todoTable.findMany()
-}
-
-type Props = Readonly<{
-  children: ReactNode
-}>
-```
-
-### Naming Conventions
-
-- **Files**: kebab-case for utilities, PascalCase for components
-  - `utils.ts`, `todo.tsx`, `NotFound.tsx`
-- **Routes**: Use TanStack Router conventions
-  - `routes/index.tsx` → `/`
-  - `routes/todo.tsx` → `/todo`
-  - `routes/__root.tsx` → Root layout
-- **Components**: PascalCase function declarations
-- **Functions**: camelCase
-- **Constants**: UPPER_SNAKE_CASE for true constants, camelCase for config objects
-- **Types/Interfaces**: PascalCase
-
-### React Patterns
-
-**Components**: Use arrow functions (enforced by Biome rule `useArrowFunction`)
-```typescript
-const MyComponent = ({ title }: { title: string }) => {
-  return <div>{title}</div>
-}
-```
-
-**Server Functions**: Use TanStack Start's `createServerFn`
-```typescript
-const getTodos = createServerFn({ method: 'GET' }).handler(async () => {
-  const todos = await db.query.todoTable.findMany()
-  return todos
-})
-```
-
-**Routing**: Use `createFileRoute` for route definitions
-```typescript
-export const Route = createFileRoute('/todo')({
-  component: Todo,
-})
-```
-
-**Data Fetching**: Use TanStack Query hooks
-- `useSuspenseQuery` for guaranteed data
-- `useQuery` when data might be optional
-
-**Props**: No direct prop mutations (enforced by `noReactPropAssignments`)
-
-### Database Schema (Drizzle)
-
-- Define schemas in `src/db/schema/*.ts`
-- Export from `src/db/schema/index.ts`
-- Use PostgreSQL types from `drizzle-orm/pg-core`
-- Use `uuidv7()` for primary keys (requires PostgreSQL extension)
-- Always include `createdAt` and `updatedAt` timestamps
-
-Example:
-```typescript
-import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'
-import { sql } from 'drizzle-orm'
-
-export const myTable = pgTable('my_table', {
-  id: uuid('id').primaryKey().default(sql`uuidv7()`),
-  name: text('name').notNull(),
-  createdAt: timestamp('created_at', { withTimezone: true })
-    .notNull()
-    .defaultNow(),
-  updatedAt: timestamp('updated_at', { withTimezone: true })
-    .notNull()
-    .defaultNow()
-    .$onUpdateFn(() => new Date()),
-})
-```
-
-### Environment Variables
-
-- Use `@t3-oss/env-core` for type-safe env validation
-- Define schema in `src/env.ts`
-- Server vars: No prefix
-- Client vars: Must have `VITE_` prefix
-- Always validate with Zod schemas
-
-### Error Handling
-
-- Use try-catch for async operations
-- Throw errors with descriptive messages
-- Prefer Result types or error boundaries for user-facing errors
-- Log errors appropriately (avoid logging sensitive data)
-
-### Styling (Tailwind CSS)
-
-- Use Tailwind v4 utility classes
-- Import styles via `@/styles.css?url`
-- Prefer composition over custom CSS
-- Use responsive modifiers: `sm:`, `md:`, `lg:`
-- Use Chinese text for UI when appropriate (as seen in codebase)
-
-## File Structure
-
-```
-src/
-├── components/         # Reusable React components
-├── db/
-│   ├── schema/        # Drizzle schema definitions
-│   └── index.ts       # Database instance
-├── lib/               # Utility functions
-├── orpc/              # ORPC (RPC layer)
-│   ├── contracts/     # Contract definitions (input/output schemas)
-│   ├── handlers/      # Server-side procedure implementations
-│   ├── middlewares/   # Middleware (e.g., DB provider)
-│   ├── contract.ts    # Contract aggregation
-│   ├── router.ts      # Router composition
-│   ├── server.ts      # Server instance
-│   ├── client.ts      # Isomorphic client
-│   └── types.ts       # Type utilities
-├── routes/            # TanStack Router file-based routes
-│   ├── __root.tsx     # Root layout
-│   ├── index.tsx      # Home page
-│   └── api/rpc.$.ts   # ORPC HTTP endpoint
-├── env.ts             # Environment variable validation
-├── index.ts           # Application entry point
-├── router.tsx         # Router configuration
-├── routeTree.gen.ts   # Auto-generated (DO NOT EDIT)
-└── styles.css         # Global styles
-```
-
-## Important Notes
-
-- **DO NOT** edit `src/routeTree.gen.ts` - it's auto-generated
-- **DO NOT** commit `.env` files - use `.env.example` for templates
-- **DO** run `bun fix` before committing to ensure code quality
-- **DO** use the `@/*` path alias instead of relative imports
-- **DO** leverage React Compiler (babel-plugin-react-compiler) - avoid manual memoization
-
-## Git Workflow
-
-1. Make changes following the style guidelines above
-2. Run `bun fix` to auto-format and lint
-3. Run `bun typecheck` to ensure type safety
-4. Test changes locally with `bun dev`
-5. Commit with clear, descriptive messages
-
-## Common Patterns
-
-### Adding a New Route
-1. Create `src/routes/my-route.tsx`
-2. Export route with `createFileRoute`
-3. Route tree auto-updates on save
-
-### Adding Database Table
-1. Create schema in `src/db/schema/my-table.ts`
-2. Export from `src/db/schema/index.ts`
-3. Run `bun db:generate` to create migration
-4. Run `bun db:migrate` to apply migration
-
-### Creating Server Function
-```typescript
-const myServerFn = createServerFn({ method: 'POST' })
-  .validator((data) => mySchema.parse(data))
-  .handler(async ({ data }) => {
-    // Server-side logic here
-    return result
-  })
-```
-
-### Creating ORPC Procedures
-
-**Step 1: Define Contract** (`src/orpc/contracts/my-feature.ts`)
-```typescript
-import { oc } from '@orpc/contract'
-import { z } from 'zod'
-
-export const myContract = {
-  get: oc.input(z.object({ id: z.uuid() })).output(mySchema),
-  create: oc.input(createSchema).output(mySchema),
-}
-```
-
-**Step 2: Implement Handler** (`src/orpc/handlers/my-feature.ts`)
-```typescript
-import { os } from '@/orpc/server'
-import { dbProvider } from '@/orpc/middlewares'
-
-export const get = os.myFeature.get
-  .use(dbProvider)
-  .handler(async ({ context, input }) => {
-    const item = await context.db.query.myTable.findFirst(...)
-    return item
-  })
-```
-
-**Step 3: Register in Contract & Router**
-```typescript
-// src/orpc/contract.ts
-export const contract = {
-  myFeature: myContract,
-}
-
-// src/orpc/router.ts
-import * as myFeature from './handlers/my-feature'
-export const router = os.router({ myFeature })
-```
-
-**Step 4: Use in Component**
-```typescript
-import { orpc } from '@/orpc'
-const query = useSuspenseQuery(orpc.myFeature.get.queryOptions({ id }))
-const mutation = useMutation(orpc.myFeature.create.mutationOptions())
-```
-
----
-
-**Last Updated**: 2026-01-18
-**Project Version**: Based on package.json dependencies

apps/server/.env.example

@@ -0,0 +1 @@
+DATABASE_URL=./data/app.db

apps/server/.gitignore

@@ -0,0 +1,5 @@
+# SQLite database files
+data/
+*.db
+*.db-shm
+*.db-wal

apps/server/AGENTS.md

@@ -0,0 +1,420 @@
+# AGENTS.md - AI Coding Agent Guidelines
+
+本文档为 AI 编程助手提供此 TanStack Start 全栈项目的开发规范和指南。
+
+## 项目概览
+
+- **框架**: TanStack Start (React SSR 框架，文件路由)
+- **运行时**: Bun
+- **语言**: TypeScript (strict mode, ESNext)
+- **样式**: Tailwind CSS v4
+- **数据库**: SQLite + Drizzle ORM
+- **状态管理**: TanStack Query
+- **路由**: TanStack Router (文件路由)
+- **RPC**: ORPC (类型安全 RPC，契约优先)
+- **构建工具**: Vite + Turbo
+- **代码质量**: Biome (格式化 + Lint)
+
+## 依赖管理
+
+项目使用 **Bun Catalog** 统一管理依赖版本。
+
+> **详细流程**: 加载 skill `bun-catalog-package` 获取完整指南。
+
+**快速参考**：
+```bash
+bun info <pkg> version          # 查询最新版本
+bun add <pkg>@catalog:          # 在子包中安装
+```
+
+## 构建、Lint 和测试命令
+
+### 开发
+```bash
+bun dev                    # 启动 Vite 开发服务器
+bun db:studio              # 打开 Drizzle Studio 数据库管理界面
+```
+
+### 构建
+```bash
+bun build                  # 构建 Vite 应用 (输出到 .output/)
+bun compile                # 编译为独立可执行文件 (使用 build.ts)
+```
+
+### 代码质量
+```bash
+bun typecheck              # 运行 TypeScript 类型检查
+bun fix                    # 运行 Biome 自动修复格式和 Lint 问题
+biome check .              # 检查但不自动修复
+biome format --write .     # 仅格式化代码
+```
+
+### 数据库
+```bash
+bun db:generate            # 从 schema 生成迁移文件
+bun db:migrate             # 执行数据库迁移
+bun db:push                # 直接推送 schema 变更 (仅开发环境)
+```
+
+### 测试
+**注意**: 当前未配置测试框架。添加测试时:
+- 使用 Vitest 或 Bun 内置测试运行器
+- 运行单个测试文件: `bun test path/to/test.ts`
+- 运行特定测试: `bun test -t "测试名称模式"`
+
+## 代码风格指南
+
+### 格式化 (Biome)
+
+**缩进**: 2 空格 (不使用 tab)
+**换行符**: LF (Unix 风格)
+**引号**: 单引号 `'string'`
+**分号**: 按需 (ASI - 自动分号插入)
+**箭头函数括号**: 始终使用 `(x) => x`
+
+示例:
+```typescript
+const myFunc = (value: string) => {
+  return value.toUpperCase()
+}
+```
+
+### 导入组织
+
+Biome 自动组织导入。顺序:
+1. 外部依赖
+2. 内部导入 (使用 `@/*` 别名)
+3. 类型导入 (仅导入类型时使用 `type` 关键字)
+
+示例:
+```typescript
+import { createFileRoute } from '@tanstack/react-router'
+import { oc } from '@orpc/contract'
+import { z } from 'zod'
+import { db } from '@/db'
+import { todoTable } from '@/db/schema'
+import type { ReactNode } from 'react'
+```
+
+### TypeScript
+
+**严格模式**: 启用了额外的严格检查
+- `strict: true`
+- `noUncheckedIndexedAccess: true` - 数组/对象索引返回 `T | undefined`
+- `noImplicitOverride: true`
+- `noFallthroughCasesInSwitch: true`
+
+**模块解析**: `bundler` 模式 + `verbatimModuleSyntax`
+- 导入时始终使用 `.ts`/`.tsx` 扩展名
+- 使用 `@/*` 路径别名指向 `src/*`
+
+**类型注解**:
+- 公共 API 的函数参数和返回类型必须注解
+- 优先使用显式类型而非 `any`
+- 对象形状用 `type`，可扩展契约用 `interface`
+- 不可变 props 使用 `Readonly<T>`
+
+### 命名规范
+
+- **文件**: 工具函数用 kebab-case，组件用 PascalCase
+  - `utils.ts`, `todo.tsx`, `NotFound.tsx`
+- **路由**: 遵循 TanStack Router 约定
+  - `routes/index.tsx` → `/`
+  - `routes/__root.tsx` → 根布局
+- **组件**: PascalCase 箭头函数 (Biome 规则 `useArrowFunction` 强制)
+- **函数**: camelCase
+- **常量**: 真常量用 UPPER_SNAKE_CASE，配置对象用 camelCase
+- **类型/接口**: PascalCase
+
+### React 模式
+
+**组件**: 使用箭头函数
+```typescript
+const MyComponent = ({ title }: { title: string }) => {
+  return <div>{title}</div>
+}
+```
+
+**路由**: 使用 `createFileRoute` 定义路由
+```typescript
+export const Route = createFileRoute('/')({
+  component: Home,
+})
+```
+
+**数据获取**: 使用 TanStack Query hooks
+- `useSuspenseQuery` - 保证有数据
+- `useQuery` - 数据可能为空
+
+**Props**: 禁止直接修改 props (Biome 规则 `noReactPropAssignments`)
+
+### 数据库 Schema (Drizzle)
+
+- 在 `src/server/db/schema/*.ts` 定义 schema
+- 从 `src/server/db/schema/index.ts` 导出
+- 使用 `drizzle-orm/sqlite-core` 的 SQLite 类型
+- 主键使用 `uuidv7()` (TEXT 存储)
+- 时间戳使用 `integer({ mode: 'timestamp_ms' })` (Unix 毫秒时间戳)
+- 始终包含 `createdAt` 和 `updatedAt` 时间戳
+
+示例:
+```typescript
+import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
+import { v7 as uuidv7 } from 'uuid'
+
+export const myTable = sqliteTable('my_table', {
+  id: text('id').primaryKey().$defaultFn(() => uuidv7()),
+  name: text('name').notNull(),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull().$defaultFn(() => new Date()),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull().$defaultFn(() => new Date()).$onUpdateFn(() => new Date()),
+})
+```
+
+### 环境变量
+
+- 使用 `@t3-oss/env-core` 进行类型安全的环境变量验证
+- 在 `src/env.ts` 定义 schema
+- 服务端变量: 无前缀
+- 客户端变量: 必须有 `VITE_` 前缀
+- 使用 Zod schema 验证
+
+### 错误处理
+
+- 异步操作使用 try-catch
+- 抛出带有描述性消息的错误
+- 用户界面错误优先使用 Result 类型或错误边界
+- 适当记录错误 (避免记录敏感数据)
+
+### 样式 (Tailwind CSS)
+
+- 使用 Tailwind v4 工具类
+- 通过 `@/styles.css?url` 导入样式
+- 优先使用组合而非自定义 CSS
+- 响应式修饰符: `sm:`, `md:`, `lg:`
+- UI 文本适当使用中文
+
+## 目录结构
+
+```
+src/
+├── components/            # 可复用 React 组件
+├── db/
+│   ├── schema/           # Drizzle schema 定义
+│   └── index.ts          # 数据库实例
+├── integrations/         # 第三方集成 (TanStack Query/Router)
+├── lib/                  # 工具函数
+├── orpc/                 # ORPC (RPC 层)
+│   ├── contracts/        # 契约定义 (input/output schemas)
+│   ├── handlers/         # 服务端过程实现
+│   ├── middlewares/      # 中间件 (如 DB provider)
+│   ├── contract.ts       # 契约聚合
+│   ├── router.ts         # 路由组合
+│   ├── server.ts         # 服务端实例
+│   └── client.ts         # 同构客户端
+├── routes/               # TanStack Router 文件路由
+│   ├── __root.tsx        # 根布局
+│   ├── index.tsx         # 首页
+│   └── api/rpc.$.ts      # ORPC HTTP 端点
+├── env.ts                # 环境变量验证
+└── router.tsx            # 路由配置
+```
+
+## 重要提示
+
+- **禁止** 编辑 `src/routeTree.gen.ts` - 自动生成
+- **禁止** 提交 `.env` 文件 - 使用 `.env.example` 作为模板
+- **必须** 在提交前运行 `bun fix`
+- **必须** 使用 `@/*` 路径别名而非相对导入
+- **必须** 利用 React Compiler (babel-plugin-react-compiler) - 避免手动 memoization
+
+## Git 工作流
+
+1. 按照上述风格指南进行修改
+2. 运行 `bun fix` 自动格式化和 lint
+3. 运行 `bun typecheck` 确保类型安全
+4. 使用 `bun dev` 本地测试变更
+5. 使用清晰的描述性消息提交
+
+## 常见模式
+
+### 创建 ORPC 过程
+
+**步骤 1: 定义契约** (`src/orpc/contracts/my-feature.ts`)
+```typescript
+import { oc } from '@orpc/contract'
+import { z } from 'zod'
+
+export const myContract = {
+  get: oc.input(z.object({ id: z.uuid() })).output(mySchema),
+  create: oc.input(createSchema).output(mySchema),
+}
+```
+
+**步骤 2: 实现处理器** (`src/orpc/handlers/my-feature.ts`)
+```typescript
+import { os } from '@/orpc/server'
+import { dbProvider } from '@/orpc/middlewares'
+
+export const get = os.myFeature.get
+  .use(dbProvider)
+  .handler(async ({ context, input }) => {
+    return await context.db.query.myTable.findFirst(...)
+  })
+```
+
+**步骤 3: 注册到契约和路由**
+```typescript
+// src/orpc/contract.ts
+export const contract = { myFeature: myContract }
+
+// src/orpc/router.ts
+import * as myFeature from './handlers/my-feature'
+export const router = os.router({ myFeature })
+```
+
+**步骤 4: 在组件中使用**
+```typescript
+import { orpc } from '@/orpc'
+const query = useSuspenseQuery(orpc.myFeature.get.queryOptions({ id }))
+const mutation = useMutation(orpc.myFeature.create.mutationOptions())
+```
+
+---
+
+## 已知问题与解决方案
+
+### 构建问题
+
+**已解决**: Vite 8.0.0-beta.10 已修复与 Nitro 插件的兼容性问题
+- **当前版本**: Vite 8.0.0-beta.10 + nitro-nightly@3.0.1-20260125
+- **状态**: 构建稳定，开发和生产环境均正常工作
+
+### 依赖选择经验
+
+**ohash vs crypto.createHash**
+
+在实现硬件指纹功能时，曾误判 `ohash` 不适合用于硬件指纹识别。经深入研究发现：
+
+**事实**：
+- `ohash` 内部使用**完整的 SHA-256** 算法（256 位）
+- 输出 43 字符 Base64URL 编码（等价于 64 字符 Hex）
+- 碰撞概率与 `crypto.createHash('sha256')` **完全相同**（2^128）
+- 自动处理对象序列化，代码更简洁
+
+**对比**：
+```typescript
+// ohash - 推荐用于对象哈希
+import { hash } from 'ohash'
+const fingerprint = hash(systemInfo) // 一行搞定
+
+// crypto - 需要手动序列化
+import { createHash } from 'node:crypto'
+const fingerprint = createHash('sha256')
+  .update(JSON.stringify(systemInfo))
+  .digest('base64url')
+```
+
+**结论**：
+- ✅ `ohash` 完全适合硬件指纹场景（数据来自系统 API，非用户输入）
+- ✅ 两者安全性等价，选择取决于代码风格偏好
+- ⚠️ ohash 文档警告的"序列化安全性"仅针对**用户输入**场景
+
+**经验教训**：
+- 不要仅凭名称（"短哈希"）判断库的实现
+- 深入研究文档和源码再做技术决策
+- 区分"用户输入场景"和"系统数据场景"的安全要求
+
+### 缓存库选择：@isaacs/ttlcache
+
+**决策时间**: 2026-01-26
+
+**背景**：
+硬件指纹功能最初使用手动实现的 TTL 缓存（module-level 变量 + 手动过期检查）。为提高代码可维护性，迁移到专业缓存库。
+
+**选型**：
+- **选择**: `@isaacs/ttlcache` v2.1.4
+- **理由**:
+  - 专为 TTL 场景优化，无需 LRU 追踪开销
+  - 零依赖，6M+ 周下载量
+  - 内置 TypeScript 类型
+  - 自动过期管理，无需手动定时器
+  - API 简洁: `new TTLCache({ ttl, max })`
+
+**实现细节**：
+- 保留 `inFlight` Promise 模式用于并发请求去重（TTLCache 不提供此功能）
+- 使用单一缓存键 `'fingerprint'`（单服务器场景，opts 不影响输出）
+- 默认 TTL: 10 分钟（可通过 `cacheTtlMs` 参数覆盖）
+
+**对比手动实现**：
+- ✅ 更少自定义代码
+- ✅ 更清晰的 TTL 语义
+- ✅ 经过充分测试的库
+- ⚠️ 仍需手动处理并发去重
+
+**经验教训**：
+- 专业库不一定解决所有问题（如并发去重）
+- 对于简单场景，手动实现 vs 库的选择主要取决于可维护性而非功能
+
+### SQLite 数据库使用说明
+
+**技术栈**:
+- **驱动**: `better-sqlite3` v11.8.1 (原生模块，跨平台)
+- **类型定义**: `@types/better-sqlite3` v7.6.12
+- **数据库文件**: `./data/app.db`
+
+**数据类型策略**:
+- **主键**: TEXT 存储 UUIDv7 (36 字符字符串，全局唯一)
+- **时间戳**: INTEGER 存储 Unix 毫秒时间戳 (`integer({ mode: 'timestamp_ms' })`)
+  - Drizzle 自动转换 `Date` ↔ `number`
+- **布尔值**: INTEGER 存储 0/1 (`integer({ mode: 'boolean' })`)
+  - Drizzle 自动转换 `boolean` ↔ `0/1`
+
+**数据库连接**:
+```typescript
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import Database from 'better-sqlite3'
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+export const createDB = () => {
+  const dbPath = env.DATABASE_URL
+  if (dbPath !== ':memory:') {
+    mkdirSync(dirname(dbPath), { recursive: true })
+  }
+  const sqlite = new Database(dbPath)
+  return drizzle(sqlite, { schema })
+}
+```
+
+**注意事项**:
+- SQLite 是文件数据库，适合嵌入环境和单实例应用
+- 不支持多进程并发写入
+- 数据库文件和 WAL 文件 (`.db-shm`, `.db-wal`) 已添加到 `.gitignore`
+- `better-sqlite3` 是原生模块，构建时需匹配生产环境 OS 和架构
+
+### AGENTS.md 文档维护原则
+
+**核心原则**：AGENTS.md 只记录当前项目状态，不记录重构历史
+
+1. **当前状态优先**：只描述项目当前使用的技术栈、架构和最佳实践
+2. **无需向后兼容**：不保留旧技术栈的文档，重构后直接更新为新状态
+3. **避免历史记录**：不记录"从 X 迁移到 Y"的过程，只记录"当前使用 Y"
+4. **保持简洁**：删除过时信息，避免上下文过长影响 AI 理解
+5. **及时同步**：架构变更后立即更新文档，确保文档与代码一致
+
+**何时更新 AGENTS.md**：
+- 更换技术栈（如数据库、框架）
+- 修改项目架构或目录结构
+- 添加/移除重要依赖
+- 发现重要的最佳实践或经验教训
+
+**何时不更新 AGENTS.md**：
+- 日常功能开发
+- Bug 修复
+- 代码重构（不涉及架构变更）
+- 临时实验或 POC
+
+---
+
+**最后更新**: 2026-01-26
+**项目版本**: 基于 package.json 依赖版本

apps/server/biome.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/@biomejs/biome/configuration_schema.json",
+  "extends": "//",
+  "files": {
+    "includes": ["**", "!**/routeTree.gen.ts"]
+  }
+}

apps/server/build.ts

@@ -6,14 +6,6 @@ import { Console, Context, Data, Effect, Layer } from 'effect'
 // Domain Models & Schema
 // ============================================================================
 
-const targetMap = {
-  'bun-windows-x64': 'x86_64-pc-windows-msvc',
-  'bun-darwin-arm64': 'aarch64-apple-darwin',
-  'bun-darwin-x64': 'x86_64-apple-darwin',
-  'bun-linux-x64': 'x86_64-unknown-linux-gnu',
-  'bun-linux-arm64': 'aarch64-unknown-linux-gnu',
-} as const
-
 const BunTargetSchema = Schema.Literal(
   'bun-windows-x64',
   'bun-darwin-arm64',
@@ -22,11 +14,19 @@ const BunTargetSchema = Schema.Literal(
   'bun-linux-arm64',
 )
 
+/**
+ * 将 bun target 转换为文件后缀 (去掉 'bun-' 前缀)
+ */
+const getTargetSuffix = (target: BunTarget): string => {
+  return target.replace('bun-', '')
+}
+
 type BunTarget = Schema.Schema.Type<typeof BunTargetSchema>
 
 const BuildConfigSchema = Schema.Struct({
   entrypoint: Schema.String.pipe(Schema.nonEmptyString()),
   outputDir: Schema.String.pipe(Schema.nonEmptyString()),
+  outfile: Schema.String.pipe(Schema.nonEmptyString()),
   targets: Schema.Array(BunTargetSchema).pipe(Schema.minItems(1)),
 })
 
@@ -93,11 +93,11 @@ class BuildConfigService extends Context.Tag('BuildConfigService')<
   static readonly Live = Layer.effect(
     BuildConfigService,
     BuildConfigService.fromRaw({
-      entrypoint: './.output/server/index.mjs',
-      // outputDir: './out',
-      outputDir: './src-tauri/binaries',
+      entrypoint: '.output/server/index.mjs',
+      outputDir: 'out',
+      outfile: 'server',
       targets: ['bun-windows-x64', 'bun-darwin-arm64', 'bun-linux-x64'],
-    }),
+    } satisfies BuildConfig),
   )
 }
 
@@ -150,7 +150,7 @@ class BuildService extends Context.Tag('BuildService')<
             Bun.build({
               entrypoints: [config.entrypoint],
               compile: {
-                outfile: `server-${targetMap[target]}`,
+                outfile: `${config.outfile}-${getTargetSuffix(target)}`,
                 target: target,
               },
               outdir: config.outputDir,
@@ -181,7 +181,7 @@ class BuildService extends Context.Tag('BuildService')<
                 Bun.build({
                   entrypoints: [config.entrypoint],
                   compile: {
-                    outfile: `server-${targetMap[target]}`,
+                    outfile: `${config.outfile}-${getTargetSuffix(target)}`,
                     target: target,
                   },
                   outdir: config.outputDir,

apps/server/drizzle.config.ts

@@ -3,8 +3,8 @@ import { env } from '@/env'
 
 export default defineConfig({
   out: './drizzle',
-  schema: './src/db/schema/index.ts',
-  dialect: 'postgresql',
+  schema: './src/server/db/schema/index.ts',
+  dialect: 'sqlite',
   dbCredentials: {
     url: env.DATABASE_URL,
   },

apps/server/drizzle/0000_messy_goliath.sql

@@ -0,0 +1,18 @@
+CREATE TABLE `device_info` (
+	`id` text PRIMARY KEY NOT NULL,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL,
+	`fingerprint` text NOT NULL,
+	`fingerprint_quality` text NOT NULL,
+	`license` text,
+	`license_activated_at` integer
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `device_info_fingerprint_unique` ON `device_info` (`fingerprint`);--> statement-breakpoint
+CREATE TABLE `todo` (
+	`id` text PRIMARY KEY NOT NULL,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL,
+	`title` text NOT NULL,
+	`completed` integer DEFAULT false NOT NULL
+);

apps/server/drizzle/0001_watery_mongu.sql

@@ -0,0 +1,10 @@
+CREATE TABLE `license_activation` (
+	`id` text PRIMARY KEY NOT NULL,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL,
+	`fingerprint` text NOT NULL,
+	`license` text,
+	`license_activated_at` integer
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `license_activation_fingerprint_unique` ON `license_activation` (`fingerprint`);

apps/server/drizzle/0002_dizzy_kingpin.sql

@@ -0,0 +1,2 @@
+DROP TABLE `device_info`;--> statement-breakpoint
+DROP TABLE `todo`;

apps/server/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,129 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "09c29147-479a-4490-8223-db64c71c910f",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "tables": {
+    "device_info": {
+      "name": "device_info",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "fingerprint": {
+          "name": "fingerprint",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "fingerprint_quality": {
+          "name": "fingerprint_quality",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "license": {
+          "name": "license",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "license_activated_at": {
+          "name": "license_activated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "device_info_fingerprint_unique": {
+          "name": "device_info_fingerprint_unique",
+          "columns": ["fingerprint"],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "todo": {
+      "name": "todo",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "completed": {
+          "name": "completed",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

apps/server/drizzle/meta/0001_snapshot.json

@@ -0,0 +1,187 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "14bad572-1fc5-489d-90f2-7560a7cad1f4",
+  "prevId": "09c29147-479a-4490-8223-db64c71c910f",
+  "tables": {
+    "device_info": {
+      "name": "device_info",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "fingerprint": {
+          "name": "fingerprint",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "fingerprint_quality": {
+          "name": "fingerprint_quality",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "license": {
+          "name": "license",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "license_activated_at": {
+          "name": "license_activated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "device_info_fingerprint_unique": {
+          "name": "device_info_fingerprint_unique",
+          "columns": ["fingerprint"],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "license_activation": {
+      "name": "license_activation",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "fingerprint": {
+          "name": "fingerprint",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "license": {
+          "name": "license",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "license_activated_at": {
+          "name": "license_activated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "license_activation_fingerprint_unique": {
+          "name": "license_activation_fingerprint_unique",
+          "columns": ["fingerprint"],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "todo": {
+      "name": "todo",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "completed": {
+          "name": "completed",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

apps/server/drizzle/meta/0002_snapshot.json

@@ -0,0 +1,76 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "2bdd10cc-8e14-4843-931a-37b1d00f21a6",
+  "prevId": "14bad572-1fc5-489d-90f2-7560a7cad1f4",
+  "tables": {
+    "license_activation": {
+      "name": "license_activation",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "fingerprint": {
+          "name": "fingerprint",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "license": {
+          "name": "license",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "license_activated_at": {
+          "name": "license_activated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "license_activation_fingerprint_unique": {
+          "name": "license_activation_fingerprint_unique",
+          "columns": ["fingerprint"],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

apps/server/drizzle/meta/_journal.json

@@ -0,0 +1,27 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1769409553227,
+      "tag": "0000_messy_goliath",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1769409970060,
+      "tag": "0001_watery_mongu",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1769412006512,
+      "tag": "0002_dizzy_kingpin",
+      "breakpoints": true
+    }
+  ]
+}

apps/server/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@furtherverse/server",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "compile": "bun build.ts",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio",
+    "dev": "vite dev",
+    "fix": "biome check --write .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@isaacs/ttlcache": "catalog:",
+    "@orpc/client": "catalog:",
+    "@orpc/contract": "catalog:",
+    "@orpc/openapi": "catalog:",
+    "@orpc/server": "catalog:",
+    "@orpc/tanstack-query": "catalog:",
+    "@orpc/zod": "catalog:",
+    "@t3-oss/env-core": "catalog:",
+    "@tanstack/react-query": "catalog:",
+    "@tanstack/react-router": "catalog:",
+    "@tanstack/react-router-ssr-query": "catalog:",
+    "@tanstack/react-start": "catalog:",
+    "drizzle-orm": "catalog:",
+    "drizzle-zod": "catalog:",
+    "ohash": "catalog:",
+    "better-sqlite3": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "systeminformation": "catalog:",
+    "uuid": "catalog:",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@effect/platform": "catalog:",
+    "@effect/schema": "catalog:",
+    "@furtherverse/tsconfig": "workspace:*",
+    "@tailwindcss/vite": "catalog:",
+    "@tanstack/devtools-vite": "catalog:",
+    "@tanstack/react-devtools": "catalog:",
+    "@tanstack/react-query-devtools": "catalog:",
+    "@tanstack/react-router-devtools": "catalog:",
+    "@types/better-sqlite3": "catalog:",
+    "@types/bun": "catalog:",
+    "@vitejs/plugin-react": "catalog:",
+    "babel-plugin-react-compiler": "catalog:",
+    "drizzle-kit": "catalog:",
+    "effect": "catalog:",
+    "nitro": "catalog:",
+    "tailwindcss": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vite-tsconfig-paths": "catalog:"
+  }
+}

apps/server/src/client/orpc.client.ts

@@ -0,0 +1,24 @@
+import { createORPCClient } from '@orpc/client'
+import { RPCLink } from '@orpc/client/fetch'
+import { createRouterClient } from '@orpc/server'
+import { createIsomorphicFn } from '@tanstack/react-start'
+import { getRequestHeaders } from '@tanstack/react-start/server'
+import { router } from '@/server/api/routers'
+import type { RouterClient } from '@/server/api/types'
+
+const getORPCClient = createIsomorphicFn()
+  .server(() =>
+    createRouterClient(router, {
+      context: () => ({
+        headers: getRequestHeaders(),
+      }),
+    }),
+  )
+  .client(() => {
+    const link = new RPCLink({
+      url: `${window.location.origin}/api/rpc`,
+    })
+    return createORPCClient<RouterClient>(link)
+  })
+
+export const orpc: RouterClient = getORPCClient()

apps/server/src/client/query-client.ts

@@ -0,0 +1,6 @@
+import { createTanstackQueryUtils } from '@orpc/tanstack-query'
+import { orpc as orpcClient } from './orpc.client'
+
+export const orpc = createTanstackQueryUtils(orpcClient, {
+  experimental_defaults: {},
+})

apps/server/src/env.ts

@@ -3,7 +3,7 @@ import { z } from 'zod'
 
 export const env = createEnv({
   server: {
-    DATABASE_URL: z.url(),
+    DATABASE_URL: z.string().min(1),
   },
   clientPrefix: 'VITE_',
   client: {

apps/server/src/lib/crypto.ts

@@ -0,0 +1,109 @@
+import {
+  constants,
+  createPrivateKey,
+  createPublicKey,
+  privateDecrypt,
+  publicEncrypt,
+} from 'node:crypto'
+
+// 对应 Java: RSA/ECB/OAEPWithSHA-256AndMGF1Padding
+const OAEP_HASH = 'sha256'
+
+/**
+ * 使用 Base64 编码的公钥加密明文
+ *
+ * 加密标准: RSA/ECB/OAEPWithSHA-256AndMGF1Padding (兼容 Java)
+ * 公钥格式: SPKI/DER (对应 Java X509EncodedKeySpec)
+ *
+ * @param plainText - 待加密的明文字符串
+ * @param publicKeyBase64 - Base64 编码的公钥 (DER/SPKI 格式)
+ * @returns Base64 编码的加密数据
+ * @throws {Error} 加密失败时抛出错误
+ *
+ * @example
+ * ```typescript
+ * const publicKey = 'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...'
+ * const encrypted = encrypt('sensitive data', publicKey)
+ * console.log(encrypted) // "a3f5e8c2d1b4..."
+ * ```
+ */
+export function encrypt(plainText: string, publicKeyBase64: string): string {
+  const buffer = Buffer.from(plainText, 'utf-8')
+  const keyBuffer = Buffer.from(publicKeyBase64, 'base64')
+
+  try {
+    // 1. 先创建 KeyObject，在这里指定密钥的格式 (DER/SPKI)
+    const publicKey = createPublicKey({
+      key: keyBuffer,
+      format: 'der',
+      type: 'spki', // 对应 Java X509EncodedKeySpec
+    })
+
+    // 2. 使用 KeyObject 进行加密，在这里指定 Padding 模式
+    const encrypted = publicEncrypt(
+      {
+        key: publicKey,
+        padding: constants.RSA_PKCS1_OAEP_PADDING,
+        oaepHash: OAEP_HASH,
+      },
+      buffer,
+    )
+
+    return encrypted.toString('base64')
+  } catch (error) {
+    throw new Error(
+      `Encryption failed: ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+}
+
+/**
+ * 使用 Base64 编码的私钥解密数据
+ *
+ * 解密标准: RSA/ECB/OAEPWithSHA-256AndMGF1Padding (兼容 Java)
+ * 私钥格式: PKCS8/DER (对应 Java PKCS8EncodedKeySpec)
+ *
+ * @param encryptedData - Base64 编码的加密数据
+ * @param privateKeyBase64 - Base64 编码的私钥 (DER/PKCS8 格式)
+ * @returns 解密后的明文字符串
+ * @throws {Error} 解密失败时抛出错误
+ *
+ * @example
+ * ```typescript
+ * const privateKey = 'MIIEvQIBADANBgkqhkiG9w0BAQEFAASC...'
+ * const decrypted = decrypt('a3f5e8c2d1b4...', privateKey)
+ * console.log(decrypted) // "sensitive data"
+ * ```
+ */
+export function decrypt(
+  encryptedData: string,
+  privateKeyBase64: string,
+): string {
+  const buffer = Buffer.from(encryptedData, 'base64')
+  const keyBuffer = Buffer.from(privateKeyBase64, 'base64')
+
+  try {
+    // 1. 先创建 KeyObject，在这里指定密钥的格式 (DER/PKCS8)
+    const privateKey = createPrivateKey({
+      key: keyBuffer,
+      format: 'der',
+      type: 'pkcs8', // 对应 Java PKCS8EncodedKeySpec
+    })
+
+    // 2. 使用 KeyObject 进行解密
+    const decrypted = privateDecrypt(
+      {
+        key: privateKey,
+        padding: constants.RSA_PKCS1_OAEP_PADDING,
+        oaepHash: OAEP_HASH,
+      },
+      buffer,
+    )
+
+    return decrypted.toString('utf-8')
+  } catch (error) {
+    throw new Error(
+      `Decryption failed: ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+}

apps/server/src/lib/fingerprint.ts

@@ -0,0 +1,233 @@
+import { TTLCache } from '@isaacs/ttlcache'
+import { hash } from 'ohash'
+import si from 'systeminformation'
+
+/**
+ * 硬件指纹质量等级
+ * - strong: 2+ 个强标识符可用(推荐用于生产授权)
+ * - medium: 1 个强标识符可用(可用但不理想)
+ * - weak: 无强标识符(仅适合开发/测试)
+ */
+export type FingerprintQuality = 'strong' | 'medium' | 'weak'
+
+/**
+ * 标准化的系统信息(用于机器码生成)
+ */
+export type NormalizedSystemInfo = {
+  /** 系统 UUID(最稳定的硬件标识符) */
+  systemUuid: string | null
+  /** 系统序列号 */
+  systemSerial: string | null
+  /** 主板序列号 */
+  baseboardSerial: string | null
+  /** 主板制造商 */
+  baseboardManufacturer: string | null
+  /** BIOS 版本 */
+  biosVersion: string | null
+  /** BIOS 供应商 */
+  biosVendor: string | null
+  /** CPU 品牌标识(用于质量评估) */
+  cpuBrand: string | null
+  /** 主硬盘序列号(可选,高稳定性) */
+  primaryDiskSerial?: string | null
+}
+
+/**
+ * 硬件指纹配置选项
+ */
+export type HardwareFingerprintOptions = {
+  /**
+   * 缓存 TTL(毫秒),默认 10 分钟
+   * 硬件信息变化频率极低,缓存可大幅提升性能
+   */
+  cacheTtlMs?: number
+
+  /**
+   * 是否包含主硬盘序列号(默认 true)
+   * 注意:在容器/虚拟机环境可能获取失败
+   */
+  includePrimaryDisk?: boolean
+}
+
+/**
+ * 硬件指纹响应
+ */
+export type HardwareFingerprintResult = {
+  /** 机器码(HMAC-SHA256 哈希,64 字符十六进制) */
+  fingerprint: string
+  /** 指纹质量等级 */
+  quality: FingerprintQuality
+  /** 可用的强标识符数量 */
+  strongIdentifiersCount: number
+  /** 生成时间戳 */
+  timestamp: number
+}
+
+// 缓存实例
+const cache = new TTLCache<'fingerprint', HardwareFingerprintResult>({
+  ttl: 10 * 60 * 1000, // 10 minutes default
+  max: 1, // Only one fingerprint cached
+})
+
+// 防止并发重复请求
+let inFlight: Promise<HardwareFingerprintResult> | null = null
+
+/**
+ * 计算指纹质量
+ */
+function computeQuality(info: NormalizedSystemInfo): {
+  quality: FingerprintQuality
+  count: number
+} {
+  const strongKeys = [
+    info.systemUuid,
+    info.systemSerial,
+    info.baseboardSerial,
+    info.primaryDiskSerial,
+  ].filter(Boolean).length
+
+  if (strongKeys >= 2) return { quality: 'strong', count: strongKeys }
+  if (strongKeys === 1) return { quality: 'medium', count: strongKeys }
+  return { quality: 'weak', count: 0 }
+}
+
+/**
+ * 安全地收集标准化系统信息(容错处理)
+ */
+async function collectNormalizedInfo(
+  opts: HardwareFingerprintOptions,
+): Promise<NormalizedSystemInfo> {
+  // 使用 Promise.allSettled 避免单点失败
+  const tasks = await Promise.allSettled([
+    si.uuid(),
+    si.system(),
+    si.baseboard(),
+    si.bios(),
+    si.cpu(),
+    opts.includePrimaryDisk !== false ? si.diskLayout() : Promise.resolve([]),
+  ])
+
+  const [uuidRes, systemRes, baseboardRes, biosRes, cpuRes, diskRes] = tasks
+
+  const uuid = uuidRes.status === 'fulfilled' ? uuidRes.value : null
+  const system = systemRes.status === 'fulfilled' ? systemRes.value : null
+  const baseboard =
+    baseboardRes.status === 'fulfilled' ? baseboardRes.value : null
+  const bios = biosRes.status === 'fulfilled' ? biosRes.value : null
+  const cpu = cpuRes.status === 'fulfilled' ? cpuRes.value : null
+
+  // 提取主硬盘序列号(通常是第一个物理磁盘)
+  let primaryDiskSerial: string | null = null
+  if (diskRes.status === 'fulfilled' && Array.isArray(diskRes.value)) {
+    const disks = diskRes.value as Array<{ serialNum?: string; type?: string }>
+    const physicalDisk = disks.find(
+      (d) => d.type !== 'USB' && d.serialNum && d.serialNum.trim(),
+    )
+    primaryDiskSerial = physicalDisk?.serialNum?.trim() || null
+  }
+
+  return {
+    // 系统级标识符(最稳定)
+    systemUuid: (system?.uuid ?? uuid?.hardware ?? null) || null,
+    systemSerial: (system?.serial ?? null) || null,
+
+    // 主板标识符(次稳定)
+    baseboardSerial: (baseboard?.serial ?? null) || null,
+    baseboardManufacturer: (baseboard?.manufacturer ?? null) || null,
+
+    // BIOS 信息(辅助识别)
+    biosVersion: (bios?.version ?? null) || null,
+    biosVendor: (bios?.vendor ?? null) || null,
+
+    // CPU 信息(辅助识别)
+    cpuBrand: (cpu?.brand ?? null) || null,
+
+    // 磁盘序列号(可选,高稳定性)
+    ...(opts.includePrimaryDisk !== false ? { primaryDiskSerial } : {}),
+  }
+}
+
+/**
+/**
+ * 获取硬件指纹(机器码)
+ *
+ * 适用场景:客户端部署的软件授权、机器绑定
+ *
+ * 安全说明:
+ * - 返回 SHA-256 哈希(Base64URL 编码,43 字符),不可逆推原始硬件信息
+ * - 使用 ohash 自动处理对象序列化和哈希
+ * - 客户端部署场景:客户可以看到代码,无法使用密钥加密
+ * - 安全性依赖硬件信息本身的不可伪造性(来自操作系统)
+ * - 自动缓存减少系统调用开销
+ *
+ * 稳定性:
+ * - 优先使用系统 UUID、序列号等不易变更的标识符
+ * - 避免网络接口等易变信息
+ * - 容错处理,部分信息缺失不影响生成
+ *
+ * @example
+ * ```typescript
+ * const result = await getHardwareFingerprint({
+ *   cacheTtlMs: 600000, // 10 分钟
+ *   includePrimaryDisk: true,
+ * })
+ *
+ * console.log(result.fingerprint) // "a3f5e8c2d1b4..."
+ * console.log(result.quality)     // "strong"
+ * ```
+ */
+export async function getHardwareFingerprint(
+  opts: HardwareFingerprintOptions,
+): Promise<HardwareFingerprintResult> {
+  const ttl = opts.cacheTtlMs ?? 10 * 60 * 1000
+  const now = Date.now()
+
+  // 返回缓存结果
+  const cached = cache.get('fingerprint')
+  if (cached) {
+    return cached
+  }
+
+  // 防止并发重复请求
+  if (inFlight) {
+    return inFlight
+  }
+
+  inFlight = (async () => {
+    // 收集标准化信息
+    const info = await collectNormalizedInfo(opts)
+
+    // 计算质量
+    const { quality, count } = computeQuality(info)
+
+    // 使用 ohash 生成指纹(自动序列化 + SHA-256 + Base64URL)
+    const fingerprint = hash({
+      v: 1, // 版本号,未来如需变更采集策略可递增
+      info,
+    })
+
+    const result: HardwareFingerprintResult = {
+      fingerprint,
+      quality,
+      strongIdentifiersCount: count,
+      timestamp: now,
+    }
+
+    // 更新缓存
+    cache.set('fingerprint', result, { ttl })
+
+    return result
+  })().finally(() => {
+    inFlight = null
+  })
+
+  return inFlight
+}
+
+/**
+ * 清除指纹缓存(用于测试或强制刷新)
+ */
+export function clearFingerprintCache(): void {
+  cache.clear()
+  inFlight = null
+}

apps/server/src/lib/license-init.ts

@@ -0,0 +1,40 @@
+import { getDB } from '@/server/db'
+import { licenseActivationTable } from '@/server/db/schema'
+import { getHardwareFingerprint } from './fingerprint'
+
+let initPromise: Promise<void> | null = null
+
+export async function ensureLicenseActivationInitialized(): Promise<void> {
+  if (initPromise) return initPromise
+
+  initPromise = (async () => {
+    try {
+      const db = getDB()
+      const result = await getHardwareFingerprint({
+        cacheTtlMs: 10 * 60 * 1000,
+        includePrimaryDisk: true,
+      })
+
+      await db
+        .insert(licenseActivationTable)
+        .values({
+          fingerprint: result.fingerprint,
+          license: null,
+          licenseActivatedAt: null,
+        })
+        .onConflictDoUpdate({
+          target: licenseActivationTable.fingerprint,
+          set: {
+            updatedAt: new Date(),
+          },
+        })
+    } catch (error) {
+      console.error('Failed to initialize license activation:', error)
+      // 重置 promise 以便下次重试
+      initPromise = null
+      throw error
+    }
+  })()
+
+  return initPromise
+}

apps/server/src/routeTree.gen.ts

@@ -9,13 +9,20 @@
 // 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 TodosRouteImport } from './routes/todos'
+import { Route as LicenseRouteImport } from './routes/license'
+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 TodosRoute = TodosRouteImport.update({
-  id: '/todos',
-  path: '/todos',
+const LicenseRoute = LicenseRouteImport.update({
+  id: '/license',
+  path: '/license',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const FingerprintRoute = FingerprintRouteImport.update({
+  id: '/fingerprint',
+  path: '/fingerprint',
   getParentRoute: () => rootRouteImport,
 } as any)
 const IndexRoute = IndexRouteImport.update({
@@ -23,6 +30,11 @@ const IndexRoute = IndexRouteImport.update({
   path: '/',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiSplatRoute = ApiSplatRouteImport.update({
+  id: '/api/$',
+  path: '/api/$',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiRpcSplatRoute = ApiRpcSplatRouteImport.update({
   id: '/api/rpc/$',
   path: '/api/rpc/$',
@@ -31,41 +43,56 @@ const ApiRpcSplatRoute = ApiRpcSplatRouteImport.update({
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
-  '/todos': typeof TodosRoute
+  '/fingerprint': typeof FingerprintRoute
+  '/license': typeof LicenseRoute
+  '/api/$': typeof ApiSplatRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
-  '/todos': typeof TodosRoute
+  '/fingerprint': typeof FingerprintRoute
+  '/license': typeof LicenseRoute
+  '/api/$': typeof ApiSplatRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
-  '/todos': typeof TodosRoute
+  '/fingerprint': typeof FingerprintRoute
+  '/license': typeof LicenseRoute
+  '/api/$': typeof ApiSplatRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
-  fullPaths: '/' | '/todos' | '/api/rpc/$'
+  fullPaths: '/' | '/fingerprint' | '/license' | '/api/$' | '/api/rpc/$'
   fileRoutesByTo: FileRoutesByTo
-  to: '/' | '/todos' | '/api/rpc/$'
-  id: '__root__' | '/' | '/todos' | '/api/rpc/$'
+  to: '/' | '/fingerprint' | '/license' | '/api/$' | '/api/rpc/$'
+  id: '__root__' | '/' | '/fingerprint' | '/license' | '/api/$' | '/api/rpc/$'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
-  TodosRoute: typeof TodosRoute
+  FingerprintRoute: typeof FingerprintRoute
+  LicenseRoute: typeof LicenseRoute
+  ApiSplatRoute: typeof ApiSplatRoute
   ApiRpcSplatRoute: typeof ApiRpcSplatRoute
 }
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
-    '/todos': {
-      id: '/todos'
-      path: '/todos'
-      fullPath: '/todos'
-      preLoaderRoute: typeof TodosRouteImport
+    '/license': {
+      id: '/license'
+      path: '/license'
+      fullPath: '/license'
+      preLoaderRoute: typeof LicenseRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/fingerprint': {
+      id: '/fingerprint'
+      path: '/fingerprint'
+      fullPath: '/fingerprint'
+      preLoaderRoute: typeof FingerprintRouteImport
       parentRoute: typeof rootRouteImport
     }
     '/': {
@@ -75,6 +102,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof IndexRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/$': {
+      id: '/api/$'
+      path: '/api/$'
+      fullPath: '/api/$'
+      preLoaderRoute: typeof ApiSplatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/rpc/$': {
       id: '/api/rpc/$'
       path: '/api/rpc/$'
@@ -87,7 +121,9 @@ declare module '@tanstack/react-router' {
 
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
-  TodosRoute: TodosRoute,
+  FingerprintRoute: FingerprintRoute,
+  LicenseRoute: LicenseRoute,
+  ApiSplatRoute: ApiSplatRoute,
   ApiRpcSplatRoute: ApiRpcSplatRoute,
 }
 export const routeTree = rootRouteImport

apps/server/src/routes/__root.tsx

@@ -1,15 +1,15 @@
 import { TanStackDevtools } from '@tanstack/react-devtools'
 import type { QueryClient } from '@tanstack/react-query'
+import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
 import {
   createRootRouteWithContext,
   HeadContent,
   Scripts,
 } from '@tanstack/react-router'
+import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'
 import type { ReactNode } from 'react'
 import { ErrorComponent } from '@/components/Error'
 import { NotFoundComponent } from '@/components/NotFount'
-import { devtools as queryDevtools } from '@/integrations/tanstack-query'
-import { devtools as routerDevtools } from '@/integrations/tanstack-router'
 import appCss from '@/styles.css?url'
 
 export interface RouterContext {
@@ -27,7 +27,7 @@ export const Route = createRootRouteWithContext<RouterContext>()({
         content: 'width=device-width, initial-scale=1',
       },
       {
-        title: 'Fullstack Starter',
+        title: 'Furtherverse',
       },
     ],
     links: [
@@ -54,7 +54,16 @@ function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
           config={{
             position: 'bottom-right',
           }}
-          plugins={[routerDevtools, queryDevtools]}
+          plugins={[
+            {
+              name: 'TanStack Router',
+              render: <TanStackRouterDevtoolsPanel />,
+            },
+            {
+              name: 'TanStack Query',
+              render: <ReactQueryDevtoolsPanel />,
+            },
+          ]}
         />
         <Scripts />
       </body>

apps/server/src/routes/api/$.ts

@@ -0,0 +1,86 @@
+import { OpenAPIHandler } from '@orpc/openapi/fetch'
+import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
+import { ORPCError, onError, ValidationError } from '@orpc/server'
+import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
+import { createFileRoute } from '@tanstack/react-router'
+import { z } from 'zod'
+import { name, version } from '@/../package.json'
+import { router } from '@/server/api/routers'
+
+const handler = new OpenAPIHandler(router, {
+  plugins: [
+    new OpenAPIReferencePlugin({
+      docsProvider: 'scalar',
+      schemaConverters: [new ZodToJsonSchemaConverter()],
+      specGenerateOptions: {
+        info: {
+          title: name,
+          version,
+        },
+        // components: {
+        //   securitySchemes: {
+        //     bearerAuth: {
+        //       type: 'http',
+        //       scheme: 'bearer',
+        //     },
+        //   },
+        // },
+      },
+      docsPath: '/docs',
+      specPath: '/spec.json',
+    }),
+  ],
+  interceptors: [
+    onError((error) => {
+      console.error(error)
+    }),
+  ],
+  clientInterceptors: [
+    onError((error) => {
+      if (
+        error instanceof ORPCError &&
+        error.code === 'BAD_REQUEST' &&
+        error.cause instanceof ValidationError
+      ) {
+        // If you only use Zod you can safely cast to ZodIssue[]
+        const zodError = new z.ZodError(
+          error.cause.issues as z.core.$ZodIssue[],
+        )
+
+        throw new ORPCError('INPUT_VALIDATION_FAILED', {
+          status: 422,
+          message: z.prettifyError(zodError),
+          data: z.flattenError(zodError),
+          cause: error.cause,
+        })
+      }
+
+      if (
+        error instanceof ORPCError &&
+        error.code === 'INTERNAL_SERVER_ERROR' &&
+        error.cause instanceof ValidationError
+      ) {
+        throw new ORPCError('OUTPUT_VALIDATION_FAILED', {
+          cause: error.cause,
+        })
+      }
+    }),
+  ],
+})
+
+export const Route = createFileRoute('/api/$')({
+  server: {
+    handlers: {
+      ANY: async ({ request }) => {
+        const { response } = await handler.handle(request, {
+          prefix: '/api',
+          context: {
+            headers: request.headers,
+          },
+        })
+
+        return response ?? new Response('Not Found', { status: 404 })
+      },
+    },
+  },
+})

apps/server/src/routes/api/rpc.$.ts

@@ -2,7 +2,7 @@ import { ORPCError, onError, ValidationError } from '@orpc/server'
 import { RPCHandler } from '@orpc/server/fetch'
 import { createFileRoute } from '@tanstack/react-router'
 import { z } from 'zod'
-import { router } from '@/orpc/router'
+import { router } from '@/server/api/routers'
 
 const handler = new RPCHandler(router, {
   interceptors: [
@@ -49,7 +49,9 @@ export const Route = createFileRoute('/api/rpc/$')({
       ANY: async ({ request }) => {
         const { response } = await handler.handle(request, {
           prefix: '/api/rpc',
-          context: {},
+          context: {
+            headers: request.headers,
+          },
         })
 
         return response ?? new Response('Not Found', { status: 404 })

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/routes/index.tsx

@@ -0,0 +1,46 @@
+import { createFileRoute, Link } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/')({
+  component: Home,
+})
+
+function Home() {
+  return (
+    <div className="min-h-screen bg-slate-50 py-12 px-4 sm:px-6 font-sans">
+      <div className="max-w-2xl mx-auto space-y-8 text-center">
+        <h1 className="text-4xl font-bold text-slate-900 tracking-tight">
+          License 管理系统
+        </h1>
+        <p className="text-slate-500 text-lg">
+          欢迎使用基于 TanStack Start + ORPC 的 License 管理系统
+        </p>
+
+        <div className="grid grid-cols-1 sm:grid-cols-2 gap-4 mt-8">
+          <Link
+            to="/fingerprint"
+            className="p-6 bg-white rounded-2xl shadow-sm border border-slate-100 hover:shadow-md hover:border-indigo-500/50 transition-all text-left group"
+          >
+            <h2 className="text-xl font-semibold text-slate-900 group-hover:text-indigo-600 transition-colors">
+              设备指纹
+            </h2>
+            <p className="text-slate-500 mt-2 text-sm">
+              查询当前设备的硬件指纹信息，用于 License 绑定
+            </p>
+          </Link>
+
+          <Link
+            to="/license"
+            className="p-6 bg-white rounded-2xl shadow-sm border border-slate-100 hover:shadow-md hover:border-indigo-500/50 transition-all text-left group"
+          >
+            <h2 className="text-xl font-semibold text-slate-900 group-hover:text-indigo-600 transition-colors">
+              License 激活
+            </h2>
+            <p className="text-slate-500 mt-2 text-sm">
+              管理和激活当前设备的 License 授权状态
+            </p>
+          </Link>
+        </div>
+      </div>
+    </div>
+  )
+}

apps/server/src/routes/license.tsx

@@ -0,0 +1,463 @@
+import {
+  useMutation,
+  useQueryClient,
+  useSuspenseQuery,
+} from '@tanstack/react-query'
+import { createFileRoute } from '@tanstack/react-router'
+import { useState } from 'react'
+import { orpc } from '@/client/query-client'
+
+export const Route = createFileRoute('/license')({
+  component: License,
+})
+
+function License() {
+  const [licenseInput, setLicenseInput] = useState('')
+  const [copySuccess, setCopySuccess] = useState(false)
+  const [showDeactivateConfirm, setShowDeactivateConfirm] = useState(false)
+  const queryClient = useQueryClient()
+
+  // 获取激活状态
+  const { data } = useSuspenseQuery(orpc.license.getActivation.queryOptions())
+
+  // 激活 mutation
+  const activateMutation = useMutation({
+    ...orpc.license.activate.mutationOptions(),
+    onSuccess: () => {
+      // 刷新数据
+      queryClient.invalidateQueries({
+        queryKey: orpc.license.getActivation.key(),
+      })
+      // 清空输入
+      setLicenseInput('')
+    },
+  })
+
+  // 反激活 mutation
+  const deactivateMutation = useMutation({
+    ...orpc.license.deactivate.mutationOptions(),
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: orpc.license.getActivation.key(),
+      })
+      setShowDeactivateConfirm(false)
+    },
+  })
+
+  const handleActivate = () => {
+    if (!licenseInput.trim()) return
+    activateMutation.mutate({ license: licenseInput.trim() })
+  }
+
+  const handleDeactivate = () => {
+    deactivateMutation.mutate()
+  }
+
+  const handleCopyFingerprint = async () => {
+    try {
+      await navigator.clipboard.writeText(data.fingerprint)
+      setCopySuccess(true)
+      setTimeout(() => setCopySuccess(false), 2000)
+    } catch (err) {
+      console.error('Failed to copy fingerprint:', err)
+    }
+  }
+
+  const isActivated = !!data.license
+
+  return (
+    <div className="min-h-screen bg-gray-50 flex items-center justify-center p-4 font-sans">
+      <div className="w-full max-w-2xl space-y-6">
+        {/* 页面标题 */}
+        <div className="text-center mb-8">
+          <h1 className="text-3xl font-bold text-gray-900 tracking-tight">
+            License 激活管理
+          </h1>
+          <p className="text-gray-500 mt-2">管理您的设备授权与激活状态</p>
+        </div>
+
+        {/* 设备信息卡片 */}
+        <div className="bg-white rounded-xl shadow-sm border border-gray-100 overflow-hidden">
+          <div className="p-6">
+            <h2 className="text-lg font-semibold text-gray-900 mb-4 flex items-center gap-2">
+              <svg
+                aria-hidden="true"
+                xmlns="http://www.w3.org/2000/svg"
+                width="20"
+                height="20"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                className="text-blue-500"
+              >
+                <rect x="4" y="4" width="16" height="16" rx="2" ry="2"></rect>
+                <rect x="9" y="9" width="6" height="6"></rect>
+                <line x1="9" y1="1" x2="9" y2="4"></line>
+                <line x1="15" y1="1" x2="15" y2="4"></line>
+                <line x1="9" y1="20" x2="9" y2="23"></line>
+                <line x1="15" y1="20" x2="15" y2="23"></line>
+                <line x1="20" y1="9" x2="23" y2="9"></line>
+                <line x1="20" y1="14" x2="23" y2="14"></line>
+                <line x1="1" y1="9" x2="4" y2="9"></line>
+                <line x1="1" y1="14" x2="4" y2="14"></line>
+              </svg>
+              设备信息
+            </h2>
+            <div className="bg-gray-50 rounded-lg p-4 border border-gray-100">
+              <p className="text-sm text-gray-500 mb-1">
+                设备指纹 (Device Fingerprint)
+              </p>
+              <div className="flex items-center gap-3">
+                <code className="flex-1 font-mono text-sm text-gray-700 break-all select-all">
+                  {data.fingerprint}
+                </code>
+                <button
+                  type="button"
+                  onClick={handleCopyFingerprint}
+                  className={`px-3 py-1.5 rounded-md text-sm font-medium transition-colors flex items-center gap-1.5 ${
+                    copySuccess
+                      ? 'bg-green-100 text-green-700 hover:bg-green-200'
+                      : 'bg-white border border-gray-200 text-gray-700 hover:bg-gray-50 hover:text-gray-900'
+                  }`}
+                >
+                  {copySuccess ? (
+                    <>
+                      <svg
+                        aria-hidden="true"
+                        xmlns="http://www.w3.org/2000/svg"
+                        width="14"
+                        height="14"
+                        viewBox="0 0 24 24"
+                        fill="none"
+                        stroke="currentColor"
+                        strokeWidth="2"
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                      >
+                        <polyline points="20 6 9 17 4 12"></polyline>
+                      </svg>
+                      已复制
+                    </>
+                  ) : (
+                    <>
+                      <svg
+                        aria-hidden="true"
+                        xmlns="http://www.w3.org/2000/svg"
+                        width="14"
+                        height="14"
+                        viewBox="0 0 24 24"
+                        fill="none"
+                        stroke="currentColor"
+                        strokeWidth="2"
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                      >
+                        <rect
+                          x="9"
+                          y="9"
+                          width="13"
+                          height="13"
+                          rx="2"
+                          ry="2"
+                        ></rect>
+                        <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+                      </svg>
+                      复制
+                    </>
+                  )}
+                </button>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        {/* License 激活卡片 */}
+        <div className="bg-white rounded-xl shadow-sm border border-gray-100 overflow-hidden">
+          <div className="p-6">
+            <h2 className="text-lg font-semibold text-gray-900 mb-4 flex items-center gap-2">
+              <svg
+                aria-hidden="true"
+                xmlns="http://www.w3.org/2000/svg"
+                width="20"
+                height="20"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                className="text-purple-500"
+              >
+                <rect x="3" y="11" width="18" height="11" rx="2" ry="2"></rect>
+                <path d="M7 11V7a5 5 0 0 1 10 0v4"></path>
+              </svg>
+              License 激活
+            </h2>
+
+            <div className="space-y-4">
+              <div>
+                <label
+                  htmlFor="license-key"
+                  className="block text-sm font-medium text-gray-700 mb-1"
+                >
+                  License Key
+                </label>
+                <input
+                  id="license-key"
+                  type="text"
+                  value={licenseInput}
+                  onChange={(e) => setLicenseInput(e.target.value)}
+                  disabled={isActivated || activateMutation.isPending}
+                  placeholder={
+                    isActivated ? '已激活，无需输入' : '请输入您的 License Key'
+                  }
+                  className="w-full px-4 py-2.5 bg-white border border-gray-300 rounded-lg focus:ring-2 focus:ring-purple-500/20 focus:border-purple-500 outline-none transition-all disabled:bg-gray-100 disabled:text-gray-500 placeholder:text-gray-400"
+                />
+              </div>
+
+              {activateMutation.isError && (
+                <div className="p-3 bg-red-50 border border-red-100 rounded-lg text-red-600 text-sm flex items-start gap-2">
+                  <svg
+                    aria-hidden="true"
+                    xmlns="http://www.w3.org/2000/svg"
+                    width="16"
+                    height="16"
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth="2"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    className="mt-0.5 shrink-0"
+                  >
+                    <circle cx="12" cy="12" r="10"></circle>
+                    <line x1="12" y1="8" x2="12" y2="12"></line>
+                    <line x1="12" y1="16" x2="12.01" y2="16"></line>
+                  </svg>
+                  <span>激活失败: 请检查 License 是否正确或稍后重试</span>
+                </div>
+              )}
+
+              <button
+                type="button"
+                onClick={handleActivate}
+                disabled={
+                  isActivated ||
+                  activateMutation.isPending ||
+                  !licenseInput.trim()
+                }
+                className={`w-full px-6 py-2.5 rounded-lg font-medium text-white shadow-sm transition-all focus:outline-none focus:ring-2 focus:ring-offset-2 ${
+                  isActivated
+                    ? 'bg-gray-300 cursor-not-allowed'
+                    : activateMutation.isPending
+                      ? 'bg-purple-500 opacity-80 cursor-wait'
+                      : 'bg-purple-600 hover:bg-purple-700 hover:shadow-md active:scale-[0.99] focus:ring-purple-500'
+                }`}
+              >
+                {activateMutation.isPending ? (
+                  <span className="flex items-center justify-center gap-2">
+                    <svg
+                      aria-hidden="true"
+                      className="animate-spin h-4 w-4 text-white"
+                      xmlns="http://www.w3.org/2000/svg"
+                      fill="none"
+                      viewBox="0 0 24 24"
+                    >
+                      <circle
+                        className="opacity-25"
+                        cx="12"
+                        cy="12"
+                        r="10"
+                        stroke="currentColor"
+                        strokeWidth="4"
+                      ></circle>
+                      <path
+                        className="opacity-75"
+                        fill="currentColor"
+                        d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+                      ></path>
+                    </svg>
+                    正在激活...
+                  </span>
+                ) : isActivated ? (
+                  '已完成激活'
+                ) : (
+                  '立即激活'
+                )}
+              </button>
+            </div>
+          </div>
+        </div>
+
+        {/* 激活状态卡片 */}
+        <div
+          className={`rounded-xl shadow-sm border overflow-hidden transition-colors ${
+            isActivated
+              ? 'bg-green-50/50 border-green-100'
+              : 'bg-white border-gray-100'
+          }`}
+        >
+          <div className="p-6">
+            <h2 className="text-lg font-semibold text-gray-900 mb-4 flex items-center gap-2">
+              <svg
+                aria-hidden="true"
+                xmlns="http://www.w3.org/2000/svg"
+                width="20"
+                height="20"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                className={isActivated ? 'text-green-500' : 'text-gray-400'}
+              >
+                <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"></path>
+                <polyline points="22 4 12 14.01 9 11.01"></polyline>
+              </svg>
+              激活状态
+            </h2>
+
+            {isActivated ? (
+              <div className="space-y-3">
+                <div className="flex items-center gap-2 text-green-700 font-medium text-lg">
+                  <svg
+                    aria-hidden="true"
+                    xmlns="http://www.w3.org/2000/svg"
+                    width="24"
+                    height="24"
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth="2"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    className="text-green-500"
+                  >
+                    <path d="M12 22c5.523 0 10-4.477 10-10S17.523 2 12 2 2 6.477 2 12s4.477 10 10 10z"></path>
+                    <path d="M9 12l2 2 4-4"></path>
+                  </svg>
+                  <span>License 已激活</span>
+                </div>
+                <div className="pl-8 space-y-1">
+                  <p className="text-gray-600 text-sm">
+                    <span className="font-medium text-gray-700">
+                      当前 License:{' '}
+                    </span>
+                    <span className="font-mono">{data.license}</span>
+                  </p>
+                  {data.licenseActivatedAt && (
+                    <p className="text-gray-500 text-sm">
+                      <span className="font-medium text-gray-700">
+                        激活时间:{' '}
+                      </span>
+                      {new Date(data.licenseActivatedAt).toLocaleString(
+                        'zh-CN',
+                        {
+                          year: 'numeric',
+                          month: '2-digit',
+                          day: '2-digit',
+                          hour: '2-digit',
+                          minute: '2-digit',
+                          second: '2-digit',
+                        },
+                      )}
+                    </p>
+                  )}
+                </div>
+
+                {!showDeactivateConfirm ? (
+                  <button
+                    type="button"
+                    onClick={() => setShowDeactivateConfirm(true)}
+                    className="mt-4 px-4 py-2 bg-red-500 text-white rounded-lg text-sm font-medium hover:bg-red-600 transition-colors shadow-sm"
+                  >
+                    反激活
+                  </button>
+                ) : (
+                  <div className="mt-4 p-4 bg-red-50 rounded-lg border border-red-200">
+                    <p className="text-red-700 text-sm mb-3 flex items-center gap-2">
+                      <svg
+                        aria-hidden="true"
+                        xmlns="http://www.w3.org/2000/svg"
+                        width="16"
+                        height="16"
+                        viewBox="0 0 24 24"
+                        fill="none"
+                        stroke="currentColor"
+                        strokeWidth="2"
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                      >
+                        <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z" />
+                        <path d="M12 9v4" />
+                        <path d="M12 17h.01" />
+                      </svg>
+                      确定要反激活吗？此操作会清除当前 License。
+                    </p>
+                    <div className="flex gap-2">
+                      <button
+                        type="button"
+                        onClick={handleDeactivate}
+                        disabled={deactivateMutation.isPending}
+                        className="px-4 py-2 bg-red-600 text-white rounded-md text-sm font-medium hover:bg-red-700 disabled:bg-gray-300 transition-colors"
+                      >
+                        {deactivateMutation.isPending
+                          ? '反激活中...'
+                          : '确认反激活'}
+                      </button>
+                      <button
+                        type="button"
+                        onClick={() => setShowDeactivateConfirm(false)}
+                        className="px-4 py-2 bg-gray-200 text-gray-700 rounded-md text-sm font-medium hover:bg-gray-300 transition-colors"
+                      >
+                        取消
+                      </button>
+                    </div>
+                    {deactivateMutation.isError && (
+                      <p className="text-red-500 mt-2 text-xs">
+                        反激活失败，请重试
+                      </p>
+                    )}
+                  </div>
+                )}
+              </div>
+            ) : (
+              <div className="flex items-start gap-3">
+                <svg
+                  aria-hidden="true"
+                  xmlns="http://www.w3.org/2000/svg"
+                  width="24"
+                  height="24"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  className="text-orange-500 shrink-0 mt-0.5"
+                >
+                  <path d="M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"></path>
+                  <line x1="12" y1="9" x2="12" y2="13"></line>
+                  <line x1="12" y1="17" x2="12.01" y2="17"></line>
+                </svg>
+                <div>
+                  <p className="text-orange-700 font-medium text-lg mb-1">
+                    未激活
+                  </p>
+                  <p className="text-gray-500 text-sm">
+                    您的设备尚未激活。请在上方输入 License Key
+                    进行激活以解锁全部功能。
+                  </p>
+                </div>
+              </div>
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}

apps/server/src/server/api/context.ts

@@ -0,0 +1,25 @@
+import type { DB } from '@/server/db'
+
+/**
+ * 基础 Context - 所有请求都包含的上下文
+ */
+export interface BaseContext {
+  headers: Headers
+}
+
+/**
+ * 数据库 Context - 通过 db middleware 扩展
+ */
+export interface DBContext extends BaseContext {
+  db: DB
+}
+
+/**
+ * 认证 Context - 通过 auth middleware 扩展（未来使用）
+ *
+ * @example
+ * export interface AuthContext extends DBContext {
+ *   userId: string
+ *   user: User
+ * }
+ */

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

@@ -0,0 +1,9 @@
+import * as fingerprint from './fingerprint.contract'
+import * as license from './license.contract'
+
+export const contract = {
+  fingerprint,
+  license,
+}
+
+export type Contract = typeof contract

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

@@ -0,0 +1,18 @@
+import { oc } from '@orpc/contract'
+import { z } from 'zod'
+
+export const getActivation = oc.input(z.void()).output(
+  z.object({
+    fingerprint: z.string(),
+    license: z.string().nullable(),
+    licenseActivatedAt: z.number().nullable(),
+  }),
+)
+
+export const activate = oc
+  .input(z.object({ license: z.string().min(1) }))
+  .output(z.object({ success: z.boolean() }))
+
+export const deactivate = oc
+  .input(z.void())
+  .output(z.object({ success: z.boolean() }))

apps/server/src/server/api/middlewares/db.middleware.ts

@@ -0,0 +1,15 @@
+import { os } from '@orpc/server'
+import { ensureLicenseActivationInitialized } from '@/lib/license-init'
+import { getDB } from '@/server/db'
+
+export const dbProvider = os.middleware(async ({ context, next }) => {
+  await ensureLicenseActivationInitialized()
+  return next({
+    context: {
+      ...context,
+      db: getDB(),
+    },
+  })
+})
+
+export const db = dbProvider

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

@@ -0,0 +1 @@
+export * from './db.middleware'

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

@@ -0,0 +1,11 @@
+import { getHardwareFingerprint } from '@/lib/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

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

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

@@ -0,0 +1,67 @@
+import { eq } from 'drizzle-orm'
+import { ensureLicenseActivationInitialized } from '@/lib/license-init'
+import { licenseActivationTable } from '@/server/db/schema'
+import { dbProvider } from '../middlewares'
+import { os } from '../server'
+
+export const getActivation = os.license.getActivation
+  .use(dbProvider)
+  .handler(async ({ context }) => {
+    await ensureLicenseActivationInitialized()
+
+    const record = await context.db.query.licenseActivationTable.findFirst()
+
+    if (!record) {
+      throw new Error('License activation record not found')
+    }
+
+    return {
+      fingerprint: record.fingerprint,
+      license: record.license,
+      licenseActivatedAt: record.licenseActivatedAt?.getTime() ?? null,
+    }
+  })
+
+export const activate = os.license.activate
+  .use(dbProvider)
+  .handler(async ({ context, input }) => {
+    await ensureLicenseActivationInitialized()
+
+    const record = await context.db.query.licenseActivationTable.findFirst()
+
+    if (!record) {
+      throw new Error('License activation record not found')
+    }
+
+    await context.db
+      .update(licenseActivationTable)
+      .set({
+        license: input.license,
+        licenseActivatedAt: new Date(),
+      })
+      .where(eq(licenseActivationTable.id, record.id))
+
+    return { success: true }
+  })
+
+export const deactivate = os.license.deactivate
+  .use(dbProvider)
+  .handler(async ({ context }) => {
+    await ensureLicenseActivationInitialized()
+
+    const record = await context.db.query.licenseActivationTable.findFirst()
+
+    if (!record) {
+      throw new Error('License activation record not found')
+    }
+
+    await context.db
+      .update(licenseActivationTable)
+      .set({
+        license: null,
+        licenseActivatedAt: null,
+      })
+      .where(eq(licenseActivationTable.id, record.id))
+
+    return { success: true }
+  })

apps/server/src/server/api/server.ts

@@ -0,0 +1,5 @@
+import { implement } from '@orpc/server'
+import type { BaseContext } from './context'
+import { contract } from './contracts'
+
+export const os = implement(contract).$context<BaseContext>()

apps/server/src/server/api/types.ts

@@ -3,9 +3,8 @@ import type {
   InferContractRouterInputs,
   InferContractRouterOutputs,
 } from '@orpc/contract'
-import type { contract } from './contract'
+import type { Contract } from './contracts'
 
-export type Contract = typeof contract
 export type RouterClient = ContractRouterClient<Contract>
 export type RouterInputs = InferContractRouterInputs<Contract>
 export type RouterOutputs = InferContractRouterOutputs<Contract>

apps/server/src/server/db/index.ts

@@ -0,0 +1,30 @@
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import Database from 'better-sqlite3'
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import { env } from '@/env'
+import * as schema from '@/server/db/schema'
+
+export const createDB = () => {
+  const dbPath = env.DATABASE_URL
+  if (dbPath !== ':memory:') {
+    mkdirSync(dirname(dbPath), { recursive: true })
+  }
+  const sqlite = new Database(dbPath)
+  return drizzle(sqlite, { schema })
+}
+
+export type DB = ReturnType<typeof createDB>
+
+export const getDB = (() => {
+  let db: DB | null = null
+
+  return (singleton = true): DB => {
+    if (!singleton) {
+      return createDB()
+    }
+
+    db ??= createDB()
+    return db
+  }
+})()

apps/server/src/server/db/schema/index.ts

@@ -0,0 +1 @@
+export * from './license-activation'

apps/server/src/server/db/schema/license-activation.ts

@@ -0,0 +1,9 @@
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+import { generatedFields } from './utils/field'
+
+export const licenseActivationTable = sqliteTable('license_activation', {
+  ...generatedFields,
+  fingerprint: text('fingerprint').notNull().unique(),
+  license: text('license'),
+  licenseActivatedAt: integer('license_activated_at', { mode: 'timestamp_ms' }),
+})

apps/server/src/server/db/schema/utils/field.ts

@@ -0,0 +1,46 @@
+import { integer, text } from 'drizzle-orm/sqlite-core'
+import { v7 as uuidv7 } from 'uuid'
+
+// id
+
+export const id = (name: string) => text(name)
+export const pk = (name: string) =>
+  id(name)
+    .primaryKey()
+    .$defaultFn(() => uuidv7())
+
+// timestamp
+
+export const createdAt = (name = 'created_at') =>
+  integer(name, { mode: 'timestamp_ms' })
+    .notNull()
+    .$defaultFn(() => new Date())
+
+export const updatedAt = (name = 'updated_at') =>
+  integer(name, { mode: 'timestamp_ms' })
+    .notNull()
+    .$defaultFn(() => new Date())
+    .$onUpdateFn(() => new Date())
+
+// generated fields
+
+export const generatedFields = {
+  id: pk('id'),
+  createdAt: createdAt('created_at'),
+  updatedAt: updatedAt('updated_at'),
+}
+
+// Helper to create omit keys from generatedFields
+const createGeneratedFieldKeys = <T extends Record<string, unknown>>(
+  fields: T,
+): Record<keyof T, true> => {
+  return Object.keys(fields).reduce(
+    (acc, key) => {
+      acc[key as keyof T] = true
+      return acc
+    },
+    {} as Record<keyof T, true>,
+  )
+}
+
+export const generatedFieldKeys = createGeneratedFieldKeys(generatedFields)

apps/server/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@furtherverse/tsconfig/react.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}

apps/server/turbo.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "../../node_modules/turbo/schema.json",
+  "extends": ["//"],
+  "tasks": {
+    "compile": {
+      "dependsOn": ["build"],
+      "outputs": ["out/**"]
+    }
+  }
+}

biome.json

@@ -6,7 +6,6 @@
     "useIgnoreFile": true
   },
   "files": {
-    "includes": ["**", "!**/routeTree.gen.ts"],
     "ignoreUnknown": false
   },
   "formatter": {

bunfig.toml

@@ -0,0 +1,2 @@
+[install]
+publicHoistPattern = ["@types/*", "bun-types", "nitro*"]

mise.toml

@@ -1,4 +1,4 @@
 [tools]
-node = "24"
+node = "latest"
 bun = "1"
 rust = 'latest'

package.json

@@ -1,59 +1,65 @@
 {
-  "name": "fullstack-starter",
+  "name": "@furtherverse/monorepo",
+  "version": "1.0.0",
   "private": true,
   "type": "module",
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
   "scripts": {
-    "build": "bun run build:vite && bun run build:compile",
-    "build:compile": "bun build.ts",
-    "build:tauri": "tauri build",
-    "build:vite": "vite build",
-    "db:generate": "drizzle-kit generate",
-    "db:migrate": "drizzle-kit migrate",
-    "db:push": "drizzle-kit push",
-    "db:studio": "drizzle-kit studio",
-    "dev": "bun run dev:vite",
-    "dev:tauri": "tauri dev",
-    "dev:vite": "vite dev",
-    "fix": "biome check --write",
-    "typecheck": "tsc -b"
+    "build": "turbo run build",
+    "compile": "turbo run compile",
+    "deploy": "turbo run deploy",
+    "dev": "turbo run dev",
+    "fix": "turbo run fix",
+    "typecheck": "turbo run typecheck"
   },
-  "dependencies": {
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.12",
+    "turbo": "^2.7.6"
+  },
+  "catalog": {
+    "@biomejs/biome": "^2.3.11",
+    "@effect/platform": "^0.94.2",
+    "@effect/schema": "^0.75.5",
+    "@isaacs/ttlcache": "^2.1.4",
     "@orpc/client": "^1.13.4",
     "@orpc/contract": "^1.13.4",
+    "@orpc/openapi": "^1.13.4",
     "@orpc/server": "^1.13.4",
     "@orpc/tanstack-query": "^1.13.4",
     "@orpc/zod": "^1.13.4",
     "@t3-oss/env-core": "^0.13.10",
-    "@tanstack/react-query": "^5.90.18",
-    "@tanstack/react-router": "^1.151.0",
-    "@tanstack/react-router-ssr-query": "^1.151.0",
-    "@tanstack/react-start": "^1.151.0",
-    "drizzle-orm": "^0.45.1",
-    "drizzle-zod": "^0.8.3",
-    "postgres": "^3.4.8",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
-    "zod": "^4.3.5"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.3.11",
-    "@effect/platform": "^0.94.1",
-    "@effect/schema": "^0.75.5",
     "@tailwindcss/vite": "^4.1.18",
     "@tanstack/devtools-vite": "^0.4.1",
     "@tanstack/react-devtools": "^0.9.2",
+    "@tanstack/react-query": "^5.90.20",
     "@tanstack/react-query-devtools": "^5.91.2",
-    "@tanstack/react-router-devtools": "^1.151.0",
-    "@tauri-apps/cli": "^2.9.6",
+    "@tanstack/react-router": "^1.157.14",
+    "@tanstack/react-router-devtools": "^1.157.14",
+    "@tanstack/react-router-ssr-query": "^1.157.14",
+    "@tanstack/react-start": "^1.157.14",
+    "@types/better-sqlite3": "^7.6.12",
     "@types/bun": "^1.3.6",
     "@vitejs/plugin-react": "^5.1.2",
     "babel-plugin-react-compiler": "^1.0.0",
     "drizzle-kit": "^0.31.8",
-    "effect": "^3.19.14",
-    "nitro": "npm:nitro-nightly@latest",
+    "drizzle-orm": "^0.45.1",
+    "drizzle-zod": "^0.8.3",
+    "effect": "^3.19.15",
+    "nitro": "npm:nitro-nightly@3.0.1-20260125-215009-8882bc9e",
+    "ohash": "^2.0.11",
+    "better-sqlite3": "^11.8.1",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
     "tailwindcss": "^4.1.18",
+    "turbo": "^2.7.5",
     "typescript": "^5.9.3",
-    "vite": "^8.0.0-beta.8",
-    "vite-tsconfig-paths": "^6.0.4"
+    "uuid": "^13.0.0",
+    "systeminformation": "^5.30.6",
+    "vite": "^8.0.0-beta.10",
+    "vite-tsconfig-paths": "^6.0.5",
+    "zod": "^4.3.6"
   }
 }

packages/tsconfig/base.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Base",
+  "compilerOptions": {
+    "target": "esnext",
+    "lib": ["ESNext"],
+    "module": "preserve",
+    "skipLibCheck": true,
+
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    "strict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true
+  },
+  "exclude": ["node_modules"]
+}

packages/tsconfig/bun.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Bun",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "types": ["bun-types"]
+  }
+}

packages/tsconfig/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@furtherverse/tsconfig",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./base.json": "./base.json",
+    "./bun.json": "./bun.json",
+    "./react.json": "./react.json"
+  }
+}

packages/tsconfig/react.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "React",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx"
+  }
+}

src-tauri/.gitignore

@@ -1,10 +0,0 @@
-# Generated by Cargo
-# will have compiled files and executables
-/target/
-
-# Generated by Tauri
-# will have schema files for capabilities auto-completion
-/gen/schemas
-
-# Tauri Sidecar
-binaries/

src-tauri/AGENTS.md

@@ -1,357 +0,0 @@
-# AGENTS.md - Tauri Shell 项目开发指南
-
-本文档为 AI 编程助手和开发者提供项目规范、构建命令和代码风格指南。
-
-## 项目概览
-
-- **项目类型**: Tauri v2 桌面应用（轻量级壳子）
-- **后端**: Rust (Edition 2021)
-- **架构**: Sidecar 模式 - Sidecar Server 承载主要业务逻辑
-- **设计理念**: Tauri 仅提供原生桌面能力（文件对话框、系统通知等），Web 逻辑全部由 Sidecar Server 处理
-- **开发模式**: 使用 localhost:3000（需手动启动开发服务器）
-- **生产模式**: 自动启动 Sidecar 二进制
-- **异步运行时**: Tokio
-- **Rust 版本**: 1.92.0+
-- **工具管理**: 使用 mise 管理 Rust 和 Tauri CLI 版本（见 `mise.toml`）
-
-## 构建、测试、运行命令
-
-### 开发运行
-```bash
-# 开发模式运行 (需要先启动开发服务器)
-# 终端 1: 启动前端开发服务器
-bun run dev
-
-# 终端 2: 启动 Tauri 应用
-tauri dev
-
-# 或者使用单命令并行启动（需要配置 package.json）
-bun run dev:tauri
-```
-
-**开发模式说明**：
-- 开发模式下，Tauri 直接连接到 `localhost:3000`（不启动 sidecar 二进制）
-- 需要手动运行 `bun run dev` 来启动开发服务器
-- 支持热重载（HMR），无需重启 Tauri 应用
-
-### 构建
-```bash
-# 开发构建 (debug mode)
-cargo build
-
-# 生产构建
-cargo build --release
-
-# Tauri 应用打包 (生成安装程序)
-tauri build
-```
-
-### 代码检查
-```bash
-# 编译检查 (不生成二进制)
-cargo check
-
-# Clippy 代码质量检查
-cargo clippy
-
-# Clippy 严格模式 (所有警告视为错误)
-cargo clippy -- -D warnings
-
-# 代码格式化检查
-cargo fmt -- --check
-
-# 自动格式化代码
-cargo fmt
-```
-
-### 测试
-```bash
-# 运行所有测试
-cargo test
-
-# 运行单个测试 (按名称过滤)
-cargo test test_function_name
-
-# 运行特定模块的测试
-cargo test module_name::
-
-# 显示测试输出 (包括 println!)
-cargo test -- --nocapture
-
-# 运行单个测试并显示输出
-cargo test test_name -- --nocapture
-```
-
-### 清理
-```bash
-# 清理构建产物
-cargo clean
-```
-
-## 项目结构
-
-```
-tauri-shell/
-├── src/
-│   ├── main.rs          # 入口文件 (仅调用 lib::run)
-│   ├── lib.rs           # 核心应用逻辑 (注册插件、命令、状态)
-│   ├── commands/
-│   │   └── mod.rs       # 原生桌面功能命令 (文件对话框、通知等)
-│   └── sidecar.rs       # Sidecar 进程管理 (启动、端口扫描、清理)
-├── binaries/            # Sidecar 二进制文件
-│   └── server-*   # Sidecar Server 可执行文件 (示例: server)
-├── capabilities/        # Tauri v2 权限配置
-│   └── default.json
-├── icons/               # 应用图标资源
-├── gen/schemas/         # 自动生成的 Schema (不要手动编辑)
-├── Cargo.toml          # Rust 项目配置
-├── tauri.conf.json     # Tauri 应用配置
-├── build.rs            # Rust 构建脚本
-└── mise.toml           # 开发工具版本管理
-```
-
-## Rust 代码风格指南
-
-### 导入 (Imports)
-
-- 使用标准库、外部 crate、当前 crate 的顺序，用空行分隔
-- 按字母顺序排列
-- 优先使用具体导入而非通配符 `*`
-
-```rust
-// ✅ 推荐
-use std::sync::Mutex;
-use std::time::Duration;
-
-use tauri::Manager;
-use tauri_plugin_shell::ShellExt;
-use tauri_plugin_shell::process::{CommandEvent, CommandChild};
-
-// ❌ 避免
-use tauri::*;
-```
-
-### 命名规范
-
-- **函数和变量**: `snake_case`
-- **类型、结构体、枚举、Trait**: `PascalCase`
-- **常量和静态变量**: `SCREAMING_SNAKE_CASE`
-- **生命周期参数**: 简短小写字母，如 `'a`, `'b`
-
-```rust
-// ✅ 推荐
-struct SidecarProcess(Mutex<Option<CommandChild>>);
-const DEFAULT_PORT: u16 = 3000;
-async fn find_available_port(start: u16) -> u16 { }
-
-// ❌ 避免
-struct sidecar_process { }
-const defaultPort: u16 = 3000;
-```
-
-### 类型注解
-
-- 函数参数必须有类型注解
-- 函数返回值必须明确声明 (除非返回 `()`)
-- 优先使用具体类型而非 `impl Trait` (除非必要)
-- 使用 `&str` 而非 `String` 作为只读字符串参数
-
-```rust
-// ✅ 推荐
-#[tauri::command]
-fn greet(name: &str) -> String {
-    format!("Hello, {}!", name)
-}
-
-async fn is_port_available(port: u16) -> bool {
-    tokio::net::TcpListener::bind(format!("127.0.0.1:{}", port))
-        .await
-        .is_ok()
-}
-```
-
-### 错误处理
-
-- 使用 `Result<T, E>` 返回可能失败的操作
-- 使用 `expect()` 时提供有意义的错误消息 (中文)
-- 避免 `unwrap()` 在生产代码中，除非逻辑上保证不会 panic
-- 使用 `?` 操作符传播错误
-- 记录关键错误信息到控制台
-
-```rust
-// ✅ 推荐
-let sidecar = app_handle
-    .shell()
-    .sidecar("server")
-    .expect("无法找到 server sidecar");
-
-let (mut rx, child) = sidecar.spawn().expect("启动 sidecar 失败");
-
-// 日志记录
-eprintln!("✗ Sidecar Server 启动失败");
-println!("✓ Sidecar Server 启动成功！");
-
-// ❌ 避免
-let data = read_file().unwrap();  // 无上下文信息
-```
-
-### 异步代码
-
-- 使用 `async/await` 而非手动创建 Future
-- Tauri 内部使用 `tauri::async_runtime::spawn` 启动异步任务
-- 使用 Tokio 的异步 API (如 `tokio::net::TcpListener`)
-- 避免阻塞异步运行时 (使用 `tokio::task::spawn_blocking`)
-
-```rust
-// ✅ 推荐
-tauri::async_runtime::spawn(async move {
-    let port = find_available_port(3000).await;
-    // ...
-});
-```
-
-### 格式化
-
-- 使用 `cargo fmt` 自动格式化
-- 缩进: 4 空格
-- 行宽: 100 字符 (rustfmt 默认)
-- 结构体和枚举的字段每行一个 (如果超过一定长度)
-- 链式调用适当换行提高可读性
-
-### 注释
-
-- 使用中文注释说明复杂逻辑
-- 代码块前添加简短说明注释
-- 避免显而易见的注释
-
-```rust
-// ✅ 推荐
-// 全局状态：存储 Sidecar Server 进程句柄
-struct SidecarProcess(Mutex<Option<CommandChild>>);
-
-// 检查端口是否可用
-async fn is_port_available(port: u16) -> bool { }
-```
-
-## Tauri 特定规范
-
-### 模块组织
-
-- **`lib.rs`**: 主入口，负责注册插件、命令、状态管理
-- **`commands/mod.rs`**: 所有 Tauri 命令集中定义，命令必须是 `pub fn`
-- **`sidecar.rs`**: Sidecar 进程管理逻辑，导出公共 API（`spawn_sidecar`, `cleanup_sidecar_process`）
-
-```rust
-// lib.rs - 模块声明
-mod commands;
-mod sidecar;
-
-use sidecar::SidecarProcess;
-
-// 注册命令时使用模块路径
-.invoke_handler(tauri::generate_handler![commands::greet])
-```
-
-### 命令定义
-
-- 使用 `#[tauri::command]` 宏标记命令
-- 命令函数必须是公开的或在 `invoke_handler` 中注册
-- 参数类型必须实现 `serde::Deserialize`
-- 返回类型必须实现 `serde::Serialize`
-
-```rust
-#[tauri::command]
-fn greet(name: &str) -> String {
-    format!("Hello, {}!", name)
-}
-
-// 在 Builder 中注册
-.invoke_handler(tauri::generate_handler![greet])
-```
-
-### 状态管理
-
-- 使用 `app.manage()` 注册全局状态
-- 状态必须实现 `Send + Sync`
-- 使用 `Mutex` 或 `RwLock` 保证线程安全
-
-```rust
-struct SidecarProcess(Mutex<Option<CommandChild>>);
-
-// 注册状态
-app.manage(SidecarProcess(Mutex::new(None)));
-
-// 访问状态
-if let Some(state) = app_handle.try_state::<SidecarProcess>() {
-    *state.0.lock().unwrap() = Some(child);
-}
-```
-
-### Sidecar 进程管理
-
-- Sidecar 二进制必须在 `tauri.conf.json` 的 `bundle.externalBin` 中声明
-- 使用 `app.shell().sidecar()` 启动 sidecar
-- 在应用退出时清理子进程 (监听 `RunEvent::ExitRequested`)
-
-```rust
-// 启动 sidecar
-let sidecar = app_handle
-    .shell()
-    .sidecar("server")
-    .expect("无法找到 server sidecar")
-    .env("NITRO_PORT", port.to_string());
-
-// 清理进程
-match event {
-    tauri::RunEvent::ExitRequested { .. } | tauri::RunEvent::Exit => {
-        if let Some(child) = process.take() {
-            let _ = child.kill();
-        }
-    }
-    _ => {}
-}
-```
-
-## 依赖管理
-
-- 在 `Cargo.toml` 中明确声明依赖版本
-- 使用语义化版本 (如 `"2"` 表示兼容 2.x.x)
-- 仅启用需要的 feature 以减少编译时间和二进制大小
-
-```toml
-tauri = { version = "2", features = [] }
-tauri-plugin-opener = "2"
-tauri-plugin-shell = "2"
-serde = { version = "1", features = ["derive"] }
-tokio = { version = "1", features = ["net"] }
-```
-
-## 开发工具
-
-推荐安装以下 VSCode 扩展:
-- `tauri-apps.tauri-vscode` - Tauri 官方支持
-- `rust-lang.rust-analyzer` - Rust 语言服务器
-
-## 最佳实践
-
-1. **开发环境配置**: 
-   - 开发模式下需先启动前端开发服务器（`bun run dev`），再启动 Tauri（`tauri dev`）
-   - 生产构建自动打包 sidecar 二进制，无需额外配置
-2. **进程生命周期**: 始终在应用退出时清理子进程和资源
-3. **端口管理**: 
-   - 开发模式固定使用 3000 端口（与开发服务器匹配）
-   - 生产模式使用端口扫描避免硬编码端口冲突
-4. **超时处理**: 异步操作设置合理的超时时间 (如 5 秒)
-5. **日志**: 使用表情符号 (✓/✗/🔧/🚀) 和中文消息提供清晰的状态反馈
-6. **错误退出**: 关键错误时调用 `std::process::exit(1)`
-7. **窗口配置**: 使用 `WebviewWindowBuilder` 动态创建窗口
-
-## 提交代码前检查清单
-
-- [ ] `cargo fmt` 格式化通过
-- [ ] `cargo clippy` 无警告
-- [ ] `cargo check` 编译通过
-- [ ] `cargo test` 测试通过
-- [ ] 更新相关注释和文档
-- [ ] 检查是否有 `unwrap()` 需要替换为 `expect()`
-- [ ] 验证 Tauri 应用正常启动和退出

src-tauri/Cargo.toml

@@ -1,24 +0,0 @@
-[package]
-name = "tauri-shell"
-version = "0.1.0"
-description = "A Tauri App"
-authors = ["imbytecat"]
-edition = "2021"
-
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
-[lib]
-# The `_lib` suffix may seem redundant but it is necessary
-# to make the lib name unique and wouldn't conflict with the bin name.
-# This seems to be only an issue on Windows, see https://github.com/rust-lang/cargo/issues/8519
-name = "tauri_shell_lib"
-crate-type = ["staticlib", "cdylib", "rlib"]
-
-[build-dependencies]
-tauri-build = { version = "2", features = [] }
-
-[dependencies]
-tauri = { version = "2", features = [] }
-tauri-plugin-shell = "2"
-serde = { version = "1", features = ["derive"] }
-tokio = { version = "1", features = ["net"] }

src-tauri/build.rs

@@ -1,3 +0,0 @@
-fn main() {
-    tauri_build::build()
-}

src-tauri/capabilities/default.json

@@ -1,18 +0,0 @@
-{
-  "$schema": "../gen/schemas/desktop-schema.json",
-  "identifier": "default",
-  "description": "Capability for the main window",
-  "windows": ["main"],
-  "permissions": [
-    "core:default",
-    {
-      "identifier": "shell:allow-execute",
-      "allow": [
-        {
-          "name": "binaries/server",
-          "sidecar": true
-        }
-      ]
-    }
-  ]
-}

src-tauri/src/commands/mod.rs

@@ -1,8 +0,0 @@
-// 原生桌面功能命令
-// 未来可能包含: 文件对话框、系统通知、剪贴板等
-
-// 示例命令 (可根据需要删除或替换)
-#[tauri::command]
-pub fn greet(name: &str) -> String {
-    format!("Hello, {}! You've been greeted from Rust!", name)
-}

src-tauri/src/lib.rs

@@ -1,35 +0,0 @@
-use tauri::Manager;
-
-// 模块声明
-mod commands;
-mod sidecar;
-
-use sidecar::SidecarProcess;
-
-#[cfg_attr(mobile, tauri::mobile_entry_point)]
-pub fn run() {
-    tauri::Builder::default()
-        .plugin(tauri_plugin_shell::init())
-        .setup(|app| {
-            // 注册全局状态
-            app.manage(SidecarProcess(std::sync::Mutex::new(None)));
-
-            // 启动 Sidecar 进程
-            let app_handle = app.handle().clone();
-            sidecar::spawn_sidecar(app_handle);
-
-            Ok(())
-        })
-        .invoke_handler(tauri::generate_handler![commands::greet])
-        .build(tauri::generate_context!())
-        .expect("error while building tauri application")
-        .run(|app_handle, event| {
-            // 监听应用退出事件，清理 Sidecar 进程
-            match event {
-                tauri::RunEvent::ExitRequested { .. } | tauri::RunEvent::Exit => {
-                    sidecar::cleanup_sidecar_process(app_handle);
-                }
-                _ => {}
-            }
-        });
-}

src-tauri/src/main.rs

@@ -1,6 +0,0 @@
-// Prevents additional console window on Windows in release, DO NOT REMOVE!!
-#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
-
-fn main() {
-    tauri_shell_lib::run()
-}

src-tauri/src/sidecar.rs

@@ -1,156 +0,0 @@
-use std::sync::Mutex;
-use std::time::Duration;
-
-use tauri::Manager;
-use tauri_plugin_shell::process::{CommandChild, CommandEvent};
-use tauri_plugin_shell::ShellExt;
-
-// ===== 配置常量 =====
-
-/// Sidecar Server 启动超时时间（秒）
-const STARTUP_TIMEOUT_SECS: u64 = 5;
-
-/// 默认起始端口
-const DEFAULT_PORT: u16 = 3000;
-
-/// 端口扫描范围（从起始端口开始扫描的端口数量）
-const PORT_SCAN_RANGE: u16 = 100;
-
-/// 窗口默认宽度
-const DEFAULT_WINDOW_WIDTH: f64 = 1200.0;
-
-/// 窗口默认高度
-const DEFAULT_WINDOW_HEIGHT: f64 = 800.0;
-
-/// 窗口标题
-const WINDOW_TITLE: &str = "Tauri App";
-
-// ===== 数据结构 =====
-
-/// 全局状态：存储 Sidecar 进程句柄
-pub struct SidecarProcess(pub Mutex<Option<CommandChild>>);
-
-// 检查端口是否可用（未被占用）
-async fn is_port_available(port: u16) -> bool {
-    tokio::net::TcpListener::bind(format!("127.0.0.1:{}", port))
-        .await
-        .is_ok()
-}
-
-// 查找可用端口
-async fn find_available_port(start: u16) -> u16 {
-    for port in start..start + PORT_SCAN_RANGE {
-        if is_port_available(port).await {
-            return port;
-        }
-    }
-    start // 回退到起始端口
-}
-
-/// 启动 Sidecar 进程并创建主窗口
-pub fn spawn_sidecar(app_handle: tauri::AppHandle) {
-    // 检测是否为开发模式
-    let is_dev = cfg!(debug_assertions);
-
-    if is_dev {
-        // 开发模式：直接创建窗口连接到 Vite 开发服务器
-        println!("🔧 开发模式：连接到 Vite 开发服务器 (localhost:3000)");
-
-        let url = "http://localhost:3000";
-        tauri::WebviewWindowBuilder::new(
-            &app_handle,
-            "main",
-            tauri::WebviewUrl::External(url.parse().unwrap()),
-        )
-        .title(WINDOW_TITLE)
-        .inner_size(DEFAULT_WINDOW_WIDTH, DEFAULT_WINDOW_HEIGHT)
-        .center()
-        .build()
-        .expect("创建窗口失败");
-
-        return;
-    }
-
-    // 生产模式：启动 sidecar 二进制
-    tauri::async_runtime::spawn(async move {
-        println!("🚀 生产模式：启动 Sidecar Server");
-
-        // 查找可用端口
-        let port = find_available_port(DEFAULT_PORT).await;
-        println!("使用端口: {}", port);
-
-        // 启动 sidecar
-        let sidecar = app_handle
-            .shell()
-            .sidecar("server")
-            .expect("无法找到 server")
-            .env("NITRO_PORT", port.to_string());
-
-        let (mut rx, child) = sidecar.spawn().expect("启动 sidecar 失败");
-
-        // 保存进程句柄到全局状态
-        if let Some(state) = app_handle.try_state::<SidecarProcess>() {
-            *state.0.lock().unwrap() = Some(child);
-        }
-
-        // 监听 stdout，等待服务器就绪信号
-        let start_time = std::time::Instant::now();
-        let timeout = Duration::from_secs(STARTUP_TIMEOUT_SECS);
-        let mut server_ready = false;
-
-        while let Some(event) = rx.recv().await {
-            if let CommandEvent::Stdout(line) = event {
-                let output = String::from_utf8_lossy(&line);
-                println!("Server: {}", output);
-
-                // 检测服务器启动成功的标志
-                if output.contains("Listening on:") || output.contains("localhost") {
-                    server_ready = true;
-                    println!("✓ Server 启动成功！");
-
-                    // 创建主窗口
-                    let url = format!("http://localhost:{}", port);
-                    tauri::WebviewWindowBuilder::new(
-                        &app_handle,
-                        "main",
-                        tauri::WebviewUrl::External(url.parse().unwrap()),
-                    )
-                    .title(WINDOW_TITLE)
-                    .inner_size(DEFAULT_WINDOW_WIDTH, DEFAULT_WINDOW_HEIGHT)
-                    .center()
-                    .build()
-                    .expect("创建窗口失败");
-
-                    break;
-                }
-            }
-
-            // 超时检查
-            if start_time.elapsed() > timeout {
-                eprintln!(
-                    "✗ 启动超时: Server 未能在 {} 秒内启动",
-                    STARTUP_TIMEOUT_SECS
-                );
-                break;
-            }
-        }
-
-        if !server_ready {
-            eprintln!("✗ Server 启动失败");
-            std::process::exit(1);
-        }
-    });
-}
-
-/// 清理 Sidecar 进程 (在应用退出时调用)
-pub fn cleanup_sidecar_process(app_handle: &tauri::AppHandle) {
-    println!("应用退出，正在清理 Sidecar 进程...");
-    if let Some(state) = app_handle.try_state::<SidecarProcess>() {
-        if let Ok(mut process) = state.0.lock() {
-            if let Some(child) = process.take() {
-                let _ = child.kill();
-                println!("✓ Sidecar 进程已终止");
-            }
-        }
-    }
-}

src-tauri/tauri.conf.json

@@ -1,29 +0,0 @@
-{
-  "$schema": "https://schema.tauri.app/config/2",
-  "productName": "tauri-shell",
-  "version": "0.1.0",
-  "identifier": "com.imbytecat.tauri-shell",
-  "build": {
-    "beforeDevCommand": "bun run dev:vite",
-    "beforeBuildCommand": "bun run build"
-  },
-  "app": {
-    "withGlobalTauri": true,
-    "windows": [],
-    "security": {
-      "csp": null
-    }
-  },
-  "bundle": {
-    "active": true,
-    "targets": "all",
-    "icon": [
-      "icons/32x32.png",
-      "icons/128x128.png",
-      "icons/128x128@2x.png",
-      "icons/icon.icns",
-      "icons/icon.ico"
-    ],
-    "externalBin": ["binaries/server"]
-  }
-}

src/db/index.ts

@@ -1,13 +0,0 @@
-import { drizzle } from 'drizzle-orm/postgres-js'
-import * as schema from '@/db/schema'
-import { env } from '@/env'
-
-export function createDb() {
-  return drizzle({
-    connection: {
-      url: env.DATABASE_URL,
-      prepare: true,
-    },
-    schema,
-  })
-}

src/db/schema/index.ts

@@ -1 +0,0 @@
-export * from './todo'

src/db/schema/todo.ts

@@ -1,15 +0,0 @@
-import { sql } from 'drizzle-orm'
-import { boolean, pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'
-
-export const todoTable = pgTable('todo', {
-  id: uuid('id').primaryKey().default(sql`uuidv7()`),
-  title: text('title').notNull(),
-  completed: boolean('completed').notNull().default(false),
-  createdAt: timestamp('created_at', { withTimezone: true })
-    .notNull()
-    .defaultNow(),
-  updatedAt: timestamp('updated_at', { withTimezone: true })
-    .notNull()
-    .defaultNow()
-    .$onUpdateFn(() => new Date()),
-})

src/integrations/tanstack-query/devtools.tsx

@@ -1,7 +0,0 @@
-import type { TanStackDevtoolsReactPlugin } from '@tanstack/react-devtools'
-import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
-
-export const devtools = {
-  name: 'TanStack Query',
-  render: <ReactQueryDevtoolsPanel />,
-} satisfies TanStackDevtoolsReactPlugin